|
|
|
|
@@ -1,4 +1,4 @@
|
|
|
|
|
This is transient.info, produced by makeinfo version 7.1.1 from
|
|
|
|
|
This is transient.info, produced by makeinfo version 7.2 from
|
|
|
|
|
transient.texi.
|
|
|
|
|
|
|
|
|
|
Copyright (C) 2018-2025 Free Software Foundation, Inc.
|
|
|
|
|
@@ -32,7 +32,7 @@ used to implement similar menus in other packages.
|
|
|
|
|
resource to get over that hurdle is Psionic K's interactive tutorial,
|
|
|
|
|
available at <https://github.com/positron-solutions/transient-showcase>.
|
|
|
|
|
|
|
|
|
|
This manual is for Transient version 0.9.3.
|
|
|
|
|
This manual is for Transient version 0.11.0.
|
|
|
|
|
|
|
|
|
|
Copyright (C) 2018-2025 Free Software Foundation, Inc.
|
|
|
|
|
|
|
|
|
|
@@ -98,7 +98,6 @@ Classes and Methods
|
|
|
|
|
* Suffix Slots::
|
|
|
|
|
* Predicate Slots::
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
File: transient.info, Node: Introduction, Next: Usage, Prev: Top, Up: Top
|
|
|
|
|
|
|
|
|
|
@@ -806,6 +805,9 @@ Auxiliary Options
|
|
|
|
|
not match the respective command-line argument should be
|
|
|
|
|
highlighted. For other infix commands this option has no effect.
|
|
|
|
|
|
|
|
|
|
This is mostly indended for autors of transient menus and disabled
|
|
|
|
|
by default.
|
|
|
|
|
|
|
|
|
|
When this option is non-‘nil’, the key binding for an infix
|
|
|
|
|
argument is highlighted when only a long argument (e.g.,
|
|
|
|
|
‘--verbose’) is specified but no shorthand (e.g., ‘-v’). In the
|
|
|
|
|
@@ -963,12 +965,12 @@ after the infix argument that is bound to ‘-3’ in ‘magit-patch-apply’.
|
|
|
|
|
These functions operate on the information stored in the
|
|
|
|
|
‘transient--layout’ property of the PREFIX symbol. Elements in that
|
|
|
|
|
tree are not objects but have the form ‘(CLASS PLIST) for suffixes’ and
|
|
|
|
|
[CLASS PLIST CHILDREN] for groups. At the root of the tree is an
|
|
|
|
|
element [N nil CHILDREN], where N is the version of the layout format,
|
|
|
|
|
currently and hopefully for a long time 2. While that element looks
|
|
|
|
|
like a group vector, that element does not count when identifying a
|
|
|
|
|
group using a coordinate vector, i.e., [0] is its first child, not the
|
|
|
|
|
root element itself.
|
|
|
|
|
‘[CLASS PLIST CHILDREN]’ for groups. At the root of the tree is an
|
|
|
|
|
element ‘[N Nil CHILDREN]’, where ‘N’ is the version of the layout
|
|
|
|
|
format, currently and hopefully for a long time 2. While that element
|
|
|
|
|
looks like a group vector, that element does not count when identifying
|
|
|
|
|
a group using a coordinate vector, i.e., ‘[0]’ is its first child, not
|
|
|
|
|
the root element itself.
|
|
|
|
|
|
|
|
|
|
-- Function: transient-insert-suffix prefix loc suffix &optional
|
|
|
|
|
keep-other
|
|
|
|
|
@@ -1577,13 +1579,26 @@ same purpose as ‘prefix-arg’ serves for prefix arguments.
|
|
|
|
|
current command was not invoked from PREFIX, then it returns the
|
|
|
|
|
set, saved or default value for PREFIX.
|
|
|
|
|
|
|
|
|
|
-- Function: transient-get-value
|
|
|
|
|
This function returns the value of the current prefix.
|
|
|
|
|
PREFIX may also be a list of prefixes. If no prefix is active, the
|
|
|
|
|
fallback value of the first of these prefixes is used.
|
|
|
|
|
|
|
|
|
|
This is mostly intended for internal use, but may also be of use in
|
|
|
|
|
‘transient-set-value’ and ‘transient-save-value’ methods. Unlike
|
|
|
|
|
‘transient-args’, this does not include the values of suffixes
|
|
|
|
|
whose ‘unsavable’ slot is non-‘nil’.
|
|
|
|
|
The generic function ‘transient-prefix-value’ is used to determine
|
|
|
|
|
the returned value.
|
|
|
|
|
|
|
|
|
|
This function is intended to be used by suffix commands, whether
|
|
|
|
|
they are invoked from a menu or not. It is not intended to be used
|
|
|
|
|
when setting up a menu and its suffixes, in which case
|
|
|
|
|
‘transient-get-value’ should be used.
|
|
|
|
|
|
|
|
|
|
-- Function: transient-get-value
|
|
|
|
|
This function returns the value of the erant prefix.
|
|
|
|
|
|
|
|
|
|
This function is intended to be used when setting up a menu and its
|
|
|
|
|
suffixes. It is not intended to be used when a suffix command is
|
|
|
|
|
invoked, whether from a menu or not, in which case ‘transient-args’
|
|
|
|
|
should be used. In other words, use this, e.g., in a suffixes
|
|
|
|
|
‘:if*’ or ‘:inapt-if*’ predicate and ‘:description’ function, but
|
|
|
|
|
never in its ‘interactive’ form or function body.
|
|
|
|
|
|
|
|
|
|
-- Function: transient-arg-value arg args
|
|
|
|
|
This function returns the value of ARG as it appears in ARGS.
|
|
|
|
|
@@ -1612,18 +1627,18 @@ its value can be accessed using ‘transient-args’.
|
|
|
|
|
This function returns the scope of the active or current transient
|
|
|
|
|
prefix command.
|
|
|
|
|
|
|
|
|
|
If optional PREFIXES and CLASSES are both nil, return the scope of
|
|
|
|
|
the prefix currently being setup, making this variation useful,
|
|
|
|
|
If optional PREFIXES and CLASSES are both ‘nil’, return the scope
|
|
|
|
|
of the prefix currently being setup, making this variation useful,
|
|
|
|
|
e.g., in ‘:if*’ predicates. If no prefix is being setup, but the
|
|
|
|
|
current command was invoked from some prefix, then return the scope
|
|
|
|
|
of that.
|
|
|
|
|
|
|
|
|
|
If PREFIXES is non-nil, it must be a prefix command or a list of
|
|
|
|
|
such commands. If CLASSES is non-nil, it must be a prefix class or
|
|
|
|
|
a list of such classes. When this function is called from the body
|
|
|
|
|
or the ‘interactive’ form of a suffix command, PREFIXES and/or
|
|
|
|
|
CLASSES should be non-nil. If either is non-nil, try the following
|
|
|
|
|
in order:
|
|
|
|
|
If PREFIXES is non-‘nil’, it must be a prefix command or a list of
|
|
|
|
|
such commands. If CLASSES is non-‘nil’, it must be a prefix class
|
|
|
|
|
or a list of such classes. When this function is called from the
|
|
|
|
|
body or the ‘interactive’ form of a suffix command, PREFIXES and/or
|
|
|
|
|
CLASSES should be non-‘nil’. If either is non-‘nil’, try the
|
|
|
|
|
following in order:
|
|
|
|
|
|
|
|
|
|
• If the current suffix command was invoked from a prefix, which
|
|
|
|
|
appears in PREFIXES, return the scope of that prefix.
|
|
|
|
|
@@ -1643,7 +1658,7 @@ its value can be accessed using ‘transient-args’.
|
|
|
|
|
respective class definition or using its
|
|
|
|
|
'transient-init-scope' method.
|
|
|
|
|
|
|
|
|
|
If no prefix matches, return nil.
|
|
|
|
|
If no prefix matches, return ‘nil’.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
File: transient.info, Node: Current Suffix Command, Next: Current Prefix Command, Prev: Using Prefix Scope, Up: Defining New Commands
|
|
|
|
|
@@ -2244,6 +2259,21 @@ functions use ‘describe-function’.
|
|
|
|
|
|
|
|
|
|
-- Function: transient-prefix-value obj
|
|
|
|
|
This generic function returns the value of the prefix object OBJ.
|
|
|
|
|
|
|
|
|
|
OBJ is a prototype object and is only used to select the
|
|
|
|
|
appropriate method of this generic function. This function does
|
|
|
|
|
not return the value of that object. Instead it extracts the name
|
|
|
|
|
of the respective command from the object and uses that to collect
|
|
|
|
|
the current values from the suffixes of the prefix from which the
|
|
|
|
|
current command was invoked. If the current command was not
|
|
|
|
|
invoked from the identified prefix, then this method returns the
|
|
|
|
|
set, save or default value, as described for ‘transient-args’.
|
|
|
|
|
|
|
|
|
|
This function is only intended to be used by ‘transient-args’. It
|
|
|
|
|
is not defined as an internal function because third-party packages
|
|
|
|
|
may define their own methods. That does not mean that it would be
|
|
|
|
|
a good idea to call it for any other purpose.
|
|
|
|
|
|
|
|
|
|
The respective generic function for infix and suffix objects is
|
|
|
|
|
named ‘transient-infix-value’.
|
|
|
|
|
|
|
|
|
|
@@ -2438,6 +2468,40 @@ Value and Scope
|
|
|
|
|
value, then this slot has to be set to the same value for all of
|
|
|
|
|
them. You probably don't want that.
|
|
|
|
|
|
|
|
|
|
• ‘remember-value’ When a suffix command is invoked, which can
|
|
|
|
|
consume the prefix's value (which depends on the suffix slot
|
|
|
|
|
‘transient’ and the prefix slots ‘transient-suffix’ and
|
|
|
|
|
‘transient-non-suffix’), then the value is automatically pushed to
|
|
|
|
|
the prefix's value history.
|
|
|
|
|
|
|
|
|
|
This slot allows additionally setting or even saving the value, so
|
|
|
|
|
that it becomes the initial value when the menu is invoked again.
|
|
|
|
|
|
|
|
|
|
Beside ‘nil’, the value can be one of these symbols:
|
|
|
|
|
|
|
|
|
|
• ‘export’ Set the value when it is exported. That is the time
|
|
|
|
|
when the value would ordinarily just be pushed to the history
|
|
|
|
|
stack.
|
|
|
|
|
|
|
|
|
|
• ‘exit’ Set the value when the menu is exited, except when that
|
|
|
|
|
is done using a command whose sole purpose is to quit the
|
|
|
|
|
menu.
|
|
|
|
|
|
|
|
|
|
• ‘quit’ Set the value when the menu is quit, using a command
|
|
|
|
|
whose sole purpose is to do so.
|
|
|
|
|
|
|
|
|
|
The value can also be a list of one or more of these symbols and
|
|
|
|
|
optionally also the symbol ‘save’.
|
|
|
|
|
|
|
|
|
|
• ‘save’ Instead of merely setting the value, save it, so that
|
|
|
|
|
it will be used in future Emacs sessions. At least one other
|
|
|
|
|
symbol has to be used together with this.
|
|
|
|
|
|
|
|
|
|
The value can also be a (quoted) variable, whose value is a list of
|
|
|
|
|
symbols as described above. Ideally an option should be used,
|
|
|
|
|
since not all users will find the automatic saving of the value
|
|
|
|
|
desirable.
|
|
|
|
|
|
|
|
|
|
• ‘incompatible’ A list of lists. Each sub-list specifies a set of
|
|
|
|
|
mutually exclusive arguments. Enabling one of these arguments
|
|
|
|
|
causes the others to be disabled. An argument may appear in
|
|
|
|
|
@@ -2614,7 +2678,7 @@ Slots of ‘transient-suffix’
|
|
|
|
|
|
|
|
|
|
The following two slots are experimental. They can also be set for a
|
|
|
|
|
group, in which case they apply to all suffixes in that group, except
|
|
|
|
|
for suffixes that set the same slot to a non-nil value.
|
|
|
|
|
for suffixes that set the same slot to a non-‘nil’ value.
|
|
|
|
|
|
|
|
|
|
• ‘advice’ A function used to advise the command. The advise is
|
|
|
|
|
called using ‘(apply advice command args)’, i.e., it behaves like
|
|
|
|
|
@@ -2622,9 +2686,9 @@ for suffixes that set the same slot to a non-nil value.
|
|
|
|
|
|
|
|
|
|
• ‘advice*’ A function used to advise the command. Unlike ‘advice’,
|
|
|
|
|
this advises not only the command body but also its ‘interactive’
|
|
|
|
|
spec. If both slots are non-nil, ‘advice’ is used for the body and
|
|
|
|
|
‘advice*’ is used for the ‘interactive’ form. When advising the
|
|
|
|
|
‘interactive’ spec, called using ‘(funcall advice
|
|
|
|
|
spec. If both slots are non-‘nil’, ‘advice’ is used for the body
|
|
|
|
|
and ‘advice*’ is used for the ‘interactive’ form. When advising
|
|
|
|
|
the ‘interactive’ spec, called using ‘(funcall advice
|
|
|
|
|
#'advice-eval-interactive-spec spec)’.
|
|
|
|
|
|
|
|
|
|
Slots of ‘transient-infix’
|
|
|
|
|
@@ -2903,7 +2967,7 @@ Appendix C Command and Function Index
|
|
|
|
|
* transient-append-suffix: Modifying Existing Transients.
|
|
|
|
|
(line 63)
|
|
|
|
|
* transient-arg-value: Using Infix Arguments.
|
|
|
|
|
(line 39)
|
|
|
|
|
(line 52)
|
|
|
|
|
* transient-args: Using Infix Arguments.
|
|
|
|
|
(line 22)
|
|
|
|
|
* transient-copy-menu-text: Other Commands. (line 25)
|
|
|
|
|
@@ -2924,7 +2988,7 @@ Appendix C Command and Function Index
|
|
|
|
|
* transient-get-suffix: Modifying Existing Transients.
|
|
|
|
|
(line 88)
|
|
|
|
|
* transient-get-value: Using Infix Arguments.
|
|
|
|
|
(line 31)
|
|
|
|
|
(line 42)
|
|
|
|
|
* transient-help: Getting Help for Suffix Commands.
|
|
|
|
|
(line 11)
|
|
|
|
|
* transient-history-next: Using History. (line 22)
|
|
|
|
|
@@ -2932,7 +2996,7 @@ Appendix C Command and Function Index
|
|
|
|
|
* transient-infix-read: Suffix Methods. (line 34)
|
|
|
|
|
* transient-infix-set: Suffix Methods. (line 54)
|
|
|
|
|
* transient-infix-value: Suffix Methods. (line 57)
|
|
|
|
|
* transient-init-scope: Prefix Methods. (line 37)
|
|
|
|
|
* transient-init-scope: Prefix Methods. (line 52)
|
|
|
|
|
* transient-init-scope <1>: Suffix Methods. (line 70)
|
|
|
|
|
* transient-init-value: Prefix Methods. (line 9)
|
|
|
|
|
* transient-init-value <1>: Suffix Methods. (line 12)
|
|
|
|
|
@@ -2974,7 +3038,7 @@ Appendix C Command and Function Index
|
|
|
|
|
* transient-suffix-put: Modifying Existing Transients.
|
|
|
|
|
(line 92)
|
|
|
|
|
* transient-suffixes: Using Infix Arguments.
|
|
|
|
|
(line 46)
|
|
|
|
|
(line 59)
|
|
|
|
|
* transient-suspend: Aborting and Resuming Transients.
|
|
|
|
|
(line 41)
|
|
|
|
|
* transient-toggle-common: Common Suffix Commands.
|
|
|
|
|
@@ -2993,7 +3057,7 @@ Appendix D Variable Index
|
|
|
|
|
|