"Fossies" - the Fresh Open Source Software Archive

Member "emacs-25.3/doc/lispref/minibuf.texi" (14 Apr 2017, 98155 Bytes) of package /linux/misc/emacs-25.3.tar.xz:


Caution: As a special service "Fossies" has tried to format the requested Texinfo source page into HTML format but that may be not always succeeeded perfectly. Alternatively you can here view or download the uninterpreted Texinfo source code. A member file download can also be achieved by clicking within a package contents listing on the according byte size field. See also the last Fossies "Diffs" side-by-side code changes report for "minibuf.texi": 25.1_vs_25.2.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1 Minibuffers

A minibuffer is a special buffer that Emacs commands use to read arguments more complicated than the single numeric prefix argument. These arguments include file names, buffer names, and command names (as in M-x). The minibuffer is displayed on the bottom line of the frame, in the same place as the echo area (@pxref{The Echo Area}), but only while it is in use for reading an argument.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.1 Introduction to Minibuffers

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 @ref{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 (@pxref{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 it is active, you can explicitly resize it temporarily with the window sizing commands; it reverts to its normal size when the minibuffer is exited. When the minibuffer is not active, you can resize it 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, you can change the minibuffer’s 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 (@pxref{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. 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 (See section Recursive Minibuffers.)

Like other buffers, a minibuffer uses a local keymap (@pxref{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. See section Reading Text Strings with the Minibuffer, for the non-completion minibuffer local maps. See section Minibuffer Commands that Do Completion, for the minibuffer local maps for completion.

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. @xref{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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.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 (@pxref{Regular Expressions}), which are a special kind of string. There are also specialized functions for reading commands, variables, file names, etc. (see section 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. @xref{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 (@pxref{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. (@xref{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. See section 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 minibuffer inherits the current input method (@pxref{Input Methods}) and the setting of enable-multibyte-characters (@pxref{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 section 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:

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 section 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:

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 (see section Reading Lisp Objects With the 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


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.3 Reading Lisp Objects with the Minibuffer

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

Function: read-minibuffer prompt &optional initial

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.

Function: eval-minibuffer prompt &optional initial

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))
Function: edit-and-eval-command prompt form

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. @xref{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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4 Minibuffer History

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 (see section 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.

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

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.

Function: add-to-history history-var newelt &optional maxelt keep-all

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.

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.

Variable: 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.

User Option: 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.

User Option: 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:

Variable: minibuffer-history

The default history list for minibuffer history input.

Variable: query-replace-history

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

Variable: file-name-history

A history list for file-name arguments.

Variable: buffer-name-history

A history list for buffer-name arguments.

Variable: regexp-history

A history list for regular expression arguments.

Variable: extended-command-history

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

Variable: shell-command-history

A history list for arguments that are shell commands.

Variable: read-expression-history

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

Variable: face-name-history

A history list for arguments that are faces.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.5 Initial Input

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. See section 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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.6 Completion

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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.6.1 Basic Completion Functions

The following completion functions have nothing in themselves to do with minibuffers. We describe them here to keep them near the higher-level completion features that do use the minibuffer.

Function: try-completion string collection &optional predicate

This function returns the longest common substring of all possible completions of string in collection.

collection is called the completion table. Its value must be a list of strings or cons cells, an obarray, a hash table, or a completion function.

try-completion compares string against each of the permissible completions specified by the completion table. If no permissible completions match, it returns nil. If there is just one matching completion, and the match is exact, it returns t. Otherwise, it returns the longest initial sequence common to all possible matching completions.

If collection is a list, the permissible completions are specified by the elements of the list, each of which should be either a string, or a cons cell whose CAR is either a string or a symbol (a symbol is converted to a string using symbol-name). If the list contains elements of any other type, those are ignored.

If collection is an obarray (@pxref{Creating Symbols}), the names of all symbols in the obarray form the set of permissible completions.

If collection is a hash table, then the keys that are strings or symbols are the possible completions. Other keys are ignored.

You can also use a function as collection. Then the function is solely responsible for performing completion; try-completion returns whatever this function returns. The function is called with three arguments: string, predicate and nil (the third argument is so that the same function can be used in all-completions and do the appropriate thing in either case). See section Programmed Completion.

If the argument predicate is non-nil, then it must be a function of one argument, unless collection is a hash table, in which case it should be a function of two arguments. It is used to test each possible match, and the match is accepted only if predicate returns non-nil. The argument given to predicate is either a string or a cons cell (the CAR of which is a string) from the alist, or a symbol (not a symbol name) from the obarray. If collection is a hash table, predicate is called with two arguments, the string key and the associated value.

In addition, to be acceptable, a completion must also match all the regular expressions in completion-regexp-list. (Unless collection is a function, in which case that function has to handle completion-regexp-list itself.)

In the first of the following examples, the string ‘foo’ is matched by three of the alist CARs. All of the matches begin with the characters ‘fooba’, so that is the result. In the second example, there is only one possible match, and it is exact, so the return value is t.

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

In the following example, numerous symbols begin with the characters ‘forw’, and all of them begin with the word ‘forward’. In most of the symbols, this is followed with a ‘-’, but not in all, so no more than ‘forward’ can be completed.

(try-completion "forw" obarray)
     ⇒ "forward"

Finally, in the following example, only two of the three possible matches pass the predicate test (the string ‘foobaz’ is too short). Both of those begin with the string ‘foobar’.

(defun test (s)
  (> (length (car s)) 6))
     ⇒ test
(try-completion
 "foo"
 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
 'test)
     ⇒ "foobar"
Function: all-completions string collection &optional predicate

This function returns a list of all possible completions of string. The arguments to this function are the same as those of try-completion, and it uses completion-regexp-list in the same way that try-completion does.

If collection is a function, it is called with three arguments: string, predicate and t; then all-completions returns whatever the function returns. See section Programmed Completion.

Here is an example, using the function test shown in the example for try-completion:

(defun test (s)
  (> (length (car s)) 6))
     ⇒ test
(all-completions
 "foo"
 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
 'test)
     ⇒ ("foobar1" "foobar2")
Function: test-completion string collection &optional predicate

This function returns non-nil if string is a valid completion alternative specified by collection and predicate. The arguments are the same as in try-completion. For instance, if collection is a list of strings, this is true if string appears in the list and predicate is satisfied.

This function uses completion-regexp-list in the same way that try-completion does.

If predicate is non-nil and if collection contains several strings that are equal to each other, as determined by compare-strings according to completion-ignore-case, then predicate should accept either all or none of them. Otherwise, the return value of test-completion is essentially unpredictable.

If collection is a function, it is called with three arguments, the values string, predicate and lambda; whatever it returns, test-completion returns in turn.

Function: completion-boundaries string collection predicate suffix

This function returns the boundaries of the field on which collection will operate, assuming that string holds the text before point and suffix holds the text after point.

Normally completion operates on the whole string, so for all normal collections, this will always return (0 . (length suffix)). But more complex completion such as completion on files is done one field at a time. For example, completion of "/usr/sh" will include "/usr/share/" but not "/usr/share/doc" even if "/usr/share/doc" exists. Also all-completions on "/usr/sh" will not include "/usr/share/" but only "share/". So if string is "/usr/sh" and suffix is "e/doc", completion-boundaries will return (5 . 1) which tells us that the collection will only return completion information that pertains to the area after "/usr/" and before "/doc".

If you store a completion alist in a variable, you should mark the variable as risky by giving it a non-nil risky-local-variable property. @xref{File Local Variables}.

Variable: completion-ignore-case

If the value of this variable is non-nil, case is not considered significant in completion. Within read-file-name, this variable is overridden by read-file-name-completion-ignore-case (see section Reading File Names); within read-buffer, it is overridden by read-buffer-completion-ignore-case (see section High-Level Completion Functions).

Variable: completion-regexp-list

This is a list of regular expressions. The completion functions only consider a completion acceptable if it matches all regular expressions in this list, with case-fold-search (@pxref{Searching and Case}) bound to the value of completion-ignore-case.

Macro: lazy-completion-table var fun

This macro provides a way to initialize the variable var as a collection for completion in a lazy way, not computing its actual contents until they are first needed. You use this macro to produce a value that you store in var. The actual computation of the proper value is done the first time you do completion using var. It is done by calling fun with no arguments. The value fun returns becomes the permanent value of var.

Here is an example:

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

There are several functions that take an existing completion table and return a modified version. completion-table-case-fold returns a case-insensitive table. completion-table-in-turn and completion-table-merge combine multiple input tables in different ways. completion-table-subvert alters a table to use a different initial prefix. completion-table-with-quoting returns a table suitable for operating on quoted text. completion-table-with-predicate filters a table with a predicate function. completion-table-with-terminator adds a terminating string.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.6.2 Completion and the Minibuffer

This section describes the basic interface for reading from the minibuffer with completion.

Function: completing-read prompt collection &optional predicate require-match initial history default inherit-input-method

This function reads a string in the minibuffer, assisting the user by providing completion. It activates the minibuffer with prompt prompt, which must be a string.

The actual completion is done by passing the completion table collection and the completion predicate predicate to the function try-completion (see section Basic Completion Functions). This happens in certain commands bound in the local keymaps used for completion. Some of these commands also call test-completion. Thus, if predicate is non-nil, it should be compatible with collection and completion-ignore-case. See Definition of test-completion.

See section Programmed Completion, for detailed requirements when collection is a function.

The value of the optional argument require-match determines how the user may exit the minibuffer:

However, empty input is always permitted, regardless of the value of require-match; in that case, completing-read returns the first element of default, if it is a list; "", if default is nil; or default. The string or strings in default are also available to the user through the history commands.

The function completing-read uses minibuffer-local-completion-map as the keymap if require-match is nil, and uses minibuffer-local-must-match-map if require-match is non-nil. See section Minibuffer Commands that Do Completion.

The argument history specifies which history list variable to use for saving the input and for minibuffer history commands. It defaults to minibuffer-history. See section Minibuffer History.

The argument initial is mostly deprecated; we recommend using a non-nil value only in conjunction with specifying a cons cell for history. See section Initial Input. For default input, use default instead.

If the argument inherit-input-method is non-nil, then the minibuffer inherits the current input method (@pxref{Input Methods}) and the setting of enable-multibyte-characters (@pxref{Text Representations}) from whichever buffer was current before entering the minibuffer.

If the variable completion-ignore-case is non-nil, completion ignores case when comparing the input against the possible matches. See section Basic Completion Functions. In this mode of operation, predicate must also ignore case, or you will get surprising results.

Here’s an example of using completing-read:

(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 ----------

If the user then types <DEL> <DEL> b <RET>, completing-read returns barfoo.

The completing-read function binds variables to pass information to the commands that actually do completion. They are described in the following section.

Variable: completing-read-function

The value of this variable must be a function, which is called by completing-read to actually do its work. It should accept the same arguments as completing-read. This can be bound to a different function to completely override the normal behavior of completing-read.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.6.3 Minibuffer Commands that Do Completion

This section describes the keymaps, commands and user options used in the minibuffer to do completion.

Variable: minibuffer-completion-table

The value of this variable is the completion table used for completion in the minibuffer. This is the global variable that contains what completing-read passes to try-completion. It is used by minibuffer completion commands such as minibuffer-complete-word.

Variable: minibuffer-completion-predicate

This variable’s value is the predicate that completing-read passes to try-completion. The variable is also used by the other minibuffer completion functions.

Variable: minibuffer-completion-confirm

This variable determines whether Emacs asks for confirmation before exiting the minibuffer; completing-read binds this variable, and the function minibuffer-complete-and-exit checks the value before exiting. If the value is nil, confirmation is not required. If the value is confirm, the user may exit with an input that is not a valid completion alternative, but Emacs asks for confirmation. If the value is confirm-after-completion, the user may exit with an input that is not a valid completion alternative, but Emacs asks for confirmation if the user submitted the input right after any of the completion commands in minibuffer-confirm-exit-commands.

Variable: minibuffer-confirm-exit-commands

This variable holds a list of commands that cause Emacs to ask for confirmation before exiting the minibuffer, if the require-match argument to completing-read is confirm-after-completion. The confirmation is requested if the user attempts to exit the minibuffer immediately after calling any command in this list.

Command: minibuffer-complete-word

This function completes the minibuffer contents by at most a single word. Even if the minibuffer contents have only one completion, minibuffer-complete-word does not add any characters beyond the first character that is not a word constituent. @xref{Syntax Tables}.

Command: minibuffer-complete

This function completes the minibuffer contents as far as possible.

Command: minibuffer-complete-and-exit

This function completes the minibuffer contents, and exits if confirmation is not required, i.e., if minibuffer-completion-confirm is nil. If confirmation is required, it is given by repeating this command immediately—the command is programmed to work without confirmation when run twice in succession.

Command: minibuffer-completion-help

This function creates a list of the possible completions of the current minibuffer contents. It works by calling all-completions using the value of the variable minibuffer-completion-table as the collection argument, and the value of minibuffer-completion-predicate as the predicate argument. The list of completions is displayed as text in a buffer named ‘*Completions*’.

Function: display-completion-list completions

This function displays completions to the stream in standard-output, usually a buffer. (@xref{Read and Print}, for more information about streams.) The argument completions is normally a list of completions just returned by all-completions, but it does not have to be. Each element may be a symbol or a string, either of which is simply printed. It can also be a list of two strings, which is printed as if the strings were concatenated. The first of the two strings is the actual completion, the second string serves as annotation.

This function is called by minibuffer-completion-help. A common way to use it is together with with-output-to-temp-buffer, like this:

(with-output-to-temp-buffer "*Completions*"
  (display-completion-list
    (all-completions (buffer-string) my-alist)))
User Option: completion-auto-help

If this variable is non-nil, the completion commands automatically display a list of possible completions whenever nothing can be completed because the next character is not uniquely determined.

Variable: minibuffer-local-completion-map

completing-read uses this value as the local keymap when an exact match of one of the completions is not required. By default, this keymap makes the following bindings:

?

minibuffer-completion-help

<SPC>

minibuffer-complete-word

<TAB>

minibuffer-complete

and uses minibuffer-local-map as its parent keymap (see Definition of minibuffer-local-map).

Variable: minibuffer-local-must-match-map

completing-read uses this value as the local keymap when an exact match of one of the completions is required. Therefore, no keys are bound to exit-minibuffer, the command that exits the minibuffer unconditionally. By default, this keymap makes the following bindings:

C-j

minibuffer-complete-and-exit

<RET>

minibuffer-complete-and-exit

and uses minibuffer-local-completion-map as its parent keymap.

Variable: minibuffer-local-filename-completion-map

This is a sparse keymap that simply unbinds <SPC>; because filenames can contain spaces. The function read-file-name combines this keymap with either minibuffer-local-completion-map or minibuffer-local-must-match-map.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.6.4 High-Level Completion Functions

This section describes the higher-level convenience functions for reading certain sorts of names with completion.

In most cases, you should not call these functions in the middle of a Lisp function. When possible, do all minibuffer input as part of reading the arguments for a command, in the interactive specification. @xref{Defining Commands}.

Function: read-buffer prompt &optional default require-match predicate

This function reads the name of a buffer and returns it as a string. It prompts with prompt. The argument default is the default name to use, the value to return if the user exits with an empty minibuffer. If non-nil, it should be a string, a list of strings, or a buffer. If it is a list, the default value is the first element of this list. It is mentioned in the prompt, but is not inserted in the minibuffer as initial input.

The argument prompt should be a string ending with a colon and a space. If default is non-nil, the function inserts it in prompt before the colon to follow the convention for reading from the minibuffer with a default value (@pxref{Programming Tips}).

The optional argument require-match has the same meaning as in completing-read. See section Completion and the Minibuffer.

The optional argument predicate, if non-nil, specifies a function to filter the buffers that should be considered: the function will be called with every potential candidate as its argument, and should return nil to reject the candidate, non-nil to accept it.

In the following example, the user enters ‘minibuffer.t’, and then types <RET>. The argument require-match is t, and the only buffer name starting with the given input is ‘minibuffer.texi’, so that name is the value.

(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"
User Option: read-buffer-function

This variable, if non-nil, specifies a function for reading buffer names. read-buffer calls this function instead of doing its usual work, with the same arguments passed to read-buffer.

User Option: read-buffer-completion-ignore-case

If this variable is non-nil, read-buffer ignores case when performing completion while reading the buffer name.

Function: read-command prompt &optional default

This function reads the name of a command and returns it as a Lisp symbol. The argument prompt is used as in read-from-minibuffer. Recall that a command is anything for which commandp returns t, and a command name is a symbol for which commandp returns t. @xref{Interactive Call}.

The argument default specifies what to return if the user enters null input. It can be a symbol, a string or a list of strings. If it is a string, read-command interns it before returning it. If it is a list, read-command interns the first element of this list. If default is nil, that means no default has been specified; then if the user enters null input, the return value is (intern ""), that is, a symbol whose name is an empty string.

(read-command "Command name? ")

;; After evaluation of the preceding expression,
;;   the following prompt appears with an empty minibuffer:
---------- Buffer: Minibuffer ----------
Command name?
---------- Buffer: Minibuffer ----------

If the user types forward-c <RET>, then this function returns forward-char.

The read-command function is a simplified interface to completing-read. It uses the variable obarray so as to complete in the set of extant Lisp symbols, and it uses the commandp predicate so as to accept only command names:

(read-command prompt)
≡
(intern (completing-read prompt obarray
                         'commandp t nil))
Function: read-variable prompt &optional default

This function reads the name of a customizable variable and returns it as a symbol. Its arguments have the same form as those of read-command. It behaves just like read-command, except that it uses the predicate custom-variable-p instead of commandp.

Command: read-color &optional prompt convert allow-empty display

This function reads a string that is a color specification, either the color’s name or an RGB hex value such as #RRRGGGBBB. It prompts with prompt (default: "Color (name or #RGB triplet):") and provides completion for color names, but not for hex RGB values. In addition to names of standard colors, completion candidates include the foreground and background colors at point.

Valid RGB values are described in @ref{Color Names}.

The function’s return value is the string typed by the user in the minibuffer. However, when called interactively or if the optional argument convert is non-nil, it converts any input color name into the corresponding RGB value string and instead returns that. This function requires a valid color specification to be input. Empty color names are allowed when allow-empty is non-nil and the user enters null input.

Interactively, or when display is non-nil, the return value is also displayed in the echo area.

See also the functions read-coding-system and read-non-nil-coding-system, in @ref{User-Chosen Coding Systems}, and read-input-method-name, in @ref{Input Methods}.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.6.5 Reading File Names

The high-level completion functions read-file-name, read-directory-name, and read-shell-command are designed to read file names, directory names, and shell commands, respectively. They provide special features, including automatic insertion of the default directory.

Function: read-file-name prompt &optional directory default require-match initial predicate

This function reads a file name, prompting with prompt and providing completion.

As an exception, this function reads a file name using a graphical file dialog instead of the minibuffer, if all of the following are true:

  1. It is invoked via a mouse command.
  2. The selected frame is on a graphical display supporting such dialogs.
  3. The variable use-dialog-box is non-nil. See Dialog Boxes in The GNU Emacs Manual.
  4. The directory argument, described below, does not specify a remote file. See Remote Files in The GNU Emacs Manual.

The exact behavior when using a graphical file dialog is platform-dependent. Here, we simply document the behavior when using the minibuffer.

read-file-name does not automatically expand the returned file name. You must call expand-file-name yourself if an absolute file name is required.

The optional argument require-match has the same meaning as in completing-read. See section Completion and the Minibuffer.

The argument directory specifies the directory to use for completing relative file names. It should be an absolute directory name. If the variable insert-default-directory is non-nil, directory is also inserted in the minibuffer as initial input. It defaults to the current buffer’s value of default-directory.

If you specify initial, that is an initial file name to insert in the buffer (after directory, if that is inserted). In this case, point goes at the beginning of initial. The default for initial is nil—don’t insert any file name. To see what initial does, try the command C-x C-v in a buffer visiting a file. Please note: we recommend using default rather than initial in most cases.

If default is non-nil, then the function returns default if the user exits the minibuffer with the same non-empty contents that read-file-name inserted initially. The initial minibuffer contents are always non-empty if insert-default-directory is non-nil, as it is by default. default is not checked for validity, regardless of the value of require-match. However, if require-match is non-nil, the initial minibuffer contents should be a valid file (or directory) name. Otherwise read-file-name attempts completion if the user exits without any editing, and does not return default. default is also available through the history commands.

If default is nil, read-file-name tries to find a substitute default to use in its place, which it treats in exactly the same way as if it had been specified explicitly. If default is nil, but initial is non-nil, then the default is the absolute file name obtained from directory and initial. If both default and initial are nil and the buffer is visiting a file, read-file-name uses the absolute file name of that file as default. If the buffer is not visiting a file, then there is no default. In that case, if the user types <RET> without any editing, read-file-name simply returns the pre-inserted contents of the minibuffer.

If the user types <RET> in an empty minibuffer, this function returns an empty string, regardless of the value of require-match. This is, for instance, how the user can make the current buffer visit no file using M-x set-visited-file-name.

If predicate is non-nil, it specifies a function of one argument that decides which file names are acceptable completion alternatives. A file name is an acceptable value if predicate returns non-nil for it.

Here is an example of using read-file-name:

(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 ----------

Typing manual <TAB> results in the following:

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

If the user types <RET>, read-file-name returns the file name as the string "/gp/gnu/elisp/manual.texi".

Variable: read-file-name-function

If non-nil, this should be a function that accepts the same arguments as read-file-name. When read-file-name is called, it calls this function with the supplied arguments instead of doing its usual work.

User Option: read-file-name-completion-ignore-case

If this variable is non-nil, read-file-name ignores case when performing completion.

Function: read-directory-name prompt &optional directory default require-match initial

This function is like read-file-name but allows only directory names as completion alternatives.

If default is nil and initial is non-nil, read-directory-name constructs a substitute default by combining directory (or the current buffer’s default directory if directory is nil) and initial. If both default and initial are nil, this function uses directory as substitute default, or the current buffer’s default directory if directory is nil.

User Option: insert-default-directory

This variable is used by read-file-name, and thus, indirectly, by most commands reading file names. (This includes all commands that use the code letters ‘f’ or ‘F’ in their interactive form. @xref{Interactive Codes,, Code Characters for interactive}.) Its value controls whether read-file-name starts by placing the name of the default directory in the minibuffer, plus the initial file name, if any. If the value of this variable is nil, then read-file-name does not place any initial input in the minibuffer (unless you specify initial input with the initial argument). In that case, the default directory is still used for completion of relative file names, but is not displayed.

If this variable is nil and the initial minibuffer contents are empty, the user may have to explicitly fetch the next history element to access a default value. If the variable is non-nil, the initial minibuffer contents are always non-empty and the user can always request a default value by immediately typing <RET> in an unedited minibuffer. (See above.)

For example:

;; 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 ----------
Function: read-shell-command prompt &optional initial history &rest args

This function reads a shell command from the minibuffer, prompting with prompt and providing intelligent completion. It completes the first word of the command using candidates that are appropriate for command names, and the rest of the command words as file names.

This function uses minibuffer-local-shell-command-map as the keymap for minibuffer input. The history argument specifies the history list to use; if is omitted or nil, it defaults to shell-command-history (see section shell-command-history). The optional argument initial specifies the initial content of the minibuffer (see section Initial Input). The rest of args, if present, are used as the default and inherit-input-method arguments in read-from-minibuffer (see section Reading Text Strings with the Minibuffer).

Variable: minibuffer-local-shell-command-map

This keymap is used by read-shell-command for completing command and file names that are part of a shell command. It uses minibuffer-local-map as its parent keymap, and binds <TAB> to completion-at-point.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.6.6 Completion Variables

Here are some variables that can be used to alter the default completion behavior.

User Option: completion-styles

The value of this variable is a list of completion style (symbols) to use for performing completion. A completion style is a set of rules for generating completions. Each symbol occurring this list must have a corresponding entry in completion-styles-alist.

Variable: completion-styles-alist

This variable stores a list of available completion styles. Each element in the list has the form

(style try-completion all-completions doc)

Here, style is the name of the completion style (a symbol), which may be used in the completion-styles variable to refer to this style; try-completion is the function that does the completion; all-completions is the function that lists the completions; and doc is a string describing the completion style.

The try-completion and all-completions functions should each accept four arguments: string, collection, predicate, and point. The string, collection, and predicate arguments have the same meanings as in try-completion (see section Basic Completion Functions), and the point argument is the position of point within string. Each function should return a non-nil value if it performed its job, and nil if it did not (e.g., if there is no way to complete string according to the completion style).

When the user calls a completion command like minibuffer-complete (see section Minibuffer Commands that Do Completion), Emacs looks for the first style listed in completion-styles and calls its try-completion function. If this function returns nil, Emacs moves to the next listed completion style and calls its try-completion function, and so on until one of the try-completion functions successfully performs completion and returns a non-nil value. A similar procedure is used for listing completions, via the all-completions functions.

See Completion Styles in The GNU Emacs Manual, for a description of the available completion styles.

User Option: completion-category-overrides

This variable specifies special completion styles and other completion behaviors to use when completing certain types of text. Its value should be an alist with elements of the form (category . alist). category is a symbol describing what is being completed; currently, the buffer, file, and unicode-name categories are defined, but others can be defined via specialized completion functions (see section Programmed Completion). alist is an association list describing how completion should behave for the corresponding category. The following alist keys are supported:

styles

The value should be a list of completion styles (symbols).

cycle

The value should be a value for completion-cycle-threshold (see Completion Options in The GNU Emacs Manual) for this category.

Additional alist entries may be defined in the future.

Variable: completion-extra-properties

This variable is used to specify extra properties of the current completion command. It is intended to be let-bound by specialized completion commands. Its value should be a list of property and value pairs. The following properties are supported:

:annotation-function

The value should be a function to add annotations in the completions buffer. This function must accept one argument, a completion, and should either return nil or a string to be displayed next to the completion.

:exit-function

The value should be a function to run after performing completion. The function should accept two arguments, string and status, where string is the text to which the field was completed, and status indicates what kind of operation happened: finished if text is now complete, sole if the text cannot be further completed but completion is not finished, or exact if the text is a valid completion but may be further completed.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.6.7 Programmed Completion

Sometimes it is not possible or convenient to create an alist or an obarray containing all the intended possible completions ahead of time. In such a case, you can supply your own function to compute the completion of a given string. This is called programmed completion. Emacs uses programmed completion when completing file names (@pxref{File Name Completion}), among many other cases.

To use this feature, pass a function as the collection argument to completing-read. The function completing-read arranges to pass your completion function along to try-completion, all-completions, and other basic completion functions, which will then let your function do all the work.

The completion function should accept three arguments:

The following is a list of metadata entries that a completion function may return in response to a metadata flag argument:

category

The value should be a symbol describing what kind of text the completion function is trying to complete. If the symbol matches one of the keys in completion-category-overrides, the usual completion behavior is overridden. See section Completion Variables.

annotation-function

The value should be a function for annotating completions. The function should take one argument, string, which is a possible completion. It should return a string, which is displayed after the completion string in the ‘*Completions*’ buffer.

display-sort-function

The value should be a function for sorting completions. The function should take one argument, a list of completion strings, and return a sorted list of completion strings. It is allowed to alter the input list destructively.

cycle-sort-function

The value should be a function for sorting completions, when completion-cycle-threshold is non-nil and the user is cycling through completion alternatives. See Completion Options in The GNU Emacs Manual. Its argument list and return value are the same as for display-sort-function.

Function: completion-table-dynamic function &optional switch-buffer

This function is a convenient way to write a function that can act as a programmed completion function. The argument function should be a function that takes one argument, a string, and returns an alist of possible completions of it. It is allowed to ignore the argument and return a full list of all possible completions. You can think of completion-table-dynamic as a transducer between that interface and the interface for programmed completion functions.

If the optional argument switch-buffer is non-nil, and completion is performed in the minibuffer, function will be called with current buffer set to the buffer from which the minibuffer was entered.

Function: completion-table-with-cache function &optional ignore-case

This is a wrapper for completion-table-dynamic that saves the last argument-result pair. This means that multiple lookups with the same argument only need to call function once. This can be useful when a slow operation is involved, such as calling an external process.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.6.8 Completion in Ordinary Buffers

Although completion is usually done in the minibuffer, the completion facility can also be used on the text in ordinary Emacs buffers. In many major modes, in-buffer completion is performed by the C-M-i or M-<TAB> command, bound to completion-at-point. See Symbol Completion in The GNU Emacs Manual. This command uses the abnormal hook variable completion-at-point-functions:

Variable: completion-at-point-functions

The value of this abnormal hook should be a list of functions, which are used to compute a completion table for completing the text at point. It can be used by major modes to provide mode-specific completion tables (@pxref{Major Mode Conventions}).

When the command completion-at-point runs, it calls the functions in the list one by one, without any argument. Each function should return nil if it is unable to produce a completion table for the text at point. Otherwise it should return a list of the form

(start end collection . props)

start and end delimit the text to complete (which should enclose point). collection is a completion table for completing that text, in a form suitable for passing as the second argument to try-completion (see section Basic Completion Functions); completion alternatives will be generated from this completion table in the usual way, via the completion styles defined in completion-styles (see section Completion Variables). props is a property list for additional information; any of the properties in completion-extra-properties are recognized (see section Completion Variables), as well as the following additional ones:

:predicate

The value should be a predicate that completion candidates need to satisfy.

:exclusive

If the value is no, then if the completion table fails to match the text at point, completion-at-point moves on to the next function in completion-at-point-functions instead of reporting a completion failure.

Supplying a function for collection is strongly recommended if generating the list of completions is an expensive operation. Emacs may internally call functions in completion-at-point-functions many times, but care about the value of collection for only some of these calls. By supplying a function for collection, Emacs can defer generating completions until necessary. You can use completion-table-dynamic to create a wrapper function:

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

A function in completion-at-point-functions may also return a function instead of a list as described above. In that case, that returned function is called, with no argument, and it is entirely responsible for performing the completion. We discourage this usage; it is intended to help convert old code to using completion-at-point.

The first function in completion-at-point-functions to return a non-nil value is used by completion-at-point. The remaining functions are not called. The exception to this is when there is an :exclusive specification, as described above.

The following function provides a convenient way to perform completion on an arbitrary stretch of text in an Emacs buffer:

Function: completion-in-region start end collection &optional predicate

This function completes the text in the current buffer between the positions start and end, using collection. The argument collection has the same meaning as in try-completion (see section Basic Completion Functions).

This function inserts the completion text directly into the current buffer. Unlike completing-read (see section Completion and the Minibuffer), it does not activate the minibuffer.

For this function to work, point must be somewhere between start and end.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.7 Yes-or-No Queries

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—more precisely, if last-nonmenu-event (@pxref{Command Loop Info}) is either nil or a list—then it uses a dialog box or pop-up menu to ask the question. Otherwise, it uses 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.

Strictly speaking, yes-or-no-p uses the minibuffer and y-or-n-p does not; but it seems best to describe them together.

Function: y-or-n-p prompt

This function asks the user a question, expecting input in the echo area. 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-] to quit, like C-g, because the question might look like a 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 echo area, 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.

This function does not actually use the minibuffer, since it does not allow editing of the answer. It actually uses the echo area (@pxref{The Echo Area}), which uses the same screen space as the minibuffer. The cursor moves to the echo area 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 (@pxref{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.

We show successive lines of echo area messages, but only one actually appears on the screen at a time.

Function: y-or-n-p-with-timeout prompt seconds default

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 @ref{Timers}. The argument seconds should be a number.

Function: yes-or-no-p prompt

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 echo area, followed by ‘(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.

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

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.8 Asking Multiple Y-or-N 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.

Function: map-y-or-n-p prompter actor list &optional help action-alist no-cursor-in-echo-area

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

If not a string, prompter should be a function of one argument (the next object to ask about) and should return the question text. If the value is a string, that is the question to ask the user. The function can also return t, meaning do act on this object (and don’t ask the user), or nil, meaning ignore this object (and don’t ask the user).

The argument actor says how to act on the answers that the user gives. It should be a function of one argument, and it is called with each object that the user says yes for. Its argument is always an object obtained from list.

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 the objects conceptually being acted on, plural is the corresponding plural noun, and action is a transitive verb describing what actor does.

If you don’t specify help, the default is ("object" "objects" "act on").

Each time a question is asked, the user may enter y, Y, or <SPC> to act on that object; n, N, or <DEL> to skip that object; ! to act on all following objects; <ESC> or q to exit (skip all following objects); . (period) to act on the current object and then exit; or C-h to 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 @ref{Search and Replace}.

You can use action-alist to specify additional possible answers and what they mean. It is an alist of elements of the form (char function help), each of which defines one additional answer. In this element, char is a character (the answer); function is a function of one argument (an object from list); 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 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.

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—more precisely, if last-nonmenu-event (@pxref{Command Loop Info}) is either nil or a list—then it uses a dialog box or pop-up menu to ask the question. 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.

The return value of map-y-or-n-p is the number of objects acted on.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.9 Reading a Password

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

Function: read-passwd prompt &optional confirm default

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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.10 Minibuffer Commands

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.

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; @pxref{Command Loop Info}).

Command: previous-history-element n

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

Command: next-history-element n

This command replaces the minibuffer contents with the value of the nth more recent history element.

Command: previous-matching-history-element pattern n

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

Command: next-matching-history-element pattern n

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

Command: previous-complete-history-element n

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

Command: next-complete-history-element n

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


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.11 Minibuffer Windows

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

Function: active-minibuffer-window

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

Function: minibuffer-window &optional frame

This function returns the minibuffer window used for frame frame. If frame is nil, that stands for the current 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.

Function: set-minibuffer-window 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 current frame.

Function: window-minibuffer-p &optional window

This function returns non-nil if window is a minibuffer window. window defaults to the selected window.

It is not correct to determine whether a given window is a 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.

Function: minibuffer-window-active-p window

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

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

User Option: 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 (@pxref{Resizing Windows}) can be used to adjust its height.

User Option: max-mini-window-height

This option provides a maximum height for resizing minibuffer windows automatically. A floating-point number specifies a fraction of the frame’s height; an integer specifies the maximum number of lines. The default value is 0.25.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.12 Minibuffer Contents

These functions access the minibuffer prompt and contents.

Function: minibuffer-prompt

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

Function: 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.

Function: minibuffer-prompt-width

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

Function: 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.

Function: minibuffer-contents-no-properties

This is like minibuffer-contents, except that it does not copy text properties, just the characters themselves. @xref{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.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.13 Recursive Minibuffers

These functions and variables deal with recursive minibuffers (@pxref{Recursive Editing}):

Function: minibuffer-depth

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

User Option: enable-recursive-minibuffers

If this variable is non-nil, you can invoke commands (such as find-file) that use minibuffers even while the minibuffer window is active. Such invocation produces a recursive editing level for a new minibuffer. The outer-level minibuffer is invisible while you are editing the inner one.

If this variable is nil, you cannot invoke minibuffer commands when the minibuffer window 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 (@pxref{Using Interactive}). The minibuffer command next-matching-history-element (normally M-s in the minibuffer) does the latter.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.14 Minibuffer Miscellany

Function: minibufferp &optional buffer-or-name

This function returns non-nil if buffer-or-name is a minibuffer. If buffer-or-name is omitted, it tests the current buffer.

Variable: minibuffer-setup-hook

This is a normal hook that is run whenever the minibuffer is entered. @xref{Hooks}.

Variable: minibuffer-exit-hook

This is a normal hook that is run whenever the minibuffer is exited. @xref{Hooks}.

Variable: minibuffer-help-form

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

Variable: 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.

Function: minibuffer-selected-window

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

User Option: max-mini-window-height

This variable specifies the maximum height for resizing minibuffer windows. If a float, it specifies a fraction of the height of the frame. If an integer, it specifies a number of lines.

Function: minibuffer-message string &rest args

This function displays string temporarily at the end of the minibuffer text, 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. @xref{Formatting Strings}.

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. @xref{Minibuffers and Frames}.


[Top] [Contents] [Index] [ ? ]

About This Document

This document was generated on September 17, 2017 using texi2html.

The buttons in the navigation panels have the following meaning:

Button Name Go to From 1.2.3 go to
[ << ] FastBack Beginning of this chapter or previous chapter 1
[ < ] Back Previous section in reading order 1.2.2
[ Up ] Up Up section 1.2
[ > ] Forward Next section in reading order 1.2.4
[ >> ] FastForward Next chapter 2
[Top] Top Cover (top) of document  
[Contents] Contents Table of contents  
[Index] Index Index  
[ ? ] About About (help)  

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:


This document was generated on September 17, 2017 using texi2html.