2649 lines
116 KiB
Plaintext
2649 lines
116 KiB
Plaintext
|
This is transient.info, produced by makeinfo version 6.7 from
|
|||
|
|
transient.texi.
|
|||
|
|
|
|||
|
|
Copyright (C) 2018-2022 Jonas Bernoulli <jonas@bernoul.li>
|
|||
|
|
|
|||
|
|
You can redistribute this document and/or modify it under the terms
|
|||
|
|
of the GNU General Public License as published by the Free Software
|
|||
|
|
Foundation, either version 3 of the License, or (at your option)
|
|||
|
|
any later version.
|
|||
|
|
|
|||
|
|
This document is distributed in the hope that it will be useful,
|
|||
|
|
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|||
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|||
|
|
General Public License for more details.
|
|||
|
|
|
|||
|
|
INFO-DIR-SECTION Emacs
|
|||
|
|
START-INFO-DIR-ENTRY
|
|||
|
|
* Transient: (transient). Transient Commands.
|
|||
|
|
END-INFO-DIR-ENTRY
|
|||
|
|
|
|||
|
|
|
|||
|
|
File: transient.info, Node: Top, Next: Introduction, Up: (dir)
|
|||
|
|
|
|||
|
|
Transient User and Developer Manual
|
|||
|
|
***********************************
|
|||
|
|
|
|||
|
|
Taking inspiration from prefix keys and prefix arguments, Transient
|
|||
|
|
implements a similar abstraction involving a prefix command, infix
|
|||
|
|
arguments and suffix commands. We could call this abstraction a
|
|||
|
|
"transient command", but because it always involves at least two
|
|||
|
|
commands (a prefix and a suffix) we prefer to call it just a
|
|||
|
|
"transient".
|
|||
|
|
|
|||
|
|
When the user calls a transient prefix command, a transient
|
|||
|
|
(temporary) keymap is activated, which binds the transient’s infix and
|
|||
|
|
suffix commands, and functions that control the transient state are
|
|||
|
|
added to ‘pre-command-hook’ and ‘post-command-hook’. The available
|
|||
|
|
suffix and infix commands and their state are shown in a popup buffer
|
|||
|
|
until the transient is exited by invoking a suffix command.
|
|||
|
|
|
|||
|
|
Calling an infix command causes its value to be changed, possibly by
|
|||
|
|
reading a new value in the minibuffer.
|
|||
|
|
|
|||
|
|
Calling a suffix command usually causes the transient to be exited
|
|||
|
|
but suffix commands can also be configured to not exit the transient.
|
|||
|
|
|
|||
|
|
This manual is for Transient version 0.3.7-git.
|
|||
|
|
|
|||
|
|
Copyright (C) 2018-2022 Jonas Bernoulli <jonas@bernoul.li>
|
|||
|
|
|
|||
|
|
You can redistribute this document and/or modify it under the terms
|
|||
|
|
of the GNU General Public License as published by the Free Software
|
|||
|
|
Foundation, either version 3 of the License, or (at your option)
|
|||
|
|
any later version.
|
|||
|
|
|
|||
|
|
This document is distributed in the hope that it will be useful,
|
|||
|
|
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|||
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|||
|
|
General Public License for more details.
|
|||
|
|
|
|||
|
|
* Menu:
|
|||
|
|
|
|||
|
|
* Introduction::
|
|||
|
|
* Usage::
|
|||
|
|
* Modifying Existing Transients::
|
|||
|
|
* Defining New Commands::
|
|||
|
|
* Classes and Methods::
|
|||
|
|
* Related Abstractions and Packages::
|
|||
|
|
* FAQ::
|
|||
|
|
* Keystroke Index::
|
|||
|
|
* Command and Function Index::
|
|||
|
|
* Variable Index::
|
|||
|
|
* Concept Index::
|
|||
|
|
|
|||
|
|
— The Detailed Node Listing —
|
|||
|
|
|
|||
|
|
Usage
|
|||
|
|
|
|||
|
|
* Invoking Transients::
|
|||
|
|
* Aborting and Resuming Transients::
|
|||
|
|
* Common Suffix Commands::
|
|||
|
|
* Saving Values::
|
|||
|
|
* Using History::
|
|||
|
|
* Getting Help for Suffix Commands::
|
|||
|
|
* Enabling and Disabling Suffixes::
|
|||
|
|
* Other Commands::
|
|||
|
|
* Configuration::
|
|||
|
|
|
|||
|
|
Defining New Commands
|
|||
|
|
|
|||
|
|
* Defining Transients::
|
|||
|
|
* Binding Suffix and Infix Commands::
|
|||
|
|
* Defining Suffix and Infix Commands::
|
|||
|
|
* Using Infix Arguments::
|
|||
|
|
* Transient State::
|
|||
|
|
|
|||
|
|
Binding Suffix and Infix Commands
|
|||
|
|
|
|||
|
|
* Group Specifications::
|
|||
|
|
* Suffix Specifications::
|
|||
|
|
|
|||
|
|
|
|||
|
|
Classes and Methods
|
|||
|
|
|
|||
|
|
* Group Classes::
|
|||
|
|
* Group Methods::
|
|||
|
|
* Prefix Classes::
|
|||
|
|
* Suffix Classes::
|
|||
|
|
* Suffix Methods::
|
|||
|
|
* Prefix Slots::
|
|||
|
|
* Suffix Slots::
|
|||
|
|
* Predicate Slots::
|
|||
|
|
|
|||
|
|
Suffix Methods
|
|||
|
|
|
|||
|
|
* Suffix Value Methods::
|
|||
|
|
* Suffix Format Methods::
|
|||
|
|
|
|||
|
|
|
|||
|
|
Related Abstractions and Packages
|
|||
|
|
|
|||
|
|
* Comparison With Prefix Keys and Prefix Arguments::
|
|||
|
|
* Comparison With Other Packages::
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
File: transient.info, Node: Introduction, Next: Usage, Prev: Top, Up: Top
|
|||
|
|
|
|||
|
|
1 Introduction
|
|||
|
|
**************
|
|||
|
|
|
|||
|
|
Taking inspiration from prefix keys and prefix arguments, Transient
|
|||
|
|
implements a similar abstraction involving a prefix command, infix
|
|||
|
|
arguments and suffix commands. We could call this abstraction a
|
|||
|
|
"transient command", but because it always involves at least two
|
|||
|
|
commands (a prefix and a suffix) we prefer to call it just a
|
|||
|
|
"transient".
|
|||
|
|
|
|||
|
|
Transient keymaps are a feature provided by Emacs. Transients as
|
|||
|
|
implemented by this package involve the use of transient keymaps.
|
|||
|
|
|
|||
|
|
Emacs provides a feature that it calls "prefix commands". When we
|
|||
|
|
talk about "prefix commands" in this manual, then we mean our own
|
|||
|
|
kind of "prefix commands", unless specified otherwise. To avoid
|
|||
|
|
ambiguity we sometimes use the terms "transient prefix command" for
|
|||
|
|
our kind and "regular prefix command" for Emacs’ kind.
|
|||
|
|
|
|||
|
|
When the user calls a transient prefix command, a transient
|
|||
|
|
(temporary) keymap is activated, which binds the transient’s infix and
|
|||
|
|
suffix commands, and functions that control the transient state are
|
|||
|
|
added to ‘pre-command-hook’ and ‘post-command-hook’. The available
|
|||
|
|
suffix and infix commands and their state are shown in a popup buffer
|
|||
|
|
until the transient state is exited by invoking a suffix command.
|
|||
|
|
|
|||
|
|
Calling an infix command causes its value to be changed. How that is
|
|||
|
|
done depends on the type of the infix command. The simplest case is an
|
|||
|
|
infix command that represents a command-line argument that does not take
|
|||
|
|
a value. Invoking such an infix command causes the switch to be toggled
|
|||
|
|
on or off. More complex infix commands may read a value from the user,
|
|||
|
|
using the minibuffer.
|
|||
|
|
|
|||
|
|
Calling a suffix command usually causes the transient to be exited;
|
|||
|
|
the transient keymaps and hook functions are removed, the popup buffer
|
|||
|
|
no longer shows information about the (no longer bound) suffix commands,
|
|||
|
|
the values of some public global variables are set, while some internal
|
|||
|
|
global variables are unset, and finally the command is actually called.
|
|||
|
|
Suffix commands can also be configured to not exit the transient.
|
|||
|
|
|
|||
|
|
A suffix command can, but does not have to, use the infix arguments
|
|||
|
|
in much the same way any command can choose to use or ignore the prefix
|
|||
|
|
arguments. For a suffix command that was invoked from a transient, the
|
|||
|
|
variable ‘transient-current-suffixes’ and the function ‘transient-args’
|
|||
|
|
serve about the same purpose as the variables ‘prefix-arg’ and
|
|||
|
|
‘current-prefix-arg’ do for any command that was called after the prefix
|
|||
|
|
arguments have been set using a command such as ‘universal-argument’.
|
|||
|
|
|
|||
|
|
The information shown in the popup buffer while a transient is active
|
|||
|
|
looks a bit like this:
|
|||
|
|
|
|||
|
|
,-----------------------------------------
|
|||
|
|
|Arguments
|
|||
|
|
| -f Force (--force)
|
|||
|
|
| -a Annotate (--annotate)
|
|||
|
|
|
|
|||
|
|
|Create
|
|||
|
|
| t tag
|
|||
|
|
| r release
|
|||
|
|
`-----------------------------------------
|
|||
|
|
|
|||
|
|
This is a simplified version of ‘magit-tag’. Info manuals do not
|
|||
|
|
support images or colored text, so the above "screenshot" lacks
|
|||
|
|
some information; in practice you would be able to tell whether the
|
|||
|
|
arguments ‘--force’ and ‘--annotate’ are enabled or not based on
|
|||
|
|
their color.
|
|||
|
|
|
|||
|
|
Transient can be used to implement simple "command dispatchers". The
|
|||
|
|
main benefit then is that the user can see all the available commands in
|
|||
|
|
a popup buffer. That is useful by itself because it frees the user from
|
|||
|
|
having to remember all the keys that are valid after a certain prefix
|
|||
|
|
key or command. Magit’s ‘magit-dispatch’ (on ‘C-x M-g’) command is an
|
|||
|
|
example of using Transient to merely implement a command dispatcher.
|
|||
|
|
|
|||
|
|
In addition to that, Transient also allows users to interactively
|
|||
|
|
pass arguments to commands. These arguments can be much more complex
|
|||
|
|
than what is reasonable when using prefix arguments. There is a limit
|
|||
|
|
to how many aspects of a command can be controlled using prefix
|
|||
|
|
arguments. Furthermore, what a certain prefix argument means for
|
|||
|
|
different commands can be completely different, and users have to read
|
|||
|
|
documentation to learn and then commit to memory what a certain prefix
|
|||
|
|
argument means to a certain command.
|
|||
|
|
|
|||
|
|
Transient suffix commands, on the other hand, can accept dozens of
|
|||
|
|
different arguments without the user having to remember anything. When
|
|||
|
|
using Transient, one can call a command with arguments that are just as
|
|||
|
|
complex as when calling the same function non-interactively from Lisp.
|
|||
|
|
|
|||
|
|
Invoking a transient command with arguments is similar to invoking a
|
|||
|
|
command in a shell with command-line completion and history enabled.
|
|||
|
|
One benefit of the Transient interface is that it remembers history not
|
|||
|
|
only on a global level ("this command was invoked using these arguments,
|
|||
|
|
and previously it was invoked using those other arguments"), but also
|
|||
|
|
remembers the values of individual arguments independently. See *note
|
|||
|
|
Using History::.
|
|||
|
|
|
|||
|
|
After a transient prefix command is invoked, ‘C-h <key>’ can be used
|
|||
|
|
to show the documentation for the infix or suffix command that ‘<key>’
|
|||
|
|
is bound to (see *note Getting Help for Suffix Commands::) and infixes
|
|||
|
|
and suffixes can be removed from the transient using ‘C-x l <key>’.
|
|||
|
|
Infixes and suffixes that are disabled by default can be enabled the
|
|||
|
|
same way. See *note Enabling and Disabling Suffixes::.
|
|||
|
|
|
|||
|
|
Transient ships with support for a few different types of specialized
|
|||
|
|
infix commands. A command that sets a command line option, for example,
|
|||
|
|
has different needs than a command that merely toggles a boolean flag.
|
|||
|
|
Additionally, Transient provides abstractions for defining new types,
|
|||
|
|
which the author of Transient did not anticipate (or didn’t get around
|
|||
|
|
to implementing yet).
|
|||
|
|
|
|||
|
|
|
|||
|
|
File: transient.info, Node: Usage, Next: Modifying Existing Transients, Prev: Introduction, Up: Top
|
|||
|
|
|
|||
|
|
2 Usage
|
|||
|
|
*******
|
|||
|
|
|
|||
|
|
* Menu:
|
|||
|
|
|
|||
|
|
* Invoking Transients::
|
|||
|
|
* Aborting and Resuming Transients::
|
|||
|
|
* Common Suffix Commands::
|
|||
|
|
* Saving Values::
|
|||
|
|
* Using History::
|
|||
|
|
* Getting Help for Suffix Commands::
|
|||
|
|
* Enabling and Disabling Suffixes::
|
|||
|
|
* Other Commands::
|
|||
|
|
* Configuration::
|
|||
|
|
|
|||
|
|
|
|||
|
|
File: transient.info, Node: Invoking Transients, Next: Aborting and Resuming Transients, Up: Usage
|
|||
|
|
|
|||
|
|
2.1 Invoking Transients
|
|||
|
|
=======================
|
|||
|
|
|
|||
|
|
A transient prefix command is invoked like any other command by pressing
|
|||
|
|
the key that is bound to that command. The main difference to other
|
|||
|
|
commands is that a transient prefix command activates a transient
|
|||
|
|
keymap, which temporarily binds the transient’s infix and suffix
|
|||
|
|
commands. Bindings from other keymaps may, or may not, be disabled
|
|||
|
|
while the transient state is in effect.
|
|||
|
|
|
|||
|
|
There are two kinds of commands that are available after invoking a
|
|||
|
|
transient prefix command; infix and suffix commands. Infix commands set
|
|||
|
|
some value (which is then shown in a popup buffer), without leaving the
|
|||
|
|
transient. Suffix commands, on the other hand, usually quit the
|
|||
|
|
transient and they may use the values set by the infix commands, i.e.,
|
|||
|
|
the infix *arguments*.
|
|||
|
|
|
|||
|
|
Instead of setting arguments to be used by a suffix command, infix
|
|||
|
|
commands may also set some value by side-effect, e.g., by setting the
|
|||
|
|
value of some variable.
|
|||
|
|
|
|||
|
|
|
|||
|
|
File: transient.info, Node: Aborting and Resuming Transients, Next: Common Suffix Commands, Prev: Invoking Transients, Up: Usage
|
|||
|
|
|
|||
|
|
2.2 Aborting and Resuming Transients
|
|||
|
|
====================================
|
|||
|
|
|
|||
|
|
To quit the transient without invoking a suffix command press ‘C-g’.
|
|||
|
|
|
|||
|
|
Key bindings in transient keymaps may be longer than a single event.
|
|||
|
|
After pressing a valid prefix key, all commands whose bindings do not
|
|||
|
|
begin with that prefix key are temporarily unavailable and grayed out.
|
|||
|
|
To abort the prefix key press ‘C-g’ (which in this case only quits the
|
|||
|
|
prefix key, but not the complete transient).
|
|||
|
|
|
|||
|
|
A transient prefix command can be bound as a suffix of another
|
|||
|
|
transient. Invoking such a suffix replaces the current transient state
|
|||
|
|
with a new transient state, i.e., the available bindings change and the
|
|||
|
|
information displayed in the popup buffer is updated accordingly.
|
|||
|
|
Pressing ‘C-g’ while a nested transient is active only quits the
|
|||
|
|
innermost transient, causing a return to the previous transient.
|
|||
|
|
|
|||
|
|
‘C-q’ or ‘C-z’ on the other hand always exits all transients. If you
|
|||
|
|
use the latter, then you can later resume the stack of transients using
|
|||
|
|
‘M-x transient-resume’.
|
|||
|
|
|
|||
|
|
‘C-g’ (‘transient-quit-seq’)
|
|||
|
|
‘C-g’ (‘transient-quit-one’)
|
|||
|
|
This key quits the currently active incomplete key sequence, if
|
|||
|
|
any, or else the current transient. When quitting the current
|
|||
|
|
transient, it returns to the previous transient, if any.
|
|||
|
|
|
|||
|
|
Transient’s predecessor bound ‘q’ instead of ‘C-g’ to the quit
|
|||
|
|
command. To learn how to get that binding back see
|
|||
|
|
‘transient-bind-q-to-quit’’s doc string.
|
|||
|
|
|
|||
|
|
‘C-q’ (‘transient-quit-all’)
|
|||
|
|
This command quits the currently active incomplete key sequence, if
|
|||
|
|
any, and all transients, including the active transient and all
|
|||
|
|
suspended transients, if any.
|
|||
|
|
|
|||
|
|
‘C-z’ (‘transient-suspend’)
|
|||
|
|
Like ‘transient-quit-all’, this command quits an incomplete key
|
|||
|
|
sequence, if any, and all transients. Additionally, it saves the
|
|||
|
|
stack of transients so that it can easily be resumed (which is
|
|||
|
|
particularly useful if you quickly need to do "something else" and
|
|||
|
|
the stack is deeper than a single transient, and/or you have
|
|||
|
|
already changed the values of some infix arguments).
|
|||
|
|
|
|||
|
|
Note that only a single stack of transients can be saved at a time.
|
|||
|
|
If another stack is already saved, then saving a new stack discards
|
|||
|
|
the previous stack.
|
|||
|
|
|
|||
|
|
‘M-x transient-resume’
|
|||
|
|
This command resumes the previously suspended stack of transients,
|
|||
|
|
if any.
|
|||
|
|
|
|||
|
|
|
|||
|
|
File: transient.info, Node: Common Suffix Commands, Next: Saving Values, Prev: Aborting and Resuming Transients, Up: Usage
|
|||
|
|
|
|||
|
|
2.3 Common Suffix Commands
|
|||
|
|
==========================
|
|||
|
|
|
|||
|
|
A few shared suffix commands are available in all transients. These
|
|||
|
|
suffix commands are not shown in the popup buffer by default.
|
|||
|
|
|
|||
|
|
This includes the aborting commands mentioned in the previous
|
|||
|
|
section, as well as some other commands that are all bound to ‘C-x
|
|||
|
|
<key>’. After ‘C-x’ is pressed, a section featuring all these common
|
|||
|
|
commands is temporarily shown in the popup buffer. After invoking one
|
|||
|
|
of them, the section disappears again. Note however that one of these
|
|||
|
|
commands is described as "Show common permanently"; invoke that if you
|
|||
|
|
want the common commands to always be shown for all transients.
|
|||
|
|
|
|||
|
|
‘C-x t’ (‘transient-toggle-common’)
|
|||
|
|
This command toggles whether the generic commands that are common
|
|||
|
|
to all transients are always displayed or only after typing the
|
|||
|
|
incomplete prefix key sequence ‘C-x’. This only affects the
|
|||
|
|
current Emacs session.
|
|||
|
|
|
|||
|
|
-- User Option: transient-show-common-commands
|
|||
|
|
This option controls whether shared suffix commands are shown
|
|||
|
|
alongside the transient-specific infix and suffix commands. By
|
|||
|
|
default, the shared commands are not shown to avoid overwhelming
|
|||
|
|
the user with to. many options.
|
|||
|
|
|
|||
|
|
While a transient is active, pressing ‘C-x’ always shows the common
|
|||
|
|
commands. The value of this option can be changed for the current
|
|||
|
|
Emacs session by typing ‘C-x t’ while a transient is active.
|
|||
|
|
|
|||
|
|
The other common commands are described in either the previous or in
|
|||
|
|
one of the following sections.
|
|||
|
|
|
|||
|
|
Some of Transient’s key bindings differ from the respective bindings
|
|||
|
|
of Magit-Popup; see *note FAQ:: for more information.
|
|||
|
|
|
|||
|
|
|
|||
|
|
File: transient.info, Node: Saving Values, Next: Using History, Prev: Common Suffix Commands, Up: Usage
|
|||
|
|
|
|||
|
|
2.4 Saving Values
|
|||
|
|
=================
|
|||
|
|
|
|||
|
|
After setting the infix arguments in a transient, the user can save
|
|||
|
|
those arguments for future invocations.
|
|||
|
|
|
|||
|
|
Most transients will start out with the saved arguments when they are
|
|||
|
|
invoked. There are a few exceptions, though. Some transients are
|
|||
|
|
designed so that the value that they use is stored externally as the
|
|||
|
|
buffer-local value of some variable. Invoking such a transient again
|
|||
|
|
uses the buffer-local value. (1)
|
|||
|
|
|
|||
|
|
If the user does not save the value and just exits using a regular
|
|||
|
|
suffix command, then the value is merely saved to the transient’s
|
|||
|
|
history. That value won’t be used when the transient is next invoked,
|
|||
|
|
but it is easily accessible (see *note Using History::).
|
|||
|
|
|
|||
|
|
‘C-x s’ (‘transient-set’)
|
|||
|
|
This command saves the value of the active transient for this Emacs
|
|||
|
|
session.
|
|||
|
|
|
|||
|
|
‘C-x C-s’ (‘transient-save’)
|
|||
|
|
Save the value of the active transient persistently across Emacs
|
|||
|
|
sessions.
|
|||
|
|
|
|||
|
|
‘C-x C-k’ (‘transient-save’)
|
|||
|
|
Clear the set and saved value of the active transient.
|
|||
|
|
|
|||
|
|
-- User Option: transient-values-file
|
|||
|
|
This option names the file that is used to persist the values of
|
|||
|
|
transients between Emacs sessions.
|
|||
|
|
|
|||
|
|
---------- Footnotes ----------
|
|||
|
|
|
|||
|
|
(1) ‘magit-diff’ and ‘magit-log’ are two prominent examples, and
|
|||
|
|
their handling of buffer-local values is actually a bit more complicated
|
|||
|
|
than outlined above and even customizable.
|
|||
|
|
|
|||
|
|
|
|||
|
|
File: transient.info, Node: Using History, Next: Getting Help for Suffix Commands, Prev: Saving Values, Up: Usage
|
|||
|
|
|
|||
|
|
2.5 Using History
|
|||
|
|
=================
|
|||
|
|
|
|||
|
|
Every time the user invokes a suffix command the transient’s current
|
|||
|
|
value is saved to its history. These values can be cycled through the
|
|||
|
|
same way one can cycle through the history of commands that read
|
|||
|
|
user-input in the minibuffer.
|
|||
|
|
|
|||
|
|
‘C-M-p’ (‘transient-history-prev’)
|
|||
|
|
‘C-x p’
|
|||
|
|
This command switches to the previous value used for the active
|
|||
|
|
transient.
|
|||
|
|
|
|||
|
|
‘C-M-n’ (‘transient-history-next’)
|
|||
|
|
‘C-x n’
|
|||
|
|
This command switches to the next value used for the active
|
|||
|
|
transient.
|
|||
|
|
|
|||
|
|
In addition to the transient-wide history, Transient of course
|
|||
|
|
supports per-infix history. When an infix reads user-input using the
|
|||
|
|
minibuffer, the user can use the regular minibuffer history commands to
|
|||
|
|
cycle through previously used values. Usually the same keys as those
|
|||
|
|
mentioned above are bound to those commands.
|
|||
|
|
|
|||
|
|
Authors of transients should arrange for different infix commands
|
|||
|
|
that read the same kind of value to also use the same history key (see
|
|||
|
|
*note Suffix Slots::).
|
|||
|
|
|
|||
|
|
Both kinds of history are saved to a file when Emacs is exited.
|
|||
|
|
|
|||
|
|
-- User Option: transient-history-file
|
|||
|
|
This option names the file that is used to persist the history of
|
|||
|
|
transients and their infixes between Emacs sessions.
|
|||
|
|
|
|||
|
|
-- User Option: transient-history-limit
|
|||
|
|
This option controls how many history elements are kept at the time
|
|||
|
|
the history is saved in ‘transient-history-file’.
|
|||
|
|
|
|||
|
|
|
|||
|
|
File: transient.info, Node: Getting Help for Suffix Commands, Next: Enabling and Disabling Suffixes, Prev: Using History, Up: Usage
|
|||
|
|
|
|||
|
|
2.6 Getting Help for Suffix Commands
|
|||
|
|
====================================
|
|||
|
|
|
|||
|
|
Transients can have many suffixes and infixes that the user might not be
|
|||
|
|
familiar with. To make it trivial to get help for these, Transient
|
|||
|
|
provides access to the documentation directly from the active transient.
|
|||
|
|
|
|||
|
|
‘C-h’ (‘transient-help’)
|
|||
|
|
This command enters help mode. When help mode is active, typing a
|
|||
|
|
key shows information about the suffix command that the key
|
|||
|
|
normally is bound to (instead of invoking it). Pressing ‘C-h’ a
|
|||
|
|
second time shows information about the _prefix_ command.
|
|||
|
|
|
|||
|
|
After typing a key, the stack of transient states is suspended and
|
|||
|
|
information about the suffix command is shown instead. Typing ‘q’
|
|||
|
|
in the help buffer buries that buffer and resumes the transient
|
|||
|
|
state.
|
|||
|
|
|
|||
|
|
What sort of documentation is shown depends on how the transient was
|
|||
|
|
defined. For infix commands that represent command-line arguments this
|
|||
|
|
ideally shows the appropriate manpage. ‘transient-help’ then tries to
|
|||
|
|
jump to the correct location within that. Info manuals are also
|
|||
|
|
supported. The fallback is to show the command’s doc string, for
|
|||
|
|
non-infix suffixes this is usually appropriate.
|
|||
|
|
|
|||
|
|
|
|||
|
|
File: transient.info, Node: Enabling and Disabling Suffixes, Next: Other Commands, Prev: Getting Help for Suffix Commands, Up: Usage
|
|||
|
|
|
|||
|
|
2.7 Enabling and Disabling Suffixes
|
|||
|
|
===================================
|
|||
|
|
|
|||
|
|
The user base of a package that uses transients can be very diverse.
|
|||
|
|
This is certainly the case for Magit; some users have been using it and
|
|||
|
|
Git for a decade, while others are just getting started now.
|
|||
|
|
|
|||
|
|
For that reason a mechanism is needed that authors can use to
|
|||
|
|
classify a transient’s infixes and suffixes along the
|
|||
|
|
essentials...everything spectrum. We use the term "levels" to describe
|
|||
|
|
that mechanism.
|
|||
|
|
|
|||
|
|
Each suffix command is placed on a level and each transient has a
|
|||
|
|
level (called transient-level), which controls which suffix commands are
|
|||
|
|
available. Integers between 1 and 7 (inclusive) are valid levels. For
|
|||
|
|
suffixes, 0 is also valid; it means that the suffix is not displayed at
|
|||
|
|
any level.
|
|||
|
|
|
|||
|
|
The levels of individual transients and/or their individual suffixes
|
|||
|
|
can be changed interactively, by invoking the transient and then
|
|||
|
|
pressing ‘C-x l’ to enter the "edit" mode, see below.
|
|||
|
|
|
|||
|
|
The default level for both transients and their suffixes is 4. The
|
|||
|
|
‘transient-default-level’ option only controls the default for
|
|||
|
|
transients. The default suffix level is always 4. The authors of
|
|||
|
|
transients should place certain suffixes on a higher level, if they
|
|||
|
|
expect that it won’t be of use to most users, and they should place very
|
|||
|
|
important suffixes on a lower level, so that they remain available even
|
|||
|
|
if the user lowers the transient level.
|
|||
|
|
|
|||
|
|
-- User Option: transient-default-level
|
|||
|
|
This option controls which suffix levels are made available by
|
|||
|
|
default. It sets the transient-level for transients for which the
|
|||
|
|
user has not set that individually.
|
|||
|
|
|
|||
|
|
-- User Option: transient-levels-file
|
|||
|
|
This option names the file that is used to persist the levels of
|
|||
|
|
transients and their suffixes between Emacs sessions.
|
|||
|
|
|
|||
|
|
‘C-x l’ (‘transient-set-level’)
|
|||
|
|
This command enters edit mode. When edit mode is active, then all
|
|||
|
|
infixes and suffixes that are currently usable are displayed along
|
|||
|
|
with their levels. The colors of the levels indicate whether they
|
|||
|
|
are enabled or not. The level of the transient is also displayed
|
|||
|
|
along with some usage information.
|
|||
|
|
|
|||
|
|
In edit mode, pressing the key that would usually invoke a certain
|
|||
|
|
suffix instead prompts the user for the level that suffix should be
|
|||
|
|
placed on.
|
|||
|
|
|
|||
|
|
Help mode is available in edit mode.
|
|||
|
|
|
|||
|
|
To change the transient level press ‘C-x l’ again.
|
|||
|
|
|
|||
|
|
To exit edit mode press ‘C-g’.
|
|||
|
|
|
|||
|
|
Note that edit mode does not display any suffixes that are not
|
|||
|
|
currently usable. ‘magit-rebase’, for example, shows different
|
|||
|
|
suffixes depending on whether a rebase is already in progress or
|
|||
|
|
not. The predicates also apply in edit mode.
|
|||
|
|
|
|||
|
|
Therefore, to control which suffixes are available given a certain
|
|||
|
|
state, you have to make sure that that state is currently active.
|
|||
|
|
|
|||
|
|
|
|||
|
|
File: transient.info, Node: Other Commands, Next: Configuration, Prev: Enabling and Disabling Suffixes, Up: Usage
|
|||
|
|
|
|||
|
|
2.8 Other Commands
|
|||
|
|
==================
|
|||
|
|
|
|||
|
|
When invoking a transient in a small frame, the transient window may not
|
|||
|
|
show the complete buffer, making it necessary to scroll, using the
|
|||
|
|
following commands. These commands are never shown in the transient
|
|||
|
|
window, and the key bindings are the same as for ‘scroll-up-command’ and
|
|||
|
|
‘scroll-down-command’ in other buffers.
|
|||
|
|
|
|||
|
|
-- Command: transient-scroll-up arg
|
|||
|
|
This command scrolls text of transient popup window upward ARG
|
|||
|
|
lines. If ARG is ‘nil’, then it scrolls near full screen. This is
|
|||
|
|
a wrapper around ‘scroll-up-command’ (which see).
|
|||
|
|
|
|||
|
|
-- Command: transient-scroll-down arg
|
|||
|
|
This command scrolls text of transient popup window down ARG lines.
|
|||
|
|
If ARG is ‘nil’, then it scrolls near full screen. This is a
|
|||
|
|
wrapper around ‘scroll-down-command’ (which see).
|
|||
|
|
|
|||
|
|
|
|||
|
|
File: transient.info, Node: Configuration, Prev: Other Commands, Up: Usage
|
|||
|
|
|
|||
|
|
2.9 Configuration
|
|||
|
|
=================
|
|||
|
|
|
|||
|
|
More options are described in *note Common Suffix Commands::, in *note
|
|||
|
|
Saving Values::, in *note Using History:: and in *note Enabling and
|
|||
|
|
Disabling Suffixes::.
|
|||
|
|
|
|||
|
|
Essential Options
|
|||
|
|
-----------------
|
|||
|
|
|
|||
|
|
Also see *note Common Suffix Commands::.
|
|||
|
|
|
|||
|
|
-- User Option: transient-show-popup
|
|||
|
|
This option controls whether the current transient’s infix and
|
|||
|
|
suffix commands are shown in the popup buffer.
|
|||
|
|
|
|||
|
|
• If ‘t’ (the default) then the popup buffer is shown as soon as
|
|||
|
|
a transient prefix command is invoked.
|
|||
|
|
|
|||
|
|
• If ‘nil’, then the popup buffer is not shown unless the user
|
|||
|
|
explicitly requests it, by pressing an incomplete prefix key
|
|||
|
|
sequence.
|
|||
|
|
|
|||
|
|
• If a number, then the a brief one-line summary is shown
|
|||
|
|
instead of the popup buffer. If zero or negative, then not
|
|||
|
|
even that summary is shown; only the pressed key itself is
|
|||
|
|
shown.
|
|||
|
|
|
|||
|
|
The popup is shown when the user explicitly requests it by
|
|||
|
|
pressing an incomplete prefix key sequence. Unless this is
|
|||
|
|
zero, the popup is shown after that many seconds of inactivity
|
|||
|
|
(using the absolute value).
|
|||
|
|
|
|||
|
|
-- User Option: transient-enable-popup-navigation
|
|||
|
|
This option controls whether navigation commands are enabled in the
|
|||
|
|
transient popup buffer.
|
|||
|
|
|
|||
|
|
While a transient is active the transient popup buffer is not the
|
|||
|
|
current buffer, making it necessary to use dedicated commands to
|
|||
|
|
act on that buffer itself. This is disabled by default. If this
|
|||
|
|
option is non-‘nil’, then the following features are available:
|
|||
|
|
|
|||
|
|
• ‘<up>’ moves the cursor to the previous suffix. ‘<down>’
|
|||
|
|
moves the cursor to the next suffix. ‘RET’ invokes the suffix
|
|||
|
|
the cursor is on.
|
|||
|
|
• ‘<mouse-1>’ invokes the clicked on suffix.
|
|||
|
|
• ‘C-s’ and ‘C-r’ start isearch in the popup buffer.
|
|||
|
|
|
|||
|
|
-- User Option: transient-display-buffer-action
|
|||
|
|
This option specifies the action used to display the transient
|
|||
|
|
popup buffer. The transient popup buffer is displayed in a window
|
|||
|
|
using ‘(display-buffer BUFFER transient-display-buffer-action)’.
|
|||
|
|
|
|||
|
|
The value of this option has the form ‘(FUNCTION . ALIST)’, where
|
|||
|
|
FUNCTION is a function or a list of functions. Each such function
|
|||
|
|
should accept two arguments: a buffer to display and an alist of
|
|||
|
|
the same form as ALIST. See *note (elisp)Choosing Window::, for
|
|||
|
|
details.
|
|||
|
|
|
|||
|
|
The default is:
|
|||
|
|
|
|||
|
|
(display-buffer-in-side-window
|
|||
|
|
(side . bottom)
|
|||
|
|
(inhibit-same-window . t)
|
|||
|
|
(window-parameters (no-other-window . t)))
|
|||
|
|
|
|||
|
|
This displays the window at the bottom of the selected frame.
|
|||
|
|
Another useful FUNCTION is ‘display-buffer-below-selected’, which
|
|||
|
|
is what ‘magit-popup’ used by default. For more alternatives see
|
|||
|
|
*note (elisp)Display Action Functions:: and *note (elisp)Buffer
|
|||
|
|
Display Action Alists::.
|
|||
|
|
|
|||
|
|
Note that the buffer that was current before the transient buffer
|
|||
|
|
is shown should remain the current buffer. Many suffix commands
|
|||
|
|
act on the thing at point, if appropriate, and if the transient
|
|||
|
|
buffer became the current buffer, then that would change what is at
|
|||
|
|
point. To that effect ‘inhibit-same-window’ ensures that the
|
|||
|
|
selected window is not used to show the transient buffer.
|
|||
|
|
|
|||
|
|
It may be possible to display the window in another frame, but
|
|||
|
|
whether that works in practice depends on the window-manager. If
|
|||
|
|
the window manager selects the new window (Emacs frame), then that
|
|||
|
|
unfortunately changes which buffer is current.
|
|||
|
|
|
|||
|
|
If you change the value of this option, then you might also want to
|
|||
|
|
change the value of ‘transient-mode-line-format’.
|
|||
|
|
|
|||
|
|
Accessibility Options
|
|||
|
|
---------------------
|
|||
|
|
|
|||
|
|
-- User Option: transient-force-single-column
|
|||
|
|
This option controls whether the use of a single column to display
|
|||
|
|
suffixes is enforced. This might be useful for users with low
|
|||
|
|
vision who use large text and might otherwise have to scroll in two
|
|||
|
|
dimensions.
|
|||
|
|
|
|||
|
|
Auxiliary Options
|
|||
|
|
-----------------
|
|||
|
|
|
|||
|
|
-- User Option: transient-mode-line-format
|
|||
|
|
This option controls whether the transient popup buffer has a
|
|||
|
|
mode-line, separator line, or neither.
|
|||
|
|
|
|||
|
|
If ‘nil’, then the buffer has no mode-line. If the buffer is not
|
|||
|
|
displayed right above the echo area, then this probably is not a
|
|||
|
|
good value.
|
|||
|
|
|
|||
|
|
If ‘line’ (the default), then the buffer also has no mode-line, but
|
|||
|
|
a thin line is drawn instead, using the background color of the
|
|||
|
|
face ‘transient-separator’. Text-mode frames cannot display thin
|
|||
|
|
lines, and therefore fall back to treating ‘line’ like ‘nil’.
|
|||
|
|
|
|||
|
|
Otherwise this can be any mode-line format. See *note (elisp)Mode
|
|||
|
|
Line Format::, for details.
|
|||
|
|
|
|||
|
|
-- User Option: transient-semantic-coloring
|
|||
|
|
This option controls whether prefixes and suffixes are colored in a
|
|||
|
|
Hydra-like fashion.
|
|||
|
|
|
|||
|
|
If non-‘nil’, then the key binding of each suffix is colorized to
|
|||
|
|
indicate whether it exits the transient state or not. The color of
|
|||
|
|
the prefix is indicated using the line that is drawn when the value
|
|||
|
|
of ‘transient-mode-line-format’ is ‘line’.
|
|||
|
|
|
|||
|
|
For more information about how Hydra uses colors see
|
|||
|
|
<https://github.com/abo-abo/hydra#color> and
|
|||
|
|
<https://oremacs.com/2015/02/19/hydra-colors-reloaded>.
|
|||
|
|
|
|||
|
|
-- User Option: transient-highlight-mismatched-keys
|
|||
|
|
This option controls whether key bindings of infix commands that do
|
|||
|
|
not match the respective command-line argument should be
|
|||
|
|
highlighted. For other infix commands this option has no effect.
|
|||
|
|
|
|||
|
|
When this option is non-‘nil’, the key binding for an infix
|
|||
|
|
argument is highlighted when only a long argument (e.g.,
|
|||
|
|
‘--verbose’) is specified but no shorthand (e.g ‘-v’). In the rare
|
|||
|
|
case that a shorthand is specified but the key binding does not
|
|||
|
|
match, then it is highlighted differently.
|
|||
|
|
|
|||
|
|
Highlighting mismatched key bindings is useful when learning the
|
|||
|
|
arguments of the underlying command-line tool; you wouldn’t want to
|
|||
|
|
learn any short-hands that do not actually exist.
|
|||
|
|
|
|||
|
|
The highlighting is done using one of the faces
|
|||
|
|
‘transient-mismatched-key’ and ‘transient-nonstandard-key’.
|
|||
|
|
|
|||
|
|
-- User Option: transient-substitute-key-function
|
|||
|
|
This function is used to modify key bindings. If the value of this
|
|||
|
|
option is nil (the default), then no substitution is performed.
|
|||
|
|
|
|||
|
|
This function is called with one argument, the prefix object, and
|
|||
|
|
must return a key binding description, either the existing key
|
|||
|
|
description it finds in the ‘key’ slot, or the key description that
|
|||
|
|
replaces the prefix key. It could be used to make other
|
|||
|
|
substitutions, but that is discouraged.
|
|||
|
|
|
|||
|
|
For example, ‘=’ is hard to reach using my custom keyboard layout,
|
|||
|
|
so I substitute ‘(’ for that, which is easy to reach using a layout
|
|||
|
|
optimized for lisp.
|
|||
|
|
|
|||
|
|
(setq transient-substitute-key-function
|
|||
|
|
(lambda (obj)
|
|||
|
|
(let ((key (oref obj key)))
|
|||
|
|
(if (string-match "\\`\\(=\\)[a-zA-Z]" key)
|
|||
|
|
(replace-match "(" t t key 1)
|
|||
|
|
key))))
|
|||
|
|
|
|||
|
|
-- User Option: transient-read-with-initial-input
|
|||
|
|
This option controls whether the last history element is used as
|
|||
|
|
the initial minibuffer input when reading the value of an infix
|
|||
|
|
argument from the user. If ‘nil’, there is no initial input and
|
|||
|
|
the first element has to be accessed the same way as the older
|
|||
|
|
elements.
|
|||
|
|
|
|||
|
|
-- User Option: transient-hide-during-minibuffer-read
|
|||
|
|
This option controls whether the transient buffer is hidden while
|
|||
|
|
user input is being read in the minibuffer.
|
|||
|
|
|
|||
|
|
-- User Option: transient-align-variable-pitch
|
|||
|
|
This option controls whether columns are aligned pixel-wise in the
|
|||
|
|
popup buffer.
|
|||
|
|
|
|||
|
|
If this is non-‘nil’, then columns are aligned pixel-wise to
|
|||
|
|
support variable-pitch fonts. Keys are not aligned, so you should
|
|||
|
|
use a fixed-pitch font for the ‘transient-key’ face. Other key
|
|||
|
|
faces inherit from that face unless a theme is used that breaks
|
|||
|
|
that relationship.
|
|||
|
|
|
|||
|
|
This option is intended for users who use a variable-pitch font for
|
|||
|
|
the ‘default’ face.
|
|||
|
|
|
|||
|
|
-- User Option: transient-force-fixed-pitch
|
|||
|
|
This option controls whether to force the use of a monospaced font
|
|||
|
|
in popup buffer. Even if you use a proportional font for the
|
|||
|
|
‘default’ face, you might still want to use a monospaced font in
|
|||
|
|
transient’s popup buffer. Setting this option to ‘t’ causes
|
|||
|
|
‘default’ to be remapped to ‘fixed-pitch’ in that buffer.
|
|||
|
|
|
|||
|
|
Developer Options
|
|||
|
|
-----------------
|
|||
|
|
|
|||
|
|
These options are mainly intended for developers.
|
|||
|
|
|
|||
|
|
-- User Option: transient-detect-key-conflicts
|
|||
|
|
This option controls whether key binding conflicts should be
|
|||
|
|
detected at the time the transient is invoked. If so, this results
|
|||
|
|
in an error, which prevents the transient from being used. Because
|
|||
|
|
of that, conflicts are ignored by default.
|
|||
|
|
|
|||
|
|
Conflicts cannot be determined earlier, i.e., when the transient is
|
|||
|
|
being defined and when new suffixes are being added, because at
|
|||
|
|
that time there can be false-positives. It is actually valid for
|
|||
|
|
multiple suffixes to share a common key binding, provided the
|
|||
|
|
predicates of those suffixes prevent that more than one of them is
|
|||
|
|
enabled at a time.
|
|||
|
|
|
|||
|
|
-- User Option: transient-highlight-higher-levels
|
|||
|
|
This option controls whether suffixes that would not be available
|
|||
|
|
by default are highlighted.
|
|||
|
|
|
|||
|
|
When non-‘nil’ then the descriptions of suffixes are highlighted if
|
|||
|
|
their level is above 4, the default of ‘transient-default-level’.
|
|||
|
|
Assuming you have set that variable to 7, this highlights all
|
|||
|
|
suffixes that won’t be available to users without them making the
|
|||
|
|
same customization.
|
|||
|
|
|
|||
|
|
|
|||
|
|
File: transient.info, Node: Modifying Existing Transients, Next: Defining New Commands, Prev: Usage, Up: Top
|
|||
|
|
|
|||
|
|
3 Modifying Existing Transients
|
|||
|
|
*******************************
|
|||
|
|
|
|||
|
|
To an extent, transients can be customized interactively, see *note
|
|||
|
|
Enabling and Disabling Suffixes::. This section explains how existing
|
|||
|
|
transients can be further modified non-interactively.
|
|||
|
|
|
|||
|
|
The following functions share a few arguments:
|
|||
|
|
|
|||
|
|
• PREFIX is a transient prefix command, a symbol.
|
|||
|
|
|
|||
|
|
• 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 *note Suffix Specifications::.
|
|||
|
|
|
|||
|
|
SUFFIX may also be a group in the same form as expected by
|
|||
|
|
‘transient-define-prefix’. See *note Group Specifications::.
|
|||
|
|
|
|||
|
|
• LOC is a command, a key vector, a key description (a string as
|
|||
|
|
returned by ‘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’.
|
|||
|
|
|
|||
|
|
-- Function: transient-insert-suffix prefix loc suffix
|
|||
|
|
This function inserts suffix or group SUFFIX into PREFIX before
|
|||
|
|
LOC.
|
|||
|
|
|
|||
|
|
-- Function: transient-append-suffix prefix loc suffix
|
|||
|
|
This function inserts suffix or group SUFFIX into PREFIX after LOC.
|
|||
|
|
|
|||
|
|
-- 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.
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
|
|||
|
|
File: transient.info, Node: Defining New Commands, Next: Classes and Methods, Prev: Modifying Existing Transients, Up: Top
|
|||
|
|
|
|||
|
|
4 Defining New Commands
|
|||
|
|
***********************
|
|||
|
|
|
|||
|
|
* Menu:
|
|||
|
|
|
|||
|
|
* Defining Transients::
|
|||
|
|
* Binding Suffix and Infix Commands::
|
|||
|
|
* Defining Suffix and Infix Commands::
|
|||
|
|
* Using Infix Arguments::
|
|||
|
|
* Transient State::
|
|||
|
|
|
|||
|
|
|
|||
|
|
File: transient.info, Node: Defining Transients, Next: Binding Suffix and Infix Commands, Up: Defining New Commands
|
|||
|
|
|
|||
|
|
4.1 Defining Transients
|
|||
|
|
=======================
|
|||
|
|
|
|||
|
|
A transient consists of a prefix command and at least one suffix
|
|||
|
|
command, though usually a transient has several infix and suffix
|
|||
|
|
commands. The below macro defines the transient prefix command *and*
|
|||
|
|
binds the transient’s infix and suffix commands. In other words, it
|
|||
|
|
defines the complete transient, not just the transient prefix command
|
|||
|
|
that is used to invoke that transient.
|
|||
|
|
|
|||
|
|
-- Macro: transient-define-prefix name arglist [docstring] [keyword
|
|||
|
|
value]... group... [body...]
|
|||
|
|
This macro defines NAME as a transient prefix command and binds the
|
|||
|
|
transient’s infix and suffix commands.
|
|||
|
|
|
|||
|
|
ARGLIST are the arguments that the prefix command takes. DOCSTRING
|
|||
|
|
is the documentation string and is optional.
|
|||
|
|
|
|||
|
|
These arguments can optionally be followed by keyword-value pairs.
|
|||
|
|
Each key has to be a keyword symbol, either ‘:class’ or a keyword
|
|||
|
|
argument supported by the constructor of that class. The
|
|||
|
|
‘transient-prefix’ class is used if the class is not specified
|
|||
|
|
explicitly.
|
|||
|
|
|
|||
|
|
GROUPs add key bindings for infix and suffix commands and specify
|
|||
|
|
how these bindings are presented in the popup buffer. At least one
|
|||
|
|
GROUP has to be specified. See *note Binding Suffix and Infix
|
|||
|
|
Commands::.
|
|||
|
|
|
|||
|
|
The BODY is optional. If it is omitted, then ARGLIST is ignored
|
|||
|
|
and the function definition becomes:
|
|||
|
|
|
|||
|
|
(lambda ()
|
|||
|
|
(interactive)
|
|||
|
|
(transient-setup 'NAME))
|
|||
|
|
|
|||
|
|
If BODY is specified, then it must begin with an ‘interactive’ form
|
|||
|
|
that matches ARGLIST, and it must call ‘transient-setup’. It may,
|
|||
|
|
however, call that function only when some condition is satisfied.
|
|||
|
|
|
|||
|
|
All transients have a (possibly ‘nil’) value, which is exported
|
|||
|
|
when suffix commands are called, so that they can consume that
|
|||
|
|
value. For some transients it might be necessary to have a sort of
|
|||
|
|
secondary value, called a "scope". Such a scope would usually be
|
|||
|
|
set in the command’s ‘interactive’ form and has to be passed to the
|
|||
|
|
setup function:
|
|||
|
|
|
|||
|
|
(transient-setup 'NAME nil nil :scope SCOPE)
|
|||
|
|
|
|||
|
|
For example, the scope of the ‘magit-branch-configure’ transient is
|
|||
|
|
the branch whose variables are being configured.
|
|||
|
|
|
|||
|
|
|
|||
|
|
File: transient.info, Node: Binding Suffix and Infix Commands, Next: Defining Suffix and Infix Commands, Prev: Defining Transients, Up: Defining New Commands
|
|||
|
|
|
|||
|
|
4.2 Binding Suffix and Infix Commands
|
|||
|
|
=====================================
|
|||
|
|
|
|||
|
|
The macro ‘transient-define-prefix’ is used to define a transient. This
|
|||
|
|
defines the actual transient prefix command (see *note Defining
|
|||
|
|
Transients::) and adds the transient’s infix and suffix bindings, as
|
|||
|
|
described below.
|
|||
|
|
|
|||
|
|
Users and third-party packages can add additional bindings using
|
|||
|
|
functions such as ‘transient-insert-suffix’ (See *note Modifying
|
|||
|
|
Existing Transients::). These functions take a "suffix specification"
|
|||
|
|
as one of their arguments, which has the same form as the specifications
|
|||
|
|
used in ‘transient-define-prefix’.
|
|||
|
|
|
|||
|
|
* Menu:
|
|||
|
|
|
|||
|
|
* Group Specifications::
|
|||
|
|
* Suffix Specifications::
|
|||
|
|
|
|||
|
|
|
|||
|
|
File: transient.info, Node: Group Specifications, Next: Suffix Specifications, Up: Binding Suffix and Infix Commands
|
|||
|
|
|
|||
|
|
4.2.1 Group Specifications
|
|||
|
|
--------------------------
|
|||
|
|
|
|||
|
|
The suffix and infix commands of a transient are organized in groups.
|
|||
|
|
The grouping controls how the descriptions of the suffixes are outlined
|
|||
|
|
visually but also makes it possible to set certain properties for a set
|
|||
|
|
of suffixes.
|
|||
|
|
|
|||
|
|
Several group classes exist, some of which organize suffixes in
|
|||
|
|
subgroups. In most cases the class does not have to be specified
|
|||
|
|
explicitly, but see *note Group Classes::.
|
|||
|
|
|
|||
|
|
Groups are specified in the call to ‘transient-define-prefix’, using
|
|||
|
|
vectors. Because groups are represented using vectors, we cannot use
|
|||
|
|
square brackets to indicate an optional element and instead use curly
|
|||
|
|
brackets to do the latter.
|
|||
|
|
|
|||
|
|
Group specifications then have this form:
|
|||
|
|
|
|||
|
|
[{LEVEL} {DESCRIPTION} {KEYWORD VALUE}... ELEMENT...]
|
|||
|
|
|
|||
|
|
The LEVEL is optional and defaults to 4. See *note Enabling and
|
|||
|
|
Disabling Suffixes::.
|
|||
|
|
|
|||
|
|
The DESCRIPTION is optional. If present, it is used as the heading
|
|||
|
|
of the group.
|
|||
|
|
|
|||
|
|
The KEYWORD-VALUE pairs are optional. Each keyword has to be a
|
|||
|
|
keyword symbol, either ‘:class’ or a keyword argument supported by the
|
|||
|
|
constructor of that class.
|
|||
|
|
|
|||
|
|
• One of these keywords, ‘:description’, is equivalent to specifying
|
|||
|
|
DESCRIPTION at the very beginning of the vector. The
|
|||
|
|
recommendation is to use ‘:description’ if some other keyword is
|
|||
|
|
also used, for consistency, or DESCRIPTION otherwise, because it
|
|||
|
|
looks better.
|
|||
|
|
|
|||
|
|
• Likewise ‘:level’ is equivalent to LEVEL.
|
|||
|
|
|
|||
|
|
• Other important keywords include the ‘:if...’ keywords. These
|
|||
|
|
keywords control whether the group is available in a certain
|
|||
|
|
situation.
|
|||
|
|
|
|||
|
|
For example, one group of the ‘magit-rebase’ transient uses ‘:if
|
|||
|
|
magit-rebase-in-progress-p’, which contains the suffixes that are
|
|||
|
|
useful while rebase is already in progress; and another that uses
|
|||
|
|
‘:if-not magit-rebase-in-progress-p’, which contains the suffixes
|
|||
|
|
that initiate a rebase.
|
|||
|
|
|
|||
|
|
These predicates can also be used on individual suffixes and are
|
|||
|
|
only documented once, see *note Predicate Slots::.
|
|||
|
|
|
|||
|
|
• The value of ‘:hide’, if non-‘nil’, is a predicate that controls
|
|||
|
|
whether the group is hidden by default. The key bindings for
|
|||
|
|
suffixes of a hidden group should all use the same prefix key.
|
|||
|
|
Pressing that prefix key should temporarily show the group and its
|
|||
|
|
suffixes, which assumes that a predicate like this is used:
|
|||
|
|
|
|||
|
|
(lambda ()
|
|||
|
|
(eq (car transient--redisplay-key)
|
|||
|
|
?\C-c)) ; the prefix key shared by all bindings
|
|||
|
|
|
|||
|
|
• The value of ‘:setup-children’, if non-‘nil’, is a function that
|
|||
|
|
takes two arguments the group object itself and a list of children.
|
|||
|
|
The children are given as a (potentially empty) list consisting of
|
|||
|
|
either group or suffix specifications. It can make arbitrary
|
|||
|
|
changes to the children including constructing new children from
|
|||
|
|
scratch. Also see ‘transient-setup-children’.
|
|||
|
|
|
|||
|
|
• The boolean ‘:pad-keys’ argument controls whether keys of all
|
|||
|
|
suffixes contained in a group are right padded, effectively
|
|||
|
|
aligning the descriptions.
|
|||
|
|
|
|||
|
|
The ELEMENTs are either all subgroups (vectors), or all suffixes
|
|||
|
|
(lists) and strings. (At least currently no group type exists that
|
|||
|
|
would allow mixing subgroups with commands at the same level, though in
|
|||
|
|
principle there is nothing that prevents that.)
|
|||
|
|
|
|||
|
|
If the ELEMENTs are not subgroups, then they can be a mixture of
|
|||
|
|
lists that specify commands and strings. Strings are inserted verbatim.
|
|||
|
|
The empty string can be used to insert gaps between suffixes, which is
|
|||
|
|
particularly useful if the suffixes are outlined as a table.
|
|||
|
|
|
|||
|
|
Variables are supported inside group specifications. For example in
|
|||
|
|
place of a direct subgroup specification, a variable can be used whose
|
|||
|
|
value is a vector that qualifies as a group specification. Likewise, a
|
|||
|
|
variable can be used where a suffix specification is expected. Lists of
|
|||
|
|
group or suffix specifications are also supported. Indirect
|
|||
|
|
specifications are resolved when the transient prefix is being defined.
|
|||
|
|
|
|||
|
|
The form of suffix specifications is documented in the next node.
|
|||
|
|
|
|||
|
|
|
|||
|
|
File: transient.info, Node: Suffix Specifications, Prev: Group Specifications, Up: Binding Suffix and Infix Commands
|
|||
|
|
|
|||
|
|
4.2.2 Suffix Specifications
|
|||
|
|
---------------------------
|
|||
|
|
|
|||
|
|
A transient’s suffix and infix commands are bound when the transient
|
|||
|
|
prefix command is defined using ‘transient-define-prefix’, see *note
|
|||
|
|
Defining Transients::. The commands are organized into groups, see
|
|||
|
|
*note Group Specifications::. Here we describe the form used to bind an
|
|||
|
|
individual suffix command.
|
|||
|
|
|
|||
|
|
The same form is also used when later binding additional commands
|
|||
|
|
using functions such as ‘transient-insert-suffix’, see *note Modifying
|
|||
|
|
Existing Transients::.
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
Suffix specifications have this form:
|
|||
|
|
|
|||
|
|
([LEVEL] [KEY] [DESCRIPTION] COMMAND|ARGUMENT [KEYWORD VALUE]...)
|
|||
|
|
|
|||
|
|
LEVEL, KEY and DESCRIPTION can also be specified using the KEYWORDs
|
|||
|
|
‘:level’, ‘:key’ and ‘:description’. If the object that is associated
|
|||
|
|
with COMMAND sets these properties, then they do not have to be
|
|||
|
|
specified here. You can however specify them here anyway, possibly
|
|||
|
|
overriding the object’s values just for the binding inside this
|
|||
|
|
transient.
|
|||
|
|
|
|||
|
|
• LEVEL is the suffix level, an integer between 1 and 7. See *note
|
|||
|
|
Enabling and Disabling Suffixes::.
|
|||
|
|
|
|||
|
|
• KEY is the key binding, either a vector or key description string.
|
|||
|
|
|
|||
|
|
• DESCRIPTION is the description, either a string or a function that
|
|||
|
|
returns a string. The function should be a lambda expression to
|
|||
|
|
avoid ambiguity. In some cases a symbol that is bound as a
|
|||
|
|
function would also work but to be safe you should use
|
|||
|
|
‘:description’ in that case.
|
|||
|
|
|
|||
|
|
The next element is either a command or an argument. This is the
|
|||
|
|
only argument that is mandatory in all cases.
|
|||
|
|
|
|||
|
|
• COMMAND should be a symbol that is bound as a function, which has
|
|||
|
|
to be defined or at least autoloaded as a command by the time the
|
|||
|
|
containing prefix command is invoked.
|
|||
|
|
|
|||
|
|
Any command will do; it does not need to have an object associated
|
|||
|
|
with it (as would be the case if ‘transient-define-suffix’ or
|
|||
|
|
‘transient-define-infix’ were used to define it).
|
|||
|
|
|
|||
|
|
Anonymous, dynamically defined suffix commands are also support.
|
|||
|
|
See information about the ‘:setup-children’ function in *note Group
|
|||
|
|
Specifications::.
|
|||
|
|
|
|||
|
|
As mentioned above, the object that is associated with a command
|
|||
|
|
can be used to set the default for certain values that otherwise
|
|||
|
|
have to be set in the suffix specification. Therefore if there is
|
|||
|
|
no object, then you have to make sure to specify the KEY and the
|
|||
|
|
DESCRIPTION.
|
|||
|
|
|
|||
|
|
As a special case, if you want to add a command that might be
|
|||
|
|
neither defined nor autoloaded, you can use a workaround like:
|
|||
|
|
|
|||
|
|
(transient-insert-suffix 'some-prefix "k"
|
|||
|
|
'("!" "Ceci n'est pas une commande" no-command
|
|||
|
|
:if (lambda () (featurep 'no-library))))
|
|||
|
|
|
|||
|
|
Instead of ‘featurep’ you could also use ‘require’ with a non-‘nil’
|
|||
|
|
value for NOERROR.
|
|||
|
|
|
|||
|
|
• The mandatory argument can also be a command-line argument, a
|
|||
|
|
string. In that case an anonymous command is defined and bound.
|
|||
|
|
|
|||
|
|
Instead of a string, this can also be a list of two strings, in
|
|||
|
|
which case the first string is used as the short argument (which
|
|||
|
|
can also be specified using ‘:shortarg’) and the second as the long
|
|||
|
|
argument (which can also be specified using ‘:argument’).
|
|||
|
|
|
|||
|
|
Only the long argument is displayed in the popup buffer. See
|
|||
|
|
‘transient-detect-key-conflicts’ for how the short argument may be
|
|||
|
|
used.
|
|||
|
|
|
|||
|
|
Unless the class is specified explicitly, the appropriate class is
|
|||
|
|
guessed based on the long argument. If the argument ends with "="
|
|||
|
|
(e.g., "–format=") then ‘transient-option’ is used, otherwise
|
|||
|
|
‘transient-switch’.
|
|||
|
|
|
|||
|
|
Finally, details can be specified using optional KEYWORD-VALUE pairs.
|
|||
|
|
Each keyword has to be a keyword symbol, either ‘:class’ or a keyword
|
|||
|
|
argument supported by the constructor of that class. See *note Suffix
|
|||
|
|
Slots::.
|
|||
|
|
|
|||
|
|
|
|||
|
|
File: transient.info, Node: Defining Suffix and Infix Commands, Next: Using Infix Arguments, Prev: Binding Suffix and Infix Commands, Up: Defining New Commands
|
|||
|
|
|
|||
|
|
4.3 Defining Suffix and Infix Commands
|
|||
|
|
======================================
|
|||
|
|
|
|||
|
|
Note that an infix is a special kind of suffix. Depending on context
|
|||
|
|
"suffixes" means "suffixes (including infixes)" or "non-infix suffixes".
|
|||
|
|
|
|||
|
|
-- Macro: transient-define-suffix name arglist [docstring] [keyword
|
|||
|
|
value]... body...
|
|||
|
|
This macro defines NAME as a transient suffix command.
|
|||
|
|
|
|||
|
|
ARGLIST are the arguments that the command takes. DOCSTRING is the
|
|||
|
|
documentation string and is optional.
|
|||
|
|
|
|||
|
|
These arguments can optionally be followed by keyword-value pairs.
|
|||
|
|
Each keyword has to be a keyword symbol, either ‘:class’ or a
|
|||
|
|
keyword argument supported by the constructor of that class. The
|
|||
|
|
‘transient-suffix’ class is used if the class is not specified
|
|||
|
|
explicitly.
|
|||
|
|
|
|||
|
|
The BODY must begin with an ‘interactive’ form that matches
|
|||
|
|
ARGLIST. The infix arguments are usually accessed by using
|
|||
|
|
‘transient-args’ inside ‘interactive’.
|
|||
|
|
|
|||
|
|
-- Macro: transient-define-infix name arglist [docstring] [keyword
|
|||
|
|
value]...
|
|||
|
|
This macro defines NAME as a transient infix command.
|
|||
|
|
|
|||
|
|
ARGLIST is always ignored (but mandatory never-the-less) and
|
|||
|
|
reserved for future use. DOCSTRING is the documentation string and
|
|||
|
|
is optional.
|
|||
|
|
|
|||
|
|
The keyword-value pairs are mandatory. All transient infix
|
|||
|
|
commands are ‘equal’ to each other (but not ‘eq’), so it is
|
|||
|
|
meaningless to define an infix command without also setting at
|
|||
|
|
least ‘:class’ and one other keyword (which it is depends on the
|
|||
|
|
used class, usually ‘:argument’ or ‘:variable’).
|
|||
|
|
|
|||
|
|
Each keyword has to be a keyword symbol, either ‘:class’ or a
|
|||
|
|
keyword argument supported by the constructor of that class. The
|
|||
|
|
‘transient-switch’ class is used if the class is not specified
|
|||
|
|
explicitly.
|
|||
|
|
|
|||
|
|
The function definition is always:
|
|||
|
|
|
|||
|
|
(lambda ()
|
|||
|
|
(interactive)
|
|||
|
|
(let ((obj (transient-suffix-object)))
|
|||
|
|
(transient-infix-set obj (transient-infix-read obj)))
|
|||
|
|
(transient--show))
|
|||
|
|
|
|||
|
|
‘transient-infix-read’ and ‘transient-infix-set’ are generic
|
|||
|
|
functions. Different infix commands behave differently because the
|
|||
|
|
concrete methods are different for different infix command classes.
|
|||
|
|
In rare cases the above command function might not be suitable,
|
|||
|
|
even if you define your own infix command class. In that case you
|
|||
|
|
have to use ‘transient-define-suffix’ to define the infix command
|
|||
|
|
and use ‘t’ as the value of the ‘:transient’ keyword.
|
|||
|
|
|
|||
|
|
-- Macro: transient-define-argument name arglist [docstring] [keyword
|
|||
|
|
value]...
|
|||
|
|
This macro defines NAME as a transient infix command.
|
|||
|
|
|
|||
|
|
This is an alias for ‘transient-define-infix’. Only use this alias
|
|||
|
|
to define an infix command that actually sets an infix argument.
|
|||
|
|
To define an infix command that, for example, sets a variable, use
|
|||
|
|
‘transient-define-infix’ instead.
|
|||
|
|
|
|||
|
|
|
|||
|
|
File: transient.info, Node: Using Infix Arguments, Next: Transient State, Prev: Defining Suffix and Infix Commands, Up: Defining New Commands
|
|||
|
|
|
|||
|
|
4.4 Using Infix Arguments
|
|||
|
|
=========================
|
|||
|
|
|
|||
|
|
The functions and the variables described below allow suffix commands to
|
|||
|
|
access the value of the transient from which they were invoked; which is
|
|||
|
|
the value of its infix arguments. These variables are set when the user
|
|||
|
|
invokes a suffix command that exits the transient, but before actually
|
|||
|
|
calling the command.
|
|||
|
|
|
|||
|
|
When returning to the command-loop after calling the suffix command,
|
|||
|
|
the arguments are reset to ‘nil’ (which causes the function to return
|
|||
|
|
‘nil’ too).
|
|||
|
|
|
|||
|
|
Like for Emacs’ prefix arguments, it is advisable, but not mandatory,
|
|||
|
|
to access the infix arguments inside the command’s ‘interactive’ form.
|
|||
|
|
The preferred way of doing that is to call the ‘transient-args’
|
|||
|
|
function, which for infix arguments serves about the same purpose as
|
|||
|
|
‘prefix-arg’ serves for prefix arguments.
|
|||
|
|
|
|||
|
|
-- Function: transient-args prefix
|
|||
|
|
This function returns the value of the transient prefix command
|
|||
|
|
PREFIX.
|
|||
|
|
|
|||
|
|
If the current command was invoked from the transient prefix
|
|||
|
|
command PREFIX, then it returns the active infix arguments. If the
|
|||
|
|
current command was not invoked from PREFIX, then it returns the
|
|||
|
|
set, saved or default value for PREFIX.
|
|||
|
|
|
|||
|
|
-- Function: transient-arg-value arg args
|
|||
|
|
This function return the value of ARG as it appears in ARGS.
|
|||
|
|
|
|||
|
|
For a switch a boolean is returned. For an option the value is
|
|||
|
|
returned as a string, using the empty string for the empty value,
|
|||
|
|
or nil if the option does not appear in ARGS.
|
|||
|
|
|
|||
|
|
-- Function: transient-suffixes prefix
|
|||
|
|
This function returns the suffixes of the transient prefix command
|
|||
|
|
PREFIX. This is a list of objects. This function should only be
|
|||
|
|
used if you need the objects (as opposed to just their values) and
|
|||
|
|
if the current command is not being invoked from PREFIX.
|
|||
|
|
|
|||
|
|
-- Variable: transient-current-suffixes
|
|||
|
|
The suffixes of the transient from which this suffix command was
|
|||
|
|
invoked. This is a list of objects. Usually it is sufficient to
|
|||
|
|
instead use the function ‘transient-args’, which returns a list of
|
|||
|
|
values. In complex cases it might be necessary to use this
|
|||
|
|
variable instead, i.e., if you need access to information beside
|
|||
|
|
the value.
|
|||
|
|
|
|||
|
|
-- Variable: transient-current-prefix
|
|||
|
|
The transient from which this suffix command was invoked. The
|
|||
|
|
returned value is a ‘transient-prefix’ object, which holds
|
|||
|
|
information associated with the transient prefix command.
|
|||
|
|
|
|||
|
|
-- Variable: transient-current-command
|
|||
|
|
The transient from which this suffix command was invoked. The
|
|||
|
|
returned value is a symbol, the transient prefix command.
|
|||
|
|
|
|||
|
|
|
|||
|
|
File: transient.info, Node: Transient State, Prev: Using Infix Arguments, Up: Defining New Commands
|
|||
|
|
|
|||
|
|
4.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 mean "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’.
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
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-return
|
|||
|
|
Call the command after exporting variables and return to parent
|
|||
|
|
prefix. If there is no parent prefix, then call
|
|||
|
|
‘transient--do-exit’.
|
|||
|
|
|
|||
|
|
-- Function: transient--do-call
|
|||
|
|
Call the command after exporting variables and stay transient.
|
|||
|
|
|
|||
|
|
The following pre-commands are suitable for sub-prefixes. Only the
|
|||
|
|
first should ever explicitly be set as the value of the ‘transient’
|
|||
|
|
slot.
|
|||
|
|
|
|||
|
|
-- Function: transient--do-recurse
|
|||
|
|
Call the transient prefix command, preparing for return to active
|
|||
|
|
transient.
|
|||
|
|
|
|||
|
|
Whether we actually return to the parent transient is ultimately
|
|||
|
|
under the control of each invoked suffix. The difference between
|
|||
|
|
this pre-command and ‘transient--do-replace’ is that it changes the
|
|||
|
|
value of the ‘transient-suffix’ slot to ‘transient--do-return’.
|
|||
|
|
|
|||
|
|
If there is no parent transient, then only call this command and
|
|||
|
|
skip the second step.
|
|||
|
|
|
|||
|
|
-- Function: transient--do-replace
|
|||
|
|
Call the transient prefix command, replacing the active transient.
|
|||
|
|
|
|||
|
|
Unless ‘transient--do-recurse’ is explicitly used, this pre-command
|
|||
|
|
is automatically used for suffixes that are prefixes themselves,
|
|||
|
|
i.e., for sub-prefixes.
|
|||
|
|
|
|||
|
|
-- Function: transient--do-suspend
|
|||
|
|
Suspend the active transient, saving the transient stack.
|
|||
|
|
|
|||
|
|
This is used by the command ‘transient-suspend’ and optionally also
|
|||
|
|
by "external events" such as ‘handle-switch-frame’. Such bindings
|
|||
|
|
should be added to ‘transient-predicate-map’.
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
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’.
|
|||
|
|
|
|||
|
|
|
|||
|
|
File: transient.info, Node: Classes and Methods, Next: Related Abstractions and Packages, Prev: Defining New Commands, Up: Top
|
|||
|
|
|
|||
|
|
5 Classes and Methods
|
|||
|
|
*********************
|
|||
|
|
|
|||
|
|
Transient uses classes and generic functions to make it possible to
|
|||
|
|
define new types of suffix commands that are similar to existing types,
|
|||
|
|
but behave differently in some aspects. It does the same for groups and
|
|||
|
|
prefix commands, though at least for prefix commands that *currently*
|
|||
|
|
appears to be less important.
|
|||
|
|
|
|||
|
|
Every prefix, infix and suffix command is associated with an object,
|
|||
|
|
which holds information that controls certain aspects of its behavior.
|
|||
|
|
This happens in two ways.
|
|||
|
|
|
|||
|
|
• Associating a command with a certain class gives the command a
|
|||
|
|
type. This makes it possible to use generic functions to do
|
|||
|
|
certain things that have to be done differently depending on what
|
|||
|
|
type of command it acts on.
|
|||
|
|
|
|||
|
|
That in turn makes it possible for third-parties to add new types
|
|||
|
|
without having to convince the maintainer of Transient that that
|
|||
|
|
new type is important enough to justify adding a special case to a
|
|||
|
|
dozen or so functions.
|
|||
|
|
|
|||
|
|
• Associating a command with an object makes it possible to easily
|
|||
|
|
store information that is specific to that particular command.
|
|||
|
|
|
|||
|
|
Two commands may have the same type, but obviously their key
|
|||
|
|
bindings and descriptions still have to be different, for example.
|
|||
|
|
|
|||
|
|
The values of some slots are functions. The ‘reader’ slot for
|
|||
|
|
example holds a function that is used to read a new value for an
|
|||
|
|
infix command. The values of such slots are regular functions.
|
|||
|
|
|
|||
|
|
Generic functions are used when a function should do something
|
|||
|
|
different based on the type of the command, i.e., when all commands
|
|||
|
|
of a certain type should behave the same way but different from the
|
|||
|
|
behavior for other types. Object slots that hold a regular
|
|||
|
|
function as value are used when the task that they perform is
|
|||
|
|
likely to differ even between different commands of the same type.
|
|||
|
|
|
|||
|
|
* Menu:
|
|||
|
|
|
|||
|
|
* Group Classes::
|
|||
|
|
* Group Methods::
|
|||
|
|
* Prefix Classes::
|
|||
|
|
* Suffix Classes::
|
|||
|
|
* Suffix Methods::
|
|||
|
|
* Prefix Slots::
|
|||
|
|
* Suffix Slots::
|
|||
|
|
* Predicate Slots::
|
|||
|
|
|
|||
|
|
|
|||
|
|
File: transient.info, Node: Group Classes, Next: Group Methods, Up: Classes and Methods
|
|||
|
|
|
|||
|
|
5.1 Group Classes
|
|||
|
|
=================
|
|||
|
|
|
|||
|
|
The type of a group can be specified using the ‘:class’ property at the
|
|||
|
|
beginning of the class specification, e.g., ‘[:class transient-columns
|
|||
|
|
...]’ in a call to ‘transient-define-prefix’.
|
|||
|
|
|
|||
|
|
• The abstract ‘transient-child’ class is the base class of both
|
|||
|
|
‘transient-group’ (and therefore all groups) as well as of
|
|||
|
|
‘transient-suffix’ (and therefore all suffix and infix commands).
|
|||
|
|
|
|||
|
|
This class exists because the elements (aka "children") of certain
|
|||
|
|
groups can be other groups instead of suffix and infix commands.
|
|||
|
|
|
|||
|
|
• The abstract ‘transient-group’ class is the superclass of all other
|
|||
|
|
group classes.
|
|||
|
|
|
|||
|
|
• The ‘transient-column’ class is the simplest group.
|
|||
|
|
|
|||
|
|
This is the default "flat" group. If the class is not specified
|
|||
|
|
explicitly and the first element is not a vector (i.e., not a
|
|||
|
|
group), then this class is used.
|
|||
|
|
|
|||
|
|
This class displays each element on a separate line.
|
|||
|
|
|
|||
|
|
• The ‘transient-row’ class displays all elements on a single line.
|
|||
|
|
|
|||
|
|
• The ‘transient-columns’ class displays commands organized in
|
|||
|
|
columns.
|
|||
|
|
|
|||
|
|
Direct elements have to be groups whose elements have to be
|
|||
|
|
commands or strings. Each subgroup represents a column. This
|
|||
|
|
class takes care of inserting the subgroups’ elements.
|
|||
|
|
|
|||
|
|
This is the default "nested" group. If the class is not specified
|
|||
|
|
explicitly and the first element is a vector (i.e., a group), then
|
|||
|
|
this class is used.
|
|||
|
|
|
|||
|
|
• The ‘transient-subgroups’ class wraps other groups.
|
|||
|
|
|
|||
|
|
Direct elements have to be groups whose elements have to be
|
|||
|
|
commands or strings. This group inserts an empty line between
|
|||
|
|
subgroups. The subgroups themselves are responsible for displaying
|
|||
|
|
their elements.
|
|||
|
|
|
|||
|
|
|
|||
|
|
File: transient.info, Node: Group Methods, Next: Prefix Classes, Prev: Group Classes, Up: Classes and Methods
|
|||
|
|
|
|||
|
|
5.2 Group Methods
|
|||
|
|
=================
|
|||
|
|
|
|||
|
|
-- Function: transient-setup-children group children
|
|||
|
|
This generic function can be used to setup the children or a group.
|
|||
|
|
|
|||
|
|
The default implementation usually just returns the children
|
|||
|
|
unchanged, but if the ‘setup-children’ slot of GROUP is non-‘nil’,
|
|||
|
|
then it calls that function with CHILDREN as the only argument and
|
|||
|
|
returns the value.
|
|||
|
|
|
|||
|
|
The children are given as a (potentially empty) list consisting of
|
|||
|
|
either group or suffix specifications. These functions can make
|
|||
|
|
arbitrary changes to the children including constructing new
|
|||
|
|
children from scratch.
|
|||
|
|
|
|||
|
|
-- Function: transient--insert-group group
|
|||
|
|
This generic function formats the group and its elements and
|
|||
|
|
inserts the result into the current buffer, which is a temporary
|
|||
|
|
buffer. The contents of that buffer are later inserted into the
|
|||
|
|
popup buffer.
|
|||
|
|
|
|||
|
|
Functions that are called by this function may need to operate in
|
|||
|
|
the buffer from which the transient was called. To do so they can
|
|||
|
|
temporarily make the ‘transient--source-buffer’ the current buffer.
|
|||
|
|
|
|||
|
|
|
|||
|
|
File: transient.info, Node: Prefix Classes, Next: Suffix Classes, Prev: Group Methods, Up: Classes and Methods
|
|||
|
|
|
|||
|
|
5.3 Prefix Classes
|
|||
|
|
==================
|
|||
|
|
|
|||
|
|
Currently the ‘transient-prefix’ class is being used for all prefix
|
|||
|
|
commands and there is only a single generic function that can be
|
|||
|
|
specialized based on the class of a prefix command.
|
|||
|
|
|
|||
|
|
-- Function: transient--history-init obj
|
|||
|
|
This generic function is called while setting up the transient and
|
|||
|
|
is responsible for initializing the ‘history’ slot. This is the
|
|||
|
|
transient-wide history; many individual infixes also have a history
|
|||
|
|
of their own.
|
|||
|
|
|
|||
|
|
The default (and currently only) method extracts the value from the
|
|||
|
|
global variable ‘transient-history’.
|
|||
|
|
|
|||
|
|
A transient prefix command’s object is stored in the
|
|||
|
|
‘transient--prefix’ property of the command symbol. While a transient
|
|||
|
|
is active, a clone of that object is stored in the variable
|
|||
|
|
‘transient--prefix’. A clone is used because some changes that are made
|
|||
|
|
to the active transient’s object should not affect later invocations.
|
|||
|
|
|
|||
|
|
|
|||
|
|
File: transient.info, Node: Suffix Classes, Next: Suffix Methods, Prev: Prefix Classes, Up: Classes and Methods
|
|||
|
|
|
|||
|
|
5.4 Suffix Classes
|
|||
|
|
==================
|
|||
|
|
|
|||
|
|
• All suffix and infix classes derive from ‘transient-suffix’, which
|
|||
|
|
in turn derives from ‘transient-child’, from which
|
|||
|
|
‘transient-group’ also derives (see *note Group Classes::).
|
|||
|
|
|
|||
|
|
• All infix classes derive from the abstract ‘transient-infix’ class,
|
|||
|
|
which in turn derives from the ‘transient-suffix’ class.
|
|||
|
|
|
|||
|
|
Infixes are a special type of suffixes. The primary difference is
|
|||
|
|
that infixes always use the ‘transient--do-stay’ pre-command, while
|
|||
|
|
non-infix suffixes use a variety of pre-commands (see *note
|
|||
|
|
Transient State::). Doing that is most easily achieved by using
|
|||
|
|
this class, though theoretically it would be possible to define an
|
|||
|
|
infix class that does not do so. If you do that then you get to
|
|||
|
|
implement many methods.
|
|||
|
|
|
|||
|
|
Also, infixes and non-infix suffixes are usually defined using
|
|||
|
|
different macros (see *note Defining Suffix and Infix Commands::).
|
|||
|
|
|
|||
|
|
• Classes used for infix commands that represent arguments should be
|
|||
|
|
derived from the abstract ‘transient-argument’ class.
|
|||
|
|
|
|||
|
|
• The ‘transient-switch’ class (or a derived class) is used for infix
|
|||
|
|
arguments that represent command-line switches (arguments that do
|
|||
|
|
not take a value).
|
|||
|
|
|
|||
|
|
• The ‘transient-option’ class (or a derived class) is used for infix
|
|||
|
|
arguments that represent command-line options (arguments that do
|
|||
|
|
take a value).
|
|||
|
|
|
|||
|
|
• The ‘transient-switches’ class can be used for a set of mutually
|
|||
|
|
exclusive command-line switches.
|
|||
|
|
|
|||
|
|
• The ‘transient-files’ class can be used for a "–" argument that
|
|||
|
|
indicates that all remaining arguments are files.
|
|||
|
|
|
|||
|
|
• Classes used for infix commands that represent variables should
|
|||
|
|
derived from the abstract ‘transient-variables’ class.
|
|||
|
|
|
|||
|
|
Magit defines additional classes, which can serve as examples for the
|
|||
|
|
fancy things you can do without modifying Transient. Some of these
|
|||
|
|
classes will likely get generalized and added to Transient. For now
|
|||
|
|
they are very much subject to change and not documented.
|
|||
|
|
|
|||
|
|
|
|||
|
|
File: transient.info, Node: Suffix Methods, Next: Prefix Slots, Prev: Suffix Classes, Up: Classes and Methods
|
|||
|
|
|
|||
|
|
5.5 Suffix Methods
|
|||
|
|
==================
|
|||
|
|
|
|||
|
|
To get information about the methods implementing these generic
|
|||
|
|
functions use ‘describe-function’.
|
|||
|
|
|
|||
|
|
* Menu:
|
|||
|
|
|
|||
|
|
* Suffix Value Methods::
|
|||
|
|
* Suffix Format Methods::
|
|||
|
|
|
|||
|
|
|
|||
|
|
File: transient.info, Node: Suffix Value Methods, Next: Suffix Format Methods, Up: Suffix Methods
|
|||
|
|
|
|||
|
|
5.5.1 Suffix Value Methods
|
|||
|
|
--------------------------
|
|||
|
|
|
|||
|
|
-- Function: transient-init-value obj
|
|||
|
|
This generic function sets the initial value of the object OBJ.
|
|||
|
|
|
|||
|
|
This function is called for all suffix commands, but unless a
|
|||
|
|
concrete method is implemented this falls through to the default
|
|||
|
|
implementation, which is a noop. In other words this usually only
|
|||
|
|
does something for infix commands, but note that this is not
|
|||
|
|
implemented for the abstract class ‘transient-infix’, so if your
|
|||
|
|
class derives from that directly, then you must implement a method.
|
|||
|
|
|
|||
|
|
-- Function: transient-infix-read obj
|
|||
|
|
This generic function determines the new value of the infix object
|
|||
|
|
OBJ.
|
|||
|
|
|
|||
|
|
This function merely determines the value; ‘transient-infix-set’ is
|
|||
|
|
used to actually store the new value in the object.
|
|||
|
|
|
|||
|
|
For most infix classes this is done by reading a value from the
|
|||
|
|
user using the reader specified by the ‘reader’ slot (using the
|
|||
|
|
‘transient-infix-value’ method described below).
|
|||
|
|
|
|||
|
|
For some infix classes the value is changed without reading
|
|||
|
|
anything in the minibuffer, i.e., the mere act of invoking the
|
|||
|
|
infix command determines what the new value should be, based on the
|
|||
|
|
previous value.
|
|||
|
|
|
|||
|
|
-- Function: transient-prompt obj
|
|||
|
|
This generic function returns the prompt to be used to read infix
|
|||
|
|
object OBJ’s value.
|
|||
|
|
|
|||
|
|
-- Function: transient-infix-set obj value
|
|||
|
|
This generic function sets the value of infix object OBJ to VALUE.
|
|||
|
|
|
|||
|
|
-- Function: transient-infix-value obj
|
|||
|
|
This generic function returns the value of the suffix object OBJ.
|
|||
|
|
|
|||
|
|
This function is called by ‘transient-args’ (which see), meaning
|
|||
|
|
this function is how the value of a transient is determined so that
|
|||
|
|
the invoked suffix command can use it.
|
|||
|
|
|
|||
|
|
Currently most values are strings, but that is not set in stone.
|
|||
|
|
‘nil’ is not a value, it means "no value".
|
|||
|
|
|
|||
|
|
Usually only infixes have a value, but see the method for
|
|||
|
|
‘transient-suffix’.
|
|||
|
|
|
|||
|
|
-- Function: transient-init-scope obj
|
|||
|
|
This generic function sets the scope of the suffix object OBJ.
|
|||
|
|
|
|||
|
|
The scope is actually a property of the transient prefix, not of
|
|||
|
|
individual suffixes. However it is possible to invoke a suffix
|
|||
|
|
command directly instead of from a transient. In that case, if the
|
|||
|
|
suffix expects a scope, then it has to determine that itself and
|
|||
|
|
store it in its ‘scope’ slot.
|
|||
|
|
|
|||
|
|
This function is called for all suffix commands, but unless a
|
|||
|
|
concrete method is implemented this falls through to the default
|
|||
|
|
implementation, which is a noop.
|
|||
|
|
|
|||
|
|
|
|||
|
|
File: transient.info, Node: Suffix Format Methods, Prev: Suffix Value Methods, Up: Suffix Methods
|
|||
|
|
|
|||
|
|
5.5.2 Suffix Format Methods
|
|||
|
|
---------------------------
|
|||
|
|
|
|||
|
|
-- Function: transient-format obj
|
|||
|
|
This generic function formats and returns OBJ for display.
|
|||
|
|
|
|||
|
|
When this function is called, then the current buffer is some
|
|||
|
|
temporary buffer. If you need the buffer from which the prefix
|
|||
|
|
command was invoked to be current, then do so by temporarily making
|
|||
|
|
‘transient--source-buffer’ current.
|
|||
|
|
|
|||
|
|
-- Function: transient-format-key obj
|
|||
|
|
This generic function formats OBJ’s ‘key’ for display and returns
|
|||
|
|
the result.
|
|||
|
|
|
|||
|
|
-- Function: transient-format-description obj
|
|||
|
|
This generic function formats OBJ’s ‘description’ for display and
|
|||
|
|
returns the result.
|
|||
|
|
|
|||
|
|
-- Function: transient-format-value obj
|
|||
|
|
This generic function formats OBJ’s value for display and returns
|
|||
|
|
the result.
|
|||
|
|
|
|||
|
|
-- Function: transient-show-help obj
|
|||
|
|
Show help for the prefix, infix or suffix command represented by
|
|||
|
|
OBJ.
|
|||
|
|
|
|||
|
|
For prefixes, show the info manual, if that is specified using the
|
|||
|
|
‘info-manual’ slot. Otherwise, show the manpage if that is
|
|||
|
|
specified using the ‘man-page’ slot. Otherwise, show the command’s
|
|||
|
|
doc string.
|
|||
|
|
|
|||
|
|
For suffixes, show the command’s doc string.
|
|||
|
|
|
|||
|
|
For infixes, show the manpage if that is specified. Otherwise show
|
|||
|
|
the command’s doc string.
|
|||
|
|
|
|||
|
|
|
|||
|
|
File: transient.info, Node: Prefix Slots, Next: Suffix Slots, Prev: Suffix Methods, Up: Classes and Methods
|
|||
|
|
|
|||
|
|
5.6 Prefix Slots
|
|||
|
|
================
|
|||
|
|
|
|||
|
|
• ‘show-help’, ‘man-page’ or ‘info-manual’ can be used to specify the
|
|||
|
|
documentation for the prefix and its suffixes. The command
|
|||
|
|
‘transient-help’ uses the method ‘transient-show-help’ (which see)
|
|||
|
|
to lookup and use these values.
|
|||
|
|
|
|||
|
|
• ‘history-key’ If multiple prefix commands should share a single
|
|||
|
|
value, then this slot has to be set to the same value for all of
|
|||
|
|
them. You probably don’t want that.
|
|||
|
|
|
|||
|
|
• ‘transient-suffix’ and ‘transient-non-suffix’ play a part when
|
|||
|
|
determining whether the currently active transient prefix command
|
|||
|
|
remains active/transient when a suffix or abitrary non-suffix
|
|||
|
|
command is invoked. See *note Transient State::.
|
|||
|
|
|
|||
|
|
• ‘incompatible’ A list of lists. Each sub-list specifies a set of
|
|||
|
|
mutually exclusive arguments. Enabling one of these arguments
|
|||
|
|
causes the others to be disabled. An argument may appear in
|
|||
|
|
multiple sub-lists.
|
|||
|
|
|
|||
|
|
• ‘scope’ For some transients it might be necessary to have a sort of
|
|||
|
|
secondary value, called a "scope". See ‘transient-define-prefix’.
|
|||
|
|
|
|||
|
|
Internal Prefix Slots
|
|||
|
|
---------------------
|
|||
|
|
|
|||
|
|
These slots are mostly intended for internal use. They should not be
|
|||
|
|
set in calls to ‘transient-define-prefix’.
|
|||
|
|
|
|||
|
|
• ‘prototype’ When a transient prefix command is invoked, then a
|
|||
|
|
clone of that object is stored in the global variable
|
|||
|
|
‘transient--prefix’ and the prototype is stored in the clone’s
|
|||
|
|
‘prototype’ slot.
|
|||
|
|
|
|||
|
|
• ‘command’ The command, a symbol. Each transient prefix command
|
|||
|
|
consists of a command, which is stored in a symbol’s function slot
|
|||
|
|
and an object, which is stored in the ‘transient--prefix’ property
|
|||
|
|
of the same symbol.
|
|||
|
|
|
|||
|
|
• ‘level’ The level of the prefix commands. The suffix commands
|
|||
|
|
whose layer is equal or lower are displayed. See *note Enabling
|
|||
|
|
and Disabling Suffixes::.
|
|||
|
|
|
|||
|
|
• ‘value’ The likely outdated value of the prefix. Instead of
|
|||
|
|
accessing this slot directly you should use the function
|
|||
|
|
‘transient-get-value’, which is guaranteed to return the up-to-date
|
|||
|
|
value.
|
|||
|
|
|
|||
|
|
• ‘history’ and ‘history-pos’ are used to keep track of historic
|
|||
|
|
values. Unless you implement your own ‘transient-infix-read’
|
|||
|
|
method you should not have to deal with these slots.
|
|||
|
|
|
|||
|
|
|
|||
|
|
File: transient.info, Node: Suffix Slots, Next: Predicate Slots, Prev: Prefix Slots, Up: Classes and Methods
|
|||
|
|
|
|||
|
|
5.7 Suffix Slots
|
|||
|
|
================
|
|||
|
|
|
|||
|
|
Here we document most of the slots that are only available for suffix
|
|||
|
|
objects. Some slots are shared by suffix and group objects, they are
|
|||
|
|
documented in *note Predicate Slots::.
|
|||
|
|
|
|||
|
|
Also see *note Suffix Classes::.
|
|||
|
|
|
|||
|
|
Slots of ‘transient-suffix’
|
|||
|
|
---------------------------
|
|||
|
|
|
|||
|
|
• ‘key’ The key, a key vector or a key description string.
|
|||
|
|
|
|||
|
|
• ‘command’ The command, a symbol.
|
|||
|
|
|
|||
|
|
• ‘transient’ Whether to stay transient. See *note Transient
|
|||
|
|
State::.
|
|||
|
|
|
|||
|
|
• ‘format’ The format used to display the suffix in the popup buffer.
|
|||
|
|
It must contain the following %-placeholders:
|
|||
|
|
|
|||
|
|
• ‘%k’ For the key.
|
|||
|
|
• ‘%d’ For the description.
|
|||
|
|
• ‘%v’ For the infix value. Non-infix suffixes don’t have a
|
|||
|
|
value.
|
|||
|
|
|
|||
|
|
• ‘description’ The description, either a string or a function that
|
|||
|
|
is called with no argument and returns a string.
|
|||
|
|
|
|||
|
|
• ‘show-help’ A function used to display help for the suffix. If
|
|||
|
|
unspecified, the prefix controls how hlep is displayed for its
|
|||
|
|
suffixes.
|
|||
|
|
|
|||
|
|
Slots of ‘transient-infix’
|
|||
|
|
--------------------------
|
|||
|
|
|
|||
|
|
Some of these slots are only meaningful for some of the subclasses.
|
|||
|
|
They are defined here anyway to allow sharing certain methods.
|
|||
|
|
|
|||
|
|
• ‘argument’ The long argument, e.g., ‘--verbose’.
|
|||
|
|
|
|||
|
|
• ‘shortarg’ The short argument, e.g., ‘-v’.
|
|||
|
|
|
|||
|
|
• ‘value’ The value. Should not be accessed directly.
|
|||
|
|
|
|||
|
|
• ‘init-value’ Function that is responsable for setting the object’s
|
|||
|
|
value. If bound, then this is called with the object as the only
|
|||
|
|
argument. Usually this is not bound, in which case the object’s
|
|||
|
|
primary ‘transient-init-value’ method is called instead.
|
|||
|
|
|
|||
|
|
• ‘unsavable’ Whether the value of the suffix is not saved as part of
|
|||
|
|
the prefixes.
|
|||
|
|
|
|||
|
|
• ‘multi-value’ For options, whether the option can have multiple
|
|||
|
|
values. If this is non-‘nil’, then the values are read using
|
|||
|
|
‘completing-read-multiple’ by default and if you specify your own
|
|||
|
|
reader, then it should read the values using that function or
|
|||
|
|
similar.
|
|||
|
|
|
|||
|
|
Supported non-‘nil’ values are:
|
|||
|
|
|
|||
|
|
• Use ‘rest’ for an option that can have multiple values. This
|
|||
|
|
is useful e.g., for an ‘--’ argument that indicates that all
|
|||
|
|
remaining arguments are files (such as ‘git log -- file1
|
|||
|
|
file2’).
|
|||
|
|
|
|||
|
|
In the list returned by ‘transient-args’ such an option and
|
|||
|
|
its values are represented by a single list of the form
|
|||
|
|
‘(ARGUMENT . VALUES)’.
|
|||
|
|
|
|||
|
|
• Use ‘repeat’ for an option that can be specified multiple
|
|||
|
|
times.
|
|||
|
|
|
|||
|
|
In the list returned by ‘transient-args’ each instance of the
|
|||
|
|
option and its value appears separately in the usual from, for
|
|||
|
|
example: ‘("--another-argument" "--option=first"
|
|||
|
|
"--option=second")’.
|
|||
|
|
|
|||
|
|
In both cases the option’s values have to be specified in the
|
|||
|
|
default value of a prefix using the same format as returned by
|
|||
|
|
‘transient-args’, e.g., ‘("--other" "--o=1" "--o=2" ("--" "f1"
|
|||
|
|
"f2"))’.
|
|||
|
|
|
|||
|
|
• ‘always-read’ For options, whether to read a value on every
|
|||
|
|
invocation. If this is nil, then options that have a value are
|
|||
|
|
simply unset and have to be invoked a second time to set a new
|
|||
|
|
value.
|
|||
|
|
|
|||
|
|
• ‘allow-empty’ For options, whether the empty string is a valid
|
|||
|
|
value.
|
|||
|
|
|
|||
|
|
• ‘history-key’ The key used to store the history. This defaults to
|
|||
|
|
the command name. This is useful when multiple infixes should
|
|||
|
|
share the same history because their values are of the same kind.
|
|||
|
|
|
|||
|
|
• ‘reader’ The function used to read the value of an infix. Not used
|
|||
|
|
for switches. The function takes three arguments, PROMPT,
|
|||
|
|
INITIAL-INPUT and HISTORY, and must return a string.
|
|||
|
|
|
|||
|
|
• ‘prompt’ The prompt used when reading the value, either a string or
|
|||
|
|
a function that takes the object as the only argument and which
|
|||
|
|
returns a prompt string.
|
|||
|
|
|
|||
|
|
• ‘choices’ A list of valid values. How exactly that is used depends
|
|||
|
|
on the class of the object.
|
|||
|
|
|
|||
|
|
Slots of ‘transient-variable’
|
|||
|
|
-----------------------------
|
|||
|
|
|
|||
|
|
• ‘variable’ The variable.
|
|||
|
|
|
|||
|
|
Slots of ‘transient-switches’
|
|||
|
|
-----------------------------
|
|||
|
|
|
|||
|
|
• ‘argument-format’ The display format. Must contain ‘%s’, one of
|
|||
|
|
the ‘choices’ is substituted for that. e.g., ‘--%s-order’.
|
|||
|
|
|
|||
|
|
• ‘argument-regexp’ The regexp used to match any one of the switches.
|
|||
|
|
e.g., ‘\\(--\\(topo\\|author-date\\|date\\)-order\\)’.
|
|||
|
|
|
|||
|
|
|
|||
|
|
File: transient.info, Node: Predicate Slots, Prev: Suffix Slots, Up: Classes and Methods
|
|||
|
|
|
|||
|
|
5.8 Predicate Slots
|
|||
|
|
===================
|
|||
|
|
|
|||
|
|
Suffix and group objects share some predicate slots that control whether
|
|||
|
|
a group or suffix should be available depending on some state. Only one
|
|||
|
|
of these slots can be used at the same time. It is undefined what
|
|||
|
|
happens if you use more than one.
|
|||
|
|
|
|||
|
|
• ‘if’ Enable if predicate returns non-‘nil’.
|
|||
|
|
• ‘if-not’ Enable if predicate returns nil.
|
|||
|
|
• ‘if-non-~nil~’ Enable if variable’s value is non-‘nil’.
|
|||
|
|
• ‘if-nil’ Enable if variable’s value is nil.
|
|||
|
|
• ‘if-mode’ Enable if major-mode matches value.
|
|||
|
|
• ‘if-not-mode’ Enable if major-mode does not match value.
|
|||
|
|
• ‘if-derived’ Enable if major-mode derives from value.
|
|||
|
|
• ‘if-not-derived’ Enable if major-mode does not derive from value.
|
|||
|
|
|
|||
|
|
One more slot is shared between group and suffix classes, ‘level’.
|
|||
|
|
Like the slots documented above, it is a predicate, but it is used for a
|
|||
|
|
different purpose. The value has to be an integer between 1 and 7.
|
|||
|
|
‘level’ controls whether a suffix or a group should be available
|
|||
|
|
depending on user preference. See *note Enabling and Disabling
|
|||
|
|
Suffixes::.
|
|||
|
|
|
|||
|
|
|
|||
|
|
File: transient.info, Node: Related Abstractions and Packages, Next: FAQ, Prev: Classes and Methods, Up: Top
|
|||
|
|
|
|||
|
|
6 Related Abstractions and Packages
|
|||
|
|
***********************************
|
|||
|
|
|
|||
|
|
* Menu:
|
|||
|
|
|
|||
|
|
* Comparison With Prefix Keys and Prefix Arguments::
|
|||
|
|
* Comparison With Other Packages::
|
|||
|
|
|
|||
|
|
|
|||
|
|
File: transient.info, Node: Comparison With Prefix Keys and Prefix Arguments, Next: Comparison With Other Packages, Up: Related Abstractions and Packages
|
|||
|
|
|
|||
|
|
6.1 Comparison With Prefix Keys and Prefix Arguments
|
|||
|
|
====================================================
|
|||
|
|
|
|||
|
|
While transient commands were inspired by regular prefix keys and prefix
|
|||
|
|
arguments, they are also quite different and much more complex.
|
|||
|
|
|
|||
|
|
The following diagrams illustrate some of the differences.
|
|||
|
|
|
|||
|
|
• ‘(c)’ represents a return to the command loop.
|
|||
|
|
• ‘(+)’ represents the user’s choice to press one key or another.
|
|||
|
|
• ‘{WORD}’ are possible behaviors.
|
|||
|
|
• ‘{NUMBER}’ is a footnote.
|
|||
|
|
|
|||
|
|
Regular Prefix Commands
|
|||
|
|
-----------------------
|
|||
|
|
|
|||
|
|
See *note (elisp)Prefix Keys::.
|
|||
|
|
|
|||
|
|
,--> command1 --> (c)
|
|||
|
|
|
|
|||
|
|
(c)-(+)-> prefix command or key --+--> command2 --> (c)
|
|||
|
|
|
|
|||
|
|
`--> command3 --> (c)
|
|||
|
|
|
|||
|
|
Regular Prefix Arguments
|
|||
|
|
------------------------
|
|||
|
|
|
|||
|
|
See *note (elisp)Prefix Command Arguments::.
|
|||
|
|
|
|||
|
|
,----------------------------------,
|
|||
|
|
| |
|
|||
|
|
v |
|
|||
|
|
(c)-(+)---> prefix argument command --(c)-(+)-> any command --> (c)
|
|||
|
|
| ^ |
|
|||
|
|
| | |
|
|||
|
|
`-- sets or changes --, ,-- maybe used --' |
|
|||
|
|
| | |
|
|||
|
|
v | |
|
|||
|
|
prefix argument state |
|
|||
|
|
^ |
|
|||
|
|
| |
|
|||
|
|
`-------- discards --------'
|
|||
|
|
|
|||
|
|
Transients
|
|||
|
|
----------
|
|||
|
|
|
|||
|
|
(∩｀-´)⊃━☆ﾟ.*･｡ﾟ
|
|||
|
|
|
|||
|
|
This diagram ignores the infix value and external state:
|
|||
|
|
|
|||
|
|
(c)
|
|||
|
|
| ,- {stay} ------<-,-<------------<-,-<---,
|
|||
|
|
(+) | | | |
|
|||
|
|
| | | | |
|
|||
|
|
| | ,--> infix1 --| | |
|
|||
|
|
| | | | | |
|
|||
|
|
| | |--> infix2 --| | |
|
|||
|
|
v v | | | |
|
|||
|
|
prefix -(c)-(+)-> infix3 --' ^ |
|
|||
|
|
| | |
|
|||
|
|
|---------------> suffix1 -->--| |
|
|||
|
|
| | |
|
|||
|
|
|---------------> suffix2 ----{1}------> {exit} --> (c)
|
|||
|
|
| |
|
|||
|
|
|---------------> suffix3 -------------> {exit} --> (c)
|
|||
|
|
| |
|
|||
|
|
`--> any command --{2}-> {warn} -->--|
|
|||
|
|
| |
|
|||
|
|
|--> {noop} -->--|
|
|||
|
|
| |
|
|||
|
|
|--> {call} -->--'
|
|||
|
|
|
|
|||
|
|
`------------------> {exit} --> (c)
|
|||
|
|
|
|||
|
|
This diagram takes the infix value into account to an extend, while
|
|||
|
|
still ignoring external state:
|
|||
|
|
|
|||
|
|
(c)
|
|||
|
|
| ,- {stay} ------<-,-<------------<-,-<---,
|
|||
|
|
(+) | | | |
|
|||
|
|
| | | | |
|
|||
|
|
| | ,--> infix1 --| | |
|
|||
|
|
| | | | | | |
|
|||
|
|
| | ,--> infix2 --| | |
|
|||
|
|
v v | | | | |
|
|||
|
|
prefix -(c)-(+)-> infix3 --' | |
|
|||
|
|
| | ^ |
|
|||
|
|
| | | |
|
|||
|
|
|---------------> suffix1 -->--| |
|
|||
|
|
| | ^ | |
|
|||
|
|
| | | | |
|
|||
|
|
|---------------> suffix2 ----{1}------> {exit} --> (c)
|
|||
|
|
| | ^ | |
|
|||
|
|
| | | | v
|
|||
|
|
| | | | |
|
|||
|
|
|---------------> suffix3 -------------> {exit} --> (c)
|
|||
|
|
| | ^ | |
|
|||
|
|
| sets | | v
|
|||
|
|
| | maybe | |
|
|||
|
|
| | used | |
|
|||
|
|
| | | | |
|
|||
|
|
| | infix --' | |
|
|||
|
|
| `---> value | |
|
|||
|
|
| ^ | |
|
|||
|
|
| | | |
|
|||
|
|
| hides | |
|
|||
|
|
| | | |
|
|||
|
|
| `--------------------------<---|
|
|||
|
|
| | |
|
|||
|
|
`--> any command --{2}-> {warn} -->--| |
|
|||
|
|
| | |
|
|||
|
|
|--> {noop} -->--| |
|
|||
|
|
| | |
|
|||
|
|
|--> {call} -->--' ^
|
|||
|
|
| |
|
|||
|
|
`------------------> {exit} --> (c)
|
|||
|
|
|
|||
|
|
This diagram provides more information about the infix value and also
|
|||
|
|
takes external state into account.
|
|||
|
|
|
|||
|
|
,----sets--- "anything"
|
|||
|
|
|
|
|||
|
|
v
|
|||
|
|
,---------> external
|
|||
|
|
| state
|
|||
|
|
| | |
|
|||
|
|
| initialized | ☉‿⚆
|
|||
|
|
sets from |
|
|||
|
|
| | maybe
|
|||
|
|
| ,----------' used
|
|||
|
|
| | |
|
|||
|
|
(c) | | v
|
|||
|
|
| ,- {stay} --|---<-,-<------|-----<-,-<---,
|
|||
|
|
(+) | | | | | | |
|
|||
|
|
| | | v | | | |
|
|||
|
|
| | ,--> infix1 --| | | |
|
|||
|
|
| | | | | | | | |
|
|||
|
|
| | | | v | | | |
|
|||
|
|
| | ,--> infix2 --| | | |
|
|||
|
|
| | | | ^ | | | |
|
|||
|
|
v v | | | | | | |
|
|||
|
|
prefix -(c)-(+)-> infix3 --' | | |
|
|||
|
|
| | ^ | ^ |
|
|||
|
|
| | | v | |
|
|||
|
|
|---------------> suffix1 -->--| |
|
|||
|
|
| | | ^ | | |
|
|||
|
|
| | | | v | |
|
|||
|
|
|---------------> suffix2 ----{1}------> {exit} --> (c)
|
|||
|
|
| | | ^ | | |
|
|||
|
|
| | | | | | v
|
|||
|
|
| | | | v | |
|
|||
|
|
|---------------> suffix3 -------------> {exit} --> (c)
|
|||
|
|
| | | ^ | |
|
|||
|
|
| sets | | | v
|
|||
|
|
| | initialized maybe | |
|
|||
|
|
| | from used | |
|
|||
|
|
| | | | | |
|
|||
|
|
| | `-- infix ---' | |
|
|||
|
|
| `---> value -----------------------------> persistent
|
|||
|
|
| ^ ^ | | across
|
|||
|
|
| | | | | invocations -,
|
|||
|
|
| hides | | | |
|
|||
|
|
| | `----------------------------------------------'
|
|||
|
|
| | | |
|
|||
|
|
| `--------------------------<---|
|
|||
|
|
| | |
|
|||
|
|
`--> any command --{2}-> {warn} -->--| |
|
|||
|
|
| | |
|
|||
|
|
|--> {noop} -->--| |
|
|||
|
|
| | |
|
|||
|
|
|--> {call} -->--' ^
|
|||
|
|
| |
|
|||
|
|
`------------------> {exit} --> (c)
|
|||
|
|
|
|||
|
|
• ‘{1}’ Transients can be configured to be exited when a suffix
|
|||
|
|
command is invoked. The default is to do so for all suffixes
|
|||
|
|
except for those that are common to all transients and which are
|
|||
|
|
used to perform tasks such as providing help and saving the value
|
|||
|
|
of the infix arguments for future invocations. The behavior can
|
|||
|
|
also be specified for individual suffix commands and may even
|
|||
|
|
depend on state.
|
|||
|
|
|
|||
|
|
• ‘{2}’ Transients can be configured to allow the user to invoke
|
|||
|
|
non-suffix commands. The default is to not allow that and instead
|
|||
|
|
warn the user.
|
|||
|
|
|
|||
|
|
Despite already being rather complex, even the last diagram leaves
|
|||
|
|
out many details. Most importantly it implies that the decision whether
|
|||
|
|
to remain transient is made later than it actually is made (for the most
|
|||
|
|
part a function on ‘pre-command-hook’ is responsible). But such
|
|||
|
|
implementation details are of little relevance to users and are covered
|
|||
|
|
elsewhere.
|
|||
|
|
|
|||
|
|
|
|||
|
|
File: transient.info, Node: Comparison With Other Packages, Prev: Comparison With Prefix Keys and Prefix Arguments, Up: Related Abstractions and Packages
|
|||
|
|
|
|||
|
|
6.2 Comparison With Other Packages
|
|||
|
|
==================================
|
|||
|
|
|
|||
|
|
Magit-Popup
|
|||
|
|
-----------
|
|||
|
|
|
|||
|
|
Transient is the successor to Magit-Popup (see *note
|
|||
|
|
(magit-popup)Top::).
|
|||
|
|
|
|||
|
|
One major difference between these two implementations of the same
|
|||
|
|
ideas is that while Transient uses transient keymaps and embraces the
|
|||
|
|
command-loop, Magit-Popup implemented an inferior mechanism that does
|
|||
|
|
not use transient keymaps and that instead of using the command-loop
|
|||
|
|
implements a naive alternative based on ‘read-char’.
|
|||
|
|
|
|||
|
|
Magit-Popup does not use classes and generic functions and defining a
|
|||
|
|
new command type is near impossible as it involves adding hard-coded
|
|||
|
|
special-cases to many functions. Because of that only a single new type
|
|||
|
|
was added, which was not already part of Magit-Popup’s initial release.
|
|||
|
|
|
|||
|
|
A lot of things are hard-coded in Magit-Popup. One random example is
|
|||
|
|
that the key bindings for switches must begin with "-" and those for
|
|||
|
|
options must begin with "=".
|
|||
|
|
|
|||
|
|
Hydra
|
|||
|
|
-----
|
|||
|
|
|
|||
|
|
Hydra (see <https://github.com/abo-abo/hydra>) is another package that
|
|||
|
|
provides features similar to those of Transient.
|
|||
|
|
|
|||
|
|
Both packages use transient keymaps to make a set of commands
|
|||
|
|
temporarily available and show the available commands in a popup buffer.
|
|||
|
|
|
|||
|
|
A Hydra "body" is equivalent to a Transient "prefix" and a Hydra
|
|||
|
|
"head" is equivalent to a Transient "suffix". Hydra has no equivalent
|
|||
|
|
of a Transient "infix".
|
|||
|
|
|
|||
|
|
Both hydras and transients can be used as simple command dispatchers.
|
|||
|
|
Used like this they are similar to regular prefix commands and prefix
|
|||
|
|
keys, except that the available commands are shown in the popup buffer.
|
|||
|
|
|
|||
|
|
(Another package that does this is ‘which-key’. It does so
|
|||
|
|
automatically for any incomplete key sequence. The advantage of that
|
|||
|
|
approach is that no additional work is necessary; the disadvantage is
|
|||
|
|
that the available commands are not organized semantically.)
|
|||
|
|
|
|||
|
|
Both Hydra and Transient provide features that go beyond simple
|
|||
|
|
command dispatchers:
|
|||
|
|
|
|||
|
|
• Invoking a command from a hydra does not necessarily exit the
|
|||
|
|
hydra. That makes it possible to invoke the same command again,
|
|||
|
|
but using a shorter key sequence (i.e., the key that was used to
|
|||
|
|
enter the hydra does not have to be pressed again).
|
|||
|
|
|
|||
|
|
Transient supports that too, but for now this feature is not a
|
|||
|
|
focus and the interface is a bit more complicated. A very basic
|
|||
|
|
example using the current interface:
|
|||
|
|
|
|||
|
|
(transient-define-prefix outline-navigate ()
|
|||
|
|
:transient-suffix 'transient--do-stay
|
|||
|
|
:transient-non-suffix 'transient--do-warn
|
|||
|
|
[("p" "previous visible heading" outline-previous-visible-heading)
|
|||
|
|
("n" "next visible heading" outline-next-visible-heading)])
|
|||
|
|
|
|||
|
|
• Transient supports infix arguments; values that are set by infix
|
|||
|
|
commands and then consumed by the invoked suffix command(s).
|
|||
|
|
|
|||
|
|
To my knowledge, Hydra does not support that.
|
|||
|
|
|
|||
|
|
Both packages make it possible to specify how exactly the available
|
|||
|
|
commands are outlined:
|
|||
|
|
|
|||
|
|
• With Hydra this is often done using an explicit format string,
|
|||
|
|
which gives authors a lot of flexibility and makes it possible to
|
|||
|
|
do fancy things.
|
|||
|
|
|
|||
|
|
The downside of this is that it becomes harder for a user to add
|
|||
|
|
additional commands to an existing hydra and to change key
|
|||
|
|
bindings.
|
|||
|
|
|
|||
|
|
• Transient allows the author of a transient to organize the commands
|
|||
|
|
into groups and the use of generic functions allows authors of
|
|||
|
|
transients to control exactly how a certain command type is
|
|||
|
|
displayed.
|
|||
|
|
|
|||
|
|
However while Transient supports giving sections a heading it does
|
|||
|
|
not currently support giving the displayed information more
|
|||
|
|
structure by, for example, using box-drawing characters.
|
|||
|
|
|
|||
|
|
That could be implemented by defining a new group class, which lets
|
|||
|
|
the author specify a format string. It should be possible to
|
|||
|
|
implement that without modifying any existing code, but it does not
|
|||
|
|
currently exist.
|
|||
|
|
|
|||
|
|
|
|||
|
|
File: transient.info, Node: FAQ, Next: Keystroke Index, Prev: Related Abstractions and Packages, Up: Top
|
|||
|
|
|
|||
|
|
Appendix A FAQ
|
|||
|
|
**************
|
|||
|
|
|
|||
|
|
A.1 Can I control how the popup buffer is displayed?
|
|||
|
|
====================================================
|
|||
|
|
|
|||
|
|
Yes, see ‘transient-display-buffer-action’ in *note Configuration::.
|
|||
|
|
|
|||
|
|
A.2 Why did some of the key bindings change?
|
|||
|
|
============================================
|
|||
|
|
|
|||
|
|
You may have noticed that the bindings for some of the common commands
|
|||
|
|
do *not* have the prefix ‘C-x’ and that furthermore some of these
|
|||
|
|
commands are grayed out while others are not. That unfortunately is a
|
|||
|
|
bit confusing if the section of common commands is not shown
|
|||
|
|
permanently, making the following explanation necessary.
|
|||
|
|
|
|||
|
|
The purpose of usually hiding that section but showing it after the
|
|||
|
|
user pressed the respective prefix key is to conserve space and not
|
|||
|
|
overwhelm users with too much noise, while allowing the user to quickly
|
|||
|
|
list common bindings on demand.
|
|||
|
|
|
|||
|
|
That however should not keep us from using the best possible key
|
|||
|
|
bindings. The bindings that do use a prefix do so to avoid wasting too
|
|||
|
|
many non-prefix bindings, keeping them available for use in individual
|
|||
|
|
transients. The bindings that do not use a prefix and that are *not*
|
|||
|
|
grayed out are very important bindings that are *always* available, even
|
|||
|
|
when invoking the "common command key prefix" or *any other*
|
|||
|
|
transient-specific prefix. The non-prefix keys that *are* grayed out
|
|||
|
|
however, are not available when any incomplete prefix key sequence is
|
|||
|
|
active. They do not use the "common command key prefix" because it is
|
|||
|
|
likely that users want to invoke them several times in a row and e.g.,
|
|||
|
|
‘M-p M-p M-p’ is much more convenient than ‘C-x M-p C-x M-p C-x M-p’.
|
|||
|
|
|
|||
|
|
You may also have noticed that the "Set" command is bound to ‘C-x s’,
|
|||
|
|
while Magit-Popup used to bind ‘C-c C-c’ instead. I have seen several
|
|||
|
|
users praise the latter binding (sic), so I did not change it
|
|||
|
|
willy-nilly. The reason that I changed it is that using different
|
|||
|
|
prefix keys for different common commands, would have made the temporary
|
|||
|
|
display of the common commands even more confusing, i.e., after pressing
|
|||
|
|
‘C-c’ all the ‘C-x ...’ bindings would be grayed out.
|
|||
|
|
|
|||
|
|
Using a single prefix for common commands key means that all other
|
|||
|
|
potential prefix keys can be used for transient-specific commands
|
|||
|
|
*without* the section of common commands also popping up. ‘C-c’ in
|
|||
|
|
particular is a prefix that I want to (and already do) use for Magit,
|
|||
|
|
and also using that for a common command would prevent me from doing so.
|
|||
|
|
|
|||
|
|
(Also see the next question.)
|
|||
|
|
|
|||
|
|
A.3 Why does ‘q’ not quit popups anymore?
|
|||
|
|
=========================================
|
|||
|
|
|
|||
|
|
I agree that ‘q’ is a good binding for commands that quit something.
|
|||
|
|
This includes quitting whatever transient is currently active, but it
|
|||
|
|
also includes quitting whatever it is that some specific transient is
|
|||
|
|
controlling. The transient ‘magit-blame’ for example binds ‘q’ to the
|
|||
|
|
command that turns ‘magit-blame-mode’ off.
|
|||
|
|
|
|||
|
|
So I had to decide if ‘q’ should quit the active transient (like
|
|||
|
|
Magit-Popup used to) or whether ‘C-g’ should do that instead, so that
|
|||
|
|
‘q’ could be bound in individual transient to whatever commands make
|
|||
|
|
sense for them. Because all other letters are already reserved for use
|
|||
|
|
by individual transients, I have decided to no longer make an exception
|
|||
|
|
for ‘q’.
|
|||
|
|
|
|||
|
|
If you want to get ‘q’’s old binding back then you can do so. Doing
|
|||
|
|
that is a bit more complicated than changing a single key binding, so I
|
|||
|
|
have implemented a function, ‘transient-bind-q-to-quit’ that makes the
|
|||
|
|
necessary changes. See its doc string for more information.
|
|||
|
|
|
|||
|
|
|
|||
|
|
File: transient.info, Node: Keystroke Index, Next: Command and Function Index, Prev: FAQ, Up: Top
|
|||
|
|
|
|||
|
|
Appendix B Keystroke Index
|
|||
|
|
**************************
|
|||
|
|
|
|||
|
|
[index ]
|
|||
|
|
* Menu:
|
|||
|
|
|
|||
|
|
* C-g: Aborting and Resuming Transients.
|
|||
|
|
(line 27)
|
|||
|
|
* C-g <1>: Aborting and Resuming Transients.
|
|||
|
|
(line 27)
|
|||
|
|
* C-h: Getting Help for Suffix Commands.
|
|||
|
|
(line 11)
|
|||
|
|
* C-M-n: Using History. (line 18)
|
|||
|
|
* C-M-p: Using History. (line 13)
|
|||
|
|
* C-q: Aborting and Resuming Transients.
|
|||
|
|
(line 36)
|
|||
|
|
* C-x C-k: Saving Values. (line 29)
|
|||
|
|
* C-x C-s: Saving Values. (line 25)
|
|||
|
|
* C-x l: Enabling and Disabling Suffixes.
|
|||
|
|
(line 43)
|
|||
|
|
* C-x n: Using History. (line 18)
|
|||
|
|
* C-x p: Using History. (line 13)
|
|||
|
|
* C-x s: Saving Values. (line 21)
|
|||
|
|
* C-x t: Common Suffix Commands.
|
|||
|
|
(line 18)
|
|||
|
|
* C-z: Aborting and Resuming Transients.
|
|||
|
|
(line 41)
|
|||
|
|
|
|||
|
|
|
|||
|
|
File: transient.info, Node: Command and Function Index, Next: Variable Index, Prev: Keystroke Index, Up: Top
|
|||
|
|
|
|||
|
|
Appendix C Command and Function Index
|
|||
|
|
*************************************
|
|||
|
|
|
|||
|
|
[index ]
|
|||
|
|
* Menu:
|
|||
|
|
|
|||
|
|
* transient--do-call: Transient State. (line 99)
|
|||
|
|
* transient--do-exit: Transient State. (line 91)
|
|||
|
|
* transient--do-noop: Transient State. (line 147)
|
|||
|
|
* transient--do-quit-all: Transient State. (line 158)
|
|||
|
|
* transient--do-quit-one: Transient State. (line 153)
|
|||
|
|
* transient--do-recurse: Transient State. (line 106)
|
|||
|
|
* transient--do-replace: Transient State. (line 118)
|
|||
|
|
* transient--do-return: Transient State. (line 94)
|
|||
|
|
* transient--do-stay: Transient State. (line 83)
|
|||
|
|
* transient--do-suspend: Transient State. (line 125)
|
|||
|
|
* transient--do-suspend <1>: Transient State. (line 163)
|
|||
|
|
* transient--do-warn: Transient State. (line 144)
|
|||
|
|
* transient--history-init: Prefix Classes. (line 10)
|
|||
|
|
* transient--insert-group: Group Methods. (line 19)
|
|||
|
|
* transient-append-suffix: Modifying Existing Transients.
|
|||
|
|
(line 46)
|
|||
|
|
* transient-arg-value: Using Infix Arguments.
|
|||
|
|
(line 31)
|
|||
|
|
* transient-args: Using Infix Arguments.
|
|||
|
|
(line 22)
|
|||
|
|
* transient-define-argument: Defining Suffix and Infix Commands.
|
|||
|
|
(line 61)
|
|||
|
|
* transient-define-infix: Defining Suffix and Infix Commands.
|
|||
|
|
(line 26)
|
|||
|
|
* transient-define-prefix: Defining Transients. (line 13)
|
|||
|
|
* transient-define-suffix: Defining Suffix and Infix Commands.
|
|||
|
|
(line 9)
|
|||
|
|
* transient-format: Suffix Format Methods.
|
|||
|
|
(line 6)
|
|||
|
|
* transient-format-description: Suffix Format Methods.
|
|||
|
|
(line 18)
|
|||
|
|
* transient-format-key: Suffix Format Methods.
|
|||
|
|
(line 14)
|
|||
|
|
* transient-format-value: Suffix Format Methods.
|
|||
|
|
(line 22)
|
|||
|
|
* transient-get-suffix: Modifying Existing Transients.
|
|||
|
|
(line 56)
|
|||
|
|
* transient-help: Getting Help for Suffix Commands.
|
|||
|
|
(line 11)
|
|||
|
|
* transient-history-next: Using History. (line 18)
|
|||
|
|
* transient-history-prev: Using History. (line 13)
|
|||
|
|
* transient-infix-read: Suffix Value Methods.
|
|||
|
|
(line 16)
|
|||
|
|
* transient-infix-set: Suffix Value Methods.
|
|||
|
|
(line 36)
|
|||
|
|
* transient-infix-value: Suffix Value Methods.
|
|||
|
|
(line 39)
|
|||
|
|
* transient-init-scope: Suffix Value Methods.
|
|||
|
|
(line 52)
|
|||
|
|
* transient-init-value: Suffix Value Methods.
|
|||
|
|
(line 6)
|
|||
|
|
* transient-insert-suffix: Modifying Existing Transients.
|
|||
|
|
(line 42)
|
|||
|
|
* transient-prompt: Suffix Value Methods.
|
|||
|
|
(line 32)
|
|||
|
|
* transient-quit-all: Aborting and Resuming Transients.
|
|||
|
|
(line 36)
|
|||
|
|
* transient-quit-one: Aborting and Resuming Transients.
|
|||
|
|
(line 27)
|
|||
|
|
* transient-quit-seq: Aborting and Resuming Transients.
|
|||
|
|
(line 27)
|
|||
|
|
* transient-remove-suffix: Modifying Existing Transients.
|
|||
|
|
(line 53)
|
|||
|
|
* transient-replace-suffix: Modifying Existing Transients.
|
|||
|
|
(line 49)
|
|||
|
|
* transient-resume: Aborting and Resuming Transients.
|
|||
|
|
(line 53)
|
|||
|
|
* transient-save: Saving Values. (line 25)
|
|||
|
|
* transient-save <1>: Saving Values. (line 29)
|
|||
|
|
* transient-scroll-down: Other Commands. (line 17)
|
|||
|
|
* transient-scroll-up: Other Commands. (line 12)
|
|||
|
|
* transient-set: Saving Values. (line 21)
|
|||
|
|
* transient-set-level: Enabling and Disabling Suffixes.
|
|||
|
|
(line 43)
|
|||
|
|
* transient-setup-children: Group Methods. (line 6)
|
|||
|
|
* transient-show-help: Suffix Format Methods.
|
|||
|
|
(line 26)
|
|||
|
|
* transient-suffix-put: Modifying Existing Transients.
|
|||
|
|
(line 60)
|
|||
|
|
* transient-suffixes: Using Infix Arguments.
|
|||
|
|
(line 38)
|
|||
|
|
* transient-suspend: Aborting and Resuming Transients.
|
|||
|
|
(line 41)
|
|||
|
|
* transient-toggle-common: Common Suffix Commands.
|
|||
|
|
(line 18)
|
|||
|
|
|
|||
|
|
|
|||
|
|
File: transient.info, Node: Variable Index, Next: Concept Index, Prev: Command and Function Index, Up: Top
|
|||
|
|
|
|||
|
|
Appendix D Variable Index
|
|||
|
|
*************************
|
|||
|
|
|
|||
|
|
[index ]
|
|||
|
|
* Menu:
|
|||
|
|
|
|||
|
|
* transient-align-variable-pitch: Configuration. (line 181)
|
|||
|
|
* transient-current-command: Using Infix Arguments.
|
|||
|
|
(line 57)
|
|||
|
|
* transient-current-prefix: Using Infix Arguments.
|
|||
|
|
(line 52)
|
|||
|
|
* transient-current-suffixes: Using Infix Arguments.
|
|||
|
|
(line 44)
|
|||
|
|
* transient-default-level: Enabling and Disabling Suffixes.
|
|||
|
|
(line 33)
|
|||
|
|
* transient-detect-key-conflicts: Configuration. (line 206)
|
|||
|
|
* transient-display-buffer-action: Configuration. (line 51)
|
|||
|
|
* transient-enable-popup-navigation: Configuration. (line 36)
|
|||
|
|
* transient-force-fixed-pitch: Configuration. (line 194)
|
|||
|
|
* transient-force-single-column: Configuration. (line 93)
|
|||
|
|
* transient-hide-during-minibuffer-read: Configuration. (line 177)
|
|||
|
|
* transient-highlight-higher-levels: Configuration. (line 219)
|
|||
|
|
* transient-highlight-mismatched-keys: Configuration. (line 131)
|
|||
|
|
* transient-history-file: Using History. (line 33)
|
|||
|
|
* transient-history-limit: Using History. (line 37)
|
|||
|
|
* transient-levels-file: Enabling and Disabling Suffixes.
|
|||
|
|
(line 38)
|
|||
|
|
* transient-mode-line-format: Configuration. (line 102)
|
|||
|
|
* transient-read-with-initial-input: Configuration. (line 170)
|
|||
|
|
* transient-semantic-coloring: Configuration. (line 118)
|
|||
|
|
* transient-show-common-commands: Common Suffix Commands.
|
|||
|
|
(line 23)
|
|||
|
|
* transient-show-popup: Configuration. (line 15)
|
|||
|
|
* transient-substitute-key-function: Configuration. (line 149)
|
|||
|
|
* transient-values-file: Saving Values. (line 31)
|
|||
|
|
|
|||
|
|
|
|||
|
|
File: transient.info, Node: Concept Index, Prev: Variable Index, Up: Top
|
|||
|
|
|
|||
|
|
Appendix E Concept Index
|
|||
|
|
************************
|
|||
|
|
|
|||
|
|
[index ]
|
|||
|
|
* Menu:
|
|||
|
|
|
|||
|
|
* aborting transients: Aborting and Resuming Transients.
|
|||
|
|
(line 6)
|
|||
|
|
* classes and methods: Classes and Methods. (line 6)
|
|||
|
|
* command dispatchers: Introduction. (line 70)
|
|||
|
|
* common suffix commands: Common Suffix Commands.
|
|||
|
|
(line 6)
|
|||
|
|
* defining infix commands: Defining Suffix and Infix Commands.
|
|||
|
|
(line 6)
|
|||
|
|
* defining suffix commands: Defining Suffix and Infix Commands.
|
|||
|
|
(line 6)
|
|||
|
|
* disabling suffixes: Enabling and Disabling Suffixes.
|
|||
|
|
(line 6)
|
|||
|
|
* enabling suffixes: Enabling and Disabling Suffixes.
|
|||
|
|
(line 6)
|
|||
|
|
* getting help: Getting Help for Suffix Commands.
|
|||
|
|
(line 6)
|
|||
|
|
* group specifications: Group Specifications. (line 6)
|
|||
|
|
* invoking transients: Invoking Transients. (line 6)
|
|||
|
|
* levels: Enabling and Disabling Suffixes.
|
|||
|
|
(line 10)
|
|||
|
|
* modifying existing transients: Modifying Existing Transients.
|
|||
|
|
(line 6)
|
|||
|
|
* quit transient: Aborting and Resuming Transients.
|
|||
|
|
(line 6)
|
|||
|
|
* resuming transients: Aborting and Resuming Transients.
|
|||
|
|
(line 6)
|
|||
|
|
* saving values of arguments: Saving Values. (line 6)
|
|||
|
|
* scope of a transient: Defining Transients. (line 43)
|
|||
|
|
* suffix specifications: Suffix Specifications.
|
|||
|
|
(line 6)
|
|||
|
|
* transient prefix command: Introduction. (line 13)
|
|||
|
|
* transient state: Transient State. (line 6)
|
|||
|
|
* transient-level: Enabling and Disabling Suffixes.
|
|||
|
|
(line 15)
|
|||
|
|
* value history: Using History. (line 6)
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
Tag Table:
|
|||
|
|
Node: Top751
|
|||
|
|
Node: Introduction3662
|
|||
|
|
Node: Usage9475
|
|||
|
|
Node: Invoking Transients9843
|
|||
|
|
Node: Aborting and Resuming Transients10922
|
|||
|
|
Node: Common Suffix Commands13529
|
|||
|
|
Node: Saving Values15363
|
|||
|
|
Ref: Saving Values-Footnote-116732
|
|||
|
|
Node: Using History16925
|
|||
|
|
Node: Getting Help for Suffix Commands18499
|
|||
|
|
Node: Enabling and Disabling Suffixes19867
|
|||
|
|
Node: Other Commands22922
|
|||
|
|
Node: Configuration23898
|
|||
|
|
Ref: Essential Options24178
|
|||
|
|
Ref: Accessibility Options27829
|
|||
|
|
Ref: Auxiliary Options28152
|
|||
|
|
Ref: Developer Options32871
|
|||
|
|
Node: Modifying Existing Transients34119
|
|||
|
|
Node: Defining New Commands37508
|
|||
|
|
Node: Defining Transients37844
|
|||
|
|
Node: Binding Suffix and Infix Commands40276
|
|||
|
|
Node: Group Specifications41130
|
|||
|
|
Node: Suffix Specifications45473
|
|||
|
|
Node: Defining Suffix and Infix Commands49731
|
|||
|
|
Node: Using Infix Arguments52925
|
|||
|
|
Node: Transient State55753
|
|||
|
|
Ref: Pre-commands for Infixes59660
|
|||
|
|
Ref: Pre-commands for Suffixes59931
|
|||
|
|
Ref: Pre-commands for Non-Suffixes61700
|
|||
|
|
Ref: Special Pre-Commands62313
|
|||
|
|
Node: Classes and Methods62821
|
|||
|
|
Node: Group Classes65035
|
|||
|
|
Node: Group Methods66951
|
|||
|
|
Node: Prefix Classes68204
|
|||
|
|
Node: Suffix Classes69295
|
|||
|
|
Node: Suffix Methods71539
|
|||
|
|
Node: Suffix Value Methods71860
|
|||
|
|
Node: Suffix Format Methods74614
|
|||
|
|
Node: Prefix Slots76063
|
|||
|
|
Ref: Internal Prefix Slots77338
|
|||
|
|
Node: Suffix Slots78595
|
|||
|
|
Ref: Slots of transient-suffix78963
|
|||
|
|
Ref: Slots of transient-infix79817
|
|||
|
|
Ref: Slots of transient-variable82937
|
|||
|
|
Ref: Slots of transient-switches83039
|
|||
|
|
Node: Predicate Slots83402
|
|||
|
|
Node: Related Abstractions and Packages84657
|
|||
|
|
Node: Comparison With Prefix Keys and Prefix Arguments84944
|
|||
|
|
Ref: Regular Prefix Commands85629
|
|||
|
|
Ref: Regular Prefix Arguments85977
|
|||
|
|
Ref: Transients86946
|
|||
|
|
Node: Comparison With Other Packages95217
|
|||
|
|
Ref: Magit-Popup95448
|
|||
|
|
Ref: Hydra96347
|
|||
|
|
Node: FAQ99383
|
|||
|
|
Ref: Can I control how the popup buffer is displayed?99526
|
|||
|
|
Ref: Why did some of the key bindings change?99707
|
|||
|
|
Ref: Why does q not quit popups anymore?102025
|
|||
|
|
Node: Keystroke Index103118
|
|||
|
|
Node: Command and Function Index104836
|
|||
|
|
Node: Variable Index111135
|
|||
|
|
Node: Concept Index113408
|
|||
|
|
|
|||
|
|
End Tag Table
|
|||
|
|
|
|||
|
|
|
|||
|
|
Local Variables:
|
|||
|
|
coding: utf-8
|
|||
|
|
End:
|