[elpa] externals/colorful-mode 48fc7d369f 13/20: Complete RGB/HSL support officially, updates to README

[ELPA Syncer]

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

    Complete RGB/HSL support officially, updates to README
    
    Add final support for CSS rgb(a) and hsl(a).
    Fix css-mode derived not being highlighted if
    colorful-only-strings is set to only-prog.
    Update README for contributions and update doc.
    
    * README.org: Update sections for contributions,
    document new changes, add faces section, and
    fix comparation table.
    
    * colorful-mode.el: (colorful-colorize-itself):
    Use string-match-p instead string-prefix-p.
    (colorful--change-color): Allow convert rgb and hsl
    to hex and names color but not vice versa.
    (colorful-extra-color-keyword-functions): Delete
    rgb colors from emacs-lisp-mode.
    (global-colorful-modes): Add scss-mode.
    (colorful-add-hsl-colors): New function for
    colorful-color-keywords.
---
 README.org       |  87 ++++++++++++++++++++++----------------
 colorful-mode.el | 125 +++++++++++++++++++++++++++++++++++++++----------------
 2 files changed, 138 insertions(+), 74 deletions(-)

diff --git a/README.org b/README.org
index f7f7e17acf..fcf725e096 100644
--- a/README.org
+++ b/README.org
@@ -21,8 +21,7 @@ in real time and in a user friendly way based on 
🌈[[https://elpa.gnu.org/pack
 * Features ✨
 - Preview emacs colors names, hexadecimal colors and CSS rgb functions
   in your current buffer in real time.
-- Convert color to other formats or copy them without replace current
-  color.
+- Replace or copy to other color formats such as hexadecimal or color names.
 - Preview using highlight or a prefix/suffix string.
 - Preview only colors in strings.
 - Exclude colors such as hex values and color names.
@@ -38,7 +37,7 @@ in real time and in a user friendly way based on 
🌈[[https://elpa.gnu.org/pack
 [[./assets/screenshot3.png]]
 
 [[./assets/screenshot4.png]]
-/With a custom prefix (in this example a non-ASCII/Unicode character)/.
+/With a custom prefix (in this example a non-ASCII/non-Unicode character)/.
 
 * User Options, Setups and Guides 📖
 ** Customizable User options
@@ -46,11 +45,13 @@ in real time and in a user friendly way based on 
🌈[[https://elpa.gnu.org/pack
   for change color.
 - =colorful-use-prefix (default: nil)= If non-nil, use prefix for preview color
   instead highlight them.
-  *NOTE: css-mode and css-ts-mode by default colorize rgb and hex colors, this 
may interfere with colorful prefix, you can disable this setting 
=css-fontify-colors= to nil*
-- =colorful-prefix-string (default: "●")= Prefix symbol to be used according
+  *NOTE: css derived modes by default colorize rgb and hex colors, this may 
interfere with colorful prefix, you can disable this setting 
=css-fontify-colors= to nil*
+- =colorful-prefix-string (default: "●")= String to be used in highlights.
+  Only relevant if `colorful-use-prefix' is non-nil.
   =colorful-use-prefix=.
 - =colorful-prefix-alignment (default: 'left)= The position to put prefix 
string.
   The value can be left or right.
+  Only relevant if `colorful-use-prefix' is non-nil.
 - =colorful-extra-color-keyword-functions=
   default:
   '((emacs-lisp-mode . (colorful-add-color-names colorful-add-rgb-colors))
@@ -74,15 +75,19 @@ in real time and in a user friendly way based on 
🌈[[https://elpa.gnu.org/pack
   Available functions are:
    + colorful-add-color-names.
    + colorful-add-rgb-colors.
+   + colorful-add-hsl-colors.
 
 - =colorful-exclude-colors (default: '("#def"))= List of keyword to don't 
highlight.
-- =colorful-short-hex-convertions (default: t)= If non nil, hex
+- =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.
 - =colorful-only-strings (default: nil)= If non-nil colorful will only 
highlight colors inside strings.
   If set to only-prog, only highlight colors in strings if current major mode 
is derived from prog-mode.
-- =global-colorful-modes (default: '(mhtml-mode html-ts-mode css-mode 
css-ts-mode emacs-lisp-mode))= Which major modes global-colorful-mode is 
switched on in (globally).
+- =global-colorful-modes (default: '(mhtml-mode html-ts-mode scss-mode 
css-mode css-ts-mode prog-mode))= Which major modes global-colorful-mode is 
switched on in (globally).
+
+** Faces
+- =colorful-base= Face used as base for highlight color names.
 
 ** Interactive User Functions.
 - =colorful-change-or-copy-color= Change or copy color to a converted
@@ -105,12 +110,13 @@ Colorful by default provides extra functions that 
highlight additional
 colors:
 
 - =colorful-add-color-names= Add emacs color names to colorful-color-keywords.
-- =colorful-add-rgb-colors= Add CSS rgb color to colorful-color-keywords.
+- =colorful-add-rgb-colors= Add CSS RGB colors to colorful-color-keywords.
+- =colorful-add-hsl-colors= Add CSS HSL colors to ‘colorful-color-keywords’.
 
 For use them add it to:
 #+begin_src emacs-lisp
-;; In this example add emacs color names to colorful-keywords.
-(add-to-list 'colorful-extra-color-keyword-functions 
#'colorful-add-color-names)
+;; In this example add emacs color names only for yaml-,mode and derived.
+  (add-to-list 'colorful-extra-color-keyword-functions '(yaml-mode . 
colorful-add-color-names))
 #+end_src
 NOTE: colorful-keyword is buffer-local variable.
 
@@ -125,7 +131,7 @@ For install colorful run:
 Or if you prefer using =use-package= macro:
 #+begin_src emacs-lisp
   (use-package colorful-mode
-    :ensure t ; (Optional)
+    :ensure t ; <-- Optional
     :hook (prog-mode text-mode)
     ...)
 
@@ -135,42 +141,49 @@ Or if you prefer using =use-package= macro:
 =colorful-mode= improves =rainbow-mode= in adding more features
 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                                  | Work in progress | 
❌              |
-| Opcionally use string preffix/suffix instead highlight | ✓                | 
❌              |
-| Exclude keywords/colors to highlight                   | ✓                | 
❌^{1}          |
-| Allow highlight some colors only in specific modes     | ✓                | 
✓^{2}           |
-| Highlight only in strings and docstrings               | ✓                | 
❌              |
-| No performance issues?^{3}                             | ❌               | ✓ 
              |
+| Comparation                                           | colorful-mode.el | 
rainbow-mode.el |
+|-------------------------------------------------------+------------------+-----------------|
+| Compatible with hl-line and other overlays?           | ✓                | ❌ 
             |
+| Convert color to other formats?                       | ✓                | ❌ 
             |
+| Insert open color hex?                                | Work in progress | ❌ 
             |
+| Opcionally use string prefix/suffix instead highlight | ✓                | ❌ 
             |
+| Exclude keywords/colors?                              | ✓                | 
❌^{1}          |
+| Allow highlight specifics colors in specific modes    | ✓                | 
✓^{2}           |
+| Opcionally highlight only in strings                  | ✓                | ❌ 
             |
+| No performance issues?^{3}                            | ❌               | ✓  
             |
 
 1. rainbow-mode (like colorful) uses regex for highlight some
    keywords, however it cannot exclude specifics colors keywords
    (such as "#def" that overrides C "#define" keyword).
-2. Only for some highlights and keywords.
+2. Only for some colors.
 3. I didn't a benchmark however due colorful-mode uses overlays
-   instead text properties (like rainbow-mode) it can be a bit slow.
+   instead text properties it can be a 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=.
+If you prefer only highlights without color convertion, prefix/suffix
+string indicator and/or anything else 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=.
+On the other hand, if you want convert colors, overlays, optional
+prefix strings and more features 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
-appreciate this since i'm not expert in elisp)/.
-
-Due I have plans for submit it to *GNU ELPA* /(and maybe MELPA)/ *Pull
-Resquest will not be accepted* (unless your contribution is less than
-15 lines [see: 
[[https://www.gnu.org/software/emacs/manual/html_node/emacs/Copyright-Assignment.html][Copyright
 Assignment]]] and this package is ready for
-submit to ELPA and you are willing to assign copyright to FSF)
+Currently this repo will only be used for feature-request, send bug
+reports, and feedback /(i would greatly appreciate this since i'm not
+expert in elisp)/.
+
+Due I have plans for submit it to *GNU ELPA* keep in mind if you want
+to contribute with a PR *you will need assign copyright to FSF*, this
+for make FSF can still maintaining or save the package if this repo
+gets deleted or something else happen.  If you don't want assign
+copyright please open an issue and send instructions for your
+feature/code, so i can implement it without requiring copyright
+paperwork.  Also if your contribution is less than 15 lines [see:
+[[https://www.gnu.org/software/emacs/manual/html_node/emacs/Copyright-Assignment.html][Copyright
 Assignment]]] you can open a PR and your contribution will be
+merged quickly.  However for people that are willing to doing
+paperwork you must wait until this package is ready for submit to
+ELPA, this is for ensure that you are ready for doing paperwork.
 
 Also i will try to make this package as stable as possible before
 submit it to ELPA, later that *I won't be able to be the mantainer* of
@@ -178,5 +191,5 @@ this package, However I would like if someone would be able 
to be the
 mantainer (if you are interested please email me
 <eg642616@gmail.com>).
 
-#+html: <img 
src="https://raw.githubusercontent.com/DevelopmentCool2449/emacs-svg-badges/main/powered_by_emacs.svg";
 align="right" width="10%">
-#+html: <img 
src="https://raw.githubusercontent.com/DevelopmentCool2449/emacs-svg-badges/main/powered_by_org_mode.svg";
 align="right" width="10%">
+#+html: <img 
src="https://raw.githubusercontent.com/DevelopmentCool2449/emacs-svg-badges/main/powered_by_emacs.svg";
 align="left" width="10%">
+#+html: <img 
src="https://raw.githubusercontent.com/DevelopmentCool2449/emacs-svg-badges/main/powered_by_org_mode.svg";
 align="center" width="10%">
diff --git a/colorful-mode.el b/colorful-mode.el
index 3998070aca..b54acc191e 100644
--- a/colorful-mode.el
+++ b/colorful-mode.el
@@ -8,7 +8,7 @@
 ;; Package-Requires: ((emacs "28.1") (compat "29.1.4.5"))
 ;; Homepage: https://github.com/DevelopmentCool2449/colorful-mode
 ;; Keywords: faces
-;; Version: 0.2.0
+;; Version: 0.3.0
 
 ;; This file is not part of GNU Emacs.
 
@@ -36,7 +36,7 @@
 ;;                                  Libraries                                 ;
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 
-(require 'compat) ; This should add compatibility for emacs-28.2 and higher.
+(require 'compat) ; This should add compatibility for emacs-28.X and higher.
 
 (require 'color)
 (require 'subr-x)
@@ -112,9 +112,9 @@ Must be a list containing regex strings.")
   "Face used as base for highlight color names.")
 
 (defcustom colorful-extra-color-keyword-functions
-  '((emacs-lisp-mode . (colorful-add-color-names
-                        colorful-add-rgb-colors))
-    ((css-mode css-ts-mode) . colorful-add-rgb-colors))
+  '((emacs-lisp-mode . colorful-add-color-names)
+    ((css-mode css-ts-mode) . (colorful-add-rgb-colors
+                               colorful-add-hsl-colors)))
   "List of functions to add extra color keywords to `colorful-color-keywords'.
 It can be a cons cell specifing the mode (or a list of modes)
 e.g:
@@ -130,7 +130,8 @@ Or a simple list of functions for executing wherever 
colorful is active:
 
 Available functions are:
  - `colorful-add-color-names'.
- - `colorful-add-rgb-colors'."
+ - `colorful-add-rgb-colors'.
+ - `colorful-add-hsl-colors'"
   :type '(repeat
           (choice
            (cons (choice :tag "Mode(s)"
@@ -157,12 +158,14 @@ Available functions are: `colorful-add-color-names'.")
   :type 'boolean)
 
 (defcustom colorful-prefix-string "●"
-  "Prefix symbol to be used according `colorful-use-prefix'."
+  "String to be used in highlights.
+Only relevant if `colorful-use-prefix' is non-nil."
   :type 'string)
 
 (defcustom colorful-prefix-alignment 'left
   "The position to put prefix string.
-The value can be left or right."
+The value can be left or right.
+Only relevant if `colorful-use-prefix' is non-nil."
   :type '(choice (const :tag "Left" left)
                  (const :tag "Right" right)))
 
@@ -219,11 +222,17 @@ mode is derived from `prog-mode'."
 ;;        ,(macroexp-progn then)
 ;;      (user-error "No color found")))
 
-;; Base Convertion functions.
+;;;;;;;;;; Base Convertion functions ;;;;;;;;;;
+
+;; TEMP: Since CSS derived modes allow converting hexs to rgb
+;;       this may be deleted when release colorful 1.0.0
 ;; (defun colorful--hex-to-rgb (hex)
 ;;   "Return HEX color as CSS rgb format."
-;;   ;; (query-replace)
-;;   )
+;;   (let* ((rgb (color-name-to-rgb hex))
+;;        (r (* 255 (nth 0 rgb)))
+;;        (g (* 255 (nth 1 rgb)))
+;;        (b (* 255 (nth 2 rgb))))
+;;   (format "rgb(%d, %d, %d)" r g b)))
 
 (defun colorful--percentage-to-absolute (percentage)
   "Convert PERCENTAGE to a absolute number.
@@ -244,10 +253,25 @@ RGB must be a string."
                    (string-remove-prefix "rgba(" rgb)
                  (string-remove-prefix "rgb(" rgb))
                ","))
-         (r (colorful--percentage-to-absolute (nth 0 rgb)))
-         (g (colorful--percentage-to-absolute (nth 1 rgb)))
-         (b (colorful--percentage-to-absolute (nth 2 rgb))))
-    (color-rgb-to-hex (/ r 255.0) (/ g 255.0) (/ b 255.0) (if 
colorful-short-hex-convertions 2))))
+         (r (/ (colorful--percentage-to-absolute (nth 0 rgb)) 255.0))
+         (g (/ (colorful--percentage-to-absolute (nth 1 rgb)) 255.0))
+         (b (/ (colorful--percentage-to-absolute (nth 2 rgb)) 255.0)))
+    (color-rgb-to-hex r g b (if colorful-short-hex-convertions 2))))
+
+(defun colorful--hsl-to-hex (hsl)
+  "Return HSL RGB as hexadecimal format.
+HSL must be a string."
+  (let* ((hsl (string-split
+               (if (string-prefix-p "hsl(" hsl)
+                   (string-remove-prefix "hsl(" hsl)
+                 (string-remove-prefix "hsla(" hsl))
+               ","))
+         (h (/ (string-to-number (nth 0 hsl)) 360.0))
+         (s (/ (string-to-number (nth 1 hsl)) 100.0))
+         (l (/ (string-to-number (nth 2 hsl)) 100.0))
+         (rgb (append (color-hsl-to-rgb h s l)
+                      `(,(if colorful-short-hex-convertions 2)))))
+    (apply #'color-rgb-to-hex rgb)))
 
 (defun colorful--hex-to-name (hex)
   "Return HEX as Emacs color name."
@@ -330,8 +354,7 @@ PROMPT must be a string with 1 format control (generally a 
string argument)."
          (end (or end (overlay-end ov)))
          (color (or color (buffer-substring-no-properties beg end)))
          (prompt (format prompt color))
-         (choices '(("Hex value" . hex)
-                    ;; ("RGB (CSS)" . rgb)
+         (choices '(("Hexadecimal color format" . hex)
                     ("Emacs color name" . name)))
          (choice (alist-get
                   (completing-read prompt choices nil t nil nil)
@@ -340,32 +363,35 @@ PROMPT must be a string with 1 format control (generally 
a string argument)."
       ('hex
        (if (not (string-prefix-p "#" color)) ; Ensure is not already a hex
            (cond
-            ;; Is a Name?
+            ;; Is Name?
             ((member color (defined-colors))
              (list (colorful--name-to-hex color) beg end))
-            ;; Is a CSS rgb?
-            ((or (string-prefix-p "rgb(" color)
-                 (string-prefix-p "rgba(" color))
-             (list (colorful--rgb-to-hex color) beg end)))
+            ;; Is CSS rgb?
+            ((string-match-p (rx (one-or-more "rgb" (opt "a") "(")) color)
+             (list (colorful--rgb-to-hex color) beg end))
+            ;; Is HSL?
+            ((string-match-p (rx (one-or-more "hsl" (opt "a") "(")) color)
+             (list (colorful--hsl-to-hex color) beg end)))
 
          (colorful--change-color ov "%s is already a Hex color. Try again: "
                                  color beg end)))
-
-      ;; ('rgb (unless (string-prefix-p "rgb" color)))
-
       ('name
        (if (not (assoc color color-name-rgb-alist))
            (cond
-            ;; Is a Hex?
+            ;; Is Hex?
             ((string-prefix-p "#" color)
              (if-let ((rep (colorful--hex-to-name color)))
                  (list rep beg end)
                (user-error "No color name available")
                nil))
-            ;; Is a CSS rgb?
-            ((string-prefix-p "rgb(" color)
-             (if-let ((rep (colorful--rgb-to-hex color))
-                      (rep (colorful--hex-to-name rep)))
+            ;; Is CSS rgb?
+            ((string-match-p (rx (one-or-more "rgb" (opt "a") "(")) color)
+             (if-let ((rep (colorful--hex-to-name (colorful--rgb-to-hex 
color))))
+                 (list rep beg end)
+               (user-error "No color name available")))
+            ;; Is HSL?
+            ((string-match-p (rx (one-or-more "hsl" (opt "a") "(")) color)
+             (if-let ((rep (colorful--hex-to-name (colorful--hsl-to-hex 
color))))
                  (list rep beg end)
                (user-error "No color name available"))))
 
@@ -435,14 +461,16 @@ it can be white or black."
               ((and (not (member string colorful-exclude-colors))
                     (or (and colorful-only-strings (nth 3 (syntax-ppss)))
                         (and (eq colorful-only-strings 'only-prog)
-                             (not (derived-mode-p 'prog-mode)))
+                             (or (derived-mode-p 'css-mode) ; Apparently CSS 
is prog-mode derived
+                                 (not (derived-mode-p 'prog-mode))))
                         (not colorful-only-strings))))
               (beg (match-beginning match))
               (end (match-end match)))
     (cond
-     ((or (string-prefix-p "rgb(" string)
-          (string-prefix-p "rgba(" string))
-      (setq string (colorful--rgb-to-hex string))))
+     ((string-match-p (rx (one-or-more "rgb" (opt "a") "(")) string)
+      (setq string (colorful--rgb-to-hex string)))
+     ((string-match-p (rx (one-or-more "hsl" (opt "a") "(")) string)
+      (setq string (colorful--hsl-to-hex string))))
 
     ;; Delete duplicates overlays found
     (dolist (ov (overlays-in beg end))
@@ -482,7 +510,24 @@ it can be white or black."
                 (opt "%"))
                (zero-or-more " ") ")"))
      (0 (colorful-colorize-itself))))
-  "Font-lock keywords to add for RGB colors.")
+  "Font-lock keywords for add RGB colors.")
+
+(defvar colorful-hsl-font-lock-keywords
+  `((,(rx (seq "hsl" (opt "a") "(" (zero-or-more " ")
+               (group (repeat 1 3 (any "0-9")))
+               (zero-or-more " ") "," (zero-or-more " ")
+               (group (repeat 1 3 (any "0-9")) "%")
+               (zero-or-more " ") "," (zero-or-more " ")
+               (group (repeat 1 3 (any "0-9")) "%")
+               (opt
+                (zero-or-more " ") "," (zero-or-more " ")
+                (zero-or-more (any "0-9")) (opt nonl)
+                (one-or-more (any "0-9"))
+                (zero-or-more " ")
+                (opt "%"))
+               (zero-or-more " ") ")"))
+     (0 (colorful-colorize-itself))))
+  "Font-lock keywords for add HSL colors.")
 
 (defun colorful-add-color-names ()
   "Function for add Emacs color names to `colorful-color-keywords'.
@@ -491,11 +536,17 @@ This is intended to be used with 
`colorful-extra-color-keyword-functions'."
     (add-to-list 'colorful-color-keywords colors t)))
 
 (defun colorful-add-rgb-colors ()
-  "Function for add CSS RGB colors keywords to `colorful-color-keywords'.
+  "Function for add CSS RGB colors to `colorful-color-keywords'.
 This is intended to be used with `colorful-extra-color-keyword-functions'."
   (dolist (colors colorful-rgb-font-lock-keywords)
     (add-to-list 'colorful-color-keywords colors t)))
 
+(defun colorful-add-hsl-colors ()
+  "Function for add CSS HSL colors to `colorful-color-keywords'.
+This is intended to be used with `colorful-extra-color-keyword-functions'."
+  (dolist (colors colorful-hsl-font-lock-keywords)
+    (add-to-list 'colorful-color-keywords colors t)))
+
 
 ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
 ;;                           Minor mode defintinions                          ;
@@ -546,7 +597,7 @@ This will fontify colors strings like \"#aabbcc\" or 
\"blue\"."
 ;;;###autoload
 (define-globalized-minor-mode global-colorful-mode
   colorful-mode colorful--turn-on
-  :predicate '(mhtml-mode html-ts-mode css-mode css-ts-mode prog-mode))
+  :predicate '(mhtml-mode html-ts-mode scss-mode css-mode css-ts-mode 
prog-mode))
 
 
 (provide 'colorful-mode)