1 [![Build Status](https://travis-ci.org/abo-abo/hydra.svg?branch=master)](https://travis-ci.org/abo-abo/hydra)
3 This is a package for GNU Emacs that can be used to tie related
4 commands into a family of short bindings with a common prefix - a
7 ![hydra](http://oremacs.com/download/Hydra.png)
9 Once you summon the Hydra through the prefixed binding (the body + any
10 one head), all heads can be called in succession with only a short
13 The Hydra is vanquished once Hercules, any binding that isn't the
14 Hydra's head, arrives. Note that Hercules, besides vanquishing the
15 Hydra, will still serve his orignal purpose, calling his proper
16 command. This makes the Hydra very seamless, it's like a minor mode
17 that disables itself auto-magically.
21 Here's how to quickly bind the examples bundled with Hydra:
24 (require 'hydra-examples)
25 (hydra-create "C-M-y" hydra-example-move-window-splitter)
26 (hydra-create "M-g" hydra-example-goto-error)
27 (hydra-create "<f2>" hydra-example-text-scale)
30 ## Using Hydra for global bindings
32 But it's much better to just take the examples as a template and write
33 down everything explicitly:
36 (defhydra hydra-zoom (global-map "<f2>")
38 ("g" text-scale-increase "in")
39 ("l" text-scale-decrease "out"))
42 With the example above, you can e.g.:
45 (key-chord-define-global "tt" 'hydra-zoom/body)
48 In fact, since `defhydra` returns the body symbol, you can even write
52 (key-chord-define-global
54 (defhydra hydra-zoom (global-map "<f2>")
56 ("g" text-scale-increase "in")
57 ("l" text-scale-decrease "out")))
60 If you like key chords so much that you don't want to touch the global
61 map at all, you can e.g.:
64 (key-chord-define-global
66 (defhydra hydra-error ()
68 ("h" first-error "first")
69 ("j" next-error "next")
70 ("k" previous-error "prev")))
73 You can also substitute `global-map` with any other keymap, like
74 `c++-mode-map` or `yas-minor-mode-map`.
76 See the [introductory blog post](http://oremacs.com/2015/01/20/introducing-hydra/) for more information.
78 ## Using Hydra for major-mode or minor-mode bindings
83 (defhydra lispy-vi (lispy-mode-map "C-z")
91 ## Can Hydras can be helpful?
96 (setq hydra-is-helpful t)
99 This is the default setting. In this case, you'll get a hint in the
100 echo area consisting of current Hydra's base comment and heads. You
101 can even add comments to the heads like this:
104 (defhydra hydra-zoom (global-map "<f2>")
106 ("g" text-scale-increase "in")
107 ("l" text-scale-decrease "out"))
110 With this, you'll see `zoom: [g]: in, [l]: out.` in your echo area,
111 once the zoom Hydra becomes active.
115 Since version `0.5.0`, Hydra's heads all have a color associated with them:
117 - *red* (default) means the calling this head will not vanquish the Hydra
118 - *blue* means that the Hydra will be vanquished after calling this head
120 In all the older examples, all heads are red by default. You can specify blue heads like this:
127 ("a" abbrev-mode "abbrev" :color blue)
128 ("d" toggle-debug-on-error "debug" :color blue)
129 ("f" auto-fill-mode "fill" :color blue)
130 ("t" toggle-truncate-lines "truncate" :color blue)
131 ("w" whitespace-mode "whitespace" :color blue)
135 Or, since the heads can inherit the color from the body, the following is equivalent:
140 (defhydra toggle (:color blue)
142 ("a" abbrev-mode "abbrev")
143 ("d" toggle-debug-on-error "debug")
144 ("f" auto-fill-mode "fill")
145 ("t" toggle-truncate-lines "truncate")
146 ("w" whitespace-mode "whitespace")
150 The above Hydra is very similar to this code:
153 (global-set-key (kbd "C-c C-v t") 'toggle-truncate-lines)
154 (global-set-key (kbd "C-c C-v f") 'auto-fill-mode)
155 (global-set-key (kbd "C-c C-v a") 'abbrev-mode)
158 However, there are two important differences:
160 - you get a hint like this right after <kbd>C-c C-v</kbd>:
162 toggle: [t]: truncate, [f]: fill, [a]: abbrev, [q]: cancel.
164 - you can cancel <kbd>C-c C-v</kbd> with a command while executing that command, instead of e.g.
165 getting an error `C-c C-v C-n is undefined` for <kbd>C-c C-v C-n</kbd>.