code.delx.au - gnu-emacs-elpa/blob - packages/hydra/README.md

   1 [![Build Status](https://travis-ci.org/abo-abo/hydra.svg?branch=master)](https://travis-ci.org/abo-abo/hydra)
   2
   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
   5 Hydra.
   6
   7 ![hydra](http://oremacs.com/download/Hydra.png)
   8
   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
  11 extension.
  12
  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.
  18
  19 ## Simplified usage
  20
  21 Here's how to quickly bind the examples bundled with Hydra:
  22
  23 ```cl
  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)
  28 ```
  29
  30 ## Using Hydra for global bindings
  31
  32 But it's much better to just take the examples as a template and write
  33 down everything explicitly:
  34
  35 ```cl
  36 (defhydra hydra-zoom (global-map "<f2>")
  37   "zoom"
  38   ("g" text-scale-increase "in")
  39   ("l" text-scale-decrease "out"))
  40 ```
  41
  42 With the example above, you can e.g.:
  43
  44 ```cl
  45 (key-chord-define-global "tt" 'hydra-zoom/body)
  46 ```
  47
  48 In fact, since `defhydra` returns the body symbol, you can even write
  49 it like this:
  50
  51 ```cl
  52 (key-chord-define-global
  53  "tt"
  54  (defhydra hydra-zoom (global-map "<f2>")
  55   "zoom"
  56   ("g" text-scale-increase "in")
  57   ("l" text-scale-decrease "out")))
  58 ```
  59
  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.:
  62
  63 ```
  64 (key-chord-define-global
  65  "hh"
  66  (defhydra hydra-error ()
  67    "goto-error"
  68    ("h" first-error "first")
  69    ("j" next-error "next")
  70    ("k" previous-error "prev")))
  71 ```
  72
  73 You can also substitute `global-map` with any other keymap, like
  74 `c++-mode-map` or `yas-minor-mode-map`.
  75
  76 See the [introductory blog post](http://oremacs.com/2015/01/20/introducing-hydra/) for more information.
  77
  78 ## Using Hydra for major-mode or minor-mode bindings
  79
  80 Here's an example:
  81
  82 ```cl
  83 (defhydra lispy-vi (lispy-mode-map "C-z")
  84   "vi"
  85   ("l" forward-char)
  86   ("h" backward-char)
  87   ("j" next-line)
  88   ("k" previous-line))
  89 ```
  90
  91 ## Can Hydras can be helpful?
  92
  93 They can, if
  94
  95 ```cl
  96 (setq hydra-is-helpful t)
  97 ```
  98
  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:
 102
 103 ```
 104 (defhydra hydra-zoom (global-map "<f2>")
 105   "zoom"
 106   ("g" text-scale-increase "in")
 107   ("l" text-scale-decrease "out"))
 108 ```
 109
 110 With this, you'll see `zoom: [g]: in, [l]: out.` in your echo area,
 111 once the zoom Hydra becomes active.
 112
 113 ## Colorful Hydras
 114
 115 Since version `0.5.0`, Hydra's heads all have a color associated with them:
 116
 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
 119
 120 In all the older examples, all heads are red by default. You can specify blue heads like this:
 121
 122 ```cl
 123 (global-set-key
 124  (kbd "C-c C-v")
 125  (defhydra toggle ()
 126    "toggle"
 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)
 132    ("q" nil "cancel")))
 133 ```
 134
 135 Or, since the heads can inherit the color from the body, the following is equivalent:
 136
 137 ```cl
 138 (global-set-key
 139  (kbd "C-c C-v")
 140  (defhydra toggle (:color blue)
 141    "toggle"
 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")
 147    ("q" nil "cancel")))
 148 ```
 149
 150 The above Hydra is very similar to this code:
 151
 152 ```cl
 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)
 156 ```
 157
 158 However, there are two important differences:
 159
 160 - you get a hint like this right after <kbd>C-c C-v</kbd>:
 161
 162         toggle: [t]: truncate, [f]: fill, [a]: abbrev, [q]: cancel.
 163
 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>.
 166
 167 ## Hydras and numeric arguments
 168
 169 Since version `0.6.0`, for any Hydra:
 170
 171 - `digit-argment` can be called with <kbd>0</kbd>-<kbd>9</kbd>.
 172 - `negative-argument` can be called with <kbd>-</kbd>
 173 - `universal-argument` can be called with <kbd>C-u</kbd>
 174
 175 ## Hydras can have `:pre` and `:post` statements
 176
 177 Since version `0.7.0`, you can specify code that will be called before each head, and
 178 after the body. For example:
 179
 180 ```cl
 181 (global-set-key
 182  (kbd "C-z")
 183  (defhydra hydra-vi
 184      (:pre
 185       (set-cursor-color "#40e0d0")
 186       :post
 187       (progn
 188         (set-cursor-color "#ffffff")
 189         (message
 190          "Thank you, come again.")))
 191    "vi"
 192    ("l" forward-char)
 193    ("h" backward-char)
 194    ("j" next-line)
 195    ("k" previous-line)
 196    ("q" nil "quit")))
 197 ```
 198
 199 ## New Hydra color: amaranth
 200
 201 Since version `0.8.0`, a new color - amaranth, in addition to the previous red and blue, is
 202 available for the Hydra body.
 203
 204 According to [Wikipedia](http://en.wikipedia.org/wiki/Amaranth):
 205
 206 > The word amaranth comes from the Greek word amaranton, meaning "unwilting" (from the
 207 > verb marainesthai, meaning "wilt").  The word was applied to amaranth because it did not
 208 > soon fade and so symbolized immortality.
 209
 210 Hydras with amaranth body are impossible to quit with any binding *except* a blue head.
 211 A check for at least one blue head exists in `defhydra`, so that you don't get stuck by accident.
 212
 213 Here's an example of an amaranth Hydra:
 214
 215 ```cl
 216 (global-set-key
 217  (kbd "C-z")
 218  (defhydra hydra-vi
 219      (:pre
 220       (set-cursor-color "#40e0d0")
 221       :post
 222       (set-cursor-color "#ffffff")
 223       :color amaranth)
 224    "vi"
 225    ("l" forward-char)
 226    ("h" backward-char)
 227    ("j" next-line)
 228    ("k" previous-line)
 229    ("q" nil "quit")))
 230 ```
 231
 232 The only way to exit it, is to press <kbd>q</kbd>. No other methods will work.  You can
 233 use an amaranth Hydra instead of a red one, if for you the cost of being able to exit only
 234 though certain bindings is less than the cost of accidentally exiting a red Hydra by
 235 pressing the wrong prefix.
 236
 237 Note that it does not make sense to define a singe amaranth head, so this color can only
 238 be assigned to the body. An amaranth body will always have some amaranth heads and some
 239 blue heads (otherwise, it's impossible to exit), no reds.