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.

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

An ordinary element of a keymap is a cons cell of the form (type . binding). This specifies one binding, for events of type type.

A cons cell whose CAR is t is 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.

If an element of a keymap is a vector, the vector counts as bindings for all the ASCII characters; 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 every ASCII character even if the vector element is nil. Such a binding of nil overrides any default binding in the keymap. However, default bindings are still meaningful for events that are not 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.

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

Keymaps do not directly record bindings for the meta characters, whose codes are from 128 to 255. 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 really represented as ESC a, and its global binding is found at the slot for a in esc-map (see section Prefix Keys).

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

Go to the first, previous, next, last section, table of contents.