Hydra
Table of Contents
Hydra is an Emacs package that creates short lived key bindings that become active after a Hydra prefix is keyed.
1 Author
Oleh Krehel (abo-abo on GitHub) is the author and maintainer of Hydra and a number of other great Emacs package. Including avy, ivy, and lispy.
3 Hydra Anatomy
Hydra provides the macro, defhydra to define a Hydra
(defhydra hydra-org-motion (org-mode-map "<f2>" :color amaranth) " Org motion ^^Info --------------------------------------- _h_: Next heading Heading: %s(substring-no-properties (org-get-heading)) _t_: Previous heading Subheading: %s(length (org-map-entries nil nil 'tree)) _p_: Promote heading Cool Points: %`my-cool-points _d_: Demote heading _+_: Add a cool point " ("h" outline-next-visible-heading nil) ("t" outline-previous-visible-heading nil) ("p" org-do-promote nil) ("d" org-do-demote :color blue) ("+" (lambda () (interactive) (setq my-cool-points (1+ my-cool-points))) nil) ("q" nil "quit"))
The code above creates the Hydra below.
Figure 1: The hydra-org-motion Hydra
3.1 Name
This symbol becomes the prefix to your Hydra and the it's heads (the heads are the functions below the docstring, more on those later). When creating a Hydra, all of the heads are bound to interactive functions.
3.2 Key Binding
Give the Hydra a key binding. This can be part of the global-map, if you want to access it
across modes. In this case, since its specific to org-mode, I've bound it to the
org-mode-map.
3.3 Docstring
The docstring gives information on what key bindings are available for the active Hydra.
3.3.2 %
Prefix for using an Emacs variable or s-expression.
If using a variable, you can use format-style width specifiers (% -5s`foo will ensure foo
will be padded with spaces to five characters. Note, if using a variable, a backtick ` is
required before the variable name.
You can also use s-expressions, like %(length (buffer-list)). The results from using these
functions are quoted. If you'd like them to be unquoted, use %s.
3.4 Property List
The Hydra's property list allows for a number of keys and values to further customize your
Hydra. All of the keywords can be used when defining a Hydra. exit, color, and bind can be
defined in Hydra heads.
3.4.3 exit
nil, the default, allows the Hydra to continue. Useful if you want to chain commands
together. t if the Hydra should stop. This keyword can also be supplied on the Hydra's head.
3.4.4 foreign-keys
Instructs what Hydra should do if a key press doesn't match one of the heads. nil, the
default, means the Hydra should stop. warn doesn't stop the Hydra, but issues a warning. run
will not stop and try to run the key.
I would advise using the color property instead if possible. The error given on warn refers
to the color.
3.4.5 color
A shortcut to set exit and foreign-keys together.
| color | toggle |
|---|---|
| red | |
| blue | :exit t |
| amaranth | :foreign-keys warn |
| teal | :foreign-keys warn :exit t |
| pink | :foreign-keys run |
3.4.6 timeout
Time (in seconds) after the Hydra is activated until it is disabled. Calling a head will reset the timer.
4 Additional Reading
Reddit user u/tirocinium posted a link to some defined Hydras that are interesting. Many of these
depend on other packages, like avy, multicursor, clj and more.