transient 
- Description
- Transient commands
- Latest
- transient-0.7.8.tar (.sig), 2024-Nov-02, 560 KiB
- Maintainer
- Jonas Bernoulli <emacs.transient@jonas.bernoulli.dev>
- 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.7.7.tar.lz | 2024-Oct-05 | 95.1 KiB |
| transient-0.7.6.tar.lz | 2024-Oct-02 | 94.9 KiB |
| transient-0.7.5.tar.lz | 2024-Sep-01 | 94.5 KiB |
| transient-0.7.4.tar.lz | 2024-Aug-05 | 94.6 KiB |
| transient-0.7.3.tar.lz | 2024-Jul-14 | 94.1 KiB |
| transient-0.7.2.tar.lz | 2024-Jun-24 | 93.6 KiB |
| transient-0.7.1.tar.lz | 2024-Jun-19 | 93.2 KiB |
| transient-0.7.0.tar.lz | 2024-Jun-18 | 93.1 KiB |
| transient-0.6.0.tar.lz | 2024-Mar-31 | 92.1 KiB |
| 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.0.tar.lz | 2021-Feb-27 | 68.2 KiB |
News
# -*- mode: org -*- * v0.7.8 2024-11-02 - Additional potential mistakes in menu definitions are now detected. bbda5bb6, 8873c300 - Added new (and still experimental) ~environment~ prefix slot, which can be used to, for example, implement a cache to be used while refreshing the menu. 05c011b8 - When navigating through the menu using the keyboard or hovering a suffix command with the mouse, information about the command is now shown in the echo area or using a tooltip. #282 Bug fixes: - When the command that exits a transient uses the minibuffer, ~transient-current-*~ variables were not immediately reset to ~nil~. #323 - Key sequences with three or more events broke ~transient-suffix-object~. #324 * v0.7.7 2024-10-04 Bug fix: - Fix a regression introduced by the previous commit, which broke dynamic prefixes that use a ~:setup-children~ function to prepare their suffixes. #313 * v0.7.6 2024-10-01 - ~transient-active-prefix~ now accepts a single prefix symbol, in place of a list of such symbols. #307 - ~other-frame-prefix~ and ~other-window-prefix~ can now be used while a transient prefix is active. #305 - Added new macro ~transient-with-help-window~ for use in ~:show-help~ functions. #309 * v0.7.5 2024-09-01 - Updated tooling. Bug fixes: - ~static-if~ is now used correctly. 0e35673e - When an existing window ends up being used to display the transient buffer, then the previous value of the ~no-other-window~ parameter is now restored, when the transient is exited. #302 - The names assigned to suffixes, which are defined using lambdas in the prefix definition, are now guaranteed to be unique. #304 * v0.7.4 2024-08-05 - Added new function ~transient-active-prefix~. * v0.7.3 2024-07-13 - Refactored code responsible for inserting columns. Bug fix: - The ~transient-current-*~ variables are intended to only be used by suffix commands, when they are invoked from a prefix. Previously they were only cleared when the prefix is ultimately exited, which meant that they unintentionally were accessible in timers. Now the values of these variables are nil when used outside their intended scope. 0e0ece32, f2cb28a5 * v0.7.2 2024-06-24 - Added support for adding suffixes that activate value presets. #183 Bug fix: - Restored the ability to individually set infix arguments if the prefix's ~refresh-suffixes~ slot is non-nil. 8db5f0fd * v0.7.1 2024-06-19 - Added a workaround for ~emoji.el~ from Emacs 29.1 calling an internal function using an outdated number of arguments. #288 * v0.7.0 2024-06-18 - Added new macro ~transient-augment-suffix~, which can be used to specify the suffix behavior of a command that was previously defined as a prefix, using ~transient-define-prefix~. 2fd3ea14 - Added new function ~transient-scope~, which is just a convenient way to get the value of the ~scope~ slot of the ~transient-prefix-object~. 7f6c39c5 - Added new hook ~transient-setup-buffer-hook~, which is run early when setting the transient menu buffer. #283 - Added new class ~transient-information*~, a variant of recently added ~transient-information~ class. 8a80e952 - By default our macros that define commands, mark those as for interactive use only. ~(declare (interactive-only nil))~ can now be used to overwrite that. fcc60e27 - Groups now also accept ~:inapt*~ predicates. 3d395d64 - Spaces between columns is reduced from three to two. dd93001e - Removed unused ~transient-plist-to-alist~ function. 1251faf0 Bug fixes: - ~transient--force-fixed-pitch~ was run to late to always succeed. #283 - Key binding conflict detection was too strict, taking hypothetical bindings for inapt commands into account. c356d1bc - Key binding conflict detection did not consider bindings in regular keymaps, such as ~transient-base-map~. 2698d62d - ~func-arity~ gets confused when a function is advised, so we had to add a wrapper function ~transient--func-arity~. 91dd7bb3 ... ...