Function: read-char-from-minibuffer

read-char-from-minibuffer is a byte-compiled function defined in subr.el.gz.

Signature

(read-char-from-minibuffer PROMPT &optional CHARS HISTORY)

Documentation

Read a character from the minibuffer, prompting for it with PROMPT.

Like read-char, but uses the minibuffer to read and return a character. Optional argument CHARS, if non-nil, should be a list of characters; the function will ignore any input that is not one of CHARS. Optional argument HISTORY, if non-nil, should be a symbol that specifies the history list variable to use for navigating in input history using M-p and M-n, with RET to select a character from history. If you bind the variable help-form to a non-nil value while calling this function, then pressing help-char causes it to evaluate help-form and display the result. There is no need to explicitly add help-char to CHARS; help-char is bound automatically to help-form-show.

Probably introduced at or before Emacs version 27.1.

Source Code

;; Defined in /usr/src/emacs/lisp/subr.el.gz
(defun read-char-from-minibuffer (prompt &optional chars history)
  "Read a character from the minibuffer, prompting for it with PROMPT.
Like `read-char', but uses the minibuffer to read and return a character.
Optional argument CHARS, if non-nil, should be a list of characters;
the function will ignore any input that is not one of CHARS.
Optional argument HISTORY, if non-nil, should be a symbol that
specifies the history list variable to use for navigating in input
history using `M-p' and `M-n', with `RET' to select a character from
history.
If you bind the variable `help-form' to a non-nil value
while calling this function, then pressing `help-char'
causes it to evaluate `help-form' and display the result.
There is no need to explicitly add `help-char' to CHARS;
`help-char' is bound automatically to `help-form-show'."
  (defvar empty-history)
  (let* ((empty-history '())
         (map (if (consp chars)
                  (or (gethash (list help-form (cons help-char chars))
                               read-char-from-minibuffer-map-hash)
                      (let ((map (make-sparse-keymap))
                            (msg help-form))
                        (set-keymap-parent map read-char-from-minibuffer-map)
                        ;; If we have a dynamically bound `help-form'
                        ;; here, then the `C-h' (i.e., `help-char')
                        ;; character should output that instead of
                        ;; being a command char.
                        (when help-form
                          (define-key map (vector help-char)
                            (lambda ()
                              (interactive)
                              (let ((help-form msg)) ; lexically bound msg
                                (help-form-show)))))
                        (dolist (char chars)
                          (define-key map (vector char)
                            #'read-char-from-minibuffer-insert-char))
                        (define-key map [remap self-insert-command]
                          #'read-char-from-minibuffer-insert-other)
                        (puthash (list help-form (cons help-char chars))
                                 map read-char-from-minibuffer-map-hash)
                        map))
                read-char-from-minibuffer-map))
         ;; Protect this-command when called from pre-command-hook (bug#45029)
         (this-command this-command)
         (result
          (read-from-minibuffer prompt nil map nil
                                (or history 'empty-history)))
         (char
          (if (> (length result) 0)
              ;; We have a string (with one character), so return the first one.
              (elt result 0)
            ;; The default value is RET.
            (when history (push "\r" (symbol-value history)))
            ?\r)))
    ;; Display the question with the answer.
    (message "%s%s" prompt (char-to-string char))
    char))