[elpa] externals/transient f2252d53b6 188/366: Support delaying setup of suffixes until prefix invocation

[Jonas Bernoulli]

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

    Support delaying setup of suffixes until prefix invocation
---
 docs/transient.org  | 27 ++++++++++++++++++++++++---
 docs/transient.texi | 30 +++++++++++++++++++++++++++---
 lisp/transient.el   | 18 ++++++++++++++----
 3 files changed, 65 insertions(+), 10 deletions(-)

diff --git a/docs/transient.org b/docs/transient.org
index 4927db5626..ff08372ec0 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-8-gc94cff7+1)
+#+SUBTITLE: for version 0.2.0 (v0.2.0-36-g96cec8e1+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-8-gc94cff7+1).
+This manual is for Transient version 0.2.0 (v0.2.0-36-g96cec8e1+1).
 
 #+BEGIN_QUOTE
 Copyright (C) 2018-2020 Jonas Bernoulli <jonas@bernoul.li>
@@ -821,7 +821,7 @@ constructor of that class.
   These predicates can also be used on individual suffixes and are
   only documented once, see [[*Predicate Slots]].
 
-- Finally the value of ~:hide~, if non-nil, is a predicate that controls
+- The value of ~:hide~, if non-nil, is a predicate that controls
   whether the group is hidden by default.  The key bindings for
   suffixes of a hidden group should all use the same prefix key.
   Pressing that prefix key should temporarily show the group and its
@@ -833,6 +833,13 @@ constructor of that class.
           ?\C-c)) ; the prefix key shared by all bindings
   #+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~.
+
 The ELEMENTs 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
@@ -1273,6 +1280,20 @@ beginning of the class specification, e.g. ~[:class 
transient-columns
 
 ** Group Methods
 
+- Function: transient-setup-children group children
+
+  This generic function can be used to setup the children or a group.
+
+  The default implementation usually just returns the children
+  unchanged, but if the ~setup-children~ slot of GROUP is non-nil, then
+  it calls that function with CHILDREN as the only argument and
+  returns the value.
+
+  The children are given as a, potentially empty, list consisting of
+  either group or suffix specifications.  These functions can make
+  arbitrary changes to the children including constructing new
+  children from scratch.
+
 - Function: transient--insert-group group
 
   This generic function formats the group and its elements and inserts
diff --git a/docs/transient.texi b/docs/transient.texi
index a2bc197897..f7dcae2d0d 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-8-gc94cff7+1)
+@subtitle for version 0.2.0 (v0.2.0-36-g96cec8e1+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-8-gc94cff7+1).
+This manual is for Transient version 0.2.0 (v0.2.0-36-g96cec8e1+1).
 
 @quotation
 Copyright (C) 2018-2020 Jonas Bernoulli <jonas@@bernoul.li>
@@ -1049,7 +1049,7 @@ only documented once, see @ref{Predicate Slots}.
 
 
 @item
-Finally the value of @code{:hide}, if non-nil, is a predicate that controls
+The value of @code{:hide}, if non-nil, is a predicate that controls
 whether the group is hidden by default.  The key bindings for
 suffixes of a hidden group should all use the same prefix key.
 Pressing that prefix key should temporarily show the group and its
@@ -1060,6 +1060,15 @@ suffixes, which assumes that a predicate like this is 
used:
   (eq (car transient--redisplay-key)
       ?\C-c)) ; the prefix key shared by all bindings
 @end lisp
+
+
+@item
+The value of @code{: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 @code{transient-setup-children}.
 @end itemize
 
 The ELEMENTs are either all subgroups (vectors), or all suffixes
@@ -1571,6 +1580,21 @@ elements.
 @node Group Methods
 @section Group Methods
 
+@defun transient-setup-children group children
+
+This generic function can be used to setup the children or a group.
+
+The default implementation usually just returns the children
+unchanged, but if the @code{setup-children} slot of GROUP is non-nil, then
+it calls that function with CHILDREN as the only argument and
+returns the value.
+
+The children are given as a, potentially empty, list consisting of
+either group or suffix specifications.  These functions can make
+arbitrary changes to the children including constructing new
+children from scratch.
+@end defun
+
 @defun transient--insert-group group
 
 This generic function formats the group and its elements and inserts
diff --git a/lisp/transient.el b/lisp/transient.el
index ed1cabb01d..1945f5937e 100644
--- a/lisp/transient.el
+++ b/lisp/transient.el
@@ -690,9 +690,10 @@ They become the value of this this argument.")
 ;;;; Group
 
 (defclass transient-group (transient-child)
-  ((suffixes    :initarg :suffixes    :initform nil)
-   (hide        :initarg :hide        :initform nil)
-   (description :initarg :description :initform nil))
+  ((suffixes       :initarg :suffixes       :initform nil)
+   (hide           :initarg :hide           :initform nil)
+   (description    :initarg :description    :initform nil)
+   (setup-children :initarg :setup-children))
   "Abstract superclass of all group classes."
   :abstract t)
 
@@ -1614,6 +1615,15 @@ EDIT may be non-nil."
     (transient--init-transient)
     (transient--suspend-which-key-mode)))
 
+(cl-defgeneric transient-setup-children (group children)
+  "Setup the CHILDREN of GROUP.
+If the value of the `setup-children' slot is non-nil, then call
+that function with CHILDREN as the only argument and return the
+value.  Otherwise return CHILDREN as is."
+  (if (slot-boundp group 'setup-children)
+      (funcall (oref group setup-children) children)
+    children))
+
 (defun transient--init-objects (name layout params)
   (setq transient--prefix
         (let ((proto (get name 'transient--prefix)))
@@ -1656,7 +1666,7 @@ EDIT may be non-nil."
         (when (transient--use-suffix-p obj)
           (when-let ((suffixes
                       (cl-mapcan (lambda (c) (transient--init-child levels c))
-                                 children)))
+                                 (transient-setup-children obj children))))
             (oset obj suffixes suffixes)
             (list obj)))))))