Function: lookup-key

lookup-key is a function defined in keymap.c.

Signature

(lookup-key KEYMAP KEY &optional ACCEPT-DEFAULT)

Documentation

Look up key sequence KEY in KEYMAP. Return the definition.

A value of nil means undefined. See doc of define-key for kinds of definitions.

A number as value means KEY is "too long"; that is, characters or symbols in it except for the last one fail to be a valid sequence of prefix characters in KEYMAP. The number is how many characters at the front of KEY it takes to reach a non-prefix key. KEYMAP can also be a list of keymaps.

Normally, lookup-key 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 third optional argument ACCEPT-DEFAULT is non-nil, lookup-key will recognize the default bindings, just as read-key-sequence does.

Probably introduced at or before Emacs version 13.

Source Code

// Defined in /usr/src/emacs/src/keymap.c
{
  Lisp_Object found = lookup_key_1 (keymap, key, accept_default);
  if (!NILP (found) && !NUMBERP (found))
    return found;

  /* Menu definitions might use mixed case symbols (notably in old
     versions of `easy-menu-define').  We accept this variation for
     backwards-compatibility.  (Bug#50752)  */
  ptrdiff_t key_len = VECTORP (key) ? ASIZE (key) : 0;
  if (key_len > 0 && EQ (AREF (key, 0), Qmenu_bar))
    {
      Lisp_Object new_key = make_vector (key_len, Qnil);
      for (int i = 0; i < key_len; ++i)
	{
	  Lisp_Object item = AREF (key, i);
	  if (!SYMBOLP (item))
	    ASET (new_key, i, item);
	  else
	    {
	      Lisp_Object sym = Fsymbol_name (item);
	      USE_SAFE_ALLOCA;
	      unsigned char *dst = SAFE_ALLOCA (SBYTES (sym) + 1);
	      memcpy (dst, SSDATA (sym), SBYTES (sym));
	      /* We can walk the string data byte by byte, because
		 UTF-8 encoding ensures that no other byte of any
		 multibyte sequence will ever include a 7-bit byte
		 equal to an ASCII single-byte character.  */
	      for (int j = 0; j < SBYTES (sym); ++j)
		if (dst[j] >= 'A' && dst[j] <= 'Z')
		  dst[j] += 'a' - 'A';  /* Convert to lower case.  */
	      ASET (new_key, i, Fintern (make_multibyte_string ((char *) dst,
								SCHARS (sym),
								SBYTES (sym)),
					 Qnil));
	      SAFE_FREE ();
	    }
	}
      found = lookup_key_1 (keymap, new_key, accept_default);
    }
  return found;
}