Function: key-valid-p

key-valid-p is a byte-compiled function defined in keymap.el.gz.

Signature

(key-valid-p KEYS)

Documentation

Return non-nil if KEYS, a string, is a valid key sequence.

KEYS should be a string consisting of one or more key strokes, with a single space character separating one key stroke from another.

Each key stroke is either a single character, or the name of an event, surrounded by angle brackets <like-this>. In addition, any key stroke may be preceded by one or more modifier keys. Finally, a limited number of characters have a special shorthand syntax.

Here are some example of valid key sequences.

  "f" (the key f)
  "S o m" (a three-key sequence of the keys S, o and m)
  "C-c o" (a two-key sequence: the key c with the control modifier
                 followed by the key o)
  "H-<left>" (the function key named "left" with the hyper modifier)
  "M-RET" (the "return" key with a meta modifier)
  "C-M-<space>" (the "space" key with both the control and meta modifiers)

These are the characters that have special shorthand syntax: NUL, RET, TAB, LFD, ESC, SPC, DEL.

Modifiers have to be specified in this order:

   A-C-H-M-S-s

which is

   Alt-Control-Hyper-Meta-Shift-super

Other relevant functions are documented in the keymaps group.

View in manual

Probably introduced at or before Emacs version 29.1.

Shortdoc

;; keymaps
(key-valid-p "C-c C-c")
    => t
  (key-valid-p "C-cC-c")
    => nil

Source Code

;; Defined in /usr/src/emacs/lisp/keymap.el.gz
(defun key-valid-p (keys)
  "Return non-nil if KEYS, a string, is a valid key sequence.
KEYS should be a string consisting of one or more key strokes,
with a single space character separating one key stroke from another.

Each key stroke is either a single character, or the name of an
event, surrounded by angle brackets <like-this>.  In addition, any
key stroke may be preceded by one or more modifier keys.  Finally,
a limited number of characters have a special shorthand syntax.

Here are some example of valid key sequences.

  \"f\"           (the key `f')
  \"S o m\"       (a three-key sequence of the keys `S', `o' and `m')
  \"C-c o\"       (a two-key sequence: the key `c' with the control modifier
                 followed by the key `o')
  \"H-<left>\"    (the function key named \"left\" with the hyper modifier)
  \"M-RET\"       (the \"return\" key with a meta modifier)
  \"C-M-<space>\" (the \"space\" key with both the control and meta modifiers)

These are the characters that have special shorthand syntax:
NUL, RET, TAB, LFD, ESC, SPC, DEL.

Modifiers have to be specified in this order:

   A-C-H-M-S-s

which is

   Alt-Control-Hyper-Meta-Shift-super"
  (declare (pure t) (side-effect-free error-free))
  (let ((case-fold-search nil))
    (and
     (stringp keys)
     (string-match-p "\\`[^ ]+\\( [^ ]+\\)*\\'" keys)
     (save-match-data
       (catch 'exit
         (let ((prefixes
                "\\(A-\\)?\\(C-\\)?\\(H-\\)?\\(M-\\)?\\(S-\\)?\\(s-\\)?"))
           (dolist (key (split-string keys " "))
             ;; Every key might have these modifiers, and they should be
             ;; in this order.
             (when (string-match (concat "\\`" prefixes) key)
               (setq key (substring key (match-end 0))))
             (unless (or (and (= (length key) 1)
                              ;; Don't accept control characters as keys.
                              (not (< (aref key 0) ?\s))
                              ;; Don't accept Meta'd characters as keys.
                              (or (multibyte-string-p key)
                                  (not (<= 127 (aref key 0) 255))))
                         (and (string-match-p "\\`<[-_A-Za-z0-9]+>\\'" key)
                              ;; Don't allow <M-C-down>.
                              (= (progn
                                   (string-match
                                    (concat "\\`<" prefixes) key)
                                   (match-end 0))
                                 1))
                         (string-match-p
                          "\\`\\(NUL\\|RET\\|TAB\\|LFD\\|ESC\\|SPC\\|DEL\\)\\'"
                          key))
               ;; Invalid.
               (throw 'exit nil)))
           t))))))