1 /* Manipulation of keymaps
2 Copyright (C) 1985-1988, 1993-1995, 1998-2015 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"
50 #include "termhooks.h"
51 #include "blockinput.h"
53 #include "intervals.h"
57 /* Actually allocate storage for these variables. */
59 Lisp_Object current_global_map
; /* Current global keymap. */
61 Lisp_Object global_map
; /* Default global key bindings. */
63 Lisp_Object meta_map
; /* The keymap used for globally bound
64 ESC-prefixed default commands. */
66 Lisp_Object control_x_map
; /* The keymap used for globally bound
67 C-x-prefixed default commands. */
69 /* The keymap used by the minibuf for local
70 bindings when spaces are allowed in the
73 /* The keymap used by the minibuf for local
74 bindings when spaces are not encouraged
77 /* Alist of elements like (DEL . "\d"). */
78 static Lisp_Object exclude_keys
;
80 /* Pre-allocated 2-element vector for Fcommand_remapping to use. */
81 static Lisp_Object command_remapping_vector
;
83 /* Hash table used to cache a reverse-map to speed up calls to where-is. */
84 static Lisp_Object where_is_cache
;
85 /* Which keymaps are reverse-stored in the cache. */
86 static Lisp_Object where_is_cache_keymaps
;
88 static Lisp_Object
store_in_keymap (Lisp_Object
, Lisp_Object
, Lisp_Object
);
90 static Lisp_Object
define_as_prefix (Lisp_Object
, Lisp_Object
);
91 static void describe_command (Lisp_Object
, Lisp_Object
);
92 static void describe_translation (Lisp_Object
, Lisp_Object
);
93 static void describe_map (Lisp_Object
, Lisp_Object
,
94 void (*) (Lisp_Object
, Lisp_Object
),
95 bool, Lisp_Object
, Lisp_Object
*, bool, bool);
96 static void describe_vector (Lisp_Object
, Lisp_Object
, Lisp_Object
,
97 void (*) (Lisp_Object
, Lisp_Object
), bool,
98 Lisp_Object
, Lisp_Object
, bool, bool);
99 static void silly_event_symbol_error (Lisp_Object
);
100 static Lisp_Object
get_keyelt (Lisp_Object
, bool);
103 CHECK_VECTOR_OR_CHAR_TABLE (Lisp_Object x
)
105 CHECK_TYPE (VECTORP (x
) || CHAR_TABLE_P (x
), Qvector_or_char_table_p
, x
);
108 /* Keymap object support - constructors and predicates. */
110 DEFUN ("make-keymap", Fmake_keymap
, Smake_keymap
, 0, 1, 0,
111 doc
: /* Construct and return a new keymap, of the form (keymap CHARTABLE . ALIST).
112 CHARTABLE is a char-table that holds the bindings for all characters
113 without modifiers. All entries in it are initially nil, meaning
114 "command undefined". ALIST is an assoc-list which holds bindings for
115 function keys, mouse events, and any other things that appear in the
116 input stream. Initially, ALIST is nil.
118 The optional arg STRING supplies a menu name for the keymap
119 in case you use it as a menu with `x-popup-menu'. */)
124 tail
= list1 (string
);
127 return Fcons (Qkeymap
,
128 Fcons (Fmake_char_table (Qkeymap
, Qnil
), tail
));
131 DEFUN ("make-sparse-keymap", Fmake_sparse_keymap
, Smake_sparse_keymap
, 0, 1, 0,
132 doc
: /* Construct and return a new sparse keymap.
133 Its car is `keymap' and its cdr is an alist of (CHAR . DEFINITION),
134 which binds the character CHAR to DEFINITION, or (SYMBOL . DEFINITION),
135 which binds the function key or mouse event SYMBOL to DEFINITION.
136 Initially the alist is nil.
138 The optional arg STRING supplies a menu name for the keymap
139 in case you use it as a menu with `x-popup-menu'. */)
144 if (!NILP (Vpurify_flag
))
145 string
= Fpurecopy (string
);
146 return list2 (Qkeymap
, string
);
148 return list1 (Qkeymap
);
151 /* This function is used for installing the standard key bindings
152 at initialization time.
156 initial_define_key (control_x_map, Ctl('X'), "exchange-point-and-mark"); */
159 initial_define_key (Lisp_Object keymap
, int key
, const char *defname
)
161 store_in_keymap (keymap
, make_number (key
), intern_c_string (defname
));
165 initial_define_lispy_key (Lisp_Object keymap
, const char *keyname
, const char *defname
)
167 store_in_keymap (keymap
, intern_c_string (keyname
), intern_c_string (defname
));
170 DEFUN ("keymapp", Fkeymapp
, Skeymapp
, 1, 1, 0,
171 doc
: /* Return t if OBJECT is a keymap.
173 A keymap is a list (keymap . ALIST),
174 or a symbol whose function definition is itself a keymap.
175 ALIST elements look like (CHAR . DEFN) or (SYMBOL . DEFN);
176 a vector of densely packed bindings for small character codes
177 is also allowed as an element. */)
180 return (KEYMAPP (object
) ? Qt
: Qnil
);
183 DEFUN ("keymap-prompt", Fkeymap_prompt
, Skeymap_prompt
, 1, 1, 0,
184 doc
: /* Return the prompt-string of a keymap MAP.
185 If non-nil, the prompt is shown in the echo-area
186 when reading a key-sequence to be looked-up in this keymap. */)
189 map
= get_keymap (map
, 0, 0);
192 Lisp_Object tem
= XCAR (map
);
195 else if (KEYMAPP (tem
))
197 tem
= Fkeymap_prompt (tem
);
206 /* Check that OBJECT is a keymap (after dereferencing through any
207 symbols). If it is, return it.
209 If AUTOLOAD and if OBJECT is a symbol whose function value
210 is an autoload form, do the autoload and try again.
211 If AUTOLOAD, callers must assume GC is possible.
213 ERROR_IF_NOT_KEYMAP controls how we respond if OBJECT isn't a keymap.
214 If ERROR_IF_NOT_KEYMAP, signal an error; otherwise,
217 Note that most of the time, we don't want to pursue autoloads.
218 Functions like Faccessible_keymaps which scan entire keymap trees
219 shouldn't load every autoloaded keymap. I'm not sure about this,
220 but it seems to me that only read_key_sequence, Flookup_key, and
221 Fdefine_key should cause keymaps to be autoloaded.
223 This function can GC when AUTOLOAD is true, because it calls
224 Fautoload_do_load which can GC. */
227 get_keymap (Lisp_Object object
, bool error_if_not_keymap
, bool autoload
)
234 if (CONSP (object
) && EQ (XCAR (object
), Qkeymap
))
237 tem
= indirect_function (object
);
240 if (EQ (XCAR (tem
), Qkeymap
))
243 /* Should we do an autoload? Autoload forms for keymaps have
244 Qkeymap as their fifth element. */
245 if ((autoload
|| !error_if_not_keymap
) && EQ (XCAR (tem
), Qautoload
)
250 tail
= Fnth (make_number (4), tem
);
251 if (EQ (tail
, Qkeymap
))
255 Fautoload_do_load (tem
, object
, Qnil
);
265 if (error_if_not_keymap
)
266 wrong_type_argument (Qkeymapp
, object
);
270 /* Return the parent map of KEYMAP, or nil if it has none.
271 We assume that KEYMAP is a valid keymap. */
274 keymap_parent (Lisp_Object keymap
, bool autoload
)
278 keymap
= get_keymap (keymap
, 1, autoload
);
280 /* Skip past the initial element `keymap'. */
281 list
= XCDR (keymap
);
282 for (; CONSP (list
); list
= XCDR (list
))
284 /* See if there is another `keymap'. */
289 return get_keymap (list
, 0, autoload
);
292 DEFUN ("keymap-parent", Fkeymap_parent
, Skeymap_parent
, 1, 1, 0,
293 doc
: /* Return the parent keymap of KEYMAP.
294 If KEYMAP has no parent, return nil. */)
297 return keymap_parent (keymap
, 1);
300 /* Check whether MAP is one of MAPS parents. */
302 keymap_memberp (Lisp_Object map
, Lisp_Object maps
)
304 if (NILP (map
)) return 0;
305 while (KEYMAPP (maps
) && !EQ (map
, maps
))
306 maps
= keymap_parent (maps
, 0);
307 return (EQ (map
, maps
));
310 /* Set the parent keymap of MAP to PARENT. */
312 DEFUN ("set-keymap-parent", Fset_keymap_parent
, Sset_keymap_parent
, 2, 2, 0,
313 doc
: /* Modify KEYMAP to set its parent map to PARENT.
314 Return PARENT. PARENT should be nil or another keymap. */)
315 (Lisp_Object keymap
, Lisp_Object parent
)
317 Lisp_Object list
, prev
;
319 /* Flush any reverse-map cache. */
320 where_is_cache
= Qnil
; where_is_cache_keymaps
= Qt
;
322 keymap
= get_keymap (keymap
, 1, 1);
326 parent
= get_keymap (parent
, 1, 0);
328 /* Check for cycles. */
329 if (keymap_memberp (keymap
, parent
))
330 error ("Cyclic keymap inheritance");
333 /* Skip past the initial element `keymap'. */
338 /* If there is a parent keymap here, replace it.
339 If we came to the end, add the parent in PREV. */
340 if (!CONSP (list
) || KEYMAPP (list
))
342 CHECK_IMPURE (prev
, XCONS (prev
));
343 XSETCDR (prev
, parent
);
351 /* Look up IDX in MAP. IDX may be any sort of event.
352 Note that this does only one level of lookup; IDX must be a single
353 event, not a sequence.
355 MAP must be a keymap or a list of keymaps.
357 If T_OK, bindings for Qt are treated as default
358 bindings; any key left unmentioned by other tables and bindings is
359 given the binding of Qt.
361 If not T_OK, bindings for Qt are not treated specially.
363 If NOINHERIT, don't accept a subkeymap found in an inherited keymap.
365 Return Qunbound if no binding was found (and return Qnil if a nil
366 binding was found). */
369 access_keymap_1 (Lisp_Object map
, Lisp_Object idx
,
370 bool t_ok
, bool noinherit
, bool autoload
)
372 /* If idx is a list (some sort of mouse click, perhaps?),
373 the index we want to use is the car of the list, which
374 ought to be a symbol. */
375 idx
= EVENT_HEAD (idx
);
377 /* If idx is a symbol, it might have modifiers, which need to
378 be put in the canonical order. */
380 idx
= reorder_modifiers (idx
);
381 else if (INTEGERP (idx
))
382 /* Clobber the high bits that can be present on a machine
383 with more than 24 bits of integer. */
384 XSETFASTINT (idx
, XINT (idx
) & (CHAR_META
| (CHAR_META
- 1)));
386 /* Handle the special meta -> esc mapping. */
387 if (INTEGERP (idx
) && XFASTINT (idx
) & meta_modifier
)
389 /* See if there is a meta-map. If there's none, there is
390 no binding for IDX, unless a default binding exists in MAP. */
391 Lisp_Object event_meta_binding
, event_meta_map
;
392 /* A strange value in which Meta is set would cause
393 infinite recursion. Protect against that. */
394 if (XINT (meta_prefix_char
) & CHAR_META
)
395 meta_prefix_char
= make_number (27);
396 event_meta_binding
= access_keymap_1 (map
, meta_prefix_char
, t_ok
,
397 noinherit
, autoload
);
398 event_meta_map
= get_keymap (event_meta_binding
, 0, autoload
);
399 if (CONSP (event_meta_map
))
401 map
= event_meta_map
;
402 idx
= make_number (XFASTINT (idx
) & ~meta_modifier
);
405 /* Set IDX to t, so that we only find a default binding. */
408 /* An explicit nil binding, or no binding at all. */
409 return NILP (event_meta_binding
) ? Qnil
: Qunbound
;
412 /* t_binding is where we put a default binding that applies,
413 to use in case we do not find a binding specifically
414 for this key sequence. */
417 Lisp_Object t_binding
= Qunbound
;
418 Lisp_Object retval
= Qunbound
;
419 Lisp_Object retval_tail
= Qnil
;
421 for (tail
= (CONSP (map
) && EQ (Qkeymap
, XCAR (map
))) ? XCDR (map
) : map
;
423 || (tail
= get_keymap (tail
, 0, autoload
), CONSP (tail
)));
426 /* Qunbound in VAL means we have found no binding. */
427 Lisp_Object val
= Qunbound
;
428 Lisp_Object binding
= XCAR (tail
);
429 Lisp_Object submap
= get_keymap (binding
, 0, autoload
);
431 if (EQ (binding
, Qkeymap
))
433 if (noinherit
|| NILP (retval
))
434 /* If NOINHERIT, stop here, the rest is inherited. */
436 else if (!EQ (retval
, Qunbound
))
438 Lisp_Object parent_entry
;
439 eassert (KEYMAPP (retval
));
441 = get_keymap (access_keymap_1 (tail
, idx
,
444 if (KEYMAPP (parent_entry
))
446 if (CONSP (retval_tail
))
447 XSETCDR (retval_tail
, parent_entry
);
450 retval_tail
= Fcons (retval
, parent_entry
);
451 retval
= Fcons (Qkeymap
, retval_tail
);
457 else if (CONSP (submap
))
459 val
= access_keymap_1 (submap
, idx
, t_ok
, noinherit
, autoload
);
461 else if (CONSP (binding
))
463 Lisp_Object key
= XCAR (binding
);
466 val
= XCDR (binding
);
467 else if (t_ok
&& EQ (key
, Qt
))
469 t_binding
= XCDR (binding
);
473 else if (VECTORP (binding
))
475 if (INTEGERP (idx
) && XFASTINT (idx
) < ASIZE (binding
))
476 val
= AREF (binding
, XFASTINT (idx
));
478 else if (CHAR_TABLE_P (binding
))
480 /* Character codes with modifiers
481 are not included in a char-table.
482 All character codes without modifiers are included. */
483 if (INTEGERP (idx
) && (XFASTINT (idx
) & CHAR_MODIFIER_MASK
) == 0)
485 val
= Faref (binding
, idx
);
486 /* nil has a special meaning for char-tables, so
487 we use something else to record an explicitly
494 /* If we found a binding, clean it up and return it. */
495 if (!EQ (val
, Qunbound
))
498 /* A Qt binding is just like an explicit nil binding
499 (i.e. it shadows any parent binding but not bindings in
500 keymaps of lower precedence). */
503 val
= get_keyelt (val
, autoload
);
507 if (NILP (retval
) || EQ (retval
, Qunbound
))
510 break; /* Shadows everything that follows. */
512 else if (NILP (retval
) || EQ (retval
, Qunbound
))
514 else if (CONSP (retval_tail
))
516 XSETCDR (retval_tail
, list1 (val
));
517 retval_tail
= XCDR (retval_tail
);
521 retval_tail
= list1 (val
);
522 retval
= Fcons (Qkeymap
, Fcons (retval
, retval_tail
));
528 return EQ (Qunbound
, retval
) ? get_keyelt (t_binding
, autoload
) : retval
;
533 access_keymap (Lisp_Object map
, Lisp_Object idx
,
534 bool t_ok
, bool noinherit
, bool autoload
)
536 Lisp_Object val
= access_keymap_1 (map
, idx
, t_ok
, noinherit
, autoload
);
537 return EQ (val
, Qunbound
) ? Qnil
: val
;
541 map_keymap_item (map_keymap_function_t fun
, Lisp_Object args
, Lisp_Object key
, Lisp_Object val
, void *data
)
545 (*fun
) (key
, val
, args
, data
);
549 map_keymap_char_table_item (Lisp_Object args
, Lisp_Object key
, Lisp_Object val
)
553 map_keymap_function_t fun
554 = (map_keymap_function_t
) XSAVE_FUNCPOINTER (args
, 0);
555 /* If the key is a range, make a copy since map_char_table modifies
558 key
= Fcons (XCAR (key
), XCDR (key
));
559 map_keymap_item (fun
, XSAVE_OBJECT (args
, 2), key
,
560 val
, XSAVE_POINTER (args
, 1));
564 /* Call FUN for every binding in MAP and stop at (and return) the parent.
565 FUN is called with 4 arguments: FUN (KEY, BINDING, ARGS, DATA). */
567 map_keymap_internal (Lisp_Object map
,
568 map_keymap_function_t fun
,
573 = (CONSP (map
) && EQ (Qkeymap
, XCAR (map
))) ? XCDR (map
) : map
;
575 for (; CONSP (tail
) && !EQ (Qkeymap
, XCAR (tail
)); tail
= XCDR (tail
))
577 Lisp_Object binding
= XCAR (tail
);
579 if (KEYMAPP (binding
)) /* An embedded parent. */
581 else if (CONSP (binding
))
582 map_keymap_item (fun
, args
, XCAR (binding
), XCDR (binding
), data
);
583 else if (VECTORP (binding
))
585 /* Loop over the char values represented in the vector. */
586 int len
= ASIZE (binding
);
588 for (c
= 0; c
< len
; c
++)
590 Lisp_Object character
;
591 XSETFASTINT (character
, c
);
592 map_keymap_item (fun
, args
, character
, AREF (binding
, c
), data
);
595 else if (CHAR_TABLE_P (binding
))
596 map_char_table (map_keymap_char_table_item
, Qnil
, binding
,
597 make_save_funcptr_ptr_obj ((voidfuncptr
) fun
, data
,
605 map_keymap_call (Lisp_Object key
, Lisp_Object val
, Lisp_Object fun
, void *dummy
)
607 call2 (fun
, key
, val
);
610 /* Same as map_keymap_internal, but traverses parent keymaps as well.
611 AUTOLOAD indicates that autoloaded keymaps should be loaded. */
613 map_keymap (Lisp_Object map
, map_keymap_function_t fun
, Lisp_Object args
,
614 void *data
, bool autoload
)
616 map
= get_keymap (map
, 1, autoload
);
619 if (KEYMAPP (XCAR (map
)))
621 map_keymap (XCAR (map
), fun
, args
, data
, autoload
);
625 map
= map_keymap_internal (map
, fun
, args
, data
);
627 map
= get_keymap (map
, 0, autoload
);
631 /* Same as map_keymap, but does it right, properly eliminating duplicate
632 bindings due to inheritance. */
634 map_keymap_canonical (Lisp_Object map
, map_keymap_function_t fun
, Lisp_Object args
, void *data
)
636 /* map_keymap_canonical may be used from redisplay (e.g. when building menus)
637 so be careful to ignore errors and to inhibit redisplay. */
638 map
= safe_call1 (Qkeymap_canonicalize
, map
);
639 /* No need to use `map_keymap' here because canonical map has no parent. */
640 map_keymap_internal (map
, fun
, args
, data
);
643 DEFUN ("map-keymap-internal", Fmap_keymap_internal
, Smap_keymap_internal
, 2, 2, 0,
644 doc
: /* Call FUNCTION once for each event binding in KEYMAP.
645 FUNCTION is called with two arguments: the event that is bound, and
646 the definition it is bound to. The event may be a character range.
647 If KEYMAP has a parent, this function returns it without processing it. */)
648 (Lisp_Object function
, Lisp_Object keymap
)
650 keymap
= get_keymap (keymap
, 1, 1);
651 keymap
= map_keymap_internal (keymap
, map_keymap_call
, function
, NULL
);
655 DEFUN ("map-keymap", Fmap_keymap
, Smap_keymap
, 2, 3, 0,
656 doc
: /* Call FUNCTION once for each event binding in KEYMAP.
657 FUNCTION is called with two arguments: the event that is bound, and
658 the definition it is bound to. The event may be a character range.
660 If KEYMAP has a parent, the parent's bindings are included as well.
661 This works recursively: if the parent has itself a parent, then the
662 grandparent's bindings are also included and so on.
663 usage: (map-keymap FUNCTION KEYMAP) */)
664 (Lisp_Object function
, Lisp_Object keymap
, Lisp_Object sort_first
)
666 if (! NILP (sort_first
))
667 return call2 (intern ("map-keymap-sorted"), function
, keymap
);
669 map_keymap (keymap
, map_keymap_call
, function
, NULL
, 1);
673 /* Given OBJECT which was found in a slot in a keymap,
674 trace indirect definitions to get the actual definition of that slot.
675 An indirect definition is a list of the form
676 (KEYMAP . INDEX), where KEYMAP is a keymap or a symbol defined as one
677 and INDEX is the object to look up in KEYMAP to yield the definition.
679 Also if OBJECT has a menu string as the first element,
680 remove that. Also remove a menu help string as second element.
682 If AUTOLOAD, load autoloadable keymaps
683 that are referred to with indirection.
685 This can GC because menu_item_eval_property calls Feval. */
688 get_keyelt (Lisp_Object object
, bool autoload
)
692 if (!(CONSP (object
)))
693 /* This is really the value. */
696 /* If the keymap contents looks like (menu-item name . DEFN)
697 or (menu-item name DEFN ...) then use DEFN.
698 This is a new format menu item. */
699 else if (EQ (XCAR (object
), Qmenu_item
))
701 if (CONSP (XCDR (object
)))
705 object
= XCDR (XCDR (object
));
708 object
= XCAR (object
);
710 /* If there's a `:filter FILTER', apply FILTER to the
711 menu-item's definition to get the real definition to
713 for (; CONSP (tem
) && CONSP (XCDR (tem
)); tem
= XCDR (tem
))
714 if (EQ (XCAR (tem
), QCfilter
) && autoload
)
717 filter
= XCAR (XCDR (tem
));
718 filter
= list2 (filter
, list2 (Qquote
, object
));
719 object
= menu_item_eval_property (filter
);
724 /* Invalid keymap. */
728 /* If the keymap contents looks like (STRING . DEFN), use DEFN.
729 Keymap alist elements like (CHAR MENUSTRING . DEFN)
730 will be used by HierarKey menus. */
731 else if (STRINGP (XCAR (object
)))
732 object
= XCDR (object
);
740 store_in_keymap (Lisp_Object keymap
, register Lisp_Object idx
, Lisp_Object def
)
742 /* Flush any reverse-map cache. */
743 where_is_cache
= Qnil
;
744 where_is_cache_keymaps
= Qt
;
746 if (EQ (idx
, Qkeymap
))
747 error ("`keymap' is reserved for embedded parent maps");
749 /* If we are preparing to dump, and DEF is a menu element
750 with a menu item indicator, copy it to ensure it is not pure. */
751 if (CONSP (def
) && PURE_P (XCONS (def
))
752 && (EQ (XCAR (def
), Qmenu_item
) || STRINGP (XCAR (def
))))
753 def
= Fcons (XCAR (def
), XCDR (def
));
755 if (!CONSP (keymap
) || !EQ (XCAR (keymap
), Qkeymap
))
756 error ("attempt to define a key in a non-keymap");
758 /* If idx is a cons, and the car part is a character, idx must be of
759 the form (FROM-CHAR . TO-CHAR). */
760 if (CONSP (idx
) && CHARACTERP (XCAR (idx
)))
761 CHECK_CHARACTER_CDR (idx
);
763 /* If idx is a list (some sort of mouse click, perhaps?),
764 the index we want to use is the car of the list, which
765 ought to be a symbol. */
766 idx
= EVENT_HEAD (idx
);
768 /* If idx is a symbol, it might have modifiers, which need to
769 be put in the canonical order. */
771 idx
= reorder_modifiers (idx
);
772 else if (INTEGERP (idx
))
773 /* Clobber the high bits that can be present on a machine
774 with more than 24 bits of integer. */
775 XSETFASTINT (idx
, XINT (idx
) & (CHAR_META
| (CHAR_META
- 1)));
777 /* Scan the keymap for a binding of idx. */
781 /* The cons after which we should insert new bindings. If the
782 keymap has a table element, we record its position here, so new
783 bindings will go after it; this way, the table will stay
784 towards the front of the alist and character lookups in dense
785 keymaps will remain fast. Otherwise, this just points at the
786 front of the keymap. */
787 Lisp_Object insertion_point
;
789 insertion_point
= keymap
;
790 for (tail
= XCDR (keymap
); CONSP (tail
); tail
= XCDR (tail
))
797 if (NATNUMP (idx
) && XFASTINT (idx
) < ASIZE (elt
))
799 CHECK_IMPURE (elt
, XVECTOR (elt
));
800 ASET (elt
, XFASTINT (idx
), def
);
803 else if (CONSP (idx
) && CHARACTERP (XCAR (idx
)))
805 int from
= XFASTINT (XCAR (idx
));
806 int to
= XFASTINT (XCDR (idx
));
808 if (to
>= ASIZE (elt
))
809 to
= ASIZE (elt
) - 1;
810 for (; from
<= to
; from
++)
811 ASET (elt
, from
, def
);
812 if (to
== XFASTINT (XCDR (idx
)))
813 /* We have defined all keys in IDX. */
816 insertion_point
= tail
;
818 else if (CHAR_TABLE_P (elt
))
820 /* Character codes with modifiers
821 are not included in a char-table.
822 All character codes without modifiers are included. */
823 if (NATNUMP (idx
) && !(XFASTINT (idx
) & CHAR_MODIFIER_MASK
))
826 /* nil has a special meaning for char-tables, so
827 we use something else to record an explicitly
829 NILP (def
) ? Qt
: def
);
832 else if (CONSP (idx
) && CHARACTERP (XCAR (idx
)))
834 Fset_char_table_range (elt
, idx
, NILP (def
) ? Qt
: def
);
837 insertion_point
= tail
;
839 else if (CONSP (elt
))
841 if (EQ (Qkeymap
, XCAR (elt
)))
842 { /* A sub keymap. This might be due to a lookup that found
843 two matching bindings (maybe because of a sub keymap).
844 It almost never happens (since the second binding normally
845 only happens in the inherited part of the keymap), but
846 if it does, we want to update the sub-keymap since the
847 main one might be temporary (built by access_keymap). */
848 tail
= insertion_point
= elt
;
850 else if (EQ (idx
, XCAR (elt
)))
852 CHECK_IMPURE (elt
, XCONS (elt
));
856 else if (CONSP (idx
) && CHARACTERP (XCAR (idx
)))
858 int from
= XFASTINT (XCAR (idx
));
859 int to
= XFASTINT (XCDR (idx
));
861 if (from
<= XFASTINT (XCAR (elt
))
862 && to
>= XFASTINT (XCAR (elt
)))
870 else if (EQ (elt
, Qkeymap
))
871 /* If we find a 'keymap' symbol in the spine of KEYMAP,
872 then we must have found the start of a second keymap
873 being used as the tail of KEYMAP, and a binding for IDX
874 should be inserted before it. */
881 /* We have scanned the entire keymap, and not found a binding for
882 IDX. Let's add one. */
886 if (CONSP (idx
) && CHARACTERP (XCAR (idx
)))
888 /* IDX specifies a range of characters, and not all of them
889 were handled yet, which means this keymap doesn't have a
890 char-table. So, we insert a char-table now. */
891 elt
= Fmake_char_table (Qkeymap
, Qnil
);
892 Fset_char_table_range (elt
, idx
, NILP (def
) ? Qt
: def
);
895 elt
= Fcons (idx
, def
);
896 CHECK_IMPURE (insertion_point
, XCONS (insertion_point
));
897 XSETCDR (insertion_point
, Fcons (elt
, XCDR (insertion_point
)));
905 copy_keymap_item (Lisp_Object elt
)
907 Lisp_Object res
, tem
;
914 /* Is this a new format menu item. */
915 if (EQ (XCAR (tem
), Qmenu_item
))
917 /* Copy cell with menu-item marker. */
918 res
= elt
= Fcons (XCAR (tem
), XCDR (tem
));
922 /* Copy cell with menu-item name. */
923 XSETCDR (elt
, Fcons (XCAR (tem
), XCDR (tem
)));
929 /* Copy cell with binding and if the binding is a keymap,
931 XSETCDR (elt
, Fcons (XCAR (tem
), XCDR (tem
)));
934 if (CONSP (tem
) && EQ (XCAR (tem
), Qkeymap
))
935 XSETCAR (elt
, Fcopy_keymap (tem
));
941 /* It may be an old format menu item.
942 Skip the optional menu string. */
943 if (STRINGP (XCAR (tem
)))
945 /* Copy the cell, since copy-alist didn't go this deep. */
946 res
= elt
= Fcons (XCAR (tem
), XCDR (tem
));
948 /* Also skip the optional menu help string. */
949 if (CONSP (tem
) && STRINGP (XCAR (tem
)))
951 XSETCDR (elt
, Fcons (XCAR (tem
), XCDR (tem
)));
955 if (CONSP (tem
) && EQ (XCAR (tem
), Qkeymap
))
956 XSETCDR (elt
, Fcopy_keymap (tem
));
958 else if (EQ (XCAR (tem
), Qkeymap
))
959 res
= Fcopy_keymap (elt
);
965 copy_keymap_1 (Lisp_Object chartable
, Lisp_Object idx
, Lisp_Object elt
)
967 Fset_char_table_range (chartable
, idx
, copy_keymap_item (elt
));
970 DEFUN ("copy-keymap", Fcopy_keymap
, Scopy_keymap
, 1, 1, 0,
971 doc
: /* Return a copy of the keymap KEYMAP.
972 The copy starts out with the same definitions of KEYMAP,
973 but changing either the copy or KEYMAP does not affect the other.
974 Any key definitions that are subkeymaps are recursively copied.
975 However, a key definition which is a symbol whose definition is a keymap
979 Lisp_Object copy
, tail
;
980 keymap
= get_keymap (keymap
, 1, 0);
981 copy
= tail
= list1 (Qkeymap
);
982 keymap
= XCDR (keymap
); /* Skip the `keymap' symbol. */
984 while (CONSP (keymap
) && !EQ (XCAR (keymap
), Qkeymap
))
986 Lisp_Object elt
= XCAR (keymap
);
987 if (CHAR_TABLE_P (elt
))
989 elt
= Fcopy_sequence (elt
);
990 map_char_table (copy_keymap_1
, Qnil
, elt
, elt
);
992 else if (VECTORP (elt
))
995 elt
= Fcopy_sequence (elt
);
996 for (i
= 0; i
< ASIZE (elt
); i
++)
997 ASET (elt
, i
, copy_keymap_item (AREF (elt
, i
)));
999 else if (CONSP (elt
))
1001 if (EQ (XCAR (elt
), Qkeymap
))
1002 /* This is a sub keymap. */
1003 elt
= Fcopy_keymap (elt
);
1005 elt
= Fcons (XCAR (elt
), copy_keymap_item (XCDR (elt
)));
1007 XSETCDR (tail
, list1 (elt
));
1009 keymap
= XCDR (keymap
);
1011 XSETCDR (tail
, keymap
);
1015 /* Simple Keymap mutators and accessors. */
1017 /* GC is possible in this function if it autoloads a keymap. */
1019 DEFUN ("define-key", Fdefine_key
, Sdefine_key
, 3, 3, 0,
1020 doc
: /* In KEYMAP, define key sequence KEY as DEF.
1023 KEY is a string or a vector of symbols and characters, representing a
1024 sequence of keystrokes and events. Non-ASCII characters with codes
1025 above 127 (such as ISO Latin-1) can be represented by vectors.
1026 Two types of vector have special meanings:
1027 [remap COMMAND] remaps any key binding for COMMAND.
1028 [t] creates a default definition, which applies to any event with no
1029 other definition in KEYMAP.
1031 DEF is anything that can be a key's definition:
1032 nil (means key is undefined in this keymap),
1033 a command (a Lisp function suitable for interactive calling),
1034 a string (treated as a keyboard macro),
1035 a keymap (to define a prefix key),
1036 a symbol (when the key is looked up, the symbol will stand for its
1037 function definition, which should at that time be one of the above,
1038 or another symbol whose function definition is used, etc.),
1039 a cons (STRING . DEFN), meaning that DEFN is the definition
1040 (DEFN should be a valid definition in its own right),
1041 or a cons (MAP . CHAR), meaning use definition of CHAR in keymap MAP,
1042 or an extended menu item definition.
1043 (See info node `(elisp)Extended Menu Items'.)
1045 If KEYMAP is a sparse keymap with a binding for KEY, the existing
1046 binding is altered. If there is no binding for KEY, the new pair
1047 binding KEY to DEF is added at the front of KEYMAP. */)
1048 (Lisp_Object keymap
, Lisp_Object key
, Lisp_Object def
)
1057 keymap
= get_keymap (keymap
, 1, 1);
1059 length
= CHECK_VECTOR_OR_STRING (key
);
1063 if (SYMBOLP (def
) && !EQ (Vdefine_key_rebound_commands
, Qt
))
1064 Vdefine_key_rebound_commands
= Fcons (def
, Vdefine_key_rebound_commands
);
1066 meta_bit
= (VECTORP (key
) || (STRINGP (key
) && STRING_MULTIBYTE (key
))
1067 ? meta_modifier
: 0x80);
1069 if (VECTORP (def
) && ASIZE (def
) > 0 && CONSP (AREF (def
, 0)))
1070 { /* DEF is apparently an XEmacs-style keyboard macro. */
1071 Lisp_Object tmp
= Fmake_vector (make_number (ASIZE (def
)), Qnil
);
1072 ptrdiff_t i
= ASIZE (def
);
1075 Lisp_Object defi
= AREF (def
, i
);
1076 if (CONSP (defi
) && lucid_event_type_list_p (defi
))
1077 defi
= Fevent_convert_list (defi
);
1078 ASET (tmp
, i
, defi
);
1086 c
= Faref (key
, make_number (idx
));
1090 /* C may be a Lucid style event type list or a cons (FROM .
1091 TO) specifying a range of characters. */
1092 if (lucid_event_type_list_p (c
))
1093 c
= Fevent_convert_list (c
);
1094 else if (CHARACTERP (XCAR (c
)))
1095 CHECK_CHARACTER_CDR (c
);
1099 silly_event_symbol_error (c
);
1102 && (XINT (c
) & meta_bit
)
1105 c
= meta_prefix_char
;
1111 XSETINT (c
, XINT (c
) & ~meta_bit
);
1117 if (!INTEGERP (c
) && !SYMBOLP (c
)
1119 /* If C is a range, it must be a leaf. */
1120 || (INTEGERP (XCAR (c
)) && idx
!= length
)))
1121 message_with_string ("Key sequence contains invalid event %s", c
, 1);
1124 return store_in_keymap (keymap
, c
, def
);
1126 cmd
= access_keymap (keymap
, c
, 0, 1, 1);
1128 /* If this key is undefined, make it a prefix. */
1130 cmd
= define_as_prefix (keymap
, c
);
1132 keymap
= get_keymap (cmd
, 0, 1);
1133 if (!CONSP (keymap
))
1135 const char *trailing_esc
= ((EQ (c
, meta_prefix_char
) && metized
)
1136 ? (idx
== 0 ? "ESC" : " ESC")
1139 /* We must use Fkey_description rather than just passing key to
1140 error; key might be a vector, not a string. */
1141 error ("Key sequence %s starts with non-prefix key %s%s",
1142 SDATA (Fkey_description (key
, Qnil
)),
1143 SDATA (Fkey_description (Fsubstring (key
, make_number (0),
1151 /* This function may GC (it calls Fkey_binding). */
1153 DEFUN ("command-remapping", Fcommand_remapping
, Scommand_remapping
, 1, 3, 0,
1154 doc
: /* Return the remapping for command COMMAND.
1155 Returns nil if COMMAND is not remapped (or not a symbol).
1157 If the optional argument POSITION is non-nil, it specifies a mouse
1158 position as returned by `event-start' and `event-end', and the
1159 remapping occurs in the keymaps associated with it. It can also be a
1160 number or marker, in which case the keymap properties at the specified
1161 buffer position instead of point are used. The KEYMAPS argument is
1162 ignored if POSITION is non-nil.
1164 If the optional argument KEYMAPS is non-nil, it should be a list of
1165 keymaps to search for command remapping. Otherwise, search for the
1166 remapping in all currently active keymaps. */)
1167 (Lisp_Object command
, Lisp_Object position
, Lisp_Object keymaps
)
1169 if (!SYMBOLP (command
))
1172 ASET (command_remapping_vector
, 1, command
);
1175 command
= Fkey_binding (command_remapping_vector
, Qnil
, Qt
, position
);
1177 command
= Flookup_key (Fcons (Qkeymap
, keymaps
),
1178 command_remapping_vector
, Qnil
);
1179 return INTEGERP (command
) ? Qnil
: command
;
1182 /* Value is number if KEY is too long; nil if valid but has no definition. */
1183 /* GC is possible in this function. */
1185 DEFUN ("lookup-key", Flookup_key
, Slookup_key
, 2, 3, 0,
1186 doc
: /* In keymap KEYMAP, look up key sequence KEY. Return the definition.
1187 A value of nil means undefined. See doc of `define-key'
1188 for kinds of definitions.
1190 A number as value means KEY is "too long";
1191 that is, characters or symbols in it except for the last one
1192 fail to be a valid sequence of prefix characters in KEYMAP.
1193 The number is how many characters at the front of KEY
1194 it takes to reach a non-prefix key.
1196 Normally, `lookup-key' ignores bindings for t, which act as default
1197 bindings, used when nothing else in the keymap applies; this makes it
1198 usable as a general function for probing keymaps. However, if the
1199 third optional argument ACCEPT-DEFAULT is non-nil, `lookup-key' will
1200 recognize the default bindings, just as `read-key-sequence' does. */)
1201 (Lisp_Object keymap
, Lisp_Object key
, Lisp_Object accept_default
)
1207 bool t_ok
= !NILP (accept_default
);
1209 keymap
= get_keymap (keymap
, 1, 1);
1211 length
= CHECK_VECTOR_OR_STRING (key
);
1218 c
= Faref (key
, make_number (idx
++));
1220 if (CONSP (c
) && lucid_event_type_list_p (c
))
1221 c
= Fevent_convert_list (c
);
1223 /* Turn the 8th bit of string chars into a meta modifier. */
1224 if (STRINGP (key
) && XINT (c
) & 0x80 && !STRING_MULTIBYTE (key
))
1225 XSETINT (c
, (XINT (c
) | meta_modifier
) & ~0x80);
1227 /* Allow string since binding for `menu-bar-select-buffer'
1228 includes the buffer name in the key sequence. */
1229 if (!INTEGERP (c
) && !SYMBOLP (c
) && !CONSP (c
) && !STRINGP (c
))
1230 message_with_string ("Key sequence contains invalid event %s", c
, 1);
1232 cmd
= access_keymap (keymap
, c
, t_ok
, 0, 1);
1236 keymap
= get_keymap (cmd
, 0, 1);
1237 if (!CONSP (keymap
))
1238 return make_number (idx
);
1244 /* Make KEYMAP define event C as a keymap (i.e., as a prefix).
1245 Assume that currently it does not define C at all.
1246 Return the keymap. */
1249 define_as_prefix (Lisp_Object keymap
, Lisp_Object c
)
1253 cmd
= Fmake_sparse_keymap (Qnil
);
1254 store_in_keymap (keymap
, c
, cmd
);
1259 /* Append a key to the end of a key sequence. We always make a vector. */
1262 append_key (Lisp_Object key_sequence
, Lisp_Object key
)
1264 AUTO_LIST1 (key_list
, key
);
1265 return CALLN (Fvconcat
, key_sequence
, key_list
);
1268 /* Given a event type C which is a symbol,
1269 signal an error if is a mistake such as RET or M-RET or C-DEL, etc. */
1272 silly_event_symbol_error (Lisp_Object c
)
1274 Lisp_Object parsed
, base
, name
, assoc
;
1277 parsed
= parse_modifiers (c
);
1278 modifiers
= XFASTINT (XCAR (XCDR (parsed
)));
1279 base
= XCAR (parsed
);
1280 name
= Fsymbol_name (base
);
1281 /* This alist includes elements such as ("RET" . "\\r"). */
1282 assoc
= Fassoc (name
, exclude_keys
);
1286 char new_mods
[sizeof ("\\A-\\C-\\H-\\M-\\S-\\s-")];
1288 Lisp_Object keystring
;
1289 if (modifiers
& alt_modifier
)
1290 { *p
++ = '\\'; *p
++ = 'A'; *p
++ = '-'; }
1291 if (modifiers
& ctrl_modifier
)
1292 { *p
++ = '\\'; *p
++ = 'C'; *p
++ = '-'; }
1293 if (modifiers
& hyper_modifier
)
1294 { *p
++ = '\\'; *p
++ = 'H'; *p
++ = '-'; }
1295 if (modifiers
& meta_modifier
)
1296 { *p
++ = '\\'; *p
++ = 'M'; *p
++ = '-'; }
1297 if (modifiers
& shift_modifier
)
1298 { *p
++ = '\\'; *p
++ = 'S'; *p
++ = '-'; }
1299 if (modifiers
& super_modifier
)
1300 { *p
++ = '\\'; *p
++ = 's'; *p
++ = '-'; }
1303 c
= reorder_modifiers (c
);
1304 AUTO_STRING (new_mods_string
, new_mods
);
1305 keystring
= concat2 (new_mods_string
, XCDR (assoc
));
1307 error ("To bind the key %s, use [?%s], not [%s]",
1308 SDATA (SYMBOL_NAME (c
)), SDATA (keystring
),
1309 SDATA (SYMBOL_NAME (c
)));
1313 /* Global, local, and minor mode keymap stuff. */
1315 /* We can't put these variables inside current_minor_maps, since under
1316 some systems, static gets macro-defined to be the empty string.
1318 static Lisp_Object
*cmm_modes
= NULL
, *cmm_maps
= NULL
;
1319 static ptrdiff_t cmm_size
= 0;
1321 /* Store a pointer to an array of the currently active minor modes in
1322 *modeptr, a pointer to an array of the keymaps of the currently
1323 active minor modes in *mapptr, and return the number of maps
1326 This function always returns a pointer to the same buffer, and may
1327 free or reallocate it, so if you want to keep it for a long time or
1328 hand it out to lisp code, copy it. This procedure will be called
1329 for every key sequence read, so the nice lispy approach (return a
1330 new assoclist, list, what have you) for each invocation would
1331 result in a lot of consing over time.
1333 If we used xrealloc/xmalloc and ran out of memory, they would throw
1334 back to the command loop, which would try to read a key sequence,
1335 which would call this function again, resulting in an infinite
1336 loop. Instead, we'll use realloc/malloc and silently truncate the
1337 list, let the key sequence be read, and hope some other piece of
1338 code signals the error. */
1340 current_minor_maps (Lisp_Object
**modeptr
, Lisp_Object
**mapptr
)
1343 int list_number
= 0;
1344 Lisp_Object alist
, assoc
, var
, val
;
1345 Lisp_Object emulation_alists
;
1346 Lisp_Object lists
[2];
1348 emulation_alists
= Vemulation_mode_map_alists
;
1349 lists
[0] = Vminor_mode_overriding_map_alist
;
1350 lists
[1] = Vminor_mode_map_alist
;
1352 for (list_number
= 0; list_number
< 2; list_number
++)
1354 if (CONSP (emulation_alists
))
1356 alist
= XCAR (emulation_alists
);
1357 emulation_alists
= XCDR (emulation_alists
);
1358 if (SYMBOLP (alist
))
1359 alist
= find_symbol_value (alist
);
1363 alist
= lists
[list_number
];
1365 for ( ; CONSP (alist
); alist
= XCDR (alist
))
1366 if ((assoc
= XCAR (alist
), CONSP (assoc
))
1367 && (var
= XCAR (assoc
), SYMBOLP (var
))
1368 && (val
= find_symbol_value (var
), !EQ (val
, Qunbound
))
1373 /* If a variable has an entry in Vminor_mode_overriding_map_alist,
1374 and also an entry in Vminor_mode_map_alist,
1375 ignore the latter. */
1376 if (list_number
== 1)
1378 val
= assq_no_quit (var
, lists
[0]);
1385 ptrdiff_t newsize
, allocsize
;
1386 Lisp_Object
*newmodes
, *newmaps
;
1388 /* Check for size calculation overflow. Other code
1389 (e.g., read_key_sequence) adds 3 to the count
1390 later, so subtract 3 from the limit here. */
1391 if (min (PTRDIFF_MAX
, SIZE_MAX
) / (2 * sizeof *newmodes
) - 3
1395 newsize
= cmm_size
== 0 ? 30 : cmm_size
* 2;
1396 allocsize
= newsize
* sizeof *newmodes
;
1398 /* Use malloc here. See the comment above this function.
1399 Avoid realloc here; it causes spurious traps on GNU/Linux [KFS] */
1401 newmodes
= malloc (allocsize
);
1406 memcpy (newmodes
, cmm_modes
,
1407 cmm_size
* sizeof cmm_modes
[0]);
1410 cmm_modes
= newmodes
;
1413 newmaps
= malloc (allocsize
);
1418 memcpy (newmaps
, cmm_maps
,
1419 cmm_size
* sizeof cmm_maps
[0]);
1426 if (newmodes
== NULL
|| newmaps
== NULL
)
1431 /* Get the keymap definition--or nil if it is not defined. */
1432 temp
= Findirect_function (XCDR (assoc
), Qt
);
1436 cmm_maps
[i
] = temp
;
1442 if (modeptr
) *modeptr
= cmm_modes
;
1443 if (mapptr
) *mapptr
= cmm_maps
;
1447 /* Return the offset of POSITION, a click position, in the style of
1448 the respective argument of Fkey_binding. */
1450 click_position (Lisp_Object position
)
1452 EMACS_INT pos
= (INTEGERP (position
) ? XINT (position
)
1453 : MARKERP (position
) ? marker_position (position
)
1455 if (! (BEGV
<= pos
&& pos
<= ZV
))
1456 args_out_of_range (Fcurrent_buffer (), position
);
1460 DEFUN ("current-active-maps", Fcurrent_active_maps
, Scurrent_active_maps
,
1462 doc
: /* Return a list of the currently active keymaps.
1463 OLP if non-nil indicates that we should obey `overriding-local-map' and
1464 `overriding-terminal-local-map'. POSITION can specify a click position
1465 like in the respective argument of `key-binding'. */)
1466 (Lisp_Object olp
, Lisp_Object position
)
1468 ptrdiff_t count
= SPECPDL_INDEX ();
1470 Lisp_Object keymaps
= list1 (current_global_map
);
1472 /* If a mouse click position is given, our variables are based on
1473 the buffer clicked on, not the current buffer. So we may have to
1474 switch the buffer here. */
1476 if (CONSP (position
))
1480 window
= POSN_WINDOW (position
);
1482 if (WINDOWP (window
)
1483 && BUFFERP (XWINDOW (window
)->contents
)
1484 && XBUFFER (XWINDOW (window
)->contents
) != current_buffer
)
1486 /* Arrange to go back to the original buffer once we're done
1487 processing the key sequence. We don't use
1488 save_excursion_{save,restore} here, in analogy to
1489 `read-key-sequence' to avoid saving point. Maybe this
1490 would not be a problem here, but it is easier to keep
1493 record_unwind_current_buffer ();
1494 set_buffer_internal (XBUFFER (XWINDOW (window
)->contents
));
1499 /* The doc said that overriding-terminal-local-map should
1500 override overriding-local-map. The code used them both,
1501 but it seems clearer to use just one. rms, jan 2005. */
1502 && NILP (KVAR (current_kboard
, Voverriding_terminal_local_map
))
1503 && !NILP (Voverriding_local_map
))
1504 keymaps
= Fcons (Voverriding_local_map
, keymaps
);
1506 if (NILP (XCDR (keymaps
)))
1510 ptrdiff_t pt
= click_position (position
);
1511 /* This usually returns the buffer's local map,
1512 but that can be overridden by a `local-map' property. */
1513 Lisp_Object local_map
= get_local_map (pt
, current_buffer
, Qlocal_map
);
1514 /* This returns nil unless there is a `keymap' property. */
1515 Lisp_Object keymap
= get_local_map (pt
, current_buffer
, Qkeymap
);
1516 Lisp_Object otlp
= KVAR (current_kboard
, Voverriding_terminal_local_map
);
1518 if (CONSP (position
))
1520 Lisp_Object string
= POSN_STRING (position
);
1522 /* For a mouse click, get the local text-property keymap
1523 of the place clicked on, rather than point. */
1525 if (POSN_INBUFFER_P (position
))
1529 pos
= POSN_BUFFER_POSN (position
);
1531 && XINT (pos
) >= BEG
&& XINT (pos
) <= Z
)
1533 local_map
= get_local_map (XINT (pos
),
1534 current_buffer
, Qlocal_map
);
1536 keymap
= get_local_map (XINT (pos
),
1537 current_buffer
, Qkeymap
);
1541 /* If on a mode line string with a local keymap,
1542 or for a click on a string, i.e. overlay string or a
1543 string displayed via the `display' property,
1544 consider `local-map' and `keymap' properties of
1547 if (CONSP (string
) && STRINGP (XCAR (string
)))
1549 Lisp_Object pos
, map
;
1551 pos
= XCDR (string
);
1552 string
= XCAR (string
);
1555 && XINT (pos
) < SCHARS (string
))
1557 map
= Fget_text_property (pos
, Qlocal_map
, string
);
1561 map
= Fget_text_property (pos
, Qkeymap
, string
);
1569 if (!NILP (local_map
))
1570 keymaps
= Fcons (local_map
, keymaps
);
1572 /* Now put all the minor mode keymaps on the list. */
1573 nmaps
= current_minor_maps (0, &maps
);
1575 for (i
= --nmaps
; i
>= 0; i
--)
1576 if (!NILP (maps
[i
]))
1577 keymaps
= Fcons (maps
[i
], keymaps
);
1580 keymaps
= Fcons (keymap
, keymaps
);
1582 if (!NILP (olp
) && !NILP (otlp
))
1583 keymaps
= Fcons (otlp
, keymaps
);
1586 unbind_to (count
, Qnil
);
1591 /* GC is possible in this function if it autoloads a keymap. */
1593 DEFUN ("key-binding", Fkey_binding
, Skey_binding
, 1, 4, 0,
1594 doc
: /* Return the binding for command KEY in current keymaps.
1595 KEY is a string or vector, a sequence of keystrokes.
1596 The binding is probably a symbol with a function definition.
1598 Normally, `key-binding' ignores bindings for t, which act as default
1599 bindings, used when nothing else in the keymap applies; this makes it
1600 usable as a general function for probing keymaps. However, if the
1601 optional second argument ACCEPT-DEFAULT is non-nil, `key-binding' does
1602 recognize the default bindings, just as `read-key-sequence' does.
1604 Like the normal command loop, `key-binding' will remap the command
1605 resulting from looking up KEY by looking up the command in the
1606 current keymaps. However, if the optional third argument NO-REMAP
1607 is non-nil, `key-binding' returns the unmapped command.
1609 If KEY is a key sequence initiated with the mouse, the used keymaps
1610 will depend on the clicked mouse position with regard to the buffer
1611 and possible local keymaps on strings.
1613 If the optional argument POSITION is non-nil, it specifies a mouse
1614 position as returned by `event-start' and `event-end', and the lookup
1615 occurs in the keymaps associated with it instead of KEY. It can also
1616 be a number or marker, in which case the keymap properties at the
1617 specified buffer position instead of point are used.
1619 (Lisp_Object key
, Lisp_Object accept_default
, Lisp_Object no_remap
, Lisp_Object position
)
1623 if (NILP (position
) && VECTORP (key
))
1627 if (ASIZE (key
) == 0)
1630 /* mouse events may have a symbolic prefix indicating the
1631 scrollbar or mode line */
1632 event
= AREF (key
, SYMBOLP (AREF (key
, 0)) && ASIZE (key
) > 1 ? 1 : 0);
1634 /* We are not interested in locations without event data */
1636 if (EVENT_HAS_PARAMETERS (event
) && CONSP (XCDR (event
)))
1638 Lisp_Object kind
= EVENT_HEAD_KIND (EVENT_HEAD (event
));
1639 if (EQ (kind
, Qmouse_click
))
1640 position
= EVENT_START (event
);
1644 value
= Flookup_key (Fcons (Qkeymap
, Fcurrent_active_maps (Qt
, position
)),
1645 key
, accept_default
);
1647 if (NILP (value
) || INTEGERP (value
))
1650 /* If the result of the ordinary keymap lookup is an interactive
1651 command, look for a key binding (ie. remapping) for that command. */
1653 if (NILP (no_remap
) && SYMBOLP (value
))
1656 if (value1
= Fcommand_remapping (value
, position
, Qnil
), !NILP (value1
))
1663 /* GC is possible in this function if it autoloads a keymap. */
1665 DEFUN ("local-key-binding", Flocal_key_binding
, Slocal_key_binding
, 1, 2, 0,
1666 doc
: /* Return the binding for command KEYS in current local keymap only.
1667 KEYS is a string or vector, a sequence of keystrokes.
1668 The binding is probably a symbol with a function definition.
1670 If optional argument ACCEPT-DEFAULT is non-nil, recognize default
1671 bindings; see the description of `lookup-key' for more details about this. */)
1672 (Lisp_Object keys
, Lisp_Object accept_default
)
1674 register Lisp_Object map
;
1675 map
= BVAR (current_buffer
, keymap
);
1678 return Flookup_key (map
, keys
, accept_default
);
1681 /* GC is possible in this function if it autoloads a keymap. */
1683 DEFUN ("global-key-binding", Fglobal_key_binding
, Sglobal_key_binding
, 1, 2, 0,
1684 doc
: /* Return the binding for command KEYS in current global keymap only.
1685 KEYS is a string or vector, a sequence of keystrokes.
1686 The binding is probably a symbol with a function definition.
1687 This function's return values are the same as those of `lookup-key'
1690 If optional argument ACCEPT-DEFAULT is non-nil, recognize default
1691 bindings; see the description of `lookup-key' for more details about this. */)
1692 (Lisp_Object keys
, Lisp_Object accept_default
)
1694 return Flookup_key (current_global_map
, keys
, accept_default
);
1697 /* GC is possible in this function if it autoloads a keymap. */
1699 DEFUN ("minor-mode-key-binding", Fminor_mode_key_binding
, Sminor_mode_key_binding
, 1, 2, 0,
1700 doc
: /* Find the visible minor mode bindings of KEY.
1701 Return an alist of pairs (MODENAME . BINDING), where MODENAME is
1702 the symbol which names the minor mode binding KEY, and BINDING is
1703 KEY's definition in that mode. In particular, if KEY has no
1704 minor-mode bindings, return nil. If the first binding is a
1705 non-prefix, all subsequent bindings will be omitted, since they would
1706 be ignored. Similarly, the list doesn't include non-prefix bindings
1707 that come after prefix bindings.
1709 If optional argument ACCEPT-DEFAULT is non-nil, recognize default
1710 bindings; see the description of `lookup-key' for more details about this. */)
1711 (Lisp_Object key
, Lisp_Object accept_default
)
1713 Lisp_Object
*modes
, *maps
;
1715 Lisp_Object binding
;
1718 nmaps
= current_minor_maps (&modes
, &maps
);
1722 for (i
= j
= 0; i
< nmaps
; i
++)
1724 && !NILP (binding
= Flookup_key (maps
[i
], key
, accept_default
))
1725 && !INTEGERP (binding
))
1727 if (KEYMAPP (binding
))
1728 maps
[j
++] = Fcons (modes
[i
], binding
);
1730 return list1 (Fcons (modes
[i
], binding
));
1733 return Flist (j
, maps
);
1736 DEFUN ("define-prefix-command", Fdefine_prefix_command
, Sdefine_prefix_command
, 1, 3, 0,
1737 doc
: /* Define COMMAND as a prefix command. COMMAND should be a symbol.
1738 A new sparse keymap is stored as COMMAND's function definition and its value.
1739 If a second optional argument MAPVAR is given, the map is stored as
1740 its value instead of as COMMAND's value; but COMMAND is still defined
1742 The third optional argument NAME, if given, supplies a menu name
1743 string for the map. This is required to use the keymap as a menu.
1744 This function returns COMMAND. */)
1745 (Lisp_Object command
, Lisp_Object mapvar
, Lisp_Object name
)
1748 map
= Fmake_sparse_keymap (name
);
1749 Ffset (command
, map
);
1753 Fset (command
, map
);
1757 DEFUN ("use-global-map", Fuse_global_map
, Suse_global_map
, 1, 1, 0,
1758 doc
: /* Select KEYMAP as the global keymap. */)
1759 (Lisp_Object keymap
)
1761 keymap
= get_keymap (keymap
, 1, 1);
1762 current_global_map
= keymap
;
1767 DEFUN ("use-local-map", Fuse_local_map
, Suse_local_map
, 1, 1, 0,
1768 doc
: /* Select KEYMAP as the local keymap.
1769 If KEYMAP is nil, that means no local keymap. */)
1770 (Lisp_Object keymap
)
1773 keymap
= get_keymap (keymap
, 1, 1);
1775 bset_keymap (current_buffer
, keymap
);
1780 DEFUN ("current-local-map", Fcurrent_local_map
, Scurrent_local_map
, 0, 0, 0,
1781 doc
: /* Return current buffer's local keymap, or nil if it has none.
1782 Normally the local keymap is set by the major mode with `use-local-map'. */)
1785 return BVAR (current_buffer
, keymap
);
1788 DEFUN ("current-global-map", Fcurrent_global_map
, Scurrent_global_map
, 0, 0, 0,
1789 doc
: /* Return the current global keymap. */)
1792 return current_global_map
;
1795 DEFUN ("current-minor-mode-maps", Fcurrent_minor_mode_maps
, Scurrent_minor_mode_maps
, 0, 0, 0,
1796 doc
: /* Return a list of keymaps for the minor modes of the current buffer. */)
1800 int nmaps
= current_minor_maps (0, &maps
);
1802 return Flist (nmaps
, maps
);
1805 /* Help functions for describing and documenting keymaps. */
1807 struct accessible_keymaps_data
{
1808 Lisp_Object maps
, tail
, thisseq
;
1809 /* Does the current sequence end in the meta-prefix-char? */
1814 accessible_keymaps_1 (Lisp_Object key
, Lisp_Object cmd
, Lisp_Object args
, void *data
)
1815 /* Use void * data to be compatible with map_keymap_function_t. */
1817 struct accessible_keymaps_data
*d
= data
; /* Cast! */
1818 Lisp_Object maps
= d
->maps
;
1819 Lisp_Object tail
= d
->tail
;
1820 Lisp_Object thisseq
= d
->thisseq
;
1821 bool is_metized
= d
->is_metized
&& INTEGERP (key
);
1824 cmd
= get_keymap (get_keyelt (cmd
, 0), 0, 0);
1828 /* Look for and break cycles. */
1829 while (!NILP (tem
= Frassq (cmd
, maps
)))
1831 Lisp_Object prefix
= XCAR (tem
);
1832 ptrdiff_t lim
= XINT (Flength (XCAR (tem
)));
1833 if (lim
<= XINT (Flength (thisseq
)))
1834 { /* This keymap was already seen with a smaller prefix. */
1836 while (i
< lim
&& EQ (Faref (prefix
, make_number (i
)),
1837 Faref (thisseq
, make_number (i
))))
1840 /* `prefix' is a prefix of `thisseq' => there's a cycle. */
1843 /* This occurrence of `cmd' in `maps' does not correspond to a cycle,
1844 but maybe `cmd' occurs again further down in `maps', so keep
1846 maps
= XCDR (Fmemq (tem
, maps
));
1849 /* If the last key in thisseq is meta-prefix-char,
1850 turn it into a meta-ized keystroke. We know
1851 that the event we're about to append is an
1852 ascii keystroke since we're processing a
1856 int meta_bit
= meta_modifier
;
1857 Lisp_Object last
= make_number (XINT (Flength (thisseq
)) - 1);
1858 tem
= Fcopy_sequence (thisseq
);
1860 Faset (tem
, last
, make_number (XINT (key
) | meta_bit
));
1862 /* This new sequence is the same length as
1863 thisseq, so stick it in the list right
1866 Fcons (Fcons (tem
, cmd
), XCDR (tail
)));
1870 tem
= append_key (thisseq
, key
);
1871 nconc2 (tail
, list1 (Fcons (tem
, cmd
)));
1875 /* This function cannot GC. */
1877 DEFUN ("accessible-keymaps", Faccessible_keymaps
, Saccessible_keymaps
,
1879 doc
: /* Find all keymaps accessible via prefix characters from KEYMAP.
1880 Returns a list of elements of the form (KEYS . MAP), where the sequence
1881 KEYS starting from KEYMAP gets you to MAP. These elements are ordered
1882 so that the KEYS increase in length. The first element is ([] . KEYMAP).
1883 An optional argument PREFIX, if non-nil, should be a key sequence;
1884 then the value includes only maps for prefixes that start with PREFIX. */)
1885 (Lisp_Object keymap
, Lisp_Object prefix
)
1887 Lisp_Object maps
, tail
;
1888 EMACS_INT prefixlen
= XFASTINT (Flength (prefix
));
1892 /* If a prefix was specified, start with the keymap (if any) for
1893 that prefix, so we don't waste time considering other prefixes. */
1895 tem
= Flookup_key (keymap
, prefix
, Qt
);
1896 /* Flookup_key may give us nil, or a number,
1897 if the prefix is not defined in this particular map.
1898 It might even give us a list that isn't a keymap. */
1899 tem
= get_keymap (tem
, 0, 0);
1900 /* If the keymap is autoloaded `tem' is not a cons-cell, but we still
1901 want to return it. */
1904 /* Convert PREFIX to a vector now, so that later on
1905 we don't have to deal with the possibility of a string. */
1906 if (STRINGP (prefix
))
1911 copy
= Fmake_vector (make_number (SCHARS (prefix
)), Qnil
);
1912 for (i
= 0, i_byte
= 0; i
< SCHARS (prefix
);)
1916 FETCH_STRING_CHAR_ADVANCE (c
, prefix
, i
, i_byte
);
1917 if (SINGLE_BYTE_CHAR_P (c
) && (c
& 0200))
1918 c
^= 0200 | meta_modifier
;
1919 ASET (copy
, i_before
, make_number (c
));
1923 maps
= list1 (Fcons (prefix
, tem
));
1929 maps
= list1 (Fcons (zero_vector
, get_keymap (keymap
, 1, 0)));
1931 /* For each map in the list maps,
1932 look at any other maps it points to,
1933 and stick them at the end if they are not already in the list.
1935 This is a breadth-first traversal, where tail is the queue of
1936 nodes, and maps accumulates a list of all nodes visited. */
1938 for (tail
= maps
; CONSP (tail
); tail
= XCDR (tail
))
1940 struct accessible_keymaps_data data
;
1941 register Lisp_Object thismap
= Fcdr (XCAR (tail
));
1944 data
.thisseq
= Fcar (XCAR (tail
));
1947 last
= make_number (XINT (Flength (data
.thisseq
)) - 1);
1948 /* Does the current sequence end in the meta-prefix-char? */
1949 data
.is_metized
= (XINT (last
) >= 0
1950 /* Don't metize the last char of PREFIX. */
1951 && XINT (last
) >= prefixlen
1952 && EQ (Faref (data
.thisseq
, last
), meta_prefix_char
));
1954 /* Since we can't run lisp code, we can't scan autoloaded maps. */
1955 if (CONSP (thismap
))
1956 map_keymap (thismap
, accessible_keymaps_1
, Qnil
, &data
, 0);
1961 /* This function cannot GC. */
1963 DEFUN ("key-description", Fkey_description
, Skey_description
, 1, 2, 0,
1964 doc
: /* Return a pretty description of key-sequence KEYS.
1965 Optional arg PREFIX is the sequence of keys leading up to KEYS.
1966 For example, [?\C-x ?l] is converted into the string \"C-x l\".
1968 For an approximate inverse of this, see `kbd'. */)
1969 (Lisp_Object keys
, Lisp_Object prefix
)
1975 EMACS_INT size
= XINT (Flength (keys
));
1977 Lisp_Object sep
= build_string (" ");
1984 size
+= XINT (Flength (prefix
));
1986 /* This has one extra element at the end that we don't pass to Fconcat. */
1988 if (INT_MULTIPLY_WRAPV (size
, 4, &size4
))
1989 memory_full (SIZE_MAX
);
1990 SAFE_ALLOCA_LISP (args
, size4
);
1992 /* In effect, this computes
1993 (mapconcat 'single-key-description keys " ")
1994 but we shouldn't use mapconcat because it can do GC. */
1998 list
= prefix
, prefix
= Qnil
;
1999 else if (!NILP (keys
))
2000 list
= keys
, keys
= Qnil
;
2005 args
[len
] = Fsingle_key_description (meta_prefix_char
, Qnil
);
2006 result
= Fconcat (len
+ 1, args
);
2009 result
= empty_unibyte_string
;
2011 result
= Fconcat (len
- 1, args
);
2017 size
= SCHARS (list
);
2018 else if (VECTORP (list
))
2019 size
= ASIZE (list
);
2020 else if (CONSP (list
))
2021 size
= XINT (Flength (list
));
2023 wrong_type_argument (Qarrayp
, list
);
2032 FETCH_STRING_CHAR_ADVANCE (c
, list
, i
, i_byte
);
2033 if (SINGLE_BYTE_CHAR_P (c
) && (c
& 0200))
2034 c
^= 0200 | meta_modifier
;
2035 XSETFASTINT (key
, c
);
2037 else if (VECTORP (list
))
2039 key
= AREF (list
, i
); i
++;
2051 || EQ (key
, meta_prefix_char
)
2052 || (XINT (key
) & meta_modifier
))
2054 args
[len
++] = Fsingle_key_description (meta_prefix_char
, Qnil
);
2056 if (EQ (key
, meta_prefix_char
))
2060 XSETINT (key
, XINT (key
) | meta_modifier
);
2063 else if (EQ (key
, meta_prefix_char
))
2068 args
[len
++] = Fsingle_key_description (key
, Qnil
);
2076 push_key_description (EMACS_INT ch
, char *p
)
2081 /* Clear all the meaningless bits above the meta bit. */
2082 c
= ch
& (meta_modifier
| ~ - meta_modifier
);
2083 c2
= c
& ~(alt_modifier
| ctrl_modifier
| hyper_modifier
2084 | meta_modifier
| shift_modifier
| super_modifier
);
2086 if (! CHARACTERP (make_number (c2
)))
2088 /* KEY_DESCRIPTION_SIZE is large enough for this. */
2089 p
+= sprintf (p
, "[%d]", c
);
2093 tab_as_ci
= (c2
== '\t' && (c
& meta_modifier
));
2095 if (c
& alt_modifier
)
2101 if ((c
& ctrl_modifier
) != 0
2102 || (c2
< ' ' && c2
!= 27 && c2
!= '\t' && c2
!= Ctl ('M'))
2107 c
&= ~ctrl_modifier
;
2109 if (c
& hyper_modifier
)
2113 c
-= hyper_modifier
;
2115 if (c
& meta_modifier
)
2121 if (c
& shift_modifier
)
2125 c
-= shift_modifier
;
2127 if (c
& super_modifier
)
2131 c
-= super_modifier
;
2151 else if (c
== Ctl ('M'))
2159 /* `C-' already added above. */
2160 if (c
> 0 && c
<= Ctl ('Z'))
2182 /* Now we are sure that C is a valid character code. */
2183 p
+= CHAR_STRING (c
, (unsigned char *) p
);
2189 /* This function cannot GC. */
2191 DEFUN ("single-key-description", Fsingle_key_description
,
2192 Ssingle_key_description
, 1, 2, 0,
2193 doc
: /* Return a pretty description of command character KEY.
2194 Control characters turn into C-whatever, etc.
2195 Optional argument NO-ANGLES non-nil means don't put angle brackets
2196 around function keys and event symbols. */)
2197 (Lisp_Object key
, Lisp_Object no_angles
)
2201 if (CONSP (key
) && lucid_event_type_list_p (key
))
2202 key
= Fevent_convert_list (key
);
2204 if (CONSP (key
) && INTEGERP (XCAR (key
)) && INTEGERP (XCDR (key
)))
2205 /* An interval from a map-char-table. */
2207 AUTO_STRING (dot_dot
, "..");
2208 return concat3 (Fsingle_key_description (XCAR (key
), no_angles
),
2210 Fsingle_key_description (XCDR (key
), no_angles
));
2213 key
= EVENT_HEAD (key
);
2215 if (INTEGERP (key
)) /* Normal character. */
2217 char tem
[KEY_DESCRIPTION_SIZE
];
2218 char *p
= push_key_description (XINT (key
), tem
);
2220 return make_specified_string (tem
, -1, p
- tem
, 1);
2222 else if (SYMBOLP (key
)) /* Function key or event-symbol. */
2224 if (NILP (no_angles
))
2227 char *buffer
= SAFE_ALLOCA (sizeof "<>"
2228 + SBYTES (SYMBOL_NAME (key
)));
2229 esprintf (buffer
, "<%s>", SDATA (SYMBOL_NAME (key
)));
2230 result
= build_string (buffer
);
2235 return Fsymbol_name (key
);
2237 else if (STRINGP (key
)) /* Buffer names in the menubar. */
2238 return Fcopy_sequence (key
);
2240 error ("KEY must be an integer, cons, symbol, or string");
2244 push_text_char_description (register unsigned int c
, register char *p
)
2255 *p
++ = c
+ 64; /* 'A' - 1 */
2267 /* This function cannot GC. */
2269 DEFUN ("text-char-description", Ftext_char_description
, Stext_char_description
, 1, 1, 0,
2270 doc
: /* Return a pretty description of file-character CHARACTER.
2271 Control characters turn into "^char", etc. This differs from
2272 `single-key-description' which turns them into "C-char".
2273 Also, this function recognizes the 2**7 bit as the Meta character,
2274 whereas `single-key-description' uses the 2**27 bit for Meta.
2275 See Info node `(elisp)Describing Characters' for examples. */)
2276 (Lisp_Object character
)
2278 /* Currently MAX_MULTIBYTE_LENGTH is 4 (< 6). */
2282 CHECK_CHARACTER (character
);
2284 c
= XINT (character
);
2285 if (!ASCII_CHAR_P (c
))
2287 int len
= CHAR_STRING (c
, (unsigned char *) str
);
2289 return make_multibyte_string (str
, 1, len
);
2292 *push_text_char_description (c
& 0377, str
) = 0;
2294 return build_string (str
);
2297 static int where_is_preferred_modifier
;
2299 /* Return 0 if SEQ uses non-preferred modifiers or non-char events.
2300 Else, return 2 if SEQ uses the where_is_preferred_modifier,
2303 preferred_sequence_p (Lisp_Object seq
)
2306 EMACS_INT len
= XFASTINT (Flength (seq
));
2309 for (i
= 0; i
< len
; i
++)
2311 Lisp_Object ii
, elt
;
2313 XSETFASTINT (ii
, i
);
2314 elt
= Faref (seq
, ii
);
2316 if (!INTEGERP (elt
))
2320 int modifiers
= XINT (elt
) & (CHAR_MODIFIER_MASK
& ~CHAR_META
);
2321 if (modifiers
== where_is_preferred_modifier
)
2332 /* where-is - finding a command in a set of keymaps. */
2334 static void where_is_internal_1 (Lisp_Object key
, Lisp_Object binding
,
2335 Lisp_Object args
, void *data
);
2337 /* Like Flookup_key, but uses a list of keymaps SHADOW instead of a single map.
2338 Returns the first non-nil binding found in any of those maps.
2339 If REMAP is true, pass the result of the lookup through command
2340 remapping before returning it. */
2343 shadow_lookup (Lisp_Object shadow
, Lisp_Object key
, Lisp_Object flag
,
2346 Lisp_Object tail
, value
;
2348 for (tail
= shadow
; CONSP (tail
); tail
= XCDR (tail
))
2350 value
= Flookup_key (XCAR (tail
), key
, flag
);
2351 if (NATNUMP (value
))
2353 value
= Flookup_key (XCAR (tail
),
2354 Fsubstring (key
, make_number (0), value
), flag
);
2358 else if (!NILP (value
))
2360 Lisp_Object remapping
;
2361 if (remap
&& SYMBOLP (value
)
2362 && (remapping
= Fcommand_remapping (value
, Qnil
, shadow
),
2372 static Lisp_Object Vmouse_events
;
2374 struct where_is_internal_data
{
2375 Lisp_Object definition
, this, last
;
2376 bool last_is_meta
, noindirect
;
2377 Lisp_Object sequences
;
2380 /* This function can't GC, AFAIK. */
2381 /* Return the list of bindings found. This list is ordered "longest
2382 to shortest". It may include bindings that are actually shadowed
2383 by others, as well as duplicate bindings and remapping bindings.
2384 The list returned is potentially shared with where_is_cache, so
2385 be careful not to modify it via side-effects. */
2388 where_is_internal (Lisp_Object definition
, Lisp_Object keymaps
,
2389 bool noindirect
, bool nomenus
)
2391 Lisp_Object maps
= Qnil
;
2393 struct where_is_internal_data data
;
2395 /* Only important use of caching is for the menubar
2396 (i.e. where-is-internal called with (def nil t nil nil)). */
2397 if (nomenus
&& !noindirect
)
2399 /* Check heuristic-consistency of the cache. */
2400 if (NILP (Fequal (keymaps
, where_is_cache_keymaps
)))
2401 where_is_cache
= Qnil
;
2403 if (NILP (where_is_cache
))
2405 /* We need to create the cache. */
2406 where_is_cache
= Fmake_hash_table (0, NULL
);
2407 where_is_cache_keymaps
= Qt
;
2410 /* We can reuse the cache. */
2411 return Fgethash (definition
, where_is_cache
, Qnil
);
2414 /* Kill the cache so that where_is_internal_1 doesn't think
2415 we're filling it up. */
2416 where_is_cache
= Qnil
;
2419 while (CONSP (found
))
2423 Faccessible_keymaps (get_keymap (XCAR (found
), 1, 0), Qnil
));
2424 found
= XCDR (found
);
2427 data
.sequences
= Qnil
;
2428 for (; CONSP (maps
); maps
= XCDR (maps
))
2430 /* Key sequence to reach map, and the map that it reaches */
2431 register Lisp_Object
this, map
, tem
;
2433 /* In order to fold [META-PREFIX-CHAR CHAR] sequences into
2434 [M-CHAR] sequences, check if last character of the sequence
2435 is the meta-prefix char. */
2439 this = Fcar (XCAR (maps
));
2440 map
= Fcdr (XCAR (maps
));
2441 last
= make_number (XINT (Flength (this)) - 1);
2442 last_is_meta
= (XINT (last
) >= 0
2443 && EQ (Faref (this, last
), meta_prefix_char
));
2445 /* if (nomenus && !preferred_sequence_p (this)) */
2446 if (nomenus
&& XINT (last
) >= 0
2447 && SYMBOLP (tem
= Faref (this, make_number (0)))
2448 && !NILP (Fmemq (XCAR (parse_modifiers (tem
)), Vmouse_events
)))
2449 /* If no menu entries should be returned, skip over the
2450 keymaps bound to `menu-bar' and `tool-bar' and other
2451 non-ascii prefixes like `C-down-mouse-2'. */
2456 data
.definition
= definition
;
2457 data
.noindirect
= noindirect
;
2460 data
.last_is_meta
= last_is_meta
;
2463 map_keymap (map
, where_is_internal_1
, Qnil
, &data
, 0);
2466 if (nomenus
&& !noindirect
)
2467 { /* Remember for which keymaps this cache was built.
2468 We do it here (late) because we want to keep where_is_cache_keymaps
2469 set to t while the cache isn't fully filled. */
2470 where_is_cache_keymaps
= keymaps
;
2471 /* During cache-filling, data.sequences is not filled by
2472 where_is_internal_1. */
2473 return Fgethash (definition
, where_is_cache
, Qnil
);
2476 return data
.sequences
;
2479 /* This function can GC if Flookup_key autoloads any keymaps. */
2481 DEFUN ("where-is-internal", Fwhere_is_internal
, Swhere_is_internal
, 1, 5, 0,
2482 doc
: /* Return list of keys that invoke DEFINITION.
2483 If KEYMAP is a keymap, search only KEYMAP and the global keymap.
2484 If KEYMAP is nil, search all the currently active keymaps, except
2485 for `overriding-local-map' (which is ignored).
2486 If KEYMAP is a list of keymaps, search only those keymaps.
2488 If optional 3rd arg FIRSTONLY is non-nil, return the first key sequence found,
2489 rather than a list of all possible key sequences.
2490 If FIRSTONLY is the symbol `non-ascii', return the first binding found,
2491 no matter what it is.
2492 If FIRSTONLY has another non-nil value, prefer bindings
2493 that use the modifier key specified in `where-is-preferred-modifier'
2494 (or their meta variants) and entirely reject menu bindings.
2496 If optional 4th arg NOINDIRECT is non-nil, don't extract the commands inside
2497 menu-items. This makes it possible to search for a menu-item itself.
2499 The optional 5th arg NO-REMAP alters how command remapping is handled:
2501 - If another command OTHER-COMMAND is remapped to DEFINITION, normally
2502 search for the bindings of OTHER-COMMAND and include them in the
2503 returned list. But if NO-REMAP is non-nil, include the vector
2504 [remap OTHER-COMMAND] in the returned list instead, without
2505 searching for those other bindings.
2507 - If DEFINITION is remapped to OTHER-COMMAND, normally return the
2508 bindings for OTHER-COMMAND. But if NO-REMAP is non-nil, return the
2509 bindings for DEFINITION instead, ignoring its remapping. */)
2510 (Lisp_Object definition
, Lisp_Object keymap
, Lisp_Object firstonly
, Lisp_Object noindirect
, Lisp_Object no_remap
)
2512 /* The keymaps in which to search. */
2513 Lisp_Object keymaps
;
2514 /* Potentially relevant bindings in "shortest to longest" order. */
2515 Lisp_Object sequences
= Qnil
;
2516 /* Actually relevant bindings. */
2517 Lisp_Object found
= Qnil
;
2518 /* 1 means ignore all menu bindings entirely. */
2519 bool nomenus
= !NILP (firstonly
) && !EQ (firstonly
, Qnon_ascii
);
2520 /* List of sequences found via remapping. Keep them in a separate
2521 variable, so as to push them later, since we prefer
2522 non-remapped binding. */
2523 Lisp_Object remapped_sequences
= Qnil
;
2524 /* Whether or not we're handling remapped sequences. This is needed
2525 because remapping is not done recursively by Fcommand_remapping: you
2526 can't remap a remapped command. */
2528 Lisp_Object tem
= Qnil
;
2530 /* Refresh the C version of the modifier preference. */
2531 where_is_preferred_modifier
2532 = parse_solitary_modifier (Vwhere_is_preferred_modifier
);
2534 /* Find the relevant keymaps. */
2535 if (CONSP (keymap
) && KEYMAPP (XCAR (keymap
)))
2537 else if (!NILP (keymap
))
2538 keymaps
= list2 (keymap
, current_global_map
);
2540 keymaps
= Fcurrent_active_maps (Qnil
, Qnil
);
2542 tem
= Fcommand_remapping (definition
, Qnil
, keymaps
);
2543 /* If `definition' is remapped to tem', then OT1H no key will run
2544 that command (since they will run `tem' instead), so we should
2545 return nil; but OTOH all keys bound to `definition' (or to `tem')
2546 will run the same command.
2547 So for menu-shortcut purposes, we want to find all the keys bound (maybe
2548 via remapping) to `tem'. But for the purpose of finding the keys that
2549 run `definition', then we'd want to just return nil.
2550 We choose to make it work right for menu-shortcuts, since it's the most
2552 Known bugs: if you remap switch-to-buffer to toto, C-h f switch-to-buffer
2553 will tell you that switch-to-buffer is bound to C-x b even though C-x b
2554 will run toto instead. And if `toto' is itself remapped to forward-char,
2555 then C-h f toto will tell you that it's bound to C-f even though C-f does
2556 not run toto and it won't tell you that C-x b does run toto. */
2557 if (NILP (no_remap
) && !NILP (tem
))
2560 if (SYMBOLP (definition
)
2561 && !NILP (firstonly
)
2562 && !NILP (tem
= Fget (definition
, QCadvertised_binding
)))
2564 /* We have a list of advertised bindings. */
2566 if (EQ (shadow_lookup (keymaps
, XCAR (tem
), Qnil
, 0), definition
))
2570 if (EQ (shadow_lookup (keymaps
, tem
, Qnil
, 0), definition
))
2574 sequences
= Freverse (where_is_internal (definition
, keymaps
,
2575 !NILP (noindirect
), nomenus
));
2577 while (CONSP (sequences
)
2578 /* If we're at the end of the `sequences' list and we haven't
2579 considered remapped sequences yet, copy them over and
2581 || (!remapped
&& (sequences
= remapped_sequences
,
2583 CONSP (sequences
))))
2585 Lisp_Object sequence
, function
;
2587 sequence
= XCAR (sequences
);
2588 sequences
= XCDR (sequences
);
2590 /* Verify that this key binding is not shadowed by another
2591 binding for the same key, before we say it exists.
2593 Mechanism: look for local definition of this key and if
2594 it is defined and does not match what we found then
2597 Either nil or number as value from Flookup_key
2599 if (NILP (Fequal (shadow_lookup (keymaps
, sequence
, Qnil
, remapped
),
2603 /* If the current sequence is a command remapping with
2604 format [remap COMMAND], find the key sequences
2605 which run COMMAND, and use those sequences instead. */
2606 if (NILP (no_remap
) && !remapped
2607 && VECTORP (sequence
) && ASIZE (sequence
) == 2
2608 && EQ (AREF (sequence
, 0), Qremap
)
2609 && (function
= AREF (sequence
, 1), SYMBOLP (function
)))
2611 Lisp_Object seqs
= where_is_internal (function
, keymaps
,
2612 !NILP (noindirect
), nomenus
);
2613 remapped_sequences
= nconc2 (Freverse (seqs
), remapped_sequences
);
2617 /* Don't annoy user with strings from a menu such as the
2618 entries from the "Edit => Paste from Kill Menu".
2619 Change them all to "(any string)", so that there
2620 seems to be only one menu item to report. */
2621 if (! NILP (sequence
))
2624 tem1
= Faref (sequence
, make_number (ASIZE (sequence
) - 1));
2626 Faset (sequence
, make_number (ASIZE (sequence
) - 1),
2627 build_string ("(any string)"));
2630 /* It is a true unshadowed match. Record it, unless it's already
2631 been seen (as could happen when inheriting keymaps). */
2632 if (NILP (Fmember (sequence
, found
)))
2633 found
= Fcons (sequence
, found
);
2635 /* If firstonly is Qnon_ascii, then we can return the first
2636 binding we find. If firstonly is not Qnon_ascii but not
2637 nil, then we should return the first ascii-only binding
2639 if (EQ (firstonly
, Qnon_ascii
))
2641 else if (!NILP (firstonly
)
2642 && 2 == preferred_sequence_p (sequence
))
2646 found
= Fnreverse (found
);
2648 /* firstonly may have been t, but we may have gone all the way through
2649 the keymaps without finding an all-ASCII key sequence. So just
2650 return the best we could find. */
2651 if (NILP (firstonly
))
2653 else if (where_is_preferred_modifier
== 0)
2654 return Fcar (found
);
2656 { /* Maybe we did not find a preferred_modifier binding, but we did find
2657 some ASCII binding. */
2658 Lisp_Object bindings
= found
;
2659 while (CONSP (bindings
))
2660 if (preferred_sequence_p (XCAR (bindings
)))
2661 return XCAR (bindings
);
2663 bindings
= XCDR (bindings
);
2664 return Fcar (found
);
2668 /* This function can GC because get_keyelt can. */
2671 where_is_internal_1 (Lisp_Object key
, Lisp_Object binding
, Lisp_Object args
, void *data
)
2673 struct where_is_internal_data
*d
= data
; /* Cast! */
2674 Lisp_Object definition
= d
->definition
;
2675 bool noindirect
= d
->noindirect
;
2676 Lisp_Object
this = d
->this;
2677 Lisp_Object last
= d
->last
;
2678 bool last_is_meta
= d
->last_is_meta
;
2679 Lisp_Object sequence
;
2681 /* Search through indirections unless that's not wanted. */
2683 binding
= get_keyelt (binding
, 0);
2685 /* End this iteration if this element does not match
2688 if (!(!NILP (where_is_cache
) /* everything "matches" during cache-fill. */
2689 || EQ (binding
, definition
)
2690 || (CONSP (definition
) && !NILP (Fequal (binding
, definition
)))))
2691 /* Doesn't match. */
2694 /* We have found a match. Construct the key sequence where we found it. */
2695 if (INTEGERP (key
) && last_is_meta
)
2697 sequence
= Fcopy_sequence (this);
2698 Faset (sequence
, last
, make_number (XINT (key
) | meta_modifier
));
2703 key
= Fcons (XCAR (key
), XCDR (key
));
2704 sequence
= append_key (this, key
);
2707 if (!NILP (where_is_cache
))
2709 Lisp_Object sequences
= Fgethash (binding
, where_is_cache
, Qnil
);
2710 Fputhash (binding
, Fcons (sequence
, sequences
), where_is_cache
);
2713 d
->sequences
= Fcons (sequence
, d
->sequences
);
2716 /* describe-bindings - summarizing all the bindings in a set of keymaps. */
2718 DEFUN ("describe-buffer-bindings", Fdescribe_buffer_bindings
, Sdescribe_buffer_bindings
, 1, 3, 0,
2719 doc
: /* Insert the list of all defined keys and their definitions.
2720 The list is inserted in the current buffer, while the bindings are
2721 looked up in BUFFER.
2722 The optional argument PREFIX, if non-nil, should be a key sequence;
2723 then we display only bindings that start with that prefix.
2724 The optional argument MENUS, if non-nil, says to mention menu bindings.
2725 (Ordinarily these are omitted from the output.) */)
2726 (Lisp_Object buffer
, Lisp_Object prefix
, Lisp_Object menus
)
2728 Lisp_Object outbuf
, shadow
;
2729 bool nomenu
= NILP (menus
);
2732 const char *alternate_heading
2734 Keyboard translations:\n\n\
2735 You type Translation\n\
2736 -------- -----------\n";
2738 CHECK_BUFFER (buffer
);
2741 outbuf
= Fcurrent_buffer ();
2743 /* Report on alternates for keys. */
2744 if (STRINGP (KVAR (current_kboard
, Vkeyboard_translate_table
)) && !NILP (prefix
))
2747 const unsigned char *translate
= SDATA (KVAR (current_kboard
, Vkeyboard_translate_table
));
2748 int translate_len
= SCHARS (KVAR (current_kboard
, Vkeyboard_translate_table
));
2750 for (c
= 0; c
< translate_len
; c
++)
2751 if (translate
[c
] != c
)
2753 char buf
[KEY_DESCRIPTION_SIZE
];
2756 if (alternate_heading
)
2758 insert_string (alternate_heading
);
2759 alternate_heading
= 0;
2762 bufend
= push_key_description (translate
[c
], buf
);
2763 insert (buf
, bufend
- buf
);
2764 Findent_to (make_number (16), make_number (1));
2765 bufend
= push_key_description (c
, buf
);
2766 insert (buf
, bufend
- buf
);
2770 /* Insert calls signal_after_change which may GC. */
2771 translate
= SDATA (KVAR (current_kboard
, Vkeyboard_translate_table
));
2777 if (!NILP (Vkey_translation_map
))
2778 describe_map_tree (Vkey_translation_map
, 0, Qnil
, prefix
,
2779 "Key translations", nomenu
, 1, 0, 0);
2782 /* Print the (major mode) local map. */
2784 if (!NILP (KVAR (current_kboard
, Voverriding_terminal_local_map
)))
2785 start1
= KVAR (current_kboard
, Voverriding_terminal_local_map
);
2789 describe_map_tree (start1
, 1, shadow
, prefix
,
2790 "\f\nOverriding Bindings", nomenu
, 0, 0, 0);
2791 shadow
= Fcons (start1
, shadow
);
2794 else if (!NILP (Voverriding_local_map
))
2795 start1
= Voverriding_local_map
;
2799 describe_map_tree (start1
, 1, shadow
, prefix
,
2800 "\f\nOverriding Bindings", nomenu
, 0, 0, 0);
2801 shadow
= Fcons (start1
, shadow
);
2805 /* Print the minor mode and major mode keymaps. */
2807 Lisp_Object
*modes
, *maps
;
2809 /* Temporarily switch to `buffer', so that we can get that buffer's
2810 minor modes correctly. */
2811 Fset_buffer (buffer
);
2813 nmaps
= current_minor_maps (&modes
, &maps
);
2814 Fset_buffer (outbuf
);
2816 start1
= get_local_map (BUF_PT (XBUFFER (buffer
)),
2817 XBUFFER (buffer
), Qkeymap
);
2820 describe_map_tree (start1
, 1, shadow
, prefix
,
2821 "\f\n`keymap' Property Bindings", nomenu
,
2823 shadow
= Fcons (start1
, shadow
);
2826 /* Print the minor mode maps. */
2827 for (i
= 0; i
< nmaps
; i
++)
2829 /* The title for a minor mode keymap
2830 is constructed at run time.
2831 We let describe_map_tree do the actual insertion
2832 because it takes care of other features when doing so. */
2835 if (!SYMBOLP (modes
[i
]))
2839 p
= title
= SAFE_ALLOCA (42 + SBYTES (SYMBOL_NAME (modes
[i
])));
2843 memcpy (p
, SDATA (SYMBOL_NAME (modes
[i
])),
2844 SBYTES (SYMBOL_NAME (modes
[i
])));
2845 p
+= SBYTES (SYMBOL_NAME (modes
[i
]));
2847 memcpy (p
, " Minor Mode Bindings", strlen (" Minor Mode Bindings"));
2848 p
+= strlen (" Minor Mode Bindings");
2851 describe_map_tree (maps
[i
], 1, shadow
, prefix
,
2852 title
, nomenu
, 0, 0, 0);
2853 shadow
= Fcons (maps
[i
], shadow
);
2857 start1
= get_local_map (BUF_PT (XBUFFER (buffer
)),
2858 XBUFFER (buffer
), Qlocal_map
);
2861 if (EQ (start1
, BVAR (XBUFFER (buffer
), keymap
)))
2862 describe_map_tree (start1
, 1, shadow
, prefix
,
2863 "\f\nMajor Mode Bindings", nomenu
, 0, 0, 0);
2865 describe_map_tree (start1
, 1, shadow
, prefix
,
2866 "\f\n`local-map' Property Bindings",
2869 shadow
= Fcons (start1
, shadow
);
2873 describe_map_tree (current_global_map
, 1, shadow
, prefix
,
2874 "\f\nGlobal Bindings", nomenu
, 0, 1, 0);
2876 /* Print the function-key-map translations under this prefix. */
2877 if (!NILP (KVAR (current_kboard
, Vlocal_function_key_map
)))
2878 describe_map_tree (KVAR (current_kboard
, Vlocal_function_key_map
), 0, Qnil
, prefix
,
2879 "\f\nFunction key map translations", nomenu
, 1, 0, 0);
2881 /* Print the input-decode-map translations under this prefix. */
2882 if (!NILP (KVAR (current_kboard
, Vinput_decode_map
)))
2883 describe_map_tree (KVAR (current_kboard
, Vinput_decode_map
), 0, Qnil
, prefix
,
2884 "\f\nInput decoding map translations", nomenu
, 1, 0, 0);
2889 /* Insert a description of the key bindings in STARTMAP,
2890 followed by those of all maps reachable through STARTMAP.
2891 If PARTIAL, omit certain "uninteresting" commands
2892 (such as `undefined').
2893 If SHADOW is non-nil, it is a list of maps;
2894 don't mention keys which would be shadowed by any of them.
2895 PREFIX, if non-nil, says mention only keys that start with PREFIX.
2896 TITLE, if not 0, is a string to insert at the beginning.
2897 TITLE should not end with a colon or a newline; we supply that.
2898 If NOMENU, then omit menu-bar commands.
2900 If TRANSL, the definitions are actually key translations
2901 so print strings and vectors differently.
2903 If ALWAYS_TITLE, print the title even if there are no maps
2906 If MENTION_SHADOW, then when something is shadowed by SHADOW,
2907 don't omit it; instead, mention it but say it is shadowed.
2909 Any inserted text ends in two newlines (used by `help-make-xrefs'). */
2912 describe_map_tree (Lisp_Object startmap
, bool partial
, Lisp_Object shadow
,
2913 Lisp_Object prefix
, const char *title
, bool nomenu
,
2914 bool transl
, bool always_title
, bool mention_shadow
)
2916 Lisp_Object maps
, orig_maps
, seen
, sub_shadows
;
2918 const char *key_heading
2923 orig_maps
= maps
= Faccessible_keymaps (startmap
, prefix
);
2931 /* Delete from MAPS each element that is for the menu bar. */
2932 for (list
= maps
; CONSP (list
); list
= XCDR (list
))
2934 Lisp_Object elt
, elt_prefix
, tem
;
2937 elt_prefix
= Fcar (elt
);
2938 if (ASIZE (elt_prefix
) >= 1)
2940 tem
= Faref (elt_prefix
, make_number (0));
2941 if (EQ (tem
, Qmenu_bar
))
2942 maps
= Fdelq (elt
, maps
);
2947 if (!NILP (maps
) || always_title
)
2951 insert_string (title
);
2954 insert_string (" Starting With ");
2955 insert1 (Fkey_description (prefix
, Qnil
));
2957 insert_string (":\n");
2959 insert_string (key_heading
);
2963 for (; CONSP (maps
); maps
= XCDR (maps
))
2965 register Lisp_Object elt
, elt_prefix
, tail
;
2968 elt_prefix
= Fcar (elt
);
2972 for (tail
= shadow
; CONSP (tail
); tail
= XCDR (tail
))
2976 shmap
= XCAR (tail
);
2978 /* If the sequence by which we reach this keymap is zero-length,
2979 then the shadow map for this keymap is just SHADOW. */
2980 if ((STRINGP (elt_prefix
) && SCHARS (elt_prefix
) == 0)
2981 || (VECTORP (elt_prefix
) && ASIZE (elt_prefix
) == 0))
2983 /* If the sequence by which we reach this keymap actually has
2984 some elements, then the sequence's definition in SHADOW is
2985 what we should use. */
2988 shmap
= Flookup_key (shmap
, Fcar (elt
), Qt
);
2989 if (INTEGERP (shmap
))
2993 /* If shmap is not nil and not a keymap,
2994 it completely shadows this map, so don't
2995 describe this map at all. */
2996 if (!NILP (shmap
) && !KEYMAPP (shmap
))
3000 sub_shadows
= Fcons (shmap
, sub_shadows
);
3003 /* Maps we have already listed in this loop shadow this map. */
3004 for (tail
= orig_maps
; !EQ (tail
, maps
); tail
= XCDR (tail
))
3007 tem
= Fequal (Fcar (XCAR (tail
)), elt_prefix
);
3009 sub_shadows
= Fcons (XCDR (XCAR (tail
)), sub_shadows
);
3012 describe_map (Fcdr (elt
), elt_prefix
,
3013 transl
? describe_translation
: describe_command
,
3014 partial
, sub_shadows
, &seen
, nomenu
, mention_shadow
);
3020 insert_string ("\n");
3023 static int previous_description_column
;
3026 describe_command (Lisp_Object definition
, Lisp_Object args
)
3028 register Lisp_Object tem1
;
3029 ptrdiff_t column
= current_column ();
3030 int description_column
;
3032 /* If column 16 is no good, go to col 32;
3033 but don't push beyond that--go to next line instead. */
3037 description_column
= 32;
3039 else if (column
> 14 || (column
> 10 && previous_description_column
== 32))
3040 description_column
= 32;
3042 description_column
= 16;
3044 Findent_to (make_number (description_column
), make_number (1));
3045 previous_description_column
= description_column
;
3047 if (SYMBOLP (definition
))
3049 tem1
= SYMBOL_NAME (definition
);
3051 insert_string ("\n");
3053 else if (STRINGP (definition
) || VECTORP (definition
))
3054 insert_string ("Keyboard Macro\n");
3055 else if (KEYMAPP (definition
))
3056 insert_string ("Prefix Command\n");
3058 insert_string ("??\n");
3062 describe_translation (Lisp_Object definition
, Lisp_Object args
)
3064 register Lisp_Object tem1
;
3066 Findent_to (make_number (16), make_number (1));
3068 if (SYMBOLP (definition
))
3070 tem1
= SYMBOL_NAME (definition
);
3072 insert_string ("\n");
3074 else if (STRINGP (definition
) || VECTORP (definition
))
3076 insert1 (Fkey_description (definition
, Qnil
));
3077 insert_string ("\n");
3079 else if (KEYMAPP (definition
))
3080 insert_string ("Prefix Command\n");
3082 insert_string ("??\n");
3085 /* describe_map puts all the usable elements of a sparse keymap
3086 into an array of `struct describe_map_elt',
3087 then sorts them by the events. */
3089 struct describe_map_elt
3092 Lisp_Object definition
;
3096 /* qsort comparison function for sorting `struct describe_map_elt' by
3100 describe_map_compare (const void *aa
, const void *bb
)
3102 const struct describe_map_elt
*a
= aa
, *b
= bb
;
3103 if (INTEGERP (a
->event
) && INTEGERP (b
->event
))
3104 return ((XINT (a
->event
) > XINT (b
->event
))
3105 - (XINT (a
->event
) < XINT (b
->event
)));
3106 if (!INTEGERP (a
->event
) && INTEGERP (b
->event
))
3108 if (INTEGERP (a
->event
) && !INTEGERP (b
->event
))
3110 if (SYMBOLP (a
->event
) && SYMBOLP (b
->event
))
3111 return (!NILP (Fstring_lessp (a
->event
, b
->event
)) ? -1
3112 : !NILP (Fstring_lessp (b
->event
, a
->event
)) ? 1
3117 /* Describe the contents of map MAP, assuming that this map itself is
3118 reached by the sequence of prefix keys PREFIX (a string or vector).
3119 PARTIAL, SHADOW, NOMENU are as in `describe_map_tree' above. */
3122 describe_map (Lisp_Object map
, Lisp_Object prefix
,
3123 void (*elt_describer
) (Lisp_Object
, Lisp_Object
),
3124 bool partial
, Lisp_Object shadow
,
3125 Lisp_Object
*seen
, bool nomenu
, bool mention_shadow
)
3127 Lisp_Object tail
, definition
, event
;
3129 Lisp_Object suppress
;
3133 /* These accumulate the values from sparse keymap bindings,
3134 so we can sort them and handle them in order. */
3135 ptrdiff_t length_needed
= 0;
3136 struct describe_map_elt
*vect
;
3137 ptrdiff_t slots_used
= 0;
3143 suppress
= intern ("suppress-keymap");
3145 /* This vector gets used to present single keys to Flookup_key. Since
3146 that is done once per keymap element, we don't want to cons up a
3147 fresh vector every time. */
3148 kludge
= Fmake_vector (make_number (1), Qnil
);
3151 map
= call1 (Qkeymap_canonicalize
, map
);
3153 for (tail
= map
; CONSP (tail
); tail
= XCDR (tail
))
3157 SAFE_NALLOCA (vect
, 1, length_needed
);
3159 for (tail
= map
; CONSP (tail
); tail
= XCDR (tail
))
3163 if (VECTORP (XCAR (tail
))
3164 || CHAR_TABLE_P (XCAR (tail
)))
3165 describe_vector (XCAR (tail
),
3166 prefix
, Qnil
, elt_describer
, partial
, shadow
, map
,
3168 else if (CONSP (XCAR (tail
)))
3170 bool this_shadowed
= 0;
3172 event
= XCAR (XCAR (tail
));
3174 /* Ignore bindings whose "prefix" are not really valid events.
3175 (We get these in the frames and buffers menu.) */
3176 if (!(SYMBOLP (event
) || INTEGERP (event
)))
3179 if (nomenu
&& EQ (event
, Qmenu_bar
))
3182 definition
= get_keyelt (XCDR (XCAR (tail
)), 0);
3184 /* Don't show undefined commands or suppressed commands. */
3185 if (NILP (definition
)) continue;
3186 if (SYMBOLP (definition
) && partial
)
3188 tem
= Fget (definition
, suppress
);
3193 /* Don't show a command that isn't really visible
3194 because a local definition of the same key shadows it. */
3196 ASET (kludge
, 0, event
);
3199 tem
= shadow_lookup (shadow
, kludge
, Qt
, 0);
3202 /* If both bindings are keymaps, this key is a prefix key,
3203 so don't say it is shadowed. */
3204 if (KEYMAPP (definition
) && KEYMAPP (tem
))
3206 /* Avoid generating duplicate entries if the
3207 shadowed binding has the same definition. */
3208 else if (mention_shadow
&& !EQ (tem
, definition
))
3215 tem
= Flookup_key (map
, kludge
, Qt
);
3216 if (!EQ (tem
, definition
)) continue;
3218 vect
[slots_used
].event
= event
;
3219 vect
[slots_used
].definition
= definition
;
3220 vect
[slots_used
].shadowed
= this_shadowed
;
3223 else if (EQ (XCAR (tail
), Qkeymap
))
3225 /* The same keymap might be in the structure twice, if we're
3226 using an inherited keymap. So skip anything we've already
3228 tem
= Fassq (tail
, *seen
);
3229 if (CONSP (tem
) && !NILP (Fequal (XCAR (tem
), prefix
)))
3231 *seen
= Fcons (Fcons (tail
, prefix
), *seen
);
3235 /* If we found some sparse map events, sort them. */
3237 qsort (vect
, slots_used
, sizeof (struct describe_map_elt
),
3238 describe_map_compare
);
3240 /* Now output them in sorted order. */
3242 for (i
= 0; i
< slots_used
; i
++)
3244 Lisp_Object start
, end
;
3248 previous_description_column
= 0;
3253 ASET (kludge
, 0, vect
[i
].event
);
3254 start
= vect
[i
].event
;
3257 definition
= vect
[i
].definition
;
3259 /* Find consecutive chars that are identically defined. */
3260 if (INTEGERP (vect
[i
].event
))
3262 while (i
+ 1 < slots_used
3263 && EQ (vect
[i
+1].event
, make_number (XINT (vect
[i
].event
) + 1))
3264 && !NILP (Fequal (vect
[i
+ 1].definition
, definition
))
3265 && vect
[i
].shadowed
== vect
[i
+ 1].shadowed
)
3267 end
= vect
[i
].event
;
3270 /* Now START .. END is the range to describe next. */
3272 /* Insert the string to describe the event START. */
3273 insert1 (Fkey_description (kludge
, prefix
));
3275 if (!EQ (start
, end
))
3279 ASET (kludge
, 0, end
);
3280 /* Insert the string to describe the character END. */
3281 insert1 (Fkey_description (kludge
, prefix
));
3284 /* Print a description of the definition of this character.
3285 elt_describer will take care of spacing out far enough
3286 for alignment purposes. */
3287 (*elt_describer
) (vect
[i
].definition
, Qnil
);
3289 if (vect
[i
].shadowed
)
3291 ptrdiff_t pt
= max (PT
- 1, BEG
);
3294 insert_string ("\n (that binding is currently shadowed by another mode)");
3295 pt
= min (PT
+ 1, Z
);
3304 describe_vector_princ (Lisp_Object elt
, Lisp_Object fun
)
3306 Findent_to (make_number (16), make_number (1));
3308 Fterpri (Qnil
, Qnil
);
3311 DEFUN ("describe-vector", Fdescribe_vector
, Sdescribe_vector
, 1, 2, 0,
3312 doc
: /* Insert a description of contents of VECTOR.
3313 This is text showing the elements of vector matched against indices.
3314 DESCRIBER is the output function used; nil means use `princ'. */)
3315 (Lisp_Object vector
, Lisp_Object describer
)
3317 ptrdiff_t count
= SPECPDL_INDEX ();
3318 if (NILP (describer
))
3319 describer
= intern ("princ");
3320 specbind (Qstandard_output
, Fcurrent_buffer ());
3321 CHECK_VECTOR_OR_CHAR_TABLE (vector
);
3322 describe_vector (vector
, Qnil
, describer
, describe_vector_princ
, 0,
3325 return unbind_to (count
, Qnil
);
3328 /* Insert in the current buffer a description of the contents of VECTOR.
3329 We call ELT_DESCRIBER to insert the description of one value found
3332 ELT_PREFIX describes what "comes before" the keys or indices defined
3333 by this vector. This is a human-readable string whose size
3334 is not necessarily related to the situation.
3336 If the vector is in a keymap, ELT_PREFIX is a prefix key which
3337 leads to this keymap.
3339 If the vector is a chartable, ELT_PREFIX is the vector
3340 of bytes that lead to the character set or portion of a character
3341 set described by this chartable.
3343 If PARTIAL, it means do not mention suppressed commands
3344 (that assumes the vector is in a keymap).
3346 SHADOW is a list of keymaps that shadow this map.
3347 If it is non-nil, then we look up the key in those maps
3348 and we don't mention it now if it is defined by any of them.
3350 ENTIRE_MAP is the keymap in which this vector appears.
3351 If the definition in effect in the whole map does not match
3352 the one in this vector, we ignore this one.
3354 ARGS is simply passed as the second argument to ELT_DESCRIBER.
3356 KEYMAP_P is 1 if vector is known to be a keymap, so map ESC to M-.
3358 ARGS is simply passed as the second argument to ELT_DESCRIBER. */
3361 describe_vector (Lisp_Object vector
, Lisp_Object prefix
, Lisp_Object args
,
3362 void (*elt_describer
) (Lisp_Object
, Lisp_Object
),
3363 bool partial
, Lisp_Object shadow
, Lisp_Object entire_map
,
3364 bool keymap_p
, bool mention_shadow
)
3366 Lisp_Object definition
;
3368 Lisp_Object elt_prefix
= Qnil
;
3370 Lisp_Object suppress
;
3373 /* Range of elements to be handled. */
3375 Lisp_Object character
;
3384 /* Call Fkey_description first, to avoid GC bug for the other string. */
3385 if (!NILP (prefix
) && XFASTINT (Flength (prefix
)) > 0)
3387 Lisp_Object tem
= Fkey_description (prefix
, Qnil
);
3388 AUTO_STRING (space
, " ");
3389 elt_prefix
= concat2 (tem
, space
);
3394 /* This vector gets used to present single keys to Flookup_key. Since
3395 that is done once per vector element, we don't want to cons up a
3396 fresh vector every time. */
3397 kludge
= Fmake_vector (make_number (1), Qnil
);
3400 suppress
= intern ("suppress-keymap");
3403 if (CHAR_TABLE_P (vector
))
3404 stop
= MAX_5_BYTE_CHAR
+ 1, to
= MAX_CHAR
+ 1;
3406 stop
= to
= ASIZE (vector
);
3408 for (i
= from
; ; i
++)
3410 bool this_shadowed
= 0;
3411 int range_beg
, range_end
;
3425 if (CHAR_TABLE_P (vector
))
3429 val
= char_table_ref_and_range (vector
, range_beg
, &range_beg
, &i
);
3432 val
= AREF (vector
, i
);
3433 definition
= get_keyelt (val
, 0);
3435 if (NILP (definition
)) continue;
3437 /* Don't mention suppressed commands. */
3438 if (SYMBOLP (definition
) && partial
)
3442 tem
= Fget (definition
, suppress
);
3444 if (!NILP (tem
)) continue;
3447 character
= make_number (starting_i
);
3448 ASET (kludge
, 0, character
);
3450 /* If this binding is shadowed by some other map, ignore it. */
3455 tem
= shadow_lookup (shadow
, kludge
, Qt
, 0);
3466 /* Ignore this definition if it is shadowed by an earlier
3467 one in the same keymap. */
3468 if (!NILP (entire_map
))
3472 tem
= Flookup_key (entire_map
, kludge
, Qt
);
3474 if (!EQ (tem
, definition
))
3484 /* Output the prefix that applies to every entry in this map. */
3485 if (!NILP (elt_prefix
))
3486 insert1 (elt_prefix
);
3488 insert1 (Fkey_description (kludge
, prefix
));
3490 /* Find all consecutive characters or rows that have the same
3491 definition. But, VECTOR is a char-table, we had better put a
3492 boundary between normal characters (-#x3FFF7F) and 8-bit
3493 characters (#x3FFF80-). */
3494 if (CHAR_TABLE_P (vector
))
3497 && (range_beg
= i
+ 1, range_end
= stop
- 1,
3498 val
= char_table_ref_and_range (vector
, range_beg
,
3499 &range_beg
, &range_end
),
3500 tem2
= get_keyelt (val
, 0),
3502 && !NILP (Fequal (tem2
, definition
)))
3507 && (tem2
= get_keyelt (AREF (vector
, i
+ 1), 0),
3509 && !NILP (Fequal (tem2
, definition
)))
3512 /* If we have a range of more than one character,
3513 print where the range reaches to. */
3515 if (i
!= starting_i
)
3519 ASET (kludge
, 0, make_number (i
));
3521 if (!NILP (elt_prefix
))
3522 insert1 (elt_prefix
);
3524 insert1 (Fkey_description (kludge
, prefix
));
3527 /* Print a description of the definition of this character.
3528 elt_describer will take care of spacing out far enough
3529 for alignment purposes. */
3530 (*elt_describer
) (definition
, args
);
3535 insert_string (" (binding currently shadowed)");
3540 if (CHAR_TABLE_P (vector
) && ! NILP (XCHAR_TABLE (vector
)->defalt
))
3542 if (!NILP (elt_prefix
))
3543 insert1 (elt_prefix
);
3544 insert ("default", 7);
3545 (*elt_describer
) (XCHAR_TABLE (vector
)->defalt
, args
);
3549 /* Apropos - finding all symbols whose names match a regexp. */
3550 static Lisp_Object apropos_predicate
;
3551 static Lisp_Object apropos_accumulate
;
3554 apropos_accum (Lisp_Object symbol
, Lisp_Object string
)
3556 register Lisp_Object tem
;
3558 tem
= Fstring_match (string
, Fsymbol_name (symbol
), Qnil
);
3559 if (!NILP (tem
) && !NILP (apropos_predicate
))
3560 tem
= call1 (apropos_predicate
, symbol
);
3562 apropos_accumulate
= Fcons (symbol
, apropos_accumulate
);
3565 DEFUN ("apropos-internal", Fapropos_internal
, Sapropos_internal
, 1, 2, 0,
3566 doc
: /* Show all symbols whose names contain match for REGEXP.
3567 If optional 2nd arg PREDICATE is non-nil, (funcall PREDICATE SYMBOL) is done
3568 for each symbol and a symbol is mentioned only if that returns non-nil.
3569 Return list of symbols found. */)
3570 (Lisp_Object regexp
, Lisp_Object predicate
)
3573 CHECK_STRING (regexp
);
3574 apropos_predicate
= predicate
;
3575 apropos_accumulate
= Qnil
;
3576 map_obarray (Vobarray
, apropos_accum
, regexp
);
3577 tem
= Fsort (apropos_accumulate
, Qstring_lessp
);
3578 apropos_accumulate
= Qnil
;
3579 apropos_predicate
= Qnil
;
3584 syms_of_keymap (void)
3586 DEFSYM (Qkeymap
, "keymap");
3587 staticpro (&apropos_predicate
);
3588 staticpro (&apropos_accumulate
);
3589 apropos_predicate
= Qnil
;
3590 apropos_accumulate
= Qnil
;
3592 DEFSYM (Qkeymap_canonicalize
, "keymap-canonicalize");
3594 /* Now we are ready to set up this property, so we can
3595 create char tables. */
3596 Fput (Qkeymap
, Qchar_table_extra_slots
, make_number (0));
3598 /* Initialize the keymaps standardly used.
3599 Each one is the value of a Lisp variable, and is also
3600 pointed to by a C variable */
3602 global_map
= Fmake_keymap (Qnil
);
3603 Fset (intern_c_string ("global-map"), global_map
);
3605 current_global_map
= global_map
;
3606 staticpro (&global_map
);
3607 staticpro (¤t_global_map
);
3609 meta_map
= Fmake_keymap (Qnil
);
3610 Fset (intern_c_string ("esc-map"), meta_map
);
3611 Ffset (intern_c_string ("ESC-prefix"), meta_map
);
3613 control_x_map
= Fmake_keymap (Qnil
);
3614 Fset (intern_c_string ("ctl-x-map"), control_x_map
);
3615 Ffset (intern_c_string ("Control-X-prefix"), control_x_map
);
3617 exclude_keys
= listn (CONSTYPE_PURE
, 5,
3618 pure_cons (build_pure_c_string ("DEL"), build_pure_c_string ("\\d")),
3619 pure_cons (build_pure_c_string ("TAB"), build_pure_c_string ("\\t")),
3620 pure_cons (build_pure_c_string ("RET"), build_pure_c_string ("\\r")),
3621 pure_cons (build_pure_c_string ("ESC"), build_pure_c_string ("\\e")),
3622 pure_cons (build_pure_c_string ("SPC"), build_pure_c_string (" ")));
3623 staticpro (&exclude_keys
);
3625 DEFVAR_LISP ("define-key-rebound-commands", Vdefine_key_rebound_commands
,
3626 doc
: /* List of commands given new key bindings recently.
3627 This is used for internal purposes during Emacs startup;
3628 don't alter it yourself. */);
3629 Vdefine_key_rebound_commands
= Qt
;
3631 DEFVAR_LISP ("minibuffer-local-map", Vminibuffer_local_map
,
3632 doc
: /* Default keymap to use when reading from the minibuffer. */);
3633 Vminibuffer_local_map
= Fmake_sparse_keymap (Qnil
);
3635 DEFVAR_LISP ("minibuffer-local-ns-map", Vminibuffer_local_ns_map
,
3636 doc
: /* Local keymap for the minibuffer when spaces are not allowed. */);
3637 Vminibuffer_local_ns_map
= Fmake_sparse_keymap (Qnil
);
3638 Fset_keymap_parent (Vminibuffer_local_ns_map
, Vminibuffer_local_map
);
3641 DEFVAR_LISP ("minor-mode-map-alist", Vminor_mode_map_alist
,
3642 doc
: /* Alist of keymaps to use for minor modes.
3643 Each element looks like (VARIABLE . KEYMAP); KEYMAP is used to read
3644 key sequences and look up bindings if VARIABLE's value is non-nil.
3645 If two active keymaps bind the same key, the keymap appearing earlier
3646 in the list takes precedence. */);
3647 Vminor_mode_map_alist
= Qnil
;
3649 DEFVAR_LISP ("minor-mode-overriding-map-alist", Vminor_mode_overriding_map_alist
,
3650 doc
: /* Alist of keymaps to use for minor modes, in current major mode.
3651 This variable is an alist just like `minor-mode-map-alist', and it is
3652 used the same way (and before `minor-mode-map-alist'); however,
3653 it is provided for major modes to bind locally. */);
3654 Vminor_mode_overriding_map_alist
= Qnil
;
3656 DEFVAR_LISP ("emulation-mode-map-alists", Vemulation_mode_map_alists
,
3657 doc
: /* List of keymap alists to use for emulation modes.
3658 It is intended for modes or packages using multiple minor-mode keymaps.
3659 Each element is a keymap alist just like `minor-mode-map-alist', or a
3660 symbol with a variable binding which is a keymap alist, and it is used
3661 the same way. The "active" keymaps in each alist are used before
3662 `minor-mode-map-alist' and `minor-mode-overriding-map-alist'. */);
3663 Vemulation_mode_map_alists
= Qnil
;
3665 DEFVAR_LISP ("where-is-preferred-modifier", Vwhere_is_preferred_modifier
,
3666 doc
: /* Preferred modifier key to use for `where-is'.
3667 When a single binding is requested, `where-is' will return one that
3668 uses this modifier key if possible. If nil, or if no such binding
3669 exists, bindings using keys without modifiers (or only with meta) will
3671 Vwhere_is_preferred_modifier
= Qnil
;
3672 where_is_preferred_modifier
= 0;
3674 DEFSYM (Qmenu_bar
, "menu-bar");
3675 DEFSYM (Qmode_line
, "mode-line");
3677 staticpro (&Vmouse_events
);
3678 Vmouse_events
= listn (CONSTYPE_PURE
, 9,
3683 intern_c_string ("mouse-1"),
3684 intern_c_string ("mouse-2"),
3685 intern_c_string ("mouse-3"),
3686 intern_c_string ("mouse-4"),
3687 intern_c_string ("mouse-5"));
3689 /* Keymap used for minibuffers when doing completion. */
3690 /* Keymap used for minibuffers when doing completion and require a match. */
3691 DEFSYM (Qkeymapp
, "keymapp");
3692 DEFSYM (Qnon_ascii
, "non-ascii");
3693 DEFSYM (Qmenu_item
, "menu-item");
3694 DEFSYM (Qremap
, "remap");
3695 DEFSYM (QCadvertised_binding
, ":advertised-binding");
3697 command_remapping_vector
= Fmake_vector (make_number (2), Qremap
);
3698 staticpro (&command_remapping_vector
);
3700 where_is_cache_keymaps
= Qt
;
3701 where_is_cache
= Qnil
;
3702 staticpro (&where_is_cache
);
3703 staticpro (&where_is_cache_keymaps
);
3705 defsubr (&Skeymapp
);
3706 defsubr (&Skeymap_parent
);
3707 defsubr (&Skeymap_prompt
);
3708 defsubr (&Sset_keymap_parent
);
3709 defsubr (&Smake_keymap
);
3710 defsubr (&Smake_sparse_keymap
);
3711 defsubr (&Smap_keymap_internal
);
3712 defsubr (&Smap_keymap
);
3713 defsubr (&Scopy_keymap
);
3714 defsubr (&Scommand_remapping
);
3715 defsubr (&Skey_binding
);
3716 defsubr (&Slocal_key_binding
);
3717 defsubr (&Sglobal_key_binding
);
3718 defsubr (&Sminor_mode_key_binding
);
3719 defsubr (&Sdefine_key
);
3720 defsubr (&Slookup_key
);
3721 defsubr (&Sdefine_prefix_command
);
3722 defsubr (&Suse_global_map
);
3723 defsubr (&Suse_local_map
);
3724 defsubr (&Scurrent_local_map
);
3725 defsubr (&Scurrent_global_map
);
3726 defsubr (&Scurrent_minor_mode_maps
);
3727 defsubr (&Scurrent_active_maps
);
3728 defsubr (&Saccessible_keymaps
);
3729 defsubr (&Skey_description
);
3730 defsubr (&Sdescribe_vector
);
3731 defsubr (&Ssingle_key_description
);
3732 defsubr (&Stext_char_description
);
3733 defsubr (&Swhere_is_internal
);
3734 defsubr (&Sdescribe_buffer_bindings
);
3735 defsubr (&Sapropos_internal
);
3739 keys_of_keymap (void)
3741 initial_define_key (global_map
, 033, "ESC-prefix");
3742 initial_define_key (global_map
, Ctl ('X'), "Control-X-prefix");