GNU ELPA - transient

transient Atom Feed

Description
Transient commands
Latest
transient-0.7.2.tar (.sig), 2024-Jun-24, 550 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.

transient.png



Compile Manual GNU ELPA MELPA Stable MELPA

Old versions

transient-0.7.1.tar.lz2024-Jun-1993.2 KiB
transient-0.7.0.tar.lz2024-Jun-1893.1 KiB
transient-0.6.0.tar.lz2024-Mar-3192.1 KiB
transient-0.5.3.tar.lz2023-Dec-1690.2 KiB
transient-0.5.2.tar.lz2023-Dec-0590.1 KiB
transient-0.5.0.tar.lz2023-Nov-2888.8 KiB
transient-0.4.3.tar.lz2023-Aug-2586.4 KiB
transient-0.4.1.tar.lz2023-Jun-0386.0 KiB
transient-0.4.0.tar.lz2023-May-1085.8 KiB
transient-0.3.7.tar.lz2021-Oct-2569.8 KiB
transient-0.3.6.tar.lz2021-Jul-0168.9 KiB
transient-0.3.5.tar.lz2021-Jun-1668.4 KiB
transient-0.3.4.tar.lz2021-May-2568.4 KiB
transient-0.3.2.tar.lz2021-Apr-2068.4 KiB
transient-0.3.0.tar.lz2021-Feb-2768.2 KiB

News

# -*- mode: org -*-
* 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

- Some mistakes, that can be expected to occur when defining suffix and
  prefix commands, were not detected.  7e827c31

* 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 ~M-x~ 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
...
...