[elpa] externals/transient d76f73f884 205/366: transient-arg-value: New function

[Jonas Bernoulli]

branch: externals/transient
commit d76f73f88449bf988ce53bf364bd922b8969c784
Author: Jonas Bernoulli <jonas@bernoul.li>
Commit: Jonas Bernoulli <jonas@bernoul.li>

    transient-arg-value: New function
---
 docs/transient.org  | 12 ++++++++++--
 docs/transient.texi | 21 +++++++++++++++++++--
 lisp/transient.el   | 19 +++++++++++++++++++
 3 files changed, 48 insertions(+), 4 deletions(-)

diff --git a/docs/transient.org b/docs/transient.org
index cf4ffe3fa2..da7b344f66 100644
--- a/docs/transient.org
+++ b/docs/transient.org
@@ -8,7 +8,7 @@
 #+TEXINFO_DIR_CATEGORY: Emacs
 #+TEXINFO_DIR_TITLE: Transient: (transient).
 #+TEXINFO_DIR_DESC: Transient Commands
-#+SUBTITLE: for version 0.2.0 (v0.2.0-49-ga3517747+1)
+#+SUBTITLE: for version 0.2.0 (v0.2.0-53-ge2fee198+1)
 
 #+TEXINFO_DEFFN: t
 #+OPTIONS: H:4 num:4 toc:2
@@ -37,7 +37,7 @@ Calling a suffix command usually causes the transient to be 
exited
 but suffix commands can also be configured to not exit the transient.
 
 #+TEXINFO: @noindent
-This manual is for Transient version 0.2.0 (v0.2.0-49-ga3517747+1).
+This manual is for Transient version 0.2.0 (v0.2.0-53-ge2fee198+1).
 
 #+BEGIN_QUOTE
 Copyright (C) 2018-2020 Jonas Bernoulli <jonas@bernoul.li>
@@ -1046,6 +1046,14 @@ function, which for infix arguments serves about the 
same purpose as
   command was not invoked from PREFIX, then it returns the set, saved
   or default value for PREFIX.
 
+- Function: transient-arg-value arg args
+
+  This function return the value of ARG as it appears in ARGS.
+
+  For a switch a boolean is returned.  For an option the value is
+  returned as a string, using the empty string for the empty value,
+  or nil if the option does not appear in ARGS.
+
 - Function: transient-suffixes prefix
 
   This function returns the suffixes of the transient prefix command
diff --git a/docs/transient.texi b/docs/transient.texi
index 46dd21734b..e52637b2fe 100644
--- a/docs/transient.texi
+++ b/docs/transient.texi
@@ -31,7 +31,7 @@ General Public License for more details.
 @finalout
 @titlepage
 @title Transient User and Developer Manual
-@subtitle for version 0.2.0 (v0.2.0-49-ga3517747+1)
+@subtitle for version 0.2.0 (v0.2.0-53-ge2fee198+1)
 @author Jonas Bernoulli
 @page
 @vskip 0pt plus 1filll
@@ -65,7 +65,7 @@ Calling a suffix command usually causes the transient to be 
exited
 but suffix commands can also be configured to not exit the transient.
 
 @noindent
-This manual is for Transient version 0.2.0 (v0.2.0-49-ga3517747+1).
+This manual is for Transient version 0.2.0 (v0.2.0-53-ge2fee198+1).
 
 @quotation
 Copyright (C) 2018-2020 Jonas Bernoulli <jonas@@bernoul.li>
@@ -1094,6 +1094,14 @@ that specify commands and strings.  Strings are inserted 
verbatim.
 The empty string can be used to insert gaps between suffixes, which is
 particularly useful if the suffixes are outlined as a table.
 
+Variables are supported inside group specifications.  For example in
+place of a direct subgroup specification, a variable can be used whose
+value is a vector that qualifies as a group specification.  Likewise a
+variable can be used where a suffix specification is expected.  Lists
+of group or suffix specifications are also supported.  Indirect
+specifications are resolved when the transient prefix is being
+defined.
+
 The form of suffix specifications is documented in the next node.
 
 @node Suffix Specifications
@@ -1292,6 +1300,15 @@ command was not invoked from PREFIX, then it returns the 
set, saved
 or default value for PREFIX@.
 @end defun
 
+@defun transient-arg-value arg args
+
+This function return the value of ARG as it appears in ARGS@.
+
+For a switch a boolean is returned.  For an option the value is
+returned as a string, using the empty string for the empty value,
+or nil if the option does not appear in ARGS@.
+@end defun
+
 @defun transient-suffixes prefix
 
 This function returns the suffixes of the transient prefix command
diff --git a/lisp/transient.el b/lisp/transient.el
index f6ff888297..87dfe62496 100644
--- a/lisp/transient.el
+++ b/lisp/transient.el
@@ -2682,6 +2682,25 @@ which is not the same as nil."
   (when-let ((value (oref obj value)))
     (cons (oref obj argument) value)))
 
+;;;; Utilities
+
+(defun transient-arg-value (arg args)
+  "Return the value of ARG as it appears in ARGS.
+
+For a switch return a boolean.  For an option return the value as
+a string, using the empty string for the empty value, or nil if
+the option does not appear in ARGS."
+  (if (string-match-p "=\\'" arg)
+      (save-match-data
+        (when-let ((match (let ((re (format "\\`%s\\(?:=\\(.+\\)\\)?\\'"
+                                            (substring arg 0 -1))))
+                            (cl-find-if (lambda (a)
+                                          (and (stringp a)
+                                               (string-match re a)))
+                                        args))))
+          (or (match-string 1 match) "")))
+    (and (member arg args) t)))
+
 ;;; History
 
 (cl-defgeneric transient--history-key (obj)