[elpa] externals/transient cac657a03e 092/366: Support inserting/removing groups and doing it using coordinates

[Jonas Bernoulli]

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

    Support inserting/removing groups and doing it using coordinates
    
    Closes #36.
---
 docs/transient.org  |  41 +++++++++++++------
 docs/transient.texi |  41 +++++++++++++------
 lisp/transient.el   | 114 +++++++++++++++++++++++++++++++++++-----------------
 3 files changed, 135 insertions(+), 61 deletions(-)

diff --git a/docs/transient.org b/docs/transient.org
index 9ba6c2eb8e..74f90ace84 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.1.0 (v0.1.0-82-gf0a7a97+1)
+#+SUBTITLE: for version 0.1.0 (v0.1.0-90-g4ce1868+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.1.0 (v0.1.0-82-gf0a7a97+1).
+This manual is for Transient version 0.1.0 (v0.1.0-90-g4ce1868+1).
 
 #+BEGIN_QUOTE
 Copyright (C) 2018-2019 Jonas Bernoulli <jonas@bernoul.li>
@@ -626,13 +626,29 @@ can be further modified non-interactively.
 The following functions share a few arguments:
 
 - PREFIX is a transient prefix command, a symbol.
+
 - SUFFIX is a transient infix or suffix specification in the same form
   as expected by ~define-transient-command~.  Note that an infix is a
   special kind of suffix.  Depending on context "suffixes" means
   "suffixes (including infixes)" or "non-infix suffixes".  Here it
   means the former.  See [[*Suffix Specifications]].
-- LOC is a command, a key vector or a key description (a string as
-  returned by ~key-description~).
+
+  SUFFIX may also be a group in the same form as expected by
+  ~define-transient-command~.  See [[*Group Specifications]].
+
+- LOC is a command, a key vector, a key description (a string as
+  returned by ~key-description~), or a list specifying coordinates (the
+  last element may also be a command or key). For example ~(1 0 -1)~
+  identifies the last suffix (~-1~) of the first subgroup (~0~) of the
+  second group (~1~).
+
+  If LOC is a list of coordinates, then it can be used to identify a
+  group, not just an individual suffix command.
+
+  The function ~transient-get-suffix~ can be useful to determine whether
+  a certain coordination list identifies the suffix or group that you
+  expect it to identify.  In hairy cases it may be necessary to look
+  at the definition of the transient prefix command.
 
 These functions operate on the information stored in the
 ~transient--layout~ property of the PREFIX symbol.  Suffix entries in
@@ -641,29 +657,30 @@ plist should set at least ~:key~, ~:description~ and 
~:command~.
 
 - Function: transient-insert-suffix prefix loc suffix
 
-  This function inserts SUFFIX into PREFIX before LOC.
+  This function inserts suffix or group SUFFIX into PREFIX before LOC.
 
 - Function: transient-append-suffix prefix loc suffix
 
-  This function inserts SUFFIX into PREFIX after LOC.
+  This function inserts suffix or group SUFFIX into PREFIX after LOC.
 
 - Function: transient-replace-suffix prefix loc suffix
 
-  This function replaces the suffix at LOC in PREFIX with SUFFIX.
+  This function replaces the suffix or group at LOC in PREFIX with
+  suffix or group SUFFIX.
 
 - Function: transient-remove-suffix prefix loc
 
-  This function removes the suffix at LOC in PREFIX.
+  This function removes the suffix or group at LOC in PREFIX.
 
 - Function: transient-get-suffix prefix loc
 
-  This function returns the suffix at LOC in PREFIX.  The returned
-  value has the form mentioned above.
+  This function returns the suffix or group at LOC in PREFIX.  The
+  returned value has the form mentioned above.
 
 - Function: transient-suffix-put prefix loc prop value
 
-  This function edits the suffix at LOC in PREFIX, by setting the
-  PROP of its plist to VALUE.
+  This function edits the suffix or group at LOC in PREFIX, by setting
+  the PROP of its plist to VALUE.
 
 Most of these functions do not signal an error if they cannot perform
 the requested modification.  The functions that insert new suffixes
diff --git a/docs/transient.texi b/docs/transient.texi
index eb1a75ce4c..c68d80174e 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.1.0 (v0.1.0-82-gf0a7a97+1)
+@subtitle for version 0.1.0 (v0.1.0-90-g4ce1868+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.1.0 (v0.1.0-82-gf0a7a97+1).
+This manual is for Transient version 0.1.0 (v0.1.0-90-g4ce1868+1).
 
 @quotation
 Copyright (C) 2018-2019 Jonas Bernoulli <jonas@@bernoul.li>
@@ -820,6 +820,7 @@ The following functions share a few arguments:
 @item
 PREFIX is a transient prefix command, a symbol.
 
+
 @item
 SUFFIX is a transient infix or suffix specification in the same form
 as expected by @code{define-transient-command}.  Note that an infix is a
@@ -827,9 +828,24 @@ special kind of suffix.  Depending on context "suffixes" 
means
 "suffixes (including infixes)" or "non-infix suffixes".  Here it
 means the former.  See @ref{Suffix Specifications}.
 
+SUFFIX may also be a group in the same form as expected by
+@code{define-transient-command}.  See @ref{Group Specifications}.
+
+
 @item
-LOC is a command, a key vector or a key description (a string as
-returned by @code{key-description}).
+LOC is a command, a key vector, a key description (a string as
+returned by @code{key-description}), or a list specifying coordinates (the
+last element may also be a command or key). For example @code{(1 0 -1)}
+identifies the last suffix (@code{-1}) of the first subgroup (@code{0}) of the
+second group (@code{1}).
+
+If LOC is a list of coordinates, then it can be used to identify a
+group, not just an individual suffix command.
+
+The function @code{transient-get-suffix} can be useful to determine whether
+a certain coordination list identifies the suffix or group that you
+expect it to identify.  In hairy cases it may be necessary to look
+at the definition of the transient prefix command.
 @end itemize
 
 These functions operate on the information stored in the
@@ -839,34 +855,35 @@ plist should set at least @code{:key}, 
@code{:description} and @code{:command}.
 
 @defun transient-insert-suffix prefix loc suffix
 
-This function inserts SUFFIX into PREFIX before LOC@.
+This function inserts suffix or group SUFFIX into PREFIX before LOC@.
 @end defun
 
 @defun transient-append-suffix prefix loc suffix
 
-This function inserts SUFFIX into PREFIX after LOC@.
+This function inserts suffix or group SUFFIX into PREFIX after LOC@.
 @end defun
 
 @defun transient-replace-suffix prefix loc suffix
 
-This function replaces the suffix at LOC in PREFIX with SUFFIX@.
+This function replaces the suffix or group at LOC in PREFIX with
+suffix or group SUFFIX@.
 @end defun
 
 @defun transient-remove-suffix prefix loc
 
-This function removes the suffix at LOC in PREFIX@.
+This function removes the suffix or group at LOC in PREFIX@.
 @end defun
 
 @defun transient-get-suffix prefix loc
 
-This function returns the suffix at LOC in PREFIX@.  The returned
-value has the form mentioned above.
+This function returns the suffix or group at LOC in PREFIX@.  The
+returned value has the form mentioned above.
 @end defun
 
 @defun transient-suffix-put prefix loc prop value
 
-This function edits the suffix at LOC in PREFIX, by setting the
-PROP of its plist to VALUE@.
+This function edits the suffix or group at LOC in PREFIX, by setting
+the PROP of its plist to VALUE@.
 @end defun
 
 Most of these functions do not signal an error if they cannot perform
diff --git a/lisp/transient.el b/lisp/transient.el
index 57be9ab7f3..b90d6cac19 100644
--- a/lisp/transient.el
+++ b/lisp/transient.el
@@ -868,64 +868,85 @@ example, sets a variable use `define-infix-command' 
instead.
 ;;; Edit
 
 (defun transient--insert-suffix (prefix loc suffix action)
-  (let* ((suf (transient--parse-suffix prefix suffix))
+  (let* ((suf (cl-etypecase suffix
+                (vector (transient--parse-group  prefix suffix))
+                (list   (transient--parse-suffix prefix suffix))))
          (mem (transient--layout-member loc prefix)))
-    (if mem
+    (cond
+     ((not mem)
+      (message "Cannot insert %S into %s; %s not found"
+               suffix prefix loc))
+     ((not (eq (type-of suffix)
+               (type-of (car mem))))
+      (message "Cannot place %S into %s at %s; %s"
+               suffix prefix loc
+               "suffixes and groups cannot be siblings"))
+     (t
+      (when (listp suffix)
         (let ((key (plist-get (nth 2 suf) :key)))
           (if (equal (transient--kbd key)
                      (transient--kbd (plist-get (nth 2 (car mem)) :key)))
               (setq action 'replace)
-            (transient-remove-suffix prefix key))
-          (cl-ecase action
-            (insert  (setcdr mem (cons (car mem) (cdr mem)))
-                     (setcar mem suf))
-            (append  (setcdr mem (cons suf (cdr mem))))
-            (replace (setcar mem suf))))
-      (message "Cannot insert %S into %s; %s not found" suffix prefix loc))))
+            (transient-remove-suffix prefix key))))
+      (cl-ecase action
+        (insert  (setcdr mem (cons (car mem) (cdr mem)))
+                 (setcar mem suf))
+        (append  (setcdr mem (cons suf (cdr mem))))
+        (replace (setcar mem suf)))))))
 
 (defun transient-insert-suffix (prefix loc suffix)
   "Insert a SUFFIX into PREFIX before LOC.
 PREFIX is a prefix command, a symbol.
-SUFFIX is a suffix command specification list of the
-  same form as expected by `define-transient-command'.
-LOC is a command or a key vector or a key description
-  (a string as returned by `key-description')."
+SUFFIX is a suffix command or a group specification (of
+  the same forms as expected by `define-transient-command').
+LOC is a command, a key vector, a key description (a string
+  as returned by `key-description'), or a coordination list
+  (whose last element may also be a command or key).
+See info node `(transient)Modifying Existing Transients'."
   (declare (indent defun))
   (transient--insert-suffix prefix loc suffix 'insert))
 
 (defun transient-append-suffix (prefix loc suffix)
   "Insert a SUFFIX into PREFIX after LOC.
 PREFIX is a prefix command, a symbol.
-SUFFIX is a suffix command specification list of the
-  same form as expected by `define-transient-command'.
-LOC is a command, a key vector or a key description
-  (a string as returned by `key-description')."
+SUFFIX is a suffix command or a group specification (of
+  the same forms as expected by `define-transient-command').
+LOC is a command, a key vector, a key description (a string
+  as returned by `key-description'), or a coordination list
+  (whose last element may also be a command or key).
+See info node `(transient)Modifying Existing Transients'."
   (declare (indent defun))
   (transient--insert-suffix prefix loc suffix 'append))
 
 (defun transient-replace-suffix (prefix loc suffix)
   "Replace the suffix at LOC in PREFIX with SUFFIX.
 PREFIX is a prefix command, a symbol.
-SUFFIX is a suffix command specification list of the
-  same form as expected by `define-transient-command'.
-LOC is a command, a key vector or a key description
-  (a string as returned by `key-description')."
+SUFFIX is a suffix command or a group specification (of
+  the same forms as expected by `define-transient-command').
+LOC is a command, a key vector, a key description (a string
+  as returned by `key-description'), or a coordination list
+  (whose last element may also be a command or key).
+See info node `(transient)Modifying Existing Transients'."
   (declare (indent defun))
   (transient--insert-suffix prefix loc suffix 'replace))
 
 (defun transient-remove-suffix (prefix loc)
-  "Remove the suffix at LOC in PREFIX.
+  "Remove the suffix or group at LOC in PREFIX.
 PREFIX is a prefix command, a symbol.
-LOC is a command, a key vector or a key description
-  (a string as returned by `key-description')."
+LOC is a command, a key vector, a key description (a string
+  as returned by `key-description'), or a coordination list
+  (whose last element may also be a command or key).
+See info node `(transient)Modifying Existing Transients'."
   (declare (indent defun))
   (transient--layout-member loc prefix 'remove))
 
 (defun transient-get-suffix (prefix loc)
-  "Return the suffix at LOC from PREFIX.
+  "Return the suffix or group at LOC in PREFIX.
 PREFIX is a prefix command, a symbol.
-LOC is a command, a key vector or a key description
-  (a string as returned by `key-description')."
+LOC is a command, a key vector, a key description (a string
+  as returned by `key-description'), or a coordination list
+  (whose last element may also be a command or key).
+See info node `(transient)Modifying Existing Transients'."
   (if-let ((mem (transient--layout-member loc prefix)))
       (car mem)
     (error "%s not found in %s" loc prefix)))
@@ -933,18 +954,34 @@ LOC is a command, a key vector or a key description
 (defun transient-suffix-put (prefix loc prop value)
   "Edit the suffix at LOC in PREFIX, setting PROP to VALUE.
 PREFIX is a prefix command, a symbol.
-LOC is a command, a key vector or a key description
-  (a string as returned by `key-description').
-PROP has to be a keyword.  What keywords and values
-  are valid depends on the type of the suffix."
-  (let ((elt (transient-get-suffix prefix loc)))
-    (setf (nth 2 elt)
-          (plist-put (nth 2 elt) prop value))))
+SUFFIX is a suffix command or a group specification (of
+  the same forms as expected by `define-transient-command').
+LOC is a command, a key vector, a key description (a string
+  as returned by `key-description'), or a coordination list
+  (whose last element may also be a command or key).
+See info node `(transient)Modifying Existing Transients'."
+  (let ((suf (transient-get-suffix prefix loc)))
+    (setf (elt suf 2)
+          (plist-put (elt suf 2) prop value))))
 
 (defun transient--layout-member (loc prefix &optional remove)
-  (if-let ((layout (get prefix 'transient--layout)))
-      (transient--layout-member-1 (transient--kbd loc) layout remove)
-    (error "%s is not a transient command" prefix)))
+  (let ((val (or (get prefix 'transient--layout)
+                 (error "%s is not a transient command" prefix))))
+    (when (listp loc)
+      (while (integerp (car loc))
+        (let* ((children (if (vectorp val) (aref val 3) val))
+               (mem (transient--nthcdr (pop loc) children)))
+          (if (and remove (not loc))
+              (let ((rest (delq (car mem) children)))
+                (if (vectorp val)
+                    (aset val 3 rest)
+                  (put prefix 'transient--layout rest))
+                (setq val nil))
+            (setq val (if loc (car mem) mem)))))
+      (setq loc (car loc)))
+    (if loc
+        (transient--layout-member-1 (transient--kbd loc) val remove)
+      val)))
 
 (defun transient--layout-member-1 (loc layout remove)
   (cond ((listp layout)
@@ -986,6 +1023,9 @@ PROP has to be a keyword.  What keywords and values
                (oref obj shortarg)
              (transient--derive-shortarg (oref obj argument)))))))
 
+(defun transient--nthcdr (n list)
+  (nthcdr (if (< n 0) (- (length list) (abs n)) n) list))
+
 ;;; Variables
 
 (defvar current-transient-prefix nil