In most ways, a minibuffer is a normal Emacs buffer. Most operations within a buffer, such as editing commands, work normally in a minibuffer. However, many operations for managing buffers do not apply to minibuffers. The name of a minibuffer always has the form *Minibuf-NUMBER*, and it cannot be changed. Minibuffers are displayed only in special windows used only for minibuffers; these windows always appear at the bottom of a frame. (Sometimes frames have no minibuffer window, and sometimes a special kind of frame contains nothing but a minibuffer window; see Minibuffers and Frames.) The text in the minibuffer always starts with the prompt string, the text that was specified by the program that is using the minibuffer to tell the user what sort of input to type. This text is marked read-only so you won't accidentally delete or change it. It is also marked as a field (Fields), so that certain motion functions, including beginning-of-line, forward-word, forward-sentence, and forward-paragraph, stop at the boundary between the prompt and the actual text. The minibuffer's window is normally a single line; it grows automatically if the contents require more space. Whilst the minibuffer is active, you can explicitly resize its window temporarily with the window sizing commands; the window reverts to its normal size when the minibuffer is exited. When the minibuffer is not active, you can resize its window permanently by using the window sizing commands in the frame's other window, or dragging the mode line with the mouse. (Due to details of the current implementation, for this to work resize-mini-windows must be nil.) If the frame contains just a minibuffer window, you can change its size by changing the frame's size. Use of the minibuffer reads input events, and that alters the values of variables such as this-command and last-command (Command Loop Info). Your program should bind them around the code that uses the minibuffer, if you do not want that to change them. Under some circumstances, a command can use a minibuffer even if there is an active minibuffer; such a minibuffer is called a recursive minibuffer. The first minibuffer is named *Minibuf-1*. Recursive minibuffers are named by incrementing the number at the end of the name. (The names begin with a space so that they won't show up in normal buffer lists.) Of several recursive minibuffers, the innermost (or most recently entered) is the active minibuffer–it is the one you can terminate by typing RET (exit-minibuffer) in. We usually call this the minibuffer. You can permit or forbid recursive minibuffers by setting the variable enable-recursive-minibuffers, or by putting properties of that name on command symbols (Recursive Mini.) Like other buffers, a minibuffer uses a local keymap (Keymaps) to specify special key bindings. The function that invokes the minibuffer also sets up its local map according to the job to be done. Text from Minibuffer, for the non-completion minibuffer local maps. Completion Commands, for the minibuffer local maps for completion. An active minibuffer usually has major mode minibuffer-mode. This is an Emacs internal mode without any special features. To customize the setup of minibuffers, we suggest you use minibuffer-setup-hook (Minibuffer Misc) rather than minibuffer-mode-hook, since the former is run later, after the minibuffer has been fully initialized. When a minibuffer is inactive, its major mode is minibuffer-inactive-mode, with keymap minibuffer-inactive-mode-map. This is only really useful if the minibuffer is in a separate frame. Minibuffers and Frames. When Emacs is running in batch mode, any request to read from the minibuffer actually reads a line from the standard input descriptor that was supplied when Emacs was started. This supports only basic input: none of the special minibuffer features (history, completion, etc.) are available in batch mode.

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.

read-from-minibuffer

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. 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. Minibuffer History. If the variable minibuffer-allow-text-properties is non-nil, either let-bound or buffer-local in the minibuffer, 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. (By default this variable is nil.) 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 (Input Methods) and the setting of enable-multibyte-characters (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.

read-string

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.

read-regexp

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). 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. 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))

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.

minibuffer-allow-text-properties

If this variable is nil, the default, then read-from-minibuffer and all functions that do minibuffer input strip all text properties from the minibuffer input before returning it. However, read-minibuffer and related functions (Reading Lisp Objects With the Minibuffer), remove the text properties unconditionally, regardless of the value of this variable. If this variable is non-nil, either let-bound or buffer-local in the minibuffer, then read-from-minibuffer, read-string, and all related functions preserve text properties. But functions that do minibuffer input with completion remove the face property while preserving other text properties.

(minibuffer-with-setup-hook
    (lambda ()
      (setq-local minibuffer-allow-text-properties t))
  (completing-read
   "String: " (list (propertize "foobar" 'face 'baz 'data 'zot))))
=> #("foobar" 0 6 (data zot))

In this example, the user typed foo and then hit the TAB key, and all text properties are preserved except the face property.

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

M-<

minibuffer-beginning-of-buffer

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

The variable minibuffer-mode-map is an alias for this variable.

read-no-blanks-input

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.

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

format-prompt

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 (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 (Keys in Documentation).

read-minibuffer-restore-windows

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.

This section describes functions for reading Lisp objects with the minibuffer.

read-minibuffer

This function reads a Lisp object using the minibuffer, and returns it without evaluating it. The arguments prompt and initial are used as in read-from-minibuffer. This is a simplified interface to the read-from-minibuffer function:

(read-minibuffer PROMPT INITIAL)
≡
(let (minibuffer-allow-text-properties)
  (read-from-minibuffer PROMPT INITIAL nil t))

Here is an example in which we supply the string "(testing)" as initial input:

(read-minibuffer
 "Enter an expression: " (format "%s" '(testing)))

;; Here is how the minibuffer is displayed:

---------- Buffer: Minibuffer ----------
Enter an expression: (testing)⋆
---------- Buffer: Minibuffer ----------

The user can type RET immediately to use the initial input as a default, or can edit the input.

eval-minibuffer

This function reads a Lisp expression using the minibuffer, evaluates it, then returns the result. The arguments prompt and initial are used as in read-from-minibuffer. This function simply evaluates the result of a call to read-minibuffer:

(eval-minibuffer PROMPT INITIAL)
≡
(eval (read-minibuffer PROMPT INITIAL))

edit-and-eval-command

This function reads a Lisp expression in the minibuffer, evaluates it, then returns the result. The difference between this command and eval-minibuffer is that here the initial form is not optional and it is treated as a Lisp object to be converted to printed representation rather than as a string of text. It is printed with prin1, so if it is a string, double-quote characters (") appear in the initial text. Output Functions. In the following example, we offer the user an expression with initial text that is already a valid form:

(edit-and-eval-command "Please edit: " '(forward-word 1))

;; After evaluation of the preceding expression
;;   the following appears in the minibuffer:

---------- Buffer: Minibuffer ----------
Please edit: (forward-word 1)⋆
---------- Buffer: Minibuffer ----------

Typing RET right away would exit the minibuffer and evaluate the expression, thus moving point forward one word.

A minibuffer history list records previous minibuffer inputs so the user can reuse them conveniently. It is a variable whose value is a list of strings (previous inputs), most recent first. There are many separate minibuffer history lists, used for different kinds of inputs. It's the Lisp programmer's job to specify the right history list for each use of the minibuffer. You specify a minibuffer history list with the optional history argument to read-from-minibuffer or completing-read. Here are the possible values for it:

variable

Use variable (a symbol) as the history list.

(variable . startpos)

Use variable (a symbol) as the history list, and assume that the initial history position is startpos (a nonnegative integer). Specifying 0 for startpos is equivalent to just specifying the symbol variable. previous-history-element will display the most recent element of the history list in the minibuffer. If you specify a positive startpos, the minibuffer history functions behave as if (elt VARIABLE (1- STARTPOS)) were the history element currently shown in the minibuffer. For consistency, you should also specify that element of the history as the initial minibuffer contents, using the initial argument to the minibuffer input function (Initial Input).

If you don't specify history, then the default history list minibuffer-history is used. For other standard history lists, see below. You can also create your own history list variable; just initialize it to nil before the first use. If the variable is buffer local, then each buffer will have its own input history list. Both read-from-minibuffer and completing-read add new elements to the history list automatically, and provide commands to allow the user to reuse items on the list (Minibuffer Commands). The only thing your program needs to do to use a history list is to initialize it and to pass its name to the input functions when you wish. But it is safe to modify the list by hand when the minibuffer input functions are not using it. By default, when M-n (next-history-element, next-history-element) reaches the end of the list of default values provided by the command which initiated reading input from the minibuffer, M-n adds all of the completion candidates, as specified by minibuffer-completion-table (Completion Commands), to the list of defaults, so that all those candidates are available as "future history". Your program can control that via the variable minibuffer-default-add-function: if its value is not a function, this automatic addition is disabled, and you can also set this variable to your own function which adds only some candidates, or some other values, to the "future history". Emacs functions that add a new element to a history list can also delete old elements if the list gets too long. The variable history-length specifies the maximum length for most history lists. To specify a different maximum length for a particular history list, put the length in the history-length property of the history list symbol. The variable history-delete-duplicates specifies whether to delete duplicates in history.

add-to-history

This function adds a new element newelt, if it isn't the empty string, to the history list stored in the variable history-var, and returns the updated history list. It limits the list length to the value of maxelt (if non-nil) or history-length (described below). The possible values of maxelt have the same meaning as the values of history-length. history-var cannot refer to a lexical variable. Normally, add-to-history removes duplicate members from the history list if history-delete-duplicates is non-nil. However, if keep-all is non-nil, that says not to remove duplicates, and to add newelt to the list even if it is empty.

history-add-new-input

If the value of this variable is nil, standard functions that read from the minibuffer don't add new elements to the history list. This lets Lisp programs explicitly manage input history by using add-to-history. The default value is t.

history-length

The value of this variable specifies the maximum length for all history lists that don't specify their own maximum lengths. If the value is t, that means there is no maximum (don't delete old elements). If a history list variable's symbol has a non-nil history-length property, it overrides this variable for that particular history list.

history-delete-duplicates

If the value of this variable is t, that means when adding a new history element, all previous identical elements are deleted.

Here are some of the standard minibuffer history list variables:

minibuffer-history

The default history list for minibuffer history input.

query-replace-history

A history list for arguments to query-replace (and similar arguments to other commands).

file-name-history

A history list for file-name arguments.

buffer-name-history

A history list for buffer-name arguments.

regexp-history

A history list for regular expression arguments.

extended-command-history

A history list for arguments that are names of extended commands.

shell-command-history

A history list for arguments that are shell commands.

read-expression-history

A history list for arguments that are Lisp expressions to evaluate.

face-name-history

A history list for arguments that are faces.

custom-variable-history

A history list for variable-name arguments read by read-variable.

read-number-history

A history list for numbers read by read-number.

goto-line-history

A history list for arguments to goto-line. This variable can be made local in every buffer by customizing the user option goto-line-history-local.

Several of the functions for minibuffer input have an argument called initial. This is a mostly-deprecated feature for specifying that the minibuffer should start out with certain text, instead of empty as usual. If initial is a string, the minibuffer starts out containing the text of the string, with point at the end, when the user starts to edit the text. If the user simply types RET to exit the minibuffer, it will use the initial input string to determine the value to return. We discourage use of a non-nil value for initial, because initial input is an intrusive interface. History lists and default values provide a much more convenient method to offer useful default inputs to the user. There is just one situation where you should specify a string for an initial argument. This is when you specify a cons cell for the history argument. Minibuffer History. initial can also be a cons cell of the form (STRING . POSITION). This means to insert string in the minibuffer but put point at position within the string's text. As a historical accident, position was implemented inconsistently in different functions. In completing-read, position's value is interpreted as origin-zero; that is, a value of 0 means the beginning of the string, 1 means after the first character, etc. In read-minibuffer, and the other non-completion minibuffer input functions that support this argument, 1 means the beginning of the string, 2 means after the first character, etc. Use of a cons cell as the value for initial arguments is deprecated.

Completion is a feature that fills in the rest of a name starting from an abbreviation for it. Completion works by comparing the user's input against a list of valid names and determining how much of the name is determined uniquely by what the user has typed. For example, when you type C-x b (switch-to-buffer) and then type the first few letters of the name of the buffer to which you wish to switch, and then type TAB (minibuffer-complete), Emacs extends the name as far as it can. Standard Emacs commands offer completion for names of symbols, files, buffers, and processes; with the functions in this section, you can implement completion for other kinds of names. The try-completion function is the basic primitive for completion: it returns the longest determined completion of a given initial string, with a given set of strings to match against. The function completing-read provides a higher-level interface for completion. A call to completing-read specifies how to determine the list of valid names. The function then activates the minibuffer with a local keymap that binds a few keys to commands useful for completion. Other functions provide convenient simple interfaces for reading certain kinds of names with completion.

(try-completion
 "foo"
 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)))
     => "fooba"

(try-completion "foo" '(("barfoo" 2) ("foo" 3)))
     => t

(try-completion "forw" obarray)
     => "forward"

(defun test (s)
  (> (length (car s)) 6))
     => test
(try-completion
 "foo"
 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
 'test)
     => "foobar"

(defun test (s)
  (> (length (car s)) 6))
     => test

(all-completions
 "foo"
 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
 'test)
     => ("foobar1" "foobar2")

(defvar foo (lazy-completion-table foo make-my-alist))

(completing-read
 "Complete a foo: "
 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
 nil t "fo")

;; After evaluation of the preceding expression
;;   the following appears in the minibuffer:

---------- Buffer: Minibuffer ----------
Complete a foo: fo⋆
---------- Buffer: Minibuffer ----------

(with-output-to-temp-buffer "*Completions*"
  (display-completion-list
    (all-completions (buffer-string) my-alist)))

(read-buffer "Buffer name: " "foo" t)
;; After evaluation of the preceding expression
;;   the following prompt appears
;;   with an empty minibuffer:

---------- Buffer: Minibuffer ----------
Buffer name (default foo): ⋆
---------- Buffer: Minibuffer ----------

;; The user types minibuffer.t <RET>.
     => "minibuffer.texi"

(read-command "Command name? ")

;; After evaluation of the preceding expression
;;   the following prompt appears with an empty minibuffer:

---------- Buffer: Minibuffer ----------
Command name?
---------- Buffer: Minibuffer ----------

(read-command PROMPT)
≡
(intern (completing-read PROMPT obarray
                         'commandp t nil))

(read-file-name "The file is ")

;; After evaluation of the preceding expression
;;   the following appears in the minibuffer:

---------- Buffer: Minibuffer ----------
The file is /gp/gnu/elisp/⋆
---------- Buffer: Minibuffer ----------

---------- Buffer: Minibuffer ----------
The file is /gp/gnu/elisp/manual.texi⋆
---------- Buffer: Minibuffer ----------

;; Here the minibuffer starts out with the default directory.
(let ((insert-default-directory t))
  (read-file-name "The file is "))

---------- Buffer: Minibuffer ----------
The file is ~lewis/manual/⋆
---------- Buffer: Minibuffer ----------

;; Here the minibuffer is empty and only the prompt
;;   appears on its line.
(let ((insert-default-directory nil))
  (read-file-name "The file is "))

---------- Buffer: Minibuffer ----------
The file is ⋆
---------- Buffer: Minibuffer ----------

(STYLE TRY-COMPLETION ALL-COMPLETIONS DOC)

(START END COLLECTION . PROPS)

;; Avoid this pattern.
(let ((beg ...) (end ...) (my-completions (my-make-completions)))
  (list beg end my-completions))

;; Use this instead.
(let ((beg ...) (end ...))
  (list beg
        end
        (completion-table-dynamic
          (lambda (_)
            (my-make-completions)))))

This section describes functions used to ask the user a yes-or-no question. The function y-or-n-p can be answered with a single character; it is useful for questions where an inadvertent wrong answer will not have serious consequences. yes-or-no-p is suitable for more momentous questions, since it requires three or four characters to answer. If either of these functions is called in a command that was invoked using the mouse or some other window-system gesture, or in a command invoked via a menu, then they use a dialog box or pop-up menu to ask the question if dialog boxes are supported. Otherwise, they use keyboard input. You can force use either of the mouse or of keyboard input by binding last-nonmenu-event to a suitable value around the call—bind it to t to force keyboard interaction, and to a list to force dialog boxes. Both yes-or-no-p and y-or-n-p use the minibuffer.

y-or-n-p

This function asks the user a question, expecting input in the minibuffer. It returns t if the user types y, nil if the user types n. This function also accepts SPC to mean yes and DEL to mean no. It accepts C-] and C-g to quit, because the question uses the minibuffer and for that reason the user might try to use C-] to get out. The answer is a single character, with no RET needed to terminate it. Upper and lower case are equivalent. "Asking the question" means printing prompt in the minibuffer, followed by the string (y or n). If the input is not one of the expected answers (y, n, SPC, DEL, or something that quits), the function responds Please answer y or n., and repeats the request. If prompt is a non-empty string, and it ends with a non-space character, a SPC character will be appended to it. This function actually uses the minibuffer, but does not allow editing of the answer. The cursor moves to the minibuffer while the question is being asked. The answers and their meanings, even y and n, are not hardwired, and are specified by the keymap query-replace-map (Search and Replace). In particular, if the user enters the special responses recenter, scroll-up, scroll-down, scroll-other-window, or scroll-other-window-down (respectively bound to C-l, C-v, M-v, C-M-v and C-M-S-v in query-replace-map), this function performs the specified window recentering or scrolling operation, and poses the question again. If you bind help-form (Help Functions) to a non-nil value while calling y-or-n-p, then pressing help-char causes it to evaluate help-form and display the result. help-char is automatically added to prompt.

y-or-n-p-with-timeout

Like y-or-n-p, except that if the user fails to answer within seconds seconds, this function stops waiting and returns default. It works by setting up a timer; see Timers. The argument seconds should be a number.

yes-or-no-p

This function asks the user a question, expecting input in the minibuffer. It returns t if the user enters yes, nil if the user types no. The user must type RET to finalize the response. Upper and lower case are equivalent. yes-or-no-p starts by displaying prompt in the minibuffer, followed by the value of yes-or-no-prompt (default (yes or no)). The user must type one of the expected responses; otherwise, the function responds Please answer yes or no., waits about two seconds and repeats the request. If prompt is a non-empty string, and it ends with a non-space character, a SPC character will be appended to it. yes-or-no-p requires more work from the user than y-or-n-p and is appropriate for more crucial decisions. Here is an example:

(yes-or-no-p "Do you really want to remove everything? ")

;; After evaluation of the preceding expression
;;   the following prompt appears
;;   with an empty minibuffer:

---------- Buffer: minibuffer ----------
Do you really want to remove everything? (yes or no)
---------- Buffer: minibuffer ----------

If the user first types y RET, which is invalid because this function demands the entire word yes, it responds by displaying these prompts, with a brief pause between them:

---------- Buffer: minibuffer ----------
Please answer yes or no.
Do you really want to remove everything? (yes or no)
---------- Buffer: minibuffer ----------

This section describes facilities for asking the user more complex questions or several similar questions. When you have a series of similar questions to ask, such as "Do you want to save this buffer?" for each buffer in turn, you should use map-y-or-n-p to ask the collection of questions, rather than asking each question individually. This gives the user certain convenient facilities such as the ability to answer the whole series at once.

map-y-or-n-p

This function asks the user a series of questions, reading a single-character answer in the echo area for each one. The value of list specifies the objects to ask questions about. It should be either a list of objects or a generator function. If it is a function, it will be called with no arguments, and should return either the next object to ask about, or nil, meaning to stop asking questions. The argument prompter specifies how to ask each question. If prompter is a string, the question text is computed like this:

(format PROMPTER OBJECT)

where object is the next object to ask about (as obtained from list). Formatting Strings, for more information about format. If prompter is not a string, it should be a function of one argument (the object to ask about) and should return the question text for that object. If the value prompter returns is a string, that is the question to ask the user. The function can also return t, meaning to act on this object without asking the user, or nil, which means to silently ignore this object. The argument actor says how to act on the objects for which the user answers yes. It should be a function of one argument, and will be called with each object from list for which the user answers yes. If the argument help is given, it should be a list of this form:

(SINGULAR PLURAL ACTION)

where singular is a string containing a singular noun that describes a single object to be acted on, plural is the corresponding plural noun, and action is a transitive verb describing what actor does with the objects. If you don't specify help, it defaults to the list ("object" "objects" "act on"). Each time a question is asked, the user can answer as follows:

y, Y, or SPC

act on the object

n, N, or DEL

skip the object

!

act on all the following objects

ESC or q

exit (skip all following objects)

. (period)

act on the object and then exit

C-h

get help

These are the same answers that query-replace accepts. The keymap query-replace-map defines their meaning for map-y-or-n-p as well as for query-replace; see Search and Replace. You can use action-alist to specify additional possible answers and what they mean. If provided, action-alist should be an alist whose elements are of the form (CHAR FUNCTION HELP). Each of the alist elements defines one additional answer. In each element, char is a character (the answer); function is a function of one argument (an object from list); and help is a string. When the user responds with char, map-y-or-n-p calls function. If it returns non-nil, the object is considered to have been acted upon, and map-y-or-n-p advances to the next object in list. If it returns nil, the prompt is repeated for the same object. If the user requests help, the text in help is used to describe these additional answers. Normally, map-y-or-n-p binds cursor-in-echo-area while prompting. But if no-cursor-in-echo-area is non-nil, it does not do that. If map-y-or-n-p is called in a command that was invoked using the mouse or some other window-system gesture, or a command invoked via a menu, then it uses a dialog box or pop-up menu to ask the question if dialog boxes are supported. In this case, it does not use keyboard input or the echo area. You can force use either of the mouse or of keyboard input by binding last-nonmenu-event to a suitable value around the call—bind it to t to force keyboard interaction, and to a list to force dialog boxes. The return value of map-y-or-n-p is the number of objects acted on. If you need to ask the user a question that might have more than just 2 answers, use read-answer.

read-answer

This function prompts the user with text in question, which should end in the SPC character. The function includes in the prompt the possible responses in answers by appending them to the end of question. The possible responses are provided in answers as an alist whose elements are of the following form:

(LONG-ANSWER SHORT-ANSWER HELP-MESSAGE)

where long-answer is the complete text of the user response, a string; short-answer is a short form of the same response, a single character or a function key; and help-message is the text that describes the meaning of the answer. If the variable read-answer-short is non-nil, the prompt will show the short variants of the possible answers and the user is expected to type the single characters/keys shown in the prompt; otherwise the prompt will show the long variants of the answers, and the user is expected to type the full text of one of the answers and end by pressing RET. If use-dialog-box is non-nil, and this function was invoked by mouse events, the question and the answers will be displayed in a GUI dialog box. The function returns the text of the long-answer selected by the user, regardless of whether long or short answers were shown in the prompt and typed by the user. Here is an example of using this function:

(let ((read-answer-short t))
  (read-answer "Foo "
     '(("yes"  ?y "perform the action")
       ("no"   ?n "skip to the next")
       ("all"  ?! "perform for the rest without more questions")
       ("help" ?h "show help")
       ("quit" ?q "exit"))))

read-char-from-minibuffer

This function uses the minibuffer to read and return a single character. Optionally, it ignores any input that is not a member of chars, a list of accepted characters. The history argument specifies the history list symbol to use; if it is omitted or nil, this function doesn't use the history. If you bind help-form (Help Functions) to a non-nil value while calling read-char-from-minibuffer, then pressing help-char causes it to evaluate help-form and display the result.

To read a password to pass to another program, you can use the function read-passwd.

read-passwd

This function reads a password, prompting with prompt. It does not echo the password as the user types it; instead, it echoes * for each character in the password. If you want to apply another character to hide the password, let-bind the variable read-hide-char with that character. The optional argument confirm, if non-nil, says to read the password twice and insist it must be the same both times. If it isn't the same, the user has to type it over and over until the last two times match. The optional argument default specifies the default password to return if the user enters empty input. If default is nil, then read-passwd returns the null string in that case. This function uses read-passwd-mode, a minor mode. It binds two keys in the minbuffer: C-u (delete-minibuffer-contents) deletes the password, and TAB (read-passwd--toggle-visibility) toggles the visibility of the password. There is also an additional icon in the mode-line's global-mode-string. Clicking on this icon with mouse-1 toggles the visibility of the password as well.

This section describes some commands meant for use in the minibuffer.

Command exit-minibuffer

This command exits the active minibuffer. It is normally bound to keys in minibuffer local keymaps. The command throws an error if the current buffer is a minibuffer, but not the active minibuffer.

Command self-insert-and-exit

This command exits the active minibuffer after inserting the last character typed on the keyboard (found in last-command-event; Command Loop Info).

Command previous-history-element

This command replaces the minibuffer contents with the value of the /n/th previous (older) history element.

Command next-history-element

This command replaces the minibuffer contents with the value of the /n/th more recent history element. The position in the history can go beyond the current position and invoke "future history" (Text from Minibuffer).

Command previous-matching-history-element

This command replaces the minibuffer contents with the value of the n/th previous (older) history element that matches /pattern (a regular expression).

Command next-matching-history-element

This command replaces the minibuffer contents with the value of the n/th next (newer) history element that matches /pattern (a regular expression).

Command previous-complete-history-element

This command replaces the minibuffer contents with the value of the /n/th previous (older) history element that completes the current contents of the minibuffer before the point.

Command next-complete-history-element

This command replaces the minibuffer contents with the value of the /n/th next (newer) history element that completes the current contents of the minibuffer before the point.

Command goto-history-element

This function puts element of the minibuffer history in the minibuffer. The argument nabs specifies the absolute history position in descending order, where 0 means the current element and a positive number n means the n/th previous element. NABS being a negative number -/n means the /n/th entry of "future history". When this function reaches the end of the default values provided by read-from-minibuffer (Text from Minibuffer) and completing-read (Minibuffer Completion), it adds the completion candidates to "future history", see minibuffer-default-add-function.

These functions access and select minibuffer windows, test whether they are active and control how they get resized.

minibuffer-window

This function returns the minibuffer window used for frame frame. If frame is nil, that stands for the selected frame. Note that the minibuffer window used by a frame need not be part of that frame—a frame that has no minibuffer of its own necessarily uses some other frame's minibuffer window. The minibuffer window of a minibuffer-less frame can be changed by setting that frame's minibuffer frame parameter (Buffer Parameters).

set-minibuffer-window

This function specifies window as the minibuffer window to use. This affects where the minibuffer is displayed if you put text in it without invoking the usual minibuffer commands. It has no effect on the usual minibuffer input functions because they all start by choosing the minibuffer window according to the selected frame.

window-minibuffer-p

This function returns t if window is a minibuffer window. window defaults to the selected window.

The following function returns the window showing the currently active minibuffer.

active-minibuffer-window

This function returns the window of the currently active minibuffer, or nil if there is no active minibuffer.

It is not sufficient to determine whether a given window shows the currently active minibuffer by comparing it with the result of (minibuffer-window), because there can be more than one minibuffer window if there is more than one frame.

minibuffer-window-active-p

This function returns non-nil if window shows the currently active minibuffer.

The following two options control whether minibuffer windows are resized automatically and how large they can get in the process.

resize-mini-windows

This option specifies whether minibuffer windows are resized automatically. The default value is grow-only, which means that a minibuffer window by default expands automatically to accommodate the text it displays and shrinks back to one line as soon as the minibuffer gets empty. If the value is t, Emacs will always try to fit the height of a minibuffer window to the text it displays (with a minimum of one line). If the value is nil, a minibuffer window never changes size automatically. In that case the window resizing commands (Resizing Windows) can be used to adjust its height.

max-mini-window-height

This option provides a maximum height for resizing minibuffer windows automatically. A floating-point number specifies the maximum height as a fraction of the frame's height; an integer specifies the maximum height in units of the frame's canonical character height (Frame Font). The default value is 0.25.

Note that the values of the above two variables take effect at display time, so let-binding them around code which produces echo-area messages will not work. If you want to prevent resizing of minibuffer windows when displaying long messages, bind the message-truncate-lines variable instead (Echo Area Customization). The option resize-mini-windows does not affect the behavior of minibuffer-only frames (Frame Layout). The following option enables automatically resizing such frames as well.

resize-mini-frames

If this is nil, minibuffer-only frames are never resized automatically. If this is a function, that function is called with the minibuffer-only frame to be resized as sole argument. At the time this function is called, the buffer of the minibuffer window of that frame is the buffer whose contents will be shown the next time that window is redisplayed. The function is expected to fit the frame to the buffer in some appropriate way. Any other non-nil value means to resize minibuffer-only frames by calling fit-mini-frame-to-buffer, a function that behaves like fit-frame-to-buffer (Resizing Windows) but does not strip leading or trailing empty lines from the buffer text.

These functions access the minibuffer prompt and contents.

minibuffer-prompt

This function returns the prompt string of the currently active minibuffer. If no minibuffer is active, it returns nil.

minibuffer-prompt-end

This function returns the current position of the end of the minibuffer prompt, if a minibuffer is current. Otherwise, it returns the minimum valid buffer position.

minibuffer-prompt-width

This function returns the current display-width of the minibuffer prompt, if a minibuffer is current. Otherwise, it returns zero.

minibuffer-contents

This function returns the editable contents of the minibuffer (that is, everything except the prompt) as a string, if a minibuffer is current. Otherwise, it returns the entire contents of the current buffer.

minibuffer-contents-no-properties

This is like minibuffer-contents, except that it does not copy text properties, just the characters themselves. Text Properties.

Command delete-minibuffer-contents

This command erases the editable contents of the minibuffer (that is, everything except the prompt), if a minibuffer is current. Otherwise, it erases the entire current buffer.

These functions and variables deal with recursive minibuffers (Recursive Editing):

minibuffer-depth

This function returns the current depth of activations of the minibuffer, a nonnegative integer. If no minibuffers are active, it returns zero.

enable-recursive-minibuffers

If this variable is non-nil, you can invoke commands (such as find-file) that use minibuffers even while the minibuffer is active. Such invocation produces a recursive editing level for a new minibuffer. By default, the outer-level minibuffer is invisible while you are editing the inner one. If you have minibuffer-follows-selected-frame set to nil, you can have minibuffers visible on several frames at the same time. Basic Minibuffer. If this variable is nil, you cannot invoke minibuffer commands when the minibuffer is active, not even if you switch to another window to do it.

If a command name has a property enable-recursive-minibuffers that is non-nil, then the command can use the minibuffer to read arguments even if it is invoked from the minibuffer. A command can also achieve this by binding enable-recursive-minibuffers to t in the interactive declaration (Using Interactive). The minibuffer command next-matching-history-element (normally M-s in the minibuffer) does the latter.

It's sometimes useful to be able to run Emacs as a headless server process that responds to commands given over a network connection. However, Emacs is primarily a platform for interactive usage, so many commands prompt the user for feedback in certain anomalous situations. This makes this use case more difficult, since the server process will just hang waiting for user input. Binding the inhibit-interaction variable to something non-nil makes Emacs signal a inhibited-interaction error instead of prompting, which can then be used by the server process to handle these situations. Here's a typical use case:

(let ((inhibit-interaction t))
  (respond-to-client
   (condition-case err
       (my-client-handling-function)
     (inhibited-interaction err))))

If my-client-handling-function ends up calling something that asks the user for something (via y-or-n-p or read-from-minibuffer or the like), an inhibited-interaction error is signaled instead. The server code then catches that error and reports it to the client.

minibufferp

This function returns non-nil if buffer-or-name is a minibuffer. If buffer-or-name is omitted or nil, it tests the current buffer. When live is non-nil, the function returns non-nil only when buffer-or-name is an active minibuffer.

minibuffer-setup-hook

This is a normal hook that is run whenever a minibuffer is entered. Hooks.

minibuffer-with-setup-hook

This macro executes body after arranging for the specified function to be called via minibuffer-setup-hook. By default, function is called before the other functions in the minibuffer-setup-hook list, but if function is of the form (:append FUNC), func will be called after the other hook functions. The body forms should not use the minibuffer more than once. If the minibuffer is re-entered recursively, function will only be called once, for the outermost use of the minibuffer.

minibuffer-exit-hook

This is a normal hook that is run whenever a minibuffer is exited. Hooks.

minibuffer-help-form

The current value of this variable is used to rebind help-form locally inside the minibuffer (Help Functions).

minibuffer-scroll-window

If the value of this variable is non-nil, it should be a window object. When the function scroll-other-window is called in the minibuffer, it scrolls this window (Textual Scrolling).

minibuffer-selected-window

This function returns the window that was selected just before the minibuffer window was selected. If the selected window is not a minibuffer window, it returns nil.

minibuffer-message

This function is like message (Displaying Messages), but it displays the messages specially when the user types in the minibuffer, typically because Emacs prompted the user for some input. When the minibuffer is the current buffer, this function displays the message specified by string temporarily at the end of the minibuffer text, and thus avoids hiding the minibuffer text by the echo-area display of the message. It leaves the message on display for a few seconds, or until the next input event arrives, whichever comes first. The variable minibuffer-message-timeout specifies the number of seconds to wait in the absence of input. It defaults to 2. If args is non-nil, the actual message is obtained by passing string and args through format-message. Formatting Strings. If called when the minibuffer is not the current buffer, this function just calls message, and thus string will be shown in the echo-area.

Command minibuffer-inactive-mode

This is the major mode used in inactive minibuffers. It uses keymap minibuffer-inactive-mode-map. This can be useful if the minibuffer is in a separate frame. Minibuffers and Frames.

Command minibuffer-regexp-mode

This minor mode makes editing regular expressions in the minibuffer more convenient. It highlight parens via show-paren-mode and blink-matching-paren in a user-friendly way, avoids reporting false paren mismatches, and makes sexp navigation more intuitive.

By default, only certain minibuffer prompts automatically activate the convenience features of minibuffer-regexp-mode when the minibuffer becomes active. This list of prompts can be customized via minibuffer-regexp-prompts.

minibuffer-regexp-prompts

This variable holds the list of regular expressions for activating the features of minibuffer-regexp-mode in the minibuffer. The mode's features will be activated only if the minibuffer prompt matches one of the regular expressions in the list.