Function: keymap-lookup

keymap-lookup is a byte-compiled function defined in keymap.el.gz.

Signature

(keymap-lookup KEYMAP KEY &optional ACCEPT-DEFAULT NO-REMAP POSITION)

Documentation

Return the binding for command KEY in KEYMAP.

KEY is a string that satisfies key-valid-p.

If KEYMAP is nil, look up in the current keymaps. If non-nil, it should either be a keymap or a list of keymaps, and only these keymap(s) will be consulted.

The binding is probably a symbol with a function definition.

Normally, keymap-lookup ignores bindings for t, which act as default bindings, used when nothing else in the keymap applies; this makes it usable as a general function for probing keymaps. However, if the optional second argument ACCEPT-DEFAULT is non-nil, keymap-lookup does recognize the default bindings, just as read-key-sequence does.

Like the normal command loop, keymap-lookup will remap the command resulting from looking up KEY by looking up the command in the current keymaps. However, if the optional third argument NO-REMAP is non-nil, keymap-lookup returns the unmapped command.

If KEY is a mouse gesture, the keymaps used depend on the clicked mouse position with regards to the buffer, and local keymaps, if any, on display and overlay strings.

If the optional argument POSITION is non-nil, it specifies a mouse position as returned by event-start and event-end, and the lookup occurs in the keymaps associated with it instead of KEY. It can also be a number or marker, in which case the keymap properties at the specified buffer position are used instead of point.

Other relevant functions are documented in the keymaps group.

View in manual

Probably introduced at or before Emacs version 29.1.

Shortdoc

;; keymaps
(keymap-lookup (current-global-map) "C-x x g")
    => revert-buffer-quick

Source Code

;; Defined in /usr/src/emacs/lisp/keymap.el.gz
(defun keymap-lookup (keymap key &optional accept-default no-remap position)
  "Return the binding for command KEY in KEYMAP.
KEY is a string that satisfies `key-valid-p'.

If KEYMAP is nil, look up in the current keymaps.  If non-nil, it
should either be a keymap or a list of keymaps, and only these
keymap(s) will be consulted.

The binding is probably a symbol with a function definition.

Normally, `keymap-lookup' ignores bindings for t, which act as
default bindings, used when nothing else in the keymap applies;
this makes it usable as a general function for probing keymaps.
However, if the optional second argument ACCEPT-DEFAULT is
non-nil, `keymap-lookup' does recognize the default bindings,
just as `read-key-sequence' does.

Like the normal command loop, `keymap-lookup' will remap the
command resulting from looking up KEY by looking up the command
in the current keymaps.  However, if the optional third argument
NO-REMAP is non-nil, `keymap-lookup' returns the unmapped
command.

If KEY is a mouse gesture, the keymaps used depend on the clicked
mouse position with regards to the buffer, and local keymaps, if any,
on display and overlay strings.

If the optional argument POSITION is non-nil, it specifies a mouse
position as returned by `event-start' and `event-end', and the lookup
occurs in the keymaps associated with it instead of KEY.  It can also
be a number or marker, in which case the keymap properties at the
specified buffer position are used instead of point."
  (declare (compiler-macro (lambda (form) (keymap--compile-check key) form)))
  (keymap--check key)
  (when (and keymap position)
    (error "Can't pass in both keymap and position"))
  (if keymap
      (let ((value (lookup-key keymap (key-parse key) accept-default)))
        (if (and (not no-remap)
                   (symbolp value))
            (or (command-remapping value) value)
          value))
    (key-binding (key-parse key) accept-default no-remap position)))