1 /* Manipulation of keymaps
2 Copyright (C) 1985-1988, 1993-1995, 1998-2014 Free Software
5 This file is part of GNU Emacs.
7 GNU Emacs is free software: you can redistribute it and/or modify
8 it under the terms of the GNU General Public License as published by
9 the Free Software Foundation, either version 3 of the License, or
10 (at your option) any later version.
12 GNU Emacs is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 GNU General Public License for more details.
17 You should have received a copy of the GNU General Public License
18 along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>. */
21 - [M-C-a] != [?\M-\C-a]
23 - (define-key map [menu-bar foo] <bla>) does not always place <bla>
24 at the head of the menu (if `foo' was already bound earlier and
25 then unbound, for example).
27 - allow many more Meta -> ESC mappings (like Hyper -> C-e for Emacspeak)
28 - Think about the various defaulting that's currently hard-coded in
29 keyboard.c (uppercase->lowercase, char->charset, button-events, ...)
30 and make it more generic. Maybe we should allow mappings of the
31 form (PREDICATE . BINDING) as generalization of the default binding,
32 tho probably a cleaner way to attack this is to allow functional
33 keymaps (i.e. keymaps that are implemented as functions that implement
34 a few different methods like `lookup', `map', ...).
35 - Make [a] equivalent to [?a].
37 - map-keymap should work meaningfully even if entries are added/removed
38 to the keymap while iterating through it:
39 start - removed <= visited <= start + added
47 #include "character.h"
52 #include "termhooks.h"
53 #include "blockinput.h"
55 #include "intervals.h"
59 /* Actually allocate storage for these variables. */
61 Lisp_Object current_global_map
; /* Current global keymap. */
63 Lisp_Object global_map
; /* Default global key bindings. */
65 Lisp_Object meta_map
; /* The keymap used for globally bound
66 ESC-prefixed default commands. */
68 Lisp_Object control_x_map
; /* The keymap used for globally bound
69 C-x-prefixed default commands. */
71 /* The keymap used by the minibuf for local
72 bindings when spaces are allowed in the
75 /* The keymap used by the minibuf for local
76 bindings when spaces are not encouraged
79 /* Keymap used for minibuffers when doing completion. */
80 /* Keymap used for minibuffers when doing completion and require a match. */
81 static Lisp_Object Qkeymapp
, Qnon_ascii
;
82 Lisp_Object Qkeymap
, Qmenu_item
, Qremap
;
83 static Lisp_Object QCadvertised_binding
;
85 /* Alist of elements like (DEL . "\d"). */
86 static Lisp_Object exclude_keys
;
88 /* Pre-allocated 2-element vector for Fcommand_remapping to use. */
89 static Lisp_Object command_remapping_vector
;
91 /* Hash table used to cache a reverse-map to speed up calls to where-is. */
92 static Lisp_Object where_is_cache
;
93 /* Which keymaps are reverse-stored in the cache. */
94 static Lisp_Object where_is_cache_keymaps
;
96 static Lisp_Object
store_in_keymap (Lisp_Object
, Lisp_Object
, Lisp_Object
);
98 static Lisp_Object
define_as_prefix (Lisp_Object
, Lisp_Object
);
99 static void describe_command (Lisp_Object
, Lisp_Object
);
100 static void describe_translation (Lisp_Object
, Lisp_Object
);
101 static void describe_map (Lisp_Object
, Lisp_Object
,
102 void (*) (Lisp_Object
, Lisp_Object
),
103 bool, Lisp_Object
, Lisp_Object
*, bool, bool);
104 static void describe_vector (Lisp_Object
, Lisp_Object
, Lisp_Object
,
105 void (*) (Lisp_Object
, Lisp_Object
), bool,
106 Lisp_Object
, Lisp_Object
, bool, bool);
107 static void silly_event_symbol_error (Lisp_Object
);
108 static Lisp_Object
get_keyelt (Lisp_Object
, bool);
111 CHECK_VECTOR_OR_CHAR_TABLE (Lisp_Object x
)
113 CHECK_TYPE (VECTORP (x
) || CHAR_TABLE_P (x
), Qvector_or_char_table_p
, x
);
116 /* Keymap object support - constructors and predicates. */
118 DEFUN ("make-keymap", Fmake_keymap
, Smake_keymap
, 0, 1, 0,
119 doc
: /* Construct and return a new keymap, of the form (keymap CHARTABLE . ALIST).
120 CHARTABLE is a char-table that holds the bindings for all characters
121 without modifiers. All entries in it are initially nil, meaning
122 "command undefined". ALIST is an assoc-list which holds bindings for
123 function keys, mouse events, and any other things that appear in the
124 input stream. Initially, ALIST is nil.
126 The optional arg STRING supplies a menu name for the keymap
127 in case you use it as a menu with `x-popup-menu'. */)
132 tail
= list1 (string
);
135 return Fcons (Qkeymap
,
136 Fcons (Fmake_char_table (Qkeymap
, Qnil
), tail
));
139 DEFUN ("make-sparse-keymap", Fmake_sparse_keymap
, Smake_sparse_keymap
, 0, 1, 0,
140 doc
: /* Construct and return a new sparse keymap.
141 Its car is `keymap' and its cdr is an alist of (CHAR . DEFINITION),
142 which binds the character CHAR to DEFINITION, or (SYMBOL . DEFINITION),
143 which binds the function key or mouse event SYMBOL to DEFINITION.
144 Initially the alist is nil.
146 The optional arg STRING supplies a menu name for the keymap
147 in case you use it as a menu with `x-popup-menu'. */)
152 if (!NILP (Vpurify_flag
))
153 string
= Fpurecopy (string
);
154 return list2 (Qkeymap
, string
);
156 return list1 (Qkeymap
);
159 /* This function is used for installing the standard key bindings
160 at initialization time.
164 initial_define_key (control_x_map, Ctl('X'), "exchange-point-and-mark"); */
167 initial_define_key (Lisp_Object keymap
, int key
, const char *defname
)
169 store_in_keymap (keymap
, make_number (key
), intern_c_string (defname
));
173 initial_define_lispy_key (Lisp_Object keymap
, const char *keyname
, const char *defname
)
175 store_in_keymap (keymap
, intern_c_string (keyname
), intern_c_string (defname
));
178 DEFUN ("keymapp", Fkeymapp
, Skeymapp
, 1, 1, 0,
179 doc
: /* Return t if OBJECT is a keymap.
181 A keymap is a list (keymap . ALIST),
182 or a symbol whose function definition is itself a keymap.
183 ALIST elements look like (CHAR . DEFN) or (SYMBOL . DEFN);
184 a vector of densely packed bindings for small character codes
185 is also allowed as an element. */)
188 return (KEYMAPP (object
) ? Qt
: Qnil
);
191 DEFUN ("keymap-prompt", Fkeymap_prompt
, Skeymap_prompt
, 1, 1, 0,
192 doc
: /* Return the prompt-string of a keymap MAP.
193 If non-nil, the prompt is shown in the echo-area
194 when reading a key-sequence to be looked-up in this keymap. */)
197 map
= get_keymap (map
, 0, 0);
200 Lisp_Object tem
= XCAR (map
);
203 else if (KEYMAPP (tem
))
205 tem
= Fkeymap_prompt (tem
);
214 /* Check that OBJECT is a keymap (after dereferencing through any
215 symbols). If it is, return it.
217 If AUTOLOAD and if OBJECT is a symbol whose function value
218 is an autoload form, do the autoload and try again.
219 If AUTOLOAD, callers must assume GC is possible.
221 ERROR_IF_NOT_KEYMAP controls how we respond if OBJECT isn't a keymap.
222 If ERROR_IF_NOT_KEYMAP, signal an error; otherwise,
225 Note that most of the time, we don't want to pursue autoloads.
226 Functions like Faccessible_keymaps which scan entire keymap trees
227 shouldn't load every autoloaded keymap. I'm not sure about this,
228 but it seems to me that only read_key_sequence, Flookup_key, and
229 Fdefine_key should cause keymaps to be autoloaded.
231 This function can GC when AUTOLOAD is true, because it calls
232 Fautoload_do_load which can GC. */
235 get_keymap (Lisp_Object object
, bool error_if_not_keymap
, bool autoload
)
242 if (CONSP (object
) && EQ (XCAR (object
), Qkeymap
))
245 tem
= indirect_function (object
);
248 if (EQ (XCAR (tem
), Qkeymap
))
251 /* Should we do an autoload? Autoload forms for keymaps have
252 Qkeymap as their fifth element. */
253 if ((autoload
|| !error_if_not_keymap
) && EQ (XCAR (tem
), Qautoload
)
258 tail
= Fnth (make_number (4), tem
);
259 if (EQ (tail
, Qkeymap
))
263 struct gcpro gcpro1
, gcpro2
;
265 GCPRO2 (tem
, object
);
266 Fautoload_do_load (tem
, object
, Qnil
);
278 if (error_if_not_keymap
)
279 wrong_type_argument (Qkeymapp
, object
);
283 /* Return the parent map of KEYMAP, or nil if it has none.
284 We assume that KEYMAP is a valid keymap. */
287 keymap_parent (Lisp_Object keymap
, bool autoload
)
291 keymap
= get_keymap (keymap
, 1, autoload
);
293 /* Skip past the initial element `keymap'. */
294 list
= XCDR (keymap
);
295 for (; CONSP (list
); list
= XCDR (list
))
297 /* See if there is another `keymap'. */
302 return get_keymap (list
, 0, autoload
);
305 DEFUN ("keymap-parent", Fkeymap_parent
, Skeymap_parent
, 1, 1, 0,
306 doc
: /* Return the parent keymap of KEYMAP.
307 If KEYMAP has no parent, return nil. */)
310 return keymap_parent (keymap
, 1);
313 /* Check whether MAP is one of MAPS parents. */
315 keymap_memberp (Lisp_Object map
, Lisp_Object maps
)
317 if (NILP (map
)) return 0;
318 while (KEYMAPP (maps
) && !EQ (map
, maps
))
319 maps
= keymap_parent (maps
, 0);
320 return (EQ (map
, maps
));
323 /* Set the parent keymap of MAP to PARENT. */
325 DEFUN ("set-keymap-parent", Fset_keymap_parent
, Sset_keymap_parent
, 2, 2, 0,
326 doc
: /* Modify KEYMAP to set its parent map to PARENT.
327 Return PARENT. PARENT should be nil or another keymap. */)
328 (Lisp_Object keymap
, Lisp_Object parent
)
330 Lisp_Object list
, prev
;
331 struct gcpro gcpro1
, gcpro2
;
333 /* Flush any reverse-map cache. */
334 where_is_cache
= Qnil
; where_is_cache_keymaps
= Qt
;
336 GCPRO2 (keymap
, parent
);
337 keymap
= get_keymap (keymap
, 1, 1);
341 parent
= get_keymap (parent
, 1, 0);
343 /* Check for cycles. */
344 if (keymap_memberp (keymap
, parent
))
345 error ("Cyclic keymap inheritance");
348 /* Skip past the initial element `keymap'. */
353 /* If there is a parent keymap here, replace it.
354 If we came to the end, add the parent in PREV. */
355 if (!CONSP (list
) || KEYMAPP (list
))
358 XSETCDR (prev
, parent
);
359 RETURN_UNGCPRO (parent
);
366 /* Look up IDX in MAP. IDX may be any sort of event.
367 Note that this does only one level of lookup; IDX must be a single
368 event, not a sequence.
370 MAP must be a keymap or a list of keymaps.
372 If T_OK, bindings for Qt are treated as default
373 bindings; any key left unmentioned by other tables and bindings is
374 given the binding of Qt.
376 If not T_OK, bindings for Qt are not treated specially.
378 If NOINHERIT, don't accept a subkeymap found in an inherited keymap.
380 Return Qunbound if no binding was found (and return Qnil if a nil
381 binding was found). */
384 access_keymap_1 (Lisp_Object map
, Lisp_Object idx
,
385 bool t_ok
, bool noinherit
, bool autoload
)
387 /* If idx is a list (some sort of mouse click, perhaps?),
388 the index we want to use is the car of the list, which
389 ought to be a symbol. */
390 idx
= EVENT_HEAD (idx
);
392 /* If idx is a symbol, it might have modifiers, which need to
393 be put in the canonical order. */
395 idx
= reorder_modifiers (idx
);
396 else if (INTEGERP (idx
))
397 /* Clobber the high bits that can be present on a machine
398 with more than 24 bits of integer. */
399 XSETFASTINT (idx
, XINT (idx
) & (CHAR_META
| (CHAR_META
- 1)));
401 /* Handle the special meta -> esc mapping. */
402 if (INTEGERP (idx
) && XFASTINT (idx
) & meta_modifier
)
404 /* See if there is a meta-map. If there's none, there is
405 no binding for IDX, unless a default binding exists in MAP. */
407 Lisp_Object event_meta_binding
, event_meta_map
;
409 /* A strange value in which Meta is set would cause
410 infinite recursion. Protect against that. */
411 if (XINT (meta_prefix_char
) & CHAR_META
)
412 meta_prefix_char
= make_number (27);
413 event_meta_binding
= access_keymap_1 (map
, meta_prefix_char
, t_ok
,
414 noinherit
, autoload
);
415 event_meta_map
= get_keymap (event_meta_binding
, 0, autoload
);
417 if (CONSP (event_meta_map
))
419 map
= event_meta_map
;
420 idx
= make_number (XFASTINT (idx
) & ~meta_modifier
);
423 /* Set IDX to t, so that we only find a default binding. */
426 /* An explicit nil binding, or no binding at all. */
427 return NILP (event_meta_binding
) ? Qnil
: Qunbound
;
430 /* t_binding is where we put a default binding that applies,
431 to use in case we do not find a binding specifically
432 for this key sequence. */
435 Lisp_Object t_binding
= Qunbound
;
436 Lisp_Object retval
= Qunbound
;
437 Lisp_Object retval_tail
= Qnil
;
438 struct gcpro gcpro1
, gcpro2
, gcpro3
, gcpro4
;
440 GCPRO4 (tail
, idx
, t_binding
, retval
);
442 for (tail
= (CONSP (map
) && EQ (Qkeymap
, XCAR (map
))) ? XCDR (map
) : map
;
444 || (tail
= get_keymap (tail
, 0, autoload
), CONSP (tail
)));
447 /* Qunbound in VAL means we have found no binding. */
448 Lisp_Object val
= Qunbound
;
449 Lisp_Object binding
= XCAR (tail
);
450 Lisp_Object submap
= get_keymap (binding
, 0, autoload
);
452 if (EQ (binding
, Qkeymap
))
454 if (noinherit
|| NILP (retval
))
455 /* If NOINHERIT, stop here, the rest is inherited. */
457 else if (!EQ (retval
, Qunbound
))
459 Lisp_Object parent_entry
;
460 eassert (KEYMAPP (retval
));
462 = get_keymap (access_keymap_1 (tail
, idx
,
465 if (KEYMAPP (parent_entry
))
467 if (CONSP (retval_tail
))
468 XSETCDR (retval_tail
, parent_entry
);
471 retval_tail
= Fcons (retval
, parent_entry
);
472 retval
= Fcons (Qkeymap
, retval_tail
);
478 else if (CONSP (submap
))
480 val
= access_keymap_1 (submap
, idx
, t_ok
, noinherit
, autoload
);
482 else if (CONSP (binding
))
484 Lisp_Object key
= XCAR (binding
);
487 val
= XCDR (binding
);
488 else if (t_ok
&& EQ (key
, Qt
))
490 t_binding
= XCDR (binding
);
494 else if (VECTORP (binding
))
496 if (INTEGERP (idx
) && XFASTINT (idx
) < ASIZE (binding
))
497 val
= AREF (binding
, XFASTINT (idx
));
499 else if (CHAR_TABLE_P (binding
))
501 /* Character codes with modifiers
502 are not included in a char-table.
503 All character codes without modifiers are included. */
504 if (INTEGERP (idx
) && (XFASTINT (idx
) & CHAR_MODIFIER_MASK
) == 0)
506 val
= Faref (binding
, idx
);
507 /* `nil' has a special meaning for char-tables, so
508 we use something else to record an explicitly
515 /* If we found a binding, clean it up and return it. */
516 if (!EQ (val
, Qunbound
))
519 /* A Qt binding is just like an explicit nil binding
520 (i.e. it shadows any parent binding but not bindings in
521 keymaps of lower precedence). */
524 val
= get_keyelt (val
, autoload
);
528 if (NILP (retval
) || EQ (retval
, Qunbound
))
531 break; /* Shadows everything that follows. */
533 else if (NILP (retval
) || EQ (retval
, Qunbound
))
535 else if (CONSP (retval_tail
))
537 XSETCDR (retval_tail
, list1 (val
));
538 retval_tail
= XCDR (retval_tail
);
542 retval_tail
= list1 (val
);
543 retval
= Fcons (Qkeymap
, Fcons (retval
, retval_tail
));
549 return EQ (Qunbound
, retval
) ? get_keyelt (t_binding
, autoload
) : retval
;
554 access_keymap (Lisp_Object map
, Lisp_Object idx
,
555 bool t_ok
, bool noinherit
, bool autoload
)
557 Lisp_Object val
= access_keymap_1 (map
, idx
, t_ok
, noinherit
, autoload
);
558 return EQ (val
, Qunbound
) ? Qnil
: val
;
562 map_keymap_item (map_keymap_function_t fun
, Lisp_Object args
, Lisp_Object key
, Lisp_Object val
, void *data
)
566 (*fun
) (key
, val
, args
, data
);
570 map_keymap_char_table_item (Lisp_Object args
, Lisp_Object key
, Lisp_Object val
)
574 map_keymap_function_t fun
575 = (map_keymap_function_t
) XSAVE_FUNCPOINTER (args
, 0);
576 /* If the key is a range, make a copy since map_char_table modifies
579 key
= Fcons (XCAR (key
), XCDR (key
));
580 map_keymap_item (fun
, XSAVE_OBJECT (args
, 2), key
,
581 val
, XSAVE_POINTER (args
, 1));
585 /* Call FUN for every binding in MAP and stop at (and return) the parent.
586 FUN is called with 4 arguments: FUN (KEY, BINDING, ARGS, DATA). */
588 map_keymap_internal (Lisp_Object map
,
589 map_keymap_function_t fun
,
593 struct gcpro gcpro1
, gcpro2
, gcpro3
;
595 = (CONSP (map
) && EQ (Qkeymap
, XCAR (map
))) ? XCDR (map
) : map
;
597 GCPRO3 (map
, args
, tail
);
598 for (; CONSP (tail
) && !EQ (Qkeymap
, XCAR (tail
)); tail
= XCDR (tail
))
600 Lisp_Object binding
= XCAR (tail
);
602 if (KEYMAPP (binding
)) /* An embedded parent. */
604 else if (CONSP (binding
))
605 map_keymap_item (fun
, args
, XCAR (binding
), XCDR (binding
), data
);
606 else if (VECTORP (binding
))
608 /* Loop over the char values represented in the vector. */
609 int len
= ASIZE (binding
);
611 for (c
= 0; c
< len
; c
++)
613 Lisp_Object character
;
614 XSETFASTINT (character
, c
);
615 map_keymap_item (fun
, args
, character
, AREF (binding
, c
), data
);
618 else if (CHAR_TABLE_P (binding
))
619 map_char_table (map_keymap_char_table_item
, Qnil
, binding
,
620 make_save_funcptr_ptr_obj ((voidfuncptr
) fun
, data
,
628 map_keymap_call (Lisp_Object key
, Lisp_Object val
, Lisp_Object fun
, void *dummy
)
630 call2 (fun
, key
, val
);
633 /* Same as map_keymap_internal, but traverses parent keymaps as well.
634 AUTOLOAD indicates that autoloaded keymaps should be loaded. */
636 map_keymap (Lisp_Object map
, map_keymap_function_t fun
, Lisp_Object args
,
637 void *data
, bool autoload
)
641 map
= get_keymap (map
, 1, autoload
);
644 if (KEYMAPP (XCAR (map
)))
646 map_keymap (XCAR (map
), fun
, args
, data
, autoload
);
650 map
= map_keymap_internal (map
, fun
, args
, data
);
652 map
= get_keymap (map
, 0, autoload
);
657 static Lisp_Object Qkeymap_canonicalize
;
659 /* Same as map_keymap, but does it right, properly eliminating duplicate
660 bindings due to inheritance. */
662 map_keymap_canonical (Lisp_Object map
, map_keymap_function_t fun
, Lisp_Object args
, void *data
)
666 /* map_keymap_canonical may be used from redisplay (e.g. when building menus)
667 so be careful to ignore errors and to inhibit redisplay. */
668 map
= safe_call1 (Qkeymap_canonicalize
, map
);
669 /* No need to use `map_keymap' here because canonical map has no parent. */
670 map_keymap_internal (map
, fun
, args
, data
);
674 DEFUN ("map-keymap-internal", Fmap_keymap_internal
, Smap_keymap_internal
, 2, 2, 0,
675 doc
: /* Call FUNCTION once for each event binding in KEYMAP.
676 FUNCTION is called with two arguments: the event that is bound, and
677 the definition it is bound to. The event may be a character range.
678 If KEYMAP has a parent, this function returns it without processing it. */)
679 (Lisp_Object function
, Lisp_Object keymap
)
683 keymap
= get_keymap (keymap
, 1, 1);
684 keymap
= map_keymap_internal (keymap
, map_keymap_call
, function
, NULL
);
689 DEFUN ("map-keymap", Fmap_keymap
, Smap_keymap
, 2, 3, 0,
690 doc
: /* Call FUNCTION once for each event binding in KEYMAP.
691 FUNCTION is called with two arguments: the event that is bound, and
692 the definition it is bound to. The event may be a character range.
694 If KEYMAP has a parent, the parent's bindings are included as well.
695 This works recursively: if the parent has itself a parent, then the
696 grandparent's bindings are also included and so on.
697 usage: (map-keymap FUNCTION KEYMAP) */)
698 (Lisp_Object function
, Lisp_Object keymap
, Lisp_Object sort_first
)
700 if (! NILP (sort_first
))
701 return call2 (intern ("map-keymap-sorted"), function
, keymap
);
703 map_keymap (keymap
, map_keymap_call
, function
, NULL
, 1);
707 /* Given OBJECT which was found in a slot in a keymap,
708 trace indirect definitions to get the actual definition of that slot.
709 An indirect definition is a list of the form
710 (KEYMAP . INDEX), where KEYMAP is a keymap or a symbol defined as one
711 and INDEX is the object to look up in KEYMAP to yield the definition.
713 Also if OBJECT has a menu string as the first element,
714 remove that. Also remove a menu help string as second element.
716 If AUTOLOAD, load autoloadable keymaps
717 that are referred to with indirection.
719 This can GC because menu_item_eval_property calls Feval. */
722 get_keyelt (Lisp_Object object
, bool autoload
)
726 if (!(CONSP (object
)))
727 /* This is really the value. */
730 /* If the keymap contents looks like (menu-item name . DEFN)
731 or (menu-item name DEFN ...) then use DEFN.
732 This is a new format menu item. */
733 else if (EQ (XCAR (object
), Qmenu_item
))
735 if (CONSP (XCDR (object
)))
739 object
= XCDR (XCDR (object
));
742 object
= XCAR (object
);
744 /* If there's a `:filter FILTER', apply FILTER to the
745 menu-item's definition to get the real definition to
747 for (; CONSP (tem
) && CONSP (XCDR (tem
)); tem
= XCDR (tem
))
748 if (EQ (XCAR (tem
), QCfilter
) && autoload
)
751 filter
= XCAR (XCDR (tem
));
752 filter
= list2 (filter
, list2 (Qquote
, object
));
753 object
= menu_item_eval_property (filter
);
758 /* Invalid keymap. */
762 /* If the keymap contents looks like (STRING . DEFN), use DEFN.
763 Keymap alist elements like (CHAR MENUSTRING . DEFN)
764 will be used by HierarKey menus. */
765 else if (STRINGP (XCAR (object
)))
766 object
= XCDR (object
);
774 store_in_keymap (Lisp_Object keymap
, register Lisp_Object idx
, Lisp_Object def
)
776 /* Flush any reverse-map cache. */
777 where_is_cache
= Qnil
;
778 where_is_cache_keymaps
= Qt
;
780 if (EQ (idx
, Qkeymap
))
781 error ("`keymap' is reserved for embedded parent maps");
783 /* If we are preparing to dump, and DEF is a menu element
784 with a menu item indicator, copy it to ensure it is not pure. */
785 if (CONSP (def
) && PURE_P (def
)
786 && (EQ (XCAR (def
), Qmenu_item
) || STRINGP (XCAR (def
))))
787 def
= Fcons (XCAR (def
), XCDR (def
));
789 if (!CONSP (keymap
) || !EQ (XCAR (keymap
), Qkeymap
))
790 error ("attempt to define a key in a non-keymap");
792 /* If idx is a cons, and the car part is a character, idx must be of
793 the form (FROM-CHAR . TO-CHAR). */
794 if (CONSP (idx
) && CHARACTERP (XCAR (idx
)))
795 CHECK_CHARACTER_CDR (idx
);
797 /* If idx is a list (some sort of mouse click, perhaps?),
798 the index we want to use is the car of the list, which
799 ought to be a symbol. */
800 idx
= EVENT_HEAD (idx
);
802 /* If idx is a symbol, it might have modifiers, which need to
803 be put in the canonical order. */
805 idx
= reorder_modifiers (idx
);
806 else if (INTEGERP (idx
))
807 /* Clobber the high bits that can be present on a machine
808 with more than 24 bits of integer. */
809 XSETFASTINT (idx
, XINT (idx
) & (CHAR_META
| (CHAR_META
- 1)));
811 /* Scan the keymap for a binding of idx. */
815 /* The cons after which we should insert new bindings. If the
816 keymap has a table element, we record its position here, so new
817 bindings will go after it; this way, the table will stay
818 towards the front of the alist and character lookups in dense
819 keymaps will remain fast. Otherwise, this just points at the
820 front of the keymap. */
821 Lisp_Object insertion_point
;
823 insertion_point
= keymap
;
824 for (tail
= XCDR (keymap
); CONSP (tail
); tail
= XCDR (tail
))
831 if (NATNUMP (idx
) && XFASTINT (idx
) < ASIZE (elt
))
834 ASET (elt
, XFASTINT (idx
), def
);
837 else if (CONSP (idx
) && CHARACTERP (XCAR (idx
)))
839 int from
= XFASTINT (XCAR (idx
));
840 int to
= XFASTINT (XCDR (idx
));
842 if (to
>= ASIZE (elt
))
843 to
= ASIZE (elt
) - 1;
844 for (; from
<= to
; from
++)
845 ASET (elt
, from
, def
);
846 if (to
== XFASTINT (XCDR (idx
)))
847 /* We have defined all keys in IDX. */
850 insertion_point
= tail
;
852 else if (CHAR_TABLE_P (elt
))
854 /* Character codes with modifiers
855 are not included in a char-table.
856 All character codes without modifiers are included. */
857 if (NATNUMP (idx
) && !(XFASTINT (idx
) & CHAR_MODIFIER_MASK
))
860 /* `nil' has a special meaning for char-tables, so
861 we use something else to record an explicitly
863 NILP (def
) ? Qt
: def
);
866 else if (CONSP (idx
) && CHARACTERP (XCAR (idx
)))
868 Fset_char_table_range (elt
, idx
, NILP (def
) ? Qt
: def
);
871 insertion_point
= tail
;
873 else if (CONSP (elt
))
875 if (EQ (Qkeymap
, XCAR (elt
)))
876 { /* A sub keymap. This might be due to a lookup that found
877 two matching bindings (maybe because of a sub keymap).
878 It almost never happens (since the second binding normally
879 only happens in the inherited part of the keymap), but
880 if it does, we want to update the sub-keymap since the
881 main one might be temporary (built by access_keymap). */
882 tail
= insertion_point
= elt
;
884 else if (EQ (idx
, XCAR (elt
)))
890 else if (CONSP (idx
) && CHARACTERP (XCAR (idx
)))
892 int from
= XFASTINT (XCAR (idx
));
893 int to
= XFASTINT (XCDR (idx
));
895 if (from
<= XFASTINT (XCAR (elt
))
896 && to
>= XFASTINT (XCAR (elt
)))
904 else if (EQ (elt
, Qkeymap
))
905 /* If we find a 'keymap' symbol in the spine of KEYMAP,
906 then we must have found the start of a second keymap
907 being used as the tail of KEYMAP, and a binding for IDX
908 should be inserted before it. */
915 /* We have scanned the entire keymap, and not found a binding for
916 IDX. Let's add one. */
920 if (CONSP (idx
) && CHARACTERP (XCAR (idx
)))
922 /* IDX specifies a range of characters, and not all of them
923 were handled yet, which means this keymap doesn't have a
924 char-table. So, we insert a char-table now. */
925 elt
= Fmake_char_table (Qkeymap
, Qnil
);
926 Fset_char_table_range (elt
, idx
, NILP (def
) ? Qt
: def
);
929 elt
= Fcons (idx
, def
);
930 CHECK_IMPURE (insertion_point
);
931 XSETCDR (insertion_point
, Fcons (elt
, XCDR (insertion_point
)));
939 copy_keymap_item (Lisp_Object elt
)
941 Lisp_Object res
, tem
;
948 /* Is this a new format menu item. */
949 if (EQ (XCAR (tem
), Qmenu_item
))
951 /* Copy cell with menu-item marker. */
952 res
= elt
= Fcons (XCAR (tem
), XCDR (tem
));
956 /* Copy cell with menu-item name. */
957 XSETCDR (elt
, Fcons (XCAR (tem
), XCDR (tem
)));
963 /* Copy cell with binding and if the binding is a keymap,
965 XSETCDR (elt
, Fcons (XCAR (tem
), XCDR (tem
)));
968 if (CONSP (tem
) && EQ (XCAR (tem
), Qkeymap
))
969 XSETCAR (elt
, Fcopy_keymap (tem
));
975 /* It may be an old format menu item.
976 Skip the optional menu string. */
977 if (STRINGP (XCAR (tem
)))
979 /* Copy the cell, since copy-alist didn't go this deep. */
980 res
= elt
= Fcons (XCAR (tem
), XCDR (tem
));
982 /* Also skip the optional menu help string. */
983 if (CONSP (tem
) && STRINGP (XCAR (tem
)))
985 XSETCDR (elt
, Fcons (XCAR (tem
), XCDR (tem
)));
989 if (CONSP (tem
) && EQ (XCAR (tem
), Qkeymap
))
990 XSETCDR (elt
, Fcopy_keymap (tem
));
992 else if (EQ (XCAR (tem
), Qkeymap
))
993 res
= Fcopy_keymap (elt
);
999 copy_keymap_1 (Lisp_Object chartable
, Lisp_Object idx
, Lisp_Object elt
)
1001 Fset_char_table_range (chartable
, idx
, copy_keymap_item (elt
));
1004 DEFUN ("copy-keymap", Fcopy_keymap
, Scopy_keymap
, 1, 1, 0,
1005 doc
: /* Return a copy of the keymap KEYMAP.
1006 The copy starts out with the same definitions of KEYMAP,
1007 but changing either the copy or KEYMAP does not affect the other.
1008 Any key definitions that are subkeymaps are recursively copied.
1009 However, a key definition which is a symbol whose definition is a keymap
1011 (Lisp_Object keymap
)
1013 Lisp_Object copy
, tail
;
1014 keymap
= get_keymap (keymap
, 1, 0);
1015 copy
= tail
= list1 (Qkeymap
);
1016 keymap
= XCDR (keymap
); /* Skip the `keymap' symbol. */
1018 while (CONSP (keymap
) && !EQ (XCAR (keymap
), Qkeymap
))
1020 Lisp_Object elt
= XCAR (keymap
);
1021 if (CHAR_TABLE_P (elt
))
1023 elt
= Fcopy_sequence (elt
);
1024 map_char_table (copy_keymap_1
, Qnil
, elt
, elt
);
1026 else if (VECTORP (elt
))
1029 elt
= Fcopy_sequence (elt
);
1030 for (i
= 0; i
< ASIZE (elt
); i
++)
1031 ASET (elt
, i
, copy_keymap_item (AREF (elt
, i
)));
1033 else if (CONSP (elt
))
1035 if (EQ (XCAR (elt
), Qkeymap
))
1036 /* This is a sub keymap. */
1037 elt
= Fcopy_keymap (elt
);
1039 elt
= Fcons (XCAR (elt
), copy_keymap_item (XCDR (elt
)));
1041 XSETCDR (tail
, list1 (elt
));
1043 keymap
= XCDR (keymap
);
1045 XSETCDR (tail
, keymap
);
1049 /* Simple Keymap mutators and accessors. */
1051 /* GC is possible in this function if it autoloads a keymap. */
1053 DEFUN ("define-key", Fdefine_key
, Sdefine_key
, 3, 3, 0,
1054 doc
: /* In KEYMAP, define key sequence KEY as DEF.
1057 KEY is a string or a vector of symbols and characters, representing a
1058 sequence of keystrokes and events. Non-ASCII characters with codes
1059 above 127 (such as ISO Latin-1) can be represented by vectors.
1060 Two types of vector have special meanings:
1061 [remap COMMAND] remaps any key binding for COMMAND.
1062 [t] creates a default definition, which applies to any event with no
1063 other definition in KEYMAP.
1065 DEF is anything that can be a key's definition:
1066 nil (means key is undefined in this keymap),
1067 a command (a Lisp function suitable for interactive calling),
1068 a string (treated as a keyboard macro),
1069 a keymap (to define a prefix key),
1070 a symbol (when the key is looked up, the symbol will stand for its
1071 function definition, which should at that time be one of the above,
1072 or another symbol whose function definition is used, etc.),
1073 a cons (STRING . DEFN), meaning that DEFN is the definition
1074 (DEFN should be a valid definition in its own right),
1075 or a cons (MAP . CHAR), meaning use definition of CHAR in keymap MAP,
1076 or an extended menu item definition.
1077 (See info node `(elisp)Extended Menu Items'.)
1079 If KEYMAP is a sparse keymap with a binding for KEY, the existing
1080 binding is altered. If there is no binding for KEY, the new pair
1081 binding KEY to DEF is added at the front of KEYMAP. */)
1082 (Lisp_Object keymap
, Lisp_Object key
, Lisp_Object def
)
1090 struct gcpro gcpro1
, gcpro2
, gcpro3
;
1092 GCPRO3 (keymap
, key
, def
);
1093 keymap
= get_keymap (keymap
, 1, 1);
1095 length
= CHECK_VECTOR_OR_STRING (key
);
1097 RETURN_UNGCPRO (Qnil
);
1099 if (SYMBOLP (def
) && !EQ (Vdefine_key_rebound_commands
, Qt
))
1100 Vdefine_key_rebound_commands
= Fcons (def
, Vdefine_key_rebound_commands
);
1102 meta_bit
= (VECTORP (key
) || (STRINGP (key
) && STRING_MULTIBYTE (key
))
1103 ? meta_modifier
: 0x80);
1105 if (VECTORP (def
) && ASIZE (def
) > 0 && CONSP (AREF (def
, 0)))
1106 { /* DEF is apparently an XEmacs-style keyboard macro. */
1107 Lisp_Object tmp
= Fmake_vector (make_number (ASIZE (def
)), Qnil
);
1108 ptrdiff_t i
= ASIZE (def
);
1111 Lisp_Object defi
= AREF (def
, i
);
1112 if (CONSP (defi
) && lucid_event_type_list_p (defi
))
1113 defi
= Fevent_convert_list (defi
);
1114 ASET (tmp
, i
, defi
);
1122 c
= Faref (key
, make_number (idx
));
1126 /* C may be a Lucid style event type list or a cons (FROM .
1127 TO) specifying a range of characters. */
1128 if (lucid_event_type_list_p (c
))
1129 c
= Fevent_convert_list (c
);
1130 else if (CHARACTERP (XCAR (c
)))
1131 CHECK_CHARACTER_CDR (c
);
1135 silly_event_symbol_error (c
);
1138 && (XINT (c
) & meta_bit
)
1141 c
= meta_prefix_char
;
1147 XSETINT (c
, XINT (c
) & ~meta_bit
);
1153 if (!INTEGERP (c
) && !SYMBOLP (c
)
1155 /* If C is a range, it must be a leaf. */
1156 || (INTEGERP (XCAR (c
)) && idx
!= length
)))
1157 message_with_string ("Key sequence contains invalid event %s", c
, 1);
1160 RETURN_UNGCPRO (store_in_keymap (keymap
, c
, def
));
1162 cmd
= access_keymap (keymap
, c
, 0, 1, 1);
1164 /* If this key is undefined, make it a prefix. */
1166 cmd
= define_as_prefix (keymap
, c
);
1168 keymap
= get_keymap (cmd
, 0, 1);
1169 if (!CONSP (keymap
))
1171 const char *trailing_esc
= ((EQ (c
, meta_prefix_char
) && metized
)
1172 ? (idx
== 0 ? "ESC" : " ESC")
1175 /* We must use Fkey_description rather than just passing key to
1176 error; key might be a vector, not a string. */
1177 error ("Key sequence %s starts with non-prefix key %s%s",
1178 SDATA (Fkey_description (key
, Qnil
)),
1179 SDATA (Fkey_description (Fsubstring (key
, make_number (0),
1187 /* This function may GC (it calls Fkey_binding). */
1189 DEFUN ("command-remapping", Fcommand_remapping
, Scommand_remapping
, 1, 3, 0,
1190 doc
: /* Return the remapping for command COMMAND.
1191 Returns nil if COMMAND is not remapped (or not a symbol).
1193 If the optional argument POSITION is non-nil, it specifies a mouse
1194 position as returned by `event-start' and `event-end', and the
1195 remapping occurs in the keymaps associated with it. It can also be a
1196 number or marker, in which case the keymap properties at the specified
1197 buffer position instead of point are used. The KEYMAPS argument is
1198 ignored if POSITION is non-nil.
1200 If the optional argument KEYMAPS is non-nil, it should be a list of
1201 keymaps to search for command remapping. Otherwise, search for the
1202 remapping in all currently active keymaps. */)
1203 (Lisp_Object command
, Lisp_Object position
, Lisp_Object keymaps
)
1205 if (!SYMBOLP (command
))
1208 ASET (command_remapping_vector
, 1, command
);
1211 command
= Fkey_binding (command_remapping_vector
, Qnil
, Qt
, position
);
1213 command
= Flookup_key (Fcons (Qkeymap
, keymaps
),
1214 command_remapping_vector
, Qnil
);
1215 return INTEGERP (command
) ? Qnil
: command
;
1218 /* Value is number if KEY is too long; nil if valid but has no definition. */
1219 /* GC is possible in this function. */
1221 DEFUN ("lookup-key", Flookup_key
, Slookup_key
, 2, 3, 0,
1222 doc
: /* In keymap KEYMAP, look up key sequence KEY. Return the definition.
1223 A value of nil means undefined. See doc of `define-key'
1224 for kinds of definitions.
1226 A number as value means KEY is "too long";
1227 that is, characters or symbols in it except for the last one
1228 fail to be a valid sequence of prefix characters in KEYMAP.
1229 The number is how many characters at the front of KEY
1230 it takes to reach a non-prefix key.
1232 Normally, `lookup-key' ignores bindings for t, which act as default
1233 bindings, used when nothing else in the keymap applies; this makes it
1234 usable as a general function for probing keymaps. However, if the
1235 third optional argument ACCEPT-DEFAULT is non-nil, `lookup-key' will
1236 recognize the default bindings, just as `read-key-sequence' does. */)
1237 (Lisp_Object keymap
, Lisp_Object key
, Lisp_Object accept_default
)
1243 bool t_ok
= !NILP (accept_default
);
1244 struct gcpro gcpro1
, gcpro2
;
1246 GCPRO2 (keymap
, key
);
1247 keymap
= get_keymap (keymap
, 1, 1);
1249 length
= CHECK_VECTOR_OR_STRING (key
);
1251 RETURN_UNGCPRO (keymap
);
1256 c
= Faref (key
, make_number (idx
++));
1258 if (CONSP (c
) && lucid_event_type_list_p (c
))
1259 c
= Fevent_convert_list (c
);
1261 /* Turn the 8th bit of string chars into a meta modifier. */
1262 if (STRINGP (key
) && XINT (c
) & 0x80 && !STRING_MULTIBYTE (key
))
1263 XSETINT (c
, (XINT (c
) | meta_modifier
) & ~0x80);
1265 /* Allow string since binding for `menu-bar-select-buffer'
1266 includes the buffer name in the key sequence. */
1267 if (!INTEGERP (c
) && !SYMBOLP (c
) && !CONSP (c
) && !STRINGP (c
))
1268 message_with_string ("Key sequence contains invalid event %s", c
, 1);
1270 cmd
= access_keymap (keymap
, c
, t_ok
, 0, 1);
1272 RETURN_UNGCPRO (cmd
);
1274 keymap
= get_keymap (cmd
, 0, 1);
1275 if (!CONSP (keymap
))
1276 RETURN_UNGCPRO (make_number (idx
));
1282 /* Make KEYMAP define event C as a keymap (i.e., as a prefix).
1283 Assume that currently it does not define C at all.
1284 Return the keymap. */
1287 define_as_prefix (Lisp_Object keymap
, Lisp_Object c
)
1291 cmd
= Fmake_sparse_keymap (Qnil
);
1292 store_in_keymap (keymap
, c
, cmd
);
1297 /* Append a key to the end of a key sequence. We always make a vector. */
1300 append_key (Lisp_Object key_sequence
, Lisp_Object key
)
1302 return Fvconcat (2, ((Lisp_Object
[]) { key_sequence
, scoped_list1 (key
) }));
1305 /* Given a event type C which is a symbol,
1306 signal an error if is a mistake such as RET or M-RET or C-DEL, etc. */
1309 silly_event_symbol_error (Lisp_Object c
)
1311 Lisp_Object parsed
, base
, name
, assoc
;
1314 parsed
= parse_modifiers (c
);
1315 modifiers
= XFASTINT (XCAR (XCDR (parsed
)));
1316 base
= XCAR (parsed
);
1317 name
= Fsymbol_name (base
);
1318 /* This alist includes elements such as ("RET" . "\\r"). */
1319 assoc
= Fassoc (name
, exclude_keys
);
1323 char new_mods
[sizeof ("\\A-\\C-\\H-\\M-\\S-\\s-")];
1325 Lisp_Object keystring
;
1326 if (modifiers
& alt_modifier
)
1327 { *p
++ = '\\'; *p
++ = 'A'; *p
++ = '-'; }
1328 if (modifiers
& ctrl_modifier
)
1329 { *p
++ = '\\'; *p
++ = 'C'; *p
++ = '-'; }
1330 if (modifiers
& hyper_modifier
)
1331 { *p
++ = '\\'; *p
++ = 'H'; *p
++ = '-'; }
1332 if (modifiers
& meta_modifier
)
1333 { *p
++ = '\\'; *p
++ = 'M'; *p
++ = '-'; }
1334 if (modifiers
& shift_modifier
)
1335 { *p
++ = '\\'; *p
++ = 'S'; *p
++ = '-'; }
1336 if (modifiers
& super_modifier
)
1337 { *p
++ = '\\'; *p
++ = 's'; *p
++ = '-'; }
1340 c
= reorder_modifiers (c
);
1341 keystring
= concat2 (build_local_string (new_mods
), XCDR (assoc
));
1343 error ("To bind the key %s, use [?%s], not [%s]",
1344 SDATA (SYMBOL_NAME (c
)), SDATA (keystring
),
1345 SDATA (SYMBOL_NAME (c
)));
1349 /* Global, local, and minor mode keymap stuff. */
1351 /* We can't put these variables inside current_minor_maps, since under
1352 some systems, static gets macro-defined to be the empty string.
1354 static Lisp_Object
*cmm_modes
= NULL
, *cmm_maps
= NULL
;
1355 static ptrdiff_t cmm_size
= 0;
1357 /* Store a pointer to an array of the currently active minor modes in
1358 *modeptr, a pointer to an array of the keymaps of the currently
1359 active minor modes in *mapptr, and return the number of maps
1362 This function always returns a pointer to the same buffer, and may
1363 free or reallocate it, so if you want to keep it for a long time or
1364 hand it out to lisp code, copy it. This procedure will be called
1365 for every key sequence read, so the nice lispy approach (return a
1366 new assoclist, list, what have you) for each invocation would
1367 result in a lot of consing over time.
1369 If we used xrealloc/xmalloc and ran out of memory, they would throw
1370 back to the command loop, which would try to read a key sequence,
1371 which would call this function again, resulting in an infinite
1372 loop. Instead, we'll use realloc/malloc and silently truncate the
1373 list, let the key sequence be read, and hope some other piece of
1374 code signals the error. */
1376 current_minor_maps (Lisp_Object
**modeptr
, Lisp_Object
**mapptr
)
1379 int list_number
= 0;
1380 Lisp_Object alist
, assoc
, var
, val
;
1381 Lisp_Object emulation_alists
;
1382 Lisp_Object lists
[2];
1384 emulation_alists
= Vemulation_mode_map_alists
;
1385 lists
[0] = Vminor_mode_overriding_map_alist
;
1386 lists
[1] = Vminor_mode_map_alist
;
1388 for (list_number
= 0; list_number
< 2; list_number
++)
1390 if (CONSP (emulation_alists
))
1392 alist
= XCAR (emulation_alists
);
1393 emulation_alists
= XCDR (emulation_alists
);
1394 if (SYMBOLP (alist
))
1395 alist
= find_symbol_value (alist
);
1399 alist
= lists
[list_number
];
1401 for ( ; CONSP (alist
); alist
= XCDR (alist
))
1402 if ((assoc
= XCAR (alist
), CONSP (assoc
))
1403 && (var
= XCAR (assoc
), SYMBOLP (var
))
1404 && (val
= find_symbol_value (var
), !EQ (val
, Qunbound
))
1409 /* If a variable has an entry in Vminor_mode_overriding_map_alist,
1410 and also an entry in Vminor_mode_map_alist,
1411 ignore the latter. */
1412 if (list_number
== 1)
1414 val
= assq_no_quit (var
, lists
[0]);
1421 ptrdiff_t newsize
, allocsize
;
1422 Lisp_Object
*newmodes
, *newmaps
;
1424 /* Check for size calculation overflow. Other code
1425 (e.g., read_key_sequence) adds 3 to the count
1426 later, so subtract 3 from the limit here. */
1427 if (min (PTRDIFF_MAX
, SIZE_MAX
) / (2 * sizeof *newmodes
) - 3
1431 newsize
= cmm_size
== 0 ? 30 : cmm_size
* 2;
1432 allocsize
= newsize
* sizeof *newmodes
;
1434 /* Use malloc here. See the comment above this function.
1435 Avoid realloc here; it causes spurious traps on GNU/Linux [KFS] */
1437 newmodes
= malloc (allocsize
);
1442 memcpy (newmodes
, cmm_modes
,
1443 cmm_size
* sizeof cmm_modes
[0]);
1446 cmm_modes
= newmodes
;
1449 newmaps
= malloc (allocsize
);
1454 memcpy (newmaps
, cmm_maps
,
1455 cmm_size
* sizeof cmm_maps
[0]);
1462 if (newmodes
== NULL
|| newmaps
== NULL
)
1467 /* Get the keymap definition--or nil if it is not defined. */
1468 temp
= Findirect_function (XCDR (assoc
), Qt
);
1472 cmm_maps
[i
] = temp
;
1478 if (modeptr
) *modeptr
= cmm_modes
;
1479 if (mapptr
) *mapptr
= cmm_maps
;
1483 /* Return the offset of POSITION, a click position, in the style of
1484 the respective argument of Fkey_binding. */
1486 click_position (Lisp_Object position
)
1488 EMACS_INT pos
= (INTEGERP (position
) ? XINT (position
)
1489 : MARKERP (position
) ? marker_position (position
)
1491 if (! (BEGV
<= pos
&& pos
<= ZV
))
1492 args_out_of_range (Fcurrent_buffer (), position
);
1496 DEFUN ("current-active-maps", Fcurrent_active_maps
, Scurrent_active_maps
,
1498 doc
: /* Return a list of the currently active keymaps.
1499 OLP if non-nil indicates that we should obey `overriding-local-map' and
1500 `overriding-terminal-local-map'. POSITION can specify a click position
1501 like in the respective argument of `key-binding'. */)
1502 (Lisp_Object olp
, Lisp_Object position
)
1504 ptrdiff_t count
= SPECPDL_INDEX ();
1506 Lisp_Object keymaps
= list1 (current_global_map
);
1508 /* If a mouse click position is given, our variables are based on
1509 the buffer clicked on, not the current buffer. So we may have to
1510 switch the buffer here. */
1512 if (CONSP (position
))
1516 window
= POSN_WINDOW (position
);
1518 if (WINDOWP (window
)
1519 && BUFFERP (XWINDOW (window
)->contents
)
1520 && XBUFFER (XWINDOW (window
)->contents
) != current_buffer
)
1522 /* Arrange to go back to the original buffer once we're done
1523 processing the key sequence. We don't use
1524 save_excursion_{save,restore} here, in analogy to
1525 `read-key-sequence' to avoid saving point. Maybe this
1526 would not be a problem here, but it is easier to keep
1529 record_unwind_current_buffer ();
1530 set_buffer_internal (XBUFFER (XWINDOW (window
)->contents
));
1535 /* The doc said that overriding-terminal-local-map should
1536 override overriding-local-map. The code used them both,
1537 but it seems clearer to use just one. rms, jan 2005. */
1538 && NILP (KVAR (current_kboard
, Voverriding_terminal_local_map
))
1539 && !NILP (Voverriding_local_map
))
1540 keymaps
= Fcons (Voverriding_local_map
, keymaps
);
1542 if (NILP (XCDR (keymaps
)))
1546 ptrdiff_t pt
= click_position (position
);
1547 /* This usually returns the buffer's local map,
1548 but that can be overridden by a `local-map' property. */
1549 Lisp_Object local_map
= get_local_map (pt
, current_buffer
, Qlocal_map
);
1550 /* This returns nil unless there is a `keymap' property. */
1551 Lisp_Object keymap
= get_local_map (pt
, current_buffer
, Qkeymap
);
1552 Lisp_Object otlp
= KVAR (current_kboard
, Voverriding_terminal_local_map
);
1554 if (CONSP (position
))
1556 Lisp_Object string
= POSN_STRING (position
);
1558 /* For a mouse click, get the local text-property keymap
1559 of the place clicked on, rather than point. */
1561 if (POSN_INBUFFER_P (position
))
1565 pos
= POSN_BUFFER_POSN (position
);
1567 && XINT (pos
) >= BEG
&& XINT (pos
) <= Z
)
1569 local_map
= get_local_map (XINT (pos
),
1570 current_buffer
, Qlocal_map
);
1572 keymap
= get_local_map (XINT (pos
),
1573 current_buffer
, Qkeymap
);
1577 /* If on a mode line string with a local keymap,
1578 or for a click on a string, i.e. overlay string or a
1579 string displayed via the `display' property,
1580 consider `local-map' and `keymap' properties of
1583 if (CONSP (string
) && STRINGP (XCAR (string
)))
1585 Lisp_Object pos
, map
;
1587 pos
= XCDR (string
);
1588 string
= XCAR (string
);
1591 && XINT (pos
) < SCHARS (string
))
1593 map
= Fget_text_property (pos
, Qlocal_map
, string
);
1597 map
= Fget_text_property (pos
, Qkeymap
, string
);
1605 if (!NILP (local_map
))
1606 keymaps
= Fcons (local_map
, keymaps
);
1608 /* Now put all the minor mode keymaps on the list. */
1609 nmaps
= current_minor_maps (0, &maps
);
1611 for (i
= --nmaps
; i
>= 0; i
--)
1612 if (!NILP (maps
[i
]))
1613 keymaps
= Fcons (maps
[i
], keymaps
);
1616 keymaps
= Fcons (keymap
, keymaps
);
1618 if (!NILP (olp
) && !NILP (otlp
))
1619 keymaps
= Fcons (otlp
, keymaps
);
1622 unbind_to (count
, Qnil
);
1627 /* GC is possible in this function if it autoloads a keymap. */
1629 DEFUN ("key-binding", Fkey_binding
, Skey_binding
, 1, 4, 0,
1630 doc
: /* Return the binding for command KEY in current keymaps.
1631 KEY is a string or vector, a sequence of keystrokes.
1632 The binding is probably a symbol with a function definition.
1634 Normally, `key-binding' ignores bindings for t, which act as default
1635 bindings, used when nothing else in the keymap applies; this makes it
1636 usable as a general function for probing keymaps. However, if the
1637 optional second argument ACCEPT-DEFAULT is non-nil, `key-binding' does
1638 recognize the default bindings, just as `read-key-sequence' does.
1640 Like the normal command loop, `key-binding' will remap the command
1641 resulting from looking up KEY by looking up the command in the
1642 current keymaps. However, if the optional third argument NO-REMAP
1643 is non-nil, `key-binding' returns the unmapped command.
1645 If KEY is a key sequence initiated with the mouse, the used keymaps
1646 will depend on the clicked mouse position with regard to the buffer
1647 and possible local keymaps on strings.
1649 If the optional argument POSITION is non-nil, it specifies a mouse
1650 position as returned by `event-start' and `event-end', and the lookup
1651 occurs in the keymaps associated with it instead of KEY. It can also
1652 be a number or marker, in which case the keymap properties at the
1653 specified buffer position instead of point are used.
1655 (Lisp_Object key
, Lisp_Object accept_default
, Lisp_Object no_remap
, Lisp_Object position
)
1659 if (NILP (position
) && VECTORP (key
))
1662 /* mouse events may have a symbolic prefix indicating the
1663 scrollbar or mode line */
1664 = AREF (key
, SYMBOLP (AREF (key
, 0)) && ASIZE (key
) > 1 ? 1 : 0);
1666 /* We are not interested in locations without event data */
1668 if (EVENT_HAS_PARAMETERS (event
) && CONSP (XCDR (event
)))
1670 Lisp_Object kind
= EVENT_HEAD_KIND (EVENT_HEAD (event
));
1671 if (EQ (kind
, Qmouse_click
))
1672 position
= EVENT_START (event
);
1676 value
= Flookup_key (Fcons (Qkeymap
, Fcurrent_active_maps (Qt
, position
)),
1677 key
, accept_default
);
1679 if (NILP (value
) || INTEGERP (value
))
1682 /* If the result of the ordinary keymap lookup is an interactive
1683 command, look for a key binding (ie. remapping) for that command. */
1685 if (NILP (no_remap
) && SYMBOLP (value
))
1688 if (value1
= Fcommand_remapping (value
, position
, Qnil
), !NILP (value1
))
1695 /* GC is possible in this function if it autoloads a keymap. */
1697 DEFUN ("local-key-binding", Flocal_key_binding
, Slocal_key_binding
, 1, 2, 0,
1698 doc
: /* Return the binding for command KEYS in current local keymap only.
1699 KEYS is a string or vector, a sequence of keystrokes.
1700 The binding is probably a symbol with a function definition.
1702 If optional argument ACCEPT-DEFAULT is non-nil, recognize default
1703 bindings; see the description of `lookup-key' for more details about this. */)
1704 (Lisp_Object keys
, Lisp_Object accept_default
)
1706 register Lisp_Object map
;
1707 map
= BVAR (current_buffer
, keymap
);
1710 return Flookup_key (map
, keys
, accept_default
);
1713 /* GC is possible in this function if it autoloads a keymap. */
1715 DEFUN ("global-key-binding", Fglobal_key_binding
, Sglobal_key_binding
, 1, 2, 0,
1716 doc
: /* Return the binding for command KEYS in current global keymap only.
1717 KEYS is a string or vector, a sequence of keystrokes.
1718 The binding is probably a symbol with a function definition.
1719 This function's return values are the same as those of `lookup-key'
1722 If optional argument ACCEPT-DEFAULT is non-nil, recognize default
1723 bindings; see the description of `lookup-key' for more details about this. */)
1724 (Lisp_Object keys
, Lisp_Object accept_default
)
1726 return Flookup_key (current_global_map
, keys
, accept_default
);
1729 /* GC is possible in this function if it autoloads a keymap. */
1731 DEFUN ("minor-mode-key-binding", Fminor_mode_key_binding
, Sminor_mode_key_binding
, 1, 2, 0,
1732 doc
: /* Find the visible minor mode bindings of KEY.
1733 Return an alist of pairs (MODENAME . BINDING), where MODENAME is
1734 the symbol which names the minor mode binding KEY, and BINDING is
1735 KEY's definition in that mode. In particular, if KEY has no
1736 minor-mode bindings, return nil. If the first binding is a
1737 non-prefix, all subsequent bindings will be omitted, since they would
1738 be ignored. Similarly, the list doesn't include non-prefix bindings
1739 that come after prefix bindings.
1741 If optional argument ACCEPT-DEFAULT is non-nil, recognize default
1742 bindings; see the description of `lookup-key' for more details about this. */)
1743 (Lisp_Object key
, Lisp_Object accept_default
)
1745 Lisp_Object
*modes
, *maps
;
1747 Lisp_Object binding
;
1749 struct gcpro gcpro1
, gcpro2
;
1751 nmaps
= current_minor_maps (&modes
, &maps
);
1752 /* Note that all these maps are GCPRO'd
1753 in the places where we found them. */
1756 GCPRO2 (key
, binding
);
1758 for (i
= j
= 0; i
< nmaps
; i
++)
1760 && !NILP (binding
= Flookup_key (maps
[i
], key
, accept_default
))
1761 && !INTEGERP (binding
))
1763 if (KEYMAPP (binding
))
1764 maps
[j
++] = Fcons (modes
[i
], binding
);
1766 RETURN_UNGCPRO (list1 (Fcons (modes
[i
], binding
)));
1770 return Flist (j
, maps
);
1773 DEFUN ("define-prefix-command", Fdefine_prefix_command
, Sdefine_prefix_command
, 1, 3, 0,
1774 doc
: /* Define COMMAND as a prefix command. COMMAND should be a symbol.
1775 A new sparse keymap is stored as COMMAND's function definition and its value.
1776 If a second optional argument MAPVAR is given, the map is stored as
1777 its value instead of as COMMAND's value; but COMMAND is still defined
1779 The third optional argument NAME, if given, supplies a menu name
1780 string for the map. This is required to use the keymap as a menu.
1781 This function returns COMMAND. */)
1782 (Lisp_Object command
, Lisp_Object mapvar
, Lisp_Object name
)
1785 map
= Fmake_sparse_keymap (name
);
1786 Ffset (command
, map
);
1790 Fset (command
, map
);
1794 DEFUN ("use-global-map", Fuse_global_map
, Suse_global_map
, 1, 1, 0,
1795 doc
: /* Select KEYMAP as the global keymap. */)
1796 (Lisp_Object keymap
)
1798 keymap
= get_keymap (keymap
, 1, 1);
1799 current_global_map
= keymap
;
1804 DEFUN ("use-local-map", Fuse_local_map
, Suse_local_map
, 1, 1, 0,
1805 doc
: /* Select KEYMAP as the local keymap.
1806 If KEYMAP is nil, that means no local keymap. */)
1807 (Lisp_Object keymap
)
1810 keymap
= get_keymap (keymap
, 1, 1);
1812 bset_keymap (current_buffer
, keymap
);
1817 DEFUN ("current-local-map", Fcurrent_local_map
, Scurrent_local_map
, 0, 0, 0,
1818 doc
: /* Return current buffer's local keymap, or nil if it has none.
1819 Normally the local keymap is set by the major mode with `use-local-map'. */)
1822 return BVAR (current_buffer
, keymap
);
1825 DEFUN ("current-global-map", Fcurrent_global_map
, Scurrent_global_map
, 0, 0, 0,
1826 doc
: /* Return the current global keymap. */)
1829 return current_global_map
;
1832 DEFUN ("current-minor-mode-maps", Fcurrent_minor_mode_maps
, Scurrent_minor_mode_maps
, 0, 0, 0,
1833 doc
: /* Return a list of keymaps for the minor modes of the current buffer. */)
1837 int nmaps
= current_minor_maps (0, &maps
);
1839 return Flist (nmaps
, maps
);
1842 /* Help functions for describing and documenting keymaps. */
1844 struct accessible_keymaps_data
{
1845 Lisp_Object maps
, tail
, thisseq
;
1846 /* Does the current sequence end in the meta-prefix-char? */
1851 accessible_keymaps_1 (Lisp_Object key
, Lisp_Object cmd
, Lisp_Object args
, void *data
)
1852 /* Use void * data to be compatible with map_keymap_function_t. */
1854 struct accessible_keymaps_data
*d
= data
; /* Cast! */
1855 Lisp_Object maps
= d
->maps
;
1856 Lisp_Object tail
= d
->tail
;
1857 Lisp_Object thisseq
= d
->thisseq
;
1858 bool is_metized
= d
->is_metized
&& INTEGERP (key
);
1861 cmd
= get_keymap (get_keyelt (cmd
, 0), 0, 0);
1865 /* Look for and break cycles. */
1866 while (!NILP (tem
= Frassq (cmd
, maps
)))
1868 Lisp_Object prefix
= XCAR (tem
);
1869 ptrdiff_t lim
= XINT (Flength (XCAR (tem
)));
1870 if (lim
<= XINT (Flength (thisseq
)))
1871 { /* This keymap was already seen with a smaller prefix. */
1873 while (i
< lim
&& EQ (Faref (prefix
, make_number (i
)),
1874 Faref (thisseq
, make_number (i
))))
1877 /* `prefix' is a prefix of `thisseq' => there's a cycle. */
1880 /* This occurrence of `cmd' in `maps' does not correspond to a cycle,
1881 but maybe `cmd' occurs again further down in `maps', so keep
1883 maps
= XCDR (Fmemq (tem
, maps
));
1886 /* If the last key in thisseq is meta-prefix-char,
1887 turn it into a meta-ized keystroke. We know
1888 that the event we're about to append is an
1889 ascii keystroke since we're processing a
1893 int meta_bit
= meta_modifier
;
1894 Lisp_Object last
= make_number (XINT (Flength (thisseq
)) - 1);
1895 tem
= Fcopy_sequence (thisseq
);
1897 Faset (tem
, last
, make_number (XINT (key
) | meta_bit
));
1899 /* This new sequence is the same length as
1900 thisseq, so stick it in the list right
1903 Fcons (Fcons (tem
, cmd
), XCDR (tail
)));
1907 tem
= append_key (thisseq
, key
);
1908 nconc2 (tail
, list1 (Fcons (tem
, cmd
)));
1912 /* This function cannot GC. */
1914 DEFUN ("accessible-keymaps", Faccessible_keymaps
, Saccessible_keymaps
,
1916 doc
: /* Find all keymaps accessible via prefix characters from KEYMAP.
1917 Returns a list of elements of the form (KEYS . MAP), where the sequence
1918 KEYS starting from KEYMAP gets you to MAP. These elements are ordered
1919 so that the KEYS increase in length. The first element is ([] . KEYMAP).
1920 An optional argument PREFIX, if non-nil, should be a key sequence;
1921 then the value includes only maps for prefixes that start with PREFIX. */)
1922 (Lisp_Object keymap
, Lisp_Object prefix
)
1924 Lisp_Object maps
, tail
;
1925 EMACS_INT prefixlen
= XFASTINT (Flength (prefix
));
1927 /* no need for gcpro because we don't autoload any keymaps. */
1931 /* If a prefix was specified, start with the keymap (if any) for
1932 that prefix, so we don't waste time considering other prefixes. */
1934 tem
= Flookup_key (keymap
, prefix
, Qt
);
1935 /* Flookup_key may give us nil, or a number,
1936 if the prefix is not defined in this particular map.
1937 It might even give us a list that isn't a keymap. */
1938 tem
= get_keymap (tem
, 0, 0);
1939 /* If the keymap is autoloaded `tem' is not a cons-cell, but we still
1940 want to return it. */
1943 /* Convert PREFIX to a vector now, so that later on
1944 we don't have to deal with the possibility of a string. */
1945 if (STRINGP (prefix
))
1950 copy
= Fmake_vector (make_number (SCHARS (prefix
)), Qnil
);
1951 for (i
= 0, i_byte
= 0; i
< SCHARS (prefix
);)
1955 FETCH_STRING_CHAR_ADVANCE (c
, prefix
, i
, i_byte
);
1956 if (SINGLE_BYTE_CHAR_P (c
) && (c
& 0200))
1957 c
^= 0200 | meta_modifier
;
1958 ASET (copy
, i_before
, make_number (c
));
1962 maps
= list1 (Fcons (prefix
, tem
));
1968 maps
= list1 (Fcons (zero_vector
, get_keymap (keymap
, 1, 0)));
1970 /* For each map in the list maps,
1971 look at any other maps it points to,
1972 and stick them at the end if they are not already in the list.
1974 This is a breadth-first traversal, where tail is the queue of
1975 nodes, and maps accumulates a list of all nodes visited. */
1977 for (tail
= maps
; CONSP (tail
); tail
= XCDR (tail
))
1979 struct accessible_keymaps_data data
;
1980 register Lisp_Object thismap
= Fcdr (XCAR (tail
));
1983 data
.thisseq
= Fcar (XCAR (tail
));
1986 last
= make_number (XINT (Flength (data
.thisseq
)) - 1);
1987 /* Does the current sequence end in the meta-prefix-char? */
1988 data
.is_metized
= (XINT (last
) >= 0
1989 /* Don't metize the last char of PREFIX. */
1990 && XINT (last
) >= prefixlen
1991 && EQ (Faref (data
.thisseq
, last
), meta_prefix_char
));
1993 /* Since we can't run lisp code, we can't scan autoloaded maps. */
1994 if (CONSP (thismap
))
1995 map_keymap (thismap
, accessible_keymaps_1
, Qnil
, &data
, 0);
1999 static Lisp_Object Qsingle_key_description
, Qkey_description
;
2001 /* This function cannot GC. */
2003 DEFUN ("key-description", Fkey_description
, Skey_description
, 1, 2, 0,
2004 doc
: /* Return a pretty description of key-sequence KEYS.
2005 Optional arg PREFIX is the sequence of keys leading up to KEYS.
2006 For example, [?\C-x ?l] is converted into the string \"C-x l\".
2008 For an approximate inverse of this, see `kbd'. */)
2009 (Lisp_Object keys
, Lisp_Object prefix
)
2015 EMACS_INT size
= XINT (Flength (keys
));
2017 Lisp_Object sep
= build_string (" ");
2024 size
+= XINT (Flength (prefix
));
2026 /* This has one extra element at the end that we don't pass to Fconcat. */
2027 if (min (PTRDIFF_MAX
, SIZE_MAX
) / word_size
/ 4 < size
)
2028 memory_full (SIZE_MAX
);
2029 SAFE_ALLOCA_LISP (args
, size
* 4);
2031 /* In effect, this computes
2032 (mapconcat 'single-key-description keys " ")
2033 but we shouldn't use mapconcat because it can do GC. */
2037 list
= prefix
, prefix
= Qnil
;
2038 else if (!NILP (keys
))
2039 list
= keys
, keys
= Qnil
;
2044 args
[len
] = Fsingle_key_description (meta_prefix_char
, Qnil
);
2045 result
= Fconcat (len
+ 1, args
);
2048 result
= empty_unibyte_string
;
2050 result
= Fconcat (len
- 1, args
);
2056 size
= SCHARS (list
);
2057 else if (VECTORP (list
))
2058 size
= ASIZE (list
);
2059 else if (CONSP (list
))
2060 size
= XINT (Flength (list
));
2062 wrong_type_argument (Qarrayp
, list
);
2071 FETCH_STRING_CHAR_ADVANCE (c
, list
, i
, i_byte
);
2072 if (SINGLE_BYTE_CHAR_P (c
) && (c
& 0200))
2073 c
^= 0200 | meta_modifier
;
2074 XSETFASTINT (key
, c
);
2076 else if (VECTORP (list
))
2078 key
= AREF (list
, i
); i
++;
2090 || EQ (key
, meta_prefix_char
)
2091 || (XINT (key
) & meta_modifier
))
2093 args
[len
++] = Fsingle_key_description (meta_prefix_char
, Qnil
);
2095 if (EQ (key
, meta_prefix_char
))
2099 XSETINT (key
, XINT (key
) | meta_modifier
);
2102 else if (EQ (key
, meta_prefix_char
))
2107 args
[len
++] = Fsingle_key_description (key
, Qnil
);
2115 push_key_description (EMACS_INT ch
, char *p
)
2120 /* Clear all the meaningless bits above the meta bit. */
2121 c
= ch
& (meta_modifier
| ~ - meta_modifier
);
2122 c2
= c
& ~(alt_modifier
| ctrl_modifier
| hyper_modifier
2123 | meta_modifier
| shift_modifier
| super_modifier
);
2125 if (! CHARACTERP (make_number (c2
)))
2127 /* KEY_DESCRIPTION_SIZE is large enough for this. */
2128 p
+= sprintf (p
, "[%d]", c
);
2132 tab_as_ci
= (c2
== '\t' && (c
& meta_modifier
));
2134 if (c
& alt_modifier
)
2140 if ((c
& ctrl_modifier
) != 0
2141 || (c2
< ' ' && c2
!= 27 && c2
!= '\t' && c2
!= Ctl ('M'))
2146 c
&= ~ctrl_modifier
;
2148 if (c
& hyper_modifier
)
2152 c
-= hyper_modifier
;
2154 if (c
& meta_modifier
)
2160 if (c
& shift_modifier
)
2164 c
-= shift_modifier
;
2166 if (c
& super_modifier
)
2170 c
-= super_modifier
;
2190 else if (c
== Ctl ('M'))
2198 /* `C-' already added above. */
2199 if (c
> 0 && c
<= Ctl ('Z'))
2221 /* Now we are sure that C is a valid character code. */
2222 p
+= CHAR_STRING (c
, (unsigned char *) p
);
2228 /* This function cannot GC. */
2230 DEFUN ("single-key-description", Fsingle_key_description
,
2231 Ssingle_key_description
, 1, 2, 0,
2232 doc
: /* Return a pretty description of command character KEY.
2233 Control characters turn into C-whatever, etc.
2234 Optional argument NO-ANGLES non-nil means don't put angle brackets
2235 around function keys and event symbols. */)
2236 (Lisp_Object key
, Lisp_Object no_angles
)
2240 if (CONSP (key
) && lucid_event_type_list_p (key
))
2241 key
= Fevent_convert_list (key
);
2243 if (CONSP (key
) && INTEGERP (XCAR (key
)) && INTEGERP (XCDR (key
)))
2244 /* An interval from a map-char-table. */
2245 return concat3 (Fsingle_key_description (XCAR (key
), no_angles
),
2246 build_local_string (".."),
2247 Fsingle_key_description (XCDR (key
), no_angles
));
2249 key
= EVENT_HEAD (key
);
2251 if (INTEGERP (key
)) /* Normal character. */
2253 char tem
[KEY_DESCRIPTION_SIZE
];
2254 char *p
= push_key_description (XINT (key
), tem
);
2256 return make_specified_string (tem
, -1, p
- tem
, 1);
2258 else if (SYMBOLP (key
)) /* Function key or event-symbol. */
2260 if (NILP (no_angles
))
2263 char *buffer
= SAFE_ALLOCA (sizeof "<>"
2264 + SBYTES (SYMBOL_NAME (key
)));
2265 esprintf (buffer
, "<%s>", SDATA (SYMBOL_NAME (key
)));
2266 result
= build_string (buffer
);
2271 return Fsymbol_name (key
);
2273 else if (STRINGP (key
)) /* Buffer names in the menubar. */
2274 return Fcopy_sequence (key
);
2276 error ("KEY must be an integer, cons, symbol, or string");
2280 push_text_char_description (register unsigned int c
, register char *p
)
2291 *p
++ = c
+ 64; /* 'A' - 1 */
2303 /* This function cannot GC. */
2305 DEFUN ("text-char-description", Ftext_char_description
, Stext_char_description
, 1, 1, 0,
2306 doc
: /* Return a pretty description of file-character CHARACTER.
2307 Control characters turn into "^char", etc. This differs from
2308 `single-key-description' which turns them into "C-char".
2309 Also, this function recognizes the 2**7 bit as the Meta character,
2310 whereas `single-key-description' uses the 2**27 bit for Meta.
2311 See Info node `(elisp)Describing Characters' for examples. */)
2312 (Lisp_Object character
)
2314 /* Currently MAX_MULTIBYTE_LENGTH is 4 (< 6). */
2318 CHECK_CHARACTER (character
);
2320 c
= XINT (character
);
2321 if (!ASCII_CHAR_P (c
))
2323 int len
= CHAR_STRING (c
, (unsigned char *) str
);
2325 return make_multibyte_string (str
, 1, len
);
2328 *push_text_char_description (c
& 0377, str
) = 0;
2330 return build_string (str
);
2333 static int where_is_preferred_modifier
;
2335 /* Return 0 if SEQ uses non-preferred modifiers or non-char events.
2336 Else, return 2 if SEQ uses the where_is_preferred_modifier,
2339 preferred_sequence_p (Lisp_Object seq
)
2342 EMACS_INT len
= XFASTINT (Flength (seq
));
2345 for (i
= 0; i
< len
; i
++)
2347 Lisp_Object ii
, elt
;
2349 XSETFASTINT (ii
, i
);
2350 elt
= Faref (seq
, ii
);
2352 if (!INTEGERP (elt
))
2356 int modifiers
= XINT (elt
) & (CHAR_MODIFIER_MASK
& ~CHAR_META
);
2357 if (modifiers
== where_is_preferred_modifier
)
2368 /* where-is - finding a command in a set of keymaps. */
2370 static void where_is_internal_1 (Lisp_Object key
, Lisp_Object binding
,
2371 Lisp_Object args
, void *data
);
2373 /* Like Flookup_key, but uses a list of keymaps SHADOW instead of a single map.
2374 Returns the first non-nil binding found in any of those maps.
2375 If REMAP is true, pass the result of the lookup through command
2376 remapping before returning it. */
2379 shadow_lookup (Lisp_Object shadow
, Lisp_Object key
, Lisp_Object flag
,
2382 Lisp_Object tail
, value
;
2384 for (tail
= shadow
; CONSP (tail
); tail
= XCDR (tail
))
2386 value
= Flookup_key (XCAR (tail
), key
, flag
);
2387 if (NATNUMP (value
))
2389 value
= Flookup_key (XCAR (tail
),
2390 Fsubstring (key
, make_number (0), value
), flag
);
2394 else if (!NILP (value
))
2396 Lisp_Object remapping
;
2397 if (remap
&& SYMBOLP (value
)
2398 && (remapping
= Fcommand_remapping (value
, Qnil
, shadow
),
2408 static Lisp_Object Vmouse_events
;
2410 struct where_is_internal_data
{
2411 Lisp_Object definition
, this, last
;
2412 bool last_is_meta
, noindirect
;
2413 Lisp_Object sequences
;
2416 /* This function can't GC, AFAIK. */
2417 /* Return the list of bindings found. This list is ordered "longest
2418 to shortest". It may include bindings that are actually shadowed
2419 by others, as well as duplicate bindings and remapping bindings.
2420 The list returned is potentially shared with where_is_cache, so
2421 be careful not to modify it via side-effects. */
2424 where_is_internal (Lisp_Object definition
, Lisp_Object keymaps
,
2425 bool noindirect
, bool nomenus
)
2427 Lisp_Object maps
= Qnil
;
2429 struct where_is_internal_data data
;
2431 /* Only important use of caching is for the menubar
2432 (i.e. where-is-internal called with (def nil t nil nil)). */
2433 if (nomenus
&& !noindirect
)
2435 /* Check heuristic-consistency of the cache. */
2436 if (NILP (Fequal (keymaps
, where_is_cache_keymaps
)))
2437 where_is_cache
= Qnil
;
2439 if (NILP (where_is_cache
))
2441 /* We need to create the cache. */
2442 Lisp_Object args
[2];
2443 where_is_cache
= Fmake_hash_table (0, args
);
2444 where_is_cache_keymaps
= Qt
;
2447 /* We can reuse the cache. */
2448 return Fgethash (definition
, where_is_cache
, Qnil
);
2451 /* Kill the cache so that where_is_internal_1 doesn't think
2452 we're filling it up. */
2453 where_is_cache
= Qnil
;
2456 while (CONSP (found
))
2460 Faccessible_keymaps (get_keymap (XCAR (found
), 1, 0), Qnil
));
2461 found
= XCDR (found
);
2464 data
.sequences
= Qnil
;
2465 for (; CONSP (maps
); maps
= XCDR (maps
))
2467 /* Key sequence to reach map, and the map that it reaches */
2468 register Lisp_Object
this, map
, tem
;
2470 /* In order to fold [META-PREFIX-CHAR CHAR] sequences into
2471 [M-CHAR] sequences, check if last character of the sequence
2472 is the meta-prefix char. */
2476 this = Fcar (XCAR (maps
));
2477 map
= Fcdr (XCAR (maps
));
2478 last
= make_number (XINT (Flength (this)) - 1);
2479 last_is_meta
= (XINT (last
) >= 0
2480 && EQ (Faref (this, last
), meta_prefix_char
));
2482 /* if (nomenus && !preferred_sequence_p (this)) */
2483 if (nomenus
&& XINT (last
) >= 0
2484 && SYMBOLP (tem
= Faref (this, make_number (0)))
2485 && !NILP (Fmemq (XCAR (parse_modifiers (tem
)), Vmouse_events
)))
2486 /* If no menu entries should be returned, skip over the
2487 keymaps bound to `menu-bar' and `tool-bar' and other
2488 non-ascii prefixes like `C-down-mouse-2'. */
2493 data
.definition
= definition
;
2494 data
.noindirect
= noindirect
;
2497 data
.last_is_meta
= last_is_meta
;
2500 map_keymap (map
, where_is_internal_1
, Qnil
, &data
, 0);
2503 if (nomenus
&& !noindirect
)
2504 { /* Remember for which keymaps this cache was built.
2505 We do it here (late) because we want to keep where_is_cache_keymaps
2506 set to t while the cache isn't fully filled. */
2507 where_is_cache_keymaps
= keymaps
;
2508 /* During cache-filling, data.sequences is not filled by
2509 where_is_internal_1. */
2510 return Fgethash (definition
, where_is_cache
, Qnil
);
2513 return data
.sequences
;
2516 /* This function can GC if Flookup_key autoloads any keymaps. */
2518 DEFUN ("where-is-internal", Fwhere_is_internal
, Swhere_is_internal
, 1, 5, 0,
2519 doc
: /* Return list of keys that invoke DEFINITION.
2520 If KEYMAP is a keymap, search only KEYMAP and the global keymap.
2521 If KEYMAP is nil, search all the currently active keymaps, except
2522 for `overriding-local-map' (which is ignored).
2523 If KEYMAP is a list of keymaps, search only those keymaps.
2525 If optional 3rd arg FIRSTONLY is non-nil, return the first key sequence found,
2526 rather than a list of all possible key sequences.
2527 If FIRSTONLY is the symbol `non-ascii', return the first binding found,
2528 no matter what it is.
2529 If FIRSTONLY has another non-nil value, prefer bindings
2530 that use the modifier key specified in `where-is-preferred-modifier'
2531 \(or their meta variants) and entirely reject menu bindings.
2533 If optional 4th arg NOINDIRECT is non-nil, don't extract the commands inside
2534 menu-items. This makes it possible to search for a menu-item itself.
2536 The optional 5th arg NO-REMAP alters how command remapping is handled:
2538 - If another command OTHER-COMMAND is remapped to DEFINITION, normally
2539 search for the bindings of OTHER-COMMAND and include them in the
2540 returned list. But if NO-REMAP is non-nil, include the vector
2541 [remap OTHER-COMMAND] in the returned list instead, without
2542 searching for those other bindings.
2544 - If DEFINITION is remapped to OTHER-COMMAND, normally return the
2545 bindings for OTHER-COMMAND. But if NO-REMAP is non-nil, return the
2546 bindings for DEFINITION instead, ignoring its remapping. */)
2547 (Lisp_Object definition
, Lisp_Object keymap
, Lisp_Object firstonly
, Lisp_Object noindirect
, Lisp_Object no_remap
)
2549 /* The keymaps in which to search. */
2550 Lisp_Object keymaps
;
2551 /* Potentially relevant bindings in "shortest to longest" order. */
2552 Lisp_Object sequences
= Qnil
;
2553 /* Actually relevant bindings. */
2554 Lisp_Object found
= Qnil
;
2555 /* 1 means ignore all menu bindings entirely. */
2556 bool nomenus
= !NILP (firstonly
) && !EQ (firstonly
, Qnon_ascii
);
2557 struct gcpro gcpro1
, gcpro2
, gcpro3
, gcpro4
, gcpro5
, gcpro6
;
2558 /* List of sequences found via remapping. Keep them in a separate
2559 variable, so as to push them later, since we prefer
2560 non-remapped binding. */
2561 Lisp_Object remapped_sequences
= Qnil
;
2562 /* Whether or not we're handling remapped sequences. This is needed
2563 because remapping is not done recursively by Fcommand_remapping: you
2564 can't remap a remapped command. */
2566 Lisp_Object tem
= Qnil
;
2568 /* Refresh the C version of the modifier preference. */
2569 where_is_preferred_modifier
2570 = parse_solitary_modifier (Vwhere_is_preferred_modifier
);
2572 /* Find the relevant keymaps. */
2573 if (CONSP (keymap
) && KEYMAPP (XCAR (keymap
)))
2575 else if (!NILP (keymap
))
2576 keymaps
= list2 (keymap
, current_global_map
);
2578 keymaps
= Fcurrent_active_maps (Qnil
, Qnil
);
2580 GCPRO6 (definition
, keymaps
, found
, sequences
, remapped_sequences
, tem
);
2582 tem
= Fcommand_remapping (definition
, Qnil
, keymaps
);
2583 /* If `definition' is remapped to tem', then OT1H no key will run
2584 that command (since they will run `tem' instead), so we should
2585 return nil; but OTOH all keys bound to `definition' (or to `tem')
2586 will run the same command.
2587 So for menu-shortcut purposes, we want to find all the keys bound (maybe
2588 via remapping) to `tem'. But for the purpose of finding the keys that
2589 run `definition', then we'd want to just return nil.
2590 We choose to make it work right for menu-shortcuts, since it's the most
2592 Known bugs: if you remap switch-to-buffer to toto, C-h f switch-to-buffer
2593 will tell you that switch-to-buffer is bound to C-x b even though C-x b
2594 will run toto instead. And if `toto' is itself remapped to forward-char,
2595 then C-h f toto will tell you that it's bound to C-f even though C-f does
2596 not run toto and it won't tell you that C-x b does run toto. */
2597 if (NILP (no_remap
) && !NILP (tem
))
2600 if (SYMBOLP (definition
)
2601 && !NILP (firstonly
)
2602 && !NILP (tem
= Fget (definition
, QCadvertised_binding
)))
2604 /* We have a list of advertised bindings. */
2606 if (EQ (shadow_lookup (keymaps
, XCAR (tem
), Qnil
, 0), definition
))
2607 RETURN_UNGCPRO (XCAR (tem
));
2610 if (EQ (shadow_lookup (keymaps
, tem
, Qnil
, 0), definition
))
2611 RETURN_UNGCPRO (tem
);
2614 sequences
= Freverse (where_is_internal (definition
, keymaps
,
2615 !NILP (noindirect
), nomenus
));
2617 while (CONSP (sequences
)
2618 /* If we're at the end of the `sequences' list and we haven't
2619 considered remapped sequences yet, copy them over and
2621 || (!remapped
&& (sequences
= remapped_sequences
,
2623 CONSP (sequences
))))
2625 Lisp_Object sequence
, function
;
2627 sequence
= XCAR (sequences
);
2628 sequences
= XCDR (sequences
);
2630 /* Verify that this key binding is not shadowed by another
2631 binding for the same key, before we say it exists.
2633 Mechanism: look for local definition of this key and if
2634 it is defined and does not match what we found then
2637 Either nil or number as value from Flookup_key
2639 if (NILP (Fequal (shadow_lookup (keymaps
, sequence
, Qnil
, remapped
),
2643 /* If the current sequence is a command remapping with
2644 format [remap COMMAND], find the key sequences
2645 which run COMMAND, and use those sequences instead. */
2646 if (NILP (no_remap
) && !remapped
2647 && VECTORP (sequence
) && ASIZE (sequence
) == 2
2648 && EQ (AREF (sequence
, 0), Qremap
)
2649 && (function
= AREF (sequence
, 1), SYMBOLP (function
)))
2651 Lisp_Object seqs
= where_is_internal (function
, keymaps
,
2652 !NILP (noindirect
), nomenus
);
2653 remapped_sequences
= nconc2 (Freverse (seqs
), remapped_sequences
);
2657 /* Don't annoy user with strings from a menu such as the
2658 entries from the "Edit => Paste from Kill Menu".
2659 Change them all to "(any string)", so that there
2660 seems to be only one menu item to report. */
2661 if (! NILP (sequence
))
2664 tem1
= Faref (sequence
, make_number (ASIZE (sequence
) - 1));
2666 Faset (sequence
, make_number (ASIZE (sequence
) - 1),
2667 build_string ("(any string)"));
2670 /* It is a true unshadowed match. Record it, unless it's already
2671 been seen (as could happen when inheriting keymaps). */
2672 if (NILP (Fmember (sequence
, found
)))
2673 found
= Fcons (sequence
, found
);
2675 /* If firstonly is Qnon_ascii, then we can return the first
2676 binding we find. If firstonly is not Qnon_ascii but not
2677 nil, then we should return the first ascii-only binding
2679 if (EQ (firstonly
, Qnon_ascii
))
2680 RETURN_UNGCPRO (sequence
);
2681 else if (!NILP (firstonly
)
2682 && 2 == preferred_sequence_p (sequence
))
2683 RETURN_UNGCPRO (sequence
);
2688 found
= Fnreverse (found
);
2690 /* firstonly may have been t, but we may have gone all the way through
2691 the keymaps without finding an all-ASCII key sequence. So just
2692 return the best we could find. */
2693 if (NILP (firstonly
))
2695 else if (where_is_preferred_modifier
== 0)
2696 return Fcar (found
);
2698 { /* Maybe we did not find a preferred_modifier binding, but we did find
2699 some ASCII binding. */
2700 Lisp_Object bindings
= found
;
2701 while (CONSP (bindings
))
2702 if (preferred_sequence_p (XCAR (bindings
)))
2703 return XCAR (bindings
);
2705 bindings
= XCDR (bindings
);
2706 return Fcar (found
);
2710 /* This function can GC because get_keyelt can. */
2713 where_is_internal_1 (Lisp_Object key
, Lisp_Object binding
, Lisp_Object args
, void *data
)
2715 struct where_is_internal_data
*d
= data
; /* Cast! */
2716 Lisp_Object definition
= d
->definition
;
2717 bool noindirect
= d
->noindirect
;
2718 Lisp_Object
this = d
->this;
2719 Lisp_Object last
= d
->last
;
2720 bool last_is_meta
= d
->last_is_meta
;
2721 Lisp_Object sequence
;
2723 /* Search through indirections unless that's not wanted. */
2725 binding
= get_keyelt (binding
, 0);
2727 /* End this iteration if this element does not match
2730 if (!(!NILP (where_is_cache
) /* everything "matches" during cache-fill. */
2731 || EQ (binding
, definition
)
2732 || (CONSP (definition
) && !NILP (Fequal (binding
, definition
)))))
2733 /* Doesn't match. */
2736 /* We have found a match. Construct the key sequence where we found it. */
2737 if (INTEGERP (key
) && last_is_meta
)
2739 sequence
= Fcopy_sequence (this);
2740 Faset (sequence
, last
, make_number (XINT (key
) | meta_modifier
));
2745 key
= Fcons (XCAR (key
), XCDR (key
));
2746 sequence
= append_key (this, key
);
2749 if (!NILP (where_is_cache
))
2751 Lisp_Object sequences
= Fgethash (binding
, where_is_cache
, Qnil
);
2752 Fputhash (binding
, Fcons (sequence
, sequences
), where_is_cache
);
2755 d
->sequences
= Fcons (sequence
, d
->sequences
);
2758 /* describe-bindings - summarizing all the bindings in a set of keymaps. */
2760 DEFUN ("describe-buffer-bindings", Fdescribe_buffer_bindings
, Sdescribe_buffer_bindings
, 1, 3, 0,
2761 doc
: /* Insert the list of all defined keys and their definitions.
2762 The list is inserted in the current buffer, while the bindings are
2763 looked up in BUFFER.
2764 The optional argument PREFIX, if non-nil, should be a key sequence;
2765 then we display only bindings that start with that prefix.
2766 The optional argument MENUS, if non-nil, says to mention menu bindings.
2767 \(Ordinarily these are omitted from the output.) */)
2768 (Lisp_Object buffer
, Lisp_Object prefix
, Lisp_Object menus
)
2770 Lisp_Object outbuf
, shadow
;
2771 bool nomenu
= NILP (menus
);
2773 struct gcpro gcpro1
;
2775 const char *alternate_heading
2777 Keyboard translations:\n\n\
2778 You type Translation\n\
2779 -------- -----------\n";
2781 CHECK_BUFFER (buffer
);
2786 outbuf
= Fcurrent_buffer ();
2788 /* Report on alternates for keys. */
2789 if (STRINGP (KVAR (current_kboard
, Vkeyboard_translate_table
)) && !NILP (prefix
))
2792 const unsigned char *translate
= SDATA (KVAR (current_kboard
, Vkeyboard_translate_table
));
2793 int translate_len
= SCHARS (KVAR (current_kboard
, Vkeyboard_translate_table
));
2795 for (c
= 0; c
< translate_len
; c
++)
2796 if (translate
[c
] != c
)
2798 char buf
[KEY_DESCRIPTION_SIZE
];
2801 if (alternate_heading
)
2803 insert_string (alternate_heading
);
2804 alternate_heading
= 0;
2807 bufend
= push_key_description (translate
[c
], buf
);
2808 insert (buf
, bufend
- buf
);
2809 Findent_to (make_number (16), make_number (1));
2810 bufend
= push_key_description (c
, buf
);
2811 insert (buf
, bufend
- buf
);
2815 /* Insert calls signal_after_change which may GC. */
2816 translate
= SDATA (KVAR (current_kboard
, Vkeyboard_translate_table
));
2822 if (!NILP (Vkey_translation_map
))
2823 describe_map_tree (Vkey_translation_map
, 0, Qnil
, prefix
,
2824 "Key translations", nomenu
, 1, 0, 0);
2827 /* Print the (major mode) local map. */
2829 if (!NILP (KVAR (current_kboard
, Voverriding_terminal_local_map
)))
2830 start1
= KVAR (current_kboard
, Voverriding_terminal_local_map
);
2834 describe_map_tree (start1
, 1, shadow
, prefix
,
2835 "\f\nOverriding Bindings", nomenu
, 0, 0, 0);
2836 shadow
= Fcons (start1
, shadow
);
2839 else if (!NILP (Voverriding_local_map
))
2840 start1
= Voverriding_local_map
;
2844 describe_map_tree (start1
, 1, shadow
, prefix
,
2845 "\f\nOverriding Bindings", nomenu
, 0, 0, 0);
2846 shadow
= Fcons (start1
, shadow
);
2850 /* Print the minor mode and major mode keymaps. */
2852 Lisp_Object
*modes
, *maps
;
2854 /* Temporarily switch to `buffer', so that we can get that buffer's
2855 minor modes correctly. */
2856 Fset_buffer (buffer
);
2858 nmaps
= current_minor_maps (&modes
, &maps
);
2859 Fset_buffer (outbuf
);
2861 start1
= get_local_map (BUF_PT (XBUFFER (buffer
)),
2862 XBUFFER (buffer
), Qkeymap
);
2865 describe_map_tree (start1
, 1, shadow
, prefix
,
2866 "\f\n`keymap' Property Bindings", nomenu
,
2868 shadow
= Fcons (start1
, shadow
);
2871 /* Print the minor mode maps. */
2872 for (i
= 0; i
< nmaps
; i
++)
2874 /* The title for a minor mode keymap
2875 is constructed at run time.
2876 We let describe_map_tree do the actual insertion
2877 because it takes care of other features when doing so. */
2880 if (!SYMBOLP (modes
[i
]))
2884 p
= title
= SAFE_ALLOCA (42 + SBYTES (SYMBOL_NAME (modes
[i
])));
2888 memcpy (p
, SDATA (SYMBOL_NAME (modes
[i
])),
2889 SBYTES (SYMBOL_NAME (modes
[i
])));
2890 p
+= SBYTES (SYMBOL_NAME (modes
[i
]));
2892 memcpy (p
, " Minor Mode Bindings", strlen (" Minor Mode Bindings"));
2893 p
+= strlen (" Minor Mode Bindings");
2896 describe_map_tree (maps
[i
], 1, shadow
, prefix
,
2897 title
, nomenu
, 0, 0, 0);
2898 shadow
= Fcons (maps
[i
], shadow
);
2902 start1
= get_local_map (BUF_PT (XBUFFER (buffer
)),
2903 XBUFFER (buffer
), Qlocal_map
);
2906 if (EQ (start1
, BVAR (XBUFFER (buffer
), keymap
)))
2907 describe_map_tree (start1
, 1, shadow
, prefix
,
2908 "\f\nMajor Mode Bindings", nomenu
, 0, 0, 0);
2910 describe_map_tree (start1
, 1, shadow
, prefix
,
2911 "\f\n`local-map' Property Bindings",
2914 shadow
= Fcons (start1
, shadow
);
2918 describe_map_tree (current_global_map
, 1, shadow
, prefix
,
2919 "\f\nGlobal Bindings", nomenu
, 0, 1, 0);
2921 /* Print the function-key-map translations under this prefix. */
2922 if (!NILP (KVAR (current_kboard
, Vlocal_function_key_map
)))
2923 describe_map_tree (KVAR (current_kboard
, Vlocal_function_key_map
), 0, Qnil
, prefix
,
2924 "\f\nFunction key map translations", nomenu
, 1, 0, 0);
2926 /* Print the input-decode-map translations under this prefix. */
2927 if (!NILP (KVAR (current_kboard
, Vinput_decode_map
)))
2928 describe_map_tree (KVAR (current_kboard
, Vinput_decode_map
), 0, Qnil
, prefix
,
2929 "\f\nInput decoding map translations", nomenu
, 1, 0, 0);
2935 /* Insert a description of the key bindings in STARTMAP,
2936 followed by those of all maps reachable through STARTMAP.
2937 If PARTIAL, omit certain "uninteresting" commands
2938 (such as `undefined').
2939 If SHADOW is non-nil, it is a list of maps;
2940 don't mention keys which would be shadowed by any of them.
2941 PREFIX, if non-nil, says mention only keys that start with PREFIX.
2942 TITLE, if not 0, is a string to insert at the beginning.
2943 TITLE should not end with a colon or a newline; we supply that.
2944 If NOMENU, then omit menu-bar commands.
2946 If TRANSL, the definitions are actually key translations
2947 so print strings and vectors differently.
2949 If ALWAYS_TITLE, print the title even if there are no maps
2952 If MENTION_SHADOW, then when something is shadowed by SHADOW,
2953 don't omit it; instead, mention it but say it is shadowed.
2955 Any inserted text ends in two newlines (used by `help-make-xrefs'). */
2958 describe_map_tree (Lisp_Object startmap
, bool partial
, Lisp_Object shadow
,
2959 Lisp_Object prefix
, const char *title
, bool nomenu
,
2960 bool transl
, bool always_title
, bool mention_shadow
)
2962 Lisp_Object maps
, orig_maps
, seen
, sub_shadows
;
2963 struct gcpro gcpro1
, gcpro2
, gcpro3
;
2965 const char *key_heading
2970 orig_maps
= maps
= Faccessible_keymaps (startmap
, prefix
);
2973 GCPRO3 (maps
, seen
, sub_shadows
);
2979 /* Delete from MAPS each element that is for the menu bar. */
2980 for (list
= maps
; CONSP (list
); list
= XCDR (list
))
2982 Lisp_Object elt
, elt_prefix
, tem
;
2985 elt_prefix
= Fcar (elt
);
2986 if (ASIZE (elt_prefix
) >= 1)
2988 tem
= Faref (elt_prefix
, make_number (0));
2989 if (EQ (tem
, Qmenu_bar
))
2990 maps
= Fdelq (elt
, maps
);
2995 if (!NILP (maps
) || always_title
)
2999 insert_string (title
);
3002 insert_string (" Starting With ");
3003 insert1 (Fkey_description (prefix
, Qnil
));
3005 insert_string (":\n");
3007 insert_string (key_heading
);
3011 for (; CONSP (maps
); maps
= XCDR (maps
))
3013 register Lisp_Object elt
, elt_prefix
, tail
;
3016 elt_prefix
= Fcar (elt
);
3020 for (tail
= shadow
; CONSP (tail
); tail
= XCDR (tail
))
3024 shmap
= XCAR (tail
);
3026 /* If the sequence by which we reach this keymap is zero-length,
3027 then the shadow map for this keymap is just SHADOW. */
3028 if ((STRINGP (elt_prefix
) && SCHARS (elt_prefix
) == 0)
3029 || (VECTORP (elt_prefix
) && ASIZE (elt_prefix
) == 0))
3031 /* If the sequence by which we reach this keymap actually has
3032 some elements, then the sequence's definition in SHADOW is
3033 what we should use. */
3036 shmap
= Flookup_key (shmap
, Fcar (elt
), Qt
);
3037 if (INTEGERP (shmap
))
3041 /* If shmap is not nil and not a keymap,
3042 it completely shadows this map, so don't
3043 describe this map at all. */
3044 if (!NILP (shmap
) && !KEYMAPP (shmap
))
3048 sub_shadows
= Fcons (shmap
, sub_shadows
);
3051 /* Maps we have already listed in this loop shadow this map. */
3052 for (tail
= orig_maps
; !EQ (tail
, maps
); tail
= XCDR (tail
))
3055 tem
= Fequal (Fcar (XCAR (tail
)), elt_prefix
);
3057 sub_shadows
= Fcons (XCDR (XCAR (tail
)), sub_shadows
);
3060 describe_map (Fcdr (elt
), elt_prefix
,
3061 transl
? describe_translation
: describe_command
,
3062 partial
, sub_shadows
, &seen
, nomenu
, mention_shadow
);
3068 insert_string ("\n");
3073 static int previous_description_column
;
3076 describe_command (Lisp_Object definition
, Lisp_Object args
)
3078 register Lisp_Object tem1
;
3079 ptrdiff_t column
= current_column ();
3080 int description_column
;
3082 /* If column 16 is no good, go to col 32;
3083 but don't push beyond that--go to next line instead. */
3087 description_column
= 32;
3089 else if (column
> 14 || (column
> 10 && previous_description_column
== 32))
3090 description_column
= 32;
3092 description_column
= 16;
3094 Findent_to (make_number (description_column
), make_number (1));
3095 previous_description_column
= description_column
;
3097 if (SYMBOLP (definition
))
3099 tem1
= SYMBOL_NAME (definition
);
3101 insert_string ("\n");
3103 else if (STRINGP (definition
) || VECTORP (definition
))
3104 insert_string ("Keyboard Macro\n");
3105 else if (KEYMAPP (definition
))
3106 insert_string ("Prefix Command\n");
3108 insert_string ("??\n");
3112 describe_translation (Lisp_Object definition
, Lisp_Object args
)
3114 register Lisp_Object tem1
;
3116 Findent_to (make_number (16), make_number (1));
3118 if (SYMBOLP (definition
))
3120 tem1
= SYMBOL_NAME (definition
);
3122 insert_string ("\n");
3124 else if (STRINGP (definition
) || VECTORP (definition
))
3126 insert1 (Fkey_description (definition
, Qnil
));
3127 insert_string ("\n");
3129 else if (KEYMAPP (definition
))
3130 insert_string ("Prefix Command\n");
3132 insert_string ("??\n");
3135 /* describe_map puts all the usable elements of a sparse keymap
3136 into an array of `struct describe_map_elt',
3137 then sorts them by the events. */
3139 struct describe_map_elt
3142 Lisp_Object definition
;
3146 /* qsort comparison function for sorting `struct describe_map_elt' by
3150 describe_map_compare (const void *aa
, const void *bb
)
3152 const struct describe_map_elt
*a
= aa
, *b
= bb
;
3153 if (INTEGERP (a
->event
) && INTEGERP (b
->event
))
3154 return ((XINT (a
->event
) > XINT (b
->event
))
3155 - (XINT (a
->event
) < XINT (b
->event
)));
3156 if (!INTEGERP (a
->event
) && INTEGERP (b
->event
))
3158 if (INTEGERP (a
->event
) && !INTEGERP (b
->event
))
3160 if (SYMBOLP (a
->event
) && SYMBOLP (b
->event
))
3161 return (!NILP (Fstring_lessp (a
->event
, b
->event
)) ? -1
3162 : !NILP (Fstring_lessp (b
->event
, a
->event
)) ? 1
3167 /* Describe the contents of map MAP, assuming that this map itself is
3168 reached by the sequence of prefix keys PREFIX (a string or vector).
3169 PARTIAL, SHADOW, NOMENU are as in `describe_map_tree' above. */
3172 describe_map (Lisp_Object map
, Lisp_Object prefix
,
3173 void (*elt_describer
) (Lisp_Object
, Lisp_Object
),
3174 bool partial
, Lisp_Object shadow
,
3175 Lisp_Object
*seen
, bool nomenu
, bool mention_shadow
)
3177 Lisp_Object tail
, definition
, event
;
3179 Lisp_Object suppress
;
3182 struct gcpro gcpro1
, gcpro2
, gcpro3
;
3184 /* These accumulate the values from sparse keymap bindings,
3185 so we can sort them and handle them in order. */
3186 ptrdiff_t length_needed
= 0;
3187 struct describe_map_elt
*vect
;
3188 ptrdiff_t slots_used
= 0;
3194 suppress
= intern ("suppress-keymap");
3196 /* This vector gets used to present single keys to Flookup_key. Since
3197 that is done once per keymap element, we don't want to cons up a
3198 fresh vector every time. */
3199 kludge
= Fmake_vector (make_number (1), Qnil
);
3202 GCPRO3 (prefix
, definition
, kludge
);
3204 map
= call1 (Qkeymap_canonicalize
, map
);
3206 for (tail
= map
; CONSP (tail
); tail
= XCDR (tail
))
3210 SAFE_NALLOCA (vect
, 1, length_needed
);
3212 for (tail
= map
; CONSP (tail
); tail
= XCDR (tail
))
3216 if (VECTORP (XCAR (tail
))
3217 || CHAR_TABLE_P (XCAR (tail
)))
3218 describe_vector (XCAR (tail
),
3219 prefix
, Qnil
, elt_describer
, partial
, shadow
, map
,
3221 else if (CONSP (XCAR (tail
)))
3223 bool this_shadowed
= 0;
3225 event
= XCAR (XCAR (tail
));
3227 /* Ignore bindings whose "prefix" are not really valid events.
3228 (We get these in the frames and buffers menu.) */
3229 if (!(SYMBOLP (event
) || INTEGERP (event
)))
3232 if (nomenu
&& EQ (event
, Qmenu_bar
))
3235 definition
= get_keyelt (XCDR (XCAR (tail
)), 0);
3237 /* Don't show undefined commands or suppressed commands. */
3238 if (NILP (definition
)) continue;
3239 if (SYMBOLP (definition
) && partial
)
3241 tem
= Fget (definition
, suppress
);
3246 /* Don't show a command that isn't really visible
3247 because a local definition of the same key shadows it. */
3249 ASET (kludge
, 0, event
);
3252 tem
= shadow_lookup (shadow
, kludge
, Qt
, 0);
3255 /* If both bindings are keymaps, this key is a prefix key,
3256 so don't say it is shadowed. */
3257 if (KEYMAPP (definition
) && KEYMAPP (tem
))
3259 /* Avoid generating duplicate entries if the
3260 shadowed binding has the same definition. */
3261 else if (mention_shadow
&& !EQ (tem
, definition
))
3268 tem
= Flookup_key (map
, kludge
, Qt
);
3269 if (!EQ (tem
, definition
)) continue;
3271 vect
[slots_used
].event
= event
;
3272 vect
[slots_used
].definition
= definition
;
3273 vect
[slots_used
].shadowed
= this_shadowed
;
3276 else if (EQ (XCAR (tail
), Qkeymap
))
3278 /* The same keymap might be in the structure twice, if we're
3279 using an inherited keymap. So skip anything we've already
3281 tem
= Fassq (tail
, *seen
);
3282 if (CONSP (tem
) && !NILP (Fequal (XCAR (tem
), prefix
)))
3284 *seen
= Fcons (Fcons (tail
, prefix
), *seen
);
3288 /* If we found some sparse map events, sort them. */
3290 qsort (vect
, slots_used
, sizeof (struct describe_map_elt
),
3291 describe_map_compare
);
3293 /* Now output them in sorted order. */
3295 for (i
= 0; i
< slots_used
; i
++)
3297 Lisp_Object start
, end
;
3301 previous_description_column
= 0;
3306 ASET (kludge
, 0, vect
[i
].event
);
3307 start
= vect
[i
].event
;
3310 definition
= vect
[i
].definition
;
3312 /* Find consecutive chars that are identically defined. */
3313 if (INTEGERP (vect
[i
].event
))
3315 while (i
+ 1 < slots_used
3316 && EQ (vect
[i
+1].event
, make_number (XINT (vect
[i
].event
) + 1))
3317 && !NILP (Fequal (vect
[i
+ 1].definition
, definition
))
3318 && vect
[i
].shadowed
== vect
[i
+ 1].shadowed
)
3320 end
= vect
[i
].event
;
3323 /* Now START .. END is the range to describe next. */
3325 /* Insert the string to describe the event START. */
3326 insert1 (Fkey_description (kludge
, prefix
));
3328 if (!EQ (start
, end
))
3332 ASET (kludge
, 0, end
);
3333 /* Insert the string to describe the character END. */
3334 insert1 (Fkey_description (kludge
, prefix
));
3337 /* Print a description of the definition of this character.
3338 elt_describer will take care of spacing out far enough
3339 for alignment purposes. */
3340 (*elt_describer
) (vect
[i
].definition
, Qnil
);
3342 if (vect
[i
].shadowed
)
3344 ptrdiff_t pt
= max (PT
- 1, BEG
);
3347 insert_string ("\n (that binding is currently shadowed by another mode)");
3348 pt
= min (PT
+ 1, Z
);
3358 describe_vector_princ (Lisp_Object elt
, Lisp_Object fun
)
3360 Findent_to (make_number (16), make_number (1));
3365 DEFUN ("describe-vector", Fdescribe_vector
, Sdescribe_vector
, 1, 2, 0,
3366 doc
: /* Insert a description of contents of VECTOR.
3367 This is text showing the elements of vector matched against indices.
3368 DESCRIBER is the output function used; nil means use `princ'. */)
3369 (Lisp_Object vector
, Lisp_Object describer
)
3371 ptrdiff_t count
= SPECPDL_INDEX ();
3372 if (NILP (describer
))
3373 describer
= intern ("princ");
3374 specbind (Qstandard_output
, Fcurrent_buffer ());
3375 CHECK_VECTOR_OR_CHAR_TABLE (vector
);
3376 describe_vector (vector
, Qnil
, describer
, describe_vector_princ
, 0,
3379 return unbind_to (count
, Qnil
);
3382 /* Insert in the current buffer a description of the contents of VECTOR.
3383 We call ELT_DESCRIBER to insert the description of one value found
3386 ELT_PREFIX describes what "comes before" the keys or indices defined
3387 by this vector. This is a human-readable string whose size
3388 is not necessarily related to the situation.
3390 If the vector is in a keymap, ELT_PREFIX is a prefix key which
3391 leads to this keymap.
3393 If the vector is a chartable, ELT_PREFIX is the vector
3394 of bytes that lead to the character set or portion of a character
3395 set described by this chartable.
3397 If PARTIAL, it means do not mention suppressed commands
3398 (that assumes the vector is in a keymap).
3400 SHADOW is a list of keymaps that shadow this map.
3401 If it is non-nil, then we look up the key in those maps
3402 and we don't mention it now if it is defined by any of them.
3404 ENTIRE_MAP is the keymap in which this vector appears.
3405 If the definition in effect in the whole map does not match
3406 the one in this vector, we ignore this one.
3408 ARGS is simply passed as the second argument to ELT_DESCRIBER.
3410 KEYMAP_P is 1 if vector is known to be a keymap, so map ESC to M-.
3412 ARGS is simply passed as the second argument to ELT_DESCRIBER. */
3415 describe_vector (Lisp_Object vector
, Lisp_Object prefix
, Lisp_Object args
,
3416 void (*elt_describer
) (Lisp_Object
, Lisp_Object
),
3417 bool partial
, Lisp_Object shadow
, Lisp_Object entire_map
,
3418 bool keymap_p
, bool mention_shadow
)
3420 Lisp_Object definition
;
3422 Lisp_Object elt_prefix
= Qnil
;
3424 Lisp_Object suppress
;
3427 struct gcpro gcpro1
, gcpro2
, gcpro3
, gcpro4
;
3428 /* Range of elements to be handled. */
3430 Lisp_Object character
;
3439 /* Call Fkey_description first, to avoid GC bug for the other string. */
3440 if (!NILP (prefix
) && XFASTINT (Flength (prefix
)) > 0)
3443 tem
= Fkey_description (prefix
, Qnil
);
3444 elt_prefix
= concat2 (tem
, build_local_string (" "));
3449 /* This vector gets used to present single keys to Flookup_key. Since
3450 that is done once per vector element, we don't want to cons up a
3451 fresh vector every time. */
3452 kludge
= Fmake_vector (make_number (1), Qnil
);
3453 GCPRO4 (elt_prefix
, prefix
, definition
, kludge
);
3456 suppress
= intern ("suppress-keymap");
3459 if (CHAR_TABLE_P (vector
))
3460 stop
= MAX_5_BYTE_CHAR
+ 1, to
= MAX_CHAR
+ 1;
3462 stop
= to
= ASIZE (vector
);
3464 for (i
= from
; ; i
++)
3466 bool this_shadowed
= 0;
3467 int range_beg
, range_end
;
3481 if (CHAR_TABLE_P (vector
))
3485 val
= char_table_ref_and_range (vector
, range_beg
, &range_beg
, &i
);
3488 val
= AREF (vector
, i
);
3489 definition
= get_keyelt (val
, 0);
3491 if (NILP (definition
)) continue;
3493 /* Don't mention suppressed commands. */
3494 if (SYMBOLP (definition
) && partial
)
3498 tem
= Fget (definition
, suppress
);
3500 if (!NILP (tem
)) continue;
3503 character
= make_number (starting_i
);
3504 ASET (kludge
, 0, character
);
3506 /* If this binding is shadowed by some other map, ignore it. */
3511 tem
= shadow_lookup (shadow
, kludge
, Qt
, 0);
3522 /* Ignore this definition if it is shadowed by an earlier
3523 one in the same keymap. */
3524 if (!NILP (entire_map
))
3528 tem
= Flookup_key (entire_map
, kludge
, Qt
);
3530 if (!EQ (tem
, definition
))
3540 /* Output the prefix that applies to every entry in this map. */
3541 if (!NILP (elt_prefix
))
3542 insert1 (elt_prefix
);
3544 insert1 (Fkey_description (kludge
, prefix
));
3546 /* Find all consecutive characters or rows that have the same
3547 definition. But, VECTOR is a char-table, we had better put a
3548 boundary between normal characters (-#x3FFF7F) and 8-bit
3549 characters (#x3FFF80-). */
3550 if (CHAR_TABLE_P (vector
))
3553 && (range_beg
= i
+ 1, range_end
= stop
- 1,
3554 val
= char_table_ref_and_range (vector
, range_beg
,
3555 &range_beg
, &range_end
),
3556 tem2
= get_keyelt (val
, 0),
3558 && !NILP (Fequal (tem2
, definition
)))
3563 && (tem2
= get_keyelt (AREF (vector
, i
+ 1), 0),
3565 && !NILP (Fequal (tem2
, definition
)))
3568 /* If we have a range of more than one character,
3569 print where the range reaches to. */
3571 if (i
!= starting_i
)
3575 ASET (kludge
, 0, make_number (i
));
3577 if (!NILP (elt_prefix
))
3578 insert1 (elt_prefix
);
3580 insert1 (Fkey_description (kludge
, prefix
));
3583 /* Print a description of the definition of this character.
3584 elt_describer will take care of spacing out far enough
3585 for alignment purposes. */
3586 (*elt_describer
) (definition
, args
);
3591 insert_string (" (binding currently shadowed)");
3596 if (CHAR_TABLE_P (vector
) && ! NILP (XCHAR_TABLE (vector
)->defalt
))
3598 if (!NILP (elt_prefix
))
3599 insert1 (elt_prefix
);
3600 insert ("default", 7);
3601 (*elt_describer
) (XCHAR_TABLE (vector
)->defalt
, args
);
3607 /* Apropos - finding all symbols whose names match a regexp. */
3608 static Lisp_Object apropos_predicate
;
3609 static Lisp_Object apropos_accumulate
;
3612 apropos_accum (Lisp_Object symbol
, Lisp_Object string
)
3614 register Lisp_Object tem
;
3616 tem
= Fstring_match (string
, Fsymbol_name (symbol
), Qnil
);
3617 if (!NILP (tem
) && !NILP (apropos_predicate
))
3618 tem
= call1 (apropos_predicate
, symbol
);
3620 apropos_accumulate
= Fcons (symbol
, apropos_accumulate
);
3623 DEFUN ("apropos-internal", Fapropos_internal
, Sapropos_internal
, 1, 2, 0,
3624 doc
: /* Show all symbols whose names contain match for REGEXP.
3625 If optional 2nd arg PREDICATE is non-nil, (funcall PREDICATE SYMBOL) is done
3626 for each symbol and a symbol is mentioned only if that returns non-nil.
3627 Return list of symbols found. */)
3628 (Lisp_Object regexp
, Lisp_Object predicate
)
3631 CHECK_STRING (regexp
);
3632 apropos_predicate
= predicate
;
3633 apropos_accumulate
= Qnil
;
3634 map_obarray (Vobarray
, apropos_accum
, regexp
);
3635 tem
= Fsort (apropos_accumulate
, Qstring_lessp
);
3636 apropos_accumulate
= Qnil
;
3637 apropos_predicate
= Qnil
;
3642 syms_of_keymap (void)
3644 DEFSYM (Qkeymap
, "keymap");
3645 staticpro (&apropos_predicate
);
3646 staticpro (&apropos_accumulate
);
3647 apropos_predicate
= Qnil
;
3648 apropos_accumulate
= Qnil
;
3650 DEFSYM (Qkeymap_canonicalize
, "keymap-canonicalize");
3652 /* Now we are ready to set up this property, so we can
3653 create char tables. */
3654 Fput (Qkeymap
, Qchar_table_extra_slots
, make_number (0));
3656 /* Initialize the keymaps standardly used.
3657 Each one is the value of a Lisp variable, and is also
3658 pointed to by a C variable */
3660 global_map
= Fmake_keymap (Qnil
);
3661 Fset (intern_c_string ("global-map"), global_map
);
3663 current_global_map
= global_map
;
3664 staticpro (&global_map
);
3665 staticpro (¤t_global_map
);
3667 meta_map
= Fmake_keymap (Qnil
);
3668 Fset (intern_c_string ("esc-map"), meta_map
);
3669 Ffset (intern_c_string ("ESC-prefix"), meta_map
);
3671 control_x_map
= Fmake_keymap (Qnil
);
3672 Fset (intern_c_string ("ctl-x-map"), control_x_map
);
3673 Ffset (intern_c_string ("Control-X-prefix"), control_x_map
);
3675 exclude_keys
= listn (CONSTYPE_PURE
, 5,
3676 pure_cons (build_pure_c_string ("DEL"), build_pure_c_string ("\\d")),
3677 pure_cons (build_pure_c_string ("TAB"), build_pure_c_string ("\\t")),
3678 pure_cons (build_pure_c_string ("RET"), build_pure_c_string ("\\r")),
3679 pure_cons (build_pure_c_string ("ESC"), build_pure_c_string ("\\e")),
3680 pure_cons (build_pure_c_string ("SPC"), build_pure_c_string (" ")));
3681 staticpro (&exclude_keys
);
3683 DEFVAR_LISP ("define-key-rebound-commands", Vdefine_key_rebound_commands
,
3684 doc
: /* List of commands given new key bindings recently.
3685 This is used for internal purposes during Emacs startup;
3686 don't alter it yourself. */);
3687 Vdefine_key_rebound_commands
= Qt
;
3689 DEFVAR_LISP ("minibuffer-local-map", Vminibuffer_local_map
,
3690 doc
: /* Default keymap to use when reading from the minibuffer. */);
3691 Vminibuffer_local_map
= Fmake_sparse_keymap (Qnil
);
3693 DEFVAR_LISP ("minibuffer-local-ns-map", Vminibuffer_local_ns_map
,
3694 doc
: /* Local keymap for the minibuffer when spaces are not allowed. */);
3695 Vminibuffer_local_ns_map
= Fmake_sparse_keymap (Qnil
);
3696 Fset_keymap_parent (Vminibuffer_local_ns_map
, Vminibuffer_local_map
);
3699 DEFVAR_LISP ("minor-mode-map-alist", Vminor_mode_map_alist
,
3700 doc
: /* Alist of keymaps to use for minor modes.
3701 Each element looks like (VARIABLE . KEYMAP); KEYMAP is used to read
3702 key sequences and look up bindings if VARIABLE's value is non-nil.
3703 If two active keymaps bind the same key, the keymap appearing earlier
3704 in the list takes precedence. */);
3705 Vminor_mode_map_alist
= Qnil
;
3707 DEFVAR_LISP ("minor-mode-overriding-map-alist", Vminor_mode_overriding_map_alist
,
3708 doc
: /* Alist of keymaps to use for minor modes, in current major mode.
3709 This variable is an alist just like `minor-mode-map-alist', and it is
3710 used the same way (and before `minor-mode-map-alist'); however,
3711 it is provided for major modes to bind locally. */);
3712 Vminor_mode_overriding_map_alist
= Qnil
;
3714 DEFVAR_LISP ("emulation-mode-map-alists", Vemulation_mode_map_alists
,
3715 doc
: /* List of keymap alists to use for emulation modes.
3716 It is intended for modes or packages using multiple minor-mode keymaps.
3717 Each element is a keymap alist just like `minor-mode-map-alist', or a
3718 symbol with a variable binding which is a keymap alist, and it is used
3719 the same way. The "active" keymaps in each alist are used before
3720 `minor-mode-map-alist' and `minor-mode-overriding-map-alist'. */);
3721 Vemulation_mode_map_alists
= Qnil
;
3723 DEFVAR_LISP ("where-is-preferred-modifier", Vwhere_is_preferred_modifier
,
3724 doc
: /* Preferred modifier key to use for `where-is'.
3725 When a single binding is requested, `where-is' will return one that
3726 uses this modifier key if possible. If nil, or if no such binding
3727 exists, bindings using keys without modifiers (or only with meta) will
3729 Vwhere_is_preferred_modifier
= Qnil
;
3730 where_is_preferred_modifier
= 0;
3732 staticpro (&Vmouse_events
);
3733 Vmouse_events
= listn (CONSTYPE_PURE
, 9,
3734 intern_c_string ("menu-bar"),
3735 intern_c_string ("tool-bar"),
3736 intern_c_string ("header-line"),
3737 intern_c_string ("mode-line"),
3738 intern_c_string ("mouse-1"),
3739 intern_c_string ("mouse-2"),
3740 intern_c_string ("mouse-3"),
3741 intern_c_string ("mouse-4"),
3742 intern_c_string ("mouse-5"));
3744 DEFSYM (Qsingle_key_description
, "single-key-description");
3745 DEFSYM (Qkey_description
, "key-description");
3746 DEFSYM (Qkeymapp
, "keymapp");
3747 DEFSYM (Qnon_ascii
, "non-ascii");
3748 DEFSYM (Qmenu_item
, "menu-item");
3749 DEFSYM (Qremap
, "remap");
3750 DEFSYM (QCadvertised_binding
, ":advertised-binding");
3752 command_remapping_vector
= Fmake_vector (make_number (2), Qremap
);
3753 staticpro (&command_remapping_vector
);
3755 where_is_cache_keymaps
= Qt
;
3756 where_is_cache
= Qnil
;
3757 staticpro (&where_is_cache
);
3758 staticpro (&where_is_cache_keymaps
);
3760 defsubr (&Skeymapp
);
3761 defsubr (&Skeymap_parent
);
3762 defsubr (&Skeymap_prompt
);
3763 defsubr (&Sset_keymap_parent
);
3764 defsubr (&Smake_keymap
);
3765 defsubr (&Smake_sparse_keymap
);
3766 defsubr (&Smap_keymap_internal
);
3767 defsubr (&Smap_keymap
);
3768 defsubr (&Scopy_keymap
);
3769 defsubr (&Scommand_remapping
);
3770 defsubr (&Skey_binding
);
3771 defsubr (&Slocal_key_binding
);
3772 defsubr (&Sglobal_key_binding
);
3773 defsubr (&Sminor_mode_key_binding
);
3774 defsubr (&Sdefine_key
);
3775 defsubr (&Slookup_key
);
3776 defsubr (&Sdefine_prefix_command
);
3777 defsubr (&Suse_global_map
);
3778 defsubr (&Suse_local_map
);
3779 defsubr (&Scurrent_local_map
);
3780 defsubr (&Scurrent_global_map
);
3781 defsubr (&Scurrent_minor_mode_maps
);
3782 defsubr (&Scurrent_active_maps
);
3783 defsubr (&Saccessible_keymaps
);
3784 defsubr (&Skey_description
);
3785 defsubr (&Sdescribe_vector
);
3786 defsubr (&Ssingle_key_description
);
3787 defsubr (&Stext_char_description
);
3788 defsubr (&Swhere_is_internal
);
3789 defsubr (&Sdescribe_buffer_bindings
);
3790 defsubr (&Sapropos_internal
);
3794 keys_of_keymap (void)
3796 initial_define_key (global_map
, 033, "ESC-prefix");
3797 initial_define_key (global_map
, Ctl ('X'), "Control-X-prefix");