2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-1999, 2001-2012
4 @c Free Software Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../../info/minibuf
7 @node Minibuffers, Command Loop, Read and Print, Top
9 @cindex arguments, reading
10 @cindex complex arguments
13 A @dfn{minibuffer} is a special buffer that Emacs commands use to
14 read arguments more complicated than the single numeric prefix
15 argument. These arguments include file names, buffer names, and
16 command names (as in @kbd{M-x}). The minibuffer is displayed on the
17 bottom line of the frame, in the same place as the echo area
18 (@pxref{The Echo Area}), but only while it is in use for reading an
22 * Intro to Minibuffers:: Basic information about minibuffers.
23 * Text from Minibuffer:: How to read a straight text string.
24 * Object from Minibuffer:: How to read a Lisp object or expression.
25 * Minibuffer History:: Recording previous minibuffer inputs
26 so the user can reuse them.
27 * Initial Input:: Specifying initial contents for the minibuffer.
28 * Completion:: How to invoke and customize completion.
29 * Yes-or-No Queries:: Asking a question with a simple answer.
30 * Multiple Queries:: Asking a series of similar questions.
31 * Reading a Password:: Reading a password from the terminal.
32 * Minibuffer Commands:: Commands used as key bindings in minibuffers.
33 * Minibuffer Windows:: Operating on the special minibuffer windows.
34 * Minibuffer Contents:: How such commands access the minibuffer text.
35 * Recursive Mini:: Whether recursive entry to minibuffer is allowed.
36 * Minibuffer Misc:: Various customization hooks and variables.
39 @node Intro to Minibuffers
40 @section Introduction to Minibuffers
42 In most ways, a minibuffer is a normal Emacs buffer. Most operations
43 @emph{within} a buffer, such as editing commands, work normally in a
44 minibuffer. However, many operations for managing buffers do not apply
45 to minibuffers. The name of a minibuffer always has the form @w{@samp{
46 *Minibuf-@var{number}*}}, and it cannot be changed. Minibuffers are
47 displayed only in special windows used only for minibuffers; these
48 windows always appear at the bottom of a frame. (Sometimes frames have
49 no minibuffer window, and sometimes a special kind of frame contains
50 nothing but a minibuffer window; see @ref{Minibuffers and Frames}.)
52 The text in the minibuffer always starts with the @dfn{prompt string},
53 the text that was specified by the program that is using the minibuffer
54 to tell the user what sort of input to type. This text is marked
55 read-only so you won't accidentally delete or change it. It is also
56 marked as a field (@pxref{Fields}), so that certain motion functions,
57 including @code{beginning-of-line}, @code{forward-word},
58 @code{forward-sentence}, and @code{forward-paragraph}, stop at the
59 boundary between the prompt and the actual text.
61 @c See http://debbugs.gnu.org/11276
62 The minibuffer's window is normally a single line; it grows
63 automatically if the contents require more space. Whilst it is
64 active, you can explicitly resize it temporarily with the window
65 sizing commands; it reverts to its normal size when the minibuffer is
66 exited. When the minibuffer is not active, you can resize it
67 permanently by using the window sizing commands in the frame's other
68 window, or dragging the mode line with the mouse. (Due to details of
69 the current implementation, for this to work @code{resize-mini-windows}
70 must be @code{nil}.) If the frame contains just a minibuffer, you can
71 change the minibuffer's size by changing the frame's size.
73 Use of the minibuffer reads input events, and that alters the values
74 of variables such as @code{this-command} and @code{last-command}
75 (@pxref{Command Loop Info}). Your program should bind them around the
76 code that uses the minibuffer, if you do not want that to change them.
78 Under some circumstances, a command can use a minibuffer even if
79 there is an active minibuffer; such a minibuffer is called a
80 @dfn{recursive minibuffer}. The first minibuffer is named
81 @w{@samp{ *Minibuf-1*}}. Recursive minibuffers are named by
82 incrementing the number at the end of the name. (The names begin with
83 a space so that they won't show up in normal buffer lists.) Of
84 several recursive minibuffers, the innermost (or most recently
85 entered) is the active minibuffer. We usually call this ``the''
86 minibuffer. You can permit or forbid recursive minibuffers by setting
87 the variable @code{enable-recursive-minibuffers}, or by putting
88 properties of that name on command symbols (@xref{Recursive Mini}.)
90 Like other buffers, a minibuffer uses a local keymap
91 (@pxref{Keymaps}) to specify special key bindings. The function that
92 invokes the minibuffer also sets up its local map according to the job
93 to be done. @xref{Text from Minibuffer}, for the non-completion
94 minibuffer local maps. @xref{Completion Commands}, for the minibuffer
95 local maps for completion.
97 @cindex inactive minibuffer
98 When a minibuffer is inactive, its major mode is
99 @code{minibuffer-inactive-mode}, with keymap
100 @code{minibuffer-inactive-mode-map}. This is only really useful if
101 the minibuffer is in a separate frame. @xref{Minibuffers and Frames}.
103 When Emacs is running in batch mode, any request to read from the
104 minibuffer actually reads a line from the standard input descriptor that
105 was supplied when Emacs was started.
107 @node Text from Minibuffer
108 @section Reading Text Strings with the Minibuffer
110 The most basic primitive for minibuffer input is
111 @code{read-from-minibuffer}, which can be used to read either a string
112 or a Lisp object in textual form. The function @code{read-regexp} is
113 used for reading regular expressions (@pxref{Regular Expressions}),
114 which are a special kind of string. There are also specialized
115 functions for reading commands, variables, file names, etc.@:
116 (@pxref{Completion}).
118 In most cases, you should not call minibuffer input functions in the
119 middle of a Lisp function. Instead, do all minibuffer input as part of
120 reading the arguments for a command, in the @code{interactive}
121 specification. @xref{Defining Commands}.
123 @defun read-from-minibuffer prompt &optional initial keymap read history default inherit-input-method
124 This function is the most general way to get input from the
125 minibuffer. By default, it accepts arbitrary text and returns it as a
126 string; however, if @var{read} is non-@code{nil}, then it uses
127 @code{read} to convert the text into a Lisp object (@pxref{Input
130 The first thing this function does is to activate a minibuffer and
131 display it with @var{prompt} (which must be a string) as the
132 prompt. Then the user can edit text in the minibuffer.
134 When the user types a command to exit the minibuffer,
135 @code{read-from-minibuffer} constructs the return value from the text in
136 the minibuffer. Normally it returns a string containing that text.
137 However, if @var{read} is non-@code{nil}, @code{read-from-minibuffer}
138 reads the text and returns the resulting Lisp object, unevaluated.
139 (@xref{Input Functions}, for information about reading.)
141 The argument @var{default} specifies default values to make available
142 through the history commands. It should be a string, a list of
143 strings, or @code{nil}. The string or strings become the minibuffer's
144 ``future history'', available to the user with @kbd{M-n}.
146 If @var{read} is non-@code{nil}, then @var{default} is also used
147 as the input to @code{read}, if the user enters empty input.
148 If @var{default} is a list of strings, the first string is used as the input.
149 If @var{default} is @code{nil}, empty input results in an @code{end-of-file} error.
150 However, in the usual case (where @var{read} is @code{nil}),
151 @code{read-from-minibuffer} ignores @var{default} when the user enters
152 empty input and returns an empty string, @code{""}. In this respect,
153 it differs from all the other minibuffer input functions in this chapter.
155 If @var{keymap} is non-@code{nil}, that keymap is the local keymap to
156 use in the minibuffer. If @var{keymap} is omitted or @code{nil}, the
157 value of @code{minibuffer-local-map} is used as the keymap. Specifying
158 a keymap is the most important way to customize the minibuffer for
159 various applications such as completion.
161 The argument @var{history} specifies a history list variable to use
162 for saving the input and for history commands used in the minibuffer.
163 It defaults to @code{minibuffer-history}. You can optionally specify
164 a starting position in the history list as well. @xref{Minibuffer History}.
166 If the variable @code{minibuffer-allow-text-properties} is
167 non-@code{nil}, then the string that is returned includes whatever text
168 properties were present in the minibuffer. Otherwise all the text
169 properties are stripped when the value is returned.
171 If the argument @var{inherit-input-method} is non-@code{nil}, then the
172 minibuffer inherits the current input method (@pxref{Input Methods}) and
173 the setting of @code{enable-multibyte-characters} (@pxref{Text
174 Representations}) from whichever buffer was current before entering the
177 Use of @var{initial} is mostly deprecated; we recommend using
178 a non-@code{nil} value only in conjunction with specifying a cons cell
179 for @var{history}. @xref{Initial Input}.
182 @defun read-string prompt &optional initial history default inherit-input-method
183 This function reads a string from the minibuffer and returns it. The
184 arguments @var{prompt}, @var{initial}, @var{history} and
185 @var{inherit-input-method} are used as in @code{read-from-minibuffer}.
186 The keymap used is @code{minibuffer-local-map}.
188 The optional argument @var{default} is used as in
189 @code{read-from-minibuffer}, except that, if non-@code{nil}, it also
190 specifies a default value to return if the user enters null input. As
191 in @code{read-from-minibuffer} it should be a string, a list of
192 strings, or @code{nil}, which is equivalent to an empty string. When
193 @var{default} is a string, that string is the default value. When it
194 is a list of strings, the first string is the default value. (All
195 these strings are available to the user in the ``future minibuffer
198 This function works by calling the
199 @code{read-from-minibuffer} function:
203 (read-string @var{prompt} @var{initial} @var{history} @var{default} @var{inherit})
206 (read-from-minibuffer @var{prompt} @var{initial} nil nil
207 @var{history} @var{default} @var{inherit})))
208 (if (and (equal value "") @var{default})
209 (if (consp @var{default}) (car @var{default}) @var{default})
215 @defun read-regexp prompt &optional default
216 This function reads a regular expression as a string from the
217 minibuffer and returns it. The argument @var{prompt} is used as in
218 @code{read-from-minibuffer}. The keymap used is
219 @code{minibuffer-local-map}, and @code{regexp-history} is used as the
220 history list (@pxref{Minibuffer History, regexp-history}).
222 The optional argument @var{default} specifies a default value to
223 return if the user enters null input; it should be a string, or
224 @code{nil}, which is equivalent to an empty string.
226 In addition, @code{read-regexp} collects a few useful candidates for
227 input and passes them to @code{read-from-minibuffer}, to make them
228 available to the user as the ``future minibuffer history list''
229 (@pxref{Minibuffer History, future list,, emacs, The GNU Emacs
230 Manual}). These candidates are:
234 The word or symbol at point.
236 The last regexp used in an incremental search.
238 The last string used in an incremental search.
240 The last string or pattern used in query-replace commands.
243 This function works by calling the @code{read-from-minibuffer}
244 function, after computing the list of defaults as described above.
247 @defvar minibuffer-allow-text-properties
248 If this variable is @code{nil}, then @code{read-from-minibuffer}
249 and @code{read-string} strip all text properties from the minibuffer
250 input before returning it. However,
251 @code{read-no-blanks-input} (see below), as well as
252 @code{read-minibuffer} and related functions (@pxref{Object from
253 Minibuffer,, Reading Lisp Objects With the Minibuffer}), and all
254 functions that do minibuffer input with completion, discard text
255 properties unconditionally, regardless of the value of this variable.
258 @defvar minibuffer-local-map
260 @anchor{Definition of minibuffer-local-map}
261 @c avoid page break at anchor; work around Texinfo deficiency
262 is the default local keymap for reading from the minibuffer. By
263 default, it makes the following bindings:
267 @code{exit-minibuffer}
270 @code{exit-minibuffer}
273 @code{abort-recursive-edit}
277 @code{next-history-element}
281 @code{previous-history-element}
284 @code{next-matching-history-element}
287 @code{previous-matching-history-element}
290 @c Does not seem worth/appropriate mentioning.
291 @item @kbd{C-@key{TAB}}
292 @code{file-cache-minibuffer-complete}
297 @c In version 18, initial is required
299 @defun read-no-blanks-input prompt &optional initial inherit-input-method
300 This function reads a string from the minibuffer, but does not allow
301 whitespace characters as part of the input: instead, those characters
302 terminate the input. The arguments @var{prompt}, @var{initial}, and
303 @var{inherit-input-method} are used as in @code{read-from-minibuffer}.
305 This is a simplified interface to the @code{read-from-minibuffer}
306 function, and passes the value of the @code{minibuffer-local-ns-map}
307 keymap as the @var{keymap} argument for that function. Since the keymap
308 @code{minibuffer-local-ns-map} does not rebind @kbd{C-q}, it @emph{is}
309 possible to put a space into the string, by quoting it.
311 This function discards text properties, regardless of the value of
312 @code{minibuffer-allow-text-properties}.
316 (read-no-blanks-input @var{prompt} @var{initial})
318 (let (minibuffer-allow-text-properties)
319 (read-from-minibuffer @var{prompt} @var{initial} minibuffer-local-ns-map))
324 @c Slightly unfortunate name, suggesting it might be related to the
326 @defvar minibuffer-local-ns-map
327 This built-in variable is the keymap used as the minibuffer local keymap
328 in the function @code{read-no-blanks-input}. By default, it makes the
329 following bindings, in addition to those of @code{minibuffer-local-map}:
333 @cindex @key{SPC} in minibuffer
334 @code{exit-minibuffer}
337 @cindex @key{TAB} in minibuffer
338 @code{exit-minibuffer}
341 @cindex @kbd{?} in minibuffer
342 @code{self-insert-and-exit}
346 @node Object from Minibuffer
347 @section Reading Lisp Objects with the Minibuffer
349 This section describes functions for reading Lisp objects with the
352 @defun read-minibuffer prompt &optional initial
353 This function reads a Lisp object using the minibuffer, and returns it
354 without evaluating it. The arguments @var{prompt} and @var{initial} are
355 used as in @code{read-from-minibuffer}.
357 This is a simplified interface to the
358 @code{read-from-minibuffer} function:
362 (read-minibuffer @var{prompt} @var{initial})
364 (let (minibuffer-allow-text-properties)
365 (read-from-minibuffer @var{prompt} @var{initial} nil t))
369 Here is an example in which we supply the string @code{"(testing)"} as
375 "Enter an expression: " (format "%s" '(testing)))
377 ;; @r{Here is how the minibuffer is displayed:}
381 ---------- Buffer: Minibuffer ----------
382 Enter an expression: (testing)@point{}
383 ---------- Buffer: Minibuffer ----------
388 The user can type @key{RET} immediately to use the initial input as a
389 default, or can edit the input.
392 @defun eval-minibuffer prompt &optional initial
393 This function reads a Lisp expression using the minibuffer, evaluates
394 it, then returns the result. The arguments @var{prompt} and
395 @var{initial} are used as in @code{read-from-minibuffer}.
397 This function simply evaluates the result of a call to
398 @code{read-minibuffer}:
402 (eval-minibuffer @var{prompt} @var{initial})
404 (eval (read-minibuffer @var{prompt} @var{initial}))
409 @defun edit-and-eval-command prompt form
410 This function reads a Lisp expression in the minibuffer, evaluates it,
411 then returns the result. The difference between this command and
412 @code{eval-minibuffer} is that here the initial @var{form} is not
413 optional and it is treated as a Lisp object to be converted to printed
414 representation rather than as a string of text. It is printed with
415 @code{prin1}, so if it is a string, double-quote characters (@samp{"})
416 appear in the initial text. @xref{Output Functions}.
418 In the following example, we offer the user an expression with initial
419 text that is already a valid form:
423 (edit-and-eval-command "Please edit: " '(forward-word 1))
425 ;; @r{After evaluation of the preceding expression,}
426 ;; @r{the following appears in the minibuffer:}
430 ---------- Buffer: Minibuffer ----------
431 Please edit: (forward-word 1)@point{}
432 ---------- Buffer: Minibuffer ----------
437 Typing @key{RET} right away would exit the minibuffer and evaluate the
438 expression, thus moving point forward one word.
441 @node Minibuffer History
442 @section Minibuffer History
443 @cindex minibuffer history
446 A @dfn{minibuffer history list} records previous minibuffer inputs
447 so the user can reuse them conveniently. It is a variable whose value
448 is a list of strings (previous inputs), most recent first.
450 There are many separate minibuffer history lists, used for different
451 kinds of inputs. It's the Lisp programmer's job to specify the right
452 history list for each use of the minibuffer.
454 You specify a minibuffer history list with the optional @var{history}
455 argument to @code{read-from-minibuffer} or @code{completing-read}.
456 Here are the possible values for it:
460 Use @var{variable} (a symbol) as the history list.
462 @item (@var{variable} . @var{startpos})
463 Use @var{variable} (a symbol) as the history list, and assume that the
464 initial history position is @var{startpos} (a nonnegative integer).
466 Specifying 0 for @var{startpos} is equivalent to just specifying the
467 symbol @var{variable}. @code{previous-history-element} will display
468 the most recent element of the history list in the minibuffer. If you
469 specify a positive @var{startpos}, the minibuffer history functions
470 behave as if @code{(elt @var{variable} (1- @var{startpos}))} were the
471 history element currently shown in the minibuffer.
473 For consistency, you should also specify that element of the history
474 as the initial minibuffer contents, using the @var{initial} argument
475 to the minibuffer input function (@pxref{Initial Input}).
478 If you don't specify @var{history}, then the default history list
479 @code{minibuffer-history} is used. For other standard history lists,
480 see below. You can also create your own history list variable; just
481 initialize it to @code{nil} before the first use.
483 Both @code{read-from-minibuffer} and @code{completing-read} add new
484 elements to the history list automatically, and provide commands to
485 allow the user to reuse items on the list. The only thing your program
486 needs to do to use a history list is to initialize it and to pass its
487 name to the input functions when you wish. But it is safe to modify the
488 list by hand when the minibuffer input functions are not using it.
490 Emacs functions that add a new element to a history list can also
491 delete old elements if the list gets too long. The variable
492 @code{history-length} specifies the maximum length for most history
493 lists. To specify a different maximum length for a particular history
494 list, put the length in the @code{history-length} property of the
495 history list symbol. The variable @code{history-delete-duplicates}
496 specifies whether to delete duplicates in history.
498 @defun add-to-history history-var newelt &optional maxelt keep-all
499 This function adds a new element @var{newelt}, if it isn't the empty
500 string, to the history list stored in the variable @var{history-var},
501 and returns the updated history list. It limits the list length to
502 the value of @var{maxelt} (if non-@code{nil}) or @code{history-length}
503 (described below). The possible values of @var{maxelt} have the same
504 meaning as the values of @code{history-length}.
506 Normally, @code{add-to-history} removes duplicate members from the
507 history list if @code{history-delete-duplicates} is non-@code{nil}.
508 However, if @var{keep-all} is non-@code{nil}, that says not to remove
509 duplicates, and to add @var{newelt} to the list even if it is empty.
512 @defvar history-add-new-input
513 If the value of this variable is @code{nil}, standard functions that
514 read from the minibuffer don't add new elements to the history list.
515 This lets Lisp programs explicitly manage input history by using
516 @code{add-to-history}. By default, @code{history-add-new-input} is
520 @defopt history-length
521 The value of this variable specifies the maximum length for all
522 history lists that don't specify their own maximum lengths. If the
523 value is @code{t}, that means there is no maximum (don't delete old
524 elements). If a history list variable's symbol has a non-@code{nil}
525 @code{history-length} property, it overrides this variable for that
526 particular history list.
529 @defopt history-delete-duplicates
530 If the value of this variable is @code{t}, that means when adding a
531 new history element, all previous identical elements are deleted.
534 Here are some of the standard minibuffer history list variables:
536 @defvar minibuffer-history
537 The default history list for minibuffer history input.
540 @defvar query-replace-history
541 A history list for arguments to @code{query-replace} (and similar
542 arguments to other commands).
545 @defvar file-name-history
546 A history list for file-name arguments.
549 @defvar buffer-name-history
550 A history list for buffer-name arguments.
553 @defvar regexp-history
554 A history list for regular expression arguments.
557 @defvar extended-command-history
558 A history list for arguments that are names of extended commands.
561 @defvar shell-command-history
562 A history list for arguments that are shell commands.
565 @defvar read-expression-history
566 A history list for arguments that are Lisp expressions to evaluate.
569 @defvar face-name-history
570 A history list for arguments that are faces.
573 @c Less common: coding-system-history, input-method-history,
574 @c command-history, grep-history, grep-find-history,
575 @c read-envvar-name-history, setenv-history, yes-or-no-p-history.
578 @section Initial Input
580 Several of the functions for minibuffer input have an argument called
581 @var{initial}. This is a mostly-deprecated
582 feature for specifying that the minibuffer should start out with
583 certain text, instead of empty as usual.
585 If @var{initial} is a string, the minibuffer starts out containing the
586 text of the string, with point at the end, when the user starts to
587 edit the text. If the user simply types @key{RET} to exit the
588 minibuffer, it will use the initial input string to determine the
591 @strong{We discourage use of a non-@code{nil} value for
592 @var{initial}}, because initial input is an intrusive interface.
593 History lists and default values provide a much more convenient method
594 to offer useful default inputs to the user.
596 There is just one situation where you should specify a string for an
597 @var{initial} argument. This is when you specify a cons cell for the
598 @var{history} argument. @xref{Minibuffer History}.
600 @var{initial} can also be a cons cell of the form @code{(@var{string}
601 . @var{position})}. This means to insert @var{string} in the
602 minibuffer but put point at @var{position} within the string's text.
604 As a historical accident, @var{position} was implemented
605 inconsistently in different functions. In @code{completing-read},
606 @var{position}'s value is interpreted as origin-zero; that is, a value
607 of 0 means the beginning of the string, 1 means after the first
608 character, etc. In @code{read-minibuffer}, and the other
609 non-completion minibuffer input functions that support this argument,
610 1 means the beginning of the string, 2 means after the first character,
613 Use of a cons cell as the value for @var{initial} arguments is deprecated.
619 @dfn{Completion} is a feature that fills in the rest of a name
620 starting from an abbreviation for it. Completion works by comparing the
621 user's input against a list of valid names and determining how much of
622 the name is determined uniquely by what the user has typed. For
623 example, when you type @kbd{C-x b} (@code{switch-to-buffer}) and then
624 @c "This is the sort of English up with which I will not put."
625 type the first few letters of the name of the buffer to which you wish
626 to switch, and then type @key{TAB} (@code{minibuffer-complete}), Emacs
627 extends the name as far as it can.
629 Standard Emacs commands offer completion for names of symbols, files,
630 buffers, and processes; with the functions in this section, you can
631 implement completion for other kinds of names.
633 The @code{try-completion} function is the basic primitive for
634 completion: it returns the longest determined completion of a given
635 initial string, with a given set of strings to match against.
637 The function @code{completing-read} provides a higher-level interface
638 for completion. A call to @code{completing-read} specifies how to
639 determine the list of valid names. The function then activates the
640 minibuffer with a local keymap that binds a few keys to commands useful
641 for completion. Other functions provide convenient simple interfaces
642 for reading certain kinds of names with completion.
645 * Basic Completion:: Low-level functions for completing strings.
646 * Minibuffer Completion:: Invoking the minibuffer with completion.
647 * Completion Commands:: Minibuffer commands that do completion.
648 * High-Level Completion:: Convenient special cases of completion
649 (reading buffer names, variable names, etc.).
650 * Reading File Names:: Using completion to read file names and
652 * Completion Variables:: Variables controlling completion behavior.
653 * Programmed Completion:: Writing your own completion function.
654 * Completion in Buffers:: Completing text in ordinary buffers.
657 @node Basic Completion
658 @subsection Basic Completion Functions
660 The following completion functions have nothing in themselves to do
661 with minibuffers. We describe them here to keep them near the
662 higher-level completion features that do use the minibuffer.
664 @defun try-completion string collection &optional predicate
665 This function returns the longest common substring of all possible
666 completions of @var{string} in @var{collection}.
668 @cindex completion table
669 The @var{collection} argument is called the @dfn{completion table}.
670 Its value must be a list of strings, an alist whose keys are strings
671 or symbols, an obarray, a hash table, or a completion function.
673 Completion compares @var{string} against each of the permissible
674 completions specified by @var{collection}. If no permissible
675 completions match, @code{try-completion} returns @code{nil}. If there
676 is just one matching completion, and the match is exact, it returns
677 @code{t}. Otherwise, it returns the longest initial sequence common
678 to all possible matching completions.
680 If @var{collection} is an alist (@pxref{Association Lists}), the
681 permissible completions are the elements of the alist that are either
682 strings, or conses whose @sc{car} is a string or symbol.
683 Symbols are converted to strings using @code{symbol-name}. Other
684 elements of the alist are ignored. (Remember that in Emacs Lisp, the
685 elements of alists do not @emph{have} to be conses.) In particular, a
686 list of strings is allowed, even though we usually do not
687 think of such lists as alists.
689 @cindex obarray in completion
690 If @var{collection} is an obarray (@pxref{Creating Symbols}), the names
691 of all symbols in the obarray form the set of permissible completions.
693 If @var{collection} is a hash table, then the keys that are strings
694 are the possible completions. Other keys are ignored.
696 You can also use a function as @var{collection}. Then the function is
697 solely responsible for performing completion; @code{try-completion}
698 returns whatever this function returns. The function is called with
699 three arguments: @var{string}, @var{predicate} and @code{nil} (the
700 reason for the third argument is so that the same function can be used
701 in @code{all-completions} and do the appropriate thing in either
702 case). @xref{Programmed Completion}.
704 If the argument @var{predicate} is non-@code{nil}, then it must be a
705 function of one argument, unless @var{collection} is a hash table, in
706 which case it should be a function of two arguments. It is used to
707 test each possible match, and the match is accepted only if
708 @var{predicate} returns non-@code{nil}. The argument given to
709 @var{predicate} is either a string or a cons cell (the @sc{car} of
710 which is a string) from the alist, or a symbol (@emph{not} a symbol
711 name) from the obarray. If @var{collection} is a hash table,
712 @var{predicate} is called with two arguments, the string key and the
715 In addition, to be acceptable, a completion must also match all the
716 regular expressions in @code{completion-regexp-list}. (Unless
717 @var{collection} is a function, in which case that function has to
718 handle @code{completion-regexp-list} itself.)
720 In the first of the following examples, the string @samp{foo} is
721 matched by three of the alist @sc{car}s. All of the matches begin with
722 the characters @samp{fooba}, so that is the result. In the second
723 example, there is only one possible match, and it is exact, so the value
730 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)))
735 (try-completion "foo" '(("barfoo" 2) ("foo" 3)))
740 In the following example, numerous symbols begin with the characters
741 @samp{forw}, and all of them begin with the word @samp{forward}. In
742 most of the symbols, this is followed with a @samp{-}, but not in all,
743 so no more than @samp{forward} can be completed.
747 (try-completion "forw" obarray)
752 Finally, in the following example, only two of the three possible
753 matches pass the predicate @code{test} (the string @samp{foobaz} is
754 too short). Both of those begin with the string @samp{foobar}.
759 (> (length (car s)) 6))
765 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
772 @c Removed obsolete argument nospace.
773 @defun all-completions string collection &optional predicate
774 This function returns a list of all possible completions of
775 @var{string}. The arguments to this function
776 @c (aside from @var{nospace})
777 are the same as those of @code{try-completion}, and it
778 uses @code{completion-regexp-list} in the same way that
779 @code{try-completion} does.
782 The optional argument @var{nospace} is obsolete. If it is
783 non-@code{nil}, completions that start with a space are ignored unless
784 @var{string} starts with a space.
787 If @var{collection} is a function, it is called with three arguments:
788 @var{string}, @var{predicate} and @code{t}; then @code{all-completions}
789 returns whatever the function returns. @xref{Programmed Completion}.
791 Here is an example, using the function @code{test} shown in the
792 example for @code{try-completion}:
797 (> (length (car s)) 6))
804 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
806 @result{} ("foobar1" "foobar2")
811 @defun test-completion string collection &optional predicate
812 @anchor{Definition of test-completion}
813 This function returns non-@code{nil} if @var{string} is a valid
814 completion alternative specified by @var{collection} and
815 @var{predicate}. The arguments are the same as in
816 @code{try-completion}. For instance, if @var{collection} is a list of
817 strings, this is true if @var{string} appears in the list and
818 @var{predicate} is satisfied.
820 This function uses @code{completion-regexp-list} in the same
821 way that @code{try-completion} does.
823 If @var{predicate} is non-@code{nil} and if @var{collection} contains
824 several strings that are equal to each other, as determined by
825 @code{compare-strings} according to @code{completion-ignore-case},
826 then @var{predicate} should accept either all or none of them.
827 Otherwise, the return value of @code{test-completion} is essentially
830 If @var{collection} is a function, it is called with three arguments,
831 the values @var{string}, @var{predicate} and @code{lambda}; whatever
832 it returns, @code{test-completion} returns in turn.
835 @defun completion-boundaries string collection predicate suffix
836 This function returns the boundaries of the field on which @var{collection}
837 will operate, assuming that @var{string} holds the text before point
838 and @var{suffix} holds the text after point.
840 Normally completion operates on the whole string, so for all normal
841 collections, this will always return @code{(0 . (length
842 @var{suffix}))}. But more complex completion such as completion on
843 files is done one field at a time. For example, completion of
844 @code{"/usr/sh"} will include @code{"/usr/share/"} but not
845 @code{"/usr/share/doc"} even if @code{"/usr/share/doc"} exists.
846 Also @code{all-completions} on @code{"/usr/sh"} will not include
847 @code{"/usr/share/"} but only @code{"share/"}. So if @var{string} is
848 @code{"/usr/sh"} and @var{suffix} is @code{"e/doc"},
849 @code{completion-boundaries} will return @code{(5 . 1)} which tells us
850 that the @var{collection} will only return completion information that
851 pertains to the area after @code{"/usr/"} and before @code{"/doc"}.
854 If you store a completion alist in a variable, you should mark the
855 variable as ``risky'' by giving it a non-@code{nil}
856 @code{risky-local-variable} property. @xref{File Local Variables}.
858 @defvar completion-ignore-case
859 If the value of this variable is non-@code{nil}, case is not
860 considered significant in completion. Within @code{read-file-name},
861 this variable is overridden by
862 @code{read-file-name-completion-ignore-case} (@pxref{Reading File
863 Names}); within @code{read-buffer}, it is overridden by
864 @code{read-buffer-completion-ignore-case} (@pxref{High-Level
868 @defvar completion-regexp-list
869 This is a list of regular expressions. The completion functions only
870 consider a completion acceptable if it matches all regular expressions
871 in this list, with @code{case-fold-search} (@pxref{Searching and Case})
872 bound to the value of @code{completion-ignore-case}.
875 @defmac lazy-completion-table var fun
876 This macro provides a way to initialize the variable @var{var} as a
877 collection for completion in a lazy way, not computing its actual
878 contents until they are first needed. You use this macro to produce a
879 value that you store in @var{var}. The actual computation of the
880 proper value is done the first time you do completion using @var{var}.
881 It is done by calling @var{fun} with no arguments. The
882 value @var{fun} returns becomes the permanent value of @var{var}.
887 (defvar foo (lazy-completion-table foo make-my-alist))
891 @node Minibuffer Completion
892 @subsection Completion and the Minibuffer
893 @cindex minibuffer completion
894 @cindex reading from minibuffer with completion
896 This section describes the basic interface for reading from the
897 minibuffer with completion.
899 @defun completing-read prompt collection &optional predicate require-match initial history default inherit-input-method
900 This function reads a string in the minibuffer, assisting the user by
901 providing completion. It activates the minibuffer with prompt
902 @var{prompt}, which must be a string.
904 The actual completion is done by passing the completion table
905 @var{collection} and the completion predicate @var{predicate} to the
906 function @code{try-completion} (@pxref{Basic Completion}). This
907 happens in certain commands bound in the local keymaps used for
908 completion. Some of these commands also call @code{test-completion}.
909 Thus, if @var{predicate} is non-@code{nil}, it should be compatible
910 with @var{collection} and @code{completion-ignore-case}.
911 @xref{Definition of test-completion}.
913 The value of the optional argument @var{require-match} determines how
914 the user may exit the minibuffer:
918 If @code{nil}, the usual minibuffer exit commands work regardless of
919 the input in the minibuffer.
922 If @code{t}, the usual minibuffer exit commands won't exit unless the
923 input completes to an element of @var{collection}.
926 If @code{confirm}, the user can exit with any input, but is asked for
927 confirmation if the input is not an element of @var{collection}.
930 If @code{confirm-after-completion}, the user can exit with any input,
931 but is asked for confirmation if the preceding command was a
932 completion command (i.e., one of the commands in
933 @code{minibuffer-confirm-exit-commands}) and the resulting input is
934 not an element of @var{collection}. @xref{Completion Commands}.
937 Any other value of @var{require-match} behaves like @code{t}, except
938 that the exit commands won't exit if it performs completion.
941 However, empty input is always permitted, regardless of the value of
942 @var{require-match}; in that case, @code{completing-read} returns the
943 first element of @var{default}, if it is a list; @code{""}, if
944 @var{default} is @code{nil}; or @var{default}. The string or strings
945 in @var{default} are also available to the user through the history
948 The function @code{completing-read} uses
949 @code{minibuffer-local-completion-map} as the keymap if
950 @var{require-match} is @code{nil}, and uses
951 @code{minibuffer-local-must-match-map} if @var{require-match} is
952 non-@code{nil}. @xref{Completion Commands}.
954 The argument @var{history} specifies which history list variable to use for
955 saving the input and for minibuffer history commands. It defaults to
956 @code{minibuffer-history}. @xref{Minibuffer History}.
958 The argument @var{initial} is mostly deprecated; we recommend using a
959 non-@code{nil} value only in conjunction with specifying a cons cell
960 for @var{history}. @xref{Initial Input}. For default input, use
961 @var{default} instead.
963 If the argument @var{inherit-input-method} is non-@code{nil}, then the
964 minibuffer inherits the current input method (@pxref{Input
965 Methods}) and the setting of @code{enable-multibyte-characters}
966 (@pxref{Text Representations}) from whichever buffer was current before
967 entering the minibuffer.
969 If the variable @code{completion-ignore-case} is
970 non-@code{nil}, completion ignores case when comparing the input
971 against the possible matches. @xref{Basic Completion}. In this mode
972 of operation, @var{predicate} must also ignore case, or you will get
975 Here's an example of using @code{completing-read}:
981 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
986 ;; @r{After evaluation of the preceding expression,}
987 ;; @r{the following appears in the minibuffer:}
989 ---------- Buffer: Minibuffer ----------
990 Complete a foo: fo@point{}
991 ---------- Buffer: Minibuffer ----------
996 If the user then types @kbd{@key{DEL} @key{DEL} b @key{RET}},
997 @code{completing-read} returns @code{barfoo}.
999 The @code{completing-read} function binds variables to pass
1000 information to the commands that actually do completion.
1001 They are described in the following section.
1004 @defvar completing-read-function
1005 The value of this variable must be a function, which is called by
1006 @code{completing-read} to actually do its work. It should accept the
1007 same arguments as @code{completing-read}. This can be bound to a
1008 different function to completely override the normal behavior of
1009 @code{completing-read}.
1012 @node Completion Commands
1013 @subsection Minibuffer Commands that Do Completion
1015 This section describes the keymaps, commands and user options used
1016 in the minibuffer to do completion.
1018 @defvar minibuffer-completion-table
1019 The value of this variable is the completion table used for completion
1020 in the minibuffer. This is the global variable that contains what
1021 @code{completing-read} passes to @code{try-completion}. It is used by
1022 minibuffer completion commands such as
1023 @code{minibuffer-complete-word}.
1026 @defvar minibuffer-completion-predicate
1027 This variable's value is the predicate that @code{completing-read}
1028 passes to @code{try-completion}. The variable is also used by the other
1029 minibuffer completion functions.
1032 @defvar minibuffer-completion-confirm
1033 This variable determines whether Emacs asks for confirmation before
1034 exiting the minibuffer; @code{completing-read} binds this variable,
1035 and the function @code{minibuffer-complete-and-exit} checks the value
1036 before exiting. If the value is @code{nil}, confirmation is not
1037 required. If the value is @code{confirm}, the user may exit with an
1038 input that is not a valid completion alternative, but Emacs asks for
1039 confirmation. If the value is @code{confirm-after-completion}, the
1040 user may exit with an input that is not a valid completion
1041 alternative, but Emacs asks for confirmation if the user submitted the
1042 input right after any of the completion commands in
1043 @code{minibuffer-confirm-exit-commands}.
1046 @defvar minibuffer-confirm-exit-commands
1047 This variable holds a list of commands that cause Emacs to ask for
1048 confirmation before exiting the minibuffer, if the @var{require-match}
1049 argument to @code{completing-read} is @code{confirm-after-completion}.
1050 The confirmation is requested if the user attempts to exit the
1051 minibuffer immediately after calling any command in this list.
1054 @deffn Command minibuffer-complete-word
1055 This function completes the minibuffer contents by at most a single
1056 word. Even if the minibuffer contents have only one completion,
1057 @code{minibuffer-complete-word} does not add any characters beyond the
1058 first character that is not a word constituent. @xref{Syntax Tables}.
1061 @deffn Command minibuffer-complete
1062 This function completes the minibuffer contents as far as possible.
1065 @deffn Command minibuffer-complete-and-exit
1066 This function completes the minibuffer contents, and exits if
1067 confirmation is not required, i.e., if
1068 @code{minibuffer-completion-confirm} is @code{nil}. If confirmation
1069 @emph{is} required, it is given by repeating this command
1070 immediately---the command is programmed to work without confirmation
1071 when run twice in succession.
1074 @deffn Command minibuffer-completion-help
1075 This function creates a list of the possible completions of the
1076 current minibuffer contents. It works by calling @code{all-completions}
1077 using the value of the variable @code{minibuffer-completion-table} as
1078 the @var{collection} argument, and the value of
1079 @code{minibuffer-completion-predicate} as the @var{predicate} argument.
1080 The list of completions is displayed as text in a buffer named
1081 @file{*Completions*}.
1084 @defun display-completion-list completions &optional common-substring
1085 This function displays @var{completions} to the stream in
1086 @code{standard-output}, usually a buffer. (@xref{Read and Print}, for more
1087 information about streams.) The argument @var{completions} is normally
1088 a list of completions just returned by @code{all-completions}, but it
1089 does not have to be. Each element may be a symbol or a string, either
1090 of which is simply printed. It can also be a list of two strings,
1091 which is printed as if the strings were concatenated. The first of
1092 the two strings is the actual completion, the second string serves as
1095 The argument @var{common-substring} is the prefix that is common to
1096 all the completions. With normal Emacs completion, it is usually the
1097 same as the string that was completed. @code{display-completion-list}
1098 uses this to highlight text in the completion list for better visual
1099 feedback. This is not needed in the minibuffer; for minibuffer
1100 completion, you can pass @code{nil}.
1102 This function is called by @code{minibuffer-completion-help}. A
1103 common way to use it is together with
1104 @code{with-output-to-temp-buffer}, like this:
1107 (with-output-to-temp-buffer "*Completions*"
1108 (display-completion-list
1109 (all-completions (buffer-string) my-alist)
1114 @defopt completion-auto-help
1115 If this variable is non-@code{nil}, the completion commands
1116 automatically display a list of possible completions whenever nothing
1117 can be completed because the next character is not uniquely determined.
1120 @defvar minibuffer-local-completion-map
1121 @code{completing-read} uses this value as the local keymap when an
1122 exact match of one of the completions is not required. By default, this
1123 keymap makes the following bindings:
1127 @code{minibuffer-completion-help}
1130 @code{minibuffer-complete-word}
1133 @code{minibuffer-complete}
1137 and uses @code{minibuffer-local-map} as its parent keymap
1138 (@pxref{Definition of minibuffer-local-map}).
1141 @defvar minibuffer-local-must-match-map
1142 @code{completing-read} uses this value as the local keymap when an
1143 exact match of one of the completions is required. Therefore, no keys
1144 are bound to @code{exit-minibuffer}, the command that exits the
1145 minibuffer unconditionally. By default, this keymap makes the following
1150 @code{minibuffer-complete-and-exit}
1153 @code{minibuffer-complete-and-exit}
1157 and uses @code{minibuffer-local-completion-map} as its parent keymap.
1160 @defvar minibuffer-local-filename-completion-map
1161 This is a sparse keymap that simply unbinds @key{SPC}; because
1162 filenames can contain spaces. The function @code{read-file-name}
1163 combines this keymap with either @code{minibuffer-local-completion-map}
1164 or @code{minibuffer-local-must-match-map}.
1168 @node High-Level Completion
1169 @subsection High-Level Completion Functions
1171 This section describes the higher-level convenience functions for
1172 reading certain sorts of names with completion.
1174 In most cases, you should not call these functions in the middle of a
1175 Lisp function. When possible, do all minibuffer input as part of
1176 reading the arguments for a command, in the @code{interactive}
1177 specification. @xref{Defining Commands}.
1179 @defun read-buffer prompt &optional default require-match
1180 This function reads the name of a buffer and returns it as a string.
1181 The argument @var{default} is the default name to use, the value to
1182 return if the user exits with an empty minibuffer. If non-@code{nil},
1183 it should be a string, a list of strings, or a buffer. If it is
1184 a list, the default value is the first element of this list. It is
1185 mentioned in the prompt, but is not inserted in the minibuffer as
1188 The argument @var{prompt} should be a string ending with a colon and a
1189 space. If @var{default} is non-@code{nil}, the function inserts it in
1190 @var{prompt} before the colon to follow the convention for reading from
1191 the minibuffer with a default value (@pxref{Programming Tips}).
1193 The optional argument @var{require-match} has the same meaning as in
1194 @code{completing-read}. @xref{Minibuffer Completion}.
1196 In the following example, the user enters @samp{minibuffer.t}, and
1197 then types @key{RET}. The argument @var{require-match} is @code{t},
1198 and the only buffer name starting with the given input is
1199 @samp{minibuffer.texi}, so that name is the value.
1202 (read-buffer "Buffer name: " "foo" t)
1204 ;; @r{After evaluation of the preceding expression,}
1205 ;; @r{the following prompt appears,}
1206 ;; @r{with an empty minibuffer:}
1210 ---------- Buffer: Minibuffer ----------
1211 Buffer name (default foo): @point{}
1212 ---------- Buffer: Minibuffer ----------
1216 ;; @r{The user types @kbd{minibuffer.t @key{RET}}.}
1217 @result{} "minibuffer.texi"
1222 @defopt read-buffer-function
1223 This variable specifies how to read buffer names. The function is
1224 called with the arguments passed to @code{read-buffer}. For example,
1225 if you set this variable to @code{iswitchb-read-buffer}, all Emacs
1226 commands that call @code{read-buffer} to read a buffer name will
1227 actually use the @code{iswitchb} package to read it.
1230 @defopt read-buffer-completion-ignore-case
1231 If this variable is non-@code{nil}, @code{read-buffer} ignores case
1232 when performing completion.
1235 @defun read-command prompt &optional default
1236 This function reads the name of a command and returns it as a Lisp
1237 symbol. The argument @var{prompt} is used as in
1238 @code{read-from-minibuffer}. Recall that a command is anything for
1239 which @code{commandp} returns @code{t}, and a command name is a symbol
1240 for which @code{commandp} returns @code{t}. @xref{Interactive Call}.
1242 The argument @var{default} specifies what to return if the user enters
1243 null input. It can be a symbol, a string or a list of strings. If it
1244 is a string, @code{read-command} interns it before returning it.
1245 If it is a list, @code{read-command} interns the first element of this list.
1246 If @var{default} is @code{nil}, that means no default has been
1247 specified; then if the user enters null input, the return value is
1248 @code{(intern "")}, that is, a symbol whose name is an empty string.
1251 (read-command "Command name? ")
1254 ;; @r{After evaluation of the preceding expression,}
1255 ;; @r{the following prompt appears with an empty minibuffer:}
1259 ---------- Buffer: Minibuffer ----------
1261 ---------- Buffer: Minibuffer ----------
1266 If the user types @kbd{forward-c @key{RET}}, then this function returns
1267 @code{forward-char}.
1269 The @code{read-command} function is a simplified interface to
1270 @code{completing-read}. It uses the variable @code{obarray} so as to
1271 complete in the set of extant Lisp symbols, and it uses the
1272 @code{commandp} predicate so as to accept only command names:
1274 @cindex @code{commandp} example
1277 (read-command @var{prompt})
1279 (intern (completing-read @var{prompt} obarray
1285 @defun read-variable prompt &optional default
1286 @anchor{Definition of read-variable}
1287 This function reads the name of a user variable and returns it as a
1288 symbol. Its arguments have the same form as those of @code{read-command}.
1289 In general, this function is similar to @code{read-command}, but uses
1290 the predicate @code{user-variable-p} instead of @code{commandp}.
1293 @deffn Command read-color &optional prompt convert allow-empty display
1294 This function reads a string that is a color specification, either the
1295 color's name or an RGB hex value such as @code{#RRRGGGBBB}. It
1296 prompts with @var{prompt} (default: @code{"Color (name or #RGB triplet):"})
1297 and provides completion for color names, but not for hex RGB values.
1298 In addition to names of standard colors, completion candidates include
1299 the foreground and background colors at point.
1301 Valid RGB values are described in @ref{Color Names}.
1303 The function's return value is the string typed by the user in the
1304 minibuffer. However, when called interactively or if the optional
1305 argument @var{convert} is non-@code{nil}, it converts any input color
1306 name into the corresponding RGB value string and instead returns that.
1307 This function requires a valid color specification to be input.
1308 Empty color names are allowed when @var{allow-empty} is
1309 non-@code{nil} and the user enters null input.
1311 Interactively, or when @var{display} is non-@code{nil}, the return
1312 value is also displayed in the echo area.
1315 See also the functions @code{read-coding-system} and
1316 @code{read-non-nil-coding-system}, in @ref{User-Chosen Coding Systems},
1317 and @code{read-input-method-name}, in @ref{Input Methods}.
1319 @node Reading File Names
1320 @subsection Reading File Names
1321 @cindex read file names
1322 @cindex prompt for file name
1324 The high-level completion functions @code{read-file-name},
1325 @code{read-directory-name}, and @code{read-shell-command} are designed
1326 to read file names, directory names, and shell commands, respectively.
1327 They provide special features, including automatic insertion of the
1330 @defun read-file-name prompt &optional directory default require-match initial predicate
1331 This function reads a file name, prompting with @var{prompt} and
1332 providing completion.
1334 As an exception, this function reads a file name using a graphical
1335 file dialog instead of the minibuffer, if all of the following are
1340 It is invoked via a mouse command.
1343 The selected frame is on a graphical display supporting such dialogs.
1346 The variable @code{use-dialog-box} is non-@code{nil}.
1347 @xref{Dialog Boxes,, Dialog Boxes, emacs, The GNU Emacs Manual}.
1350 The @var{directory} argument, described below, does not specify a
1351 remote file. @xref{Remote Files,, Remote Files, emacs, The GNU Emacs Manual}.
1355 The exact behavior when using a graphical file dialog is
1356 platform-dependent. Here, we simply document the behavior when using
1359 @code{read-file-name} does not automatically expand the returned file
1360 name. You must call @code{expand-file-name} yourself if an absolute
1361 file name is required.
1363 The optional argument @var{require-match} has the same meaning as in
1364 @code{completing-read}. @xref{Minibuffer Completion}.
1366 The argument @var{directory} specifies the directory to use for
1367 completing relative file names. It should be an absolute directory
1368 name. If the variable @code{insert-default-directory} is non-@code{nil},
1369 @var{directory} is also inserted in the minibuffer as initial input.
1370 It defaults to the current buffer's value of @code{default-directory}.
1372 If you specify @var{initial}, that is an initial file name to insert
1373 in the buffer (after @var{directory}, if that is inserted). In this
1374 case, point goes at the beginning of @var{initial}. The default for
1375 @var{initial} is @code{nil}---don't insert any file name. To see what
1376 @var{initial} does, try the command @kbd{C-x C-v} in a buffer visiting
1377 a file. @strong{Please note:} we recommend using @var{default} rather
1378 than @var{initial} in most cases.
1380 If @var{default} is non-@code{nil}, then the function returns
1381 @var{default} if the user exits the minibuffer with the same non-empty
1382 contents that @code{read-file-name} inserted initially. The initial
1383 minibuffer contents are always non-empty if
1384 @code{insert-default-directory} is non-@code{nil}, as it is by
1385 default. @var{default} is not checked for validity, regardless of the
1386 value of @var{require-match}. However, if @var{require-match} is
1387 non-@code{nil}, the initial minibuffer contents should be a valid file
1388 (or directory) name. Otherwise @code{read-file-name} attempts
1389 completion if the user exits without any editing, and does not return
1390 @var{default}. @var{default} is also available through the history
1393 If @var{default} is @code{nil}, @code{read-file-name} tries to find a
1394 substitute default to use in its place, which it treats in exactly the
1395 same way as if it had been specified explicitly. If @var{default} is
1396 @code{nil}, but @var{initial} is non-@code{nil}, then the default is
1397 the absolute file name obtained from @var{directory} and
1398 @var{initial}. If both @var{default} and @var{initial} are @code{nil}
1399 and the buffer is visiting a file, @code{read-file-name} uses the
1400 absolute file name of that file as default. If the buffer is not
1401 visiting a file, then there is no default. In that case, if the user
1402 types @key{RET} without any editing, @code{read-file-name} simply
1403 returns the pre-inserted contents of the minibuffer.
1405 If the user types @key{RET} in an empty minibuffer, this function
1406 returns an empty string, regardless of the value of
1407 @var{require-match}. This is, for instance, how the user can make the
1408 current buffer visit no file using @code{M-x set-visited-file-name}.
1410 If @var{predicate} is non-@code{nil}, it specifies a function of one
1411 argument that decides which file names are acceptable completion
1412 alternatives. A file name is an acceptable value if @var{predicate}
1413 returns non-@code{nil} for it.
1415 Here is an example of using @code{read-file-name}:
1419 (read-file-name "The file is ")
1421 ;; @r{After evaluation of the preceding expression,}
1422 ;; @r{the following appears in the minibuffer:}
1426 ---------- Buffer: Minibuffer ----------
1427 The file is /gp/gnu/elisp/@point{}
1428 ---------- Buffer: Minibuffer ----------
1433 Typing @kbd{manual @key{TAB}} results in the following:
1437 ---------- Buffer: Minibuffer ----------
1438 The file is /gp/gnu/elisp/manual.texi@point{}
1439 ---------- Buffer: Minibuffer ----------
1443 @c Wordy to avoid overfull hbox in smallbook mode.
1445 If the user types @key{RET}, @code{read-file-name} returns the file name
1446 as the string @code{"/gp/gnu/elisp/manual.texi"}.
1449 @defvar read-file-name-function
1450 If non-@code{nil}, this should be a function that accepts the same
1451 arguments as @code{read-file-name}. When @code{read-file-name} is
1452 called, it calls this function with the supplied arguments instead of
1453 doing its usual work.
1456 @defopt read-file-name-completion-ignore-case
1457 If this variable is non-@code{nil}, @code{read-file-name} ignores case
1458 when performing completion.
1461 @defun read-directory-name prompt &optional directory default require-match initial
1462 This function is like @code{read-file-name} but allows only directory
1463 names as completion alternatives.
1465 If @var{default} is @code{nil} and @var{initial} is non-@code{nil},
1466 @code{read-directory-name} constructs a substitute default by
1467 combining @var{directory} (or the current buffer's default directory
1468 if @var{directory} is @code{nil}) and @var{initial}. If both
1469 @var{default} and @var{initial} are @code{nil}, this function uses
1470 @var{directory} as substitute default, or the current buffer's default
1471 directory if @var{directory} is @code{nil}.
1474 @defopt insert-default-directory
1475 This variable is used by @code{read-file-name}, and thus, indirectly,
1476 by most commands reading file names. (This includes all commands that
1477 use the code letters @samp{f} or @samp{F} in their interactive form.
1478 @xref{Interactive Codes,, Code Characters for interactive}.) Its
1479 value controls whether @code{read-file-name} starts by placing the
1480 name of the default directory in the minibuffer, plus the initial file
1481 name, if any. If the value of this variable is @code{nil}, then
1482 @code{read-file-name} does not place any initial input in the
1483 minibuffer (unless you specify initial input with the @var{initial}
1484 argument). In that case, the default directory is still used for
1485 completion of relative file names, but is not displayed.
1487 If this variable is @code{nil} and the initial minibuffer contents are
1488 empty, the user may have to explicitly fetch the next history element
1489 to access a default value. If the variable is non-@code{nil}, the
1490 initial minibuffer contents are always non-empty and the user can
1491 always request a default value by immediately typing @key{RET} in an
1492 unedited minibuffer. (See above.)
1498 ;; @r{Here the minibuffer starts out with the default directory.}
1499 (let ((insert-default-directory t))
1500 (read-file-name "The file is "))
1504 ---------- Buffer: Minibuffer ----------
1505 The file is ~lewis/manual/@point{}
1506 ---------- Buffer: Minibuffer ----------
1510 ;; @r{Here the minibuffer is empty and only the prompt}
1511 ;; @r{appears on its line.}
1512 (let ((insert-default-directory nil))
1513 (read-file-name "The file is "))
1517 ---------- Buffer: Minibuffer ----------
1518 The file is @point{}
1519 ---------- Buffer: Minibuffer ----------
1524 @defun read-shell-command prompt &optional initial history &rest args
1525 This function reads a shell command from the minibuffer, prompting
1526 with @var{prompt} and providing intelligent completion. It completes
1527 the first word of the command using candidates that are appropriate
1528 for command names, and the rest of the command words as file names.
1530 This function uses @code{minibuffer-local-shell-command-map} as the
1531 keymap for minibuffer input. The @var{history} argument specifies the
1532 history list to use; if is omitted or @code{nil}, it defaults to
1533 @code{shell-command-history} (@pxref{Minibuffer History,
1534 shell-command-history}). The optional argument @var{initial}
1535 specifies the initial content of the minibuffer (@pxref{Initial
1536 Input}). The rest of @var{args}, if present, are used as the
1537 @var{default} and @var{inherit-input-method} arguments in
1538 @code{read-from-minibuffer} (@pxref{Text from Minibuffer}).
1541 @defvar minibuffer-local-shell-command-map
1542 This keymap is used by @code{read-shell-command} for completing
1543 command and file names that are part of a shell command. It uses
1544 @code{minibuffer-local-map} as its parent keymap, and binds @key{TAB}
1545 to @code{completion-at-point}.
1548 @node Completion Variables
1549 @subsection Completion Variables
1551 Here are some variables that can be used to alter the default
1552 completion behavior.
1554 @cindex completion styles
1555 @defopt completion-styles
1556 The value of this variable is a list of completion style (symbols) to
1557 use for performing completion. A @dfn{completion style} is a set of
1558 rules for generating completions. Each symbol occurring this list
1559 must have a corresponding entry in @code{completion-styles-alist}.
1562 @defvar completion-styles-alist
1563 This variable stores a list of available completion styles. Each
1564 element in the list has the form
1567 (@var{style} @var{try-completion} @var{all-completions} @var{doc})
1571 Here, @var{style} is the name of the completion style (a symbol),
1572 which may be used in the @code{completion-styles} variable to refer to
1573 this style; @var{try-completion} is the function that does the
1574 completion; @var{all-completions} is the function that lists the
1575 completions; and @var{doc} is a string describing the completion
1578 The @var{try-completion} and @var{all-completions} functions should
1579 each accept four arguments: @var{string}, @var{collection},
1580 @var{predicate}, and @var{point}. The @var{string}, @var{collection},
1581 and @var{predicate} arguments have the same meanings as in
1582 @code{try-completion} (@pxref{Basic Completion}), and the @var{point}
1583 argument is the position of point within @var{string}. Each function
1584 should return a non-@code{nil} value if it performed its job, and
1585 @code{nil} if it did not (e.g.@: if there is no way to complete
1586 @var{string} according to the completion style).
1588 When the user calls a completion command like
1589 @code{minibuffer-complete} (@pxref{Completion Commands}), Emacs looks
1590 for the first style listed in @code{completion-styles} and calls its
1591 @var{try-completion} function. If this function returns @code{nil},
1592 Emacs moves to the next listed completion style and calls its
1593 @var{try-completion} function, and so on until one of the
1594 @var{try-completion} functions successfully performs completion and
1595 returns a non-@code{nil} value. A similar procedure is used for
1596 listing completions, via the @var{all-completions} functions.
1598 @xref{Completion Styles,,, emacs, The GNU Emacs Manual}, for a
1599 description of the available completion styles.
1602 @defopt completion-category-overrides
1603 This variable specifies special completion styles and other completion
1604 behaviors to use when completing certain types of text. Its value
1605 should be an alist with elements of the form @code{(@var{category}
1606 . @var{alist})}. @var{category} is a symbol describing what is being
1607 completed; currently, the @code{buffer}, @code{file}, and
1608 @code{unicode-name} categories are defined, but others can be defined
1609 via specialized completion functions (@pxref{Programmed Completion}).
1610 @var{alist} is an association list describing how completion should
1611 behave for the corresponding category. The following alist keys are
1616 The value should be a list of completion styles (symbols).
1619 The value should be a value for @code{completion-cycle-threshold}
1620 (@pxref{Completion Options,,, emacs, The GNU Emacs Manual}) for this
1625 Additional alist entries may be defined in the future.
1628 @defvar completion-extra-properties
1629 This variable is used to specify extra properties of the current
1630 completion command. It is intended to be let-bound by specialized
1631 completion commands. Its value should be a list of property and value
1632 pairs. The following properties are supported:
1635 @item :annotation-function
1636 The value should be a function to add annotations in the completions
1637 buffer. This function must accept one argument, a completion, and
1638 should either return @code{nil} or a string to be displayed next to
1641 @item :exit-function
1642 The value should be a function to run after performing completion.
1643 The function should accept two arguments, @var{string} and
1644 @var{status}, where @var{string} is the text to which the field was
1645 completed, and @var{status} indicates what kind of operation happened:
1646 @code{finished} if text is now complete, @code{sole} if the text
1647 cannot be further completed but completion is not finished, or
1648 @code{exact} if the text is a valid completion but may be further
1653 @node Programmed Completion
1654 @subsection Programmed Completion
1655 @cindex programmed completion
1657 Sometimes it is not possible or convenient to create an alist or
1658 an obarray containing all the intended possible completions ahead
1659 of time. In such a case, you can supply your own function to compute
1660 the completion of a given string. This is called @dfn{programmed
1661 completion}. Emacs uses programmed completion when completing file
1662 names (@pxref{File Name Completion}), among many other cases.
1664 To use this feature, pass a function as the @var{collection}
1665 argument to @code{completing-read}. The function
1666 @code{completing-read} arranges to pass your completion function along
1667 to @code{try-completion}, @code{all-completions}, and other basic
1668 completion functions, which will then let your function do all
1671 The completion function should accept three arguments:
1675 The string to be completed.
1678 A predicate function with which to filter possible matches, or
1679 @code{nil} if none. The function should call the predicate for each
1680 possible match, and ignore the match if the predicate returns
1684 A flag specifying the type of completion operation to perform. This
1685 is one of the following four values:
1689 This specifies a @code{try-completion} operation. The function should
1690 return @code{t} if the specified string is a unique and exact match;
1691 if there is more than one match, it should return the common substring
1692 of all matches (if the string is an exact match for one completion
1693 alternative but also matches other longer alternatives, the return
1694 value is the string); if there are no matches, it should return
1698 This specifies an @code{all-completions} operation. The function
1699 should return a list of all possible completions of the specified
1703 This specifies a @code{test-completion} operation. The function
1704 should return @code{t} if the specified string is an exact match for
1705 some completion alternative; @code{nil} otherwise.
1707 @item (boundaries . @var{suffix})
1708 This specifies a @code{completion-boundaries} operation. The function
1709 should return @code{(boundaries @var{start} . @var{end})}, where
1710 @var{start} is the position of the beginning boundary in the specified
1711 string, and @var{end} is the position of the end boundary in
1715 This specifies a request for information about the state of the
1716 current completion. The function should return an alist, as described
1717 below. The alist may contain any number of elements.
1721 If the flag has any other value, the completion function should return
1725 The following is a list of metadata entries that a completion function
1726 may return in response to a @code{metadata} flag argument:
1730 The value should be a symbol describing what kind of text the
1731 completion function is trying to complete. If the symbol matches one
1732 of the keys in @code{completion-category-overrides}, the usual
1733 completion behavior is overridden. @xref{Completion Variables}.
1735 @item annotation-function
1736 The value should be a function for @dfn{annotating} completions. The
1737 function should take one argument, @var{string}, which is a possible
1738 completion. It should return a string, which is displayed after the
1739 completion @var{string} in the @file{*Completions*} buffer.
1741 @item display-sort-function
1742 The value should be a function for sorting completions. The function
1743 should take one argument, a list of completion strings, and return a
1744 sorted list of completion strings. It is allowed to alter the input
1747 @item cycle-sort-function
1748 The value should be a function for sorting completions, when
1749 @code{completion-cycle-threshold} is non-@code{nil} and the user is
1750 cycling through completion alternatives. @xref{Completion Options,,,
1751 emacs, The GNU Emacs Manual}. Its argument list and return value are
1752 the same as for @code{display-sort-function}.
1755 @defun completion-table-dynamic function
1756 This function is a convenient way to write a function that can act as
1757 a programmed completion function. The argument @var{function} should be
1758 a function that takes one argument, a string, and returns an alist of
1759 possible completions of it. You can think of
1760 @code{completion-table-dynamic} as a transducer between that interface
1761 and the interface for programmed completion functions.
1764 @node Completion in Buffers
1765 @subsection Completion in Ordinary Buffers
1766 @cindex inline completion
1768 @findex completion-at-point
1769 Although completion is usually done in the minibuffer, the
1770 completion facility can also be used on the text in ordinary Emacs
1771 buffers. In many major modes, in-buffer completion is performed by
1772 the @kbd{C-M-i} or @kbd{M-@key{TAB}} command, bound to
1773 @code{completion-at-point}. @xref{Symbol Completion,,, emacs, The GNU
1774 Emacs Manual}. This command uses the abnormal hook variable
1775 @code{completion-at-point-functions}:
1777 @defvar completion-at-point-functions
1778 The value of this abnormal hook should be a list of functions, which
1779 are used to compute a completion table for completing the text at
1780 point. It can be used by major modes to provide mode-specific
1781 completion tables (@pxref{Major Mode Conventions}).
1783 When the command @code{completion-at-point} runs, it calls the
1784 functions in the list one by one, without any argument. Each function
1785 should return @code{nil} if it is unable to produce a completion table
1786 for the text at point. Otherwise it should return a list of the form
1789 (@var{start} @var{end} @var{collection} . @var{props})
1793 @var{start} and @var{end} delimit the text to complete (which should
1794 enclose point). @var{collection} is a completion table for completing
1795 that text, in a form suitable for passing as the second argument to
1796 @code{try-completion} (@pxref{Basic Completion}); completion
1797 alternatives will be generated from this completion table in the usual
1798 way, via the completion styles defined in @code{completion-styles}
1799 (@pxref{Completion Variables}). @var{props} is a property list for
1800 additional information; any of the properties in
1801 @code{completion-extra-properties} are recognized (@pxref{Completion
1802 Variables}), as well as the following additional ones:
1806 The value should be a predicate that completion candidates need to
1810 If the value is @code{no}, then if the completion table fails to match
1811 the text at point, @code{completion-at-point} moves on to the
1812 next function in @code{completion-at-point-functions} instead of
1813 reporting a completion failure.
1816 A function in @code{completion-at-point-functions} may also return a
1817 function. In that case, that returned function is called, with no
1818 argument, and it is entirely responsible for performing the
1819 completion. We discourage this usage; it is intended to help convert
1820 old code to using @code{completion-at-point}.
1822 The first function in @code{completion-at-point-functions} to return a
1823 non-@code{nil} value is used by @code{completion-at-point}. The
1824 remaining functions are not called. The exception to this is when
1825 there is an @code{:exclusive} specification, as described above.
1828 The following function provides a convenient way to perform
1829 completion on an arbitrary stretch of text in an Emacs buffer:
1831 @defun completion-in-region start end collection &optional predicate
1832 This function completes the text in the current buffer between the
1833 positions @var{start} and @var{end}, using @var{collection}. The
1834 argument @var{collection} has the same meaning as in
1835 @code{try-completion} (@pxref{Basic Completion}).
1837 This function inserts the completion text directly into the current
1838 buffer. Unlike @code{completing-read} (@pxref{Minibuffer
1839 Completion}), it does not activate the minibuffer.
1841 For this function to work, point must be somewhere between @var{start}
1846 @node Yes-or-No Queries
1847 @section Yes-or-No Queries
1848 @cindex asking the user questions
1849 @cindex querying the user
1850 @cindex yes-or-no questions
1852 This section describes functions used to ask the user a yes-or-no
1853 question. The function @code{y-or-n-p} can be answered with a single
1854 character; it is useful for questions where an inadvertent wrong answer
1855 will not have serious consequences. @code{yes-or-no-p} is suitable for
1856 more momentous questions, since it requires three or four characters to
1859 If either of these functions is called in a command that was invoked
1860 using the mouse---more precisely, if @code{last-nonmenu-event}
1861 (@pxref{Command Loop Info}) is either @code{nil} or a list---then it
1862 uses a dialog box or pop-up menu to ask the question. Otherwise, it
1863 uses keyboard input. You can force use either of the mouse or of keyboard
1864 input by binding @code{last-nonmenu-event} to a suitable value around
1867 Strictly speaking, @code{yes-or-no-p} uses the minibuffer and
1868 @code{y-or-n-p} does not; but it seems best to describe them together.
1870 @defun y-or-n-p prompt
1871 This function asks the user a question, expecting input in the echo
1872 area. It returns @code{t} if the user types @kbd{y}, @code{nil} if the
1873 user types @kbd{n}. This function also accepts @key{SPC} to mean yes
1874 and @key{DEL} to mean no. It accepts @kbd{C-]} to mean ``quit'', like
1875 @kbd{C-g}, because the question might look like a minibuffer and for
1876 that reason the user might try to use @kbd{C-]} to get out. The answer
1877 is a single character, with no @key{RET} needed to terminate it. Upper
1878 and lower case are equivalent.
1880 ``Asking the question'' means printing @var{prompt} in the echo area,
1881 followed by the string @w{@samp{(y or n) }}. If the input is not one of
1882 the expected answers (@kbd{y}, @kbd{n}, @kbd{@key{SPC}},
1883 @kbd{@key{DEL}}, or something that quits), the function responds
1884 @samp{Please answer y or n.}, and repeats the request.
1886 This function does not actually use the minibuffer, since it does not
1887 allow editing of the answer. It actually uses the echo area (@pxref{The
1888 Echo Area}), which uses the same screen space as the minibuffer. The
1889 cursor moves to the echo area while the question is being asked.
1891 The answers and their meanings, even @samp{y} and @samp{n}, are not
1892 hardwired. The keymap @code{query-replace-map} specifies them.
1893 @xref{Search and Replace}.
1895 In the following example, the user first types @kbd{q}, which is
1896 invalid. At the next prompt the user types @kbd{y}.
1898 @c Need an interactive example, because otherwise the return value
1899 @c obscures the display of the valid answer.
1904 (y-or-n-p "Do you need a lift? "))
1906 ;; @r{After evaluation of the preceding definition, @kbd{M-x ask}}
1907 ;; @r{causes the following prompt to appear in the echo area:}
1911 ---------- Echo area ----------
1912 Do you need a lift? (y or n)
1913 ---------- Echo area ----------
1916 ;; @r{If the user then types @kbd{q}, the following appears:}
1919 ---------- Echo area ----------
1920 Please answer y or n. Do you need a lift? (y or n)
1921 ---------- Echo area ----------
1924 ;; @r{When the user types a valid answer,}
1925 ;; @r{it is displayed after the question:}
1928 ---------- Echo area ----------
1929 Do you need a lift? (y or n) y
1930 ---------- Echo area ----------
1935 We show successive lines of echo area messages, but only one actually
1936 appears on the screen at a time.
1939 @defun y-or-n-p-with-timeout prompt seconds default
1940 Like @code{y-or-n-p}, except that if the user fails to answer within
1941 @var{seconds} seconds, this function stops waiting and returns
1942 @var{default}. It works by setting up a timer; see @ref{Timers}.
1943 The argument @var{seconds} may be an integer or a floating point number.
1946 @defun yes-or-no-p prompt
1947 This function asks the user a question, expecting input in the
1948 minibuffer. It returns @code{t} if the user enters @samp{yes},
1949 @code{nil} if the user types @samp{no}. The user must type @key{RET} to
1950 finalize the response. Upper and lower case are equivalent.
1952 @code{yes-or-no-p} starts by displaying @var{prompt} in the echo area,
1953 followed by @w{@samp{(yes or no) }}. The user must type one of the
1954 expected responses; otherwise, the function responds @samp{Please answer
1955 yes or no.}, waits about two seconds and repeats the request.
1957 @code{yes-or-no-p} requires more work from the user than
1958 @code{y-or-n-p} and is appropriate for more crucial decisions.
1964 (yes-or-no-p "Do you really want to remove everything? ")
1966 ;; @r{After evaluation of the preceding expression,}
1967 ;; @r{the following prompt appears,}
1968 ;; @r{with an empty minibuffer:}
1972 ---------- Buffer: minibuffer ----------
1973 Do you really want to remove everything? (yes or no)
1974 ---------- Buffer: minibuffer ----------
1979 If the user first types @kbd{y @key{RET}}, which is invalid because this
1980 function demands the entire word @samp{yes}, it responds by displaying
1981 these prompts, with a brief pause between them:
1985 ---------- Buffer: minibuffer ----------
1986 Please answer yes or no.
1987 Do you really want to remove everything? (yes or no)
1988 ---------- Buffer: minibuffer ----------
1993 @node Multiple Queries
1994 @section Asking Multiple Y-or-N Questions
1996 When you have a series of similar questions to ask, such as ``Do you
1997 want to save this buffer'' for each buffer in turn, you should use
1998 @code{map-y-or-n-p} to ask the collection of questions, rather than
1999 asking each question individually. This gives the user certain
2000 convenient facilities such as the ability to answer the whole series at
2003 @defun map-y-or-n-p prompter actor list &optional help action-alist no-cursor-in-echo-area
2004 This function asks the user a series of questions, reading a
2005 single-character answer in the echo area for each one.
2007 The value of @var{list} specifies the objects to ask questions about.
2008 It should be either a list of objects or a generator function. If it is
2009 a function, it should expect no arguments, and should return either the
2010 next object to ask about, or @code{nil}, meaning to stop asking questions.
2012 The argument @var{prompter} specifies how to ask each question. If
2013 @var{prompter} is a string, the question text is computed like this:
2016 (format @var{prompter} @var{object})
2020 where @var{object} is the next object to ask about (as obtained from
2023 If not a string, @var{prompter} should be a function of one argument
2024 (the next object to ask about) and should return the question text. If
2025 the value is a string, that is the question to ask the user. The
2026 function can also return @code{t}, meaning do act on this object (and
2027 don't ask the user), or @code{nil}, meaning ignore this object (and don't
2030 The argument @var{actor} says how to act on the answers that the user
2031 gives. It should be a function of one argument, and it is called with
2032 each object that the user says yes for. Its argument is always an
2033 object obtained from @var{list}.
2035 If the argument @var{help} is given, it should be a list of this form:
2038 (@var{singular} @var{plural} @var{action})
2042 where @var{singular} is a string containing a singular noun that
2043 describes the objects conceptually being acted on, @var{plural} is the
2044 corresponding plural noun, and @var{action} is a transitive verb
2045 describing what @var{actor} does.
2047 If you don't specify @var{help}, the default is @code{("object"
2048 "objects" "act on")}.
2050 Each time a question is asked, the user may enter @kbd{y}, @kbd{Y}, or
2051 @key{SPC} to act on that object; @kbd{n}, @kbd{N}, or @key{DEL} to skip
2052 that object; @kbd{!} to act on all following objects; @key{ESC} or
2053 @kbd{q} to exit (skip all following objects); @kbd{.} (period) to act on
2054 the current object and then exit; or @kbd{C-h} to get help. These are
2055 the same answers that @code{query-replace} accepts. The keymap
2056 @code{query-replace-map} defines their meaning for @code{map-y-or-n-p}
2057 as well as for @code{query-replace}; see @ref{Search and Replace}.
2059 You can use @var{action-alist} to specify additional possible answers
2060 and what they mean. It is an alist of elements of the form
2061 @code{(@var{char} @var{function} @var{help})}, each of which defines one
2062 additional answer. In this element, @var{char} is a character (the
2063 answer); @var{function} is a function of one argument (an object from
2064 @var{list}); @var{help} is a string.
2066 When the user responds with @var{char}, @code{map-y-or-n-p} calls
2067 @var{function}. If it returns non-@code{nil}, the object is considered
2068 ``acted upon'', and @code{map-y-or-n-p} advances to the next object in
2069 @var{list}. If it returns @code{nil}, the prompt is repeated for the
2072 Normally, @code{map-y-or-n-p} binds @code{cursor-in-echo-area} while
2073 prompting. But if @var{no-cursor-in-echo-area} is non-@code{nil}, it
2076 If @code{map-y-or-n-p} is called in a command that was invoked using the
2077 mouse---more precisely, if @code{last-nonmenu-event} (@pxref{Command
2078 Loop Info}) is either @code{nil} or a list---then it uses a dialog box
2079 or pop-up menu to ask the question. In this case, it does not use
2080 keyboard input or the echo area. You can force use either of the mouse or
2081 of keyboard input by binding @code{last-nonmenu-event} to a suitable
2082 value around the call.
2084 The return value of @code{map-y-or-n-p} is the number of objects acted on.
2086 @c FIXME An example of this would be more useful than all the
2087 @c preceding examples of simple things.
2089 @node Reading a Password
2090 @section Reading a Password
2091 @cindex passwords, reading
2093 To read a password to pass to another program, you can use the
2094 function @code{read-passwd}.
2096 @defun read-passwd prompt &optional confirm default
2097 This function reads a password, prompting with @var{prompt}. It does
2098 not echo the password as the user types it; instead, it echoes @samp{.}
2099 for each character in the password.
2101 The optional argument @var{confirm}, if non-@code{nil}, says to read the
2102 password twice and insist it must be the same both times. If it isn't
2103 the same, the user has to type it over and over until the last two
2106 The optional argument @var{default} specifies the default password to
2107 return if the user enters empty input. If @var{default} is @code{nil},
2108 then @code{read-passwd} returns the null string in that case.
2111 @node Minibuffer Commands
2112 @section Minibuffer Commands
2114 This section describes some commands meant for use in the
2117 @deffn Command exit-minibuffer
2118 This command exits the active minibuffer. It is normally bound to
2119 keys in minibuffer local keymaps.
2122 @deffn Command self-insert-and-exit
2123 This command exits the active minibuffer after inserting the last
2124 character typed on the keyboard (found in @code{last-command-event};
2125 @pxref{Command Loop Info}).
2128 @deffn Command previous-history-element n
2129 This command replaces the minibuffer contents with the value of the
2130 @var{n}th previous (older) history element.
2133 @deffn Command next-history-element n
2134 This command replaces the minibuffer contents with the value of the
2135 @var{n}th more recent history element.
2138 @deffn Command previous-matching-history-element pattern n
2139 This command replaces the minibuffer contents with the value of the
2140 @var{n}th previous (older) history element that matches @var{pattern} (a
2141 regular expression).
2144 @deffn Command next-matching-history-element pattern n
2145 This command replaces the minibuffer contents with the value of the
2146 @var{n}th next (newer) history element that matches @var{pattern} (a
2147 regular expression).
2150 @deffn Command previous-complete-history-element n
2151 This command replaces the minibuffer contents with the value of the
2152 @var{n}th previous (older) history element that completes the current
2153 contents of the minibuffer before the point.
2156 @deffn Command next-complete-history-element n
2157 This command replaces the minibuffer contents with the value of the
2158 @var{n}th next (newer) history element that completes the current
2159 contents of the minibuffer before the point.
2163 @node Minibuffer Windows
2164 @section Minibuffer Windows
2165 @cindex minibuffer windows
2167 These functions access and select minibuffer windows
2168 and test whether they are active.
2170 @defun active-minibuffer-window
2171 This function returns the currently active minibuffer window, or
2172 @code{nil} if there is none.
2175 @defun minibuffer-window &optional frame
2176 @anchor{Definition of minibuffer-window}
2177 This function returns the minibuffer window used for frame @var{frame}.
2178 If @var{frame} is @code{nil}, that stands for the current frame. Note
2179 that the minibuffer window used by a frame need not be part of that
2180 frame---a frame that has no minibuffer of its own necessarily uses some
2181 other frame's minibuffer window.
2184 @defun set-minibuffer-window window
2185 This function specifies @var{window} as the minibuffer window to use.
2186 This affects where the minibuffer is displayed if you put text in it
2187 without invoking the usual minibuffer commands. It has no effect on
2188 the usual minibuffer input functions because they all start by
2189 choosing the minibuffer window according to the current frame.
2193 @defun window-minibuffer-p &optional window
2194 This function returns non-@code{nil} if @var{window} is a minibuffer
2196 @var{window} defaults to the selected window.
2199 It is not correct to determine whether a given window is a minibuffer by
2200 comparing it with the result of @code{(minibuffer-window)}, because
2201 there can be more than one minibuffer window if there is more than one
2204 @defun minibuffer-window-active-p window
2205 This function returns non-@code{nil} if @var{window} is the currently
2206 active minibuffer window.
2209 @node Minibuffer Contents
2210 @section Minibuffer Contents
2212 These functions access the minibuffer prompt and contents.
2214 @defun minibuffer-prompt
2215 This function returns the prompt string of the currently active
2216 minibuffer. If no minibuffer is active, it returns @code{nil}.
2219 @defun minibuffer-prompt-end
2220 This function returns the current
2221 position of the end of the minibuffer prompt, if a minibuffer is
2222 current. Otherwise, it returns the minimum valid buffer position.
2225 @defun minibuffer-prompt-width
2226 This function returns the current display-width of the minibuffer
2227 prompt, if a minibuffer is current. Otherwise, it returns zero.
2230 @defun minibuffer-contents
2231 This function returns the editable
2232 contents of the minibuffer (that is, everything except the prompt) as
2233 a string, if a minibuffer is current. Otherwise, it returns the
2234 entire contents of the current buffer.
2237 @defun minibuffer-contents-no-properties
2238 This is like @code{minibuffer-contents}, except that it does not copy text
2239 properties, just the characters themselves. @xref{Text Properties}.
2242 @defun minibuffer-completion-contents
2243 This is like @code{minibuffer-contents}, except that it returns only
2244 the contents before point. That is the part that completion commands
2245 operate on. @xref{Minibuffer Completion}.
2248 @defun delete-minibuffer-contents
2249 This function erases the editable contents of the minibuffer (that is,
2250 everything except the prompt), if a minibuffer is current. Otherwise,
2251 it erases the entire current buffer.
2254 @node Recursive Mini
2255 @section Recursive Minibuffers
2256 @cindex recursive minibuffers
2258 These functions and variables deal with recursive minibuffers
2259 (@pxref{Recursive Editing}):
2261 @defun minibuffer-depth
2262 This function returns the current depth of activations of the
2263 minibuffer, a nonnegative integer. If no minibuffers are active, it
2267 @defopt enable-recursive-minibuffers
2268 If this variable is non-@code{nil}, you can invoke commands (such as
2269 @code{find-file}) that use minibuffers even while the minibuffer window
2270 is active. Such invocation produces a recursive editing level for a new
2271 minibuffer. The outer-level minibuffer is invisible while you are
2272 editing the inner one.
2274 If this variable is @code{nil}, you cannot invoke minibuffer
2275 commands when the minibuffer window is active, not even if you switch to
2276 another window to do it.
2280 If a command name has a property @code{enable-recursive-minibuffers}
2281 that is non-@code{nil}, then the command can use the minibuffer to read
2282 arguments even if it is invoked from the minibuffer. A command can
2283 also achieve this by binding @code{enable-recursive-minibuffers}
2284 to @code{t} in the interactive declaration (@pxref{Using Interactive}).
2285 The minibuffer command @code{next-matching-history-element} (normally
2286 @kbd{M-s} in the minibuffer) does the latter.
2288 @node Minibuffer Misc
2289 @section Minibuffer Miscellany
2291 @defun minibufferp &optional buffer-or-name
2292 This function returns non-@code{nil} if @var{buffer-or-name} is a
2293 minibuffer. If @var{buffer-or-name} is omitted, it tests the current
2297 @defvar minibuffer-setup-hook
2298 This is a normal hook that is run whenever the minibuffer is entered.
2302 @defvar minibuffer-exit-hook
2303 This is a normal hook that is run whenever the minibuffer is exited.
2307 @defvar minibuffer-help-form
2308 @anchor{Definition of minibuffer-help-form}
2309 The current value of this variable is used to rebind @code{help-form}
2310 locally inside the minibuffer (@pxref{Help Functions}).
2313 @defvar minibuffer-scroll-window
2314 @anchor{Definition of minibuffer-scroll-window}
2315 If the value of this variable is non-@code{nil}, it should be a window
2316 object. When the function @code{scroll-other-window} is called in the
2317 minibuffer, it scrolls this window.
2320 @defun minibuffer-selected-window
2321 This function returns the window that was selected when the
2322 minibuffer was entered. If selected window is not a minibuffer
2323 window, it returns @code{nil}.
2326 @defopt max-mini-window-height
2327 This variable specifies the maximum height for resizing minibuffer
2328 windows. If a float, it specifies a fraction of the height of the
2329 frame. If an integer, it specifies a number of lines.
2332 @vindex minibuffer-message-timeout
2333 @defun minibuffer-message string &rest args
2334 This function displays @var{string} temporarily at the end of the
2335 minibuffer text, for a few seconds, or until the next input event
2336 arrives, whichever comes first. The variable
2337 @code{minibuffer-message-timeout} specifies the number of seconds to
2338 wait in the absence of input. It defaults to 2. If @var{args} is
2339 non-@code{nil}, the actual message is obtained by passing @var{string}
2340 and @var{args} through @code{format}. @xref{Formatting Strings}.
2343 @deffn Command minibuffer-inactive-mode
2344 This is the major mode used in inactive minibuffers. It uses
2345 keymap @code{minibuffer-inactive-mode-map}. This can be useful
2346 if the minibuffer is in a separate frame. @xref{Minibuffers and Frames}.