Binding to repeat-maps (use-package User Manual)

4.2.4 Binding to repeat-maps ¶

A special case of binding within a local keymap is when that keymap is used by repeat-mode (see Repeating in GNU Emacs Manual). These keymaps are usually defined specifically for this. Using the :repeat-map keyword, and passing it a name for the map it defines, will bind all the following keys inside that map, and (by default) set the repeat-map property of each bound command to that map.

The following example creates a keymap called git-gutter+-repeat-map, makes four bindings in it, then sets the repeat-map property of each bound command (git-gutter+-next-hunk, git-gutter+-previous-hunk, git-gutter+-stage-hunks, and git-gutter+-revert-hunk) to that keymap.

(use-package git-gutter+
 :bind
 (:repeat-map git-gutter+-repeat-map
 ("n" . git-gutter+-next-hunk)
 ("p" . git-gutter+-previous-hunk)
 ("s" . git-gutter+-stage-hunks)
 ("r" . git-gutter+-revert-hunk)))

Specifying :exit inside the scope of :repeat-map will prevent the repeat-map property from being set, so that the command can be used from within the repeat map, but after using it the repeat map will no longer be available. This is useful for commands often used at the end of a series of repeated commands. Example:

(use-package git-gutter+
 :bind
 (:repeat-map my/git-gutter+-repeat-map
 ("n" . git-gutter+-next-hunk)
 ("p" . git-gutter+-previous-hunk)
 ("s" . git-gutter+-stage-hunks)
 ("r" . git-gutter+-revert-hunk)
 :exit
 ("c" . magit-commit-create)
 ("C" . magit-commit)
 ("b" . magit-blame)))

Specifying :continue forces setting the repeat-map property (just like not specifying :exit), so the above snippet is equivalent to:

(use-package git-gutter+
 :bind
 (:repeat-map my/git-gutter+-repeat-map
 :exit
 ("c" . magit-commit-create)
 ("C" . magit-commit)
 ("b" . magit-blame)
 :continue
 ("n" . git-gutter+-next-hunk)
 ("p" . git-gutter+-previous-hunk)
 ("s" . git-gutter+-stage-hunks)
 ("r" . git-gutter+-revert-hunk)))

Specifying :continue-only inside the scope of :repeat-map will make commands continue an active repeating sequence, but never initiate it. This is done by setting the repeat-continue property of each command with the keymap, but not the repeat-map property. This is useful for commands that should be available while repeating a sequence, but not initiate the repeat map themselves. Example:

(use-package emacs
 :bind
 (:repeat-map
 paragraph-repeat-map
 ("}" . forward-paragraph)
 ("{" . backward-paragraph)
 ("]" . forward-paragraph)
 ("[" . backward-paragraph)
 :continue-only
 ("h" . mark-paragraph)
 ("w" . kill-region)
 ("M-w" . kill-ring-save)
 ("k" . kill-paragraph)
 ("y" . yank)))

Next: Displaying personal keybindings, Previous: Binding to keymaps, Up: Key bindings [Contents][Index]