GNU ELPA - transient

transient

Description
Transient commands
Latest
transient-0.4.3.tar, 2023-Aug-25, 530 KiB
Maintainer
Jonas Bernoulli <jonas@bernoul.li>
Website
https://github.com/magit/transient
Browse ELPA's repository
CGit or Gitweb
Badge
Manual
transient

To install this package, run in Emacs:

M-x package-install RET transient RET

Full description

1. Transient commands

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 Transient's documentation, 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, then 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. 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 it 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.

transient.png



Compile Manual GNU ELPA MELPA Stable MELPA

Old versions

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.4.3    2023-08-25

- Added a second implementation of ~transient--wrap-command~, taking
  advantage of improvements in Emacs 30.

* v0.4.2    2023-08-25

- Infix commands are only useful when invoked from a transient prefix
  command and ~execute-extended-command~ should not offer them as
  completion candidates.  In the past we used a weird kludge to
  accomplish that, but now we rely on ~read-extended-command-predicate~.
  That allowed the removal of some complications and made it possible
  to fix a bug in ~transient--wrap-command~.

  To hide infix commands, users now have to update to Emacs 28, or
  later, and customize ~read-extended-command-predicate~.

  #+begin_src emacs-lisp
    (setq read-extended-command-predicate
          'command-completion-default-include-p)
  #+end_src

- Due to changes in Emacs 29.1, pretty-printing isn't consistent
  across Emacs releases anymore by default, which is unfortunate
  in our case because we use it to write to files that are likely
  to be checked into version control.  We now force the use of the
  old style across releases.

* v0.4.1    2023-06-02

Bug fixes:

- 070d47b0 Support searches that end right after suffix
- ab831828 transient--insert-group(columns): Drop separator before first column
- 62edeffd #247 Fix bug using :incompatible using suffixes before infixes
- 6efa9fad transient-predicate-map: Bind univeral-argument-more

* v0.4.0    2023-05-10

- Transient has to update state after every suffix command.  If that
  fails for some reason, then Emacs ends up in an badly broken state.
  It was rare, but in the worst case scenario, that meant that Emacs
  refused to call any more commands and had to be killed.

  Naturally ~post-command-hook~ is the first choice to run something
  after commands, but unfortunately that hook is not guaranteed to run
  only once, and worse it is not guaranteed run /after/ the command.
  Working around this limitation made an essential part of Transient
  much more complex and fragile.  As new edge-cases were discovered,
  new and increasingly desperate heuristics had to be added, until I
  finally decided that relying solely on hooks was just not feasible.

  Now ~pre-command-hook~ is used to advice ~this-command~, to add an
  around advice, which ensures that the state update takes place, even
  when ~post-command-hook~ is run prematurely.  The advice wraps both
  the function body and the interactive spec with ~unwind-protect~, so
  we can finally be sure that the state change is always performed,
  and that the advice is removed again.

  It has been an interesting journey, and I have documented it in long
  commit messages.  If you are interested in the details, see 7b8a7d71
  (which still tries to avoid using any advice), 51c68c87, 52cac9c0,
  bug#61179 and bug#61176.

- The ~transient-define-prefix~ now expands to code instead of data,
  meaning that lambda expressions are finally properly evaluated and
  byte-compiled.  ea851f3b e88f51d6 277e5f2d a1774182

- Popup navigation is no longer considered a second-class feature and
  is enabled by default.  Some transients allow arbitrary non-suffixes
  to be invoked, so some key bindings, which were previously used for
  popup navigation, had to be removed, to avoid conflicts.  98d50202 ff

- Each prefix and suffix can now have its own help function.  This is
  configured using the new ~show-help~ slot.  ea5ac99f

- The ~transient-options~ class now supports two types of options that
  can have multiple values: repeated option-value pairs and a final
  option that takes all remaining arguments as value.  #154

- Added support for the use of non-proportional text in the transient
  popup.  7f5520b3

- Imenu was taught about Transient's definition macros.  #178

- It is now possible to return to the parent prefix from a sub-prefix.
  e90f7a16

- Boolean values of the ~transient~ slot of sub-prefixes are now
  interpreted correctly.  4a36b1d9

- Added new option ~transient-hide-during-minibuffer-read~.  5762bd9a
...
...