1 /* Manipulation of keymaps
2 Copyright (C) 1985, 1986, 1987, 1988 Free Software Foundation, Inc.
4 This file is part of GNU Emacs.
6 GNU Emacs is free software; you can redistribute it and/or modify
7 it under the terms of the GNU General Public License as published by
8 the Free Software Foundation; either version 1, or (at your option)
11 GNU Emacs is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 GNU General Public License for more details.
16 You should have received a copy of the GNU General Public License
17 along with GNU Emacs; see the file COPYING. If not, write to
18 the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA. */
28 #define min(a, b) ((a) < (b) ? (a) : (b))
30 /* Dense keymaps look like (keymap VECTOR . ALIST), where VECTOR is a
31 128-element vector used to look up bindings for ASCII characters,
32 and ALIST is an assoc list for looking up symbols. */
33 #define DENSE_TABLE_SIZE (0200)
35 /* Actually allocate storage for these variables */
37 Lisp_Object current_global_map
; /* Current global keymap */
39 Lisp_Object global_map
; /* default global key bindings */
41 Lisp_Object meta_map
; /* The keymap used for globally bound
42 ESC-prefixed default commands */
44 Lisp_Object control_x_map
; /* The keymap used for globally bound
45 C-x-prefixed default commands */
47 /* was MinibufLocalMap */
48 Lisp_Object Vminibuffer_local_map
;
49 /* The keymap used by the minibuf for local
50 bindings when spaces are allowed in the
53 /* was MinibufLocalNSMap */
54 Lisp_Object Vminibuffer_local_ns_map
;
55 /* The keymap used by the minibuf for local
56 bindings when spaces are not encouraged
59 /* keymap used for minibuffers when doing completion */
60 /* was MinibufLocalCompletionMap */
61 Lisp_Object Vminibuffer_local_completion_map
;
63 /* keymap used for minibuffers when doing completion and require a match */
64 /* was MinibufLocalMustMatchMap */
65 Lisp_Object Vminibuffer_local_must_match_map
;
67 Lisp_Object Qkeymapp
, Qkeymap
;
69 /* A char over 0200 in a key sequence
70 is equivalent to prefixing with this character. */
72 extern Lisp_Object meta_prefix_char
;
74 void describe_map_tree ();
75 static Lisp_Object
describe_buffer_bindings ();
76 static void describe_command ();
77 static void describe_map ();
78 static void describe_alist ();
80 DEFUN ("make-keymap", Fmake_keymap
, Smake_keymap
, 0, 0, 0,
81 "Construct and return a new keymap, of the form (keymap VECTOR . ALIST).\n\
82 VECTOR is a 128-element vector which holds the bindings for the ASCII\n\
83 characters. ALIST is an assoc-list which holds bindings for function keys,\n\
84 mouse events, and any other things that appear in the input stream.\n\
85 All entries in it are initially nil, meaning \"command undefined\".")
88 return Fcons (Qkeymap
,
89 Fcons (Fmake_vector (make_number (DENSE_TABLE_SIZE
), Qnil
),
93 DEFUN ("make-sparse-keymap", Fmake_sparse_keymap
, Smake_sparse_keymap
, 0, 0, 0,
94 "Construct and return a new sparse-keymap list.\n\
95 Its car is `keymap' and its cdr is an alist of (CHAR . DEFINITION),\n\
96 which binds the character CHAR to DEFINITION, or (SYMBOL . DEFINITION),\n\
97 which binds the function key or mouse event SYMBOL to DEFINITION.\n\
98 Initially the alist is nil.")
101 return Fcons (Qkeymap
, Qnil
);
104 /* This function is used for installing the standard key bindings
105 at initialization time.
109 initial_define_key (control_x_map, Ctl('X'), "exchange-point-and-mark");
111 I haven't extended these to allow the initializing code to bind
112 function keys and mouse events; since they are called by many files,
113 I'd have to fix lots of callers, and nobody right now would be using
114 the new functionality, so it seems like a waste of time. But there's
115 no technical reason not to. -JimB */
118 initial_define_key (keymap
, key
, defname
)
123 store_in_keymap (keymap
, make_number (key
), intern (defname
));
126 /* Define character fromchar in map frommap as an alias for character
127 tochar in map tomap. Subsequent redefinitions of the latter WILL
128 affect the former. */
132 synkey (frommap
, fromchar
, tomap
, tochar
)
133 struct Lisp_Vector
*frommap
, *tomap
;
134 int fromchar
, tochar
;
137 XSET (v
, Lisp_Vector
, tomap
);
138 XFASTINT (c
) = tochar
;
139 frommap
->contents
[fromchar
] = Fcons (v
, c
);
143 DEFUN ("keymapp", Fkeymapp
, Skeymapp
, 1, 1, 0,
144 "Return t if ARG is a keymap.\n\
146 A keymap is list (keymap . ALIST), a list (keymap VECTOR . ALIST),\n\
147 or a symbol whose function definition is a keymap is itself a keymap.\n\
148 ALIST elements look like (CHAR . DEFN) or (SYMBOL . DEFN);\n\
149 VECTOR is a 128-element vector of bindings for ASCII characters.")
153 return (NULL (get_keymap_1 (object
, 0)) ? Qnil
: Qt
);
156 /* Check that OBJECT is a keymap (after dereferencing through any
157 symbols). If it is, return it; otherwise, return nil, or signal an
158 error if ERROR != 0. */
160 get_keymap_1 (object
, error
)
164 register Lisp_Object tem
;
167 while (XTYPE (tem
) == Lisp_Symbol
&& !EQ (tem
, Qunbound
))
169 tem
= XSYMBOL (tem
)->function
;
172 if (CONSP (tem
) && EQ (XCONS (tem
)->car
, Qkeymap
))
175 wrong_type_argument (Qkeymapp
, object
);
183 return get_keymap_1 (object
, 1);
187 /* If KEYMAP is a dense keymap, return the vector from its cadr.
188 Otherwise, return nil. */
191 keymap_table (keymap
)
196 if (CONSP (XCONS (keymap
)->cdr
)
197 && XTYPE (cadr
= XCONS (XCONS (keymap
)->cdr
)->car
) == Lisp_Vector
198 && XVECTOR (cadr
)->size
== DENSE_TABLE_SIZE
)
205 /* Look up IDX in MAP. IDX may be any sort of event.
206 Note that this does only one level of lookup; IDX must
207 be a single event, not a sequence. */
210 access_keymap (map
, idx
)
214 /* If idx is a list (some sort of mouse click, perhaps?),
215 the index we want to use is the car of the list, which
216 ought to be a symbol. */
217 if (XTYPE (idx
) == Lisp_Cons
)
218 idx
= XCONS (idx
)->car
;
220 if (XTYPE (idx
) == Lisp_Int
221 && (XINT (idx
) < 0 || XINT (idx
) >= DENSE_TABLE_SIZE
))
222 error ("Command key is not an ASCII character");
225 Lisp_Object table
= keymap_table (map
);
227 /* A dense keymap indexed by a character? */
228 if (XTYPE (idx
) == Lisp_Int
230 return XVECTOR (table
)->contents
[XFASTINT (idx
)];
232 /* This lookup will not involve a vector reference. */
235 /* If idx is a symbol, it might have modifiers, which need to
236 be put in the canonical order. */
237 if (XTYPE (idx
) == Lisp_Symbol
)
238 idx
= reorder_modifiers (idx
);
240 return Fcdr (Fassq (idx
, map
));
245 /* Given OBJECT which was found in a slot in a keymap,
246 trace indirect definitions to get the actual definition of that slot.
247 An indirect definition is a list of the form
248 (KEYMAP . INDEX), where KEYMAP is a keymap or a symbol defined as one
249 and INDEX is the object to look up in KEYMAP to yield the definition.
251 Also if OBJECT has a menu string as the first element,
256 register Lisp_Object object
;
260 register Lisp_Object map
, tem
;
262 map
= get_keymap_1 (Fcar_safe (object
), 0);
263 tem
= Fkeymapp (map
);
265 /* If the contents are (KEYMAP . ELEMENT), go indirect. */
267 object
= access_keymap (map
, Fcdr (object
));
269 /* If the keymap contents looks like (STRING . DEFN),
271 Keymap alist elements like (CHAR MENUSTRING . DEFN)
272 will be used by HierarKey menus. */
273 else if (XTYPE (object
) == Lisp_Cons
274 && XTYPE (XCONS (object
)->car
) == Lisp_String
)
275 object
= XCONS (object
)->cdr
;
278 /* Anything else is really the value. */
284 store_in_keymap (keymap
, idx
, def
)
286 register Lisp_Object idx
;
287 register Lisp_Object def
;
289 /* If idx is a list (some sort of mouse click, perhaps?),
290 the index we want to use is the car of the list, which
291 ought to be a symbol. */
292 if (XTYPE (idx
) == Lisp_Cons
)
295 if (XTYPE (idx
) == Lisp_Int
296 && (XINT (idx
) < 0 || XINT (idx
) >= DENSE_TABLE_SIZE
))
297 error ("Command key is a character outside of the ASCII set.");
300 Lisp_Object table
= keymap_table (keymap
);
302 /* A dense keymap indexed by a character? */
303 if (XTYPE (idx
) == Lisp_Int
&& !NULL (table
))
304 XVECTOR (table
)->contents
[XFASTINT (idx
)] = def
;
306 /* Must be a sparse keymap, or a dense keymap indexed by a symbol. */
309 /* Point to the pointer to the start of the assoc-list part
311 register Lisp_Object
*assoc_head
313 ? & XCONS (keymap
)->cdr
314 : & XCONS (XCONS (keymap
)->cdr
)->cdr
);
315 register Lisp_Object defining_pair
;
317 /* If idx is a symbol, it might have modifiers, which need to
318 be put in the canonical order. */
319 if (XTYPE (idx
) == Lisp_Symbol
)
320 idx
= reorder_modifiers (idx
);
322 /* Point to the pair where idx is bound, if any. */
323 defining_pair
= Fassq (idx
, *assoc_head
);
325 if (NULL (defining_pair
))
326 *assoc_head
= Fcons (Fcons (idx
, def
), *assoc_head
);
328 Fsetcdr (defining_pair
, def
);
335 DEFUN ("copy-keymap", Fcopy_keymap
, Scopy_keymap
, 1, 1, 0,
336 "Return a copy of the keymap KEYMAP.\n\
337 The copy starts out with the same definitions of KEYMAP,\n\
338 but changing either the copy or KEYMAP does not affect the other.\n\
339 Any key definitions that are subkeymaps are recursively copied.\n\
340 However, a key definition which is a symbol whose definition is a keymap\n\
345 register Lisp_Object copy
, tail
;
347 copy
= Fcopy_alist (get_keymap (keymap
));
348 tail
= XCONS (copy
)->cdr
;
350 /* If this is a dense keymap, copy the vector. */
353 register Lisp_Object table
= XCONS (tail
)->car
;
355 if (XTYPE (table
) == Lisp_Vector
356 && XVECTOR (table
)->size
== DENSE_TABLE_SIZE
)
360 table
= Fcopy_sequence (table
);
362 for (i
= 0; i
< DENSE_TABLE_SIZE
; i
++)
363 if (XTYPE (XVECTOR (copy
)->contents
[i
]) != Lisp_Symbol
)
364 if (! NULL (Fkeymapp (XVECTOR (table
)->contents
[i
])))
365 XVECTOR (table
)->contents
[i
]
366 = Fcopy_keymap (XVECTOR (table
)->contents
[i
]);
367 XCONS (tail
)->car
= table
;
369 tail
= XCONS (tail
)->cdr
;
373 /* Copy the alist portion of the keymap. */
376 register Lisp_Object elt
;
378 elt
= XCONS (tail
)->car
;
380 && XTYPE (XCONS (elt
)->cdr
) != Lisp_Symbol
381 && ! NULL (Fkeymapp (XCONS (elt
)->cdr
)))
382 XCONS (elt
)->cdr
= Fcopy_keymap (XCONS (elt
)->cdr
);
384 tail
= XCONS (tail
)->cdr
;
390 DEFUN ("define-key", Fdefine_key
, Sdefine_key
, 3, 3, 0,
391 "Args KEYMAP, KEY, DEF. Define key sequence KEY, in KEYMAP, as DEF.\n\
392 KEYMAP is a keymap. KEY is a string or a vector of symbols and characters\n\
393 meaning a sequence of keystrokes and events.\n\
394 DEF is anything that can be a key's definition:\n\
395 nil (means key is undefined in this keymap),\n\
396 a command (a Lisp function suitable for interactive calling)\n\
397 a string (treated as a keyboard macro),\n\
398 a keymap (to define a prefix key),\n\
399 a symbol. When the key is looked up, the symbol will stand for its\n\
400 function definition, which should at that time be one of the above,\n\
401 or another symbol whose function definition is used, etc.\n\
402 a cons (STRING . DEFN), meaning that DEFN is the definition\n\
403 (DEFN should be a valid definition in its own right),\n\
404 or a cons (KEYMAP . CHAR), meaning use definition of CHAR in map KEYMAP.\n\
406 If KEYMAP is a sparse keymap, the pair binding KEY to DEF is added at\n\
407 the front of KEYMAP.")
409 register Lisp_Object keymap
;
414 register Lisp_Object c
;
415 register Lisp_Object tem
;
416 register Lisp_Object cmd
;
420 keymap
= get_keymap (keymap
);
422 if (XTYPE (key
) != Lisp_Vector
423 && XTYPE (key
) != Lisp_String
)
424 key
= wrong_type_argument (Qarrayp
, key
);
426 length
= Flength (key
);
433 c
= Faref (key
, make_number (idx
));
435 if (XTYPE (c
) == Lisp_Int
439 c
= meta_prefix_char
;
444 if (XTYPE (c
) == Lisp_Int
)
445 XSETINT (c
, XINT (c
) & 0177);
452 return store_in_keymap (keymap
, c
, def
);
454 cmd
= get_keyelt (access_keymap (keymap
, c
));
458 cmd
= Fmake_sparse_keymap ();
459 store_in_keymap (keymap
, c
, cmd
);
462 tem
= Fkeymapp (cmd
);
464 error ("Key sequence %s uses invalid prefix characters",
465 XSTRING (key
)->data
);
467 keymap
= get_keymap (cmd
);
471 /* Value is number if KEY is too long; NIL if valid but has no definition. */
473 DEFUN ("lookup-key", Flookup_key
, Slookup_key
, 2, 2, 0,
474 "In keymap KEYMAP, look up key sequence KEY. Return the definition.\n\
475 nil means undefined. See doc of `define-key' for kinds of definitions.\n\
476 A number as value means KEY is \"too long\";\n\
477 that is, characters or symbols in it except for the last one\n\
478 fail to be a valid sequence of prefix characters in KEYMAP.\n\
479 The number is how many characters at the front of KEY\n\
480 it takes to reach a non-prefix command.")
482 register Lisp_Object keymap
;
486 register Lisp_Object tem
;
487 register Lisp_Object cmd
;
488 register Lisp_Object c
;
492 keymap
= get_keymap (keymap
);
494 if (XTYPE (key
) != Lisp_Vector
495 && XTYPE (key
) != Lisp_String
)
496 key
= wrong_type_argument (Qarrayp
, key
);
498 length
= Flength (key
);
505 c
= Faref (key
, make_number (idx
));
507 if (XTYPE (c
) == Lisp_Int
511 c
= meta_prefix_char
;
516 if (XTYPE (c
) == Lisp_Int
)
517 XSETINT (c
, XINT (c
) & 0177);
523 cmd
= get_keyelt (access_keymap (keymap
, c
));
527 tem
= Fkeymapp (cmd
);
529 return make_number (idx
);
531 keymap
= get_keymap (cmd
);
536 /* Append a key to the end of a key sequence. If key_sequence is a
537 string and key is a character, the result will be another string;
538 otherwise, it will be a vector. */
540 append_key (key_sequence
, key
)
541 Lisp_Object key_sequence
, key
;
545 args
[0] = key_sequence
;
547 if (XTYPE (key_sequence
) == Lisp_String
548 && XTYPE (key
) == Lisp_Int
)
550 args
[1] = Fchar_to_string (key
);
551 return Fconcat (2, args
);
555 args
[1] = Fcons (key
, Qnil
);
556 return Fvconcat (2, args
);
561 DEFUN ("key-binding", Fkey_binding
, Skey_binding
, 1, 1, 0,
562 "Return the binding for command KEY in current keymaps.\n\
563 KEY is a string, a sequence of keystrokes.\n\
564 The binding is probably a symbol with a function definition.")
568 register Lisp_Object map
, value
, value1
;
569 map
= current_buffer
->keymap
;
572 value
= Flookup_key (map
, key
);
575 value1
= Flookup_key (current_global_map
, key
);
576 if (XTYPE (value1
) == Lisp_Int
)
580 else if (XTYPE (value
) != Lisp_Int
)
583 return Flookup_key (current_global_map
, key
);
586 DEFUN ("local-key-binding", Flocal_key_binding
, Slocal_key_binding
, 1, 1, 0,
587 "Return the binding for command KEYS in current local keymap only.\n\
588 KEYS is a string, a sequence of keystrokes.\n\
589 The binding is probably a symbol with a function definition.")
593 register Lisp_Object map
;
594 map
= current_buffer
->keymap
;
597 return Flookup_key (map
, keys
);
600 DEFUN ("global-key-binding", Fglobal_key_binding
, Sglobal_key_binding
, 1, 1, 0,
601 "Return the binding for command KEYS in current global keymap only.\n\
602 KEYS is a string, a sequence of keystrokes.\n\
603 The binding is probably a symbol with a function definition.")
607 return Flookup_key (current_global_map
, keys
);
610 DEFUN ("global-set-key", Fglobal_set_key
, Sglobal_set_key
, 2, 2,
611 "kSet key globally: \nCSet key %s to command: ",
612 "Give KEY a global binding as COMMAND.\n\
613 COMMAND is a symbol naming an interactively-callable function.\n\
614 KEY is a string representing a sequence of keystrokes.\n\
615 Note that if KEY has a local binding in the current buffer\n\
616 that local binding will continue to shadow any global binding.")
618 Lisp_Object keys
, function
;
620 if (XTYPE (keys
) != Lisp_Vector
621 && XTYPE (keys
) != Lisp_String
)
622 keys
= wrong_type_argument (Qarrayp
, keys
);
624 Fdefine_key (current_global_map
, keys
, function
);
628 DEFUN ("local-set-key", Flocal_set_key
, Slocal_set_key
, 2, 2,
629 "kSet key locally: \nCSet key %s locally to command: ",
630 "Give KEY a local binding as COMMAND.\n\
631 COMMAND is a symbol naming an interactively-callable function.\n\
632 KEY is a string representing a sequence of keystrokes.\n\
633 The binding goes in the current buffer's local map,\n\
634 which is shared with other buffers in the same major mode.")
636 Lisp_Object keys
, function
;
638 register Lisp_Object map
;
639 map
= current_buffer
->keymap
;
642 map
= Fmake_sparse_keymap ();
643 current_buffer
->keymap
= map
;
646 if (XTYPE (keys
) != Lisp_Vector
647 && XTYPE (keys
) != Lisp_String
)
648 keys
= wrong_type_argument (Qarrayp
, keys
);
650 Fdefine_key (map
, keys
, function
);
654 DEFUN ("global-unset-key", Fglobal_unset_key
, Sglobal_unset_key
,
655 1, 1, "kUnset key globally: ",
656 "Remove global binding of KEY.\n\
657 KEY is a string representing a sequence of keystrokes.")
661 return Fglobal_set_key (keys
, Qnil
);
664 DEFUN ("local-unset-key", Flocal_unset_key
, Slocal_unset_key
, 1, 1,
665 "kUnset key locally: ",
666 "Remove local binding of KEY.\n\
667 KEY is a string representing a sequence of keystrokes.")
671 if (!NULL (current_buffer
->keymap
))
672 Flocal_set_key (keys
, Qnil
);
676 DEFUN ("define-prefix-command", Fdefine_prefix_command
, Sdefine_prefix_command
, 1, 2, 0,
677 "Define COMMAND as a prefix command.\n\
678 A new sparse keymap is stored as COMMAND's function definition and its value.\n\
679 If a second optional argument MAPVAR is given, the map is stored as\n\
680 its value instead of as COMMAND's value; but COMMAND is still defined\n\
683 Lisp_Object name
, mapvar
;
686 map
= Fmake_sparse_keymap ();
695 DEFUN ("use-global-map", Fuse_global_map
, Suse_global_map
, 1, 1, 0,
696 "Select KEYMAP as the global keymap.")
700 keymap
= get_keymap (keymap
);
701 current_global_map
= keymap
;
705 DEFUN ("use-local-map", Fuse_local_map
, Suse_local_map
, 1, 1, 0,
706 "Select KEYMAP as the local keymap.\n\
707 If KEYMAP is nil, that means no local keymap.")
712 keymap
= get_keymap (keymap
);
714 current_buffer
->keymap
= keymap
;
719 DEFUN ("current-local-map", Fcurrent_local_map
, Scurrent_local_map
, 0, 0, 0,
720 "Return current buffer's local keymap, or nil if it has none.")
723 return current_buffer
->keymap
;
726 DEFUN ("current-global-map", Fcurrent_global_map
, Scurrent_global_map
, 0, 0, 0,
727 "Return the current global keymap.")
730 return current_global_map
;
733 DEFUN ("accessible-keymaps", Faccessible_keymaps
, Saccessible_keymaps
,
735 "Find all keymaps accessible via prefix characters from KEYMAP.\n\
736 Returns a list of elements of the form (KEYS . MAP), where the sequence\n\
737 KEYS starting from KEYMAP gets you to MAP. These elements are ordered\n\
738 so that the KEYS increase in length. The first element is (\"\" . KEYMAP).")
740 Lisp_Object startmap
;
742 Lisp_Object maps
, tail
;
744 maps
= Fcons (Fcons (build_string (""), get_keymap (startmap
)), Qnil
);
747 /* For each map in the list maps,
748 look at any other maps it points to,
749 and stick them at the end if they are not already in the list.
751 This is a breadth-first traversal, where tail is the queue of
752 nodes, and maps accumulates a list of all nodes visited. */
756 register Lisp_Object thisseq
= Fcar (Fcar (tail
));
757 register Lisp_Object thismap
= Fcdr (Fcar (tail
));
758 Lisp_Object last
= make_number (XINT (Flength (thisseq
)) - 1);
760 /* Does the current sequence end in the meta-prefix-char? */
761 int is_metized
= (XINT (last
) >= 0
762 && EQ (Faref (thisseq
, last
), meta_prefix_char
));
764 /* Skip the 'keymap element of the list. */
765 thismap
= Fcdr (thismap
);
769 register Lisp_Object table
= XCONS (thismap
)->car
;
771 if (XTYPE (table
) == Lisp_Vector
)
775 /* Vector keymap. Scan all the elements. */
776 for (i
= 0; i
< DENSE_TABLE_SIZE
; i
++)
778 register Lisp_Object tem
;
779 register Lisp_Object cmd
;
781 cmd
= get_keyelt (XVECTOR (table
)->contents
[i
]);
782 if (NULL (cmd
)) continue;
783 tem
= Fkeymapp (cmd
);
786 cmd
= get_keymap (cmd
);
787 /* Ignore keymaps that are already added to maps. */
788 tem
= Frassq (cmd
, maps
);
791 /* If the last key in thisseq is meta-prefix-char,
792 turn it into a meta-ized keystroke. We know
793 that the event we're about to append is an
797 tem
= Fcopy_sequence (thisseq
);
798 Faset (tem
, last
, make_number (i
| 0200));
800 /* This new sequence is the same length as
801 thisseq, so stick it in the list right
804 Fcons (Fcons (tem
, cmd
), XCONS (tail
)->cdr
);
808 tem
= append_key (thisseq
, make_number (i
));
809 nconc2 (tail
, Fcons (Fcons (tem
, cmd
), Qnil
));
815 /* Once finished with the lookup elements of the dense
816 keymap, go on to scan its assoc list. */
817 thismap
= XCONS (thismap
)->cdr
;
821 /* The rest is an alist. Scan all the alist elements. */
822 while (CONSP (thismap
))
824 Lisp_Object elt
= XCONS (thismap
)->car
;
826 /* Ignore elements that are not conses. */
829 register Lisp_Object cmd
= get_keyelt (XCONS (elt
)->cdr
);
830 register Lisp_Object tem
;
832 /* Ignore definitions that aren't keymaps themselves. */
833 tem
= Fkeymapp (cmd
);
836 /* Ignore keymaps that have been seen already. */
837 cmd
= get_keymap (cmd
);
838 tem
= Frassq (cmd
, maps
);
841 /* let elt be the event defined by this map entry. */
842 elt
= XCONS (elt
)->car
;
844 /* If the last key in thisseq is meta-prefix-char, and
845 this entry is a binding for an ascii keystroke,
846 turn it into a meta-ized keystroke. */
847 if (is_metized
&& XTYPE (elt
) == Lisp_Int
)
849 tem
= Fcopy_sequence (thisseq
);
850 Faset (tem
, last
, make_number (XINT (elt
) | 0200));
852 /* This new sequence is the same length as
853 thisseq, so stick it in the list right
856 Fcons (Fcons (tem
, cmd
), XCONS (tail
)->cdr
);
860 Fcons (Fcons (append_key (thisseq
, elt
), cmd
),
866 thismap
= XCONS (thismap
)->cdr
;
875 Lisp_Object Qsingle_key_description
, Qkey_description
;
877 DEFUN ("key-description", Fkey_description
, Skey_description
, 1, 1, 0,
878 "Return a pretty description of key-sequence KEYS.\n\
879 Control characters turn into \"C-foo\" sequences, meta into \"M-foo\"\n\
880 spaces are put between sequence elements, etc.")
884 return Fmapconcat (Qsingle_key_description
, keys
, build_string (" "));
888 push_key_description (c
, p
)
889 register unsigned int c
;
906 else if (c
== Ctl('I'))
912 else if (c
== Ctl('J'))
918 else if (c
== Ctl('M'))
928 if (c
> 0 && c
<= Ctl ('Z'))
952 DEFUN ("single-key-description", Fsingle_key_description
, Ssingle_key_description
, 1, 1, 0,
953 "Return a pretty description of command character KEY.\n\
954 Control characters turn into C-whatever, etc.")
958 register unsigned char c
;
963 case Lisp_Int
: /* Normal character */
964 c
= XINT (key
) & 0377;
965 *push_key_description (c
, tem
) = 0;
966 return build_string (tem
);
968 case Lisp_Symbol
: /* Function key or event-symbol */
969 return Fsymbol_name (key
);
971 case Lisp_Cons
: /* Mouse event */
972 key
= XCONS (key
)->car
;
973 if (XTYPE (key
) == Lisp_Symbol
)
974 return Fsymbol_name (key
);
975 /* Mouse events should have an identifying symbol as their car;
976 fall through when this isn't the case. */
979 error ("KEY must be an integer, cons, or symbol.");
984 push_text_char_description (c
, p
)
985 register unsigned int c
;
997 *p
++ = c
+ 64; /* 'A' - 1 */
1009 DEFUN ("text-char-description", Ftext_char_description
, Stext_char_description
, 1, 1, 0,
1010 "Return a pretty description of file-character CHAR.\n\
1011 Control characters turn into \"^char\", etc.")
1017 CHECK_NUMBER (chr
, 0);
1019 *push_text_char_description (XINT (chr
) & 0377, tem
) = 0;
1021 return build_string (tem
);
1024 DEFUN ("where-is-internal", Fwhere_is_internal
, Swhere_is_internal
, 1, 5, 0,
1025 "Return list of keys that invoke DEFINITION in KEYMAP or KEYMAP1.\n\
1026 If KEYMAP is nil, search only KEYMAP1.\n\
1027 If KEYMAP1 is nil, use the current global map.\n\
1029 If optional 4th arg FIRSTONLY is non-nil,\n\
1030 return a string representing the first key sequence found,\n\
1031 rather than a list of all possible key sequences.\n\
1033 If optional 5th arg NOINDIRECT is non-nil, don't follow indirections\n\
1034 to other keymaps or slots. This makes it possible to search for an\n\
1035 indirect definition itself.")
1036 (definition
, local_keymap
, global_keymap
, firstonly
, noindirect
)
1037 Lisp_Object definition
, local_keymap
, global_keymap
;
1038 Lisp_Object firstonly
, noindirect
;
1040 register Lisp_Object maps
;
1043 if (NULL (global_keymap
))
1044 global_keymap
= current_global_map
;
1046 if (!NULL (local_keymap
))
1047 maps
= nconc2 (Faccessible_keymaps (get_keymap (local_keymap
)),
1048 Faccessible_keymaps (get_keymap (global_keymap
)));
1050 maps
= Faccessible_keymaps (get_keymap (global_keymap
));
1054 for (; !NULL (maps
); maps
= Fcdr (maps
))
1056 register this = Fcar (Fcar (maps
)); /* Key sequence to reach map */
1057 register map
= Fcdr (Fcar (maps
)); /* The map that it reaches */
1058 register dense_alist
;
1061 /* In order to fold [META-PREFIX-CHAR CHAR] sequences into
1062 [M-CHAR] sequences, check if last character of the sequence
1063 is the meta-prefix char. */
1064 Lisp_Object last
= make_number (XINT (Flength (this)) - 1);
1065 int last_is_meta
= (XINT (last
) >= 0
1066 && EQ (Faref (this, last
), meta_prefix_char
));
1068 /* Skip the 'keymap element of the list. */
1071 /* If the keymap is sparse, map traverses the alist to the end.
1073 If the keymap is dense, we set map to the vector and
1074 dense_alist to the assoc-list portion of the keymap. When we
1075 are finished dealing with the vector portion, we set map to
1076 dense_alist, and handle the rest like a sparse keymap. */
1077 if (XTYPE (XCONS (map
)->car
) == Lisp_Vector
)
1079 dense_alist
= XCONS (map
)->cdr
;
1080 map
= XCONS (map
)->car
;
1085 register Lisp_Object key
, binding
, sequence
;
1088 if (XTYPE (map
) == Lisp_Vector
)
1090 /* In a vector, look at each element. */
1091 binding
= XVECTOR (map
)->contents
[i
];
1095 /* If we've just finished scanning a vector, switch map to
1096 the assoc-list at the end of the vector. */
1097 if (i
>= DENSE_TABLE_SIZE
)
1100 else if (CONSP (map
))
1102 /* In an alist, ignore elements that aren't conses. */
1103 if (! CONSP (XCONS (map
)->car
))
1105 /* Ignore other elements. */
1109 binding
= Fcdr (Fcar (map
));
1110 key
= Fcar (Fcar (map
));
1116 /* Search through indirections unless that's not wanted. */
1117 if (NULL (noindirect
))
1118 binding
= get_keyelt (binding
);
1120 /* End this iteration if this element does not match
1123 if (XTYPE (definition
) == Lisp_Cons
)
1126 tem
= Fequal (binding
, definition
);
1131 if (!EQ (binding
, definition
))
1134 /* We have found a match.
1135 Construct the key sequence where we found it. */
1136 if (XTYPE (key
) == Lisp_Int
&& last_is_meta
)
1138 sequence
= Fcopy_sequence (this);
1139 Faset (sequence
, last
, make_number (XINT (key
) | 0200));
1142 sequence
= append_key (this, key
);
1144 /* Verify that this key binding is not shadowed by another
1145 binding for the same key, before we say it exists.
1147 Mechanism: look for local definition of this key and if
1148 it is defined and does not match what we found then
1151 Either nil or number as value from Flookup_key
1153 if (!NULL (local_keymap
))
1155 binding
= Flookup_key (local_keymap
, sequence
);
1156 if (!NULL (binding
) && XTYPE (binding
) != Lisp_Int
)
1158 if (XTYPE (definition
) == Lisp_Cons
)
1161 tem
= Fequal (binding
, definition
);
1166 if (!EQ (binding
, definition
))
1171 /* It is a true unshadowed match. Record it. */
1173 if (!NULL (firstonly
))
1175 found
= Fcons (sequence
, found
);
1178 return Fnreverse (found
);
1181 /* Return a string listing the keys and buttons that run DEFINITION. */
1184 where_is_string (definition
)
1185 Lisp_Object definition
;
1187 register Lisp_Object keys
, keys1
;
1189 keys
= Fwhere_is_internal (definition
,
1190 current_buffer
->keymap
, Qnil
, Qnil
, Qnil
);
1191 keys1
= Fmapconcat (Qkey_description
, keys
, build_string (", "));
1196 DEFUN ("where-is", Fwhere_is
, Swhere_is
, 1, 1, "CWhere is command: ",
1197 "Print message listing key sequences that invoke specified command.\n\
1198 Argument is a command definition, usually a symbol with a function definition.")
1200 Lisp_Object definition
;
1202 register Lisp_Object string
;
1204 CHECK_SYMBOL (definition
, 0);
1205 string
= where_is_string (definition
);
1207 if (XSTRING (string
)->size
)
1208 message ("%s is on %s", XSYMBOL (definition
)->name
->data
,
1209 XSTRING (string
)->data
);
1211 message ("%s is not on any key", XSYMBOL (definition
)->name
->data
);
1215 DEFUN ("describe-bindings", Fdescribe_bindings
, Sdescribe_bindings
, 0, 0, "",
1216 "Show a list of all defined keys, and their definitions.\n\
1217 The list is put in a buffer, which is displayed.")
1220 register Lisp_Object thisbuf
;
1221 XSET (thisbuf
, Lisp_Buffer
, current_buffer
);
1222 internal_with_output_to_temp_buffer ("*Help*",
1223 describe_buffer_bindings
,
1229 describe_buffer_bindings (descbuf
)
1230 Lisp_Object descbuf
;
1232 register Lisp_Object start1
, start2
;
1235 = "key binding\n--- -------\n";
1237 Fset_buffer (Vstandard_output
);
1239 start1
= XBUFFER (descbuf
)->keymap
;
1242 insert_string ("Local Bindings:\n");
1243 insert_string (heading
);
1244 describe_map_tree (start1
, 0, Qnil
, Qnil
);
1245 insert_string ("\n");
1248 insert_string ("Global Bindings:\n");
1249 insert_string (heading
);
1251 describe_map_tree (current_global_map
, 0, XBUFFER (descbuf
)->keymap
, Qnil
);
1253 Fset_buffer (descbuf
);
1257 /* Insert a desription of the key bindings in STARTMAP,
1258 followed by those of all maps reachable through STARTMAP.
1259 If PARTIAL is nonzero, omit certain "uninteresting" commands
1260 (such as `undefined').
1261 If SHADOW is non-nil, it is another map;
1262 don't mention keys which would be shadowed by it. */
1265 describe_map_tree (startmap
, partial
, shadow
)
1266 Lisp_Object startmap
, shadow
;
1269 register Lisp_Object elt
, sh
;
1271 struct gcpro gcpro1
;
1273 maps
= Faccessible_keymaps (startmap
);
1276 for (; !NULL (maps
); maps
= Fcdr (maps
))
1281 /* If there is no shadow keymap given, don't shadow. */
1285 /* If the sequence by which we reach this keymap is zero-length,
1286 then the shadow map for this keymap is just SHADOW. */
1287 else if ((XTYPE (sh
) == Lisp_String
1288 && XSTRING (sh
)->size
== 0)
1289 || (XTYPE (sh
) == Lisp_Vector
1290 && XVECTOR (sh
)->size
== 0))
1293 /* If the sequence by which we reach this keymap actually has
1294 some elements, then the sequence's definition in SHADOW is
1295 what we should use. */
1298 sh
= Flookup_key (shadow
, Fcar (elt
));
1299 if (XTYPE (sh
) == Lisp_Int
)
1303 /* If sh is null (meaning that the current map is not shadowed),
1304 or a keymap (meaning that bindings from the current map might
1305 show through), describe the map. Otherwise, sh is a command
1306 that completely shadows the current map, and we shouldn't
1308 if (NULL (sh
) || !NULL (Fkeymapp (sh
)))
1309 describe_map (Fcdr (elt
), Fcar (elt
), partial
, sh
);
1316 describe_command (definition
)
1317 Lisp_Object definition
;
1319 register Lisp_Object tem1
;
1321 Findent_to (make_number (16), make_number (1));
1323 if (XTYPE (definition
) == Lisp_Symbol
)
1325 XSET (tem1
, Lisp_String
, XSYMBOL (definition
)->name
);
1327 insert_string ("\n");
1331 tem1
= Fkeymapp (definition
);
1333 insert_string ("Prefix Command\n");
1335 insert_string ("??\n");
1339 /* Describe the contents of map MAP, assuming that this map itself is
1340 reached by the sequence of prefix keys KEYS (a string or vector).
1341 PARTIAL, SHADOW is as in `describe_map_tree' above. */
1344 describe_map (map
, keys
, partial
, shadow
)
1345 Lisp_Object map
, keys
;
1349 register Lisp_Object keysdesc
;
1351 if (!NULL (keys
) && Flength (keys
) > 0)
1352 keysdesc
= concat2 (Fkey_description (keys
),
1353 build_string (" "));
1357 /* Skip the 'keymap element of the list. */
1360 /* If this is a dense keymap, take care of the table. */
1362 && XTYPE (XCONS (map
)->car
) == Lisp_Vector
)
1364 describe_vector (XCONS (map
)->car
, keysdesc
, describe_command
,
1366 map
= XCONS (map
)->cdr
;
1369 /* Now map is an alist. */
1370 describe_alist (map
, keysdesc
, describe_command
, partial
, shadow
);
1373 /* Insert a description of ALIST into the current buffer.
1374 Note that ALIST is just a plain association list, not a keymap. */
1377 describe_alist (alist
, elt_prefix
, elt_describer
, partial
, shadow
)
1378 register Lisp_Object alist
;
1379 Lisp_Object elt_prefix
;
1380 int (*elt_describer
) ();
1385 Lisp_Object tem1
, tem2
= Qnil
;
1386 Lisp_Object suppress
;
1389 struct gcpro gcpro1
, gcpro2
, gcpro3
;
1392 suppress
= intern ("suppress-keymap");
1394 /* This vector gets used to present single keys to Flookup_key. Since
1395 that is done once per alist element, we don't want to cons up a
1396 fresh vector every time. */
1397 kludge
= Fmake_vector (make_number (1), Qnil
);
1399 GCPRO3 (elt_prefix
, tem2
, kludge
);
1401 for (; CONSP (alist
); alist
= Fcdr (alist
))
1404 tem1
= Fcar_safe (Fcar (alist
));
1405 tem2
= get_keyelt (Fcdr_safe (Fcar (alist
)));
1407 /* Don't show undefined commands or suppressed commands. */
1408 if (NULL (tem2
)) continue;
1409 if (XTYPE (tem2
) == Lisp_Symbol
&& partial
)
1411 this = Fget (tem2
, suppress
);
1416 /* Don't show a command that isn't really visible
1417 because a local definition of the same key shadows it. */
1423 XVECTOR (kludge
)->contents
[0] = tem1
;
1424 tem
= Flookup_key (shadow
, kludge
);
1425 if (!NULL (tem
)) continue;
1434 if (!NULL (elt_prefix
))
1435 insert1 (elt_prefix
);
1437 /* THIS gets the string to describe the character TEM1. */
1438 this = Fsingle_key_description (tem1
);
1441 /* Print a description of the definition of this character.
1442 elt_describer will take care of spacing out far enough
1443 for alignment purposes. */
1444 (*elt_describer
) (tem2
);
1451 describe_vector_princ (elt
)
1457 DEFUN ("describe-vector", Fdescribe_vector
, Sdescribe_vector
, 1, 1, 0,
1458 "Print on `standard-output' a description of contents of VECTOR.\n\
1459 This is text showing the elements of vector matched against indices.")
1463 CHECK_VECTOR (vector
, 0);
1464 describe_vector (vector
, Qnil
, describe_vector_princ
, 0, Qnil
, Qnil
);
1467 describe_vector (vector
, elt_prefix
, elt_describer
, partial
, shadow
)
1468 register Lisp_Object vector
;
1469 Lisp_Object elt_prefix
;
1470 int (*elt_describer
) ();
1476 Lisp_Object tem1
, tem2
;
1478 Lisp_Object suppress
;
1481 struct gcpro gcpro1
, gcpro2
, gcpro3
;
1485 /* This vector gets used to present single keys to Flookup_key. Since
1486 that is done once per vector element, we don't want to cons up a
1487 fresh vector every time. */
1488 kludge
= Fmake_vector (make_number (1), Qnil
);
1489 GCPRO3 (elt_prefix
, tem1
, kludge
);
1492 suppress
= intern ("suppress-keymap");
1494 for (i
= 0; i
< DENSE_TABLE_SIZE
; i
++)
1497 tem1
= get_keyelt (XVECTOR (vector
)->contents
[i
]);
1499 if (NULL (tem1
)) continue;
1501 /* Don't mention suppressed commands. */
1502 if (XTYPE (tem1
) == Lisp_Symbol
&& partial
)
1504 this = Fget (tem1
, suppress
);
1509 /* If this command in this map is shadowed by some other map,
1515 XVECTOR (kludge
)->contents
[0] = make_number (i
);
1516 tem
= Flookup_key (shadow
, kludge
);
1518 if (!NULL (tem
)) continue;
1527 /* Output the prefix that applies to every entry in this map. */
1528 if (!NULL (elt_prefix
))
1529 insert1 (elt_prefix
);
1531 /* Get the string to describe the character I, and print it. */
1532 XFASTINT (dummy
) = i
;
1534 /* THIS gets the string to describe the character DUMMY. */
1535 this = Fsingle_key_description (dummy
);
1538 /* Find all consecutive characters that have the same definition. */
1539 while (i
+ 1 < DENSE_TABLE_SIZE
1540 && (tem2
= get_keyelt (XVECTOR (vector
)->contents
[i
+1]),
1544 /* If we have a range of more than one character,
1545 print where the range reaches to. */
1547 if (i
!= XINT (dummy
))
1550 if (!NULL (elt_prefix
))
1551 insert1 (elt_prefix
);
1553 XFASTINT (dummy
) = i
;
1554 insert1 (Fsingle_key_description (dummy
));
1557 /* Print a description of the definition of this character.
1558 elt_describer will take care of spacing out far enough
1559 for alignment purposes. */
1560 (*elt_describer
) (tem1
);
1567 Lisp_Object apropos_predicate
;
1568 Lisp_Object apropos_accumulate
;
1571 apropos_accum (symbol
, string
)
1572 Lisp_Object symbol
, string
;
1574 register Lisp_Object tem
;
1576 tem
= Fstring_match (string
, Fsymbol_name (symbol
), Qnil
);
1577 if (!NULL (tem
) && !NULL (apropos_predicate
))
1578 tem
= call1 (apropos_predicate
, symbol
);
1580 apropos_accumulate
= Fcons (symbol
, apropos_accumulate
);
1583 DEFUN ("apropos-internal", Fapropos_internal
, Sapropos_internal
, 1, 2, 0,
1584 "Show all symbols whose names contain match for REGEXP.\n\
1585 If optional 2nd arg PRED is non-nil, (funcall PRED SYM) is done\n\
1586 for each symbol and a symbol is mentioned only if that returns non-nil.\n\
1587 Return list of symbols found.")
1589 Lisp_Object string
, pred
;
1591 struct gcpro gcpro1
, gcpro2
;
1592 CHECK_STRING (string
, 0);
1593 apropos_predicate
= pred
;
1594 GCPRO2 (apropos_predicate
, apropos_accumulate
);
1595 apropos_accumulate
= Qnil
;
1596 map_obarray (Vobarray
, apropos_accum
, string
);
1597 apropos_accumulate
= Fsort (apropos_accumulate
, Qstring_lessp
);
1599 return apropos_accumulate
;
1606 Qkeymap
= intern ("keymap");
1607 staticpro (&Qkeymap
);
1609 /* Initialize the keymaps standardly used.
1610 Each one is the value of a Lisp variable, and is also
1611 pointed to by a C variable */
1613 global_map
= Fmake_keymap ();
1614 Fset (intern ("global-map"), global_map
);
1616 meta_map
= Fmake_keymap ();
1617 Fset (intern ("esc-map"), meta_map
);
1618 Ffset (intern ("ESC-prefix"), meta_map
);
1620 control_x_map
= Fmake_keymap ();
1621 Fset (intern ("ctl-x-map"), control_x_map
);
1622 Ffset (intern ("Control-X-prefix"), control_x_map
);
1624 DEFVAR_LISP ("minibuffer-local-map", &Vminibuffer_local_map
,
1625 "Default keymap to use when reading from the minibuffer.");
1626 Vminibuffer_local_map
= Fmake_sparse_keymap ();
1628 DEFVAR_LISP ("minibuffer-local-ns-map", &Vminibuffer_local_ns_map
,
1629 "Local keymap for the minibuffer when spaces are not allowed.");
1630 Vminibuffer_local_ns_map
= Fmake_sparse_keymap ();
1632 DEFVAR_LISP ("minibuffer-local-completion-map", &Vminibuffer_local_completion_map
,
1633 "Local keymap for minibuffer input with completion.");
1634 Vminibuffer_local_completion_map
= Fmake_sparse_keymap ();
1636 DEFVAR_LISP ("minibuffer-local-must-match-map", &Vminibuffer_local_must_match_map
,
1637 "Local keymap for minibuffer input with completion, for exact match.");
1638 Vminibuffer_local_must_match_map
= Fmake_sparse_keymap ();
1640 current_global_map
= global_map
;
1642 Qsingle_key_description
= intern ("single-key-description");
1643 staticpro (&Qsingle_key_description
);
1645 Qkey_description
= intern ("key-description");
1646 staticpro (&Qkey_description
);
1648 Qkeymapp
= intern ("keymapp");
1649 staticpro (&Qkeymapp
);
1651 defsubr (&Skeymapp
);
1652 defsubr (&Smake_keymap
);
1653 defsubr (&Smake_sparse_keymap
);
1654 defsubr (&Scopy_keymap
);
1655 defsubr (&Skey_binding
);
1656 defsubr (&Slocal_key_binding
);
1657 defsubr (&Sglobal_key_binding
);
1658 defsubr (&Sglobal_set_key
);
1659 defsubr (&Slocal_set_key
);
1660 defsubr (&Sdefine_key
);
1661 defsubr (&Slookup_key
);
1662 defsubr (&Sglobal_unset_key
);
1663 defsubr (&Slocal_unset_key
);
1664 defsubr (&Sdefine_prefix_command
);
1665 defsubr (&Suse_global_map
);
1666 defsubr (&Suse_local_map
);
1667 defsubr (&Scurrent_local_map
);
1668 defsubr (&Scurrent_global_map
);
1669 defsubr (&Saccessible_keymaps
);
1670 defsubr (&Skey_description
);
1671 defsubr (&Sdescribe_vector
);
1672 defsubr (&Ssingle_key_description
);
1673 defsubr (&Stext_char_description
);
1674 defsubr (&Swhere_is_internal
);
1675 defsubr (&Swhere_is
);
1676 defsubr (&Sdescribe_bindings
);
1677 defsubr (&Sapropos_internal
);
1684 initial_define_key (global_map
, 033, "ESC-prefix");
1685 initial_define_key (global_map
, Ctl('X'), "Control-X-prefix");