3 Modifying Existing Transients

To an extent 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 transient-define-prefix. 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. See Suffix Specifications.

  SUFFIX may also be a group in the same form as expected by transient-define-prefix. See Group Specifications.

• LOC is a command, a key vector, a key description (a string as returned by key-description), or a list specifying coordinates (the last element may also be a command or key). For example (1 0 -1) identifies the last suffix (-1) of the first subgroup (0) of the second group (1).

  If LOC is a list of coordinates, then it can be used to identify a group, not just an individual suffix command.

  The function transient-get-suffix can be useful to determine whether a certain coordination list identifies the suffix or group that you expect it to identify. In hairy cases it may be necessary to look at the definition of the transient prefix command.

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 or group SUFFIX into PREFIX before LOC.

Function: transient-append-suffix prefix loc suffix

This function inserts suffix or group SUFFIX into PREFIX after LOC.

Function: transient-replace-suffix prefix loc suffix

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

Function: transient-remove-suffix prefix loc

This function removes the suffix or group at LOC in PREFIX.

Function: transient-get-suffix prefix loc

This function returns the suffix or group 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 or group 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 from loading. Among these functions only transient-get-suffix and transient-suffix-put may signal an error.