5.5 Transient State

Invoking a transient prefix command "activates" the respective transient, i.e. it puts a transient keymap into effect, which binds the transient’s infix and suffix commands.

The default behavior while a transient is active is as follows:

• Invoking an infix command does not affect the transient state; the transient remains active.
• Invoking a (non-infix) suffix command "deactivates" the transient state by removing the transient keymap and performing some additional cleanup.
• Invoking a command that is bound in a keymap other than the transient keymap is disallowed and trying to do so results in a warning. This does not "deactivate" the transient.

But these are just the defaults. Whether a certain command deactivates or "exits" the transient is configurable. There is more than one way in which a command can be "transient" or "non-transient"; the exact behavior is implemented by calling a so-called "pre-command" function. Whether non-suffix commands are allowed to be called is configurable per transient.

• The transient-ness of suffix commands (including infix commands) is controlled by the value of their transient slot, which can be set either when defining the command or when adding a binding to a transient while defining the respective transient prefix command.

  Valid values are booleans and the pre-commands described below.

  • t is equivalent to transient--do-stay.
  • nil is equivalent to transient--do-exit.
  • If transient is unbound (and that is actually the default for non-infix suffixes) then the value of the prefix’s transient-suffix slot is used instead. The default value of that slot is nil, so the suffix’s transient slot being unbound is essentially equivalent to it being nil.
• A suffix command can be a prefix command itself, i.e. a "sub-prefix". While a sub-prefix is active we nearly always want C-g to take the user back to the "super-prefix". However in rare cases this may not be desirable, and that makes the following complication necessary:

  For transient-suffix objects the transient slot is unbound. We can ignore that for the most part because, as stated above, nil and the slot being unbound are equivalent, and means "do exit". That isn’t actually true for suffixes that are sub-prefixes though. For such suffixes unbound means "do exit but allow going back", which is the default, while nil means "do exit permanently", which requires that slot to be explicitly set to that value.

• The transient-ness of certain built-in suffix commands is specified using transient-predicate-map. This is a special keymap, which binds commands to pre-commands (as opposed to keys to commands) and takes precedence over the transient slot.

The available pre-command functions are documented below. They are called by transient--pre-command, a function on pre-command-hook and the value that they return determines whether the transient is exited. To do so the value of one of the constants transient--exit or transient--stay is used (that way we don’t have to remember if t means "exit" or "stay").

Additionally these functions may change the value of this-command (which explains why they have to be called using pre-command-hook), call transient-export, transient--stack-zap or transient--stack-push; and set the values of transient--exitp, transient--helpp or transient--editp.

5.5.1 Pre-commands for Infixes

The default for infixes is transient--do-stay. This is also the only function that makes sense for infixes.

Function: transient--do-stay

Call the command without exporting variables and stay transient.

5.5.2 Pre-commands for Suffixes

The default for suffixes is transient--do-exit.

Function: transient--do-exit

Call the command after exporting variables and exit the transient.

Function: transient--do-call

Call the command after exporting variables and stay transient.

Function: transient--do-replace

Call the transient prefix command, replacing the active transient.

This is used for suffix that are prefixes themselves, i.e. for sub-prefixes.

5.5.3 Pre-commands for Non-Suffixes

The default for non-suffixes, i.e commands that are bound in other keymaps beside the transient keymap, is transient--do-warn. Silently ignoring the user-error is also an option, though probably not a good one.

If you want to let the user invoke non-suffix commands, then use transient--do-stay as the value of the prefix’s transient-non-suffix slot.

Function: transient--do-warn

Call transient-undefined and stay transient.

Function: transient--do-noop

Call transient-noop and stay transient.

5.5.4 Special Pre-Commands

Function: transient--do-quit-one

If active, quit help or edit mode, else exit the active transient.

This is used when the user pressed C-g.

Function: transient--do-quit-all

Exit all transients without saving the transient stack.

This is used when the user pressed C-q.

Function: transient--do-suspend

Suspend the active transient, saving the transient stack.

This is used when the user pressed C-z.