Next: Object from Minibuffer, Previous: Intro to Minibuffers, Up: Minibuffers
Most often, the minibuffer is used to read text as a string. It can
also be used to read a Lisp object in textual form. The most basic
primitive for minibuffer input is read-from-minibuffer
; it can do
either one.
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 through the minibuffer. By default, it accepts arbitrary text and returns it as a string; however, if read is non-
nil
, then it usesread
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-string as the prompt. This value must be a string. 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 a default value to make available through the history commands. It should be a string, or
nil
. If read is non-nil
, then default is also used as the input toread
, if the user enters empty input. However, in the usual case (where read isnil
),read-from-minibuffer
does not return default when the user enters empty input; it returns an empty string,""
. In this respect, it is different 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 ornil
, the value ofminibuffer-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 hist specifies which history list variable to use for saving the input and for history commands used in the minibuffer. It defaults to
minibuffer-history
. See Minibuffer History.If the variable
minibuffer-allow-text-properties
is non-nil
, then the string which 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 minibuffer inherits the current input method (see Input Methods) and the setting ofenable-multibyte-characters
(see Text Representations) from whichever buffer was current before entering the minibuffer.If initial-contents is a string,
read-from-minibuffer
inserts it into the minibuffer, leaving point at the end, before the user starts to edit the text. The minibuffer appears with this text as its initial contents.Alternatively, initial-contents can be a cons cell of the form
(
string.
position)
. This means to insert string in the minibuffer but put point position characters from the beginning, rather than at the end.Usage note: The initial-contents argument and the default argument are two alternative features for more or less the same job. It does not make sense to use both features in a single call to
read-from-minibuffer
. In general, we recommend using default, since this permits the user to insert the default value when it is wanted, but does not burden the user with deleting it from the minibuffer on other occasions.
This function reads a string from the minibuffer and returns it. The arguments prompt and initial are used as in
read-from-minibuffer
. The keymap used isminibuffer-local-map
.The optional argument history, if non-nil, specifies a history list and optionally the initial position in the list. The optional argument default specifies a default value to return if the user enters null input; it should be a string. The optional argument inherit-input-method specifies whether to inherit the current buffer's input method.
This function is a simplified interface to 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 (equal value "") default value))
If this variable is
nil
, thenread-from-minibuffer
strips all text properties from the minibuffer input before returning it. Since all minibuffer input usesread-from-minibuffer
, this variable applies to all minibuffer input.Note that the completion functions discard text properties unconditionally, regardless of the value of this variable.
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
next-history-element
- M-p
previous-history-element
- M-r
next-matching-history-element
- M-s
previous-matching-history-element
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 theminibuffer-local-ns-map
keymap as the keymap argument for that function. Since the keymapminibuffer-local-ns-map
does not rebind C-q, it is possible to put a space into the string, by quoting it.(read-no-blanks-input prompt initial) == (read-from-minibuffer prompt initial minibuffer-local-ns-map)