Next: Transient State, Previous: Defining Suffix and Infix Commands, Up: Defining New Commands [Contents][Index]
The function and the variables described below allow suffix commands to access the value of the transient from which they were invoked; which is the value of its infix arguments. These variables are set when the user invokes a suffix command that exits the transient, but before actually calling the command.
When returning to the command-loop after calling the suffix command,
the arguments are reset to nil
(which causes the function to return
nil
too).
Like for Emacs’ prefix arguments it is advisable, but not mandatory,
to access the infix arguments inside the command’s interactive
form.
The preferred way of doing that is to call the transient-args
function, which for infix arguments serves about the same purpose as
prefix-arg
serves for prefix arguments.
This function returns the value of the transient from which the
current suffix was called. If the current suffix command was not
called from a transient, then it returns nil
.
If optional PREFIX is non-nil
, then it should be a symbol, a
transient prefix command. In that case the value of the transient
is only returned if the suffix was invoked from that transient.
Otherwise nil
is returned. This function is also used internally,
in which PREFIX can also be a transient-prefix
object.
If optional SEPARATE is non-nil
, then the arguments are separated
into two groups. If SEPARATE is t
, they are separated into atoms
and conses (nil
isn’t a valid value, so it doesn’t matter that that
is both an atom and a cons).
SEPARATE can also be a predicate function, in which case the first
element is a list of the values for which it returns non-nil
and the
second element is a list of the values for which it returns nil
.
For transients that are used to pass arguments to a subprocess (such
as git
), stringp
is a useful value for SEPARATE, it separates
non-positional arguments from positional arguments. The value of
Magit’s file argument ("--"
) for example looks like this: ("--"
file...)
."
The suffixes of the transient from which this suffix command was
invoked. This is a list of objects. Usually it is sufficient to
instead use the function transient-args
, which returns a list of
values. In complex cases it might be necessary to use this variable
instead, i.e. if you need access to information beside the value.
The transient from which this suffix command was invoked. The
returned value is a transient-prefix
object, which holds information
associated with the transient prefix command.
The transient from which this suffix command was invoked. The returned value is a symbol, the transient prefix command.
Next: Transient State, Previous: Defining Suffix and Infix Commands, Up: Defining New Commands [Contents][Index]