mirrors/emacs
1
Fork 0
mirror of git://git.sv.gnu.org/emacs.git synced 2026-01-30 12:21:25 -08:00
Code Issues Projects Releases Wiki Activity

Update to Transient v0.3.7-182-gfe7dcbd

Browse source
This commit is contained in:
Jonas Bernoulli 2022-11-30 21:32:40 +01:00
parent 1abda0c839
commit 26c2ebd0dd
No known key found for this signature in database
GPG key ID: 230C2EFBB326D927
2 changed files with 110 additions and 47 deletions
Download patch file Download diff file Expand all files Collapse all files

127
doc/misc/transient.texi
View file

@ -31,7 +31,7 @@ General Public License for more details.
@finalout
@titlepage
@title Transient User and Developer Manual
@subtitle for version 0.3.7
@subtitle for version 0.3.7.50
@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.3.7.
This manual is for Transient version 0.3.7.50.
@insertcopying
@end ifnottex
@ -447,10 +447,10 @@ session.
Save the value of the active transient persistently across Emacs
sessions.
@item @kbd{C-x C-k} (@code{transient-save})
@item @kbd{C-x C-k} (@code{transient-reset})
@kindex C-x C-k
@findex transient-save
Clear the set and saved value of the active transient.
@findex transient-reset
Clear the set and saved values of the active transient.
@end table
@defopt transient-values-file
@ -911,7 +911,6 @@ means the former. @xref{Suffix Specifications}.
@var{SUFFIX} may also be a group in the same form as expected by
@code{transient-define-prefix}. @xref{Group Specifications}.
@item
@var{LOC} is a command, a key vector, a key description (a string as
returned by @code{key-description}), or a list specifying coordinates (the
@ -1044,6 +1043,18 @@ For example, the scope of the @code{magit-branch-configure} transient is
the branch whose variables are being configured.
@end defmac
It is possible to define one or more groups independently of a prefix
definition, which is useful when those groups are to be used by more
than just one prefix command.
@defmac transient-define-groups name group...
This macro defines one or more groups of infix and suffix commands
and stores them in a property of the symbol @var{NAME}. @var{GROUP} has the
same form as for @code{transient-define-prefix}. Subsequently @var{NAME} can
be used in a @var{GROUP} of @code{transient-define-prefix}, as described in the
next section.
@end defmac
@node Binding Suffix and Infix Commands
@section Binding Suffix and Infix Commands
@ -1139,11 +1150,17 @@ suffixes, which assumes that a predicate like this is used:
@item
The value of @code{:setup-children}, if non-@code{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}.
one argument, a potentially list of children, and must return a list
of children or an empty list. This can either be used to somehow
transform the group's children that were defined the normal way, or
to dynamically create the children from scratch.
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
transform them from the convenient to the expected form.
@item
The boolean @code{:pad-keys} argument controls whether keys of all suffixes
@ -1151,23 +1168,35 @@ contained in a group are right padded, effectively aligning the
descriptions.
@end itemize
The @var{ELEMENT}s 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
in principle there is nothing that prevents that.)
The @var{ELEMENT}s are either all subgroups, or all suffixes and strings.
(At least currently no group type exists that would allow mixing
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.
The empty string can be used to insert gaps between suffixes, which is
particularly useful if the suffixes are outlined as a table.
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.
Variables are supported inside group specifications. For example in
place of a direct subgroup specification, a variable can be used whose
value is a vector that qualifies as a group specification. Likewise,
a variable can be used where a suffix specification is expected.
Lists of group or suffix specifications are also supported. Indirect
specifications are resolved when the transient prefix is being
defined.
Inside group specifications, including inside contained suffix
specifications, nothing has to be quoted and quoting anyway is
invalid.
How symbols are treated, depends on context. Inside suffix
specifications they often name functions. However if they appear in
a place where a group is expected, then they are treated as indirect
group specifications. Such a symbol must have an associated group
specification, created using @code{transient-define-groups}.
Likewise a symbol can appear in a place where a suffix specification
is expected. The value of the @code{transient--layout} property of that
symbol must be a single suffix specification or a list of such
specifications. Currently no macro exist that would create such a
symbol, and this feature should usually not be used.
The value following a keyword, can be explicitly unquoted using @code{,}.
This feature is experimental and should be avoided as well.
The form of suffix specifications is documented in the next node.
@ -1232,7 +1261,7 @@ Any command will do; it does not need to have an object associated
with it (as would be the case if @code{transient-define-suffix} or
@code{transient-define-infix} were used to define it).
Anonymous, dynamically defined suffix commands are also support.
Anonymous, dynamically defined suffix commands are also supported.
See information about the @code{:setup-children} function in @ref{Group Specifications}.
As mentioned above, the object that is associated with a command can
@ -1515,7 +1544,18 @@ Call the command without exporting variables and stay transient.
@anchor{Pre-commands for Suffixes}
@subheading Pre-commands for Suffixes
The default for suffixes is @code{transient--do-exit}.
By default, invoking a suffix causes the transient to be exited.
If you want a different default behavior for a certain transient
prefix command, then set its @code{:transient-suffix} slot. The value can be
a boolean, answering the question "does the transient stay active,
when a suffix command is invoked?" @code{t} means that the transient stays
active, while @code{nil} means that invoking a suffix exits the transient.
In either case, the exact behavior depends on whether the suffix is
itself a prefix (i.e., a sub-prefix), an infix or a regular suffix.
The behavior for an individual suffix command can be changed by
setting its @code{transient} slot to one of the following pre-commands.
@defun transient--do-exit
Call the command after exporting variables and exit the transient.
@ -1566,21 +1606,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}
@ -1810,7 +1861,7 @@ indicates that all remaining arguments are files.
@item
Classes used for infix commands that represent variables should
derived from the abstract @code{transient-variables} class.
derived from the abstract @code{transient-variable} class.
@end itemize
Magit defines additional classes, which can serve as examples for the
@ -2045,7 +2096,7 @@ called with no argument and returns a string.
@item
@code{show-help} A function used to display help for the suffix. If
unspecified, the prefix controls how hlep is displayed for its
unspecified, the prefix controls how help is displayed for its
suffixes.
@end itemize

30
lisp/transient.el
View file

@ -6,7 +6,7 @@
;; URL: https://github.com/magit/transient
;; Keywords: extensions
;; Package-Version: 0.3.7
;; Package-Version: 0.3.7.50
;; Package-Requires: ((emacs "26.1"))
;; SPDX-License-Identifier: GPL-3.0-or-later
@ -2199,7 +2199,7 @@ value. Otherwise return CHILDREN as is."
(delayed (if transient--exitp
(apply-partially #'transient--post-exit this-command)
#'transient--resume-override))
post-command abort-minibuffer)
outside-interactive post-command abort-minibuffer)
(unless abort-only
(setq post-command
(lambda () "@transient--delay-post-command"
@ -2211,7 +2211,9 @@ value. Otherwise return CHILDREN as is."
(equal
(ignore-errors
(string-to-multibyte (this-command-keys)))
(format "\M-x%s\r" this-command))))))
(format "\M-x%s\r" this-command))
;; Minibuffer used outside `interactive'.
(and outside-interactive 'post-cmd)))))
(transient--debug 'post-command-hook "act: %s" act)
(when act
(remove-hook 'transient--post-command-hook post-command)
@ -2220,12 +2222,15 @@ value. Otherwise return CHILDREN as is."
(add-hook 'transient--post-command-hook post-command))
(setq abort-minibuffer
(lambda () "@transient--delay-post-command"
(let ((act (and (or (memq this-command transient--abort-commands)
(equal (this-command-keys) ""))
(= (minibuffer-depth) depth))))
(let ((act (and (= (minibuffer-depth) depth)
(or (memq this-command transient--abort-commands)
(equal (this-command-keys) "")
(prog1 nil
(setq outside-interactive t))))))
(transient--debug
'abort-minibuffer
"mini: %s|%s, act %s" (minibuffer-depth) depth act)
"mini: %s|%s, act: %s" (minibuffer-depth) depth
(or act (and outside-interactive '->post-cmd)))
(when act
(remove-hook 'transient--post-command-hook post-command)
(remove-hook 'minibuffer-exit-hook abort-minibuffer)
@ -2407,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."
@ -3376,7 +3385,7 @@ have a history of their own.")
(insert ?\n)
(insert (propertize " " 'display
`(space :align-to (,(nth (1+ c) cc)))))))
(insert (make-string (- (nth c cc) (current-column)) ?\s))
(insert (make-string (max 1 (- (nth c cc) (current-column))) ?\s))
(when-let ((cell (nth r (nth c columns))))
(insert cell))
(when (= c (1- cs))
@ -4119,7 +4128,10 @@ we stop there."
'face 'transient-value))
(cl-defmethod transient-prompt ((obj transient-lisp-variable))
(format "Set %s: " (oref obj variable)))
(if (and (slot-boundp obj 'prompt)
(oref obj prompt))
(cl-call-next-method obj)
(format "Set %s: " (oref obj variable))))
(defun transient-lisp-variable--reader (prompt initial-input _history)
(read--expression prompt initial-input))