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.
19 ## Sample global Hydras
23 (defhydra hydra-zoom (global-map "<f2>")
25 ("g" text-scale-increase "in")
26 ("l" text-scale-decrease "out"))
32 (defhydra hydra-error (global-map "M-g")
34 ("h" first-error "first")
35 ("j" next-error "next")
36 ("k" previous-error "prev")
37 ("v" recenter-top-bottom "recenter")
44 (require 'hydra-examples)
45 (defhydra hydra-splitter (global-map "C-M-s")
47 ("h" hydra-move-splitter-left)
48 ("j" hydra-move-splitter-down)
49 ("k" hydra-move-splitter-up)
50 ("l" hydra-move-splitter-right))
54 A few useful hydras are aggregated in projects [community wiki](https://github.com/abo-abo/hydra/wiki/Hydras%20by%20Topic). Feel free to add your own or edit existing ones.
56 ## Using the functions generated by `defhydra`
58 With the example above, you can e.g.:
61 (key-chord-define-global "tt" 'hydra-zoom/body)
64 In fact, since `defhydra` returns the body symbol, you can even write
68 (key-chord-define-global
70 (defhydra hydra-zoom (global-map "<f2>")
72 ("g" text-scale-increase "in")
73 ("l" text-scale-decrease "out")))
76 If you like key chords so much that you don't want to touch the global
77 map at all, you can e.g.:
80 (key-chord-define-global
82 (defhydra hydra-error ()
84 ("h" first-error "first")
85 ("j" next-error "next")
86 ("k" previous-error "prev")))
89 You can also substitute `global-map` with any other keymap, like
90 `c++-mode-map` or `yas-minor-mode-map`.
92 See the [introductory blog post](http://oremacs.com/2015/01/20/introducing-hydra/) for more information.
94 ## Using Hydra for major-mode or minor-mode bindings
99 (defhydra lispy-vi (lispy-mode-map "C-z")
107 ## Can Hydras can be helpful?
112 (setq hydra-is-helpful t)
115 This is the default setting. In this case, you'll get a hint in the
116 echo area consisting of current Hydra's base comment and heads. You
117 can even add comments to the heads like this:
120 (defhydra hydra-zoom (global-map "<f2>")
122 ("g" text-scale-increase "in")
123 ("l" text-scale-decrease "out"))
126 With this, you'll see `zoom: [g]: in, [l]: out.` in your echo area,
127 once the zoom Hydra becomes active.
131 Since version `0.5.0`, Hydra's heads all have a color associated with them:
133 - *red* (default) means the calling this head will not vanquish the Hydra
134 - *blue* means that the Hydra will be vanquished after calling this head
136 In all the older examples, all heads are red by default. You can specify blue heads like this:
143 ("a" abbrev-mode "abbrev" :color blue)
144 ("d" toggle-debug-on-error "debug" :color blue)
145 ("f" auto-fill-mode "fill" :color blue)
146 ("t" toggle-truncate-lines "truncate" :color blue)
147 ("w" whitespace-mode "whitespace" :color blue)
151 Or, since the heads can inherit the color from the body, the following is equivalent:
156 (defhydra toggle (:color blue)
158 ("a" abbrev-mode "abbrev")
159 ("d" toggle-debug-on-error "debug")
160 ("f" auto-fill-mode "fill")
161 ("t" toggle-truncate-lines "truncate")
162 ("w" whitespace-mode "whitespace")
166 The above Hydra is very similar to this code:
169 (global-set-key (kbd "C-c C-v t") 'toggle-truncate-lines)
170 (global-set-key (kbd "C-c C-v f") 'auto-fill-mode)
171 (global-set-key (kbd "C-c C-v a") 'abbrev-mode)
174 However, there are two important differences:
176 - you get a hint like this right after <kbd>C-c C-v</kbd>:
178 toggle: [t]: truncate, [f]: fill, [a]: abbrev, [q]: cancel.
180 - you can cancel <kbd>C-c C-v</kbd> with a command while executing that command, instead of e.g.
181 getting an error `C-c C-v C-n is undefined` for <kbd>C-c C-v C-n</kbd>.
183 ## Hydras and numeric arguments
185 Since version `0.6.0`, for any Hydra:
187 - `digit-argment` can be called with <kbd>0</kbd>-<kbd>9</kbd>.
188 - `negative-argument` can be called with <kbd>-</kbd>
189 - `universal-argument` can be called with <kbd>C-u</kbd>
191 ## Hydras can have `:pre` and `:post` statements
193 Since version `0.7.0`, you can specify code that will be called before each head, and
194 after the body. For example:
201 (set-cursor-color "#40e0d0")
204 (set-cursor-color "#ffffff")
206 "Thank you, come again.")))
215 ## New Hydra color: amaranth
217 Since version `0.8.0`, a new color - amaranth, in addition to the previous red and blue, is
218 available for the Hydra body.
220 According to [Wikipedia](http://en.wikipedia.org/wiki/Amaranth):
222 > The word amaranth comes from the Greek word amaranton, meaning "unwilting" (from the
223 > verb marainesthai, meaning "wilt"). The word was applied to amaranth because it did not
224 > soon fade and so symbolized immortality.
226 Hydras with amaranth body are impossible to quit with any binding *except* a blue head.
227 A check for at least one blue head exists in `defhydra`, so that you don't get stuck by accident.
229 Here's an example of an amaranth Hydra:
236 (set-cursor-color "#40e0d0")
238 (set-cursor-color "#ffffff")
248 The only way to exit it, is to press <kbd>q</kbd>. No other methods will work. You can
249 use an amaranth Hydra instead of a red one, if for you the cost of being able to exit only
250 though certain bindings is less than the cost of accidentally exiting a red Hydra by
251 pressing the wrong prefix.
253 Note that it does not make sense to define a single amaranth head, so this color can only
254 be assigned to the body. An amaranth body will always have some amaranth heads and some
255 blue heads (otherwise, it's impossible to exit), no reds.
257 ## Generate simple lambdas in-place:
259 Since version `0.9.0` it's possible to pass a single sexp instead of a function name or a lambda
260 to a head. This sexp will be wrapped in an interactive lambda. Here's an example:
263 (defhydra hydra-launcher (:color blue)
266 ("r" (browse-url "http://www.reddit.com/r/emacs/") "reddit")
267 ("w" (browse-url "http://www.emacswiki.org/") "emacswiki")
270 (global-set-key (kbd "C-c r") 'hydra-launcher/body)
273 ## Define Hydra heads that don't show up in the hint at all
275 This can be done by setting the head's hint explicitly to `nil`, instead of the usual string.
277 ## Use a dedicated window for Hydra hints
279 Since version `0.10.0`, setting `hydra-lv` to `t` (the default setting) will make it use a dedicated
280 window right above the Echo Area for hints. This has the advantage that you can immediately see
281 any `message` output from the functions that you call, since Hydra no longer uses `message` to display
282 the hint. You can still have the old behavior by setting `hydra-lv` to `nil`.
287 | Body Color | Head Inherited | Executing NON-HEADS | Executing HEADS |
288 |------------+----------------+-----------------------+-----------------|
289 | amaranth | red | Disallow and Continue | Continue |
290 | teal | blue | Disallow and Continue | Quit |
291 | pink | red | Allow and Continue | Continue |
292 | red | red | Allow and Quit | Continue |
293 | blue | blue | Allow and Quit | Quit |
295 ## Color to toggle correspondence
297 By popular demand, an alternative syntax has been implemented that translates to colors without
298 using them in the syntax. `:exit` can be used both in body (heads will inherit) and in heads
299 (possible to override body). `:exit` is nil by default, corresponding to `red` head; you don't need
300 to set it explicitly to nil. `:foreign-keys` can be used only in body and can be either nil (default),
304 |----------+----------------------------|
307 | amaranth | :foreign-keys warn |
308 | teal | :foreign-keys warn :exit t |
309 | pink | :foreign-keys run |