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 (see Regular Expressions),
which are a special kind of string. There are also specialized
functions for reading commands, variables, file names, etc.
(see 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. See Defining Commands.
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 (see 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.
(See 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. In
addition, if the call provides completion (e.g., via the keymap
argument), the completion candidates are added to the “future
history” when the values in default are exhausted by M-n;
see minibuffer-default-add-function.
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. If history is the
symbol t, history is not recorded. You can optionally specify
a starting position in the history list as well. See 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.
The text properties in minibuffer-prompt-properties are applied
to the prompt. By default, this property list defines a face to use
for the prompt. This face, if present, is applied to the end of the
face list and merged before display.
If the user wants to completely control the look of the prompt, the
most convenient way to do that is to specify the default face
at the end of all face lists. For instance:
(read-from-minibuffer (concat (propertize "Bold" 'face '(bold default)) (propertize " and normal: " 'face '(default))))
If the argument inherit-input-method is non-nil, then the
minibuffer inherits the current input method (see Input Methods) and
the setting of enable-multibyte-characters (see 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. See Initial Input.
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))
If you have a long string (for instance, one that is several lines
long) that you wish to edit, using read-string may not be
ideal. In that case, popping to a new, normal buffer where the user
can edit the string may be more convenient, and you can use the
read-string-from-buffer function to do that.
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).
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 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 (see future list in The GNU Emacs Manual).
The optional argument history, if non-nil, is a symbol
specifying a minibuffer history list to use (see Minibuffer History). If it is omitted or nil, the history list defaults
to regexp-history.
The user can use the M-s c command to indicate whether case
folding should be on or off. If the user has used this command, the
returned string will have the text property case-fold set to
either fold or inhibit-fold. It is up to the caller of
read-regexp to actually use this value, and the convenience
function read-regexp-case-fold-search is provided for that. A
typical usage pattern here might look like:
(let* ((regexp (read-regexp "Search for: "))
(case-fold-search (read-regexp-case-fold-search regexp)))
(re-search-forward regexp))
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:
regexp-history-last.
nil, a string,
or a list of strings.
See read-regexp above for details of how these values are used.
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 (see Reading Lisp Objects With the Minibuffer), and all
functions that do minibuffer input with completion, remove the face
property unconditionally, regardless of the value of this variable.
If this variable is non-nil, most text properties on strings
from the completion table are preserved—but only on the part of the
strings that were completed.
(let ((minibuffer-allow-text-properties t))
(completing-read "String: " (list (propertize "foobar" 'data 'zot))))
=> #("foobar" 3 6 (data zot))
In this example, the user typed ‘foo’ and then hit the TAB key, so the text properties are only preserved on the last three characters.
This is the default local keymap for reading from the minibuffer. By default, it makes the following bindings:
exit-minibuffer
exit-minibuffer
minibuffer-beginning-of-buffer
abort-recursive-edit
next-history-element
previous-history-element
next-matching-history-element
previous-matching-history-element
The variable minibuffer-mode-map is an alias for this variable.
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))
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:
Format prompt with default value default according to the
minibuffer-default-prompt-format variable.
minibuffer-default-prompt-format is a format string (defaulting
to ‘" (default %s)"’ that says how the “default” bit in prompts
like ‘"Local filename (default somefile): "’ are to be formatted.
To allow the users to customize how this is displayed, code that prompts the user for a value (and has a default) should look something along the lines of this code snippet:
(read-file-name (format-prompt "Local filename" file) nil file)
If format-args is nil, prompt is used as a literal
string. If format-args is non-nil, prompt is used
as a format control string, and prompt and format-args are
passed to format (see Formatting Strings).
minibuffer-default-prompt-format can be ‘""’, in which
case no default values are displayed.
If default is nil, there is no default value, and
therefore no “default value” string is included in the result value.
If default is a non-nil list, the first element of the
list is used in the prompt.
Both prompt and minibuffer-default-prompt-format are run
through substitute-command-keys (see Substituting Key Bindings in Documentation).
If this option is non-nil (the default), getting input from the
minibuffer will restore, on exit, the window configurations of the frame
where the minibuffer was entered from and, if it is different, the frame
that owns the minibuffer window. This means that if, for example, a
user splits a window while getting input from the minibuffer on the same
frame, that split will be undone when exiting the minibuffer.
If this option is nil, no such restorations are done. Hence, the
window split mentioned above will persist after exiting the minibuffer.