2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software
5 @c See the file elisp.texi for copying conditions.
8 @cindex arguments, reading
9 @cindex complex arguments
12 A @dfn{minibuffer} is a special buffer that Emacs commands use to
13 read arguments more complicated than the single numeric prefix
14 argument. These arguments include file names, buffer names, and
15 command names (as in @kbd{M-x}). The minibuffer is displayed on the
16 bottom line of the frame, in the same place as the echo area
17 (@pxref{The Echo Area}), but only while it is in use for reading an
21 * Intro to Minibuffers:: Basic information about minibuffers.
22 * Text from Minibuffer:: How to read a straight text string.
23 * Object from Minibuffer:: How to read a Lisp object or expression.
24 * Minibuffer History:: Recording previous minibuffer inputs
25 so the user can reuse them.
26 * Initial Input:: Specifying initial contents for the minibuffer.
27 * Completion:: How to invoke and customize completion.
28 * Yes-or-No Queries:: Asking a question with a simple answer.
29 * Multiple Queries:: Asking a series of similar questions.
30 * Reading a Password:: Reading a password from the terminal.
31 * Minibuffer Commands:: Commands used as key bindings in minibuffers.
32 * Minibuffer Windows:: Operating on the special minibuffer windows.
33 * Minibuffer Contents:: How such commands access the minibuffer text.
34 * Recursive Mini:: Whether recursive entry to minibuffer is allowed.
35 * Minibuffer Misc:: Various customization hooks and variables.
38 @node Intro to Minibuffers
39 @section Introduction to Minibuffers
41 In most ways, a minibuffer is a normal Emacs buffer. Most operations
42 @emph{within} a buffer, such as editing commands, work normally in a
43 minibuffer. However, many operations for managing buffers do not apply
44 to minibuffers. The name of a minibuffer always has the form @w{@samp{
45 *Minibuf-@var{number}*}}, and it cannot be changed. Minibuffers are
46 displayed only in special windows used only for minibuffers; these
47 windows always appear at the bottom of a frame. (Sometimes frames have
48 no minibuffer window, and sometimes a special kind of frame contains
49 nothing but a minibuffer window; see @ref{Minibuffers and Frames}.)
51 The text in the minibuffer always starts with the @dfn{prompt string},
52 the text that was specified by the program that is using the minibuffer
53 to tell the user what sort of input to type. This text is marked
54 read-only so you won't accidentally delete or change it. It is also
55 marked as a field (@pxref{Fields}), so that certain motion functions,
56 including @code{beginning-of-line}, @code{forward-word},
57 @code{forward-sentence}, and @code{forward-paragraph}, stop at the
58 boundary between the prompt and the actual text.
60 @c See http://debbugs.gnu.org/11276
61 The minibuffer's window is normally a single line; it grows
62 automatically if the contents require more space. Whilst it is
63 active, you can explicitly resize it temporarily with the window
64 sizing commands; it reverts to its normal size when the minibuffer is
65 exited. When the minibuffer is not active, you can resize it
66 permanently by using the window sizing commands in the frame's other
67 window, or dragging the mode line with the mouse. (Due to details of
68 the current implementation, for this to work @code{resize-mini-windows}
69 must be @code{nil}.) If the frame contains just a minibuffer, you can
70 change the minibuffer's size by changing the frame's size.
72 Use of the minibuffer reads input events, and that alters the values
73 of variables such as @code{this-command} and @code{last-command}
74 (@pxref{Command Loop Info}). Your program should bind them around the
75 code that uses the minibuffer, if you do not want that to change them.
77 Under some circumstances, a command can use a minibuffer even if
78 there is an active minibuffer; such a minibuffer is called a
79 @dfn{recursive minibuffer}. The first minibuffer is named
80 @w{@samp{ *Minibuf-1*}}. Recursive minibuffers are named by
81 incrementing the number at the end of the name. (The names begin with
82 a space so that they won't show up in normal buffer lists.) Of
83 several recursive minibuffers, the innermost (or most recently
84 entered) is the active minibuffer. We usually call this @emph{the}
85 minibuffer. You can permit or forbid recursive minibuffers by setting
86 the variable @code{enable-recursive-minibuffers}, or by putting
87 properties of that name on command symbols (@xref{Recursive Mini}.)
89 Like other buffers, a minibuffer uses a local keymap
90 (@pxref{Keymaps}) to specify special key bindings. The function that
91 invokes the minibuffer also sets up its local map according to the job
92 to be done. @xref{Text from Minibuffer}, for the non-completion
93 minibuffer local maps. @xref{Completion Commands}, for the minibuffer
94 local maps for completion.
96 @cindex inactive minibuffer
97 When a minibuffer is inactive, its major mode is
98 @code{minibuffer-inactive-mode}, with keymap
99 @code{minibuffer-inactive-mode-map}. This is only really useful if
100 the minibuffer is in a separate frame. @xref{Minibuffers and Frames}.
102 When Emacs is running in batch mode, any request to read from the
103 minibuffer actually reads a line from the standard input descriptor that
104 was supplied when Emacs was started. This supports only basic input:
105 none of the special minibuffer features (history, completion, etc.)@:
106 are available in batch mode.
108 @node Text from Minibuffer
109 @section Reading Text Strings with the Minibuffer
110 @cindex minibuffer input, reading text strings
112 The most basic primitive for minibuffer input is
113 @code{read-from-minibuffer}, which can be used to read either a string
114 or a Lisp object in textual form. The function @code{read-regexp} is
115 used for reading regular expressions (@pxref{Regular Expressions}),
116 which are a special kind of string. There are also specialized
117 functions for reading commands, variables, file names, etc.@:
118 (@pxref{Completion}).
120 In most cases, you should not call minibuffer input functions in the
121 middle of a Lisp function. Instead, do all minibuffer input as part of
122 reading the arguments for a command, in the @code{interactive}
123 specification. @xref{Defining Commands}.
125 @defun read-from-minibuffer prompt &optional initial keymap read history default inherit-input-method
126 This function is the most general way to get input from the
127 minibuffer. By default, it accepts arbitrary text and returns it as a
128 string; however, if @var{read} is non-@code{nil}, then it uses
129 @code{read} to convert the text into a Lisp object (@pxref{Input
132 The first thing this function does is to activate a minibuffer and
133 display it with @var{prompt} (which must be a string) as the
134 prompt. Then the user can edit text in the minibuffer.
136 When the user types a command to exit the minibuffer,
137 @code{read-from-minibuffer} constructs the return value from the text in
138 the minibuffer. Normally it returns a string containing that text.
139 However, if @var{read} is non-@code{nil}, @code{read-from-minibuffer}
140 reads the text and returns the resulting Lisp object, unevaluated.
141 (@xref{Input Functions}, for information about reading.)
143 The argument @var{default} specifies default values to make available
144 through the history commands. It should be a string, a list of
145 strings, or @code{nil}. The string or strings become the minibuffer's
146 ``future history'', available to the user with @kbd{M-n}.
148 If @var{read} is non-@code{nil}, then @var{default} is also used
149 as the input to @code{read}, if the user enters empty input.
150 If @var{default} is a list of strings, the first string is used as the input.
151 If @var{default} is @code{nil}, empty input results in an @code{end-of-file} error.
152 However, in the usual case (where @var{read} is @code{nil}),
153 @code{read-from-minibuffer} ignores @var{default} when the user enters
154 empty input and returns an empty string, @code{""}. In this respect,
155 it differs from all the other minibuffer input functions in this chapter.
157 If @var{keymap} is non-@code{nil}, that keymap is the local keymap to
158 use in the minibuffer. If @var{keymap} is omitted or @code{nil}, the
159 value of @code{minibuffer-local-map} is used as the keymap. Specifying
160 a keymap is the most important way to customize the minibuffer for
161 various applications such as completion.
163 The argument @var{history} specifies a history list variable to use
164 for saving the input and for history commands used in the minibuffer.
165 It defaults to @code{minibuffer-history}. You can optionally specify
166 a starting position in the history list as well. @xref{Minibuffer History}.
168 If the variable @code{minibuffer-allow-text-properties} is
169 non-@code{nil}, then the string that is returned includes whatever text
170 properties were present in the minibuffer. Otherwise all the text
171 properties are stripped when the value is returned.
173 If the argument @var{inherit-input-method} is non-@code{nil}, then the
174 minibuffer inherits the current input method (@pxref{Input Methods}) and
175 the setting of @code{enable-multibyte-characters} (@pxref{Text
176 Representations}) from whichever buffer was current before entering the
179 Use of @var{initial} is mostly deprecated; we recommend using
180 a non-@code{nil} value only in conjunction with specifying a cons cell
181 for @var{history}. @xref{Initial Input}.
184 @defun read-string prompt &optional initial history default inherit-input-method
185 This function reads a string from the minibuffer and returns it. The
186 arguments @var{prompt}, @var{initial}, @var{history} and
187 @var{inherit-input-method} are used as in @code{read-from-minibuffer}.
188 The keymap used is @code{minibuffer-local-map}.
190 The optional argument @var{default} is used as in
191 @code{read-from-minibuffer}, except that, if non-@code{nil}, it also
192 specifies a default value to return if the user enters null input. As
193 in @code{read-from-minibuffer} it should be a string, a list of
194 strings, or @code{nil}, which is equivalent to an empty string. When
195 @var{default} is a string, that string is the default value. When it
196 is a list of strings, the first string is the default value. (All
197 these strings are available to the user in the ``future minibuffer
200 This function works by calling the
201 @code{read-from-minibuffer} function:
205 (read-string @var{prompt} @var{initial} @var{history} @var{default} @var{inherit})
208 (read-from-minibuffer @var{prompt} @var{initial} nil nil
209 @var{history} @var{default} @var{inherit})))
210 (if (and (equal value "") @var{default})
211 (if (consp @var{default}) (car @var{default}) @var{default})
217 @defun read-regexp prompt &optional defaults history
218 This function reads a regular expression as a string from the
219 minibuffer and returns it. If the minibuffer prompt string
220 @var{prompt} does not end in @samp{:} (followed by optional
221 whitespace), the function adds @samp{: } to the end, preceded by the
222 default return value (see below), if that is non-empty.
224 The optional argument @var{defaults} controls the default value to
225 return if the user enters null input, and should be one of: a string;
226 @code{nil}, which is equivalent to an empty string; a list of strings;
229 If @var{defaults} is a symbol, @code{read-regexp} consults the value
230 of the variable @code{read-regexp-defaults-function} (see below), and
231 if that is non-@code{nil} uses it in preference to @var{defaults}.
232 The value in this case should be either:
236 @code{regexp-history-last}, which means to use the first element of
237 the appropriate minibuffer history list (see below).
240 A function of no arguments, whose return value (which should be
241 @code{nil}, a string, or a list of strings) becomes the value of
245 @code{read-regexp} now ensures that the result of processing
246 @var{defaults} is a list (i.e., if the value is @code{nil} or a
247 string, it converts it to a list of one element). To this list,
248 @code{read-regexp} then appends a few potentially useful candidates for
253 The word or symbol at point.
255 The last regexp used in an incremental search.
257 The last string used in an incremental search.
259 The last string or pattern used in query-replace commands.
262 The function now has a list of regular expressions that it passes to
263 @code{read-from-minibuffer} to obtain the user's input. The first
264 element of the list is the default result in case of empty input. All
265 elements of the list are available to the user as the ``future
266 minibuffer history'' list (@pxref{Minibuffer History, future list,,
267 emacs, The GNU Emacs Manual}).
269 The optional argument @var{history}, if non-@code{nil}, is a symbol
270 specifying a minibuffer history list to use (@pxref{Minibuffer
271 History}). If it is omitted or @code{nil}, the history list defaults
272 to @code{regexp-history}.
275 @defvar read-regexp-defaults-function
276 The function @code{read-regexp} may use the value of this variable to
277 determine its list of default regular expressions. If non-@code{nil},
278 the value of this variable should be either:
282 The symbol @code{regexp-history-last}.
285 A function of no arguments that returns either @code{nil}, a string,
286 or a list of strings.
290 See @code{read-regexp} above for details of how these values are used.
293 @defvar minibuffer-allow-text-properties
294 If this variable is @code{nil}, then @code{read-from-minibuffer}
295 and @code{read-string} strip all text properties from the minibuffer
296 input before returning it. However,
297 @code{read-no-blanks-input} (see below), as well as
298 @code{read-minibuffer} and related functions (@pxref{Object from
299 Minibuffer,, Reading Lisp Objects With the Minibuffer}), and all
300 functions that do minibuffer input with completion, discard text
301 properties unconditionally, regardless of the value of this variable.
304 @defvar minibuffer-local-map
306 @anchor{Definition of minibuffer-local-map}
307 @c avoid page break at anchor; work around Texinfo deficiency
308 is the default local keymap for reading from the minibuffer. By
309 default, it makes the following bindings:
313 @code{exit-minibuffer}
316 @code{exit-minibuffer}
319 @code{abort-recursive-edit}
323 @code{next-history-element}
327 @code{previous-history-element}
330 @code{next-matching-history-element}
333 @code{previous-matching-history-element}
336 @c Does not seem worth/appropriate mentioning.
337 @item @kbd{C-@key{TAB}}
338 @code{file-cache-minibuffer-complete}
343 @c In version 18, initial is required
345 @defun read-no-blanks-input prompt &optional initial inherit-input-method
346 This function reads a string from the minibuffer, but does not allow
347 whitespace characters as part of the input: instead, those characters
348 terminate the input. The arguments @var{prompt}, @var{initial}, and
349 @var{inherit-input-method} are used as in @code{read-from-minibuffer}.
351 This is a simplified interface to the @code{read-from-minibuffer}
352 function, and passes the value of the @code{minibuffer-local-ns-map}
353 keymap as the @var{keymap} argument for that function. Since the keymap
354 @code{minibuffer-local-ns-map} does not rebind @kbd{C-q}, it @emph{is}
355 possible to put a space into the string, by quoting it.
357 This function discards text properties, regardless of the value of
358 @code{minibuffer-allow-text-properties}.
362 (read-no-blanks-input @var{prompt} @var{initial})
364 (let (minibuffer-allow-text-properties)
365 (read-from-minibuffer @var{prompt} @var{initial} minibuffer-local-ns-map))
370 @c Slightly unfortunate name, suggesting it might be related to the
372 @defvar minibuffer-local-ns-map
373 This built-in variable is the keymap used as the minibuffer local keymap
374 in the function @code{read-no-blanks-input}. By default, it makes the
375 following bindings, in addition to those of @code{minibuffer-local-map}:
379 @cindex @key{SPC} in minibuffer
380 @code{exit-minibuffer}
383 @cindex @key{TAB} in minibuffer
384 @code{exit-minibuffer}
387 @cindex @kbd{?} in minibuffer
388 @code{self-insert-and-exit}
392 @node Object from Minibuffer
393 @section Reading Lisp Objects with the Minibuffer
394 @cindex minibuffer input, reading lisp objects
396 This section describes functions for reading Lisp objects with the
399 @defun read-minibuffer prompt &optional initial
400 This function reads a Lisp object using the minibuffer, and returns it
401 without evaluating it. The arguments @var{prompt} and @var{initial} are
402 used as in @code{read-from-minibuffer}.
404 This is a simplified interface to the
405 @code{read-from-minibuffer} function:
409 (read-minibuffer @var{prompt} @var{initial})
411 (let (minibuffer-allow-text-properties)
412 (read-from-minibuffer @var{prompt} @var{initial} nil t))
416 Here is an example in which we supply the string @code{"(testing)"} as
422 "Enter an expression: " (format "%s" '(testing)))
424 ;; @r{Here is how the minibuffer is displayed:}
428 ---------- Buffer: Minibuffer ----------
429 Enter an expression: (testing)@point{}
430 ---------- Buffer: Minibuffer ----------
435 The user can type @key{RET} immediately to use the initial input as a
436 default, or can edit the input.
439 @defun eval-minibuffer prompt &optional initial
440 This function reads a Lisp expression using the minibuffer, evaluates
441 it, then returns the result. The arguments @var{prompt} and
442 @var{initial} are used as in @code{read-from-minibuffer}.
444 This function simply evaluates the result of a call to
445 @code{read-minibuffer}:
449 (eval-minibuffer @var{prompt} @var{initial})
451 (eval (read-minibuffer @var{prompt} @var{initial}))
456 @defun edit-and-eval-command prompt form
457 This function reads a Lisp expression in the minibuffer, evaluates it,
458 then returns the result. The difference between this command and
459 @code{eval-minibuffer} is that here the initial @var{form} is not
460 optional and it is treated as a Lisp object to be converted to printed
461 representation rather than as a string of text. It is printed with
462 @code{prin1}, so if it is a string, double-quote characters (@samp{"})
463 appear in the initial text. @xref{Output Functions}.
465 In the following example, we offer the user an expression with initial
466 text that is already a valid form:
470 (edit-and-eval-command "Please edit: " '(forward-word 1))
472 ;; @r{After evaluation of the preceding expression,}
473 ;; @r{the following appears in the minibuffer:}
477 ---------- Buffer: Minibuffer ----------
478 Please edit: (forward-word 1)@point{}
479 ---------- Buffer: Minibuffer ----------
484 Typing @key{RET} right away would exit the minibuffer and evaluate the
485 expression, thus moving point forward one word.
488 @node Minibuffer History
489 @section Minibuffer History
490 @cindex minibuffer history
493 A @dfn{minibuffer history list} records previous minibuffer inputs
494 so the user can reuse them conveniently. It is a variable whose value
495 is a list of strings (previous inputs), most recent first.
497 There are many separate minibuffer history lists, used for different
498 kinds of inputs. It's the Lisp programmer's job to specify the right
499 history list for each use of the minibuffer.
501 You specify a minibuffer history list with the optional @var{history}
502 argument to @code{read-from-minibuffer} or @code{completing-read}.
503 Here are the possible values for it:
507 Use @var{variable} (a symbol) as the history list.
509 @item (@var{variable} . @var{startpos})
510 Use @var{variable} (a symbol) as the history list, and assume that the
511 initial history position is @var{startpos} (a nonnegative integer).
513 Specifying 0 for @var{startpos} is equivalent to just specifying the
514 symbol @var{variable}. @code{previous-history-element} will display
515 the most recent element of the history list in the minibuffer. If you
516 specify a positive @var{startpos}, the minibuffer history functions
517 behave as if @code{(elt @var{variable} (1- @var{startpos}))} were the
518 history element currently shown in the minibuffer.
520 For consistency, you should also specify that element of the history
521 as the initial minibuffer contents, using the @var{initial} argument
522 to the minibuffer input function (@pxref{Initial Input}).
525 If you don't specify @var{history}, then the default history list
526 @code{minibuffer-history} is used. For other standard history lists,
527 see below. You can also create your own history list variable; just
528 initialize it to @code{nil} before the first use.
530 Both @code{read-from-minibuffer} and @code{completing-read} add new
531 elements to the history list automatically, and provide commands to
532 allow the user to reuse items on the list. The only thing your program
533 needs to do to use a history list is to initialize it and to pass its
534 name to the input functions when you wish. But it is safe to modify the
535 list by hand when the minibuffer input functions are not using it.
537 Emacs functions that add a new element to a history list can also
538 delete old elements if the list gets too long. The variable
539 @code{history-length} specifies the maximum length for most history
540 lists. To specify a different maximum length for a particular history
541 list, put the length in the @code{history-length} property of the
542 history list symbol. The variable @code{history-delete-duplicates}
543 specifies whether to delete duplicates in history.
545 @defun add-to-history history-var newelt &optional maxelt keep-all
546 This function adds a new element @var{newelt}, if it isn't the empty
547 string, to the history list stored in the variable @var{history-var},
548 and returns the updated history list. It limits the list length to
549 the value of @var{maxelt} (if non-@code{nil}) or @code{history-length}
550 (described below). The possible values of @var{maxelt} have the same
551 meaning as the values of @code{history-length}.
553 Normally, @code{add-to-history} removes duplicate members from the
554 history list if @code{history-delete-duplicates} is non-@code{nil}.
555 However, if @var{keep-all} is non-@code{nil}, that says not to remove
556 duplicates, and to add @var{newelt} to the list even if it is empty.
559 @defvar history-add-new-input
560 If the value of this variable is @code{nil}, standard functions that
561 read from the minibuffer don't add new elements to the history list.
562 This lets Lisp programs explicitly manage input history by using
563 @code{add-to-history}. The default value is @code{t}.
566 @defopt history-length
567 The value of this variable specifies the maximum length for all
568 history lists that don't specify their own maximum lengths. If the
569 value is @code{t}, that means there is no maximum (don't delete old
570 elements). If a history list variable's symbol has a non-@code{nil}
571 @code{history-length} property, it overrides this variable for that
572 particular history list.
575 @defopt history-delete-duplicates
576 If the value of this variable is @code{t}, that means when adding a
577 new history element, all previous identical elements are deleted.
580 Here are some of the standard minibuffer history list variables:
582 @defvar minibuffer-history
583 The default history list for minibuffer history input.
586 @defvar query-replace-history
587 A history list for arguments to @code{query-replace} (and similar
588 arguments to other commands).
591 @defvar file-name-history
592 A history list for file-name arguments.
595 @defvar buffer-name-history
596 A history list for buffer-name arguments.
599 @defvar regexp-history
600 A history list for regular expression arguments.
603 @defvar extended-command-history
604 A history list for arguments that are names of extended commands.
607 @defvar shell-command-history
608 A history list for arguments that are shell commands.
611 @defvar read-expression-history
612 A history list for arguments that are Lisp expressions to evaluate.
615 @defvar face-name-history
616 A history list for arguments that are faces.
619 @c Less common: coding-system-history, input-method-history,
620 @c command-history, grep-history, grep-find-history,
621 @c read-envvar-name-history, setenv-history, yes-or-no-p-history.
624 @section Initial Input
626 Several of the functions for minibuffer input have an argument called
627 @var{initial}. This is a mostly-deprecated
628 feature for specifying that the minibuffer should start out with
629 certain text, instead of empty as usual.
631 If @var{initial} is a string, the minibuffer starts out containing the
632 text of the string, with point at the end, when the user starts to
633 edit the text. If the user simply types @key{RET} to exit the
634 minibuffer, it will use the initial input string to determine the
637 @strong{We discourage use of a non-@code{nil} value for
638 @var{initial}}, because initial input is an intrusive interface.
639 History lists and default values provide a much more convenient method
640 to offer useful default inputs to the user.
642 There is just one situation where you should specify a string for an
643 @var{initial} argument. This is when you specify a cons cell for the
644 @var{history} argument. @xref{Minibuffer History}.
646 @var{initial} can also be a cons cell of the form @code{(@var{string}
647 . @var{position})}. This means to insert @var{string} in the
648 minibuffer but put point at @var{position} within the string's text.
650 As a historical accident, @var{position} was implemented
651 inconsistently in different functions. In @code{completing-read},
652 @var{position}'s value is interpreted as origin-zero; that is, a value
653 of 0 means the beginning of the string, 1 means after the first
654 character, etc. In @code{read-minibuffer}, and the other
655 non-completion minibuffer input functions that support this argument,
656 1 means the beginning of the string, 2 means after the first character,
659 Use of a cons cell as the value for @var{initial} arguments is deprecated.
665 @dfn{Completion} is a feature that fills in the rest of a name
666 starting from an abbreviation for it. Completion works by comparing the
667 user's input against a list of valid names and determining how much of
668 the name is determined uniquely by what the user has typed. For
669 example, when you type @kbd{C-x b} (@code{switch-to-buffer}) and then
670 @c "This is the sort of English up with which I will not put."
671 type the first few letters of the name of the buffer to which you wish
672 to switch, and then type @key{TAB} (@code{minibuffer-complete}), Emacs
673 extends the name as far as it can.
675 Standard Emacs commands offer completion for names of symbols, files,
676 buffers, and processes; with the functions in this section, you can
677 implement completion for other kinds of names.
679 The @code{try-completion} function is the basic primitive for
680 completion: it returns the longest determined completion of a given
681 initial string, with a given set of strings to match against.
683 The function @code{completing-read} provides a higher-level interface
684 for completion. A call to @code{completing-read} specifies how to
685 determine the list of valid names. The function then activates the
686 minibuffer with a local keymap that binds a few keys to commands useful
687 for completion. Other functions provide convenient simple interfaces
688 for reading certain kinds of names with completion.
691 * Basic Completion:: Low-level functions for completing strings.
692 * Minibuffer Completion:: Invoking the minibuffer with completion.
693 * Completion Commands:: Minibuffer commands that do completion.
694 * High-Level Completion:: Convenient special cases of completion
695 (reading buffer names, variable names, etc.).
696 * Reading File Names:: Using completion to read file names and
698 * Completion Variables:: Variables controlling completion behavior.
699 * Programmed Completion:: Writing your own completion function.
700 * Completion in Buffers:: Completing text in ordinary buffers.
703 @node Basic Completion
704 @subsection Basic Completion Functions
706 The following completion functions have nothing in themselves to do
707 with minibuffers. We describe them here to keep them near the
708 higher-level completion features that do use the minibuffer.
710 @defun try-completion string collection &optional predicate
711 This function returns the longest common substring of all possible
712 completions of @var{string} in @var{collection}.
714 @cindex completion table
715 @var{collection} is called the @dfn{completion table}. Its value must
716 be a list of strings or cons cells, an obarray, a hash table, or a
719 @code{try-completion} compares @var{string} against each of the
720 permissible completions specified by the completion table. If no
721 permissible completions match, it returns @code{nil}. If there is
722 just one matching completion, and the match is exact, it returns
723 @code{t}. Otherwise, it returns the longest initial sequence common
724 to all possible matching completions.
726 If @var{collection} is a list, the permissible completions are
727 specified by the elements of the list, each of which should be either
728 a string, or a cons cell whose @sc{car} is either a string or a symbol
729 (a symbol is converted to a string using @code{symbol-name}). If the
730 list contains elements of any other type, those are ignored.
732 @cindex obarray in completion
733 If @var{collection} is an obarray (@pxref{Creating Symbols}), the names
734 of all symbols in the obarray form the set of permissible completions.
736 If @var{collection} is a hash table, then the keys that are strings
737 are the possible completions. Other keys are ignored.
739 You can also use a function as @var{collection}. Then the function is
740 solely responsible for performing completion; @code{try-completion}
741 returns whatever this function returns. The function is called with
742 three arguments: @var{string}, @var{predicate} and @code{nil} (the
743 third argument is so that the same function can be used
744 in @code{all-completions} and do the appropriate thing in either
745 case). @xref{Programmed Completion}.
747 If the argument @var{predicate} is non-@code{nil}, then it must be a
748 function of one argument, unless @var{collection} is a hash table, in
749 which case it should be a function of two arguments. It is used to
750 test each possible match, and the match is accepted only if
751 @var{predicate} returns non-@code{nil}. The argument given to
752 @var{predicate} is either a string or a cons cell (the @sc{car} of
753 which is a string) from the alist, or a symbol (@emph{not} a symbol
754 name) from the obarray. If @var{collection} is a hash table,
755 @var{predicate} is called with two arguments, the string key and the
758 In addition, to be acceptable, a completion must also match all the
759 regular expressions in @code{completion-regexp-list}. (Unless
760 @var{collection} is a function, in which case that function has to
761 handle @code{completion-regexp-list} itself.)
763 In the first of the following examples, the string @samp{foo} is
764 matched by three of the alist @sc{car}s. All of the matches begin with
765 the characters @samp{fooba}, so that is the result. In the second
766 example, there is only one possible match, and it is exact, so the
767 return value is @code{t}.
773 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)))
778 (try-completion "foo" '(("barfoo" 2) ("foo" 3)))
783 In the following example, numerous symbols begin with the characters
784 @samp{forw}, and all of them begin with the word @samp{forward}. In
785 most of the symbols, this is followed with a @samp{-}, but not in all,
786 so no more than @samp{forward} can be completed.
790 (try-completion "forw" obarray)
795 Finally, in the following example, only two of the three possible
796 matches pass the predicate @code{test} (the string @samp{foobaz} is
797 too short). Both of those begin with the string @samp{foobar}.
802 (> (length (car s)) 6))
808 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
815 @c Removed obsolete argument nospace.
816 @defun all-completions string collection &optional predicate
817 This function returns a list of all possible completions of
818 @var{string}. The arguments to this function
819 @c (aside from @var{nospace})
820 are the same as those of @code{try-completion}, and it
821 uses @code{completion-regexp-list} in the same way that
822 @code{try-completion} does.
825 The optional argument @var{nospace} is obsolete. If it is
826 non-@code{nil}, completions that start with a space are ignored unless
827 @var{string} starts with a space.
830 If @var{collection} is a function, it is called with three arguments:
831 @var{string}, @var{predicate} and @code{t}; then @code{all-completions}
832 returns whatever the function returns. @xref{Programmed Completion}.
834 Here is an example, using the function @code{test} shown in the
835 example for @code{try-completion}:
840 (> (length (car s)) 6))
847 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
849 @result{} ("foobar1" "foobar2")
854 @defun test-completion string collection &optional predicate
855 @anchor{Definition of test-completion}
856 This function returns non-@code{nil} if @var{string} is a valid
857 completion alternative specified by @var{collection} and
858 @var{predicate}. The arguments are the same as in
859 @code{try-completion}. For instance, if @var{collection} is a list of
860 strings, this is true if @var{string} appears in the list and
861 @var{predicate} is satisfied.
863 This function uses @code{completion-regexp-list} in the same
864 way that @code{try-completion} does.
866 If @var{predicate} is non-@code{nil} and if @var{collection} contains
867 several strings that are equal to each other, as determined by
868 @code{compare-strings} according to @code{completion-ignore-case},
869 then @var{predicate} should accept either all or none of them.
870 Otherwise, the return value of @code{test-completion} is essentially
873 If @var{collection} is a function, it is called with three arguments,
874 the values @var{string}, @var{predicate} and @code{lambda}; whatever
875 it returns, @code{test-completion} returns in turn.
878 @defun completion-boundaries string collection predicate suffix
879 This function returns the boundaries of the field on which @var{collection}
880 will operate, assuming that @var{string} holds the text before point
881 and @var{suffix} holds the text after point.
883 Normally completion operates on the whole string, so for all normal
884 collections, this will always return @code{(0 . (length
885 @var{suffix}))}. But more complex completion such as completion on
886 files is done one field at a time. For example, completion of
887 @code{"/usr/sh"} will include @code{"/usr/share/"} but not
888 @code{"/usr/share/doc"} even if @code{"/usr/share/doc"} exists.
889 Also @code{all-completions} on @code{"/usr/sh"} will not include
890 @code{"/usr/share/"} but only @code{"share/"}. So if @var{string} is
891 @code{"/usr/sh"} and @var{suffix} is @code{"e/doc"},
892 @code{completion-boundaries} will return @code{(5 . 1)} which tells us
893 that the @var{collection} will only return completion information that
894 pertains to the area after @code{"/usr/"} and before @code{"/doc"}.
897 If you store a completion alist in a variable, you should mark the
898 variable as risky by giving it a non-@code{nil}
899 @code{risky-local-variable} property. @xref{File Local Variables}.
901 @defvar completion-ignore-case
902 If the value of this variable is non-@code{nil}, case is not
903 considered significant in completion. Within @code{read-file-name},
904 this variable is overridden by
905 @code{read-file-name-completion-ignore-case} (@pxref{Reading File
906 Names}); within @code{read-buffer}, it is overridden by
907 @code{read-buffer-completion-ignore-case} (@pxref{High-Level
911 @defvar completion-regexp-list
912 This is a list of regular expressions. The completion functions only
913 consider a completion acceptable if it matches all regular expressions
914 in this list, with @code{case-fold-search} (@pxref{Searching and Case})
915 bound to the value of @code{completion-ignore-case}.
918 @defmac lazy-completion-table var fun
919 This macro provides a way to initialize the variable @var{var} as a
920 collection for completion in a lazy way, not computing its actual
921 contents until they are first needed. You use this macro to produce a
922 value that you store in @var{var}. The actual computation of the
923 proper value is done the first time you do completion using @var{var}.
924 It is done by calling @var{fun} with no arguments. The
925 value @var{fun} returns becomes the permanent value of @var{var}.
930 (defvar foo (lazy-completion-table foo make-my-alist))
934 @c FIXME? completion-table-with-context?
935 @findex completion-table-case-fold
936 @findex completion-table-in-turn
937 @findex completion-table-merge
938 @findex completion-table-subvert
939 @findex completion-table-with-quoting
940 @findex completion-table-with-predicate
941 @findex completion-table-with-terminator
942 @cindex completion table, modifying
943 @cindex completion tables, combining
944 There are several functions that take an existing completion table and
945 return a modified version. @code{completion-table-case-fold} returns
946 a case-insensitive table. @code{completion-table-in-turn} and
947 @code{completion-table-merge} combine multiple input tables in
948 different ways. @code{completion-table-subvert} alters a table to use
949 a different initial prefix. @code{completion-table-with-quoting}
950 returns a table suitable for operating on quoted text.
951 @code{completion-table-with-predicate} filters a table with a
952 predicate function. @code{completion-table-with-terminator} adds a
956 @node Minibuffer Completion
957 @subsection Completion and the Minibuffer
958 @cindex minibuffer completion
959 @cindex reading from minibuffer with completion
961 This section describes the basic interface for reading from the
962 minibuffer with completion.
964 @defun completing-read prompt collection &optional predicate require-match initial history default inherit-input-method
965 This function reads a string in the minibuffer, assisting the user by
966 providing completion. It activates the minibuffer with prompt
967 @var{prompt}, which must be a string.
969 The actual completion is done by passing the completion table
970 @var{collection} and the completion predicate @var{predicate} to the
971 function @code{try-completion} (@pxref{Basic Completion}). This
972 happens in certain commands bound in the local keymaps used for
973 completion. Some of these commands also call @code{test-completion}.
974 Thus, if @var{predicate} is non-@code{nil}, it should be compatible
975 with @var{collection} and @code{completion-ignore-case}.
976 @xref{Definition of test-completion}.
978 @xref{Programmed Completion}, for detailed requirements when
979 @var{collection} is a function.
981 The value of the optional argument @var{require-match} determines how
982 the user may exit the minibuffer:
986 If @code{nil}, the usual minibuffer exit commands work regardless of
987 the input in the minibuffer.
990 If @code{t}, the usual minibuffer exit commands won't exit unless the
991 input completes to an element of @var{collection}.
994 If @code{confirm}, the user can exit with any input, but is asked for
995 confirmation if the input is not an element of @var{collection}.
998 If @code{confirm-after-completion}, the user can exit with any input,
999 but is asked for confirmation if the preceding command was a
1000 completion command (i.e., one of the commands in
1001 @code{minibuffer-confirm-exit-commands}) and the resulting input is
1002 not an element of @var{collection}. @xref{Completion Commands}.
1005 Any other value of @var{require-match} behaves like @code{t}, except
1006 that the exit commands won't exit if it performs completion.
1009 However, empty input is always permitted, regardless of the value of
1010 @var{require-match}; in that case, @code{completing-read} returns the
1011 first element of @var{default}, if it is a list; @code{""}, if
1012 @var{default} is @code{nil}; or @var{default}. The string or strings
1013 in @var{default} are also available to the user through the history
1016 The function @code{completing-read} uses
1017 @code{minibuffer-local-completion-map} as the keymap if
1018 @var{require-match} is @code{nil}, and uses
1019 @code{minibuffer-local-must-match-map} if @var{require-match} is
1020 non-@code{nil}. @xref{Completion Commands}.
1022 The argument @var{history} specifies which history list variable to use for
1023 saving the input and for minibuffer history commands. It defaults to
1024 @code{minibuffer-history}. @xref{Minibuffer History}.
1026 The argument @var{initial} is mostly deprecated; we recommend using a
1027 non-@code{nil} value only in conjunction with specifying a cons cell
1028 for @var{history}. @xref{Initial Input}. For default input, use
1029 @var{default} instead.
1031 If the argument @var{inherit-input-method} is non-@code{nil}, then the
1032 minibuffer inherits the current input method (@pxref{Input
1033 Methods}) and the setting of @code{enable-multibyte-characters}
1034 (@pxref{Text Representations}) from whichever buffer was current before
1035 entering the minibuffer.
1037 If the variable @code{completion-ignore-case} is
1038 non-@code{nil}, completion ignores case when comparing the input
1039 against the possible matches. @xref{Basic Completion}. In this mode
1040 of operation, @var{predicate} must also ignore case, or you will get
1043 Here's an example of using @code{completing-read}:
1049 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
1054 ;; @r{After evaluation of the preceding expression,}
1055 ;; @r{the following appears in the minibuffer:}
1057 ---------- Buffer: Minibuffer ----------
1058 Complete a foo: fo@point{}
1059 ---------- Buffer: Minibuffer ----------
1064 If the user then types @kbd{@key{DEL} @key{DEL} b @key{RET}},
1065 @code{completing-read} returns @code{barfoo}.
1067 The @code{completing-read} function binds variables to pass
1068 information to the commands that actually do completion.
1069 They are described in the following section.
1072 @defvar completing-read-function
1073 The value of this variable must be a function, which is called by
1074 @code{completing-read} to actually do its work. It should accept the
1075 same arguments as @code{completing-read}. This can be bound to a
1076 different function to completely override the normal behavior of
1077 @code{completing-read}.
1080 @node Completion Commands
1081 @subsection Minibuffer Commands that Do Completion
1083 This section describes the keymaps, commands and user options used
1084 in the minibuffer to do completion.
1086 @defvar minibuffer-completion-table
1087 The value of this variable is the completion table used for completion
1088 in the minibuffer. This is the global variable that contains what
1089 @code{completing-read} passes to @code{try-completion}. It is used by
1090 minibuffer completion commands such as
1091 @code{minibuffer-complete-word}.
1094 @defvar minibuffer-completion-predicate
1095 This variable's value is the predicate that @code{completing-read}
1096 passes to @code{try-completion}. The variable is also used by the other
1097 minibuffer completion functions.
1100 @defvar minibuffer-completion-confirm
1101 This variable determines whether Emacs asks for confirmation before
1102 exiting the minibuffer; @code{completing-read} binds this variable,
1103 and the function @code{minibuffer-complete-and-exit} checks the value
1104 before exiting. If the value is @code{nil}, confirmation is not
1105 required. If the value is @code{confirm}, the user may exit with an
1106 input that is not a valid completion alternative, but Emacs asks for
1107 confirmation. If the value is @code{confirm-after-completion}, the
1108 user may exit with an input that is not a valid completion
1109 alternative, but Emacs asks for confirmation if the user submitted the
1110 input right after any of the completion commands in
1111 @code{minibuffer-confirm-exit-commands}.
1114 @defvar minibuffer-confirm-exit-commands
1115 This variable holds a list of commands that cause Emacs to ask for
1116 confirmation before exiting the minibuffer, if the @var{require-match}
1117 argument to @code{completing-read} is @code{confirm-after-completion}.
1118 The confirmation is requested if the user attempts to exit the
1119 minibuffer immediately after calling any command in this list.
1122 @deffn Command minibuffer-complete-word
1123 This function completes the minibuffer contents by at most a single
1124 word. Even if the minibuffer contents have only one completion,
1125 @code{minibuffer-complete-word} does not add any characters beyond the
1126 first character that is not a word constituent. @xref{Syntax Tables}.
1129 @deffn Command minibuffer-complete
1130 This function completes the minibuffer contents as far as possible.
1133 @deffn Command minibuffer-complete-and-exit
1134 This function completes the minibuffer contents, and exits if
1135 confirmation is not required, i.e., if
1136 @code{minibuffer-completion-confirm} is @code{nil}. If confirmation
1137 @emph{is} required, it is given by repeating this command
1138 immediately---the command is programmed to work without confirmation
1139 when run twice in succession.
1142 @deffn Command minibuffer-completion-help
1143 This function creates a list of the possible completions of the
1144 current minibuffer contents. It works by calling @code{all-completions}
1145 using the value of the variable @code{minibuffer-completion-table} as
1146 the @var{collection} argument, and the value of
1147 @code{minibuffer-completion-predicate} as the @var{predicate} argument.
1148 The list of completions is displayed as text in a buffer named
1149 @file{*Completions*}.
1152 @defun display-completion-list completions
1153 This function displays @var{completions} to the stream in
1154 @code{standard-output}, usually a buffer. (@xref{Read and Print}, for more
1155 information about streams.) The argument @var{completions} is normally
1156 a list of completions just returned by @code{all-completions}, but it
1157 does not have to be. Each element may be a symbol or a string, either
1158 of which is simply printed. It can also be a list of two strings,
1159 which is printed as if the strings were concatenated. The first of
1160 the two strings is the actual completion, the second string serves as
1163 This function is called by @code{minibuffer-completion-help}. A
1164 common way to use it is together with
1165 @code{with-output-to-temp-buffer}, like this:
1168 (with-output-to-temp-buffer "*Completions*"
1169 (display-completion-list
1170 (all-completions (buffer-string) my-alist)))
1174 @defopt completion-auto-help
1175 If this variable is non-@code{nil}, the completion commands
1176 automatically display a list of possible completions whenever nothing
1177 can be completed because the next character is not uniquely determined.
1180 @defvar minibuffer-local-completion-map
1181 @code{completing-read} uses this value as the local keymap when an
1182 exact match of one of the completions is not required. By default, this
1183 keymap makes the following bindings:
1187 @code{minibuffer-completion-help}
1190 @code{minibuffer-complete-word}
1193 @code{minibuffer-complete}
1197 and uses @code{minibuffer-local-map} as its parent keymap
1198 (@pxref{Definition of minibuffer-local-map}).
1201 @defvar minibuffer-local-must-match-map
1202 @code{completing-read} uses this value as the local keymap when an
1203 exact match of one of the completions is required. Therefore, no keys
1204 are bound to @code{exit-minibuffer}, the command that exits the
1205 minibuffer unconditionally. By default, this keymap makes the following
1210 @code{minibuffer-complete-and-exit}
1213 @code{minibuffer-complete-and-exit}
1217 and uses @code{minibuffer-local-completion-map} as its parent keymap.
1220 @defvar minibuffer-local-filename-completion-map
1221 This is a sparse keymap that simply unbinds @key{SPC}; because
1222 filenames can contain spaces. The function @code{read-file-name}
1223 combines this keymap with either @code{minibuffer-local-completion-map}
1224 or @code{minibuffer-local-must-match-map}.
1228 @node High-Level Completion
1229 @subsection High-Level Completion Functions
1231 This section describes the higher-level convenience functions for
1232 reading certain sorts of names with completion.
1234 In most cases, you should not call these functions in the middle of a
1235 Lisp function. When possible, do all minibuffer input as part of
1236 reading the arguments for a command, in the @code{interactive}
1237 specification. @xref{Defining Commands}.
1239 @defun read-buffer prompt &optional default require-match
1240 This function reads the name of a buffer and returns it as a string.
1241 The argument @var{default} is the default name to use, the value to
1242 return if the user exits with an empty minibuffer. If non-@code{nil},
1243 it should be a string, a list of strings, or a buffer. If it is
1244 a list, the default value is the first element of this list. It is
1245 mentioned in the prompt, but is not inserted in the minibuffer as
1248 The argument @var{prompt} should be a string ending with a colon and a
1249 space. If @var{default} is non-@code{nil}, the function inserts it in
1250 @var{prompt} before the colon to follow the convention for reading from
1251 the minibuffer with a default value (@pxref{Programming Tips}).
1253 The optional argument @var{require-match} has the same meaning as in
1254 @code{completing-read}. @xref{Minibuffer Completion}.
1256 In the following example, the user enters @samp{minibuffer.t}, and
1257 then types @key{RET}. The argument @var{require-match} is @code{t},
1258 and the only buffer name starting with the given input is
1259 @samp{minibuffer.texi}, so that name is the value.
1262 (read-buffer "Buffer name: " "foo" t)
1264 ;; @r{After evaluation of the preceding expression,}
1265 ;; @r{the following prompt appears,}
1266 ;; @r{with an empty minibuffer:}
1270 ---------- Buffer: Minibuffer ----------
1271 Buffer name (default foo): @point{}
1272 ---------- Buffer: Minibuffer ----------
1276 ;; @r{The user types @kbd{minibuffer.t @key{RET}}.}
1277 @result{} "minibuffer.texi"
1282 @defopt read-buffer-function
1283 This variable, if non-@code{nil}, specifies a function for reading
1284 buffer names. @code{read-buffer} calls this function instead of doing
1285 its usual work, with the same arguments passed to @code{read-buffer}.
1288 @defopt read-buffer-completion-ignore-case
1289 If this variable is non-@code{nil}, @code{read-buffer} ignores case
1290 when performing completion.
1293 @defun read-command prompt &optional default
1294 This function reads the name of a command and returns it as a Lisp
1295 symbol. The argument @var{prompt} is used as in
1296 @code{read-from-minibuffer}. Recall that a command is anything for
1297 which @code{commandp} returns @code{t}, and a command name is a symbol
1298 for which @code{commandp} returns @code{t}. @xref{Interactive Call}.
1300 The argument @var{default} specifies what to return if the user enters
1301 null input. It can be a symbol, a string or a list of strings. If it
1302 is a string, @code{read-command} interns it before returning it.
1303 If it is a list, @code{read-command} interns the first element of this list.
1304 If @var{default} is @code{nil}, that means no default has been
1305 specified; then if the user enters null input, the return value is
1306 @code{(intern "")}, that is, a symbol whose name is an empty string.
1309 (read-command "Command name? ")
1312 ;; @r{After evaluation of the preceding expression,}
1313 ;; @r{the following prompt appears with an empty minibuffer:}
1317 ---------- Buffer: Minibuffer ----------
1319 ---------- Buffer: Minibuffer ----------
1324 If the user types @kbd{forward-c @key{RET}}, then this function returns
1325 @code{forward-char}.
1327 The @code{read-command} function is a simplified interface to
1328 @code{completing-read}. It uses the variable @code{obarray} so as to
1329 complete in the set of extant Lisp symbols, and it uses the
1330 @code{commandp} predicate so as to accept only command names:
1332 @cindex @code{commandp} example
1335 (read-command @var{prompt})
1337 (intern (completing-read @var{prompt} obarray
1343 @defun read-variable prompt &optional default
1344 @anchor{Definition of read-variable}
1345 This function reads the name of a customizable variable and returns it
1346 as a symbol. Its arguments have the same form as those of
1347 @code{read-command}. It behaves just like @code{read-command}, except
1348 that it uses the predicate @code{custom-variable-p} instead of
1352 @deffn Command read-color &optional prompt convert allow-empty display
1353 This function reads a string that is a color specification, either the
1354 color's name or an RGB hex value such as @code{#RRRGGGBBB}. It
1355 prompts with @var{prompt} (default: @code{"Color (name or #RGB triplet):"})
1356 and provides completion for color names, but not for hex RGB values.
1357 In addition to names of standard colors, completion candidates include
1358 the foreground and background colors at point.
1360 Valid RGB values are described in @ref{Color Names}.
1362 The function's return value is the string typed by the user in the
1363 minibuffer. However, when called interactively or if the optional
1364 argument @var{convert} is non-@code{nil}, it converts any input color
1365 name into the corresponding RGB value string and instead returns that.
1366 This function requires a valid color specification to be input.
1367 Empty color names are allowed when @var{allow-empty} is
1368 non-@code{nil} and the user enters null input.
1370 Interactively, or when @var{display} is non-@code{nil}, the return
1371 value is also displayed in the echo area.
1374 See also the functions @code{read-coding-system} and
1375 @code{read-non-nil-coding-system}, in @ref{User-Chosen Coding Systems},
1376 and @code{read-input-method-name}, in @ref{Input Methods}.
1378 @node Reading File Names
1379 @subsection Reading File Names
1380 @cindex read file names
1381 @cindex prompt for file name
1383 The high-level completion functions @code{read-file-name},
1384 @code{read-directory-name}, and @code{read-shell-command} are designed
1385 to read file names, directory names, and shell commands, respectively.
1386 They provide special features, including automatic insertion of the
1389 @defun read-file-name prompt &optional directory default require-match initial predicate
1390 This function reads a file name, prompting with @var{prompt} and
1391 providing completion.
1393 As an exception, this function reads a file name using a graphical
1394 file dialog instead of the minibuffer, if all of the following are
1399 It is invoked via a mouse command.
1402 The selected frame is on a graphical display supporting such dialogs.
1405 The variable @code{use-dialog-box} is non-@code{nil}.
1406 @xref{Dialog Boxes,, Dialog Boxes, emacs, The GNU Emacs Manual}.
1409 The @var{directory} argument, described below, does not specify a
1410 remote file. @xref{Remote Files,, Remote Files, emacs, The GNU Emacs Manual}.
1414 The exact behavior when using a graphical file dialog is
1415 platform-dependent. Here, we simply document the behavior when using
1418 @code{read-file-name} does not automatically expand the returned file
1419 name. You must call @code{expand-file-name} yourself if an absolute
1420 file name is required.
1422 The optional argument @var{require-match} has the same meaning as in
1423 @code{completing-read}. @xref{Minibuffer Completion}.
1425 The argument @var{directory} specifies the directory to use for
1426 completing relative file names. It should be an absolute directory
1427 name. If the variable @code{insert-default-directory} is non-@code{nil},
1428 @var{directory} is also inserted in the minibuffer as initial input.
1429 It defaults to the current buffer's value of @code{default-directory}.
1431 If you specify @var{initial}, that is an initial file name to insert
1432 in the buffer (after @var{directory}, if that is inserted). In this
1433 case, point goes at the beginning of @var{initial}. The default for
1434 @var{initial} is @code{nil}---don't insert any file name. To see what
1435 @var{initial} does, try the command @kbd{C-x C-v} in a buffer visiting
1436 a file. @strong{Please note:} we recommend using @var{default} rather
1437 than @var{initial} in most cases.
1439 If @var{default} is non-@code{nil}, then the function returns
1440 @var{default} if the user exits the minibuffer with the same non-empty
1441 contents that @code{read-file-name} inserted initially. The initial
1442 minibuffer contents are always non-empty if
1443 @code{insert-default-directory} is non-@code{nil}, as it is by
1444 default. @var{default} is not checked for validity, regardless of the
1445 value of @var{require-match}. However, if @var{require-match} is
1446 non-@code{nil}, the initial minibuffer contents should be a valid file
1447 (or directory) name. Otherwise @code{read-file-name} attempts
1448 completion if the user exits without any editing, and does not return
1449 @var{default}. @var{default} is also available through the history
1452 If @var{default} is @code{nil}, @code{read-file-name} tries to find a
1453 substitute default to use in its place, which it treats in exactly the
1454 same way as if it had been specified explicitly. If @var{default} is
1455 @code{nil}, but @var{initial} is non-@code{nil}, then the default is
1456 the absolute file name obtained from @var{directory} and
1457 @var{initial}. If both @var{default} and @var{initial} are @code{nil}
1458 and the buffer is visiting a file, @code{read-file-name} uses the
1459 absolute file name of that file as default. If the buffer is not
1460 visiting a file, then there is no default. In that case, if the user
1461 types @key{RET} without any editing, @code{read-file-name} simply
1462 returns the pre-inserted contents of the minibuffer.
1464 If the user types @key{RET} in an empty minibuffer, this function
1465 returns an empty string, regardless of the value of
1466 @var{require-match}. This is, for instance, how the user can make the
1467 current buffer visit no file using @kbd{M-x set-visited-file-name}.
1469 If @var{predicate} is non-@code{nil}, it specifies a function of one
1470 argument that decides which file names are acceptable completion
1471 alternatives. A file name is an acceptable value if @var{predicate}
1472 returns non-@code{nil} for it.
1474 Here is an example of using @code{read-file-name}:
1478 (read-file-name "The file is ")
1480 ;; @r{After evaluation of the preceding expression,}
1481 ;; @r{the following appears in the minibuffer:}
1485 ---------- Buffer: Minibuffer ----------
1486 The file is /gp/gnu/elisp/@point{}
1487 ---------- Buffer: Minibuffer ----------
1492 Typing @kbd{manual @key{TAB}} results in the following:
1496 ---------- Buffer: Minibuffer ----------
1497 The file is /gp/gnu/elisp/manual.texi@point{}
1498 ---------- Buffer: Minibuffer ----------
1502 @c Wordy to avoid overfull hbox in smallbook mode.
1504 If the user types @key{RET}, @code{read-file-name} returns the file name
1505 as the string @code{"/gp/gnu/elisp/manual.texi"}.
1508 @defvar read-file-name-function
1509 If non-@code{nil}, this should be a function that accepts the same
1510 arguments as @code{read-file-name}. When @code{read-file-name} is
1511 called, it calls this function with the supplied arguments instead of
1512 doing its usual work.
1515 @defopt read-file-name-completion-ignore-case
1516 If this variable is non-@code{nil}, @code{read-file-name} ignores case
1517 when performing completion.
1520 @defun read-directory-name prompt &optional directory default require-match initial
1521 This function is like @code{read-file-name} but allows only directory
1522 names as completion alternatives.
1524 If @var{default} is @code{nil} and @var{initial} is non-@code{nil},
1525 @code{read-directory-name} constructs a substitute default by
1526 combining @var{directory} (or the current buffer's default directory
1527 if @var{directory} is @code{nil}) and @var{initial}. If both
1528 @var{default} and @var{initial} are @code{nil}, this function uses
1529 @var{directory} as substitute default, or the current buffer's default
1530 directory if @var{directory} is @code{nil}.
1533 @defopt insert-default-directory
1534 This variable is used by @code{read-file-name}, and thus, indirectly,
1535 by most commands reading file names. (This includes all commands that
1536 use the code letters @samp{f} or @samp{F} in their interactive form.
1537 @xref{Interactive Codes,, Code Characters for interactive}.) Its
1538 value controls whether @code{read-file-name} starts by placing the
1539 name of the default directory in the minibuffer, plus the initial file
1540 name, if any. If the value of this variable is @code{nil}, then
1541 @code{read-file-name} does not place any initial input in the
1542 minibuffer (unless you specify initial input with the @var{initial}
1543 argument). In that case, the default directory is still used for
1544 completion of relative file names, but is not displayed.
1546 If this variable is @code{nil} and the initial minibuffer contents are
1547 empty, the user may have to explicitly fetch the next history element
1548 to access a default value. If the variable is non-@code{nil}, the
1549 initial minibuffer contents are always non-empty and the user can
1550 always request a default value by immediately typing @key{RET} in an
1551 unedited minibuffer. (See above.)
1557 ;; @r{Here the minibuffer starts out with the default directory.}
1558 (let ((insert-default-directory t))
1559 (read-file-name "The file is "))
1563 ---------- Buffer: Minibuffer ----------
1564 The file is ~lewis/manual/@point{}
1565 ---------- Buffer: Minibuffer ----------
1569 ;; @r{Here the minibuffer is empty and only the prompt}
1570 ;; @r{appears on its line.}
1571 (let ((insert-default-directory nil))
1572 (read-file-name "The file is "))
1576 ---------- Buffer: Minibuffer ----------
1577 The file is @point{}
1578 ---------- Buffer: Minibuffer ----------
1583 @defun read-shell-command prompt &optional initial history &rest args
1584 This function reads a shell command from the minibuffer, prompting
1585 with @var{prompt} and providing intelligent completion. It completes
1586 the first word of the command using candidates that are appropriate
1587 for command names, and the rest of the command words as file names.
1589 This function uses @code{minibuffer-local-shell-command-map} as the
1590 keymap for minibuffer input. The @var{history} argument specifies the
1591 history list to use; if is omitted or @code{nil}, it defaults to
1592 @code{shell-command-history} (@pxref{Minibuffer History,
1593 shell-command-history}). The optional argument @var{initial}
1594 specifies the initial content of the minibuffer (@pxref{Initial
1595 Input}). The rest of @var{args}, if present, are used as the
1596 @var{default} and @var{inherit-input-method} arguments in
1597 @code{read-from-minibuffer} (@pxref{Text from Minibuffer}).
1600 @defvar minibuffer-local-shell-command-map
1601 This keymap is used by @code{read-shell-command} for completing
1602 command and file names that are part of a shell command. It uses
1603 @code{minibuffer-local-map} as its parent keymap, and binds @key{TAB}
1604 to @code{completion-at-point}.
1607 @node Completion Variables
1608 @subsection Completion Variables
1610 Here are some variables that can be used to alter the default
1611 completion behavior.
1613 @cindex completion styles
1614 @defopt completion-styles
1615 The value of this variable is a list of completion style (symbols) to
1616 use for performing completion. A @dfn{completion style} is a set of
1617 rules for generating completions. Each symbol occurring this list
1618 must have a corresponding entry in @code{completion-styles-alist}.
1621 @defvar completion-styles-alist
1622 This variable stores a list of available completion styles. Each
1623 element in the list has the form
1626 (@var{style} @var{try-completion} @var{all-completions} @var{doc})
1630 Here, @var{style} is the name of the completion style (a symbol),
1631 which may be used in the @code{completion-styles} variable to refer to
1632 this style; @var{try-completion} is the function that does the
1633 completion; @var{all-completions} is the function that lists the
1634 completions; and @var{doc} is a string describing the completion
1637 The @var{try-completion} and @var{all-completions} functions should
1638 each accept four arguments: @var{string}, @var{collection},
1639 @var{predicate}, and @var{point}. The @var{string}, @var{collection},
1640 and @var{predicate} arguments have the same meanings as in
1641 @code{try-completion} (@pxref{Basic Completion}), and the @var{point}
1642 argument is the position of point within @var{string}. Each function
1643 should return a non-@code{nil} value if it performed its job, and
1644 @code{nil} if it did not (e.g., if there is no way to complete
1645 @var{string} according to the completion style).
1647 When the user calls a completion command like
1648 @code{minibuffer-complete} (@pxref{Completion Commands}), Emacs looks
1649 for the first style listed in @code{completion-styles} and calls its
1650 @var{try-completion} function. If this function returns @code{nil},
1651 Emacs moves to the next listed completion style and calls its
1652 @var{try-completion} function, and so on until one of the
1653 @var{try-completion} functions successfully performs completion and
1654 returns a non-@code{nil} value. A similar procedure is used for
1655 listing completions, via the @var{all-completions} functions.
1657 @xref{Completion Styles,,, emacs, The GNU Emacs Manual}, for a
1658 description of the available completion styles.
1661 @defopt completion-category-overrides
1662 This variable specifies special completion styles and other completion
1663 behaviors to use when completing certain types of text. Its value
1664 should be an alist with elements of the form @code{(@var{category}
1665 . @var{alist})}. @var{category} is a symbol describing what is being
1666 completed; currently, the @code{buffer}, @code{file}, and
1667 @code{unicode-name} categories are defined, but others can be defined
1668 via specialized completion functions (@pxref{Programmed Completion}).
1669 @var{alist} is an association list describing how completion should
1670 behave for the corresponding category. The following alist keys are
1675 The value should be a list of completion styles (symbols).
1678 The value should be a value for @code{completion-cycle-threshold}
1679 (@pxref{Completion Options,,, emacs, The GNU Emacs Manual}) for this
1684 Additional alist entries may be defined in the future.
1687 @defvar completion-extra-properties
1688 This variable is used to specify extra properties of the current
1689 completion command. It is intended to be let-bound by specialized
1690 completion commands. Its value should be a list of property and value
1691 pairs. The following properties are supported:
1694 @item :annotation-function
1695 The value should be a function to add annotations in the completions
1696 buffer. This function must accept one argument, a completion, and
1697 should either return @code{nil} or a string to be displayed next to
1700 @item :exit-function
1701 The value should be a function to run after performing completion.
1702 The function should accept two arguments, @var{string} and
1703 @var{status}, where @var{string} is the text to which the field was
1704 completed, and @var{status} indicates what kind of operation happened:
1705 @code{finished} if text is now complete, @code{sole} if the text
1706 cannot be further completed but completion is not finished, or
1707 @code{exact} if the text is a valid completion but may be further
1712 @node Programmed Completion
1713 @subsection Programmed Completion
1714 @cindex programmed completion
1716 Sometimes it is not possible or convenient to create an alist or
1717 an obarray containing all the intended possible completions ahead
1718 of time. In such a case, you can supply your own function to compute
1719 the completion of a given string. This is called @dfn{programmed
1720 completion}. Emacs uses programmed completion when completing file
1721 names (@pxref{File Name Completion}), among many other cases.
1723 To use this feature, pass a function as the @var{collection}
1724 argument to @code{completing-read}. The function
1725 @code{completing-read} arranges to pass your completion function along
1726 to @code{try-completion}, @code{all-completions}, and other basic
1727 completion functions, which will then let your function do all
1730 The completion function should accept three arguments:
1734 The string to be completed.
1737 A predicate function with which to filter possible matches, or
1738 @code{nil} if none. The function should call the predicate for each
1739 possible match, and ignore the match if the predicate returns
1743 A flag specifying the type of completion operation to perform. This
1744 flag may be one of the following values.
1748 This specifies a @code{try-completion} operation. The function should
1749 return @code{t} if the specified string is a unique and exact match;
1750 if there is more than one match, it should return the common substring
1751 of all matches (if the string is an exact match for one completion
1752 alternative but also matches other longer alternatives, the return
1753 value is the string); if there are no matches, it should return
1757 This specifies an @code{all-completions} operation. The function
1758 should return a list of all possible completions of the specified
1762 This specifies a @code{test-completion} operation. The function
1763 should return @code{t} if the specified string is an exact match for
1764 some completion alternative; @code{nil} otherwise.
1766 @item (boundaries . @var{suffix})
1767 This specifies a @code{completion-boundaries} operation. The function
1768 should return @code{(boundaries @var{start} . @var{end})}, where
1769 @var{start} is the position of the beginning boundary in the specified
1770 string, and @var{end} is the position of the end boundary in
1774 This specifies a request for information about the state of the
1775 current completion. The return value should have the form
1776 @code{(metadata . @var{alist})}, where @var{alist} is an alist whose
1777 elements are described below.
1781 If the flag has any other value, the completion function should return
1785 The following is a list of metadata entries that a completion function
1786 may return in response to a @code{metadata} flag argument:
1790 The value should be a symbol describing what kind of text the
1791 completion function is trying to complete. If the symbol matches one
1792 of the keys in @code{completion-category-overrides}, the usual
1793 completion behavior is overridden. @xref{Completion Variables}.
1795 @item annotation-function
1796 The value should be a function for @dfn{annotating} completions. The
1797 function should take one argument, @var{string}, which is a possible
1798 completion. It should return a string, which is displayed after the
1799 completion @var{string} in the @file{*Completions*} buffer.
1801 @item display-sort-function
1802 The value should be a function for sorting completions. The function
1803 should take one argument, a list of completion strings, and return a
1804 sorted list of completion strings. It is allowed to alter the input
1807 @item cycle-sort-function
1808 The value should be a function for sorting completions, when
1809 @code{completion-cycle-threshold} is non-@code{nil} and the user is
1810 cycling through completion alternatives. @xref{Completion Options,,,
1811 emacs, The GNU Emacs Manual}. Its argument list and return value are
1812 the same as for @code{display-sort-function}.
1815 @defun completion-table-dynamic function
1816 This function is a convenient way to write a function that can act as
1817 a programmed completion function. The argument @var{function} should be
1818 a function that takes one argument, a string, and returns an alist of
1819 possible completions of it. You can think of
1820 @code{completion-table-dynamic} as a transducer between that interface
1821 and the interface for programmed completion functions.
1824 @defun completion-table-with-cache function &optional ignore-case
1825 This is a wrapper for @code{completion-table-dynamic} that saves the
1826 last argument-result pair. This means that multiple lookups with the
1827 same argument only need to call @var{function} once. This can be useful
1828 when a slow operation is involved, such as calling an external process.
1831 @node Completion in Buffers
1832 @subsection Completion in Ordinary Buffers
1833 @cindex inline completion
1835 @findex completion-at-point
1836 Although completion is usually done in the minibuffer, the
1837 completion facility can also be used on the text in ordinary Emacs
1838 buffers. In many major modes, in-buffer completion is performed by
1839 the @kbd{C-M-i} or @kbd{M-@key{TAB}} command, bound to
1840 @code{completion-at-point}. @xref{Symbol Completion,,, emacs, The GNU
1841 Emacs Manual}. This command uses the abnormal hook variable
1842 @code{completion-at-point-functions}:
1844 @defvar completion-at-point-functions
1845 The value of this abnormal hook should be a list of functions, which
1846 are used to compute a completion table for completing the text at
1847 point. It can be used by major modes to provide mode-specific
1848 completion tables (@pxref{Major Mode Conventions}).
1850 When the command @code{completion-at-point} runs, it calls the
1851 functions in the list one by one, without any argument. Each function
1852 should return @code{nil} if it is unable to produce a completion table
1853 for the text at point. Otherwise it should return a list of the form
1856 (@var{start} @var{end} @var{collection} . @var{props})
1860 @var{start} and @var{end} delimit the text to complete (which should
1861 enclose point). @var{collection} is a completion table for completing
1862 that text, in a form suitable for passing as the second argument to
1863 @code{try-completion} (@pxref{Basic Completion}); completion
1864 alternatives will be generated from this completion table in the usual
1865 way, via the completion styles defined in @code{completion-styles}
1866 (@pxref{Completion Variables}). @var{props} is a property list for
1867 additional information; any of the properties in
1868 @code{completion-extra-properties} are recognized (@pxref{Completion
1869 Variables}), as well as the following additional ones:
1873 The value should be a predicate that completion candidates need to
1877 If the value is @code{no}, then if the completion table fails to match
1878 the text at point, @code{completion-at-point} moves on to the
1879 next function in @code{completion-at-point-functions} instead of
1880 reporting a completion failure.
1883 Supplying a function for @var{collection} is strongly recommended if
1884 generating the list of completions is an expensive operation. Emacs
1885 may internally call functions in @code{completion-at-point-functions}
1886 many times, but care about the value of @var{collection} for only some
1887 of these calls. By supplying a function for @var{collection}, Emacs
1888 can defer generating completions until necessary. You can use
1889 @var{completion-table-dynamic} to create a wrapper function:
1892 ;; Avoid this pattern.
1893 (let ((beg ...) (end ...) (my-completions (my-make-completions)))
1894 (list beg end my-completions))
1896 ;; Use this instead.
1897 (let ((beg ...) (end ...))
1900 (completion-table-dynamic
1902 (my-make-completions)))))
1905 A function in @code{completion-at-point-functions} may also return a
1906 function instead of a list as described above. In that case, that
1907 returned function is called, with no argument, and it is entirely
1908 responsible for performing the completion. We discourage this usage;
1909 it is intended to help convert old code to using
1910 @code{completion-at-point}.
1912 The first function in @code{completion-at-point-functions} to return a
1913 non-@code{nil} value is used by @code{completion-at-point}. The
1914 remaining functions are not called. The exception to this is when
1915 there is an @code{:exclusive} specification, as described above.
1918 The following function provides a convenient way to perform
1919 completion on an arbitrary stretch of text in an Emacs buffer:
1921 @defun completion-in-region start end collection &optional predicate
1922 This function completes the text in the current buffer between the
1923 positions @var{start} and @var{end}, using @var{collection}. The
1924 argument @var{collection} has the same meaning as in
1925 @code{try-completion} (@pxref{Basic Completion}).
1927 This function inserts the completion text directly into the current
1928 buffer. Unlike @code{completing-read} (@pxref{Minibuffer
1929 Completion}), it does not activate the minibuffer.
1931 For this function to work, point must be somewhere between @var{start}
1936 @node Yes-or-No Queries
1937 @section Yes-or-No Queries
1938 @cindex asking the user questions
1939 @cindex querying the user
1940 @cindex yes-or-no questions
1942 This section describes functions used to ask the user a yes-or-no
1943 question. The function @code{y-or-n-p} can be answered with a single
1944 character; it is useful for questions where an inadvertent wrong answer
1945 will not have serious consequences. @code{yes-or-no-p} is suitable for
1946 more momentous questions, since it requires three or four characters to
1949 If either of these functions is called in a command that was invoked
1950 using the mouse---more precisely, if @code{last-nonmenu-event}
1951 (@pxref{Command Loop Info}) is either @code{nil} or a list---then it
1952 uses a dialog box or pop-up menu to ask the question. Otherwise, it
1953 uses keyboard input. You can force use either of the mouse or of keyboard
1954 input by binding @code{last-nonmenu-event} to a suitable value around
1957 Strictly speaking, @code{yes-or-no-p} uses the minibuffer and
1958 @code{y-or-n-p} does not; but it seems best to describe them together.
1960 @defun y-or-n-p prompt
1961 This function asks the user a question, expecting input in the echo
1962 area. It returns @code{t} if the user types @kbd{y}, @code{nil} if the
1963 user types @kbd{n}. This function also accepts @key{SPC} to mean yes
1964 and @key{DEL} to mean no. It accepts @kbd{C-]} to quit, like
1965 @kbd{C-g}, because the question might look like a minibuffer and for
1966 that reason the user might try to use @kbd{C-]} to get out. The answer
1967 is a single character, with no @key{RET} needed to terminate it. Upper
1968 and lower case are equivalent.
1970 ``Asking the question'' means printing @var{prompt} in the echo area,
1971 followed by the string @w{@samp{(y or n) }}. If the input is not one of
1972 the expected answers (@kbd{y}, @kbd{n}, @kbd{@key{SPC}},
1973 @kbd{@key{DEL}}, or something that quits), the function responds
1974 @samp{Please answer y or n.}, and repeats the request.
1976 This function does not actually use the minibuffer, since it does not
1977 allow editing of the answer. It actually uses the echo area (@pxref{The
1978 Echo Area}), which uses the same screen space as the minibuffer. The
1979 cursor moves to the echo area while the question is being asked.
1981 The answers and their meanings, even @samp{y} and @samp{n}, are not
1982 hardwired, and are specified by the keymap @code{query-replace-map}
1983 (@pxref{Search and Replace}). In particular, if the user enters the
1984 special responses @code{recenter}, @code{scroll-up},
1985 @code{scroll-down}, @code{scroll-other-window}, or
1986 @code{scroll-other-window-down} (respectively bound to @kbd{C-l},
1987 @kbd{C-v}, @kbd{M-v}, @kbd{C-M-v} and @kbd{C-M-S-v} in
1988 @code{query-replace-map}), this function performs the specified window
1989 recentering or scrolling operation, and poses the question again.
1992 We show successive lines of echo area messages, but only one actually
1993 appears on the screen at a time.
1996 @defun y-or-n-p-with-timeout prompt seconds default
1997 Like @code{y-or-n-p}, except that if the user fails to answer within
1998 @var{seconds} seconds, this function stops waiting and returns
1999 @var{default}. It works by setting up a timer; see @ref{Timers}.
2000 The argument @var{seconds} should be a number.
2003 @defun yes-or-no-p prompt
2004 This function asks the user a question, expecting input in the
2005 minibuffer. It returns @code{t} if the user enters @samp{yes},
2006 @code{nil} if the user types @samp{no}. The user must type @key{RET} to
2007 finalize the response. Upper and lower case are equivalent.
2009 @code{yes-or-no-p} starts by displaying @var{prompt} in the echo area,
2010 followed by @w{@samp{(yes or no) }}. The user must type one of the
2011 expected responses; otherwise, the function responds @samp{Please answer
2012 yes or no.}, waits about two seconds and repeats the request.
2014 @code{yes-or-no-p} requires more work from the user than
2015 @code{y-or-n-p} and is appropriate for more crucial decisions.
2021 (yes-or-no-p "Do you really want to remove everything? ")
2023 ;; @r{After evaluation of the preceding expression,}
2024 ;; @r{the following prompt appears,}
2025 ;; @r{with an empty minibuffer:}
2029 ---------- Buffer: minibuffer ----------
2030 Do you really want to remove everything? (yes or no)
2031 ---------- Buffer: minibuffer ----------
2036 If the user first types @kbd{y @key{RET}}, which is invalid because this
2037 function demands the entire word @samp{yes}, it responds by displaying
2038 these prompts, with a brief pause between them:
2042 ---------- Buffer: minibuffer ----------
2043 Please answer yes or no.
2044 Do you really want to remove everything? (yes or no)
2045 ---------- Buffer: minibuffer ----------
2050 @node Multiple Queries
2051 @section Asking Multiple Y-or-N Questions
2052 @cindex multiple yes-or-no questions
2054 When you have a series of similar questions to ask, such as ``Do you
2055 want to save this buffer?'' for each buffer in turn, you should use
2056 @code{map-y-or-n-p} to ask the collection of questions, rather than
2057 asking each question individually. This gives the user certain
2058 convenient facilities such as the ability to answer the whole series at
2061 @defun map-y-or-n-p prompter actor list &optional help action-alist no-cursor-in-echo-area
2062 This function asks the user a series of questions, reading a
2063 single-character answer in the echo area for each one.
2065 The value of @var{list} specifies the objects to ask questions about.
2066 It should be either a list of objects or a generator function. If it is
2067 a function, it should expect no arguments, and should return either the
2068 next object to ask about, or @code{nil}, meaning to stop asking questions.
2070 The argument @var{prompter} specifies how to ask each question. If
2071 @var{prompter} is a string, the question text is computed like this:
2074 (format @var{prompter} @var{object})
2078 where @var{object} is the next object to ask about (as obtained from
2081 If not a string, @var{prompter} should be a function of one argument
2082 (the next object to ask about) and should return the question text. If
2083 the value is a string, that is the question to ask the user. The
2084 function can also return @code{t}, meaning do act on this object (and
2085 don't ask the user), or @code{nil}, meaning ignore this object (and don't
2088 The argument @var{actor} says how to act on the answers that the user
2089 gives. It should be a function of one argument, and it is called with
2090 each object that the user says yes for. Its argument is always an
2091 object obtained from @var{list}.
2093 If the argument @var{help} is given, it should be a list of this form:
2096 (@var{singular} @var{plural} @var{action})
2100 where @var{singular} is a string containing a singular noun that
2101 describes the objects conceptually being acted on, @var{plural} is the
2102 corresponding plural noun, and @var{action} is a transitive verb
2103 describing what @var{actor} does.
2105 If you don't specify @var{help}, the default is @code{("object"
2106 "objects" "act on")}.
2108 Each time a question is asked, the user may enter @kbd{y}, @kbd{Y}, or
2109 @key{SPC} to act on that object; @kbd{n}, @kbd{N}, or @key{DEL} to skip
2110 that object; @kbd{!} to act on all following objects; @key{ESC} or
2111 @kbd{q} to exit (skip all following objects); @kbd{.} (period) to act on
2112 the current object and then exit; or @kbd{C-h} to get help. These are
2113 the same answers that @code{query-replace} accepts. The keymap
2114 @code{query-replace-map} defines their meaning for @code{map-y-or-n-p}
2115 as well as for @code{query-replace}; see @ref{Search and Replace}.
2117 You can use @var{action-alist} to specify additional possible answers
2118 and what they mean. It is an alist of elements of the form
2119 @code{(@var{char} @var{function} @var{help})}, each of which defines one
2120 additional answer. In this element, @var{char} is a character (the
2121 answer); @var{function} is a function of one argument (an object from
2122 @var{list}); @var{help} is a string.
2124 When the user responds with @var{char}, @code{map-y-or-n-p} calls
2125 @var{function}. If it returns non-@code{nil}, the object is considered
2126 acted upon, and @code{map-y-or-n-p} advances to the next object in
2127 @var{list}. If it returns @code{nil}, the prompt is repeated for the
2130 Normally, @code{map-y-or-n-p} binds @code{cursor-in-echo-area} while
2131 prompting. But if @var{no-cursor-in-echo-area} is non-@code{nil}, it
2134 If @code{map-y-or-n-p} is called in a command that was invoked using the
2135 mouse---more precisely, if @code{last-nonmenu-event} (@pxref{Command
2136 Loop Info}) is either @code{nil} or a list---then it uses a dialog box
2137 or pop-up menu to ask the question. In this case, it does not use
2138 keyboard input or the echo area. You can force use either of the mouse or
2139 of keyboard input by binding @code{last-nonmenu-event} to a suitable
2140 value around the call.
2142 The return value of @code{map-y-or-n-p} is the number of objects acted on.
2144 @c FIXME An example of this would be more useful than all the
2145 @c preceding examples of simple things.
2147 @node Reading a Password
2148 @section Reading a Password
2149 @cindex passwords, reading
2151 To read a password to pass to another program, you can use the
2152 function @code{read-passwd}.
2154 @defun read-passwd prompt &optional confirm default
2155 This function reads a password, prompting with @var{prompt}. It does
2156 not echo the password as the user types it; instead, it echoes
2157 @samp{.} for each character in the password. If you want to apply
2158 another character to hide the password, let-bind the variable
2159 @code{read-hide-char} with that character.
2161 The optional argument @var{confirm}, if non-@code{nil}, says to read the
2162 password twice and insist it must be the same both times. If it isn't
2163 the same, the user has to type it over and over until the last two
2166 The optional argument @var{default} specifies the default password to
2167 return if the user enters empty input. If @var{default} is @code{nil},
2168 then @code{read-passwd} returns the null string in that case.
2171 @node Minibuffer Commands
2172 @section Minibuffer Commands
2174 This section describes some commands meant for use in the
2177 @deffn Command exit-minibuffer
2178 This command exits the active minibuffer. It is normally bound to
2179 keys in minibuffer local keymaps.
2182 @deffn Command self-insert-and-exit
2183 This command exits the active minibuffer after inserting the last
2184 character typed on the keyboard (found in @code{last-command-event};
2185 @pxref{Command Loop Info}).
2188 @deffn Command previous-history-element n
2189 This command replaces the minibuffer contents with the value of the
2190 @var{n}th previous (older) history element.
2193 @deffn Command next-history-element n
2194 This command replaces the minibuffer contents with the value of the
2195 @var{n}th more recent history element.
2198 @deffn Command previous-matching-history-element pattern n
2199 This command replaces the minibuffer contents with the value of the
2200 @var{n}th previous (older) history element that matches @var{pattern} (a
2201 regular expression).
2204 @deffn Command next-matching-history-element pattern n
2205 This command replaces the minibuffer contents with the value of the
2206 @var{n}th next (newer) history element that matches @var{pattern} (a
2207 regular expression).
2210 @deffn Command previous-complete-history-element n
2211 This command replaces the minibuffer contents with the value of the
2212 @var{n}th previous (older) history element that completes the current
2213 contents of the minibuffer before the point.
2216 @deffn Command next-complete-history-element n
2217 This command replaces the minibuffer contents with the value of the
2218 @var{n}th next (newer) history element that completes the current
2219 contents of the minibuffer before the point.
2223 @node Minibuffer Windows
2224 @section Minibuffer Windows
2225 @cindex minibuffer windows
2227 These functions access and select minibuffer windows, test whether they
2228 are active and control how they get resized.
2230 @defun active-minibuffer-window
2231 This function returns the currently active minibuffer window, or
2232 @code{nil} if there is none.
2235 @defun minibuffer-window &optional frame
2236 @anchor{Definition of minibuffer-window}
2237 This function returns the minibuffer window used for frame @var{frame}.
2238 If @var{frame} is @code{nil}, that stands for the current frame. Note
2239 that the minibuffer window used by a frame need not be part of that
2240 frame---a frame that has no minibuffer of its own necessarily uses some
2241 other frame's minibuffer window.
2244 @defun set-minibuffer-window window
2245 This function specifies @var{window} as the minibuffer window to use.
2246 This affects where the minibuffer is displayed if you put text in it
2247 without invoking the usual minibuffer commands. It has no effect on
2248 the usual minibuffer input functions because they all start by
2249 choosing the minibuffer window according to the current frame.
2253 @defun window-minibuffer-p &optional window
2254 This function returns non-@code{nil} if @var{window} is a minibuffer
2256 @var{window} defaults to the selected window.
2259 It is not correct to determine whether a given window is a minibuffer by
2260 comparing it with the result of @code{(minibuffer-window)}, because
2261 there can be more than one minibuffer window if there is more than one
2264 @defun minibuffer-window-active-p window
2265 This function returns non-@code{nil} if @var{window} is the currently
2266 active minibuffer window.
2269 The following two options control whether minibuffer windows are resized
2270 automatically and how large they can get in the process.
2272 @defopt resize-mini-windows
2273 This option specifies whether minibuffer windows are resized
2274 automatically. The default value is @code{grow-only}, which means that
2275 a minibuffer window by default expands automatically to accommodate the
2276 text it displays and shrinks back to one line as soon as the minibuffer
2277 gets empty. If the value is @code{t}, Emacs will always try to fit the
2278 height of a minibuffer window to the text it displays (with a minimum of
2279 one line). If the value is @code{nil}, a minibuffer window never
2280 changes size automatically. In that case the window resizing commands
2281 (@pxref{Resizing Windows}) can be used to adjust its height.
2284 @defopt max-mini-window-height
2285 This option provides a maximum height for resizing minibuffer windows
2286 automatically. A floating-point number specifies a fraction of the
2287 frame's height; an integer specifies the maximum number of lines. The
2288 default value is 0.25.
2292 @node Minibuffer Contents
2293 @section Minibuffer Contents
2294 @cindex access minibuffer contents
2295 @cindex minibuffer contents, accessing
2297 These functions access the minibuffer prompt and contents.
2299 @defun minibuffer-prompt
2300 This function returns the prompt string of the currently active
2301 minibuffer. If no minibuffer is active, it returns @code{nil}.
2304 @defun minibuffer-prompt-end
2305 This function returns the current
2306 position of the end of the minibuffer prompt, if a minibuffer is
2307 current. Otherwise, it returns the minimum valid buffer position.
2310 @defun minibuffer-prompt-width
2311 This function returns the current display-width of the minibuffer
2312 prompt, if a minibuffer is current. Otherwise, it returns zero.
2315 @defun minibuffer-contents
2316 This function returns the editable
2317 contents of the minibuffer (that is, everything except the prompt) as
2318 a string, if a minibuffer is current. Otherwise, it returns the
2319 entire contents of the current buffer.
2322 @defun minibuffer-contents-no-properties
2323 This is like @code{minibuffer-contents}, except that it does not copy text
2324 properties, just the characters themselves. @xref{Text Properties}.
2327 @defun delete-minibuffer-contents
2328 This function erases the editable contents of the minibuffer (that is,
2329 everything except the prompt), if a minibuffer is current. Otherwise,
2330 it erases the entire current buffer.
2333 @node Recursive Mini
2334 @section Recursive Minibuffers
2335 @cindex recursive minibuffers
2337 These functions and variables deal with recursive minibuffers
2338 (@pxref{Recursive Editing}):
2340 @defun minibuffer-depth
2341 This function returns the current depth of activations of the
2342 minibuffer, a nonnegative integer. If no minibuffers are active, it
2346 @defopt enable-recursive-minibuffers
2347 If this variable is non-@code{nil}, you can invoke commands (such as
2348 @code{find-file}) that use minibuffers even while the minibuffer window
2349 is active. Such invocation produces a recursive editing level for a new
2350 minibuffer. The outer-level minibuffer is invisible while you are
2351 editing the inner one.
2353 If this variable is @code{nil}, you cannot invoke minibuffer
2354 commands when the minibuffer window is active, not even if you switch to
2355 another window to do it.
2359 If a command name has a property @code{enable-recursive-minibuffers}
2360 that is non-@code{nil}, then the command can use the minibuffer to read
2361 arguments even if it is invoked from the minibuffer. A command can
2362 also achieve this by binding @code{enable-recursive-minibuffers}
2363 to @code{t} in the interactive declaration (@pxref{Using Interactive}).
2364 The minibuffer command @code{next-matching-history-element} (normally
2365 @kbd{M-s} in the minibuffer) does the latter.
2367 @node Minibuffer Misc
2368 @section Minibuffer Miscellany
2370 @defun minibufferp &optional buffer-or-name
2371 This function returns non-@code{nil} if @var{buffer-or-name} is a
2372 minibuffer. If @var{buffer-or-name} is omitted, it tests the current
2376 @defvar minibuffer-setup-hook
2377 This is a normal hook that is run whenever the minibuffer is entered.
2381 @defvar minibuffer-exit-hook
2382 This is a normal hook that is run whenever the minibuffer is exited.
2386 @defvar minibuffer-help-form
2387 @anchor{Definition of minibuffer-help-form}
2388 The current value of this variable is used to rebind @code{help-form}
2389 locally inside the minibuffer (@pxref{Help Functions}).
2392 @defvar minibuffer-scroll-window
2393 @anchor{Definition of minibuffer-scroll-window}
2394 If the value of this variable is non-@code{nil}, it should be a window
2395 object. When the function @code{scroll-other-window} is called in the
2396 minibuffer, it scrolls this window.
2399 @defun minibuffer-selected-window
2400 This function returns the window that was selected when the
2401 minibuffer was entered. If selected window is not a minibuffer
2402 window, it returns @code{nil}.
2405 @defopt max-mini-window-height
2406 This variable specifies the maximum height for resizing minibuffer
2407 windows. If a float, it specifies a fraction of the height of the
2408 frame. If an integer, it specifies a number of lines.
2411 @vindex minibuffer-message-timeout
2412 @defun minibuffer-message string &rest args
2413 This function displays @var{string} temporarily at the end of the
2414 minibuffer text, for a few seconds, or until the next input event
2415 arrives, whichever comes first. The variable
2416 @code{minibuffer-message-timeout} specifies the number of seconds to
2417 wait in the absence of input. It defaults to 2. If @var{args} is
2418 non-@code{nil}, the actual message is obtained by passing @var{string}
2419 and @var{args} through @code{format-message}. @xref{Formatting Strings}.
2422 @deffn Command minibuffer-inactive-mode
2423 This is the major mode used in inactive minibuffers. It uses
2424 keymap @code{minibuffer-inactive-mode-map}. This can be useful
2425 if the minibuffer is in a separate frame. @xref{Minibuffers and Frames}.