27.4.1 Keymaps

The bindings between characters and command functions are recorded in data structures called keymaps. Emacs has many of these. One, the global keymap, defines the meanings of the single-character keys that are defined regardless of major mode. It is the value of the variable global-map.

Each major mode has another keymap, its local keymap, which contains overriding definitions for the single-character keys that are redefined in that mode. Each buffer records which local keymap is installed for it at any time, and the current buffer’s local keymap is the only one that directly affects command execution. The local keymaps for Lisp mode, C mode, and many other major modes always exist even when not in use. They are the values of the variables lisp-mode-map, c-mode-map, and so on. For less frequently used major modes, the local keymap is sometimes constructed only when the mode is used for the first time in a session, to save space.

There are local keymaps for the minibuffer, too; they contain various completion and exit commands.

• minibuffer-local-map is used for ordinary input (no completion).
• minibuffer-local-ns-map is similar, except that SPC exits just like RET. This is used mainly for Mocklisp compatibility.
• minibuffer-local-completion-map is for permissive completion.
• minibuffer-local-must-match-map is for strict completion and for cautious completion.
• repeat-complex-command-map is for use in C-x ESC ESC.
• isearch-mode-map contains the bindings of the special keys which are bound in the pseudo-mode entered with C-s and C-r.

Finally, each prefix key has a keymap which defines the key sequences that start with it. For example, ctl-x-map is the keymap used for characters following a C-x.

• ctl-x-map is the variable name for the map used for characters that follow C-x.
• help-map is used for characters that follow C-h.
• esc-map is for characters that follow ESC. All Meta characters are actually defined by this map.
• ctl-x-4-map is for characters that follow C-x 4.
• mode-specific-map is for characters that follow C-c.

The definition of a prefix key is the keymap to use for looking up the following character. Sometimes the definition is actually a Lisp symbol whose function definition is the following character keymap. The effect is the same, but it provides a command name for the prefix key that you can use as a description of what the prefix key is for. Thus the binding of C-x is the symbol Ctl-X-Prefix, whose function definition is the keymap for C-x commands, the value of ctl-x-map.

Prefix key definitions can appear in either the global map or a local map. The definitions of C-c, C-x, C-h, and ESC as prefix keys appear in the global map, so these prefix keys are always available. Major modes can locally redefine a key as a prefix by putting a prefix key definition for it in the local map.

A mode can also put a prefix definition of a global prefix character such as C-x into its local map. This is how major modes override the definitions of certain keys that start with C-x. This case is special, because the local definition does not entirely replace the global one. When both the global and local definitions of a key are other keymaps, the next character is looked up in both keymaps, with the local definition overriding the global one. The character after the C-x is looked up in both the major mode’s own keymap for redefined C-x commands and in ctl-x-map. If the major mode’s own keymap for C-x commands contains nil, the definition from the global keymap for C-x commands is used.