branch: externals/transient
commit eac39e8b70ecbc92f88384be5b181701aebe1351
Author: Jonas Bernoulli <jo...@bernoul.li>
Commit: Jonas Bernoulli <jo...@bernoul.li>
transient--do-leave: New pre-command for non-suffixes
Previously one would have had to use `transient--do-exit` but
unlike `transient--do-stay', that does export variable. Avoid
this unfortunate asymmetry, even though in most, if not all,
cases it should not affect the outcome.
---
docs/transient.org | 31 ++++++++++++++++++++++---------
docs/transient.texi | 29 ++++++++++++++++++++---------
lisp/transient.el | 4 ++++
3 files changed, 46 insertions(+), 18 deletions(-)
diff --git a/docs/transient.org b/docs/transient.org
index 5105e2a8d4..37845403af 100644
--- a/docs/transient.org
+++ b/docs/transient.org
@@ -1371,22 +1371,35 @@ slot.
:UNNUMBERED: notoc
:END:
-The default for non-suffixes, i.e., commands that are bound in other
-keymaps beside the transient keymap, is ~transient--do-warn~. Silently
-ignoring the user-error is also an option, though probably not a good
-one.
+By default, non-suffixes (commands that are bound in other keymaps
+beside the transient keymap) cannot be invoked. Trying to invoke
+such a command results in a warning and the transient stays active.
-If you want to let the user invoke non-suffix commands, then use
-~transient--do-stay~ as the value of the prefix's ~transient-non-suffix~
-slot.
+If you want a different behavior, then set the ~:transient-non-suffix~
+slot of the transient prefix command. The value can be a boolean,
+answering the question, "is it allowed to invoke non-suffix commands?"
+
+If the value is ~t~ or ~transient--do-stay~, then non-suffixes can be
+invoked, when it is ~nil~ or ~transient--do-warn~ (the default) then they
+cannot be invoked.
+
+The only other recommended value is ~transient--do-leave~. If that is
+used, then non-suffixes can be invoked, but if one is invoked, then
+that exits the transient.
- Function: transient--do-warn ::
Call ~transient-undefined~ and stay transient.
-- Function: transient--do-noop ::
+- Function: transient--do-stay ::
+
+ Call the command without exporting variables and stay transient.
+
+- Function: transient--do-leave ::
+
+ Call the command without exporting variables and exit the transient.
- Call ~transient-noop~ and stay transient.
+# transient--do-noop intentionally left undocumented.
*** Special Pre-Commands
:PROPERTIES:
diff --git a/docs/transient.texi b/docs/transient.texi
index 996cd96949..2b882d1725 100644
--- a/docs/transient.texi
+++ b/docs/transient.texi
@@ -1586,21 +1586,32 @@ be added to @code{transient-predicate-map}.
@anchor{Pre-commands for Non-Suffixes}
@subheading Pre-commands for Non-Suffixes
-The default for non-suffixes, i.e., commands that are bound in other
-keymaps beside the transient keymap, is @code{transient--do-warn}. Silently
-ignoring the user-error is also an option, though probably not a good
-one.
+By default, non-suffixes (commands that are bound in other keymaps
+beside the transient keymap) cannot be invoked. Trying to invoke
+such a command results in a warning and the transient stays active.
-If you want to let the user invoke non-suffix commands, then use
-@code{transient--do-stay} as the value of the prefix's
@code{transient-non-suffix}
-slot.
+If you want a different behavior, then set the @code{:transient-non-suffix}
+slot of the transient prefix command. The value can be a boolean,
+answering the question, "is it allowed to invoke non-suffix commands?"
+
+If the value is @code{t} or @code{transient--do-stay}, then non-suffixes can be
+invoked, when it is @code{nil} or @code{transient--do-warn} (the default) then
they
+cannot be invoked.
+
+The only other recommended value is @code{transient--do-leave}. If that is
+used, then non-suffixes can be invoked, but if one is invoked, then
+that exits the transient.
@defun transient--do-warn
Call @code{transient-undefined} and stay transient.
@end defun
-@defun transient--do-noop
-Call @code{transient-noop} and stay transient.
+@defun transient--do-stay
+Call the command without exporting variables and stay transient.
+@end defun
+
+@defun transient--do-leave
+Call the command without exporting variables and exit the transient.
@end defun
@anchor{Special Pre-Commands}
diff --git a/lisp/transient.el b/lisp/transient.el
index ab51e6c37a..deeb825d45 100644
--- a/lisp/transient.el
+++ b/lisp/transient.el
@@ -2412,6 +2412,10 @@ If there is no parent prefix, then behave like
`transient--do-exit'."
(transient--stack-zap)
transient--exit)
+(defun transient--do-leave ()
+ "Call the command without exporting variables and exit the transient."
+ transient--stay)
+
(defun transient--do-push-button ()
"Call the command represented by the activated button.
Use that command's pre-command to determine transient behavior."
