GNU Info

(elisp)Format of Keymaps

---

Next: Creating Keymaps Prev: Keymap Terminology Up: Keymaps

---

Enter node , (file) or (file)node

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.  Note: 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.  Note: 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' (Note: 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