[elpa] externals/ef-themes 5ec73a5583: Add ef-themes-get-color-value function and document it

[ELPA Syncer]

branch: externals/ef-themes
commit 5ec73a5583e9a46a3e1e7452bfb91865457f3e5a
Author: Protesilaos Stavrou <info@protesilaos.com>
Commit: Protesilaos Stavrou <info@protesilaos.com>

    Add ef-themes-get-color-value function and document it
---
 README.org   | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 ef-themes.el | 62 ++++++++++++++++++++++++++++++++++++++++--------------------
 2 files changed, 96 insertions(+), 21 deletions(-)

diff --git a/README.org b/README.org
index 3ff7731112..b29f40c402 100644
--- a/README.org
+++ b/README.org
@@ -695,6 +695,61 @@ code that uses ~ef-themes-with-colors~.
 This section documents how the user can further tweak the Ef themes to
 their liking.
 
+** Get a single color from the palette
+:PROPERTIES:
+:CUSTOM_ID: h:cc1633d3-8e83-45b5-b258-804935f9ee0d
+:END:
+
+[ Part of {{{development-version}}}. ]
+
+[[#h:ec0adf54-c037-4c53-81b8-7eab2303794d][The general approach to advanced 
DIY changes]].
+
+#+findex: ef-themes-get-color-value
+The fuction ~ef-themes-get-color-value~ can be called from Lisp to
+return the value of a color from the active Ef theme palette.  It
+takea a =COLOR= argument and an optional =OVERRIDES=.
+
+=COLOR= is a symbol that represents a named color entry in the
+palette.
+
+[[#h:8dd67bf5-879e-46e5-b277-5bac141f53d1][Preview theme colors]].
+
+If the value is the name of another color entry in the palette (so a
+mapping), this function recurs until it finds the underlying color
+value.
+
+With an optional =OVERRIDES= argument as a non-nil value, it accounts
+for palette overrides.  Else it reads only the default palette.
+
+[[#h:4b923795-4b23-4345-81e5-d1c108a84b6a][Palette overrides]].
+
+If =COLOR= is not present in the palette, this function returns the
+=unspecified= symbol, which is safe when used as a face attribute's
+value.
+
+An example with ~ef-summer~ to show how this function behaves
+with/without overrides and when recursive mappings are introduced.
+
+#+begin_src emacs-lisp
+;; Here we show the recursion of palette mappings.  In general, it is
+;; better for the user to specify named colors to avoid possible
+;; confusion with their configuration, though those still work as
+;; expected.
+(setq ef-themes-common-palette-overrides
+      '((cursor red)
+        (prompt cursor)
+        (variable prompt)))
+
+;; Ignore the overrides and get the original value.
+(ef-themes-get-color-value 'variable)
+;; => "#5250ef"
+
+;; Read from the overrides and deal with any recursion to find the
+;; underlying value.
+(ef-themes-get-color-value 'variable :overrides)
+;; => "#d3303a"
+#+end_src
+
 ** The general approach to advanced DIY changes
 :PROPERTIES:
 :CUSTOM_ID: h:ec0adf54-c037-4c53-81b8-7eab2303794d
diff --git a/ef-themes.el b/ef-themes.el
index b29bda7070..c363c62898 100644
--- a/ef-themes.el
+++ b/ef-themes.el
@@ -421,6 +421,47 @@ foreground that is used with any of the intense 
backgrounds."
 
 ;;; Commands and their helper functions
 
+(defun ef-themes--retrieve-palette-value (color palette)
+  "Return COLOR from PALETTE.
+Use recursion until COLOR is retrieved as a string.  Refrain from
+doing so if the value of COLOR is not a key in the PALETTE.
+
+Return `unspecified' if the value of COLOR cannot be determined.
+This symbol is accepted by faces and is thus harmless.
+
+This function is used in the macros `ef-themes-theme',
+`ef-themes-with-colors'."
+  (let ((value (car (alist-get color palette))))
+    (cond
+     ((or (stringp value)
+          (eq value 'unspecified))
+      value)
+     ((and (symbolp value)
+           (memq value (mapcar #'car palette)))
+      (ef-themes--retrieve-palette-value value palette))
+     (t
+      'unspecified))))
+
+(defun ef-themes-get-color-value (color &optional overrides)
+  "Return color value of named COLOR for current Ef theme.
+
+COLOR is a symbol that represents a named color entry in the
+palette.
+
+If the value is the name of another color entry in the
+palette (so a mapping), recur until you find the underlying color
+value.
+
+With optional OVERRIDES as a non-nil value, account for palette
+overrides.  Else use the default palette.
+
+If COLOR is not present in the palette, return the `unspecified'
+symbol, which is safe when used as a face attribute's value."
+  (if-let* ((palette (ef-themes--current-theme-palette overrides))
+            (value (ef-themes--retrieve-palette-value color palette)))
+      value
+    'unspecified))
+
 (defun ef-themes--list-enabled-themes ()
   "Return list of `custom-enabled-themes' with ef- prefix."
   (seq-filter
@@ -2013,27 +2054,6 @@ Helper function for `ef-themes-preview-colors'."
 
 ;;; Theme macros
 
-(defun ef-themes--retrieve-palette-value (color palette)
-  "Return COLOR from PALETTE.
-Use recursion until COLOR is retrieved as a string.  Refrain from
-doing so if the value of COLOR is not a key in the PALETTE.
-
-Return `unspecified' if the value of COLOR cannot be determined.
-This symbol is accepted by faces and is thus harmless.
-
-This function is used in the macros `ef-themes-theme',
-`ef-themes-with-colors'."
-  (let ((value (car (alist-get color palette))))
-    (cond
-     ((or (stringp value)
-          (eq value 'unspecified))
-      value)
-     ((and (symbolp value)
-           (memq value (mapcar #'car palette)))
-      (ef-themes--retrieve-palette-value value palette))
-     (t
-      'unspecified))))
-
 ;;;; Instantiate an Ef theme
 
 ;;;###autoload