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.

2 Installation

Available from MELPA, M-x package-install hydra.

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 ()
             (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.1 ^

Inserts an empty character. Useful for aligning text in the defhydra for easier reading.

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.3.3 _key_

Another way to provide hints for the Hydra head. The underscores will highlight the enclosed keys and expect a head to be defined with the same binding (if one isn't found, a warning is emitted).

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.1 pre

Execute a function before the head is executed.

3.4.2 post

Execute a function after the head is executed.

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
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.

3.4.7 idle

Set the time before the Hydra buffer is displayed. Useful if you have the key commands committed to muscle memory.

3.4.8 columns

Sets the number of columns for the key hints to be arranged in.

3.4.9 bind

Rarely used. Provides a lambda to to be used to bind each head. Can be used to bind keys using bind-key instead of define-key.

3.5 Heads

3.5.1 Binding

The binding is a string that can is passed to kbd.

3.5.2 Command

The command can be any of the following

  • a command
  • a lambda
  • a single sexp, which Hydra will wrap in an interactive lambda.
  • nil, causing the Hydra to exit

3.5.3 Hint

The hint shows up next to binding with information about what the binding does. If you've already provided a hint via the docstring, you can pass nil instead.

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.

Author: Michael Hunsinger

Created: 2017-06-23 Fri 10:32