A transient consists of a prefix command and at least one suffix command, though usually a transient has several infix and suffix commands. The below macro defines the transient prefix command and binds the transient’s infix and suffix commands. In other words, it defines the complete transient, not just the transient prefix command that is used to invoke that transient.
This macro defines NAME as a transient prefix command and binds the transient’s infix and suffix commands.
ARGLIST are the arguments that the prefix command takes. DOCSTRING is the documentation string and is optional.
These arguments can optionally be followed by keyword-value pairs.
Each key has to be a keyword symbol, either
:class or a keyword
argument supported by the constructor of that class. The
transient-prefix class is used if the class is not specified
GROUPs add key bindings for infix and suffix commands and specify how these bindings are presented in the popup buffer. At least one GROUP has to be specified. See Binding Suffix and Infix Commands.
The BODY is optional. If it is omitted, then ARGLIST is ignored and the function definition becomes:
(lambda () (interactive) (transient-setup 'NAME))
If BODY is specified, then it must begin with an
that matches ARGLIST, and it must call
transient-setup. It may,
however, call that function only when some condition is satisfied.
All transients have a (possibly
nil) value, which is exported when
suffix commands are called, so that they can consume that value.
For some transients it might be necessary to have a sort of
secondary value, called a “scope”. Such a scope would usually be
set in the command’s
interactive form and has to be passed to the
(transient-setup 'NAME nil nil :scope SCOPE)
For example, the scope of the
magit-branch-configure transient is
the branch whose variables are being configured.