[elpa] externals/transient 277e5f2d27 2/4: transient-prepare-suffix{, es}: New functions

[Jonas Bernoulli]

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

    transient-prepare-suffix{,es}: New functions
---
 docs/transient.org  | 16 +++++++++++-----
 docs/transient.texi | 48 +++++++++++++++++++++++++++++-------------------
 lisp/transient.el   | 16 ++++++++++++++++
 3 files changed, 56 insertions(+), 24 deletions(-)

diff --git a/docs/transient.org b/docs/transient.org
index 27401836f1..ade5955b26 100644
--- a/docs/transient.org
+++ b/docs/transient.org
@@ -952,11 +952,17 @@ constructor of that class.
   #+END_SRC
 
 - The value of ~:setup-children~, if non-~nil~, is a function that takes
-  two arguments the group object itself and a list of children.
-  The children are given as a (potentially empty) list consisting
-  of either group or suffix specifications.  It can make arbitrary
-  changes to the children including constructing new children from
-  scratch.  Also see ~transient-setup-children~.
+  one argument, a potentially list of children, and must return a list
+  of children or an empty list.  This can either be used to somehow
+  transform the prefix's children that were defined the normal way, or
+  to dynamically create the children from scratch.
+
+  The returned children must have the same form as stored in the
+  prefix's ~transient--layout~ property, but it is often more convenient
+  to use the same form as understood by ~transient-define-prefix~,
+  described below.  If you use the latter approach, you can use the
+  ~transient-parse-child~ and ~transient-parse-children~ functions to
+  transform them from the convenient to the expected form.
 
 - The boolean ~:pad-keys~ argument controls whether keys of all suffixes
   contained in a group are right padded, effectively aligning the
diff --git a/docs/transient.texi b/docs/transient.texi
index 78b44f5943..6527aeb36d 100644
--- a/docs/transient.texi
+++ b/docs/transient.texi
@@ -1143,11 +1143,17 @@ suffixes, which assumes that a predicate like this is 
used:
 
 @item
 The value of @code{:setup-children}, if non-@code{nil}, is a function that 
takes
-two arguments the group object itself and a list of children.
-The children are given as a (potentially empty) list consisting
-of either group or suffix specifications.  It can make arbitrary
-changes to the children including constructing new children from
-scratch.  Also see @code{transient-setup-children}.
+one argument, a potentially list of children, and must return a list
+of children or an empty list.  This can either be used to somehow
+transform the prefix's children that were defined the normal way, or
+to dynamically create the children from scratch.
+
+The returned children must have the same form as stored in the
+prefix's @code{transient--layout} property, but it is often more convenient
+to use the same form as understood by @code{transient-define-prefix},
+described below.  If you use the latter approach, you can use the
+@code{transient-parse-child} and @code{transient-parse-children} functions to
+transform them from the convenient to the expected form.
 
 @item
 The boolean @code{:pad-keys} argument controls whether keys of all suffixes
@@ -1155,22 +1161,26 @@ contained in a group are right padded, effectively 
aligning the
 descriptions.
 @end itemize
 
-The @var{ELEMENT}s are either all subgroups (vectors), or all suffixes
-(lists) and strings.  (At least currently no group type exists that
-would allow mixing subgroups with commands at the same level, though
-in principle there is nothing that prevents that.)
+The @var{ELEMENT}s are either all subgroups, or all suffixes and strings.
+(At least currently no group type exists that would allow mixing
+subgroups with commands at the same level, though in principle there
+is nothing that prevents that.)
 
 If the @var{ELEMENT}s are not subgroups, then they can be a mixture of lists
-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.
-
-Inside group specifications, including contained suffix specifications,
-nothing has to be quoted.  How symbols are treated, depends on context.
-In most places they are expected to name functions.  However if they
-appear in a place where a group vector is expected, then they are
-treated as indirect group specifications. Such a symbol must have an
-associated group specification, created using @code{transient-define-groups}.
+that specify commands and strings.  Strings are inserted verbatim into
+the buffer.  The empty string can be used to insert gaps between
+suffixes, which is particularly useful if the suffixes are outlined as
+a table.
+
+Inside group specifications, including inside contained suffix
+specifications, nothing has to be quoted and quoting anyway is
+invalid.
+
+How symbols are treated, depends on context.  Inside suffix
+specifications they often name functions.  However if they appear in
+a place where a group is expected, then they are treated as indirect
+group specifications. Such a symbol must have an associated group
+specification, created using @code{transient-define-groups}.
 
 Likewise a symbol can appear in a place where a suffix specification
 is expected.  The value of the @code{transient--layout} property of that
diff --git a/lisp/transient.el b/lisp/transient.el
index 5af5e7bd31..9f9f81aee0 100644
--- a/lisp/transient.el
+++ b/lisp/transient.el
@@ -1165,6 +1165,22 @@ example, sets a variable use `transient-define-infix' 
instead.
     (and (string-match "\\`\\(-[a-zA-Z]\\)\\(\\'\\|=\\)" arg)
          (match-string 1 arg))))
 
+(defun transient-parse-suffix (prefix suffix)
+  "Parse SUFFIX, to be added to PREFIX.
+PREFIX is a prefix command, a symbol.
+SUFFIX is a suffix command or a group specification (of
+  the same forms as expected by `transient-define-prefix').
+Intended for use in PREFIX's `:setup-children' function."
+  (eval (car (transient--parse-child prefix suffix))))
+
+(defun transient-parse-suffixes (prefix suffixes)
+  "Parse SUFFIXES, to be added to PREFIX.
+PREFIX is a prefix command, a symbol.
+SUFFIXES is a list of suffix command or a group specification
+  (of the same forms as expected by `transient-define-prefix').
+Intended for use in PREFIX's `:setup-children' function."
+  (mapcar (apply-partially #'transient-parse-suffix prefix) suffixes))
+
 ;;; Edit
 
 (defun transient--insert-suffix (prefix loc suffix action &optional keep-other)