4 Modifying Existing Transients

To an extend transients can be customized interactively, see Enabling and Disabling Suffixes. This section explains how existing transients can be further modified non-interactively.

The following functions share a few arguments:

• PREFIX is a transient prefix command, a symbol.
• SUFFIX is a transient infix or suffix specification in the same form as expected by define-transient-command. See Suffix Specifications.
• LOC is a command, a key vector or a key description (a string as returned by key-description).

These functions operate on the information stored in the transient--layout property of the PREFIX symbol. Suffix entries in that tree are not objects but have the form (LEVEL CLASS PLIST), where plist should set at least :key, :description and :command.

Function: transient-insert-suffix prefix loc suffix

This function inserts SUFFIX into PREFIX before LOC.

Function: transient-append-suffix prefix loc suffix

This function inserts SUFFIX into PREFIX after LOC.

Function: transient-replace-suffix prefix loc suffix

This function replaces the suffix at LOC in PREFIX with SUFFIX.

Function: transient-remove-suffix prefix loc

This function removes the suffix at LOC in PREFIX.

Function: transient-get-suffix prefix loc

This function returns the suffix at LOC in PREFIX. The returned value has the form mentioned above.

Function: transient-suffix-put prefix loc prop value

This function edits the suffix at LOC in PREFIX, by setting the PROP of its plist to VALUE.

Most of these functions do not signal an error if they cannot perform the requested modification. The functions that insert new suffixes show a warning if LOC cannot be found in PREFIX, without signaling an error. The reason for doing it like this is that establishing a key binding (and that is what we essentially are trying to do here) should not prevent the rest of the configuration to fail also. Among these functions only transient-get-suffix and transient-suffix-put may signal an error.