Info Catalog elisp: Keys in Documentation elisp: Documentation elisp: Help Functions

elisp: Describing Characters

 
 23.4 Describing Characters for Help Messages
 ============================================
 
 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.
 
  -- Function: key-description sequence &optional prefix
      This function returns a string containing the Emacs standard
      notation for the input events in SEQUENCE.  If PREFIX is non-‘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.  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-description’, below.
 
  -- Function: single-key-description event &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
      brackets.
 
           (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"
 
  -- Function: text-char-description character
      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
      character, whereas ‘single-key-description’ uses the 2**27 bit for
      Meta.
 
           (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"
 
  -- Command: read-kbd-macro string &optional need-vector
      This function is used mainly for operating on keyboard macros, but
      it can also be used as a rough inverse for ‘key-description’.  You
      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; Key Sequences.)  If
      NEED-VECTOR is non-‘nil’, the return value is always a vector.
 

Info Catalog elisp: Keys in Documentation elisp: Documentation elisp: Help Functions