[elpa] externals/transient eac39e8b70 1/2: transient--do-leave: New pre-command for non-suffixes

[Jonas Bernoulli]

branch: externals/transient
commit eac39e8b70ecbc92f88384be5b181701aebe1351
Author: Jonas Bernoulli <jonas@bernoul.li>
Commit: Jonas Bernoulli <jonas@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."