transient
- Description
- Transient commands
- Latest
- transient-0.6.0.tar (.sig), 2024-Mar-31, 550 KiB
- Maintainer
- Jonas Bernoulli <jonas@bernoul.li>
- Atom feed
- transient.xml
- Website
- https://github.com/magit/transient
- Browse ELPA's repository
- CGit or Gitweb
- Badge
- Manual
- transient
To install this package from Emacs, use package-install
or list-packages
.
Full description
1. Transient command menus
Transient is the library used to implement the keyboard-driven “menus” in Magit. It is distributed as a separate package, so that it can be used to implement similar menus in other packages.
1.1. Some things that Transient can do
- Display current state of arguments
- Display and manage lifecycle of modal bindings
- Contextual user interface
- Flow control for wizard-like composition of interactive forms
- History & persistence
- Rendering arguments for controlling CLI programs
1.2. Complexity in CLI programs
Complexity tends to grow with time. How do you manage the complexity
of commands? Consider the humble shell command ls
. It now has over
fifty command line options. Some of these are boolean flags (ls -l
).
Some take arguments (ls --sort=s
). Some have no effect unless paired
with other flags (ls -lh
). Some are mutually exclusive. Some shell
commands even have so many options that they introduce subcommands
(git branch
, git commit
), each with their own rich set of options
(git branch -f
).
1.3. Using Transient for composing interactive commands
What about Emacs commands used interactively? How do these handle
options? One solution is to make many versions of the same command,
so you don't need to! Consider: delete-other-windows
vs.
delete-other-windows-vertically
(among many similar examples).
Some Emacs commands will simply prompt you for the next "argument"
(M-x switch-to-buffer
). Another common solution is to use prefix
arguments which usually start with C-u
. Sometimes these are sensibly
numerical in nature (C-u 4 M-x forward-paragraph
to move forward 4
paragraphs). But sometimes they function instead as boolean
"switches" (C-u C-SPACE
to jump to the last mark instead of just
setting it, C-u C-u C-SPACE
to unconditionally set the mark). Since
there aren't many standards for the use of prefix options, you have to
read the command's documentation to find out what the possibilities
are.
But when an Emacs command grows to have a truly large set of options
and arguments, with dependencies between them, lots of option values,
etc., these simple approaches just don't scale. Transient is designed
to solve this issue. Think of it as the humble prefix argument C-u
,
raised to the power of 10. Like C-u
, it is key driven. Like the
shell, it supports boolean "flag" options, options that take
arguments, and even "sub-commands", with their own options. But
instead of searching through a man page or command documentation,
well-designed transients guide their users to the relevant set of
options (and even their possible values!) directly, taking into
account any important pre-existing Emacs settings. And while for
shell commands like ls
, there is only one way to "execute" (hit
Return
!), transients can "execute" using multiple different keys tied
to one of many self-documenting actions (imagine having 5 different
colored return keys on your keyboard!). Transients make navigating
and setting large, complex groups of command options and arguments
easy. Fun even. Once you've tried it, it's hard to go back to the
C-u what can I do here again?
way.
Old versions
transient-0.5.3.tar.lz | 2023-Dec-16 | 90.2 KiB |
transient-0.5.2.tar.lz | 2023-Dec-05 | 90.1 KiB |
transient-0.5.0.tar.lz | 2023-Nov-28 | 88.8 KiB |
transient-0.4.3.tar.lz | 2023-Aug-25 | 86.4 KiB |
transient-0.4.1.tar.lz | 2023-Jun-03 | 86.0 KiB |
transient-0.4.0.tar.lz | 2023-May-10 | 85.8 KiB |
transient-0.3.7.tar.lz | 2021-Oct-25 | 69.8 KiB |
transient-0.3.6.tar.lz | 2021-Jul-01 | 68.9 KiB |
transient-0.3.5.tar.lz | 2021-Jun-16 | 68.4 KiB |
transient-0.3.4.tar.lz | 2021-May-25 | 68.4 KiB |
transient-0.3.2.tar.lz | 2021-Apr-20 | 68.4 KiB |
transient-0.3.0.tar.lz | 2021-Feb-27 | 68.2 KiB |
News
# -*- mode: org -*- * v0.6.0 2024-03-21 - On Emacs 28.1 and later, all infix commands and suffix commands that are defined inline (i.e., using a lambda when defining a prefix command), are now hidden from ~execute-extended-command~ (aka ~M-x~) /by default/. It was already possible to hide these commands, but users had to opt-in explicitly. After refactoring how these commands are declared to be unsuitable for ~M-x~, it is now possible to hide them /without/ also hiding other, unrelated kinds of unsuitable commands. I recommend that you instruct to hide /all/ unsuitable command. This requires that you customizing ~read-extended-command-predicate~, because the Emacs authors have decided that this should be an opt-in feature. Note that this has no effect on Emacs releases before 28.1. - Added documentation stating that ~:class~ has to be specified when using ~:setup-children~. beecdc85 - Added a new prefix slot ~column-widths~, which can be used to specify the minimal width of each column in all ~transient-columns~ groups of that prefix. 92e8952e - When assigning a name to a suffix that is defined inline, we no longer use the suffix description, iff that would result in an overly long name. 81a108ba - Functions used as the value of face slots can now take one argument, the suffix object. Functions that take zero arguments are still supported. Additionally, ~transient--pending-suffix~ is bound around calls to these functions, but it is better to pass the object as an argument. f582a9bc - The new ~definition~ suffix slot can be used to specify a default function definition that is used if no function body is provided using ~transient-define-suffix~. 5b334a51 - Taught ~transient-suffix-object~ about ~transient--pending-suffix~. 20a3770d Bug fixes: - If ~transient-parse-suffix~ and ~transient-parse-suffixes~ are called with an invalid value for their ~prefix~ argument, they failed to detect that. 03e752d9 - If ~nil~ is encountered inside a group specification, that was silently ignored. Now an error is signaled. 8c01a1eb - ~find-function~ wasn't able to locate the definitions of infix commands anymore. a30df67b - There was no binding for ~ignore-preserving-kill-region~ in ~transient-predicate-map~. 0fc87002 - Invoking a non-symbolic non-suffix command, caused an error. bd2a5ea0 - When a group begins with an included subgroup, that affected what group class was assumed, in the absence of an explicit specification. df36bc87 - ~transient--suspend-override~ failed to move out of the minibuffer before refreshing the transient buffer. 833143ba - When a suffix command signaled an error during a trivial phase (which does not involve, e.g., the minibuffer), then the transient window was not deleted when the debugger was entered. 9d8f361f - When a prefix was refreshed, the wrong color was used for suffix commands that exit the prefix, indicating that would cause a return to the outer prefix, even though there is none. f51c144a - Calling ~transient-infix-read~ with an invalid value, resulted in a confusing error. Now an appropriate error is used. 3ebb6acf - When third-party code or user customization managed to display another buffer in our dedicated window, then that buffer got killed when we tried to kill the transient buffer. #271 * v0.5.3 2023-12-16 - Fixed regression when setting ~:pad-keys~ for a ~transient-columns~ group. #269 * v0.5.2 2023-12-05 - Fixed formatting issues in the manual. * v0.5.1 2023-12-05 - Added a new introduction by JD Smith (@jdtsmith). Bug fixes: - Faces that use a box are now defined more defensively to protect against unexpected values and provide reasonable fallback colors. 413310cd, b8aefce3 - Only prepare to return to the parent transient if there actually is a parent. The only negative effect of failing to do this was that the suffix was colored wrong, since ~transient--do-return~ falls back ... ...