A transient’s suffix and infix commands are bound when the transient
prefix command is defined using transient-define-prefix
, see
Defining Transients. The commands are organized into groups, see
Group Specifications. Here we describe the form used to bind an
individual suffix command.
The same form is also used when later binding additional commands
using functions such as transient-insert-suffix
, see Modifying Existing Transients.
Note that an infix is a special kind of suffix. Depending on context “suffixes” means “suffixes (including infixes)” or “non-infix suffixes”. Here it means the former.
Suffix specifications have this form:
([LEVEL] [KEY [DESCRIPTION]] COMMAND|ARGUMENT [KEYWORD VALUE]...)
LEVEL, KEY and DESCRIPTION can also be specified using the KEYWORDs
:level
, :key
and :description
. If the object that is associated with
COMMAND sets these properties, then they do not have to be specified
here. You can however specify them here anyway, possibly overriding
the object’s values just for the binding inside this transient.
:description
in that
case.
The next element is either a command or an argument. This is the only argument that is mandatory in all cases.
Any command will do; it does not need to have an object associated
with it (as would be the case if transient-define-suffix
or
transient-define-infix
were used to define it).
COMMAND can also be a lambda
expression.
As mentioned above, the object that is associated with a command can be used to set the default for certain values that otherwise have to be set in the suffix specification. Therefore if there is no object, then you have to make sure to specify the KEY and the DESCRIPTION.
As a special case, if you want to add a command that might be neither defined nor autoloaded, you can use a workaround like:
(transient-insert-suffix 'some-prefix "k" '("!" "Ceci n'est pas une commande" no-command :if (lambda () (featurep 'no-library))))
Instead of featurep
you could also use require
with a non-nil
value
for NOERROR.
Instead of a string, this can also be a list of two strings, in
which case the first string is used as the short argument (which can
also be specified using :shortarg
) and the second as the long argument
(which can also be specified using :argument
).
Only the long argument is displayed in the popup buffer. See
transient-detect-key-conflicts
for how the short argument may be
used.
Unless the class is specified explicitly, the appropriate class is
guessed based on the long argument. If the argument ends with ‘=’
(e.g., ‘--format=’) then transient-option
is used, otherwise
transient-switch
.
Finally, details can be specified using optional KEYWORD-VALUE pairs.
Each keyword has to be a keyword symbol, either :class
or a keyword
argument supported by the constructor of that class. See Suffix Slots.