22.2 Format of Keymaps

A keymap is a list whose CAR is the symbol keymap. The remaining elements of the list define the key bindings of the keymap. Use the function keymapp (see below) to test whether an object is a keymap.

Several kinds of elements may appear in a keymap, after the symbol keymap that begins it:

(type . binding)

This specifies one binding, for events of type type. Each ordinary binding applies to events of a particular event type, which is always a character or a symbol. See section 21.6.12 Classifying Events.

(t . binding)

This specifies a default key binding; any event not bound by other elements of the keymap is given binding as its binding. Default bindings allow a keymap to bind all possible event types without having to enumerate all of them. A keymap that has a default binding completely masks any lower-precedence keymap.

vector

If an element of a keymap is a vector, the vector counts as bindings for all the ASCII characters, codes 0 through 127; vector element n is the binding for the character with code n. This is a compact way to record lots of bindings. A keymap with such a vector is called a full keymap. Other keymaps are called sparse keymaps.

When a keymap contains a vector, it always defines a binding for each ASCII character, even if the vector contains nil for that character. Such a binding of nil overrides any default key binding in the keymap, for ASCII characters. However, default bindings are still meaningful for events other than ASCII characters. A binding of nil does not override lower-precedence keymaps; thus, if the local map gives a binding of nil, Emacs uses the binding from the global map.

string

Aside from bindings, a keymap can also have a string as an element. This is called the overall prompt string and makes it possible to use the keymap as a menu. See section 22.12.1 Defining Menus.

Keymaps do not directly record bindings for the meta characters. Instead, meta characters are regarded for purposes of key lookup as sequences of two characters, the first of which is ESC (or whatever is currently the value of meta-prefix-char). Thus, the key M-a is internally represented as ESC a, and its global binding is found at the slot for a in esc-map (see section 22.5 Prefix Keys).

This conversion applies only to characters, not to function keys or other input events; thus, M-end has nothing to do with ESC end.

Here as an example is the local keymap for Lisp mode, a sparse keymap. It defines bindings for DEL and TAB, plus C-c C-l, M-C-q, and M-C-x.

lisp-mode-map => (keymap ;; TAB (9 . lisp-indent-line) ;; DEL (127 . backward-delete-char-untabify) (3 keymap ;; C-c C-l (12 . run-lisp)) (27 keymap ;; M-C-q, treated as ESC C-q (17 . indent-sexp) ;; M-C-x, treated as ESC C-x (24 . lisp-send-defun)))

Function: keymapp object

This function returns t if object is a keymap, nil otherwise. More precisely, this function tests for a list whose CAR is keymap.

(keymapp '(keymap)) => t (keymapp (current-global-map)) => t