1 /* Manipulation of keymaps
2 Copyright (C) 1985-1988, 1993-1995, 1998-2014 Free Software
5 This file is part of GNU Emacs.
7 GNU Emacs is free software: you can redistribute it and/or modify
8 it under the terms of the GNU General Public License as published by
9 the Free Software Foundation, either version 3 of the License, or
10 (at your option) any later version.
12 GNU Emacs is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 GNU General Public License for more details.
17 You should have received a copy of the GNU General Public License
18 along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>. */
21 - [M-C-a] != [?\M-\C-a]
23 - (define-key map [menu-bar foo] <bla>) does not always place <bla>
24 at the head of the menu (if `foo' was already bound earlier and
25 then unbound, for example).
27 - allow many more Meta -> ESC mappings (like Hyper -> C-e for Emacspeak)
28 - Think about the various defaulting that's currently hard-coded in
29 keyboard.c (uppercase->lowercase, char->charset, button-events, ...)
30 and make it more generic. Maybe we should allow mappings of the
31 form (PREDICATE . BINDING) as generalization of the default binding,
32 tho probably a cleaner way to attack this is to allow functional
33 keymaps (i.e. keymaps that are implemented as functions that implement
34 a few different methods like `lookup', `map', ...).
35 - Make [a] equivalent to [?a].
37 - map-keymap should work meaningfully even if entries are added/removed
38 to the keymap while iterating through it:
39 start - removed <= visited <= start + added
47 #include "character.h"
52 #include "termhooks.h"
53 #include "blockinput.h"
55 #include "intervals.h"
59 /* Actually allocate storage for these variables. */
61 Lisp_Object current_global_map
; /* Current global keymap. */
63 Lisp_Object global_map
; /* Default global key bindings. */
65 Lisp_Object meta_map
; /* The keymap used for globally bound
66 ESC-prefixed default commands. */
68 Lisp_Object control_x_map
; /* The keymap used for globally bound
69 C-x-prefixed default commands. */
71 /* The keymap used by the minibuf for local
72 bindings when spaces are allowed in the
75 /* The keymap used by the minibuf for local
76 bindings when spaces are not encouraged
79 /* Keymap used for minibuffers when doing completion. */
80 /* Keymap used for minibuffers when doing completion and require a match. */
81 static Lisp_Object Qkeymapp
, Qnon_ascii
;
82 Lisp_Object Qkeymap
, Qmenu_item
, Qremap
;
83 static Lisp_Object QCadvertised_binding
;
85 /* Alist of elements like (DEL . "\d"). */
86 static Lisp_Object exclude_keys
;
88 /* Pre-allocated 2-element vector for Fcommand_remapping to use. */
89 static Lisp_Object command_remapping_vector
;
91 /* Hash table used to cache a reverse-map to speed up calls to where-is. */
92 static Lisp_Object where_is_cache
;
93 /* Which keymaps are reverse-stored in the cache. */
94 static Lisp_Object where_is_cache_keymaps
;
96 static Lisp_Object
store_in_keymap (Lisp_Object
, Lisp_Object
, Lisp_Object
);
98 static Lisp_Object
define_as_prefix (Lisp_Object
, Lisp_Object
);
99 static void describe_command (Lisp_Object
, Lisp_Object
);
100 static void describe_translation (Lisp_Object
, Lisp_Object
);
101 static void describe_map (Lisp_Object
, Lisp_Object
,
102 void (*) (Lisp_Object
, Lisp_Object
),
103 bool, Lisp_Object
, Lisp_Object
*, bool, bool);
104 static void describe_vector (Lisp_Object
, Lisp_Object
, Lisp_Object
,
105 void (*) (Lisp_Object
, Lisp_Object
), bool,
106 Lisp_Object
, Lisp_Object
, bool, bool);
107 static void silly_event_symbol_error (Lisp_Object
);
108 static Lisp_Object
get_keyelt (Lisp_Object
, bool);
111 CHECK_VECTOR_OR_CHAR_TABLE (Lisp_Object x
)
113 CHECK_TYPE (VECTORP (x
) || CHAR_TABLE_P (x
), Qvector_or_char_table_p
, x
);
116 /* Keymap object support - constructors and predicates. */
118 DEFUN ("make-keymap", Fmake_keymap
, Smake_keymap
, 0, 1, 0,
119 doc
: /* Construct and return a new keymap, of the form (keymap CHARTABLE . ALIST).
120 CHARTABLE is a char-table that holds the bindings for all characters
121 without modifiers. All entries in it are initially nil, meaning
122 "command undefined". ALIST is an assoc-list which holds bindings for
123 function keys, mouse events, and any other things that appear in the
124 input stream. Initially, ALIST is nil.
126 The optional arg STRING supplies a menu name for the keymap
127 in case you use it as a menu with `x-popup-menu'. */)
132 tail
= list1 (string
);
135 return Fcons (Qkeymap
,
136 Fcons (Fmake_char_table (Qkeymap
, Qnil
), tail
));
139 DEFUN ("make-sparse-keymap", Fmake_sparse_keymap
, Smake_sparse_keymap
, 0, 1, 0,
140 doc
: /* Construct and return a new sparse keymap.
141 Its car is `keymap' and its cdr is an alist of (CHAR . DEFINITION),
142 which binds the character CHAR to DEFINITION, or (SYMBOL . DEFINITION),
143 which binds the function key or mouse event SYMBOL to DEFINITION.
144 Initially the alist is nil.
146 The optional arg STRING supplies a menu name for the keymap
147 in case you use it as a menu with `x-popup-menu'. */)
152 if (!NILP (Vpurify_flag
))
153 string
= Fpurecopy (string
);
154 return list2 (Qkeymap
, string
);
156 return list1 (Qkeymap
);
159 /* This function is used for installing the standard key bindings
160 at initialization time.
164 initial_define_key (control_x_map, Ctl('X'), "exchange-point-and-mark"); */
167 initial_define_key (Lisp_Object keymap
, int key
, const char *defname
)
169 store_in_keymap (keymap
, make_number (key
), intern_c_string (defname
));
173 initial_define_lispy_key (Lisp_Object keymap
, const char *keyname
, const char *defname
)
175 store_in_keymap (keymap
, intern_c_string (keyname
), intern_c_string (defname
));
178 DEFUN ("keymapp", Fkeymapp
, Skeymapp
, 1, 1, 0,
179 doc
: /* Return t if OBJECT is a keymap.
181 A keymap is a list (keymap . ALIST),
182 or a symbol whose function definition is itself a keymap.
183 ALIST elements look like (CHAR . DEFN) or (SYMBOL . DEFN);
184 a vector of densely packed bindings for small character codes
185 is also allowed as an element. */)
188 return (KEYMAPP (object
) ? Qt
: Qnil
);
191 DEFUN ("keymap-prompt", Fkeymap_prompt
, Skeymap_prompt
, 1, 1, 0,
192 doc
: /* Return the prompt-string of a keymap MAP.
193 If non-nil, the prompt is shown in the echo-area
194 when reading a key-sequence to be looked-up in this keymap. */)
197 map
= get_keymap (map
, 0, 0);
200 Lisp_Object tem
= XCAR (map
);
203 else if (KEYMAPP (tem
))
205 tem
= Fkeymap_prompt (tem
);
214 /* Check that OBJECT is a keymap (after dereferencing through any
215 symbols). If it is, return it.
217 If AUTOLOAD and if OBJECT is a symbol whose function value
218 is an autoload form, do the autoload and try again.
219 If AUTOLOAD, callers must assume GC is possible.
221 ERROR_IF_NOT_KEYMAP controls how we respond if OBJECT isn't a keymap.
222 If ERROR_IF_NOT_KEYMAP, signal an error; otherwise,
225 Note that most of the time, we don't want to pursue autoloads.
226 Functions like Faccessible_keymaps which scan entire keymap trees
227 shouldn't load every autoloaded keymap. I'm not sure about this,
228 but it seems to me that only read_key_sequence, Flookup_key, and
229 Fdefine_key should cause keymaps to be autoloaded.
231 This function can GC when AUTOLOAD is true, because it calls
232 Fautoload_do_load which can GC. */
235 get_keymap (Lisp_Object object
, bool error_if_not_keymap
, bool autoload
)
242 if (CONSP (object
) && EQ (XCAR (object
), Qkeymap
))
245 tem
= indirect_function (object
);
248 if (EQ (XCAR (tem
), Qkeymap
))
251 /* Should we do an autoload? Autoload forms for keymaps have
252 Qkeymap as their fifth element. */
253 if ((autoload
|| !error_if_not_keymap
) && EQ (XCAR (tem
), Qautoload
)
258 tail
= Fnth (make_number (4), tem
);
259 if (EQ (tail
, Qkeymap
))
263 struct gcpro gcpro1
, gcpro2
;
265 GCPRO2 (tem
, object
);
266 Fautoload_do_load (tem
, object
, Qnil
);
278 if (error_if_not_keymap
)
279 wrong_type_argument (Qkeymapp
, object
);
283 /* Return the parent map of KEYMAP, or nil if it has none.
284 We assume that KEYMAP is a valid keymap. */
287 keymap_parent (Lisp_Object keymap
, bool autoload
)
291 keymap
= get_keymap (keymap
, 1, autoload
);
293 /* Skip past the initial element `keymap'. */
294 list
= XCDR (keymap
);
295 for (; CONSP (list
); list
= XCDR (list
))
297 /* See if there is another `keymap'. */
302 return get_keymap (list
, 0, autoload
);
305 DEFUN ("keymap-parent", Fkeymap_parent
, Skeymap_parent
, 1, 1, 0,
306 doc
: /* Return the parent keymap of KEYMAP.
307 If KEYMAP has no parent, return nil. */)
310 return keymap_parent (keymap
, 1);
313 /* Check whether MAP is one of MAPS parents. */
315 keymap_memberp (Lisp_Object map
, Lisp_Object maps
)
317 if (NILP (map
)) return 0;
318 while (KEYMAPP (maps
) && !EQ (map
, maps
))
319 maps
= keymap_parent (maps
, 0);
320 return (EQ (map
, maps
));
323 /* Set the parent keymap of MAP to PARENT. */
325 DEFUN ("set-keymap-parent", Fset_keymap_parent
, Sset_keymap_parent
, 2, 2, 0,
326 doc
: /* Modify KEYMAP to set its parent map to PARENT.
327 Return PARENT. PARENT should be nil or another keymap. */)
328 (Lisp_Object keymap
, Lisp_Object parent
)
330 Lisp_Object list
, prev
;
331 struct gcpro gcpro1
, gcpro2
;
333 /* Flush any reverse-map cache. */
334 where_is_cache
= Qnil
; where_is_cache_keymaps
= Qt
;
336 GCPRO2 (keymap
, parent
);
337 keymap
= get_keymap (keymap
, 1, 1);
341 parent
= get_keymap (parent
, 1, 0);
343 /* Check for cycles. */
344 if (keymap_memberp (keymap
, parent
))
345 error ("Cyclic keymap inheritance");
348 /* Skip past the initial element `keymap'. */
353 /* If there is a parent keymap here, replace it.
354 If we came to the end, add the parent in PREV. */
355 if (!CONSP (list
) || KEYMAPP (list
))
358 XSETCDR (prev
, parent
);
359 RETURN_UNGCPRO (parent
);
366 /* Look up IDX in MAP. IDX may be any sort of event.
367 Note that this does only one level of lookup; IDX must be a single
368 event, not a sequence.
370 MAP must be a keymap or a list of keymaps.
372 If T_OK, bindings for Qt are treated as default
373 bindings; any key left unmentioned by other tables and bindings is
374 given the binding of Qt.
376 If not T_OK, bindings for Qt are not treated specially.
378 If NOINHERIT, don't accept a subkeymap found in an inherited keymap.
380 Return Qunbound if no binding was found (and return Qnil if a nil
381 binding was found). */
384 access_keymap_1 (Lisp_Object map
, Lisp_Object idx
,
385 bool t_ok
, bool noinherit
, bool autoload
)
387 /* If idx is a list (some sort of mouse click, perhaps?),
388 the index we want to use is the car of the list, which
389 ought to be a symbol. */
390 idx
= EVENT_HEAD (idx
);
392 /* If idx is a symbol, it might have modifiers, which need to
393 be put in the canonical order. */
395 idx
= reorder_modifiers (idx
);
396 else if (INTEGERP (idx
))
397 /* Clobber the high bits that can be present on a machine
398 with more than 24 bits of integer. */
399 XSETFASTINT (idx
, XINT (idx
) & (CHAR_META
| (CHAR_META
- 1)));
401 /* Handle the special meta -> esc mapping. */
402 if (INTEGERP (idx
) && XFASTINT (idx
) & meta_modifier
)
404 /* See if there is a meta-map. If there's none, there is
405 no binding for IDX, unless a default binding exists in MAP. */
407 Lisp_Object event_meta_binding
, event_meta_map
;
409 /* A strange value in which Meta is set would cause
410 infinite recursion. Protect against that. */
411 if (XINT (meta_prefix_char
) & CHAR_META
)
412 meta_prefix_char
= make_number (27);
413 event_meta_binding
= access_keymap_1 (map
, meta_prefix_char
, t_ok
,
414 noinherit
, autoload
);
415 event_meta_map
= get_keymap (event_meta_binding
, 0, autoload
);
417 if (CONSP (event_meta_map
))
419 map
= event_meta_map
;
420 idx
= make_number (XFASTINT (idx
) & ~meta_modifier
);
423 /* Set IDX to t, so that we only find a default binding. */
426 /* An explicit nil binding, or no binding at all. */
427 return NILP (event_meta_binding
) ? Qnil
: Qunbound
;
430 /* t_binding is where we put a default binding that applies,
431 to use in case we do not find a binding specifically
432 for this key sequence. */
435 Lisp_Object t_binding
= Qunbound
;
436 Lisp_Object retval
= Qunbound
;
437 Lisp_Object retval_tail
= Qnil
;
438 struct gcpro gcpro1
, gcpro2
, gcpro3
, gcpro4
;
440 GCPRO4 (tail
, idx
, t_binding
, retval
);
442 for (tail
= (CONSP (map
) && EQ (Qkeymap
, XCAR (map
))) ? XCDR (map
) : map
;
444 || (tail
= get_keymap (tail
, 0, autoload
), CONSP (tail
)));
447 /* Qunbound in VAL means we have found no binding. */
448 Lisp_Object val
= Qunbound
;
449 Lisp_Object binding
= XCAR (tail
);
450 Lisp_Object submap
= get_keymap (binding
, 0, autoload
);
452 if (EQ (binding
, Qkeymap
))
454 if (noinherit
|| NILP (retval
))
455 /* If NOINHERIT, stop here, the rest is inherited. */
457 else if (!EQ (retval
, Qunbound
))
459 Lisp_Object parent_entry
;
460 eassert (KEYMAPP (retval
));
462 = get_keymap (access_keymap_1 (tail
, idx
,
465 if (KEYMAPP (parent_entry
))
467 if (CONSP (retval_tail
))
468 XSETCDR (retval_tail
, parent_entry
);
471 retval_tail
= Fcons (retval
, parent_entry
);
472 retval
= Fcons (Qkeymap
, retval_tail
);
478 else if (CONSP (submap
))
480 val
= access_keymap_1 (submap
, idx
, t_ok
, noinherit
, autoload
);
482 else if (CONSP (binding
))
484 Lisp_Object key
= XCAR (binding
);
487 val
= XCDR (binding
);
488 else if (t_ok
&& EQ (key
, Qt
))
490 t_binding
= XCDR (binding
);
494 else if (VECTORP (binding
))
496 if (INTEGERP (idx
) && XFASTINT (idx
) < ASIZE (binding
))
497 val
= AREF (binding
, XFASTINT (idx
));
499 else if (CHAR_TABLE_P (binding
))
501 /* Character codes with modifiers
502 are not included in a char-table.
503 All character codes without modifiers are included. */
504 if (INTEGERP (idx
) && (XFASTINT (idx
) & CHAR_MODIFIER_MASK
) == 0)
506 val
= Faref (binding
, idx
);
507 /* `nil' has a special meaning for char-tables, so
508 we use something else to record an explicitly
515 /* If we found a binding, clean it up and return it. */
516 if (!EQ (val
, Qunbound
))
519 /* A Qt binding is just like an explicit nil binding
520 (i.e. it shadows any parent binding but not bindings in
521 keymaps of lower precedence). */
524 val
= get_keyelt (val
, autoload
);
528 if (NILP (retval
) || EQ (retval
, Qunbound
))
531 break; /* Shadows everything that follows. */
533 else if (NILP (retval
) || EQ (retval
, Qunbound
))
535 else if (CONSP (retval_tail
))
537 XSETCDR (retval_tail
, list1 (val
));
538 retval_tail
= XCDR (retval_tail
);
542 retval_tail
= list1 (val
);
543 retval
= Fcons (Qkeymap
, Fcons (retval
, retval_tail
));
549 return EQ (Qunbound
, retval
) ? get_keyelt (t_binding
, autoload
) : retval
;
554 access_keymap (Lisp_Object map
, Lisp_Object idx
,
555 bool t_ok
, bool noinherit
, bool autoload
)
557 Lisp_Object val
= access_keymap_1 (map
, idx
, t_ok
, noinherit
, autoload
);
558 return EQ (val
, Qunbound
) ? Qnil
: val
;
562 map_keymap_item (map_keymap_function_t fun
, Lisp_Object args
, Lisp_Object key
, Lisp_Object val
, void *data
)
566 (*fun
) (key
, val
, args
, data
);
570 map_keymap_char_table_item (Lisp_Object args
, Lisp_Object key
, Lisp_Object val
)
574 map_keymap_function_t fun
575 = (map_keymap_function_t
) XSAVE_FUNCPOINTER (args
, 0);
576 /* If the key is a range, make a copy since map_char_table modifies
579 key
= Fcons (XCAR (key
), XCDR (key
));
580 map_keymap_item (fun
, XSAVE_OBJECT (args
, 2), key
,
581 val
, XSAVE_POINTER (args
, 1));
585 /* Call FUN for every binding in MAP and stop at (and return) the parent.
586 FUN is called with 4 arguments: FUN (KEY, BINDING, ARGS, DATA). */
588 map_keymap_internal (Lisp_Object map
,
589 map_keymap_function_t fun
,
593 struct gcpro gcpro1
, gcpro2
, gcpro3
;
595 = (CONSP (map
) && EQ (Qkeymap
, XCAR (map
))) ? XCDR (map
) : map
;
597 GCPRO3 (map
, args
, tail
);
598 for (; CONSP (tail
) && !EQ (Qkeymap
, XCAR (tail
)); tail
= XCDR (tail
))
600 Lisp_Object binding
= XCAR (tail
);
602 if (KEYMAPP (binding
)) /* An embedded parent. */
604 else if (CONSP (binding
))
605 map_keymap_item (fun
, args
, XCAR (binding
), XCDR (binding
), data
);
606 else if (VECTORP (binding
))
608 /* Loop over the char values represented in the vector. */
609 int len
= ASIZE (binding
);
611 for (c
= 0; c
< len
; c
++)
613 Lisp_Object character
;
614 XSETFASTINT (character
, c
);
615 map_keymap_item (fun
, args
, character
, AREF (binding
, c
), data
);
618 else if (CHAR_TABLE_P (binding
))
619 map_char_table (map_keymap_char_table_item
, Qnil
, binding
,
620 make_save_funcptr_ptr_obj ((voidfuncptr
) fun
, data
,
628 map_keymap_call (Lisp_Object key
, Lisp_Object val
, Lisp_Object fun
, void *dummy
)
630 call2 (fun
, key
, val
);
633 /* Same as map_keymap_internal, but traverses parent keymaps as well.
634 AUTOLOAD indicates that autoloaded keymaps should be loaded. */
636 map_keymap (Lisp_Object map
, map_keymap_function_t fun
, Lisp_Object args
,
637 void *data
, bool autoload
)
641 map
= get_keymap (map
, 1, autoload
);
644 if (KEYMAPP (XCAR (map
)))
646 map_keymap (XCAR (map
), fun
, args
, data
, autoload
);
650 map
= map_keymap_internal (map
, fun
, args
, data
);
652 map
= get_keymap (map
, 0, autoload
);
657 static Lisp_Object Qkeymap_canonicalize
;
659 /* Same as map_keymap, but does it right, properly eliminating duplicate
660 bindings due to inheritance. */
662 map_keymap_canonical (Lisp_Object map
, map_keymap_function_t fun
, Lisp_Object args
, void *data
)
666 /* map_keymap_canonical may be used from redisplay (e.g. when building menus)
667 so be careful to ignore errors and to inhibit redisplay. */
668 map
= safe_call1 (Qkeymap_canonicalize
, map
);
669 /* No need to use `map_keymap' here because canonical map has no parent. */
670 map_keymap_internal (map
, fun
, args
, data
);
674 DEFUN ("map-keymap-internal", Fmap_keymap_internal
, Smap_keymap_internal
, 2, 2, 0,
675 doc
: /* Call FUNCTION once for each event binding in KEYMAP.
676 FUNCTION is called with two arguments: the event that is bound, and
677 the definition it is bound to. The event may be a character range.
678 If KEYMAP has a parent, this function returns it without processing it. */)
679 (Lisp_Object function
, Lisp_Object keymap
)
683 keymap
= get_keymap (keymap
, 1, 1);
684 keymap
= map_keymap_internal (keymap
, map_keymap_call
, function
, NULL
);
689 DEFUN ("map-keymap", Fmap_keymap
, Smap_keymap
, 2, 3, 0,
690 doc
: /* Call FUNCTION once for each event binding in KEYMAP.
691 FUNCTION is called with two arguments: the event that is bound, and
692 the definition it is bound to. The event may be a character range.
694 If KEYMAP has a parent, the parent's bindings are included as well.
695 This works recursively: if the parent has itself a parent, then the
696 grandparent's bindings are also included and so on.
697 usage: (map-keymap FUNCTION KEYMAP) */)
698 (Lisp_Object function
, Lisp_Object keymap
, Lisp_Object sort_first
)
700 if (! NILP (sort_first
))
701 return call2 (intern ("map-keymap-sorted"), function
, keymap
);
703 map_keymap (keymap
, map_keymap_call
, function
, NULL
, 1);
707 /* Given OBJECT which was found in a slot in a keymap,
708 trace indirect definitions to get the actual definition of that slot.
709 An indirect definition is a list of the form
710 (KEYMAP . INDEX), where KEYMAP is a keymap or a symbol defined as one
711 and INDEX is the object to look up in KEYMAP to yield the definition.
713 Also if OBJECT has a menu string as the first element,
714 remove that. Also remove a menu help string as second element.
716 If AUTOLOAD, load autoloadable keymaps
717 that are referred to with indirection.
719 This can GC because menu_item_eval_property calls Feval. */
722 get_keyelt (Lisp_Object object
, bool autoload
)
726 if (!(CONSP (object
)))
727 /* This is really the value. */
730 /* If the keymap contents looks like (menu-item name . DEFN)
731 or (menu-item name DEFN ...) then use DEFN.
732 This is a new format menu item. */
733 else if (EQ (XCAR (object
), Qmenu_item
))
735 if (CONSP (XCDR (object
)))
739 object
= XCDR (XCDR (object
));
742 object
= XCAR (object
);
744 /* If there's a `:filter FILTER', apply FILTER to the
745 menu-item's definition to get the real definition to
747 for (; CONSP (tem
) && CONSP (XCDR (tem
)); tem
= XCDR (tem
))
748 if (EQ (XCAR (tem
), QCfilter
) && autoload
)
751 filter
= XCAR (XCDR (tem
));
752 filter
= list2 (filter
, list2 (Qquote
, object
));
753 object
= menu_item_eval_property (filter
);
758 /* Invalid keymap. */
762 /* If the keymap contents looks like (STRING . DEFN), use DEFN.
763 Keymap alist elements like (CHAR MENUSTRING . DEFN)
764 will be used by HierarKey menus. */
765 else if (STRINGP (XCAR (object
)))
766 object
= XCDR (object
);
774 store_in_keymap (Lisp_Object keymap
, register Lisp_Object idx
, Lisp_Object def
)
776 /* Flush any reverse-map cache. */
777 where_is_cache
= Qnil
;
778 where_is_cache_keymaps
= Qt
;
780 if (EQ (idx
, Qkeymap
))
781 error ("`keymap' is reserved for embedded parent maps");
783 /* If we are preparing to dump, and DEF is a menu element
784 with a menu item indicator, copy it to ensure it is not pure. */
785 if (CONSP (def
) && PURE_P (def
)
786 && (EQ (XCAR (def
), Qmenu_item
) || STRINGP (XCAR (def
))))
787 def
= Fcons (XCAR (def
), XCDR (def
));
789 if (!CONSP (keymap
) || !EQ (XCAR (keymap
), Qkeymap
))
790 error ("attempt to define a key in a non-keymap");
792 /* If idx is a cons, and the car part is a character, idx must be of
793 the form (FROM-CHAR . TO-CHAR). */
794 if (CONSP (idx
) && CHARACTERP (XCAR (idx
)))
795 CHECK_CHARACTER_CDR (idx
);
797 /* If idx is a list (some sort of mouse click, perhaps?),
798 the index we want to use is the car of the list, which
799 ought to be a symbol. */
800 idx
= EVENT_HEAD (idx
);
802 /* If idx is a symbol, it might have modifiers, which need to
803 be put in the canonical order. */
805 idx
= reorder_modifiers (idx
);
806 else if (INTEGERP (idx
))
807 /* Clobber the high bits that can be present on a machine
808 with more than 24 bits of integer. */
809 XSETFASTINT (idx
, XINT (idx
) & (CHAR_META
| (CHAR_META
- 1)));
811 /* Scan the keymap for a binding of idx. */
815 /* The cons after which we should insert new bindings. If the
816 keymap has a table element, we record its position here, so new
817 bindings will go after it; this way, the table will stay
818 towards the front of the alist and character lookups in dense
819 keymaps will remain fast. Otherwise, this just points at the
820 front of the keymap. */
821 Lisp_Object insertion_point
;
823 insertion_point
= keymap
;
824 for (tail
= XCDR (keymap
); CONSP (tail
); tail
= XCDR (tail
))
831 if (NATNUMP (idx
) && XFASTINT (idx
) < ASIZE (elt
))
834 ASET (elt
, XFASTINT (idx
), def
);
837 else if (CONSP (idx
) && CHARACTERP (XCAR (idx
)))
839 int from
= XFASTINT (XCAR (idx
));
840 int to
= XFASTINT (XCDR (idx
));
842 if (to
>= ASIZE (elt
))
843 to
= ASIZE (elt
) - 1;
844 for (; from
<= to
; from
++)
845 ASET (elt
, from
, def
);
846 if (to
== XFASTINT (XCDR (idx
)))
847 /* We have defined all keys in IDX. */
850 insertion_point
= tail
;
852 else if (CHAR_TABLE_P (elt
))
854 /* Character codes with modifiers
855 are not included in a char-table.
856 All character codes without modifiers are included. */
857 if (NATNUMP (idx
) && !(XFASTINT (idx
) & CHAR_MODIFIER_MASK
))
860 /* `nil' has a special meaning for char-tables, so
861 we use something else to record an explicitly
863 NILP (def
) ? Qt
: def
);
866 else if (CONSP (idx
) && CHARACTERP (XCAR (idx
)))
868 Fset_char_table_range (elt
, idx
, NILP (def
) ? Qt
: def
);
871 insertion_point
= tail
;
873 else if (CONSP (elt
))
875 if (EQ (Qkeymap
, XCAR (elt
)))
876 { /* A sub keymap. This might be due to a lookup that found
877 two matching bindings (maybe because of a sub keymap).
878 It almost never happens (since the second binding normally
879 only happens in the inherited part of the keymap), but
880 if it does, we want to update the sub-keymap since the
881 main one might be temporary (built by access_keymap). */
882 tail
= insertion_point
= elt
;
884 else if (EQ (idx
, XCAR (elt
)))
890 else if (CONSP (idx
) && CHARACTERP (XCAR (idx
)))
892 int from
= XFASTINT (XCAR (idx
));
893 int to
= XFASTINT (XCDR (idx
));
895 if (from
<= XFASTINT (XCAR (elt
))
896 && to
>= XFASTINT (XCAR (elt
)))
904 else if (EQ (elt
, Qkeymap
))
905 /* If we find a 'keymap' symbol in the spine of KEYMAP,
906 then we must have found the start of a second keymap
907 being used as the tail of KEYMAP, and a binding for IDX
908 should be inserted before it. */
915 /* We have scanned the entire keymap, and not found a binding for
916 IDX. Let's add one. */
920 if (CONSP (idx
) && CHARACTERP (XCAR (idx
)))
922 /* IDX specifies a range of characters, and not all of them
923 were handled yet, which means this keymap doesn't have a
924 char-table. So, we insert a char-table now. */
925 elt
= Fmake_char_table (Qkeymap
, Qnil
);
926 Fset_char_table_range (elt
, idx
, NILP (def
) ? Qt
: def
);
929 elt
= Fcons (idx
, def
);
930 CHECK_IMPURE (insertion_point
);
931 XSETCDR (insertion_point
, Fcons (elt
, XCDR (insertion_point
)));
939 copy_keymap_item (Lisp_Object elt
)
941 Lisp_Object res
, tem
;
948 /* Is this a new format menu item. */
949 if (EQ (XCAR (tem
), Qmenu_item
))
951 /* Copy cell with menu-item marker. */
952 res
= elt
= Fcons (XCAR (tem
), XCDR (tem
));
956 /* Copy cell with menu-item name. */
957 XSETCDR (elt
, Fcons (XCAR (tem
), XCDR (tem
)));
963 /* Copy cell with binding and if the binding is a keymap,
965 XSETCDR (elt
, Fcons (XCAR (tem
), XCDR (tem
)));
968 if (CONSP (tem
) && EQ (XCAR (tem
), Qkeymap
))
969 XSETCAR (elt
, Fcopy_keymap (tem
));
975 /* It may be an old format menu item.
976 Skip the optional menu string. */
977 if (STRINGP (XCAR (tem
)))
979 /* Copy the cell, since copy-alist didn't go this deep. */
980 res
= elt
= Fcons (XCAR (tem
), XCDR (tem
));
982 /* Also skip the optional menu help string. */
983 if (CONSP (tem
) && STRINGP (XCAR (tem
)))
985 XSETCDR (elt
, Fcons (XCAR (tem
), XCDR (tem
)));
989 if (CONSP (tem
) && EQ (XCAR (tem
), Qkeymap
))
990 XSETCDR (elt
, Fcopy_keymap (tem
));
992 else if (EQ (XCAR (tem
), Qkeymap
))
993 res
= Fcopy_keymap (elt
);
999 copy_keymap_1 (Lisp_Object chartable
, Lisp_Object idx
, Lisp_Object elt
)
1001 Fset_char_table_range (chartable
, idx
, copy_keymap_item (elt
));
1004 DEFUN ("copy-keymap", Fcopy_keymap
, Scopy_keymap
, 1, 1, 0,
1005 doc
: /* Return a copy of the keymap KEYMAP.
1006 The copy starts out with the same definitions of KEYMAP,
1007 but changing either the copy or KEYMAP does not affect the other.
1008 Any key definitions that are subkeymaps are recursively copied.
1009 However, a key definition which is a symbol whose definition is a keymap
1011 (Lisp_Object keymap
)
1013 Lisp_Object copy
, tail
;
1014 keymap
= get_keymap (keymap
, 1, 0);
1015 copy
= tail
= list1 (Qkeymap
);
1016 keymap
= XCDR (keymap
); /* Skip the `keymap' symbol. */
1018 while (CONSP (keymap
) && !EQ (XCAR (keymap
), Qkeymap
))
1020 Lisp_Object elt
= XCAR (keymap
);
1021 if (CHAR_TABLE_P (elt
))
1023 elt
= Fcopy_sequence (elt
);
1024 map_char_table (copy_keymap_1
, Qnil
, elt
, elt
);
1026 else if (VECTORP (elt
))
1029 elt
= Fcopy_sequence (elt
);
1030 for (i
= 0; i
< ASIZE (elt
); i
++)
1031 ASET (elt
, i
, copy_keymap_item (AREF (elt
, i
)));
1033 else if (CONSP (elt
))
1035 if (EQ (XCAR (elt
), Qkeymap
))
1036 /* This is a sub keymap. */
1037 elt
= Fcopy_keymap (elt
);
1039 elt
= Fcons (XCAR (elt
), copy_keymap_item (XCDR (elt
)));
1041 XSETCDR (tail
, list1 (elt
));
1043 keymap
= XCDR (keymap
);
1045 XSETCDR (tail
, keymap
);
1049 /* Simple Keymap mutators and accessors. */
1051 /* GC is possible in this function if it autoloads a keymap. */
1053 DEFUN ("define-key", Fdefine_key
, Sdefine_key
, 3, 3, 0,
1054 doc
: /* In KEYMAP, define key sequence KEY as DEF.
1057 KEY is a string or a vector of symbols and characters, representing a
1058 sequence of keystrokes and events. Non-ASCII characters with codes
1059 above 127 (such as ISO Latin-1) can be represented by vectors.
1060 Two types of vector have special meanings:
1061 [remap COMMAND] remaps any key binding for COMMAND.
1062 [t] creates a default definition, which applies to any event with no
1063 other definition in KEYMAP.
1065 DEF is anything that can be a key's definition:
1066 nil (means key is undefined in this keymap),
1067 a command (a Lisp function suitable for interactive calling),
1068 a string (treated as a keyboard macro),
1069 a keymap (to define a prefix key),
1070 a symbol (when the key is looked up, the symbol will stand for its
1071 function definition, which should at that time be one of the above,
1072 or another symbol whose function definition is used, etc.),
1073 a cons (STRING . DEFN), meaning that DEFN is the definition
1074 (DEFN should be a valid definition in its own right),
1075 or a cons (MAP . CHAR), meaning use definition of CHAR in keymap MAP,
1076 or an extended menu item definition.
1077 (See info node `(elisp)Extended Menu Items'.)
1079 If KEYMAP is a sparse keymap with a binding for KEY, the existing
1080 binding is altered. If there is no binding for KEY, the new pair
1081 binding KEY to DEF is added at the front of KEYMAP. */)
1082 (Lisp_Object keymap
, Lisp_Object key
, Lisp_Object def
)
1090 struct gcpro gcpro1
, gcpro2
, gcpro3
;
1092 GCPRO3 (keymap
, key
, def
);
1093 keymap
= get_keymap (keymap
, 1, 1);
1095 length
= CHECK_VECTOR_OR_STRING (key
);
1097 RETURN_UNGCPRO (Qnil
);
1099 if (SYMBOLP (def
) && !EQ (Vdefine_key_rebound_commands
, Qt
))
1100 Vdefine_key_rebound_commands
= Fcons (def
, Vdefine_key_rebound_commands
);
1102 meta_bit
= (VECTORP (key
) || (STRINGP (key
) && STRING_MULTIBYTE (key
))
1103 ? meta_modifier
: 0x80);
1105 if (VECTORP (def
) && ASIZE (def
) > 0 && CONSP (AREF (def
, 0)))
1106 { /* DEF is apparently an XEmacs-style keyboard macro. */
1107 Lisp_Object tmp
= Fmake_vector (make_number (ASIZE (def
)), Qnil
);
1108 ptrdiff_t i
= ASIZE (def
);
1111 Lisp_Object defi
= AREF (def
, i
);
1112 if (CONSP (defi
) && lucid_event_type_list_p (defi
))
1113 defi
= Fevent_convert_list (defi
);
1114 ASET (tmp
, i
, defi
);
1122 c
= Faref (key
, make_number (idx
));
1126 /* C may be a Lucid style event type list or a cons (FROM .
1127 TO) specifying a range of characters. */
1128 if (lucid_event_type_list_p (c
))
1129 c
= Fevent_convert_list (c
);
1130 else if (CHARACTERP (XCAR (c
)))
1131 CHECK_CHARACTER_CDR (c
);
1135 silly_event_symbol_error (c
);
1138 && (XINT (c
) & meta_bit
)
1141 c
= meta_prefix_char
;
1147 XSETINT (c
, XINT (c
) & ~meta_bit
);
1153 if (!INTEGERP (c
) && !SYMBOLP (c
)
1155 /* If C is a range, it must be a leaf. */
1156 || (INTEGERP (XCAR (c
)) && idx
!= length
)))
1157 message_with_string ("Key sequence contains invalid event %s", c
, 1);
1160 RETURN_UNGCPRO (store_in_keymap (keymap
, c
, def
));
1162 cmd
= access_keymap (keymap
, c
, 0, 1, 1);
1164 /* If this key is undefined, make it a prefix. */
1166 cmd
= define_as_prefix (keymap
, c
);
1168 keymap
= get_keymap (cmd
, 0, 1);
1169 if (!CONSP (keymap
))
1171 const char *trailing_esc
= ((EQ (c
, meta_prefix_char
) && metized
)
1172 ? (idx
== 0 ? "ESC" : " ESC")
1175 /* We must use Fkey_description rather than just passing key to
1176 error; key might be a vector, not a string. */
1177 error ("Key sequence %s starts with non-prefix key %s%s",
1178 SDATA (Fkey_description (key
, Qnil
)),
1179 SDATA (Fkey_description (Fsubstring (key
, make_number (0),
1187 /* This function may GC (it calls Fkey_binding). */
1189 DEFUN ("command-remapping", Fcommand_remapping
, Scommand_remapping
, 1, 3, 0,
1190 doc
: /* Return the remapping for command COMMAND.
1191 Returns nil if COMMAND is not remapped (or not a symbol).
1193 If the optional argument POSITION is non-nil, it specifies a mouse
1194 position as returned by `event-start' and `event-end', and the
1195 remapping occurs in the keymaps associated with it. It can also be a
1196 number or marker, in which case the keymap properties at the specified
1197 buffer position instead of point are used. The KEYMAPS argument is
1198 ignored if POSITION is non-nil.
1200 If the optional argument KEYMAPS is non-nil, it should be a list of
1201 keymaps to search for command remapping. Otherwise, search for the
1202 remapping in all currently active keymaps. */)
1203 (Lisp_Object command
, Lisp_Object position
, Lisp_Object keymaps
)
1205 if (!SYMBOLP (command
))
1208 ASET (command_remapping_vector
, 1, command
);
1211 command
= Fkey_binding (command_remapping_vector
, Qnil
, Qt
, position
);
1213 command
= Flookup_key (Fcons (Qkeymap
, keymaps
),
1214 command_remapping_vector
, Qnil
);
1215 return INTEGERP (command
) ? Qnil
: command
;
1218 /* Value is number if KEY is too long; nil if valid but has no definition. */
1219 /* GC is possible in this function. */
1221 DEFUN ("lookup-key", Flookup_key
, Slookup_key
, 2, 3, 0,
1222 doc
: /* In keymap KEYMAP, look up key sequence KEY. Return the definition.
1223 A value of nil means undefined. See doc of `define-key'
1224 for kinds of definitions.
1226 A number as value means KEY is "too long";
1227 that is, characters or symbols in it except for the last one
1228 fail to be a valid sequence of prefix characters in KEYMAP.
1229 The number is how many characters at the front of KEY
1230 it takes to reach a non-prefix key.
1232 Normally, `lookup-key' ignores bindings for t, which act as default
1233 bindings, used when nothing else in the keymap applies; this makes it
1234 usable as a general function for probing keymaps. However, if the
1235 third optional argument ACCEPT-DEFAULT is non-nil, `lookup-key' will
1236 recognize the default bindings, just as `read-key-sequence' does. */)
1237 (Lisp_Object keymap
, Lisp_Object key
, Lisp_Object accept_default
)
1243 bool t_ok
= !NILP (accept_default
);
1244 struct gcpro gcpro1
, gcpro2
;
1246 GCPRO2 (keymap
, key
);
1247 keymap
= get_keymap (keymap
, 1, 1);
1249 length
= CHECK_VECTOR_OR_STRING (key
);
1251 RETURN_UNGCPRO (keymap
);
1256 c
= Faref (key
, make_number (idx
++));
1258 if (CONSP (c
) && lucid_event_type_list_p (c
))
1259 c
= Fevent_convert_list (c
);
1261 /* Turn the 8th bit of string chars into a meta modifier. */
1262 if (STRINGP (key
) && XINT (c
) & 0x80 && !STRING_MULTIBYTE (key
))
1263 XSETINT (c
, (XINT (c
) | meta_modifier
) & ~0x80);
1265 /* Allow string since binding for `menu-bar-select-buffer'
1266 includes the buffer name in the key sequence. */
1267 if (!INTEGERP (c
) && !SYMBOLP (c
) && !CONSP (c
) && !STRINGP (c
))
1268 message_with_string ("Key sequence contains invalid event %s", c
, 1);
1270 cmd
= access_keymap (keymap
, c
, t_ok
, 0, 1);
1272 RETURN_UNGCPRO (cmd
);
1274 keymap
= get_keymap (cmd
, 0, 1);
1275 if (!CONSP (keymap
))
1276 RETURN_UNGCPRO (make_number (idx
));
1282 /* Make KEYMAP define event C as a keymap (i.e., as a prefix).
1283 Assume that currently it does not define C at all.
1284 Return the keymap. */
1287 define_as_prefix (Lisp_Object keymap
, Lisp_Object c
)
1291 cmd
= Fmake_sparse_keymap (Qnil
);
1292 store_in_keymap (keymap
, c
, cmd
);
1297 /* Append a key to the end of a key sequence. We always make a vector. */
1300 append_key (Lisp_Object key_sequence
, Lisp_Object key
)
1302 return Fvconcat (2, ((Lisp_Object
[]) { key_sequence
, scoped_list1 (key
) }));
1305 /* Given a event type C which is a symbol,
1306 signal an error if is a mistake such as RET or M-RET or C-DEL, etc. */
1309 silly_event_symbol_error (Lisp_Object c
)
1312 Lisp_Object parsed
, base
, name
, assoc
;
1315 parsed
= parse_modifiers (c
);
1316 modifiers
= XFASTINT (XCAR (XCDR (parsed
)));
1317 base
= XCAR (parsed
);
1318 name
= Fsymbol_name (base
);
1319 /* This alist includes elements such as ("RET" . "\\r"). */
1320 assoc
= Fassoc (name
, exclude_keys
);
1324 char new_mods
[sizeof ("\\A-\\C-\\H-\\M-\\S-\\s-")];
1326 Lisp_Object keystring
;
1327 if (modifiers
& alt_modifier
)
1328 { *p
++ = '\\'; *p
++ = 'A'; *p
++ = '-'; }
1329 if (modifiers
& ctrl_modifier
)
1330 { *p
++ = '\\'; *p
++ = 'C'; *p
++ = '-'; }
1331 if (modifiers
& hyper_modifier
)
1332 { *p
++ = '\\'; *p
++ = 'H'; *p
++ = '-'; }
1333 if (modifiers
& meta_modifier
)
1334 { *p
++ = '\\'; *p
++ = 'M'; *p
++ = '-'; }
1335 if (modifiers
& shift_modifier
)
1336 { *p
++ = '\\'; *p
++ = 'S'; *p
++ = '-'; }
1337 if (modifiers
& super_modifier
)
1338 { *p
++ = '\\'; *p
++ = 's'; *p
++ = '-'; }
1341 c
= reorder_modifiers (c
);
1342 keystring
= concat2 (build_local_string (new_mods
), XCDR (assoc
));
1344 error ("To bind the key %s, use [?%s], not [%s]",
1345 SDATA (SYMBOL_NAME (c
)), SDATA (keystring
),
1346 SDATA (SYMBOL_NAME (c
)));
1350 /* Global, local, and minor mode keymap stuff. */
1352 /* We can't put these variables inside current_minor_maps, since under
1353 some systems, static gets macro-defined to be the empty string.
1355 static Lisp_Object
*cmm_modes
= NULL
, *cmm_maps
= NULL
;
1356 static ptrdiff_t cmm_size
= 0;
1358 /* Store a pointer to an array of the currently active minor modes in
1359 *modeptr, a pointer to an array of the keymaps of the currently
1360 active minor modes in *mapptr, and return the number of maps
1363 This function always returns a pointer to the same buffer, and may
1364 free or reallocate it, so if you want to keep it for a long time or
1365 hand it out to lisp code, copy it. This procedure will be called
1366 for every key sequence read, so the nice lispy approach (return a
1367 new assoclist, list, what have you) for each invocation would
1368 result in a lot of consing over time.
1370 If we used xrealloc/xmalloc and ran out of memory, they would throw
1371 back to the command loop, which would try to read a key sequence,
1372 which would call this function again, resulting in an infinite
1373 loop. Instead, we'll use realloc/malloc and silently truncate the
1374 list, let the key sequence be read, and hope some other piece of
1375 code signals the error. */
1377 current_minor_maps (Lisp_Object
**modeptr
, Lisp_Object
**mapptr
)
1380 int list_number
= 0;
1381 Lisp_Object alist
, assoc
, var
, val
;
1382 Lisp_Object emulation_alists
;
1383 Lisp_Object lists
[2];
1385 emulation_alists
= Vemulation_mode_map_alists
;
1386 lists
[0] = Vminor_mode_overriding_map_alist
;
1387 lists
[1] = Vminor_mode_map_alist
;
1389 for (list_number
= 0; list_number
< 2; list_number
++)
1391 if (CONSP (emulation_alists
))
1393 alist
= XCAR (emulation_alists
);
1394 emulation_alists
= XCDR (emulation_alists
);
1395 if (SYMBOLP (alist
))
1396 alist
= find_symbol_value (alist
);
1400 alist
= lists
[list_number
];
1402 for ( ; CONSP (alist
); alist
= XCDR (alist
))
1403 if ((assoc
= XCAR (alist
), CONSP (assoc
))
1404 && (var
= XCAR (assoc
), SYMBOLP (var
))
1405 && (val
= find_symbol_value (var
), !EQ (val
, Qunbound
))
1410 /* If a variable has an entry in Vminor_mode_overriding_map_alist,
1411 and also an entry in Vminor_mode_map_alist,
1412 ignore the latter. */
1413 if (list_number
== 1)
1415 val
= assq_no_quit (var
, lists
[0]);
1422 ptrdiff_t newsize
, allocsize
;
1423 Lisp_Object
*newmodes
, *newmaps
;
1425 /* Check for size calculation overflow. Other code
1426 (e.g., read_key_sequence) adds 3 to the count
1427 later, so subtract 3 from the limit here. */
1428 if (min (PTRDIFF_MAX
, SIZE_MAX
) / (2 * sizeof *newmodes
) - 3
1432 newsize
= cmm_size
== 0 ? 30 : cmm_size
* 2;
1433 allocsize
= newsize
* sizeof *newmodes
;
1435 /* Use malloc here. See the comment above this function.
1436 Avoid realloc here; it causes spurious traps on GNU/Linux [KFS] */
1438 newmodes
= malloc (allocsize
);
1443 memcpy (newmodes
, cmm_modes
,
1444 cmm_size
* sizeof cmm_modes
[0]);
1447 cmm_modes
= newmodes
;
1450 newmaps
= malloc (allocsize
);
1455 memcpy (newmaps
, cmm_maps
,
1456 cmm_size
* sizeof cmm_maps
[0]);
1463 if (newmodes
== NULL
|| newmaps
== NULL
)
1468 /* Get the keymap definition--or nil if it is not defined. */
1469 temp
= Findirect_function (XCDR (assoc
), Qt
);
1473 cmm_maps
[i
] = temp
;
1479 if (modeptr
) *modeptr
= cmm_modes
;
1480 if (mapptr
) *mapptr
= cmm_maps
;
1484 /* Return the offset of POSITION, a click position, in the style of
1485 the respective argument of Fkey_binding. */
1487 click_position (Lisp_Object position
)
1489 EMACS_INT pos
= (INTEGERP (position
) ? XINT (position
)
1490 : MARKERP (position
) ? marker_position (position
)
1492 if (! (BEGV
<= pos
&& pos
<= ZV
))
1493 args_out_of_range (Fcurrent_buffer (), position
);
1497 DEFUN ("current-active-maps", Fcurrent_active_maps
, Scurrent_active_maps
,
1499 doc
: /* Return a list of the currently active keymaps.
1500 OLP if non-nil indicates that we should obey `overriding-local-map' and
1501 `overriding-terminal-local-map'. POSITION can specify a click position
1502 like in the respective argument of `key-binding'. */)
1503 (Lisp_Object olp
, Lisp_Object position
)
1505 ptrdiff_t count
= SPECPDL_INDEX ();
1507 Lisp_Object keymaps
= list1 (current_global_map
);
1509 /* If a mouse click position is given, our variables are based on
1510 the buffer clicked on, not the current buffer. So we may have to
1511 switch the buffer here. */
1513 if (CONSP (position
))
1517 window
= POSN_WINDOW (position
);
1519 if (WINDOWP (window
)
1520 && BUFFERP (XWINDOW (window
)->contents
)
1521 && XBUFFER (XWINDOW (window
)->contents
) != current_buffer
)
1523 /* Arrange to go back to the original buffer once we're done
1524 processing the key sequence. We don't use
1525 save_excursion_{save,restore} here, in analogy to
1526 `read-key-sequence' to avoid saving point. Maybe this
1527 would not be a problem here, but it is easier to keep
1530 record_unwind_current_buffer ();
1531 set_buffer_internal (XBUFFER (XWINDOW (window
)->contents
));
1536 /* The doc said that overriding-terminal-local-map should
1537 override overriding-local-map. The code used them both,
1538 but it seems clearer to use just one. rms, jan 2005. */
1539 && NILP (KVAR (current_kboard
, Voverriding_terminal_local_map
))
1540 && !NILP (Voverriding_local_map
))
1541 keymaps
= Fcons (Voverriding_local_map
, keymaps
);
1543 if (NILP (XCDR (keymaps
)))
1547 ptrdiff_t pt
= click_position (position
);
1548 /* This usually returns the buffer's local map,
1549 but that can be overridden by a `local-map' property. */
1550 Lisp_Object local_map
= get_local_map (pt
, current_buffer
, Qlocal_map
);
1551 /* This returns nil unless there is a `keymap' property. */
1552 Lisp_Object keymap
= get_local_map (pt
, current_buffer
, Qkeymap
);
1553 Lisp_Object otlp
= KVAR (current_kboard
, Voverriding_terminal_local_map
);
1555 if (CONSP (position
))
1557 Lisp_Object string
= POSN_STRING (position
);
1559 /* For a mouse click, get the local text-property keymap
1560 of the place clicked on, rather than point. */
1562 if (POSN_INBUFFER_P (position
))
1566 pos
= POSN_BUFFER_POSN (position
);
1568 && XINT (pos
) >= BEG
&& XINT (pos
) <= Z
)
1570 local_map
= get_local_map (XINT (pos
),
1571 current_buffer
, Qlocal_map
);
1573 keymap
= get_local_map (XINT (pos
),
1574 current_buffer
, Qkeymap
);
1578 /* If on a mode line string with a local keymap,
1579 or for a click on a string, i.e. overlay string or a
1580 string displayed via the `display' property,
1581 consider `local-map' and `keymap' properties of
1584 if (CONSP (string
) && STRINGP (XCAR (string
)))
1586 Lisp_Object pos
, map
;
1588 pos
= XCDR (string
);
1589 string
= XCAR (string
);
1592 && XINT (pos
) < SCHARS (string
))
1594 map
= Fget_text_property (pos
, Qlocal_map
, string
);
1598 map
= Fget_text_property (pos
, Qkeymap
, string
);
1606 if (!NILP (local_map
))
1607 keymaps
= Fcons (local_map
, keymaps
);
1609 /* Now put all the minor mode keymaps on the list. */
1610 nmaps
= current_minor_maps (0, &maps
);
1612 for (i
= --nmaps
; i
>= 0; i
--)
1613 if (!NILP (maps
[i
]))
1614 keymaps
= Fcons (maps
[i
], keymaps
);
1617 keymaps
= Fcons (keymap
, keymaps
);
1619 if (!NILP (olp
) && !NILP (otlp
))
1620 keymaps
= Fcons (otlp
, keymaps
);
1623 unbind_to (count
, Qnil
);
1628 /* GC is possible in this function if it autoloads a keymap. */
1630 DEFUN ("key-binding", Fkey_binding
, Skey_binding
, 1, 4, 0,
1631 doc
: /* Return the binding for command KEY in current keymaps.
1632 KEY is a string or vector, a sequence of keystrokes.
1633 The binding is probably a symbol with a function definition.
1635 Normally, `key-binding' ignores bindings for t, which act as default
1636 bindings, used when nothing else in the keymap applies; this makes it
1637 usable as a general function for probing keymaps. However, if the
1638 optional second argument ACCEPT-DEFAULT is non-nil, `key-binding' does
1639 recognize the default bindings, just as `read-key-sequence' does.
1641 Like the normal command loop, `key-binding' will remap the command
1642 resulting from looking up KEY by looking up the command in the
1643 current keymaps. However, if the optional third argument NO-REMAP
1644 is non-nil, `key-binding' returns the unmapped command.
1646 If KEY is a key sequence initiated with the mouse, the used keymaps
1647 will depend on the clicked mouse position with regard to the buffer
1648 and possible local keymaps on strings.
1650 If the optional argument POSITION is non-nil, it specifies a mouse
1651 position as returned by `event-start' and `event-end', and the lookup
1652 occurs in the keymaps associated with it instead of KEY. It can also
1653 be a number or marker, in which case the keymap properties at the
1654 specified buffer position instead of point are used.
1656 (Lisp_Object key
, Lisp_Object accept_default
, Lisp_Object no_remap
, Lisp_Object position
)
1660 if (NILP (position
) && VECTORP (key
))
1663 /* mouse events may have a symbolic prefix indicating the
1664 scrollbar or mode line */
1665 = AREF (key
, SYMBOLP (AREF (key
, 0)) && ASIZE (key
) > 1 ? 1 : 0);
1667 /* We are not interested in locations without event data */
1669 if (EVENT_HAS_PARAMETERS (event
) && CONSP (XCDR (event
)))
1671 Lisp_Object kind
= EVENT_HEAD_KIND (EVENT_HEAD (event
));
1672 if (EQ (kind
, Qmouse_click
))
1673 position
= EVENT_START (event
);
1677 value
= Flookup_key (Fcons (Qkeymap
, Fcurrent_active_maps (Qt
, position
)),
1678 key
, accept_default
);
1680 if (NILP (value
) || INTEGERP (value
))
1683 /* If the result of the ordinary keymap lookup is an interactive
1684 command, look for a key binding (ie. remapping) for that command. */
1686 if (NILP (no_remap
) && SYMBOLP (value
))
1689 if (value1
= Fcommand_remapping (value
, position
, Qnil
), !NILP (value1
))
1696 /* GC is possible in this function if it autoloads a keymap. */
1698 DEFUN ("local-key-binding", Flocal_key_binding
, Slocal_key_binding
, 1, 2, 0,
1699 doc
: /* Return the binding for command KEYS in current local keymap only.
1700 KEYS is a string or vector, a sequence of keystrokes.
1701 The binding is probably a symbol with a function definition.
1703 If optional argument ACCEPT-DEFAULT is non-nil, recognize default
1704 bindings; see the description of `lookup-key' for more details about this. */)
1705 (Lisp_Object keys
, Lisp_Object accept_default
)
1707 register Lisp_Object map
;
1708 map
= BVAR (current_buffer
, keymap
);
1711 return Flookup_key (map
, keys
, accept_default
);
1714 /* GC is possible in this function if it autoloads a keymap. */
1716 DEFUN ("global-key-binding", Fglobal_key_binding
, Sglobal_key_binding
, 1, 2, 0,
1717 doc
: /* Return the binding for command KEYS in current global keymap only.
1718 KEYS is a string or vector, a sequence of keystrokes.
1719 The binding is probably a symbol with a function definition.
1720 This function's return values are the same as those of `lookup-key'
1723 If optional argument ACCEPT-DEFAULT is non-nil, recognize default
1724 bindings; see the description of `lookup-key' for more details about this. */)
1725 (Lisp_Object keys
, Lisp_Object accept_default
)
1727 return Flookup_key (current_global_map
, keys
, accept_default
);
1730 /* GC is possible in this function if it autoloads a keymap. */
1732 DEFUN ("minor-mode-key-binding", Fminor_mode_key_binding
, Sminor_mode_key_binding
, 1, 2, 0,
1733 doc
: /* Find the visible minor mode bindings of KEY.
1734 Return an alist of pairs (MODENAME . BINDING), where MODENAME is
1735 the symbol which names the minor mode binding KEY, and BINDING is
1736 KEY's definition in that mode. In particular, if KEY has no
1737 minor-mode bindings, return nil. If the first binding is a
1738 non-prefix, all subsequent bindings will be omitted, since they would
1739 be ignored. Similarly, the list doesn't include non-prefix bindings
1740 that come after prefix bindings.
1742 If optional argument ACCEPT-DEFAULT is non-nil, recognize default
1743 bindings; see the description of `lookup-key' for more details about this. */)
1744 (Lisp_Object key
, Lisp_Object accept_default
)
1746 Lisp_Object
*modes
, *maps
;
1748 Lisp_Object binding
;
1750 struct gcpro gcpro1
, gcpro2
;
1752 nmaps
= current_minor_maps (&modes
, &maps
);
1753 /* Note that all these maps are GCPRO'd
1754 in the places where we found them. */
1757 GCPRO2 (key
, binding
);
1759 for (i
= j
= 0; i
< nmaps
; i
++)
1761 && !NILP (binding
= Flookup_key (maps
[i
], key
, accept_default
))
1762 && !INTEGERP (binding
))
1764 if (KEYMAPP (binding
))
1765 maps
[j
++] = Fcons (modes
[i
], binding
);
1767 RETURN_UNGCPRO (list1 (Fcons (modes
[i
], binding
)));
1771 return Flist (j
, maps
);
1774 DEFUN ("define-prefix-command", Fdefine_prefix_command
, Sdefine_prefix_command
, 1, 3, 0,
1775 doc
: /* Define COMMAND as a prefix command. COMMAND should be a symbol.
1776 A new sparse keymap is stored as COMMAND's function definition and its value.
1777 If a second optional argument MAPVAR is given, the map is stored as
1778 its value instead of as COMMAND's value; but COMMAND is still defined
1780 The third optional argument NAME, if given, supplies a menu name
1781 string for the map. This is required to use the keymap as a menu.
1782 This function returns COMMAND. */)
1783 (Lisp_Object command
, Lisp_Object mapvar
, Lisp_Object name
)
1786 map
= Fmake_sparse_keymap (name
);
1787 Ffset (command
, map
);
1791 Fset (command
, map
);
1795 DEFUN ("use-global-map", Fuse_global_map
, Suse_global_map
, 1, 1, 0,
1796 doc
: /* Select KEYMAP as the global keymap. */)
1797 (Lisp_Object keymap
)
1799 keymap
= get_keymap (keymap
, 1, 1);
1800 current_global_map
= keymap
;
1805 DEFUN ("use-local-map", Fuse_local_map
, Suse_local_map
, 1, 1, 0,
1806 doc
: /* Select KEYMAP as the local keymap.
1807 If KEYMAP is nil, that means no local keymap. */)
1808 (Lisp_Object keymap
)
1811 keymap
= get_keymap (keymap
, 1, 1);
1813 bset_keymap (current_buffer
, keymap
);
1818 DEFUN ("current-local-map", Fcurrent_local_map
, Scurrent_local_map
, 0, 0, 0,
1819 doc
: /* Return current buffer's local keymap, or nil if it has none.
1820 Normally the local keymap is set by the major mode with `use-local-map'. */)
1823 return BVAR (current_buffer
, keymap
);
1826 DEFUN ("current-global-map", Fcurrent_global_map
, Scurrent_global_map
, 0, 0, 0,
1827 doc
: /* Return the current global keymap. */)
1830 return current_global_map
;
1833 DEFUN ("current-minor-mode-maps", Fcurrent_minor_mode_maps
, Scurrent_minor_mode_maps
, 0, 0, 0,
1834 doc
: /* Return a list of keymaps for the minor modes of the current buffer. */)
1838 int nmaps
= current_minor_maps (0, &maps
);
1840 return Flist (nmaps
, maps
);
1843 /* Help functions for describing and documenting keymaps. */
1845 struct accessible_keymaps_data
{
1846 Lisp_Object maps
, tail
, thisseq
;
1847 /* Does the current sequence end in the meta-prefix-char? */
1852 accessible_keymaps_1 (Lisp_Object key
, Lisp_Object cmd
, Lisp_Object args
, void *data
)
1853 /* Use void * data to be compatible with map_keymap_function_t. */
1855 struct accessible_keymaps_data
*d
= data
; /* Cast! */
1856 Lisp_Object maps
= d
->maps
;
1857 Lisp_Object tail
= d
->tail
;
1858 Lisp_Object thisseq
= d
->thisseq
;
1859 bool is_metized
= d
->is_metized
&& INTEGERP (key
);
1862 cmd
= get_keymap (get_keyelt (cmd
, 0), 0, 0);
1866 /* Look for and break cycles. */
1867 while (!NILP (tem
= Frassq (cmd
, maps
)))
1869 Lisp_Object prefix
= XCAR (tem
);
1870 ptrdiff_t lim
= XINT (Flength (XCAR (tem
)));
1871 if (lim
<= XINT (Flength (thisseq
)))
1872 { /* This keymap was already seen with a smaller prefix. */
1874 while (i
< lim
&& EQ (Faref (prefix
, make_number (i
)),
1875 Faref (thisseq
, make_number (i
))))
1878 /* `prefix' is a prefix of `thisseq' => there's a cycle. */
1881 /* This occurrence of `cmd' in `maps' does not correspond to a cycle,
1882 but maybe `cmd' occurs again further down in `maps', so keep
1884 maps
= XCDR (Fmemq (tem
, maps
));
1887 /* If the last key in thisseq is meta-prefix-char,
1888 turn it into a meta-ized keystroke. We know
1889 that the event we're about to append is an
1890 ascii keystroke since we're processing a
1894 int meta_bit
= meta_modifier
;
1895 Lisp_Object last
= make_number (XINT (Flength (thisseq
)) - 1);
1896 tem
= Fcopy_sequence (thisseq
);
1898 Faset (tem
, last
, make_number (XINT (key
) | meta_bit
));
1900 /* This new sequence is the same length as
1901 thisseq, so stick it in the list right
1904 Fcons (Fcons (tem
, cmd
), XCDR (tail
)));
1908 tem
= append_key (thisseq
, key
);
1909 nconc2 (tail
, list1 (Fcons (tem
, cmd
)));
1913 /* This function cannot GC. */
1915 DEFUN ("accessible-keymaps", Faccessible_keymaps
, Saccessible_keymaps
,
1917 doc
: /* Find all keymaps accessible via prefix characters from KEYMAP.
1918 Returns a list of elements of the form (KEYS . MAP), where the sequence
1919 KEYS starting from KEYMAP gets you to MAP. These elements are ordered
1920 so that the KEYS increase in length. The first element is ([] . KEYMAP).
1921 An optional argument PREFIX, if non-nil, should be a key sequence;
1922 then the value includes only maps for prefixes that start with PREFIX. */)
1923 (Lisp_Object keymap
, Lisp_Object prefix
)
1925 Lisp_Object maps
, tail
;
1926 EMACS_INT prefixlen
= XFASTINT (Flength (prefix
));
1928 /* no need for gcpro because we don't autoload any keymaps. */
1932 /* If a prefix was specified, start with the keymap (if any) for
1933 that prefix, so we don't waste time considering other prefixes. */
1935 tem
= Flookup_key (keymap
, prefix
, Qt
);
1936 /* Flookup_key may give us nil, or a number,
1937 if the prefix is not defined in this particular map.
1938 It might even give us a list that isn't a keymap. */
1939 tem
= get_keymap (tem
, 0, 0);
1940 /* If the keymap is autoloaded `tem' is not a cons-cell, but we still
1941 want to return it. */
1944 /* Convert PREFIX to a vector now, so that later on
1945 we don't have to deal with the possibility of a string. */
1946 if (STRINGP (prefix
))
1951 copy
= Fmake_vector (make_number (SCHARS (prefix
)), Qnil
);
1952 for (i
= 0, i_byte
= 0; i
< SCHARS (prefix
);)
1956 FETCH_STRING_CHAR_ADVANCE (c
, prefix
, i
, i_byte
);
1957 if (SINGLE_BYTE_CHAR_P (c
) && (c
& 0200))
1958 c
^= 0200 | meta_modifier
;
1959 ASET (copy
, i_before
, make_number (c
));
1963 maps
= list1 (Fcons (prefix
, tem
));
1969 maps
= list1 (Fcons (zero_vector
, get_keymap (keymap
, 1, 0)));
1971 /* For each map in the list maps,
1972 look at any other maps it points to,
1973 and stick them at the end if they are not already in the list.
1975 This is a breadth-first traversal, where tail is the queue of
1976 nodes, and maps accumulates a list of all nodes visited. */
1978 for (tail
= maps
; CONSP (tail
); tail
= XCDR (tail
))
1980 struct accessible_keymaps_data data
;
1981 register Lisp_Object thismap
= Fcdr (XCAR (tail
));
1984 data
.thisseq
= Fcar (XCAR (tail
));
1987 last
= make_number (XINT (Flength (data
.thisseq
)) - 1);
1988 /* Does the current sequence end in the meta-prefix-char? */
1989 data
.is_metized
= (XINT (last
) >= 0
1990 /* Don't metize the last char of PREFIX. */
1991 && XINT (last
) >= prefixlen
1992 && EQ (Faref (data
.thisseq
, last
), meta_prefix_char
));
1994 /* Since we can't run lisp code, we can't scan autoloaded maps. */
1995 if (CONSP (thismap
))
1996 map_keymap (thismap
, accessible_keymaps_1
, Qnil
, &data
, 0);
2000 static Lisp_Object Qsingle_key_description
, Qkey_description
;
2002 /* This function cannot GC. */
2004 DEFUN ("key-description", Fkey_description
, Skey_description
, 1, 2, 0,
2005 doc
: /* Return a pretty description of key-sequence KEYS.
2006 Optional arg PREFIX is the sequence of keys leading up to KEYS.
2007 For example, [?\C-x ?l] is converted into the string \"C-x l\".
2009 For an approximate inverse of this, see `kbd'. */)
2010 (Lisp_Object keys
, Lisp_Object prefix
)
2016 EMACS_INT size
= XINT (Flength (keys
));
2018 Lisp_Object sep
= build_string (" ");
2025 size
+= XINT (Flength (prefix
));
2027 /* This has one extra element at the end that we don't pass to Fconcat. */
2028 if (min (PTRDIFF_MAX
, SIZE_MAX
) / word_size
/ 4 < size
)
2029 memory_full (SIZE_MAX
);
2030 SAFE_ALLOCA_LISP (args
, size
* 4);
2032 /* In effect, this computes
2033 (mapconcat 'single-key-description keys " ")
2034 but we shouldn't use mapconcat because it can do GC. */
2038 list
= prefix
, prefix
= Qnil
;
2039 else if (!NILP (keys
))
2040 list
= keys
, keys
= Qnil
;
2045 args
[len
] = Fsingle_key_description (meta_prefix_char
, Qnil
);
2046 result
= Fconcat (len
+ 1, args
);
2049 result
= empty_unibyte_string
;
2051 result
= Fconcat (len
- 1, args
);
2057 size
= SCHARS (list
);
2058 else if (VECTORP (list
))
2059 size
= ASIZE (list
);
2060 else if (CONSP (list
))
2061 size
= XINT (Flength (list
));
2063 wrong_type_argument (Qarrayp
, list
);
2072 FETCH_STRING_CHAR_ADVANCE (c
, list
, i
, i_byte
);
2073 if (SINGLE_BYTE_CHAR_P (c
) && (c
& 0200))
2074 c
^= 0200 | meta_modifier
;
2075 XSETFASTINT (key
, c
);
2077 else if (VECTORP (list
))
2079 key
= AREF (list
, i
); i
++;
2091 || EQ (key
, meta_prefix_char
)
2092 || (XINT (key
) & meta_modifier
))
2094 args
[len
++] = Fsingle_key_description (meta_prefix_char
, Qnil
);
2096 if (EQ (key
, meta_prefix_char
))
2100 XSETINT (key
, XINT (key
) | meta_modifier
);
2103 else if (EQ (key
, meta_prefix_char
))
2108 args
[len
++] = Fsingle_key_description (key
, Qnil
);
2116 push_key_description (EMACS_INT ch
, char *p
)
2121 /* Clear all the meaningless bits above the meta bit. */
2122 c
= ch
& (meta_modifier
| ~ - meta_modifier
);
2123 c2
= c
& ~(alt_modifier
| ctrl_modifier
| hyper_modifier
2124 | meta_modifier
| shift_modifier
| super_modifier
);
2126 if (! CHARACTERP (make_number (c2
)))
2128 /* KEY_DESCRIPTION_SIZE is large enough for this. */
2129 p
+= sprintf (p
, "[%d]", c
);
2133 tab_as_ci
= (c2
== '\t' && (c
& meta_modifier
));
2135 if (c
& alt_modifier
)
2141 if ((c
& ctrl_modifier
) != 0
2142 || (c2
< ' ' && c2
!= 27 && c2
!= '\t' && c2
!= Ctl ('M'))
2147 c
&= ~ctrl_modifier
;
2149 if (c
& hyper_modifier
)
2153 c
-= hyper_modifier
;
2155 if (c
& meta_modifier
)
2161 if (c
& shift_modifier
)
2165 c
-= shift_modifier
;
2167 if (c
& super_modifier
)
2171 c
-= super_modifier
;
2191 else if (c
== Ctl ('M'))
2199 /* `C-' already added above. */
2200 if (c
> 0 && c
<= Ctl ('Z'))
2222 /* Now we are sure that C is a valid character code. */
2223 p
+= CHAR_STRING (c
, (unsigned char *) p
);
2229 /* This function cannot GC. */
2231 DEFUN ("single-key-description", Fsingle_key_description
,
2232 Ssingle_key_description
, 1, 2, 0,
2233 doc
: /* Return a pretty description of command character KEY.
2234 Control characters turn into C-whatever, etc.
2235 Optional argument NO-ANGLES non-nil means don't put angle brackets
2236 around function keys and event symbols. */)
2237 (Lisp_Object key
, Lisp_Object no_angles
)
2241 if (CONSP (key
) && lucid_event_type_list_p (key
))
2242 key
= Fevent_convert_list (key
);
2244 if (CONSP (key
) && INTEGERP (XCAR (key
)) && INTEGERP (XCDR (key
)))
2245 /* An interval from a map-char-table. */
2246 return concat3 (Fsingle_key_description (XCAR (key
), no_angles
),
2247 build_local_string (".."),
2248 Fsingle_key_description (XCDR (key
), no_angles
));
2250 key
= EVENT_HEAD (key
);
2252 if (INTEGERP (key
)) /* Normal character. */
2254 char tem
[KEY_DESCRIPTION_SIZE
];
2255 char *p
= push_key_description (XINT (key
), tem
);
2257 return make_specified_string (tem
, -1, p
- tem
, 1);
2259 else if (SYMBOLP (key
)) /* Function key or event-symbol. */
2261 if (NILP (no_angles
))
2264 char *buffer
= SAFE_ALLOCA (sizeof "<>"
2265 + SBYTES (SYMBOL_NAME (key
)));
2266 esprintf (buffer
, "<%s>", SDATA (SYMBOL_NAME (key
)));
2267 result
= build_string (buffer
);
2272 return Fsymbol_name (key
);
2274 else if (STRINGP (key
)) /* Buffer names in the menubar. */
2275 return Fcopy_sequence (key
);
2277 error ("KEY must be an integer, cons, symbol, or string");
2281 push_text_char_description (register unsigned int c
, register char *p
)
2292 *p
++ = c
+ 64; /* 'A' - 1 */
2304 /* This function cannot GC. */
2306 DEFUN ("text-char-description", Ftext_char_description
, Stext_char_description
, 1, 1, 0,
2307 doc
: /* Return a pretty description of file-character CHARACTER.
2308 Control characters turn into "^char", etc. This differs from
2309 `single-key-description' which turns them into "C-char".
2310 Also, this function recognizes the 2**7 bit as the Meta character,
2311 whereas `single-key-description' uses the 2**27 bit for Meta.
2312 See Info node `(elisp)Describing Characters' for examples. */)
2313 (Lisp_Object character
)
2315 /* Currently MAX_MULTIBYTE_LENGTH is 4 (< 6). */
2319 CHECK_CHARACTER (character
);
2321 c
= XINT (character
);
2322 if (!ASCII_CHAR_P (c
))
2324 int len
= CHAR_STRING (c
, (unsigned char *) str
);
2326 return make_multibyte_string (str
, 1, len
);
2329 *push_text_char_description (c
& 0377, str
) = 0;
2331 return build_string (str
);
2334 static int where_is_preferred_modifier
;
2336 /* Return 0 if SEQ uses non-preferred modifiers or non-char events.
2337 Else, return 2 if SEQ uses the where_is_preferred_modifier,
2340 preferred_sequence_p (Lisp_Object seq
)
2343 EMACS_INT len
= XFASTINT (Flength (seq
));
2346 for (i
= 0; i
< len
; i
++)
2348 Lisp_Object ii
, elt
;
2350 XSETFASTINT (ii
, i
);
2351 elt
= Faref (seq
, ii
);
2353 if (!INTEGERP (elt
))
2357 int modifiers
= XINT (elt
) & (CHAR_MODIFIER_MASK
& ~CHAR_META
);
2358 if (modifiers
== where_is_preferred_modifier
)
2369 /* where-is - finding a command in a set of keymaps. */
2371 static void where_is_internal_1 (Lisp_Object key
, Lisp_Object binding
,
2372 Lisp_Object args
, void *data
);
2374 /* Like Flookup_key, but uses a list of keymaps SHADOW instead of a single map.
2375 Returns the first non-nil binding found in any of those maps.
2376 If REMAP is true, pass the result of the lookup through command
2377 remapping before returning it. */
2380 shadow_lookup (Lisp_Object shadow
, Lisp_Object key
, Lisp_Object flag
,
2383 Lisp_Object tail
, value
;
2385 for (tail
= shadow
; CONSP (tail
); tail
= XCDR (tail
))
2387 value
= Flookup_key (XCAR (tail
), key
, flag
);
2388 if (NATNUMP (value
))
2390 value
= Flookup_key (XCAR (tail
),
2391 Fsubstring (key
, make_number (0), value
), flag
);
2395 else if (!NILP (value
))
2397 Lisp_Object remapping
;
2398 if (remap
&& SYMBOLP (value
)
2399 && (remapping
= Fcommand_remapping (value
, Qnil
, shadow
),
2409 static Lisp_Object Vmouse_events
;
2411 struct where_is_internal_data
{
2412 Lisp_Object definition
, this, last
;
2413 bool last_is_meta
, noindirect
;
2414 Lisp_Object sequences
;
2417 /* This function can't GC, AFAIK. */
2418 /* Return the list of bindings found. This list is ordered "longest
2419 to shortest". It may include bindings that are actually shadowed
2420 by others, as well as duplicate bindings and remapping bindings.
2421 The list returned is potentially shared with where_is_cache, so
2422 be careful not to modify it via side-effects. */
2425 where_is_internal (Lisp_Object definition
, Lisp_Object keymaps
,
2426 bool noindirect
, bool nomenus
)
2428 Lisp_Object maps
= Qnil
;
2430 struct where_is_internal_data data
;
2432 /* Only important use of caching is for the menubar
2433 (i.e. where-is-internal called with (def nil t nil nil)). */
2434 if (nomenus
&& !noindirect
)
2436 /* Check heuristic-consistency of the cache. */
2437 if (NILP (Fequal (keymaps
, where_is_cache_keymaps
)))
2438 where_is_cache
= Qnil
;
2440 if (NILP (where_is_cache
))
2442 /* We need to create the cache. */
2443 Lisp_Object args
[2];
2444 where_is_cache
= Fmake_hash_table (0, args
);
2445 where_is_cache_keymaps
= Qt
;
2448 /* We can reuse the cache. */
2449 return Fgethash (definition
, where_is_cache
, Qnil
);
2452 /* Kill the cache so that where_is_internal_1 doesn't think
2453 we're filling it up. */
2454 where_is_cache
= Qnil
;
2457 while (CONSP (found
))
2461 Faccessible_keymaps (get_keymap (XCAR (found
), 1, 0), Qnil
));
2462 found
= XCDR (found
);
2465 data
.sequences
= Qnil
;
2466 for (; CONSP (maps
); maps
= XCDR (maps
))
2468 /* Key sequence to reach map, and the map that it reaches */
2469 register Lisp_Object
this, map
, tem
;
2471 /* In order to fold [META-PREFIX-CHAR CHAR] sequences into
2472 [M-CHAR] sequences, check if last character of the sequence
2473 is the meta-prefix char. */
2477 this = Fcar (XCAR (maps
));
2478 map
= Fcdr (XCAR (maps
));
2479 last
= make_number (XINT (Flength (this)) - 1);
2480 last_is_meta
= (XINT (last
) >= 0
2481 && EQ (Faref (this, last
), meta_prefix_char
));
2483 /* if (nomenus && !preferred_sequence_p (this)) */
2484 if (nomenus
&& XINT (last
) >= 0
2485 && SYMBOLP (tem
= Faref (this, make_number (0)))
2486 && !NILP (Fmemq (XCAR (parse_modifiers (tem
)), Vmouse_events
)))
2487 /* If no menu entries should be returned, skip over the
2488 keymaps bound to `menu-bar' and `tool-bar' and other
2489 non-ascii prefixes like `C-down-mouse-2'. */
2494 data
.definition
= definition
;
2495 data
.noindirect
= noindirect
;
2498 data
.last_is_meta
= last_is_meta
;
2501 map_keymap (map
, where_is_internal_1
, Qnil
, &data
, 0);
2504 if (nomenus
&& !noindirect
)
2505 { /* Remember for which keymaps this cache was built.
2506 We do it here (late) because we want to keep where_is_cache_keymaps
2507 set to t while the cache isn't fully filled. */
2508 where_is_cache_keymaps
= keymaps
;
2509 /* During cache-filling, data.sequences is not filled by
2510 where_is_internal_1. */
2511 return Fgethash (definition
, where_is_cache
, Qnil
);
2514 return data
.sequences
;
2517 /* This function can GC if Flookup_key autoloads any keymaps. */
2519 DEFUN ("where-is-internal", Fwhere_is_internal
, Swhere_is_internal
, 1, 5, 0,
2520 doc
: /* Return list of keys that invoke DEFINITION.
2521 If KEYMAP is a keymap, search only KEYMAP and the global keymap.
2522 If KEYMAP is nil, search all the currently active keymaps, except
2523 for `overriding-local-map' (which is ignored).
2524 If KEYMAP is a list of keymaps, search only those keymaps.
2526 If optional 3rd arg FIRSTONLY is non-nil, return the first key sequence found,
2527 rather than a list of all possible key sequences.
2528 If FIRSTONLY is the symbol `non-ascii', return the first binding found,
2529 no matter what it is.
2530 If FIRSTONLY has another non-nil value, prefer bindings
2531 that use the modifier key specified in `where-is-preferred-modifier'
2532 \(or their meta variants) and entirely reject menu bindings.
2534 If optional 4th arg NOINDIRECT is non-nil, don't extract the commands inside
2535 menu-items. This makes it possible to search for a menu-item itself.
2537 The optional 5th arg NO-REMAP alters how command remapping is handled:
2539 - If another command OTHER-COMMAND is remapped to DEFINITION, normally
2540 search for the bindings of OTHER-COMMAND and include them in the
2541 returned list. But if NO-REMAP is non-nil, include the vector
2542 [remap OTHER-COMMAND] in the returned list instead, without
2543 searching for those other bindings.
2545 - If DEFINITION is remapped to OTHER-COMMAND, normally return the
2546 bindings for OTHER-COMMAND. But if NO-REMAP is non-nil, return the
2547 bindings for DEFINITION instead, ignoring its remapping. */)
2548 (Lisp_Object definition
, Lisp_Object keymap
, Lisp_Object firstonly
, Lisp_Object noindirect
, Lisp_Object no_remap
)
2550 /* The keymaps in which to search. */
2551 Lisp_Object keymaps
;
2552 /* Potentially relevant bindings in "shortest to longest" order. */
2553 Lisp_Object sequences
= Qnil
;
2554 /* Actually relevant bindings. */
2555 Lisp_Object found
= Qnil
;
2556 /* 1 means ignore all menu bindings entirely. */
2557 bool nomenus
= !NILP (firstonly
) && !EQ (firstonly
, Qnon_ascii
);
2558 struct gcpro gcpro1
, gcpro2
, gcpro3
, gcpro4
, gcpro5
, gcpro6
;
2559 /* List of sequences found via remapping. Keep them in a separate
2560 variable, so as to push them later, since we prefer
2561 non-remapped binding. */
2562 Lisp_Object remapped_sequences
= Qnil
;
2563 /* Whether or not we're handling remapped sequences. This is needed
2564 because remapping is not done recursively by Fcommand_remapping: you
2565 can't remap a remapped command. */
2567 Lisp_Object tem
= Qnil
;
2569 /* Refresh the C version of the modifier preference. */
2570 where_is_preferred_modifier
2571 = parse_solitary_modifier (Vwhere_is_preferred_modifier
);
2573 /* Find the relevant keymaps. */
2574 if (CONSP (keymap
) && KEYMAPP (XCAR (keymap
)))
2576 else if (!NILP (keymap
))
2577 keymaps
= list2 (keymap
, current_global_map
);
2579 keymaps
= Fcurrent_active_maps (Qnil
, Qnil
);
2581 GCPRO6 (definition
, keymaps
, found
, sequences
, remapped_sequences
, tem
);
2583 tem
= Fcommand_remapping (definition
, Qnil
, keymaps
);
2584 /* If `definition' is remapped to tem', then OT1H no key will run
2585 that command (since they will run `tem' instead), so we should
2586 return nil; but OTOH all keys bound to `definition' (or to `tem')
2587 will run the same command.
2588 So for menu-shortcut purposes, we want to find all the keys bound (maybe
2589 via remapping) to `tem'. But for the purpose of finding the keys that
2590 run `definition', then we'd want to just return nil.
2591 We choose to make it work right for menu-shortcuts, since it's the most
2593 Known bugs: if you remap switch-to-buffer to toto, C-h f switch-to-buffer
2594 will tell you that switch-to-buffer is bound to C-x b even though C-x b
2595 will run toto instead. And if `toto' is itself remapped to forward-char,
2596 then C-h f toto will tell you that it's bound to C-f even though C-f does
2597 not run toto and it won't tell you that C-x b does run toto. */
2598 if (NILP (no_remap
) && !NILP (tem
))
2601 if (SYMBOLP (definition
)
2602 && !NILP (firstonly
)
2603 && !NILP (tem
= Fget (definition
, QCadvertised_binding
)))
2605 /* We have a list of advertised bindings. */
2607 if (EQ (shadow_lookup (keymaps
, XCAR (tem
), Qnil
, 0), definition
))
2608 RETURN_UNGCPRO (XCAR (tem
));
2611 if (EQ (shadow_lookup (keymaps
, tem
, Qnil
, 0), definition
))
2612 RETURN_UNGCPRO (tem
);
2615 sequences
= Freverse (where_is_internal (definition
, keymaps
,
2616 !NILP (noindirect
), nomenus
));
2618 while (CONSP (sequences
)
2619 /* If we're at the end of the `sequences' list and we haven't
2620 considered remapped sequences yet, copy them over and
2622 || (!remapped
&& (sequences
= remapped_sequences
,
2624 CONSP (sequences
))))
2626 Lisp_Object sequence
, function
;
2628 sequence
= XCAR (sequences
);
2629 sequences
= XCDR (sequences
);
2631 /* Verify that this key binding is not shadowed by another
2632 binding for the same key, before we say it exists.
2634 Mechanism: look for local definition of this key and if
2635 it is defined and does not match what we found then
2638 Either nil or number as value from Flookup_key
2640 if (NILP (Fequal (shadow_lookup (keymaps
, sequence
, Qnil
, remapped
),
2644 /* If the current sequence is a command remapping with
2645 format [remap COMMAND], find the key sequences
2646 which run COMMAND, and use those sequences instead. */
2647 if (NILP (no_remap
) && !remapped
2648 && VECTORP (sequence
) && ASIZE (sequence
) == 2
2649 && EQ (AREF (sequence
, 0), Qremap
)
2650 && (function
= AREF (sequence
, 1), SYMBOLP (function
)))
2652 Lisp_Object seqs
= where_is_internal (function
, keymaps
,
2653 !NILP (noindirect
), nomenus
);
2654 remapped_sequences
= nconc2 (Freverse (seqs
), remapped_sequences
);
2658 /* Don't annoy user with strings from a menu such as the
2659 entries from the "Edit => Paste from Kill Menu".
2660 Change them all to "(any string)", so that there
2661 seems to be only one menu item to report. */
2662 if (! NILP (sequence
))
2665 tem1
= Faref (sequence
, make_number (ASIZE (sequence
) - 1));
2667 Faset (sequence
, make_number (ASIZE (sequence
) - 1),
2668 build_string ("(any string)"));
2671 /* It is a true unshadowed match. Record it, unless it's already
2672 been seen (as could happen when inheriting keymaps). */
2673 if (NILP (Fmember (sequence
, found
)))
2674 found
= Fcons (sequence
, found
);
2676 /* If firstonly is Qnon_ascii, then we can return the first
2677 binding we find. If firstonly is not Qnon_ascii but not
2678 nil, then we should return the first ascii-only binding
2680 if (EQ (firstonly
, Qnon_ascii
))
2681 RETURN_UNGCPRO (sequence
);
2682 else if (!NILP (firstonly
)
2683 && 2 == preferred_sequence_p (sequence
))
2684 RETURN_UNGCPRO (sequence
);
2689 found
= Fnreverse (found
);
2691 /* firstonly may have been t, but we may have gone all the way through
2692 the keymaps without finding an all-ASCII key sequence. So just
2693 return the best we could find. */
2694 if (NILP (firstonly
))
2696 else if (where_is_preferred_modifier
== 0)
2697 return Fcar (found
);
2699 { /* Maybe we did not find a preferred_modifier binding, but we did find
2700 some ASCII binding. */
2701 Lisp_Object bindings
= found
;
2702 while (CONSP (bindings
))
2703 if (preferred_sequence_p (XCAR (bindings
)))
2704 return XCAR (bindings
);
2706 bindings
= XCDR (bindings
);
2707 return Fcar (found
);
2711 /* This function can GC because get_keyelt can. */
2714 where_is_internal_1 (Lisp_Object key
, Lisp_Object binding
, Lisp_Object args
, void *data
)
2716 struct where_is_internal_data
*d
= data
; /* Cast! */
2717 Lisp_Object definition
= d
->definition
;
2718 bool noindirect
= d
->noindirect
;
2719 Lisp_Object
this = d
->this;
2720 Lisp_Object last
= d
->last
;
2721 bool last_is_meta
= d
->last_is_meta
;
2722 Lisp_Object sequence
;
2724 /* Search through indirections unless that's not wanted. */
2726 binding
= get_keyelt (binding
, 0);
2728 /* End this iteration if this element does not match
2731 if (!(!NILP (where_is_cache
) /* everything "matches" during cache-fill. */
2732 || EQ (binding
, definition
)
2733 || (CONSP (definition
) && !NILP (Fequal (binding
, definition
)))))
2734 /* Doesn't match. */
2737 /* We have found a match. Construct the key sequence where we found it. */
2738 if (INTEGERP (key
) && last_is_meta
)
2740 sequence
= Fcopy_sequence (this);
2741 Faset (sequence
, last
, make_number (XINT (key
) | meta_modifier
));
2746 key
= Fcons (XCAR (key
), XCDR (key
));
2747 sequence
= append_key (this, key
);
2750 if (!NILP (where_is_cache
))
2752 Lisp_Object sequences
= Fgethash (binding
, where_is_cache
, Qnil
);
2753 Fputhash (binding
, Fcons (sequence
, sequences
), where_is_cache
);
2756 d
->sequences
= Fcons (sequence
, d
->sequences
);
2759 /* describe-bindings - summarizing all the bindings in a set of keymaps. */
2761 DEFUN ("describe-buffer-bindings", Fdescribe_buffer_bindings
, Sdescribe_buffer_bindings
, 1, 3, 0,
2762 doc
: /* Insert the list of all defined keys and their definitions.
2763 The list is inserted in the current buffer, while the bindings are
2764 looked up in BUFFER.
2765 The optional argument PREFIX, if non-nil, should be a key sequence;
2766 then we display only bindings that start with that prefix.
2767 The optional argument MENUS, if non-nil, says to mention menu bindings.
2768 \(Ordinarily these are omitted from the output.) */)
2769 (Lisp_Object buffer
, Lisp_Object prefix
, Lisp_Object menus
)
2771 Lisp_Object outbuf
, shadow
;
2772 bool nomenu
= NILP (menus
);
2774 struct gcpro gcpro1
;
2776 const char *alternate_heading
2778 Keyboard translations:\n\n\
2779 You type Translation\n\
2780 -------- -----------\n";
2782 CHECK_BUFFER (buffer
);
2787 outbuf
= Fcurrent_buffer ();
2789 /* Report on alternates for keys. */
2790 if (STRINGP (KVAR (current_kboard
, Vkeyboard_translate_table
)) && !NILP (prefix
))
2793 const unsigned char *translate
= SDATA (KVAR (current_kboard
, Vkeyboard_translate_table
));
2794 int translate_len
= SCHARS (KVAR (current_kboard
, Vkeyboard_translate_table
));
2796 for (c
= 0; c
< translate_len
; c
++)
2797 if (translate
[c
] != c
)
2799 char buf
[KEY_DESCRIPTION_SIZE
];
2802 if (alternate_heading
)
2804 insert_string (alternate_heading
);
2805 alternate_heading
= 0;
2808 bufend
= push_key_description (translate
[c
], buf
);
2809 insert (buf
, bufend
- buf
);
2810 Findent_to (make_number (16), make_number (1));
2811 bufend
= push_key_description (c
, buf
);
2812 insert (buf
, bufend
- buf
);
2816 /* Insert calls signal_after_change which may GC. */
2817 translate
= SDATA (KVAR (current_kboard
, Vkeyboard_translate_table
));
2823 if (!NILP (Vkey_translation_map
))
2824 describe_map_tree (Vkey_translation_map
, 0, Qnil
, prefix
,
2825 "Key translations", nomenu
, 1, 0, 0);
2828 /* Print the (major mode) local map. */
2830 if (!NILP (KVAR (current_kboard
, Voverriding_terminal_local_map
)))
2831 start1
= KVAR (current_kboard
, Voverriding_terminal_local_map
);
2835 describe_map_tree (start1
, 1, shadow
, prefix
,
2836 "\f\nOverriding Bindings", nomenu
, 0, 0, 0);
2837 shadow
= Fcons (start1
, shadow
);
2840 else if (!NILP (Voverriding_local_map
))
2841 start1
= Voverriding_local_map
;
2845 describe_map_tree (start1
, 1, shadow
, prefix
,
2846 "\f\nOverriding Bindings", nomenu
, 0, 0, 0);
2847 shadow
= Fcons (start1
, shadow
);
2851 /* Print the minor mode and major mode keymaps. */
2853 Lisp_Object
*modes
, *maps
;
2855 /* Temporarily switch to `buffer', so that we can get that buffer's
2856 minor modes correctly. */
2857 Fset_buffer (buffer
);
2859 nmaps
= current_minor_maps (&modes
, &maps
);
2860 Fset_buffer (outbuf
);
2862 start1
= get_local_map (BUF_PT (XBUFFER (buffer
)),
2863 XBUFFER (buffer
), Qkeymap
);
2866 describe_map_tree (start1
, 1, shadow
, prefix
,
2867 "\f\n`keymap' Property Bindings", nomenu
,
2869 shadow
= Fcons (start1
, shadow
);
2872 /* Print the minor mode maps. */
2873 for (i
= 0; i
< nmaps
; i
++)
2875 /* The title for a minor mode keymap
2876 is constructed at run time.
2877 We let describe_map_tree do the actual insertion
2878 because it takes care of other features when doing so. */
2881 if (!SYMBOLP (modes
[i
]))
2885 p
= title
= SAFE_ALLOCA (42 + SBYTES (SYMBOL_NAME (modes
[i
])));
2889 memcpy (p
, SDATA (SYMBOL_NAME (modes
[i
])),
2890 SBYTES (SYMBOL_NAME (modes
[i
])));
2891 p
+= SBYTES (SYMBOL_NAME (modes
[i
]));
2893 memcpy (p
, " Minor Mode Bindings", strlen (" Minor Mode Bindings"));
2894 p
+= strlen (" Minor Mode Bindings");
2897 describe_map_tree (maps
[i
], 1, shadow
, prefix
,
2898 title
, nomenu
, 0, 0, 0);
2899 shadow
= Fcons (maps
[i
], shadow
);
2903 start1
= get_local_map (BUF_PT (XBUFFER (buffer
)),
2904 XBUFFER (buffer
), Qlocal_map
);
2907 if (EQ (start1
, BVAR (XBUFFER (buffer
), keymap
)))
2908 describe_map_tree (start1
, 1, shadow
, prefix
,
2909 "\f\nMajor Mode Bindings", nomenu
, 0, 0, 0);
2911 describe_map_tree (start1
, 1, shadow
, prefix
,
2912 "\f\n`local-map' Property Bindings",
2915 shadow
= Fcons (start1
, shadow
);
2919 describe_map_tree (current_global_map
, 1, shadow
, prefix
,
2920 "\f\nGlobal Bindings", nomenu
, 0, 1, 0);
2922 /* Print the function-key-map translations under this prefix. */
2923 if (!NILP (KVAR (current_kboard
, Vlocal_function_key_map
)))
2924 describe_map_tree (KVAR (current_kboard
, Vlocal_function_key_map
), 0, Qnil
, prefix
,
2925 "\f\nFunction key map translations", nomenu
, 1, 0, 0);
2927 /* Print the input-decode-map translations under this prefix. */
2928 if (!NILP (KVAR (current_kboard
, Vinput_decode_map
)))
2929 describe_map_tree (KVAR (current_kboard
, Vinput_decode_map
), 0, Qnil
, prefix
,
2930 "\f\nInput decoding map translations", nomenu
, 1, 0, 0);
2936 /* Insert a description of the key bindings in STARTMAP,
2937 followed by those of all maps reachable through STARTMAP.
2938 If PARTIAL, omit certain "uninteresting" commands
2939 (such as `undefined').
2940 If SHADOW is non-nil, it is a list of maps;
2941 don't mention keys which would be shadowed by any of them.
2942 PREFIX, if non-nil, says mention only keys that start with PREFIX.
2943 TITLE, if not 0, is a string to insert at the beginning.
2944 TITLE should not end with a colon or a newline; we supply that.
2945 If NOMENU, then omit menu-bar commands.
2947 If TRANSL, the definitions are actually key translations
2948 so print strings and vectors differently.
2950 If ALWAYS_TITLE, print the title even if there are no maps
2953 If MENTION_SHADOW, then when something is shadowed by SHADOW,
2954 don't omit it; instead, mention it but say it is shadowed.
2956 Any inserted text ends in two newlines (used by `help-make-xrefs'). */
2959 describe_map_tree (Lisp_Object startmap
, bool partial
, Lisp_Object shadow
,
2960 Lisp_Object prefix
, const char *title
, bool nomenu
,
2961 bool transl
, bool always_title
, bool mention_shadow
)
2963 Lisp_Object maps
, orig_maps
, seen
, sub_shadows
;
2964 struct gcpro gcpro1
, gcpro2
, gcpro3
;
2966 const char *key_heading
2971 orig_maps
= maps
= Faccessible_keymaps (startmap
, prefix
);
2974 GCPRO3 (maps
, seen
, sub_shadows
);
2980 /* Delete from MAPS each element that is for the menu bar. */
2981 for (list
= maps
; CONSP (list
); list
= XCDR (list
))
2983 Lisp_Object elt
, elt_prefix
, tem
;
2986 elt_prefix
= Fcar (elt
);
2987 if (ASIZE (elt_prefix
) >= 1)
2989 tem
= Faref (elt_prefix
, make_number (0));
2990 if (EQ (tem
, Qmenu_bar
))
2991 maps
= Fdelq (elt
, maps
);
2996 if (!NILP (maps
) || always_title
)
3000 insert_string (title
);
3003 insert_string (" Starting With ");
3004 insert1 (Fkey_description (prefix
, Qnil
));
3006 insert_string (":\n");
3008 insert_string (key_heading
);
3012 for (; CONSP (maps
); maps
= XCDR (maps
))
3014 register Lisp_Object elt
, elt_prefix
, tail
;
3017 elt_prefix
= Fcar (elt
);
3021 for (tail
= shadow
; CONSP (tail
); tail
= XCDR (tail
))
3025 shmap
= XCAR (tail
);
3027 /* If the sequence by which we reach this keymap is zero-length,
3028 then the shadow map for this keymap is just SHADOW. */
3029 if ((STRINGP (elt_prefix
) && SCHARS (elt_prefix
) == 0)
3030 || (VECTORP (elt_prefix
) && ASIZE (elt_prefix
) == 0))
3032 /* If the sequence by which we reach this keymap actually has
3033 some elements, then the sequence's definition in SHADOW is
3034 what we should use. */
3037 shmap
= Flookup_key (shmap
, Fcar (elt
), Qt
);
3038 if (INTEGERP (shmap
))
3042 /* If shmap is not nil and not a keymap,
3043 it completely shadows this map, so don't
3044 describe this map at all. */
3045 if (!NILP (shmap
) && !KEYMAPP (shmap
))
3049 sub_shadows
= Fcons (shmap
, sub_shadows
);
3052 /* Maps we have already listed in this loop shadow this map. */
3053 for (tail
= orig_maps
; !EQ (tail
, maps
); tail
= XCDR (tail
))
3056 tem
= Fequal (Fcar (XCAR (tail
)), elt_prefix
);
3058 sub_shadows
= Fcons (XCDR (XCAR (tail
)), sub_shadows
);
3061 describe_map (Fcdr (elt
), elt_prefix
,
3062 transl
? describe_translation
: describe_command
,
3063 partial
, sub_shadows
, &seen
, nomenu
, mention_shadow
);
3069 insert_string ("\n");
3074 static int previous_description_column
;
3077 describe_command (Lisp_Object definition
, Lisp_Object args
)
3079 register Lisp_Object tem1
;
3080 ptrdiff_t column
= current_column ();
3081 int description_column
;
3083 /* If column 16 is no good, go to col 32;
3084 but don't push beyond that--go to next line instead. */
3088 description_column
= 32;
3090 else if (column
> 14 || (column
> 10 && previous_description_column
== 32))
3091 description_column
= 32;
3093 description_column
= 16;
3095 Findent_to (make_number (description_column
), make_number (1));
3096 previous_description_column
= description_column
;
3098 if (SYMBOLP (definition
))
3100 tem1
= SYMBOL_NAME (definition
);
3102 insert_string ("\n");
3104 else if (STRINGP (definition
) || VECTORP (definition
))
3105 insert_string ("Keyboard Macro\n");
3106 else if (KEYMAPP (definition
))
3107 insert_string ("Prefix Command\n");
3109 insert_string ("??\n");
3113 describe_translation (Lisp_Object definition
, Lisp_Object args
)
3115 register Lisp_Object tem1
;
3117 Findent_to (make_number (16), make_number (1));
3119 if (SYMBOLP (definition
))
3121 tem1
= SYMBOL_NAME (definition
);
3123 insert_string ("\n");
3125 else if (STRINGP (definition
) || VECTORP (definition
))
3127 insert1 (Fkey_description (definition
, Qnil
));
3128 insert_string ("\n");
3130 else if (KEYMAPP (definition
))
3131 insert_string ("Prefix Command\n");
3133 insert_string ("??\n");
3136 /* describe_map puts all the usable elements of a sparse keymap
3137 into an array of `struct describe_map_elt',
3138 then sorts them by the events. */
3140 struct describe_map_elt
3143 Lisp_Object definition
;
3147 /* qsort comparison function for sorting `struct describe_map_elt' by
3151 describe_map_compare (const void *aa
, const void *bb
)
3153 const struct describe_map_elt
*a
= aa
, *b
= bb
;
3154 if (INTEGERP (a
->event
) && INTEGERP (b
->event
))
3155 return ((XINT (a
->event
) > XINT (b
->event
))
3156 - (XINT (a
->event
) < XINT (b
->event
)));
3157 if (!INTEGERP (a
->event
) && INTEGERP (b
->event
))
3159 if (INTEGERP (a
->event
) && !INTEGERP (b
->event
))
3161 if (SYMBOLP (a
->event
) && SYMBOLP (b
->event
))
3162 return (!NILP (Fstring_lessp (a
->event
, b
->event
)) ? -1
3163 : !NILP (Fstring_lessp (b
->event
, a
->event
)) ? 1
3168 /* Describe the contents of map MAP, assuming that this map itself is
3169 reached by the sequence of prefix keys PREFIX (a string or vector).
3170 PARTIAL, SHADOW, NOMENU are as in `describe_map_tree' above. */
3173 describe_map (Lisp_Object map
, Lisp_Object prefix
,
3174 void (*elt_describer
) (Lisp_Object
, Lisp_Object
),
3175 bool partial
, Lisp_Object shadow
,
3176 Lisp_Object
*seen
, bool nomenu
, bool mention_shadow
)
3178 Lisp_Object tail
, definition
, event
;
3180 Lisp_Object suppress
;
3183 struct gcpro gcpro1
, gcpro2
, gcpro3
;
3185 /* These accumulate the values from sparse keymap bindings,
3186 so we can sort them and handle them in order. */
3187 ptrdiff_t length_needed
= 0;
3188 struct describe_map_elt
*vect
;
3189 ptrdiff_t slots_used
= 0;
3195 suppress
= intern ("suppress-keymap");
3197 /* This vector gets used to present single keys to Flookup_key. Since
3198 that is done once per keymap element, we don't want to cons up a
3199 fresh vector every time. */
3200 kludge
= Fmake_vector (make_number (1), Qnil
);
3203 GCPRO3 (prefix
, definition
, kludge
);
3205 map
= call1 (Qkeymap_canonicalize
, map
);
3207 for (tail
= map
; CONSP (tail
); tail
= XCDR (tail
))
3211 SAFE_NALLOCA (vect
, 1, length_needed
);
3213 for (tail
= map
; CONSP (tail
); tail
= XCDR (tail
))
3217 if (VECTORP (XCAR (tail
))
3218 || CHAR_TABLE_P (XCAR (tail
)))
3219 describe_vector (XCAR (tail
),
3220 prefix
, Qnil
, elt_describer
, partial
, shadow
, map
,
3222 else if (CONSP (XCAR (tail
)))
3224 bool this_shadowed
= 0;
3226 event
= XCAR (XCAR (tail
));
3228 /* Ignore bindings whose "prefix" are not really valid events.
3229 (We get these in the frames and buffers menu.) */
3230 if (!(SYMBOLP (event
) || INTEGERP (event
)))
3233 if (nomenu
&& EQ (event
, Qmenu_bar
))
3236 definition
= get_keyelt (XCDR (XCAR (tail
)), 0);
3238 /* Don't show undefined commands or suppressed commands. */
3239 if (NILP (definition
)) continue;
3240 if (SYMBOLP (definition
) && partial
)
3242 tem
= Fget (definition
, suppress
);
3247 /* Don't show a command that isn't really visible
3248 because a local definition of the same key shadows it. */
3250 ASET (kludge
, 0, event
);
3253 tem
= shadow_lookup (shadow
, kludge
, Qt
, 0);
3256 /* If both bindings are keymaps, this key is a prefix key,
3257 so don't say it is shadowed. */
3258 if (KEYMAPP (definition
) && KEYMAPP (tem
))
3260 /* Avoid generating duplicate entries if the
3261 shadowed binding has the same definition. */
3262 else if (mention_shadow
&& !EQ (tem
, definition
))
3269 tem
= Flookup_key (map
, kludge
, Qt
);
3270 if (!EQ (tem
, definition
)) continue;
3272 vect
[slots_used
].event
= event
;
3273 vect
[slots_used
].definition
= definition
;
3274 vect
[slots_used
].shadowed
= this_shadowed
;
3277 else if (EQ (XCAR (tail
), Qkeymap
))
3279 /* The same keymap might be in the structure twice, if we're
3280 using an inherited keymap. So skip anything we've already
3282 tem
= Fassq (tail
, *seen
);
3283 if (CONSP (tem
) && !NILP (Fequal (XCAR (tem
), prefix
)))
3285 *seen
= Fcons (Fcons (tail
, prefix
), *seen
);
3289 /* If we found some sparse map events, sort them. */
3291 qsort (vect
, slots_used
, sizeof (struct describe_map_elt
),
3292 describe_map_compare
);
3294 /* Now output them in sorted order. */
3296 for (i
= 0; i
< slots_used
; i
++)
3298 Lisp_Object start
, end
;
3302 previous_description_column
= 0;
3307 ASET (kludge
, 0, vect
[i
].event
);
3308 start
= vect
[i
].event
;
3311 definition
= vect
[i
].definition
;
3313 /* Find consecutive chars that are identically defined. */
3314 if (INTEGERP (vect
[i
].event
))
3316 while (i
+ 1 < slots_used
3317 && EQ (vect
[i
+1].event
, make_number (XINT (vect
[i
].event
) + 1))
3318 && !NILP (Fequal (vect
[i
+ 1].definition
, definition
))
3319 && vect
[i
].shadowed
== vect
[i
+ 1].shadowed
)
3321 end
= vect
[i
].event
;
3324 /* Now START .. END is the range to describe next. */
3326 /* Insert the string to describe the event START. */
3327 insert1 (Fkey_description (kludge
, prefix
));
3329 if (!EQ (start
, end
))
3333 ASET (kludge
, 0, end
);
3334 /* Insert the string to describe the character END. */
3335 insert1 (Fkey_description (kludge
, prefix
));
3338 /* Print a description of the definition of this character.
3339 elt_describer will take care of spacing out far enough
3340 for alignment purposes. */
3341 (*elt_describer
) (vect
[i
].definition
, Qnil
);
3343 if (vect
[i
].shadowed
)
3345 ptrdiff_t pt
= max (PT
- 1, BEG
);
3348 insert_string ("\n (that binding is currently shadowed by another mode)");
3349 pt
= min (PT
+ 1, Z
);
3359 describe_vector_princ (Lisp_Object elt
, Lisp_Object fun
)
3361 Findent_to (make_number (16), make_number (1));
3366 DEFUN ("describe-vector", Fdescribe_vector
, Sdescribe_vector
, 1, 2, 0,
3367 doc
: /* Insert a description of contents of VECTOR.
3368 This is text showing the elements of vector matched against indices.
3369 DESCRIBER is the output function used; nil means use `princ'. */)
3370 (Lisp_Object vector
, Lisp_Object describer
)
3372 ptrdiff_t count
= SPECPDL_INDEX ();
3373 if (NILP (describer
))
3374 describer
= intern ("princ");
3375 specbind (Qstandard_output
, Fcurrent_buffer ());
3376 CHECK_VECTOR_OR_CHAR_TABLE (vector
);
3377 describe_vector (vector
, Qnil
, describer
, describe_vector_princ
, 0,
3380 return unbind_to (count
, Qnil
);
3383 /* Insert in the current buffer a description of the contents of VECTOR.
3384 We call ELT_DESCRIBER to insert the description of one value found
3387 ELT_PREFIX describes what "comes before" the keys or indices defined
3388 by this vector. This is a human-readable string whose size
3389 is not necessarily related to the situation.
3391 If the vector is in a keymap, ELT_PREFIX is a prefix key which
3392 leads to this keymap.
3394 If the vector is a chartable, ELT_PREFIX is the vector
3395 of bytes that lead to the character set or portion of a character
3396 set described by this chartable.
3398 If PARTIAL, it means do not mention suppressed commands
3399 (that assumes the vector is in a keymap).
3401 SHADOW is a list of keymaps that shadow this map.
3402 If it is non-nil, then we look up the key in those maps
3403 and we don't mention it now if it is defined by any of them.
3405 ENTIRE_MAP is the keymap in which this vector appears.
3406 If the definition in effect in the whole map does not match
3407 the one in this vector, we ignore this one.
3409 ARGS is simply passed as the second argument to ELT_DESCRIBER.
3411 KEYMAP_P is 1 if vector is known to be a keymap, so map ESC to M-.
3413 ARGS is simply passed as the second argument to ELT_DESCRIBER. */
3416 describe_vector (Lisp_Object vector
, Lisp_Object prefix
, Lisp_Object args
,
3417 void (*elt_describer
) (Lisp_Object
, Lisp_Object
),
3418 bool partial
, Lisp_Object shadow
, Lisp_Object entire_map
,
3419 bool keymap_p
, bool mention_shadow
)
3422 Lisp_Object definition
;
3424 Lisp_Object elt_prefix
= Qnil
;
3426 Lisp_Object suppress
;
3429 struct gcpro gcpro1
, gcpro2
, gcpro3
, gcpro4
;
3430 /* Range of elements to be handled. */
3432 Lisp_Object character
;
3441 /* Call Fkey_description first, to avoid GC bug for the other string. */
3442 if (!NILP (prefix
) && XFASTINT (Flength (prefix
)) > 0)
3445 tem
= Fkey_description (prefix
, Qnil
);
3446 elt_prefix
= concat2 (tem
, build_local_string (" "));
3451 /* This vector gets used to present single keys to Flookup_key. Since
3452 that is done once per vector element, we don't want to cons up a
3453 fresh vector every time. */
3454 kludge
= Fmake_vector (make_number (1), Qnil
);
3455 GCPRO4 (elt_prefix
, prefix
, definition
, kludge
);
3458 suppress
= intern ("suppress-keymap");
3461 if (CHAR_TABLE_P (vector
))
3462 stop
= MAX_5_BYTE_CHAR
+ 1, to
= MAX_CHAR
+ 1;
3464 stop
= to
= ASIZE (vector
);
3466 for (i
= from
; ; i
++)
3468 bool this_shadowed
= 0;
3469 int range_beg
, range_end
;
3483 if (CHAR_TABLE_P (vector
))
3487 val
= char_table_ref_and_range (vector
, range_beg
, &range_beg
, &i
);
3490 val
= AREF (vector
, i
);
3491 definition
= get_keyelt (val
, 0);
3493 if (NILP (definition
)) continue;
3495 /* Don't mention suppressed commands. */
3496 if (SYMBOLP (definition
) && partial
)
3500 tem
= Fget (definition
, suppress
);
3502 if (!NILP (tem
)) continue;
3505 character
= make_number (starting_i
);
3506 ASET (kludge
, 0, character
);
3508 /* If this binding is shadowed by some other map, ignore it. */
3513 tem
= shadow_lookup (shadow
, kludge
, Qt
, 0);
3524 /* Ignore this definition if it is shadowed by an earlier
3525 one in the same keymap. */
3526 if (!NILP (entire_map
))
3530 tem
= Flookup_key (entire_map
, kludge
, Qt
);
3532 if (!EQ (tem
, definition
))
3542 /* Output the prefix that applies to every entry in this map. */
3543 if (!NILP (elt_prefix
))
3544 insert1 (elt_prefix
);
3546 insert1 (Fkey_description (kludge
, prefix
));
3548 /* Find all consecutive characters or rows that have the same
3549 definition. But, VECTOR is a char-table, we had better put a
3550 boundary between normal characters (-#x3FFF7F) and 8-bit
3551 characters (#x3FFF80-). */
3552 if (CHAR_TABLE_P (vector
))
3555 && (range_beg
= i
+ 1, range_end
= stop
- 1,
3556 val
= char_table_ref_and_range (vector
, range_beg
,
3557 &range_beg
, &range_end
),
3558 tem2
= get_keyelt (val
, 0),
3560 && !NILP (Fequal (tem2
, definition
)))
3565 && (tem2
= get_keyelt (AREF (vector
, i
+ 1), 0),
3567 && !NILP (Fequal (tem2
, definition
)))
3570 /* If we have a range of more than one character,
3571 print where the range reaches to. */
3573 if (i
!= starting_i
)
3577 ASET (kludge
, 0, make_number (i
));
3579 if (!NILP (elt_prefix
))
3580 insert1 (elt_prefix
);
3582 insert1 (Fkey_description (kludge
, prefix
));
3585 /* Print a description of the definition of this character.
3586 elt_describer will take care of spacing out far enough
3587 for alignment purposes. */
3588 (*elt_describer
) (definition
, args
);
3593 insert_string (" (binding currently shadowed)");
3598 if (CHAR_TABLE_P (vector
) && ! NILP (XCHAR_TABLE (vector
)->defalt
))
3600 if (!NILP (elt_prefix
))
3601 insert1 (elt_prefix
);
3602 insert ("default", 7);
3603 (*elt_describer
) (XCHAR_TABLE (vector
)->defalt
, args
);
3609 /* Apropos - finding all symbols whose names match a regexp. */
3610 static Lisp_Object apropos_predicate
;
3611 static Lisp_Object apropos_accumulate
;
3614 apropos_accum (Lisp_Object symbol
, Lisp_Object string
)
3616 register Lisp_Object tem
;
3618 tem
= Fstring_match (string
, Fsymbol_name (symbol
), Qnil
);
3619 if (!NILP (tem
) && !NILP (apropos_predicate
))
3620 tem
= call1 (apropos_predicate
, symbol
);
3622 apropos_accumulate
= Fcons (symbol
, apropos_accumulate
);
3625 DEFUN ("apropos-internal", Fapropos_internal
, Sapropos_internal
, 1, 2, 0,
3626 doc
: /* Show all symbols whose names contain match for REGEXP.
3627 If optional 2nd arg PREDICATE is non-nil, (funcall PREDICATE SYMBOL) is done
3628 for each symbol and a symbol is mentioned only if that returns non-nil.
3629 Return list of symbols found. */)
3630 (Lisp_Object regexp
, Lisp_Object predicate
)
3633 CHECK_STRING (regexp
);
3634 apropos_predicate
= predicate
;
3635 apropos_accumulate
= Qnil
;
3636 map_obarray (Vobarray
, apropos_accum
, regexp
);
3637 tem
= Fsort (apropos_accumulate
, Qstring_lessp
);
3638 apropos_accumulate
= Qnil
;
3639 apropos_predicate
= Qnil
;
3644 syms_of_keymap (void)
3646 DEFSYM (Qkeymap
, "keymap");
3647 staticpro (&apropos_predicate
);
3648 staticpro (&apropos_accumulate
);
3649 apropos_predicate
= Qnil
;
3650 apropos_accumulate
= Qnil
;
3652 DEFSYM (Qkeymap_canonicalize
, "keymap-canonicalize");
3654 /* Now we are ready to set up this property, so we can
3655 create char tables. */
3656 Fput (Qkeymap
, Qchar_table_extra_slots
, make_number (0));
3658 /* Initialize the keymaps standardly used.
3659 Each one is the value of a Lisp variable, and is also
3660 pointed to by a C variable */
3662 global_map
= Fmake_keymap (Qnil
);
3663 Fset (intern_c_string ("global-map"), global_map
);
3665 current_global_map
= global_map
;
3666 staticpro (&global_map
);
3667 staticpro (¤t_global_map
);
3669 meta_map
= Fmake_keymap (Qnil
);
3670 Fset (intern_c_string ("esc-map"), meta_map
);
3671 Ffset (intern_c_string ("ESC-prefix"), meta_map
);
3673 control_x_map
= Fmake_keymap (Qnil
);
3674 Fset (intern_c_string ("ctl-x-map"), control_x_map
);
3675 Ffset (intern_c_string ("Control-X-prefix"), control_x_map
);
3677 exclude_keys
= listn (CONSTYPE_PURE
, 5,
3678 pure_cons (build_pure_c_string ("DEL"), build_pure_c_string ("\\d")),
3679 pure_cons (build_pure_c_string ("TAB"), build_pure_c_string ("\\t")),
3680 pure_cons (build_pure_c_string ("RET"), build_pure_c_string ("\\r")),
3681 pure_cons (build_pure_c_string ("ESC"), build_pure_c_string ("\\e")),
3682 pure_cons (build_pure_c_string ("SPC"), build_pure_c_string (" ")));
3683 staticpro (&exclude_keys
);
3685 DEFVAR_LISP ("define-key-rebound-commands", Vdefine_key_rebound_commands
,
3686 doc
: /* List of commands given new key bindings recently.
3687 This is used for internal purposes during Emacs startup;
3688 don't alter it yourself. */);
3689 Vdefine_key_rebound_commands
= Qt
;
3691 DEFVAR_LISP ("minibuffer-local-map", Vminibuffer_local_map
,
3692 doc
: /* Default keymap to use when reading from the minibuffer. */);
3693 Vminibuffer_local_map
= Fmake_sparse_keymap (Qnil
);
3695 DEFVAR_LISP ("minibuffer-local-ns-map", Vminibuffer_local_ns_map
,
3696 doc
: /* Local keymap for the minibuffer when spaces are not allowed. */);
3697 Vminibuffer_local_ns_map
= Fmake_sparse_keymap (Qnil
);
3698 Fset_keymap_parent (Vminibuffer_local_ns_map
, Vminibuffer_local_map
);
3701 DEFVAR_LISP ("minor-mode-map-alist", Vminor_mode_map_alist
,
3702 doc
: /* Alist of keymaps to use for minor modes.
3703 Each element looks like (VARIABLE . KEYMAP); KEYMAP is used to read
3704 key sequences and look up bindings if VARIABLE's value is non-nil.
3705 If two active keymaps bind the same key, the keymap appearing earlier
3706 in the list takes precedence. */);
3707 Vminor_mode_map_alist
= Qnil
;
3709 DEFVAR_LISP ("minor-mode-overriding-map-alist", Vminor_mode_overriding_map_alist
,
3710 doc
: /* Alist of keymaps to use for minor modes, in current major mode.
3711 This variable is an alist just like `minor-mode-map-alist', and it is
3712 used the same way (and before `minor-mode-map-alist'); however,
3713 it is provided for major modes to bind locally. */);
3714 Vminor_mode_overriding_map_alist
= Qnil
;
3716 DEFVAR_LISP ("emulation-mode-map-alists", Vemulation_mode_map_alists
,
3717 doc
: /* List of keymap alists to use for emulation modes.
3718 It is intended for modes or packages using multiple minor-mode keymaps.
3719 Each element is a keymap alist just like `minor-mode-map-alist', or a
3720 symbol with a variable binding which is a keymap alist, and it is used
3721 the same way. The "active" keymaps in each alist are used before
3722 `minor-mode-map-alist' and `minor-mode-overriding-map-alist'. */);
3723 Vemulation_mode_map_alists
= Qnil
;
3725 DEFVAR_LISP ("where-is-preferred-modifier", Vwhere_is_preferred_modifier
,
3726 doc
: /* Preferred modifier key to use for `where-is'.
3727 When a single binding is requested, `where-is' will return one that
3728 uses this modifier key if possible. If nil, or if no such binding
3729 exists, bindings using keys without modifiers (or only with meta) will
3731 Vwhere_is_preferred_modifier
= Qnil
;
3732 where_is_preferred_modifier
= 0;
3734 staticpro (&Vmouse_events
);
3735 Vmouse_events
= listn (CONSTYPE_PURE
, 9,
3736 intern_c_string ("menu-bar"),
3737 intern_c_string ("tool-bar"),
3738 intern_c_string ("header-line"),
3739 intern_c_string ("mode-line"),
3740 intern_c_string ("mouse-1"),
3741 intern_c_string ("mouse-2"),
3742 intern_c_string ("mouse-3"),
3743 intern_c_string ("mouse-4"),
3744 intern_c_string ("mouse-5"));
3746 DEFSYM (Qsingle_key_description
, "single-key-description");
3747 DEFSYM (Qkey_description
, "key-description");
3748 DEFSYM (Qkeymapp
, "keymapp");
3749 DEFSYM (Qnon_ascii
, "non-ascii");
3750 DEFSYM (Qmenu_item
, "menu-item");
3751 DEFSYM (Qremap
, "remap");
3752 DEFSYM (QCadvertised_binding
, ":advertised-binding");
3754 command_remapping_vector
= Fmake_vector (make_number (2), Qremap
);
3755 staticpro (&command_remapping_vector
);
3757 where_is_cache_keymaps
= Qt
;
3758 where_is_cache
= Qnil
;
3759 staticpro (&where_is_cache
);
3760 staticpro (&where_is_cache_keymaps
);
3762 defsubr (&Skeymapp
);
3763 defsubr (&Skeymap_parent
);
3764 defsubr (&Skeymap_prompt
);
3765 defsubr (&Sset_keymap_parent
);
3766 defsubr (&Smake_keymap
);
3767 defsubr (&Smake_sparse_keymap
);
3768 defsubr (&Smap_keymap_internal
);
3769 defsubr (&Smap_keymap
);
3770 defsubr (&Scopy_keymap
);
3771 defsubr (&Scommand_remapping
);
3772 defsubr (&Skey_binding
);
3773 defsubr (&Slocal_key_binding
);
3774 defsubr (&Sglobal_key_binding
);
3775 defsubr (&Sminor_mode_key_binding
);
3776 defsubr (&Sdefine_key
);
3777 defsubr (&Slookup_key
);
3778 defsubr (&Sdefine_prefix_command
);
3779 defsubr (&Suse_global_map
);
3780 defsubr (&Suse_local_map
);
3781 defsubr (&Scurrent_local_map
);
3782 defsubr (&Scurrent_global_map
);
3783 defsubr (&Scurrent_minor_mode_maps
);
3784 defsubr (&Scurrent_active_maps
);
3785 defsubr (&Saccessible_keymaps
);
3786 defsubr (&Skey_description
);
3787 defsubr (&Sdescribe_vector
);
3788 defsubr (&Ssingle_key_description
);
3789 defsubr (&Stext_char_description
);
3790 defsubr (&Swhere_is_internal
);
3791 defsubr (&Sdescribe_buffer_bindings
);
3792 defsubr (&Sapropos_internal
);
3796 keys_of_keymap (void)
3798 initial_define_key (global_map
, 033, "ESC-prefix");
3799 initial_define_key (global_map
, Ctl ('X'), "Control-X-prefix");