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. Let’s begin with an example:

emacs-lisp
(transient-append-suffix 'magit-patch-apply "-3"
  '("-R" "Apply in reverse" "--reverse"))

This inserts a new infix argument to toggle the --reverse argument after the infix argument that toggles -3 in magit-patch-apply.

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 &optional keep-other ​

Function: transient-append-suffix prefix loc suffix &optional keep-other ​

These functions insert the suffix or group SUFFIX into PREFIX before or after LOC.

Conceptually adding a binding to a transient prefix is similar to adding a binding to a keymap, but this is complicated by the fact that multiple suffix commands can be bound to the same key, provided they are never active at the same time, see Predicate Slots.

Unfortunately both false-positives and false-negatives are possible. To deal with the former use non-nil KEEP-OTHER. To deal with the latter remove the conflicting binding explicitly.

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.