5.2.2 Suffix Specifications

A transient’s suffix and infix commands are bound when the transient prefix command is defined using define-transient-command, 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.

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 objects value just for the binding inside this transient.

• LEVEL is the suffix level, an integer between 1 and 7. See Enabling and Disabling Suffixes.
• KEY is the key binding, either a vector or key description string.
• DESCRIPTION is the description, either a string or a function that return a string. The function should to be a lambda expression to avoid ambiguity. In some cases a symbol that is bound as a function would also work but to be safe you should use :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.

• COMMAND is a symbol that is bound as a function, which has to be a command. Any command will do; it does not need to have an object associated with it (as would be the case if define-suffix-command or define-infix-command were used to define it).

  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.

• The mandatory argument can also be an command-line argument, a string. In that case an anonymous command is defined and bound.

  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 the long argument (which can also be specified using :argument).

  Only the long argument is displayed in the echo area. 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.