elisp: Text from Minibuffer
19.2 Reading Text Strings with the Minibuffer
=============================================
The most basic primitive for minibuffer input is ‘read-from-minibuffer’,
which can be used to read either a string or a Lisp object in textual
form. The function ‘read-regexp’ is used for reading regular
expressions (
Regular Expressions), which are a special kind of
string. There are also specialized functions for reading commands,
variables, file names, etc. (Completion).
In most cases, you should not call minibuffer input functions in the
middle of a Lisp function. Instead, do all minibuffer input as part of
reading the arguments for a command, in the ‘interactive’ specification.
Defining Commands.
-- Function: read-from-minibuffer prompt &optional initial keymap read
history default inherit-input-method
This function is the most general way to get input from the
minibuffer. By default, it accepts arbitrary text and returns it
as a string; however, if READ is non-‘nil’, then it uses ‘read’ to
convert the text into a Lisp object (Input Functions).
The first thing this function does is to activate a minibuffer and
display it with PROMPT (which must be a string) as the prompt.
Then the user can edit text in the minibuffer.
When the user types a command to exit the minibuffer,
‘read-from-minibuffer’ constructs the return value from the text in
the minibuffer. Normally it returns a string containing that text.
However, if READ is non-‘nil’, ‘read-from-minibuffer’ reads the
text and returns the resulting Lisp object, unevaluated. (
Input Functions, for information about reading.)
The argument DEFAULT specifies default values to make available
through the history commands. It should be a string, a list of
strings, or ‘nil’. The string or strings become the minibuffer’s
“future history”, available to the user with ‘M-n’.
If READ is non-‘nil’, then DEFAULT is also used as the input to
‘read’, if the user enters empty input. If DEFAULT is a list of
strings, the first string is used as the input. If DEFAULT is
‘nil’, empty input results in an ‘end-of-file’ error. However, in
the usual case (where READ is ‘nil’), ‘read-from-minibuffer’
ignores DEFAULT when the user enters empty input and returns an
empty string, ‘""’. In this respect, it differs from all the other
minibuffer input functions in this chapter.
If KEYMAP is non-‘nil’, that keymap is the local keymap to use in
the minibuffer. If KEYMAP is omitted or ‘nil’, the value of
‘minibuffer-local-map’ is used as the keymap. Specifying a keymap
is the most important way to customize the minibuffer for various
applications such as completion.
The argument HISTORY specifies a history list variable to use for
saving the input and for history commands used in the minibuffer.
It defaults to ‘minibuffer-history’. You can optionally specify a
starting position in the history list as well. Minibuffer
History.
If the variable ‘minibuffer-allow-text-properties’ is non-‘nil’,
then the string that is returned includes whatever text properties
were present in the minibuffer. Otherwise all the text properties
are stripped when the value is returned.
If the argument INHERIT-INPUT-METHOD is non-‘nil’, then the
Text Representations::) from whichever buffer was current before
entering the minibuffer.
Use of INITIAL is mostly deprecated; we recommend using a non-‘nil’
value only in conjunction with specifying a cons cell for HISTORY.
Initial Input.
-- Function: read-string prompt &optional initial history default
inherit-input-method
This function reads a string from the minibuffer and returns it.
The arguments PROMPT, INITIAL, HISTORY and INHERIT-INPUT-METHOD are
used as in ‘read-from-minibuffer’. The keymap used is
‘minibuffer-local-map’.
The optional argument DEFAULT is used as in ‘read-from-minibuffer’,
except that, if non-‘nil’, it also specifies a default value to
return if the user enters null input. As in ‘read-from-minibuffer’
it should be a string, a list of strings, or ‘nil’, which is
equivalent to an empty string. When DEFAULT is a string, that
string is the default value. When it is a list of strings, the
first string is the default value. (All these strings are
available to the user in the “future minibuffer history”.)
This function works by calling the ‘read-from-minibuffer’ function:
(read-string PROMPT INITIAL HISTORY DEFAULT INHERIT)
≡
(let ((value
(read-from-minibuffer PROMPT INITIAL nil nil
HISTORY DEFAULT INHERIT)))
(if (and (equal value "") DEFAULT)
(if (consp DEFAULT) (car DEFAULT) DEFAULT)
value))
-- Function: read-regexp prompt &optional defaults history
This function reads a regular expression as a string from the
minibuffer and returns it. If the minibuffer prompt string PROMPT
does not end in ‘:’ (followed by optional whitespace), the function
adds ‘: ’ to the end, preceded by the default return value (see
below), if that is non-empty.
The optional argument DEFAULTS controls the default value to return
if the user enters null input, and should be one of: a string;
‘nil’, which is equivalent to an empty string; a list of strings;
or a symbol.
If DEFAULTS is a symbol, ‘read-regexp’ consults the value of the
variable ‘read-regexp-defaults-function’ (see below), and if that
is non-‘nil’ uses it in preference to DEFAULTS. The value in this
case should be either:
− ‘regexp-history-last’, which means to use the first element of
the appropriate minibuffer history list (see below).
− A function of no arguments, whose return value (which should
be ‘nil’, a string, or a list of strings) becomes the value of
DEFAULTS.
‘read-regexp’ now ensures that the result of processing DEFAULTS is
a list (i.e., if the value is ‘nil’ or a string, it converts it to
a list of one element). To this list, ‘read-regexp’ then appends a
few potentially useful candidates for input. These are:
− The word or symbol at point.
− The last regexp used in an incremental search.
− The last string used in an incremental search.
− The last string or pattern used in query-replace commands.
The function now has a list of regular expressions that it passes
to ‘read-from-minibuffer’ to obtain the user’s input. The first
element of the list is the default result in case of empty input.
All elements of the list are available to the user as the “future
minibuffer history” list (future list (emacs)Minibuffer
History.).
The optional argument HISTORY, if non-‘nil’, is a symbol specifying
a minibuffer history list to use (Minibuffer History). If
it is omitted or ‘nil’, the history list defaults to
‘regexp-history’.
-- User Option: read-regexp-defaults-function
The function ‘read-regexp’ may use the value of this variable to
determine its list of default regular expressions. If non-‘nil’,
the value of this variable should be either:
− The symbol ‘regexp-history-last’.
− A function of no arguments that returns either ‘nil’, a
string, or a list of strings.
See ‘read-regexp’ above for details of how these values are used.
-- Variable: minibuffer-allow-text-properties
If this variable is ‘nil’, then ‘read-from-minibuffer’ and
‘read-string’ strip all text properties from the minibuffer input
before returning it. However, ‘read-no-blanks-input’ (see below),
as well as ‘read-minibuffer’ and related functions (Reading
Lisp Objects With the Minibuffer Object from Minibuffer.), and all
functions that do minibuffer input with completion, discard text
properties unconditionally, regardless of the value of this
variable.
-- Variable: minibuffer-local-map
This is the default local keymap for reading from the minibuffer.
By default, it makes the following bindings:
‘C-j’
‘exit-minibuffer’
<RET>
‘exit-minibuffer’
‘C-g’
‘abort-recursive-edit’
‘M-n’
<DOWN>
‘next-history-element’
‘M-p’
<UP>
‘previous-history-element’
‘M-s’
‘next-matching-history-element’
‘M-r’
‘previous-matching-history-element’
-- Function: read-no-blanks-input prompt &optional initial
inherit-input-method
This function reads a string from the minibuffer, but does not
allow whitespace characters as part of the input: instead, those
characters terminate the input. The arguments PROMPT, INITIAL, and
INHERIT-INPUT-METHOD are used as in ‘read-from-minibuffer’.
This is a simplified interface to the ‘read-from-minibuffer’
function, and passes the value of the ‘minibuffer-local-ns-map’
keymap as the KEYMAP argument for that function. Since the keymap
‘minibuffer-local-ns-map’ does not rebind ‘C-q’, it _is_ possible
to put a space into the string, by quoting it.
This function discards text properties, regardless of the value of
‘minibuffer-allow-text-properties’.
(read-no-blanks-input PROMPT INITIAL)
≡
(let (minibuffer-allow-text-properties)
(read-from-minibuffer PROMPT INITIAL minibuffer-local-ns-map))
-- Variable: minibuffer-local-ns-map
This built-in variable is the keymap used as the minibuffer local
keymap in the function ‘read-no-blanks-input’. By default, it
makes the following bindings, in addition to those of
‘minibuffer-local-map’:
<SPC>
‘exit-minibuffer’
<TAB>
‘exit-minibuffer’
‘?’
‘self-insert-and-exit’
Info Catalog
elisp: Intro to Minibuffers
elisp: Minibuffers
elisp: Object from Minibuffer