[elpa] externals/colorful-mode c1856d8aad 04/20: New user options and updates README

[ELPA Syncer]

branch: externals/colorful-mode
commit c1856d8aadc1d20c255350901b3cab720cf5dc83
Author: Elias G. B. Perez <eg642616@gmail.com>
Commit: Elias G. B. Perez <eg642616@gmail.com>

    New user options and updates README
    
    * colorful-mode.el (colorful-short-hex-convertions)
    (colorful-exclude-colors-string): New user options.
    (colorful--name-to-hex): Rework for include
    colorful-short-hex-convertions.
    (colorful-colorize-itself): Rework for include
    colorful-exclude-colors.
    (colorful--turn-on): Indentation.
    (global-colorful-mode): Change global modes values.
    
    * README.org (Customizable User options)
    (Interactive User Functions.): Document new user options.
    (How does it compare to =rainbow-mode=?): Add new differences table
    between colorful-mode and rainbow-mode.
---
 README.org       | 64 +++++++++++++++++++++++++++++++++++++++++++-------------
 colorful-mode.el | 36 ++++++++++++++++++++-----------
 2 files changed, 73 insertions(+), 27 deletions(-)

diff --git a/README.org b/README.org
index c81bcdc74d..739b1ed53e 100644
--- a/README.org
+++ b/README.org
@@ -33,27 +33,44 @@ friendly way based on 
🌈[[https://elpa.gnu.org/packages/rainbow-mode.html][rai
 
 * User Setup and Guides 📖
 ** Customizable User options
-
-- =colorful-allow-mouse-clicks= If non-nil, allow using mouse buttons
+- =colorful-allow-mouse-clicks (default: t)= If non-nil, allow using mouse 
buttons
   for change color.
-- =colorful-use-prefix= If non-nil, use prefix for preview color
+- =colorful-use-prefix (default: nil)= If non-nil, use prefix for preview color
   instead highlight them.
-- =colorful-prefix-string= Prefix symbol to be used according
+- =colorful-prefix-string (default: "●")= Prefix symbol to be used according
   =colorful-use-prefix=.
-- =colorful-prefix-alignment= The position to put prefix string.
-The value can be left or right.
-- =colorful-extra-color-keywords-hook= Hook used for add extra color
+- =colorful-prefix-alignment (default: 'left)= The position to put prefix 
string.
+  The value can be left or right.
+- =colorful-extra-color-keywords-hook (default: nil)= Hook used for add extra 
color
   keywords to =colorful-color-keywords=.
   Available functions are: =colorful-add-color-names=.
-- =global-colorful-modes= Which major modes colorful-mode is switched
-  on in (globally).
+- =colorful-exclude-colors (default: '("#def"))= List of keyword to don't 
highlight.
+- =colorful-short-hex-convertions (default: t)= If non nil, hex
+  values converted by coloful should be as short as possible.
+  Setting this to t will make hex values follow a 24-bit specification
+  and can make them inaccurate.
+- =global-colorful-modes (default: '(mhtml-mode html-ts-mode css-mode 
css-ts-mode emacs-lisp-mode))= Which major modes colorful-mode is switched on 
in (globally).
 
 ** Interactive User Functions.
 - =colorful-change-color= Change color at current cursor position.
+- =colorful-mode= Buffer-local minor mode.
+- =global-colorful-mode= Global minor mode.
 
 ** Key bindings
 These key bindings are defined by: =colorful-mode-map=
-- =C-c c= → =colorful-change-color=.
+- =C-c c c= → =colorful-change-color=.
+
+** Adding extra colors
+Colorful by default provides extra functions that highlight additional
+colors:
+
+- =colorful-add-color-names= Add emacs color names to colorful-color-keywords.
+
+For use them add it to =colorful-extra-color-keywords-hook=:
+#+begin_src emacs-lisp
+;; In this example highlight emacs color names.
+(add-hook 'colorful-extra-color-keywords-hook #'colorful-add-color-names)
+#+end_src
 
 * Installation 📦
 Currently colorful-mode is not available in any elisp package archive,
@@ -73,15 +90,32 @@ For emacs 30 users you can use =use-package=
 
 * How does it compare to =rainbow-mode=?
 =colorful-mode= improves =rainbow-mode= in adding more features
-and fixing some /(and old)/ bugs like:
-- The well know issue with hl-line.
-- Deprecated (and some old functions) in source code.
-- Refactoring.
-- &c.
+and fixing some /(and old)/ bugs:
+
+| Comparation                                             | colorful-mode.el | 
rainbow-mode.el |
+|---------------------------------------------------------+------------------+-----------------|
+| Compatible with hl-line and other overlays?             | ✓                | 
❌              |
+| Convert color to other formats?                         | ✓                | 
❌              |
+| Insert open color hex                                   | not yet          | 
❌(?)           |
+| Opcionally use string preffix/suffix instead highlight  | ✓                | 
❌              |
+| Use emacs built-in functions instead define custom ones | ✓^{1}              
 | ✓^{2}              |
+| No performance issues?^{3}                                 | ❌               
| ✓               |
+
+1. However colorful defines helper funtion for some cases avoiding
+    innecesary computation.
+2. Only for some cases.
+3. I didn't a benchmark however due colorful-mode uses overlays
+    instead text properties (like rainbow-mode) it can be a bit slow.
 
 The intention is to provide a featured alternative to
 =rainbow-mode.el= with a user-friendy approach
 
+If you prefer only highlights without color convertion or
+preffix/suffix you can use =rainbow-mode.el=.
+
+On the other hand, if you want convert colors, overlays and
+optional prefix strings you can use =colorful-mode.el=.
+
 * Plans for future
 Currently this repo will only be used for feature-request /(i can't
 promise to do them)/, send bug reports, and feedback /(i would greatly
diff --git a/colorful-mode.el b/colorful-mode.el
index 84d2999549..d51c4227f7 100644
--- a/colorful-mode.el
+++ b/colorful-mode.el
@@ -8,7 +8,7 @@
 ;; Package-Requires: ((emacs "29.1"))
 ;; Homepage: https://github.com/DevelopmentCool2449/colorful-mode
 ;; Keywords: faces
-;; Version: 0.1.1
+;; Version: 0.1.2
 
 ;; This file is not part of GNU Emacs.
 
@@ -102,7 +102,6 @@ Must be a list containing regex strings.")
 (defcustom colorful-extra-color-keywords-hook nil
   "Hook used for add extra color keywords to `colorful-color-keywords'.
 Available functions are: `colorful-add-color-names'."
-  :group 'dashboard
   :type 'hook)
 
 (defcustom colorful-allow-mouse-clicks t
@@ -123,11 +122,21 @@ The value can be left or right."
   :type '(choice (const :tag "Left" left)
                  (const :tag "Right" right)))
 
+(defcustom colorful-exclude-colors '("#def")
+  "List of keyword to don't highlight."
+  :type '(repeat string))
+
+(defcustom colorful-short-hex-convertions t
+  "If non nil, hex values converted by coloful should be as short as possible.
+Setting this to t will make hex values follow a 24-bit specification
+and can make them inaccurate."
+  :type 'boolean)
+
 
 ;; Keymaps
 (defvar-keymap colorful-mode-map
   :doc "Keymap when `colorful-mode' is active."
-  "C-c c" #'colorful-change-color)
+  "C-c c c" #'colorful-change-color)
 
 
 ;; Internal Functions
@@ -148,7 +157,8 @@ The value can be left or right."
 
 (defun colorful--name-to-hex (name)
   "Return Emacs color NAME as hex color format."
-  (let ((color (color-name-to-rgb name)))
+  (let* ((short (if colorful-short-hex-convertions 2 1))
+         (color (append (color-name-to-rgb name) `(,short))))
     (apply #'color-rgb-to-hex color)))
 
 (defun colorful--replace-region (beg end text)
@@ -269,11 +279,12 @@ The background uses COLOR color value.  The foreground is 
computed using
   "Helper function for Colorize MATCH with itself."
   (let* ((match1 (or match 0))
          (string (match-string-no-properties match1)))
-    ;; Delete duplicates overlays found
-    (dolist (ov (overlays-in (match-beginning match1) (match-end match1)))
-      (if (overlay-get ov 'colorful--overlay)
-          (colorful--delete-overlay ov)))
-    (colorful--colorize-match string match)))
+    (unless (member string colorful-exclude-colors)
+      ;; Delete duplicates overlays found
+      (dolist (ov (overlays-in (match-beginning match1) (match-end match1)))
+        (if (overlay-get ov 'colorful--overlay)
+            (colorful--delete-overlay ov)))
+      (colorful--colorize-match string match))))
 
 
 ;; Extras color regex functions and variables.
@@ -294,8 +305,7 @@ This is intended to be used with 
`colorful-extra-color-keywords-hook'."
   "Helper function for turn on `colorful-mode'."
   (run-hooks 'colorful-extra-color-keywords-hook)
 
-  (font-lock-add-keywords nil
-                          colorful-color-keywords)
+  (font-lock-add-keywords nil colorful-color-keywords)
 
   ;; Refresh font-lock
   (font-lock-flush))
@@ -320,7 +330,9 @@ This will fontify colors strings like \"#aabbcc\" or 
\"blue\"."
 ;;;###autoload
 (define-globalized-minor-mode global-colorful-mode
   colorful-mode colorful--turn-on
-  :predicate '(prog-mode text-mode) :group 'colorful)
+  :predicate
+  '(mhtml-mode html-ts-mode css-mode css-ts-mode emacs-lisp-mode)
+  :group 'colorful)
 
 
 (provide 'colorful-mode)