dotemacs

My Emacs configuration
git clone git://git.entf.net/dotemacs
Log | Files | Refs | LICENSE

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>