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:
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.
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
.
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.
This function replaces the suffix or group at LOC in PREFIX with suffix or group SUFFIX.
This function removes the suffix or group at LOC in PREFIX.
This function returns the suffix or group at LOC in PREFIX. The returned value has the form mentioned above.
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.