README-elpa (3889B)
1 1 Transient command menus 2 ═════════════════════════ 3 4 Transient is the library used to implement the keyboard-driven “menus” 5 in [Magit]. It is distributed as a separate package, so that it can 6 be used to implement similar menus in [other packages]. 7 8 9 [Magit] <https://github.com/magit/magit/> 10 11 [other packages] <https://melpa.org/#/transient> 12 13 1.1 Some things that Transient can do 14 ───────────────────────────────────── 15 16 • Display current state of arguments 17 • Display and manage lifecycle of modal bindings 18 • Contextual user interface 19 • Flow control for wizard-like composition of interactive forms 20 • History & persistence 21 • Rendering arguments for controlling CLI programs 22 23 24 1.2 Complexity in CLI programs 25 ────────────────────────────── 26 27 Complexity tends to grow with time. How do you manage the complexity 28 of commands? Consider the humble shell command `ls'. It now has over 29 /fifty/ command line options. Some of these are boolean flags (`ls 30 -l'). Some take arguments (`ls --sort=s'). Some have no effect 31 unless paired with other flags (`ls -lh'). Some are mutually 32 exclusive. Some shell commands even have so many options that they 33 introduce /subcommands/ (`git branch', `git commit'), each with their 34 own rich set of options (`git branch -f'). 35 36 37 1.3 Using Transient for composing interactive commands 38 ────────────────────────────────────────────────────── 39 40 What about Emacs commands used interactively? How do these handle 41 options? One solution is to make many versions of the same command, 42 so you don't need to! Consider: `delete-other-windows' vs. 43 `delete-other-windows-vertically' (among many similar examples). 44 45 Some Emacs commands will simply prompt you for the next "argument" 46 (`M-x switch-to-buffer'). Another common solution is to use prefix 47 arguments which usually start with `C-u'. Sometimes these are 48 sensibly numerical in nature (`C-u 4 M-x forward-paragraph' to move 49 forward 4 paragraphs). But sometimes they function instead as boolean 50 "switches" (`C-u C-SPACE' to jump to the last mark instead of just 51 setting it, `C-u C-u C-SPACE' to unconditionally set the mark). Since 52 there aren't many standards for the use of prefix options, you have to 53 read the command's documentation to find out what the possibilities 54 are. 55 56 But when an Emacs command grows to have a truly large set of options 57 and arguments, with dependencies between them, lots of option values, 58 etc., these simple approaches just don't scale. Transient is designed 59 to solve this issue. Think of it as the humble prefix argument `C-u', 60 /raised to the power of 10/. Like `C-u', it is key driven. Like the 61 shell, it supports boolean "flag" options, options that take 62 arguments, and even "sub-commands", with their own options. But 63 instead of searching through a man page or command documentation, 64 well-designed transients /guide/ their users to the relevant set of 65 options (and even their possible values!) directly, taking into 66 account any important pre-existing Emacs settings. And while for 67 shell commands like `ls', there is only one way to "execute" (hit 68 `Return'!), transients can "execute" using multiple different keys 69 tied to one of many self-documenting /actions/ (imagine having 5 70 different colored return keys on your keyboard!). Transients make 71 navigating and setting large, complex groups of command options and 72 arguments easy. Fun even. Once you've tried it, it's hard to go back 73 to the `C-u what can I do here again?' way. 74 75 <http://readme.emacsair.me/transient.png>