Next: , Previous: , Up: Transient User and Developer Manual   [Contents][Index]

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

(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:

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.

Next: Defining New Commands, Previous: Usage, Up: Transient User and Developer Manual   [Contents][Index]