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 Once you summon the Hydra through the prefixed binding (the body + any
   8 one head), all heads can be called in succession with only a short
   9 extension.
  10
  11 The Hydra is vanquished once Hercules, any binding that isn't the
  12 Hydra's head, arrives.  Note that Hercules, besides vanquishing the
  13 Hydra, will still serve his orignal purpose, calling his proper
  14 command.  This makes the Hydra very seamless, it's like a minor mode
  15 that disables itself auto-magically.
  16
  17 Here's how to quickly bind the examples bundled with Hydra:
  18
  19 ```cl
  20 (require 'hydra-examples)
  21 (hydra-create "C-M-y" hydra-example-move-window-splitter)
  22 (hydra-create "M-g" hydra-example-goto-error)
  23 (hydra-create "<f2>" hydra-example-text-scale)
  24 ```
  25
  26 But it's much better to just take the examples as a template and write
  27 down everything explicitly:
  28
  29 ```cl
  30 (defhydra hydra-zoom (global-map "<f2>")
  31   "zoom"
  32   ("g" text-scale-increase "in")
  33   ("l" text-scale-decrease "out"))
  34 ```
  35
  36 With the example above, you can e.g.:
  37
  38 ```cl
  39 (key-chord-define-global "tt" 'hydra-zoom/body)
  40 ```
  41
  42 In fact, since `defhydra` returns the body symbol, you can even write
  43 it like this:
  44
  45 ```cl
  46 (key-chord-define-global
  47  "tt"
  48  (defhydra hydra-zoom (global-map "<f2>")
  49   "zoom"
  50   ("g" text-scale-increase "in")
  51   ("l" text-scale-decrease "out")))
  52 ```
  53
  54 If you like key chords so much that you don't want to touch the global map at all, you can e.g.:
  55
  56 ```
  57 (key-chord-define-global
  58  "hh"
  59  (defhydra hydra-error ()
  60    "goto-error"
  61    ("h" first-error "first")
  62    ("j" next-error "next")
  63    ("k" previous-error "prev")))
  64 ```
  65
  66 You can also substitute `global-map` with any other keymap, like
  67 `c++-mode-map` or `yas-minor-mode-map`.
  68
  69 See the [introductory blog post](http://oremacs.com/2015/01/20/introducing-hydra/) for more information.
  70
  71 ![hydra](http://oremacs.com/download/Hydra.png)
  72
  73 ## Using Hydra to define bindings other than global ones
  74
  75 Here's an example:
  76
  77 ```cl
  78 (defhydra lispy-vi (lispy-mode-map "C-z")
  79   "vi"
  80   ("l" forward-char)
  81   ("h" backward-char)
  82   ("j" next-line)
  83   ("k" previous-line))
  84 ```
  85
  86 ## Can Hydras can be helpful?
  87
  88 They can, if
  89
  90 ```cl
  91 (setq hydra-is-helpful t)
  92 ```
  93
  94 This is the default setting. In this case, you'll get a hint in the
  95 echo area consisting of current Hydra's base comment and heads.  You
  96 can even add comments to the heads like this:
  97
  98 ```
  99 (defhydra hydra-zoom (global-map "<f2>")
 100   "zoom"
 101   ("g" text-scale-increase "in")
 102   ("l" text-scale-decrease "out"))
 103 ```
 104
 105 With this, you'll see `zoom: [g]: in, [l]: out.` in your echo area,
 106 once the zoom Hydra becomes active.