#+TITLE: Emaps

* Introduction

Emaps provides utilities for working with keymaps and keybindings in Emacs.

* Features

** Defining keys

Emacs has a built-in ~define-key~ function, but this can only handle one binding
at a time, for example:

#+BEGIN_SRC emacs-lisp
(define-key keymap "a" 'fun-a)
(define-key keymap "b" 'fun-b)
(define-key keymap "c" 'fun-c)
; etc.
#+END_SRC

Emaps provides the ~emaps-define-key~ function that provides the same
functionality, but allows multiple keys to be defined at once, thus the
above becomes:

#+BEGIN_SRC emacs-lisp
(emaps-define-key keymap
  "a" 'fun-a
  "b" 'fun-b
  "c" 'fun-c) ; etc.
#+END_SRC

** Viewing keymaps

Run ~M-x emaps-describe-keymap-bindings~ to display the
bindings for a given keymap (see below),
~emaps-describe-keymap~ can be used to view keymaps as
variables (but with characters displayed instead of integers,
where possible). Executing these commands with a prefix
argument allows you to choose from only active keymaps.

#+CAPTION: Display after running ~emaps-describe-keymap-bindings~ with ~magit-status-mode-map~.
#+NAME:   fig:emaps-describe-keymap-bindings-magit-status-mode-map
[[./images/emaps-describe-keymap-bindings.png]]

** Recommended Bindings

I recommend the following bindings with Emaps (though I
encourage you to experiment and find what works best for you):

| Key     | Command                          |
|---------+----------------------------------|
| ~C-h K~ | ~emaps-describe-keymap-bindings~ |

Which you can set with the following snippet:

#+BEGIN_SRC emacs-lisp
  (emaps-define-key global-map
    (kbd "C-h K") 'emaps-describe-keymap-bindings)
#+END_SRC