* lisp/textmodes/string-edit.el (read-string-from-buffer):
* lisp/simple.el (read-from-kill-ring, read-shell-command)
(read-signal-name):
* lisp/replace.el (read-regexp-case-fold-search):
* lisp/auth-source.el (read-passwd):
* lisp/subr.el (read-key, read-number):
* lisp/minibuffer.el (read-file-name, read-no-blanks-input):
* lisp/international/mule-cmds.el (read-multilingual-string):
* lisp/language/japan-util.el (read-hiragana-string):
* lisp/files-x.el (read-file-local-variable)
(read-file-local-variable-mode, read-file-local-variable-value):
* lisp/faces.el (read-face-font, read-face-name):
* lisp/simple.el (read-extended-command):
* lisp/env.el (read-envvar-name):
* lisp/files.el (read-directory-name):
* lisp/faces.el (read-color):
* lisp/international/mule-diag.el (read-charset):
* lisp/emacs-lisp/map-ynp.el (read-answer):
* src/coding.c (Fread_coding_system)
(Fread_non_nil_coding_system):
* src/minibuf.c (Fread_command, Fread_from_minibuffer):
* src/lread.c (Fread_char, Fread_char_exclusive, Fread_event): Doc
fixes.
(cherry picked from commit
59d1aac49dfdc49e34be5964f547db0cfa7e127b)
(defun read-answer (question answers)
"Read an answer either as a complete word or its character abbreviation.
Ask user a question and accept an answer from the list of possible answers.
+Return the long answer even when accepting short ones.
QUESTION should end in a space; this function adds a list of answers to it.
When `read-answer-short' is non-nil, accept short answers.
-Return a long answer even in case of accepting short ones.
-
When `use-dialog-box' is t, pop up a dialog window to get user input."
(let* ((short (if (eq read-answer-short 'auto)
(or use-short-answers
(defvar read-envvar-name-history nil)
(defun read-envvar-name (prompt &optional mustmatch)
- "Read environment variable name, prompting with PROMPT.
+ "Read and return an environment variable name string, prompting with PROMPT.
Optional second arg MUSTMATCH, if non-nil, means require existing envvar name.
If it is also not t, RET does not exit if it does non-null completion."
(completing-read prompt
(pattern &optional face frame maximum width))
(defun read-face-font (face &optional frame)
- "Read the name of a font for FACE on FRAME.
+ "Read and return the string name of the font for FACE on FRAME.
If optional argument FRAME is nil or omitted, use the selected frame."
(completing-read-case-insensitive
(format-message
(defun read-color (&optional prompt convert-to-RGB allow-empty-name msg
foreground face)
- "Read a color name or RGB triplet.
+ "Read a color name or RGB triplet, return a string, the color name or RGB.
Completion is available for color names, but not for RGB triplets.
RGB triplets have the form \"#RRGGBB\". Each of the R, G, and B
;;; Commands to add/delete file-local/directory-local variables.
(defun read-file-local-variable (prompt)
- "Read file-local variable using PROMPT and completion.
+ "Read the name of a file-local variable using PROMPT and completion.
+Return the symbol of the variable, or nil if the user entered empty or
+null name.
Intended to be used in the `interactive' spec of
`add-file-local-variable', `delete-file-local-variable',
`add-dir-local-variable', `delete-dir-local-variable'."
(and (stringp variable) (intern variable))))
(defun read-file-local-variable-value (variable)
- "Read value of file-local VARIABLE using completion.
+ "Read and return the value of a file-local VARIABLE using completion.
Intended to be used in the `interactive' spec of
`add-file-local-variable' and `add-dir-local-variable'."
(cond
default)))))
(defun read-file-local-variable-mode ()
- "Read per-directory file-local variable's mode using completion.
+ "Read the name of a per-directory file-local variable's mode using completion.
+Return the symbol of the variable, or nil if the user entered empty or
+null name.
Intended to be used in the `interactive' spec of
`add-dir-local-variable', `delete-dir-local-variable'."
(let* ((default (and (symbolp major-mode) (symbol-name major-mode)))
(defun read-multilingual-string (prompt &optional initial-input input-method)
"Read a multilingual string from minibuffer, prompting with string PROMPT.
+Return the string thus read.
The input method selected last time is activated in minibuffer.
If optional second argument INITIAL-INPUT is non-nil, insert it in the
minibuffer initially.
(defun read-charset (prompt &optional default-value initial-input)
"Read a character set from the minibuffer, prompting with string PROMPT.
It must be an Emacs character set listed in the variable `charset-list'.
+Return the charset as a symbol.
Optional arguments are DEFAULT-VALUE and INITIAL-INPUT.
DEFAULT-VALUE, if non-nil, is the default value.
;;;###autoload
(defun read-hiragana-string (prompt &optional initial-input)
"Read a Hiragana string from the minibuffer, prompting with string PROMPT.
-If non-nil, second arg INITIAL-INPUT is a string to insert before reading."
+If non-nil, second arg INITIAL-INPUT is a string to insert before reading.
+Return the string read from the minibuffer."
(read-multilingual-string prompt initial-input "japanese-hiragana"))
;;
(or result input))))
(defun read-regexp-case-fold-search (regexp)
- "Return a value for `case-fold-search' based on REGEXP and current settings.
+ "Return the value for `case-fold-search' based on REGEXP and current settings.
REGEXP is a string as returned by `read-regexp'."
(let ((fold (get-text-property 0 'case-fold regexp)))
(cond
"Hook run by `read-shell-command' when entering the minibuffer.")
(defun read-shell-command (prompt &optional initial-contents hist &rest args)
- "Read a shell command from the minibuffer.
+ "Read a shell command from the minibuffer, and return it as a string.
The arguments are the same as the ones of `read-from-minibuffer',
except READ and KEYMAP are missing and HIST defaults
to `shell-command-history'."
(defvar read-from-kill-ring-history)
(defun read-from-kill-ring (prompt)
"Read a `kill-ring' entry using completion and minibuffer history.
-PROMPT is a string to prompt with."
+PROMPT is a string to prompt with.
+Return the entry as a string."
;; `current-kill' updates `kill-ring' with a possible interprogram-paste
(current-kill 0)
(let* ((history-pos (when yank-from-kill-ring-rotate
(string= string ""))
(defun read-signal-name ()
- "Read a signal number or name."
+ "Read a signal number or name.
+Return the signal number, if the user entered a number, otherwise
+the signal symbol."
(let ((value
(completing-read "Signal code or name: "
(signal-names)
(defvar read-key-delay 0.01) ;Fast enough for 100Hz repeat rate, hopefully.
(defun read-key (&optional prompt disable-fallbacks)
- "Read a key from the keyboard.
+ "Read a key from the keyboard, return the event thus read.
Contrary to `read-event' this will not return a raw event but instead will
obey the input decoding and translations usually done by `read-key-sequence'.
So escape sequences and keyboard encoding are taken into account.
"The default history for the `read-number' function.")
(defun read-number (prompt &optional default hist)
- "Read a numeric value in the minibuffer, prompting with PROMPT.
+ "Read from the minibuffer and return a numeric value, prompting with PROMPT.
DEFAULT specifies a default value to return if the user just types RET.
For historical reasons, the value of DEFAULT is always inserted into
PROMPT, so it's recommended to use `format' instead of `format-prompt'
included in the resulting string. If nil, no prompt will be
inserted in the buffer.
+When the user exits recursive edit, this function returns the
+edited STRING.
+
Also see `string-edit'."
(string-edit
prompt
DEFUN ("read-non-nil-coding-system", Fread_non_nil_coding_system,
Sread_non_nil_coding_system, 1, 1, 0,
- doc: /* Read a coding system from the minibuffer, prompting with string PROMPT. */)
+ doc: /* Read a coding system from the minibuffer, prompting with string PROMPT.
+Return the symbol of the coding-system. */)
(Lisp_Object prompt)
{
Lisp_Object val;
DEFUN ("read-coding-system", Fread_coding_system, Sread_coding_system, 1, 2, 0,
doc: /* Read a coding system from the minibuffer, prompting with string PROMPT.
If the user enters null input, return second argument DEFAULT-CODING-SYSTEM.
+Return the coding-system's symbol, or nil if both the user input and
+DEFAULT-CODING-SYSTEM are empty or null.
Ignores case when completing coding systems (all Emacs coding systems
are lower-case). */)
(Lisp_Object prompt, Lisp_Object default_coding_system)
DEFUN ("read-char", Fread_char, Sread_char, 0, 3, 0,
doc: /* Read a character event from the command input (keyboard or macro).
-It is returned as a number.
+Return the character as a number.
If the event has modifiers, they are resolved and reflected in the
returned character code if possible (e.g. C-SPC yields 0 and C-a yields 97).
If some of the modifiers cannot be reflected in the character code, the
}
DEFUN ("read-event", Fread_event, Sread_event, 0, 3, 0,
- doc: /* Read an event object from the input stream.
+ doc: /* Read and return an event object from the input stream.
If you want to read non-character events, consider calling `read-key'
instead. `read-key' will decode events via `input-decode-map' that
DEFUN ("read-char-exclusive", Fread_char_exclusive, Sread_char_exclusive, 0, 3, 0,
doc: /* Read a character event from the command input (keyboard or macro).
-It is returned as a number. Non-character events are ignored.
+Return the character as a number. Non-character events are ignored.
If the event has modifiers, they are resolved and reflected in the
returned character code if possible (e.g. C-SPC yields 0 and C-a yields 97).
If some of the modifiers cannot be reflected in the character code, the
DEFUN ("read-from-minibuffer", Fread_from_minibuffer,
Sread_from_minibuffer, 1, 7, 0,
- doc: /* Read a string from the minibuffer, prompting with string PROMPT.
+ doc: /* Read and return a string from the minibuffer, prompting with string PROMPT.
The optional second arg INITIAL-CONTENTS is an obsolete alternative to
DEFAULT-VALUE. It normally should be nil in new code, except when
HIST is a cons. It is discussed in more detail below.
}
DEFUN ("read-command", Fread_command, Sread_command, 1, 2, 0,
- doc: /* Read the name of a command and return as a symbol.
+ doc: /* Read the name of a command and return it as a symbol.
Prompt with PROMPT. By default, return DEFAULT-VALUE or its first element
if it is a list. If DEFAULT-VALUE is omitted or nil, and the user enters
null input, return a symbol whose name is an empty string. */)
projects / emacs.git / commitdiff