These functions convert events, key sequences, or characters to textual descriptions. These descriptions are useful for including arbitrary text characters or key sequences in messages, because they convert non-printing and whitespace characters to sequences of printing characters. The description of a non-whitespace printing character is the character itself.
key-descriptionsequence &optional prefix
This function returns a string containing the Emacs standard notation
for the input events in sequence. If prefix is
nil, it is a sequence of input events leading up to
sequence and is included in the return value. Both arguments
may be strings, vectors or lists. See Input Events, for more
information about valid events.
(key-description [?\M-3 delete]) ⇒ "M-3 <delete>"
(key-description [delete] "\M-3") ⇒ "M-3 <delete>"
See also the examples for
single-key-descriptionevent &optional no-angles
This function returns a string describing event in the standard Emacs notation for keyboard input. A normal printing character appears as itself, but a control character turns into a string starting with ‘C-’, a meta character turns into a string starting with ‘M-’, and space, tab, etc., appear as ‘SPC’, ‘TAB’, etc. A function key symbol appears inside angle brackets ‘<…>’. An event that is a list appears as the name of the symbol in the CAR of the list, inside angle brackets.
If the optional argument no-angles is non-
nil, the angle
brackets around function keys and event symbols are omitted; this is
for compatibility with old versions of Emacs which didn’t use the
(single-key-description ?\C-x) ⇒ "C-x"
(key-description "\C-x \M-y \n \t \r \f123") ⇒ "C-x SPC M-y SPC C-j SPC TAB SPC RET SPC C-l 1 2 3"
(single-key-description 'delete) ⇒ "<delete>"
(single-key-description 'C-mouse-1) ⇒ "<C-mouse-1>"
(single-key-description 'C-mouse-1 t) ⇒ "C-mouse-1"
This function returns a string describing character in the
standard Emacs notation for characters that appear in text—like
single-key-description, except that control characters are
represented with a leading caret (which is how control characters in
Emacs buffers are usually displayed). Another difference is that
text-char-description recognizes the 2**7 bit as the Meta
single-key-description uses the 2**27 bit
(text-char-description ?\C-c) ⇒ "^C"
(text-char-description ?\M-m) ⇒ "\xed"
(text-char-description ?\C-\M-m) ⇒ "\x8d"
(text-char-description (+ 128 ?m)) ⇒ "M-m"
(text-char-description (+ 128 ?\C-m)) ⇒ "M-^M"
read-kbd-macrostring &optional need-vector
This function is used mainly for operating on keyboard macros, but it
can also be used as a rough inverse for
call it with a string containing key descriptions, separated by spaces;
it returns a string or vector containing the corresponding events.
(This may or may not be a single valid key sequence, depending on what
events you use; see Key Sequences.) If need-vector is
nil, the return value is always a vector.