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 is bound to -3 in magit-patch-apply.

The following functions share a few arguments:

• PREFIX is a transient prefix command, a symbol.

  PREFIX may also by a symbol identifying a separately defined group, which can be included in multiple prefixes. See TODO.

• 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 key description (a string as returned by key-description and understood by kbd), a command, a symbol identifying an included group, or a vector specifying coordinates. For example, [1 0 -1] identifies the last suffix (-1) of the first subgroup (0) of the second group (1).

  If LOC is a vector, then it can be used to identify a group, not just an individual suffix command. The last element in a vector may also be a symbol or key, in which case the preceding elements must match a group and the last element is looked up within that group.

  The function transient-get-suffix can be useful to determine whether a certain coordinate vector identifies the suffix or group that you expect it to identify. In hairy cases it may be necessary to look at the internal layout representation, which you can access using the function transient--get-layout.

These functions operate on the information stored in the transient--layout property of the PREFIX symbol. Elements in that tree are not objects but have the form (CLASS PLIST) for suffixes and [CLASS PLIST CHILDREN] for groups. At the root of the tree is an element [N nil CHILDREN], where N is the version of the layout format, currently and hopefully for a long time 2. While that element looks like a group vector, that element does not count when identifying a group using a coordinate vector, i.e., [0] is its first child, not the root element itself.

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. The symbol always prevents the removal of a false-positive, in some cases where other non-nil values would fail. To deal with false-negatives remove the conflicting binding separately, using transient-remove-suffix.

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.

Some prefix commands share suffixes, which are separately and then included in each prefix when it is defined. The inclusion is done by reference, the included suffix groups are not inlined by default. So if you change, for example, the key binding for an argument in magit-diff (d) the same change also applies to magit-diff-refresh (D). In the rare case that this is not desirable use transient-inline-group before making changes to included suffixes.

Function: transient-inline-group PREFIX GROUP ¶

This function inlines the included GROUP into PREFIX, by replacing the symbol GROUP with its expanded layout in the layout of PREFIX.

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 signal an error by default. If you really want the insert functions to also signal an error, set transient-error-on-insert-failure to t.