master f216f38: Move read-char-from-minibuffer from simple.el to subr.el and document it.

[Juri Linkov]

branch: master
commit f216f38870c14ba995cd004b1e98c9f9ce8c2874
Author: Juri Linkov <address@hidden>
Commit: Juri Linkov <address@hidden>

    Move read-char-from-minibuffer from simple.el to subr.el and document it.
    
    * doc/lispref/minibuf.texi (Multiple Queries):
    Document read-char-from-minibuffer (bug#10477, bug#38076).
    
    * lisp/subr.el (read-char-history)
    (read-char-from-minibuffer-map)
    (read-char-from-minibuffer-map-hash)
    (read-char-from-minibuffer-insert-char)
    (read-char-from-minibuffer-insert-other, empty-history)
    (read-char-from-minibuffer): Move from simple.el to subr.el.
---
 doc/lispref/minibuf.texi | 12 ++++++++
 etc/NEWS                 |  1 +
 lisp/simple.el           | 70 ----------------------------------------------
 lisp/subr.el             | 72 ++++++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 85 insertions(+), 70 deletions(-)

diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index 41c87ce..c87723d 100644
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -2253,6 +2253,18 @@ Here is an example of using this function:
 @end lisp
 @end defun
 
+If you need a function to read a character like @code{read-char} or
+@code{read-char-choice} (@pxref{Reading One Event}) but using the
+minibuffer, use @code{read-char-from-minibuffer}.
+
+@defun read-char-from-minibuffer prompt &optional chars history
+This function uses the minibuffer to read and return a single
+character.  Optionally, it ignores any input that is not a member of
+@var{chars}, a list of accepted characters.  The @var{history}
+argument specifies the history list symbol to use; if is omitted or
+@code{nil}, it doesn't use the history.
+@end defun
+
 @node Reading a Password
 @section Reading a Password
 @cindex passwords, reading
diff --git a/etc/NEWS b/etc/NEWS
index 8356601..4134f7b 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -2573,6 +2573,7 @@ This macro works like 'progn', but messages how long it 
takes to
 evaluate the body forms.  The value of the last form is the return
 value.
 
++++
 ** New function 'read-char-from-minibuffer'.
 This function works like 'read-char', but uses 'read-from-minibuffer'
 to read a character, so it maintains a history that can be navigated
diff --git a/lisp/simple.el b/lisp/simple.el
index 6dc4e56..47d4adb 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -5174,76 +5174,6 @@ and KILLP is t if a prefix arg was specified."
     ;; Avoid warning about delete-backward-char
     (with-no-warnings (delete-backward-char n killp))))
 
-(defvar read-char-history nil
-  "The default history for the `read-char-from-minibuffer' function.")
-
-(defvar read-char-from-minibuffer-map
-  (let ((map (make-sparse-keymap)))
-    (set-keymap-parent map minibuffer-local-map)
-    (define-key map [remap self-insert-command]
-      'read-char-from-minibuffer-insert-char)
-    map)
-  "Keymap for the `read-char-from-minibuffer' function.")
-
-(defconst read-char-from-minibuffer-map-hash
-  (make-hash-table :weakness 'key :test 'equal))
-
-(defun read-char-from-minibuffer-insert-char ()
-  "Insert the character you type in the minibuffer and exit.
-Discard all previous input before inserting and exiting the minibuffer."
-  (interactive)
-  (delete-minibuffer-contents)
-  (insert last-command-event)
-  (exit-minibuffer))
-
-(defun read-char-from-minibuffer-insert-other ()
-  "Handle inserting of a character other than allowed.
-Display an error on trying to insert a disallowed character.
-Also discard all previous input in the minibuffer."
-  (interactive)
-  (delete-minibuffer-contents)
-  (ding)
-  (minibuffer-message "Wrong answer")
-  (sit-for 2))
-
-(defvar empty-history)
-
-(defun read-char-from-minibuffer (prompt &optional chars history)
-  "Read a character from the minibuffer, prompting for PROMPT.
-Like `read-char', but uses the minibuffer to read and return a character.
-When CHARS is non-nil, any input that is not one of CHARS is ignored.
-When HISTORY is a symbol, then allows navigating in a history.
-The navigation commands are `M-p' and `M-n', with `RET' to select
-a character from history."
-  (discard-input)
-  (let* ((empty-history '())
-         (map (if (consp chars)
-                  (or (gethash chars read-char-from-minibuffer-map-hash)
-                      (puthash chars
-                               (let ((map (make-sparse-keymap)))
-                                 (set-keymap-parent map 
read-char-from-minibuffer-map)
-                                 (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)
-                                 map)
-                               read-char-from-minibuffer-map-hash))
-                read-char-from-minibuffer-map))
-         (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))
-
 (defun zap-to-char (arg char)
   "Kill up to and including ARGth occurrence of CHAR.
 Case is ignored if `case-fold-search' is non-nil in the current buffer.
diff --git a/lisp/subr.el b/lisp/subr.el
index ea56b49..eaec223 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -2665,6 +2665,78 @@ floating point support."
            (push (cons t read) unread-command-events)
            nil))))))
 
+
+(defvar read-char-history nil
+  "The default history for the `read-char-from-minibuffer' function.")
+
+(defvar read-char-from-minibuffer-map
+  (let ((map (make-sparse-keymap)))
+    (set-keymap-parent map minibuffer-local-map)
+    (define-key map [remap self-insert-command]
+      'read-char-from-minibuffer-insert-char)
+    map)
+  "Keymap for the `read-char-from-minibuffer' function.")
+
+(defconst read-char-from-minibuffer-map-hash
+  (make-hash-table :weakness 'key :test 'equal))
+
+(defun read-char-from-minibuffer-insert-char ()
+  "Insert the character you type in the minibuffer and exit.
+Discard all previous input before inserting and exiting the minibuffer."
+  (interactive)
+  (delete-minibuffer-contents)
+  (insert last-command-event)
+  (exit-minibuffer))
+
+(defun read-char-from-minibuffer-insert-other ()
+  "Handle inserting of a character other than allowed.
+Display an error on trying to insert a disallowed character.
+Also discard all previous input in the minibuffer."
+  (interactive)
+  (delete-minibuffer-contents)
+  (ding)
+  (minibuffer-message "Wrong answer")
+  (sit-for 2))
+
+(defvar empty-history)
+
+(defun read-char-from-minibuffer (prompt &optional chars history)
+  "Read a character from the minibuffer, prompting for PROMPT.
+Like `read-char', but uses the minibuffer to read and return a character.
+When CHARS is non-nil, any input that is not one of CHARS is ignored.
+When HISTORY is a symbol, then allows navigating in a history.
+The navigation commands are `M-p' and `M-n', with `RET' to select
+a character from history."
+  (discard-input)
+  (let* ((empty-history '())
+         (map (if (consp chars)
+                  (or (gethash chars read-char-from-minibuffer-map-hash)
+                      (puthash chars
+                               (let ((map (make-sparse-keymap)))
+                                 (set-keymap-parent map 
read-char-from-minibuffer-map)
+                                 (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)
+                                 map)
+                               read-char-from-minibuffer-map-hash))
+                read-char-from-minibuffer-map))
+         (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))
+
+
 ;; Behind display-popup-menus-p test.
 (declare-function x-popup-dialog "menu.c" (position contents &optional header))