branch: externals/transient
commit beecdc85799231338314bd20292f71fc8cd687e8
Author: Jonas Bernoulli <jo...@bernoul.li>
Commit: Jonas Bernoulli <jo...@bernoul.li>
Document that :class might be needed if :setup-children is used
It was undefined which class would be used if none was specified
explicitly and `:setup-children' is used. Using `transient-column'
makes sense because, at least for a flat list of suffixes, that is
the default for explicitly specified suffixes too.
[1: df36bc87] accidentally changed the undefined default behavior to
use `transient-columns' instead. This commit reverts that, but it is
still considered undefined behavior. We now display a warning if this
is encountered, and that will eventually be turned into an error.
(Note that while not particularly useful, it is allowed to define a
group with neither explicit children nor `:setup-children' (it will
be silently omitted). At least for now, we keep it that way.)
Closes #277.
1: 2024-02-01 df36bc8745520f4580c8bc9260d57aa53878a053
transient--parse-group: Detect columns beginning with included group
---
docs/transient.org | 22 ++++++++++++++++------
docs/transient.texi | 22 ++++++++++++++++------
lisp/transient.el | 5 ++++-
3 files changed, 36 insertions(+), 13 deletions(-)
diff --git a/docs/transient.org b/docs/transient.org
index 598910ea35..3b64c6e38e 100644
--- a/docs/transient.org
+++ b/docs/transient.org
@@ -1011,9 +1011,19 @@ constructor of that class.
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
+ ~transient-parse-suffixes~ and ~transient-parse-suffix~ functions to
transform them from the convenient to the expected form.
+ If you explicitly specify children and then transform them using
+ ~:setup-chilren~, then the class of the group is determined as usual,
+ based on explicitly specified children.
+
+ If you do not explicitly specify children and thus rely solely on
+ ~:setup-children~, then you must specify the class using ~:class~.
+ For backward compatibility, if you fail to do so, ~transient-column~
+ is used and a warning is displayed. This warning will eventually
+ be replaced with an error.
+
- The boolean ~:pad-keys~ argument controls whether keys of all suffixes
contained in a group are right padded, effectively aligning the
descriptions.
@@ -1023,11 +1033,11 @@ The {{{var(ELEMENT)}}}s are either all subgroups, or
all suffixes and strings.
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 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.
+If the {{{var(ELEMENT)}}}s are not subgroups, then they can be a mixture of
+lists, which 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
diff --git a/docs/transient.texi b/docs/transient.texi
index d90f72609f..e74e090b7c 100644
--- a/docs/transient.texi
+++ b/docs/transient.texi
@@ -1200,9 +1200,19 @@ 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
+@code{transient-parse-suffixes} and @code{transient-parse-suffix} functions to
transform them from the convenient to the expected form.
+If you explicitly specify children and then transform them using
+@code{:setup-chilren}, then the class of the group is determined as usual,
+based on explicitly specified children.
+
+If you do not explicitly specify children and thus rely solely on
+@code{:setup-children}, then you must specify the class using @code{:class}.
+For backward compatibility, if you fail to do so, @code{transient-column}
+is used and a warning is displayed. This warning will eventually
+be replaced with an error.
+
@item
The boolean @code{:pad-keys} argument controls whether keys of all suffixes
contained in a group are right padded, effectively aligning the
@@ -1214,11 +1224,11 @@ The @var{ELEMENT}s are either all subgroups, or all
suffixes and strings.
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 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.
+If the @var{ELEMENT}s are not subgroups, then they can be a mixture of
+lists, which 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
diff --git a/lisp/transient.el b/lisp/transient.el
index c0e4eee11c..c9b24d6206 100644
--- a/lisp/transient.el
+++ b/lisp/transient.el
@@ -1117,11 +1117,14 @@ commands are aliases for."
(and (listp val) (not (eq (car val) 'lambda))))
(setq args (plist-put args key (macroexp-quote val))))
((setq args (plist-put args key val))))))
+ (unless (or spec class (not (plist-get args :setup-children)))
+ (message "WARNING: %s: When %s is used, %s must also be specified"
+ 'transient-define-prefix :setup-children :class))
(list 'vector
(or level transient--default-child-level)
(cond (class)
((or (vectorp car)
- (symbolp car))
+ (and car (symbolp car)))
(quote 'transient-columns))
((quote 'transient-column)))
(and args (cons 'list args))
