README.org (3405B)
1 * Transient commands 2 3 Taking inspiration from prefix keys and prefix arguments, Transient 4 implements a similar abstraction involving a prefix command, infix 5 arguments and suffix commands. We could call this abstraction a 6 "transient command", but because it always involves at least two 7 commands (a prefix and a suffix) we prefer to call it just a 8 "transient". 9 10 #+begin_quote 11 Transient keymaps are a feature provided by Emacs. Transients as 12 implemented by this package involve the use of transient keymaps. 13 14 Emacs provides a feature that it calls "prefix commands". When we 15 talk about "prefix commands" in Transient's documentation, then we 16 mean our own kind of "prefix commands", unless specified otherwise. 17 To avoid ambiguity we sometimes use the terms "transient prefix 18 command" for our kind and "regular prefix command" for Emacs' kind. 19 #+end_quote 20 21 When the user calls a transient prefix command, then a transient 22 (temporary) keymap is activated, which binds the transient's infix and 23 suffix commands, and functions that control the transient state are 24 added to ~pre-command-hook~ and ~post-command-hook~. The available 25 suffix and infix commands and their state are shown in a popup buffer 26 until the transient is exited by invoking a suffix command. 27 28 Calling an infix command causes its value to be changed. How that is 29 done depends on the type of the infix command. The simplest case is 30 an infix command that represents a command-line argument that does not 31 take a value. Invoking such an infix command causes the switch to be 32 toggled on or off. More complex infix commands may read a value from 33 the user, using the minibuffer. 34 35 Calling a suffix command usually causes the transient to be exited; 36 the transient keymaps and hook functions are removed, the popup buffer 37 no longer shows information about the (no longer bound) suffix 38 commands, the values of some public global variables are set, while 39 some internal global variables are unset, and finally the command is 40 actually called. Suffix commands can also be configured to not exit 41 the transient. 42 43 A suffix command can, but does not have to, use the infix arguments in 44 much the same way it can choose to use or ignore the prefix arguments. 45 For a suffix command that was invoked from a transient the variable 46 ~transient-current-suffixes~ and the function ~transient-args~ serve about 47 the same purpose as the variables ~prefix-arg~ and ~current-prefix-arg~ do 48 for any command that was called after the prefix arguments have been 49 set using a command such as ~universal-argument~. 50 51 [[http://readme.emacsair.me/transient.png]] 52 53 #+html: <br><br> 54 #+html: <a href="https://github.com/magit/transient/actions/workflows/compile.yml"><img alt="Compile" src="https://github.com/magit/transient/actions/workflows/compile.yml/badge.svg"/></a> 55 #+html: <a href="https://github.com/magit/transient/actions/workflows/manual.yml"><img alt="Manual" src="https://github.com/magit/transient/actions/workflows/manual.yml/badge.svg"/></a> 56 #+html: <a href="https://elpa.gnu.org/packages/transient.html"><img alt="GNU ELPA" src="https://elpa.gnu.org/packages/transient.svg"/></a> 57 #+html: <a href="https://stable.melpa.org/#/transient"><img alt="MELPA Stable" src="https://stable.melpa.org/packages/transient-badge.svg"/></a> 58 #+html: <a href="https://melpa.org/#/transient"><img alt="MELPA" src="https://melpa.org/packages/transient-badge.svg"/></a>