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 Contents:: How such commands access the minibuffer text.
34 * Minibuffer Windows:: Operating on the special minibuffer windows.
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 The minibuffer's window is normally a single line; it grows
62 automatically if the contents require more space. You can explicitly
63 @c FIXME? Works in 23.4, not 24.0.95. (Bug#11276)
64 resize it temporarily with the window sizing commands; it reverts to
65 its normal size when the minibuffer is exited. You can resize it
66 @c FIXME? Doesn't work in any version of Emacs?
67 permanently by using the window sizing commands in the frame's other
68 window, when the minibuffer is not active. If the frame contains just
69 a minibuffer, you can change the minibuffer's size by changing the
72 Use of the minibuffer reads input events, and that alters the values
73 of variables such as @code{this-command} and @code{last-command}
74 (@pxref{Command Loop Info}). Your program should bind them around the
75 code that uses the minibuffer, if you do not want that to change them.
77 Under some circumstances, a command can use a minibuffer even if
78 there is an active minibuffer; such a minibuffer is called a
79 @dfn{recursive minibuffer}. The first minibuffer is named
80 @w{@samp{ *Minibuf-1*}}. Recursive minibuffers are named by
81 incrementing the number at the end of the name. (The names begin with
82 a space so that they won't show up in normal buffer lists.) Of
83 several recursive minibuffers, the innermost (or most recently
84 entered) is the active minibuffer. We usually call this ``the''
85 minibuffer. You can permit or forbid recursive minibuffers by setting
86 the variable @code{enable-recursive-minibuffers}, or by putting
87 properties of that name on command symbols (@xref{Recursive Mini}.)
89 Like other buffers, a minibuffer uses a local keymap
90 (@pxref{Keymaps}) to specify special key bindings. The function that
91 invokes the minibuffer also sets up its local map according to the job
92 to be done. @xref{Text from Minibuffer}, for the non-completion
93 minibuffer local maps. @xref{Completion Commands}, for the minibuffer
94 local maps for completion.
96 @findex minibuffer-inactive-mode
97 @vindex minibuffer-inactive-mode-map
98 @cindex inactive minibuffer
99 When a minibuffer is inactive, it's major mode is
100 @code{minibuffer-inactive-mode}, with keymap
101 @code{minibuffer-inactive-mode-map}. This is only really useful if
102 the minibuffer is in a separate frame. @xref{Minibuffers and Frames}.
104 When Emacs is running in batch mode, any request to read from the
105 minibuffer actually reads a line from the standard input descriptor that
106 was supplied when Emacs was started.
108 @node Text from Minibuffer
109 @section Reading Text Strings with the Minibuffer
111 The most basic primitive for minibuffer input is
112 @code{read-from-minibuffer}, which can be used to read either a string
113 or a Lisp object in textual form. The function @code{read-regexp} is
114 used for reading regular expressions (@pxref{Regular Expressions}),
115 which are a special kind of string. There are also specialized
116 functions for reading commands, variables, file names, etc.@:
117 (@pxref{Completion}).
119 In most cases, you should not call minibuffer input functions in the
120 middle of a Lisp function. Instead, do all minibuffer input as part of
121 reading the arguments for a command, in the @code{interactive}
122 specification. @xref{Defining Commands}.
124 @defun read-from-minibuffer prompt &optional initial keymap read history default inherit-input-method
125 This function is the most general way to get input from the
126 minibuffer. By default, it accepts arbitrary text and returns it as a
127 string; however, if @var{read} is non-@code{nil}, then it uses
128 @code{read} to convert the text into a Lisp object (@pxref{Input
131 The first thing this function does is to activate a minibuffer and
132 display it with @var{prompt} (which must be a string) as the
133 prompt. Then the user can edit text in the minibuffer.
135 When the user types a command to exit the minibuffer,
136 @code{read-from-minibuffer} constructs the return value from the text in
137 the minibuffer. Normally it returns a string containing that text.
138 However, if @var{read} is non-@code{nil}, @code{read-from-minibuffer}
139 reads the text and returns the resulting Lisp object, unevaluated.
140 (@xref{Input Functions}, for information about reading.)
142 The argument @var{default} specifies default values to make available
143 through the history commands. It should be a string, a list of
144 strings, or @code{nil}. The string or strings become the minibuffer's
145 ``future history'', available to the user with @kbd{M-n}.
147 If @var{read} is non-@code{nil}, then @var{default} is also used
148 as the input to @code{read}, if the user enters empty input.
149 If @var{default} is a list of strings, the first string is used as the input.
150 If @var{default} is @code{nil}, empty input results in an @code{end-of-file} error.
151 However, in the usual case (where @var{read} is @code{nil}),
152 @code{read-from-minibuffer} ignores @var{default} when the user enters
153 empty input and returns an empty string, @code{""}. In this respect,
154 it differs from all the other minibuffer input functions in this chapter.
156 If @var{keymap} is non-@code{nil}, that keymap is the local keymap to
157 use in the minibuffer. If @var{keymap} is omitted or @code{nil}, the
158 value of @code{minibuffer-local-map} is used as the keymap. Specifying
159 a keymap is the most important way to customize the minibuffer for
160 various applications such as completion.
162 The argument @var{history} specifies a history list variable to use
163 for saving the input and for history commands used in the minibuffer.
164 It defaults to @code{minibuffer-history}. You can optionally specify
165 a starting position in the history list as well. @xref{Minibuffer History}.
167 If the variable @code{minibuffer-allow-text-properties} is
168 non-@code{nil}, then the string that is returned includes whatever text
169 properties were present in the minibuffer. Otherwise all the text
170 properties are stripped when the value is returned.
172 If the argument @var{inherit-input-method} is non-@code{nil}, then the
173 minibuffer inherits the current input method (@pxref{Input Methods}) and
174 the setting of @code{enable-multibyte-characters} (@pxref{Text
175 Representations}) from whichever buffer was current before entering the
178 Use of @var{initial} is mostly deprecated; we recommend using
179 a non-@code{nil} value only in conjunction with specifying a cons cell
180 for @var{history}. @xref{Initial Input}.
183 @defun read-string prompt &optional initial history default inherit-input-method
184 This function reads a string from the minibuffer and returns it. The
185 arguments @var{prompt}, @var{initial}, @var{history} and
186 @var{inherit-input-method} are used as in @code{read-from-minibuffer}.
187 The keymap used is @code{minibuffer-local-map}.
189 The optional argument @var{default} is used as in
190 @code{read-from-minibuffer}, except that, if non-@code{nil}, it also
191 specifies a default value to return if the user enters null input. As
192 in @code{read-from-minibuffer} it should be a string, a list of
193 strings, or @code{nil}, which is equivalent to an empty string. When
194 @var{default} is a string, that string is the default value. When it
195 is a list of strings, the first string is the default value. (All
196 these strings are available to the user in the ``future minibuffer
199 This function works by calling the
200 @code{read-from-minibuffer} function:
204 (read-string @var{prompt} @var{initial} @var{history} @var{default} @var{inherit})
207 (read-from-minibuffer @var{prompt} @var{initial} nil nil
208 @var{history} @var{default} @var{inherit})))
209 (if (and (equal value "") @var{default})
210 (if (consp @var{default}) (car @var{default}) @var{default})
216 @defun read-regexp prompt &optional default
217 This function reads a regular expression as a string from the
218 minibuffer and returns it. The argument @var{prompt} is used as in
219 @code{read-from-minibuffer}. The keymap used is
220 @code{minibuffer-local-map}, and @code{regexp-history} is used as the
221 history list (@pxref{Minibuffer History, regexp-history}).
223 The optional argument @var{default} specifies a default value to
224 return if the user enters null input; it should be a string, or
225 @code{nil}, which is equivalent to an empty string.
227 In addition, @code{read-regexp} collects a few useful candidates for
228 input and passes them to @code{read-from-minibuffer}, to make them
229 available to the user as the ``future minibuffer history list''
230 (@pxref{Minibuffer History, future list,, emacs, The GNU Emacs
231 Manual}). These candidates are:
235 The word or symbol at point.
237 The last regexp used in an incremental search.
239 The last string used in an incremental search.
241 The last string or pattern used in query-replace commands.
244 This function works by calling the @code{read-from-minibuffer}
245 function, after computing the list of defaults as described above.
248 @defvar minibuffer-allow-text-properties
249 If this variable is @code{nil}, then @code{read-from-minibuffer}
250 and @code{read-string} strip all text properties from the minibuffer
251 input before returning it. However,
252 @code{read-no-blanks-input} (see below), as well as
253 @code{read-minibuffer} and related functions (@pxref{Object from
254 Minibuffer,, Reading Lisp Objects With the Minibuffer}), and all
255 functions that do minibuffer input with completion, discard text
256 properties unconditionally, regardless of the value of this variable.
259 @defvar minibuffer-local-map
261 @anchor{Definition of minibuffer-local-map}
262 @c avoid page break at anchor; work around Texinfo deficiency
263 is the default local keymap for reading from the minibuffer. By
264 default, it makes the following bindings:
268 @code{exit-minibuffer}
271 @code{exit-minibuffer}
274 @code{abort-recursive-edit}
278 @code{next-history-element}
282 @code{previous-history-element}
285 @code{next-matching-history-element}
288 @code{previous-matching-history-element}
291 @c Does not seem worth/appropriate mentioning.
292 @item @kbd{C-@key{TAB}}
293 @code{file-cache-minibuffer-complete}
298 @c In version 18, initial is required
300 @defun read-no-blanks-input prompt &optional initial inherit-input-method
301 This function reads a string from the minibuffer, but does not allow
302 whitespace characters as part of the input: instead, those characters
303 terminate the input. The arguments @var{prompt}, @var{initial}, and
304 @var{inherit-input-method} are used as in @code{read-from-minibuffer}.
306 This is a simplified interface to the @code{read-from-minibuffer}
307 function, and passes the value of the @code{minibuffer-local-ns-map}
308 keymap as the @var{keymap} argument for that function. Since the keymap
309 @code{minibuffer-local-ns-map} does not rebind @kbd{C-q}, it @emph{is}
310 possible to put a space into the string, by quoting it.
312 This function discards text properties, regardless of the value of
313 @code{minibuffer-allow-text-properties}.
317 (read-no-blanks-input @var{prompt} @var{initial})
319 (let (minibuffer-allow-text-properties)
320 (read-from-minibuffer @var{prompt} @var{initial} minibuffer-local-ns-map))
325 @c Slightly unfortunate name, suggesting it might be related to the
327 @defvar minibuffer-local-ns-map
328 This built-in variable is the keymap used as the minibuffer local keymap
329 in the function @code{read-no-blanks-input}. By default, it makes the
330 following bindings, in addition to those of @code{minibuffer-local-map}:
334 @cindex @key{SPC} in minibuffer
335 @code{exit-minibuffer}
338 @cindex @key{TAB} in minibuffer
339 @code{exit-minibuffer}
342 @cindex @kbd{?} in minibuffer
343 @code{self-insert-and-exit}
347 @node Object from Minibuffer
348 @section Reading Lisp Objects with the Minibuffer
350 This section describes functions for reading Lisp objects with the
353 @defun read-minibuffer prompt &optional initial
354 This function reads a Lisp object using the minibuffer, and returns it
355 without evaluating it. The arguments @var{prompt} and @var{initial} are
356 used as in @code{read-from-minibuffer}.
358 This is a simplified interface to the
359 @code{read-from-minibuffer} function:
363 (read-minibuffer @var{prompt} @var{initial})
365 (let (minibuffer-allow-text-properties)
366 (read-from-minibuffer @var{prompt} @var{initial} nil t))
370 Here is an example in which we supply the string @code{"(testing)"} as
376 "Enter an expression: " (format "%s" '(testing)))
378 ;; @r{Here is how the minibuffer is displayed:}
382 ---------- Buffer: Minibuffer ----------
383 Enter an expression: (testing)@point{}
384 ---------- Buffer: Minibuffer ----------
389 The user can type @key{RET} immediately to use the initial input as a
390 default, or can edit the input.
393 @defun eval-minibuffer prompt &optional initial
394 This function reads a Lisp expression using the minibuffer, evaluates
395 it, then returns the result. The arguments @var{prompt} and
396 @var{initial} are used as in @code{read-from-minibuffer}.
398 This function simply evaluates the result of a call to
399 @code{read-minibuffer}:
403 (eval-minibuffer @var{prompt} @var{initial})
405 (eval (read-minibuffer @var{prompt} @var{initial}))
410 @defun edit-and-eval-command prompt form
411 This function reads a Lisp expression in the minibuffer, and then
412 evaluates it. The difference between this command and
413 @code{eval-minibuffer} is that here the initial @var{form} is not
414 optional and it is treated as a Lisp object to be converted to printed
415 representation rather than as a string of text. It is printed with
416 @code{prin1}, so if it is a string, double-quote characters (@samp{"})
417 appear in the initial text. @xref{Output Functions}.
419 The first thing @code{edit-and-eval-command} does is to activate the
420 minibuffer with @var{prompt} as the prompt. Then it inserts the printed
421 representation of @var{form} in the minibuffer, and lets the user edit it.
422 When the user exits the minibuffer, the edited text is read with
423 @code{read} and then evaluated. The resulting value becomes the value
424 of @code{edit-and-eval-command}.
426 In the following example, we offer the user an expression with initial
427 text which is a valid form already:
431 (edit-and-eval-command "Please edit: " '(forward-word 1))
433 ;; @r{After evaluation of the preceding expression,}
434 ;; @r{the following appears in the minibuffer:}
438 ---------- Buffer: Minibuffer ----------
439 Please edit: (forward-word 1)@point{}
440 ---------- Buffer: Minibuffer ----------
445 Typing @key{RET} right away would exit the minibuffer and evaluate the
446 expression, thus moving point forward one word.
447 @code{edit-and-eval-command} returns @code{nil} in this example.
450 @node Minibuffer History
451 @section Minibuffer History
452 @cindex minibuffer history
455 A @dfn{minibuffer history list} records previous minibuffer inputs
456 so the user can reuse them conveniently. It is a variable whose value
457 is a list of strings (previous inputs), most recent first.
459 There are many separate minibuffer history lists, used for different
460 kinds of inputs. It's the Lisp programmer's job to specify the right
461 history list for each use of the minibuffer.
463 You specify a minibuffer history list with the optional @var{history}
464 argument to @code{read-from-minibuffer} or @code{completing-read}.
465 Here are the possible values for it:
469 Use @var{variable} (a symbol) as the history list.
471 @item (@var{variable} . @var{startpos})
472 Use @var{variable} (a symbol) as the history list, and assume that the
473 initial history position is @var{startpos} (a nonnegative integer).
475 Specifying 0 for @var{startpos} is equivalent to just specifying the
476 symbol @var{variable}. @code{previous-history-element} will display
477 the most recent element of the history list in the minibuffer. If you
478 specify a positive @var{startpos}, the minibuffer history functions
479 behave as if @code{(elt @var{variable} (1- @var{startpos}))} were the
480 history element currently shown in the minibuffer.
482 For consistency, you should also specify that element of the history
483 as the initial minibuffer contents, using the @var{initial} argument
484 to the minibuffer input function (@pxref{Initial Input}).
487 If you don't specify @var{history}, then the default history list
488 @code{minibuffer-history} is used. For other standard history lists,
489 see below. You can also create your own history list variable; just
490 initialize it to @code{nil} before the first use.
492 Both @code{read-from-minibuffer} and @code{completing-read} add new
493 elements to the history list automatically, and provide commands to
494 allow the user to reuse items on the list. The only thing your program
495 needs to do to use a history list is to initialize it and to pass its
496 name to the input functions when you wish. But it is safe to modify the
497 list by hand when the minibuffer input functions are not using it.
499 Emacs functions that add a new element to a history list can also
500 delete old elements if the list gets too long. The variable
501 @code{history-length} specifies the maximum length for most history
502 lists. To specify a different maximum length for a particular history
503 list, put the length in the @code{history-length} property of the
504 history list symbol. The variable @code{history-delete-duplicates}
505 specifies whether to delete duplicates in history.
507 @defun add-to-history history-var newelt &optional maxelt keep-all
508 This function adds a new element @var{newelt}, if it isn't the empty
509 string, to the history list stored in the variable @var{history-var},
510 and returns the updated history list. It limits the list length to
511 the value of @var{maxelt} (if non-@code{nil}) or @code{history-length}
512 (described below). The possible values of @var{maxelt} have the same
513 meaning as the values of @code{history-length}.
515 Normally, @code{add-to-history} removes duplicate members from the
516 history list if @code{history-delete-duplicates} is non-@code{nil}.
517 However, if @var{keep-all} is non-@code{nil}, that says not to remove
518 duplicates, and to add @var{newelt} to the list even if it is empty.
521 @defvar history-add-new-input
522 If the value of this variable is @code{nil}, standard functions that
523 read from the minibuffer don't add new elements to the history list.
524 This lets Lisp programs explicitly manage input history by using
525 @code{add-to-history}. By default, @code{history-add-new-input} is
526 set to a non-@code{nil} value.
529 @defopt history-length
530 The value of this variable specifies the maximum length for all
531 history lists that don't specify their own maximum lengths. If the
532 value is @code{t}, that means there is no maximum (don't delete old
533 elements). The value of @code{history-length} property of the history
534 list variable's symbol, if set, overrides this variable for that
535 particular history list.
538 @defopt history-delete-duplicates
539 If the value of this variable is @code{t}, that means when adding a
540 new history element, all previous identical elements are deleted.
543 Here are some of the standard minibuffer history list variables:
545 @defvar minibuffer-history
546 The default history list for minibuffer history input.
549 @defvar query-replace-history
550 A history list for arguments to @code{query-replace} (and similar
551 arguments to other commands).
554 @defvar file-name-history
555 A history list for file-name arguments.
558 @defvar buffer-name-history
559 A history list for buffer-name arguments.
562 @defvar regexp-history
563 A history list for regular expression arguments.
566 @defvar extended-command-history
567 A history list for arguments that are names of extended commands.
570 @defvar shell-command-history
571 A history list for arguments that are shell commands.
574 @defvar read-expression-history
575 A history list for arguments that are Lisp expressions to evaluate.
579 @section Initial Input
581 Several of the functions for minibuffer input have an argument called
582 @var{initial}. This is a mostly-deprecated
583 feature for specifying that the minibuffer should start out with
584 certain text, instead of empty as usual.
586 If @var{initial} is a string, the minibuffer starts out containing the
587 text of the string, with point at the end, when the user starts to
588 edit the text. If the user simply types @key{RET} to exit the
589 minibuffer, it will use the initial input string to determine the
592 @strong{We discourage use of a non-@code{nil} value for
593 @var{initial}}, because initial input is an intrusive interface.
594 History lists and default values provide a much more convenient method
595 to offer useful default inputs to the user.
597 There is just one situation where you should specify a string for an
598 @var{initial} argument. This is when you specify a cons cell for the
599 @var{history} argument. @xref{Minibuffer History}.
601 @var{initial} can also be a cons cell of the form @code{(@var{string}
602 . @var{position})}. This means to insert @var{string} in the
603 minibuffer but put point at @var{position} within the string's text.
605 As a historical accident, @var{position} was implemented
606 inconsistently in different functions. In @code{completing-read},
607 @var{position}'s value is interpreted as origin-zero; that is, a value
608 of 0 means the beginning of the string, 1 means after the first
609 character, etc. In @code{read-minibuffer}, and the other
610 non-completion minibuffer input functions that support this argument,
611 1 means the beginning of the string 2 means after the first character,
614 Use of a cons cell as the value for @var{initial} arguments is
615 deprecated in user code.
621 @dfn{Completion} is a feature that fills in the rest of a name
622 starting from an abbreviation for it. Completion works by comparing the
623 user's input against a list of valid names and determining how much of
624 the name is determined uniquely by what the user has typed. For
625 example, when you type @kbd{C-x b} (@code{switch-to-buffer}) and then
626 type the first few letters of the name of the buffer to which you wish
627 to switch, and then type @key{TAB} (@code{minibuffer-complete}), Emacs
628 extends the name as far as it can.
630 Standard Emacs commands offer completion for names of symbols, files,
631 buffers, and processes; with the functions in this section, you can
632 implement completion for other kinds of names.
634 The @code{try-completion} function is the basic primitive for
635 completion: it returns the longest determined completion of a given
636 initial string, with a given set of strings to match against.
638 The function @code{completing-read} provides a higher-level interface
639 for completion. A call to @code{completing-read} specifies how to
640 determine the list of valid names. The function then activates the
641 minibuffer with a local keymap that binds a few keys to commands useful
642 for completion. Other functions provide convenient simple interfaces
643 for reading certain kinds of names with completion.
646 * Basic Completion:: Low-level functions for completing strings.
647 * Minibuffer Completion:: Invoking the minibuffer with completion.
648 * Completion Commands:: Minibuffer commands that do completion.
649 * High-Level Completion:: Convenient special cases of completion
650 (reading buffer name, file name, etc.).
651 * Reading File Names:: Using completion to read file names and
653 * Completion Variables:: Variables controlling completion behavior.
654 * Programmed Completion:: Writing your own completion function.
655 * Completion in Buffers:: Completing text in ordinary buffers.
658 @node Basic Completion
659 @subsection Basic Completion Functions
661 The following completion functions have nothing in themselves to do
662 with minibuffers. We describe them here to keep them near the
663 higher-level completion features that do use the minibuffer.
665 @defun try-completion string collection &optional predicate
666 This function returns the longest common substring of all possible
667 completions of @var{string} in @var{collection}.
669 @cindex completion table
670 The @var{collection} argument is called the @dfn{completion table}.
671 Its value must be a list of strings, an alist whose keys are strings
672 or symbols, an obarray, a hash table, or a completion function.
674 Completion compares @var{string} against each of the permissible
675 completions specified by @var{collection}. If no permissible
676 completions match, @code{try-completion} returns @code{nil}. If there
677 is just one matching completion, and the match is exact, it returns
678 @code{t}. Otherwise, it returns the longest initial sequence common
679 to all possible matching completions.
681 If @var{collection} is an alist (@pxref{Association Lists}), the
682 permissible completions are the elements of the alist that are either
683 strings, or conses whose @sc{car} is a string or symbol.
684 Symbols are converted to strings using @code{symbol-name}. Other
685 elements of the alist are ignored. (Remember that in Emacs Lisp, the
686 elements of alists do not @emph{have} to be conses.) In particular, a
687 list of strings is allowed, even though we usually do not
688 think of such lists as alists.
690 @cindex obarray in completion
691 If @var{collection} is an obarray (@pxref{Creating Symbols}), the names
692 of all symbols in the obarray form the set of permissible completions. The
693 global variable @code{obarray} holds an obarray containing the names of
694 all interned Lisp symbols.
696 Note that the only valid way to make a new obarray is to create it
697 empty and then add symbols to it one by one using @code{intern}.
698 Also, you cannot intern a given symbol in more than one obarray.
700 If @var{collection} is a hash table, then the keys that are strings
701 are the possible completions. Other keys are ignored.
703 You can also use a function as @var{collection}. Then the function is
704 solely responsible for performing completion; @code{try-completion}
705 returns whatever this function returns. The function is called with
706 three arguments: @var{string}, @var{predicate} and @code{nil} (the
707 reason for the third argument is so that the same function can be used
708 in @code{all-completions} and do the appropriate thing in either
709 case). @xref{Programmed Completion}.
711 If the argument @var{predicate} is non-@code{nil}, then it must be a
712 function of one argument, unless @var{collection} is a hash table, in
713 which case it should be a function of two arguments. It is used to
714 test each possible match, and the match is accepted only if
715 @var{predicate} returns non-@code{nil}. The argument given to
716 @var{predicate} is either a string or a cons cell (the @sc{car} of
717 which is a string) from the alist, or a symbol (@emph{not} a symbol
718 name) from the obarray. If @var{collection} is a hash table,
719 @var{predicate} is called with two arguments, the string key and the
722 In addition, to be acceptable, a completion must also match all the
723 regular expressions in @code{completion-regexp-list}. (Unless
724 @var{collection} is a function, in which case that function has to
725 handle @code{completion-regexp-list} itself.)
727 In the first of the following examples, the string @samp{foo} is
728 matched by three of the alist @sc{car}s. All of the matches begin with
729 the characters @samp{fooba}, so that is the result. In the second
730 example, there is only one possible match, and it is exact, so the value
737 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)))
742 (try-completion "foo" '(("barfoo" 2) ("foo" 3)))
747 In the following example, numerous symbols begin with the characters
748 @samp{forw}, and all of them begin with the word @samp{forward}. In
749 most of the symbols, this is followed with a @samp{-}, but not in all,
750 so no more than @samp{forward} can be completed.
754 (try-completion "forw" obarray)
759 Finally, in the following example, only two of the three possible
760 matches pass the predicate @code{test} (the string @samp{foobaz} is
761 too short). Both of those begin with the string @samp{foobar}.
766 (> (length (car s)) 6))
772 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
779 @defun all-completions string collection &optional predicate nospace
780 This function returns a list of all possible completions of
781 @var{string}. The arguments to this function (aside from
782 @var{nospace}) are the same as those of @code{try-completion}. Also,
783 this function uses @code{completion-regexp-list} in the same way that
784 @code{try-completion} does.
786 The optional argument @var{nospace} is obsolete. If it is
787 non-@code{nil}, completions that start with a space are ignored unless
788 @var{string} starts with a space.
790 If @var{collection} is a function, it is called with three arguments:
791 @var{string}, @var{predicate} and @code{t}; then @code{all-completions}
792 returns whatever the function returns. @xref{Programmed Completion}.
794 Here is an example, using the function @code{test} shown in the
795 example for @code{try-completion}:
800 (> (length (car s)) 6))
807 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
809 @result{} ("foobar1" "foobar2")
814 @defun test-completion string collection &optional predicate
815 @anchor{Definition of test-completion}
816 This function returns non-@code{nil} if @var{string} is a valid
817 completion alternative specified by @var{collection} and
818 @var{predicate}. The arguments are the same as in
819 @code{try-completion}. For instance, if @var{collection} is a list of
820 strings, this is true if @var{string} appears in the list and
821 @var{predicate} is satisfied.
823 This function uses @code{completion-regexp-list} in the same
824 way that @code{try-completion} does.
826 If @var{predicate} is non-@code{nil} and if @var{collection} contains
827 several strings that are equal to each other, as determined by
828 @code{compare-strings} according to @code{completion-ignore-case},
829 then @var{predicate} should accept either all or none of them.
830 Otherwise, the return value of @code{test-completion} is essentially
833 If @var{collection} is a function, it is called with three arguments,
834 the values @var{string}, @var{predicate} and @code{lambda}; whatever
835 it returns, @code{test-completion} returns in turn.
838 @defun completion-boundaries string collection predicate suffix
839 This function returns the boundaries of the field on which @var{collection}
840 will operate, assuming that @var{string} holds the text before point
841 and @var{suffix} holds the text after point.
843 Normally completion operates on the whole string, so for all normal
844 collections, this will always return @code{(0 . (length
845 @var{suffix}))}. But more complex completion such as completion on
846 files is done one field at a time. For example, completion of
847 @code{"/usr/sh"} will include @code{"/usr/share/"} but not
848 @code{"/usr/share/doc"} even if @code{"/usr/share/doc"} exists.
849 Also @code{all-completions} on @code{"/usr/sh"} will not include
850 @code{"/usr/share/"} but only @code{"share/"}. So if @var{string} is
851 @code{"/usr/sh"} and @var{suffix} is @code{"e/doc"},
852 @code{completion-boundaries} will return @code{(5 . 1)} which tells us
853 that the @var{collection} will only return completion information that
854 pertains to the area after @code{"/usr/"} and before @code{"/doc"}.
857 If you store a completion alist in a variable, you should mark the
858 variable as ``risky'' with a non-@code{nil}
859 @code{risky-local-variable} property. @xref{File Local Variables}.
861 @defvar completion-ignore-case
862 If the value of this variable is non-@code{nil}, case is not
863 considered significant in completion. Within @code{read-file-name},
864 this variable is overridden by
865 @code{read-file-name-completion-ignore-case} (@pxref{Reading File
866 Names}); within @code{read-buffer}, it is overridden by
867 @code{read-buffer-completion-ignore-case} (@pxref{High-Level
871 @defvar completion-regexp-list
872 This is a list of regular expressions. The completion functions only
873 consider a completion acceptable if it matches all regular expressions
874 in this list, with @code{case-fold-search} (@pxref{Searching and Case})
875 bound to the value of @code{completion-ignore-case}.
878 @defmac lazy-completion-table var fun
879 This macro provides a way to initialize the variable @var{var} as a
880 collection for completion in a lazy way, not computing its actual
881 contents until they are first needed. You use this macro to produce a
882 value that you store in @var{var}. The actual computation of the
883 proper value is done the first time you do completion using @var{var}.
884 It is done by calling @var{fun} with no arguments. The
885 value @var{fun} returns becomes the permanent value of @var{var}.
887 Here is a usage example:
890 (defvar foo (lazy-completion-table foo make-my-alist))
894 @node Minibuffer Completion
895 @subsection Completion and the Minibuffer
896 @cindex minibuffer completion
897 @cindex reading from minibuffer with completion
899 This section describes the basic interface for reading from the
900 minibuffer with completion.
902 @defun completing-read prompt collection &optional predicate require-match initial history default inherit-input-method
903 This function reads a string in the minibuffer, assisting the user by
904 providing completion. It activates the minibuffer with prompt
905 @var{prompt}, which must be a string.
907 The actual completion is done by passing the completion table
908 @var{collection} and the completion predicate @var{predicate} to the
909 function @code{try-completion} (@pxref{Basic Completion}). This
910 happens in certain commands bound in the local keymaps used for
911 completion. Some of these commands also call @code{test-completion}.
912 Thus, if @var{predicate} is non-@code{nil}, it should be compatible
913 with @var{collection} and @code{completion-ignore-case}.
914 @xref{Definition of test-completion}.
916 The value of the optional argument @var{require-match} determines how
917 the user may exit the minibuffer:
921 If @code{nil}, the usual minibuffer exit commands work regardless of
922 the input in the minibuffer.
925 If @code{t}, the usual minibuffer exit commands won't exit unless the
926 input completes to an element of @var{collection}.
929 If @code{confirm}, the user can exit with any input, but is asked for
930 confirmation if the input is not an element of @var{collection}.
933 If @code{confirm-after-completion}, the user can exit with any input,
934 but is asked for confirmation if the preceding command was a
935 completion command (i.e., one of the commands in
936 @code{minibuffer-confirm-exit-commands}) and the resulting input is
937 not an element of @var{collection}. @xref{Completion Commands}.
940 Any other value of @var{require-match} behaves like @code{t}, except
941 that the exit commands won't exit if it performs completion.
944 However, empty input is always permitted, regardless of the value of
945 @var{require-match}; in that case, @code{completing-read} returns the
946 first element of @var{default}, if it is a list; @code{""}, if
947 @var{default} is @code{nil}; or @var{default}. The string or strings
948 in @var{default} are also available to the user through the history
951 The function @code{completing-read} uses
952 @code{minibuffer-local-completion-map} as the keymap if
953 @var{require-match} is @code{nil}, and uses
954 @code{minibuffer-local-must-match-map} if @var{require-match} is
955 non-@code{nil}. @xref{Completion Commands}.
957 The argument @var{history} specifies which history list variable to use for
958 saving the input and for minibuffer history commands. It defaults to
959 @code{minibuffer-history}. @xref{Minibuffer History}.
961 The argument @var{initial} is mostly deprecated; we recommend using a
962 non-@code{nil} value only in conjunction with specifying a cons cell
963 for @var{history}. @xref{Initial Input}. For default input, use
964 @var{default} instead.
966 If the argument @var{inherit-input-method} is non-@code{nil}, then the
967 minibuffer inherits the current input method (@pxref{Input
968 Methods}) and the setting of @code{enable-multibyte-characters}
969 (@pxref{Text Representations}) from whichever buffer was current before
970 entering the minibuffer.
972 If the built-in variable @code{completion-ignore-case} is
973 non-@code{nil}, completion ignores case when comparing the input
974 against the possible matches. @xref{Basic Completion}. In this mode
975 of operation, @var{predicate} must also ignore case, or you will get
978 Here's an example of using @code{completing-read}:
984 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
989 ;; @r{After evaluation of the preceding expression,}
990 ;; @r{the following appears in the minibuffer:}
992 ---------- Buffer: Minibuffer ----------
993 Complete a foo: fo@point{}
994 ---------- Buffer: Minibuffer ----------
999 If the user then types @kbd{@key{DEL} @key{DEL} b @key{RET}},
1000 @code{completing-read} returns @code{barfoo}.
1002 The @code{completing-read} function binds variables to pass
1003 information to the commands that actually do completion.
1004 They are described in the following section.
1007 @defvar completing-read-function
1008 The value of this variable must be a function, which is called by
1009 @code{completing-read} to actually do its work. It should accept the
1010 same arguments as @code{completing-read}. This can be bound to a
1011 different function to completely override the normal behavior of
1012 @code{completing-read}.
1015 @node Completion Commands
1016 @subsection Minibuffer Commands that Do Completion
1018 This section describes the keymaps, commands and user options used
1019 in the minibuffer to do completion.
1021 @defvar minibuffer-completion-table
1022 The value of this variable is the completion table used for completion
1023 in the minibuffer. This is the global variable that contains what
1024 @code{completing-read} passes to @code{try-completion}. It is used by
1025 minibuffer completion commands such as
1026 @code{minibuffer-complete-word}.
1029 @defvar minibuffer-completion-predicate
1030 This variable's value is the predicate that @code{completing-read}
1031 passes to @code{try-completion}. The variable is also used by the other
1032 minibuffer completion functions.
1035 @defvar minibuffer-completion-confirm
1036 This variable determines whether Emacs asks for confirmation before
1037 exiting the minibuffer; @code{completing-read} binds this variable,
1038 and the function @code{minibuffer-complete-and-exit} checks the value
1039 before exiting. If the value is @code{nil}, confirmation is not
1040 required. If the value is @code{confirm}, the user may exit with an
1041 input that is not a valid completion alternative, but Emacs asks for
1042 confirmation. If the value is @code{confirm-after-completion}, the
1043 user may exit with an input that is not a valid completion
1044 alternative, but Emacs asks for confirmation if the user submitted the
1045 input right after any of the completion commands in
1046 @code{minibuffer-confirm-exit-commands}.
1049 @defvar minibuffer-confirm-exit-commands
1050 This variable holds a list of commands that cause Emacs to ask for
1051 confirmation before exiting the minibuffer, if the @var{require-match}
1052 argument to @code{completing-read} is @code{confirm-after-completion}.
1053 The confirmation is requested if the user attempts to exit the
1054 minibuffer immediately after calling any command in this list.
1057 @deffn Command minibuffer-complete-word
1058 This function completes the minibuffer contents by at most a single
1059 word. Even if the minibuffer contents have only one completion,
1060 @code{minibuffer-complete-word} does not add any characters beyond the
1061 first character that is not a word constituent. @xref{Syntax Tables}.
1064 @deffn Command minibuffer-complete
1065 This function completes the minibuffer contents as far as possible.
1068 @deffn Command minibuffer-complete-and-exit
1069 This function completes the minibuffer contents, and exits if
1070 confirmation is not required, i.e., if
1071 @code{minibuffer-completion-confirm} is @code{nil}. If confirmation
1072 @emph{is} required, it is given by repeating this command
1073 immediately---the command is programmed to work without confirmation
1074 when run twice in succession.
1077 @deffn Command minibuffer-completion-help
1078 This function creates a list of the possible completions of the
1079 current minibuffer contents. It works by calling @code{all-completions}
1080 using the value of the variable @code{minibuffer-completion-table} as
1081 the @var{collection} argument, and the value of
1082 @code{minibuffer-completion-predicate} as the @var{predicate} argument.
1083 The list of completions is displayed as text in a buffer named
1084 @file{*Completions*}.
1087 @defun display-completion-list completions &optional common-substring
1088 This function displays @var{completions} to the stream in
1089 @code{standard-output}, usually a buffer. (@xref{Read and Print}, for more
1090 information about streams.) The argument @var{completions} is normally
1091 a list of completions just returned by @code{all-completions}, but it
1092 does not have to be. Each element may be a symbol or a string, either
1093 of which is simply printed. It can also be a list of two strings,
1094 which is printed as if the strings were concatenated. The first of
1095 the two strings is the actual completion, the second string serves as
1098 The argument @var{common-substring} is the prefix that is common to
1099 all the completions. With normal Emacs completion, it is usually the
1100 same as the string that was completed. @code{display-completion-list}
1101 uses this to highlight text in the completion list for better visual
1102 feedback. This is not needed in the minibuffer; for minibuffer
1103 completion, you can pass @code{nil}.
1105 This function is called by @code{minibuffer-completion-help}. The
1106 most common way to use it is together with
1107 @code{with-output-to-temp-buffer}, like this:
1110 (with-output-to-temp-buffer "*Completions*"
1111 (display-completion-list
1112 (all-completions (buffer-string) my-alist)
1117 @defopt completion-auto-help
1118 If this variable is non-@code{nil}, the completion commands
1119 automatically display a list of possible completions whenever nothing
1120 can be completed because the next character is not uniquely determined.
1123 @defvar minibuffer-local-completion-map
1124 @code{completing-read} uses this value as the local keymap when an
1125 exact match of one of the completions is not required. By default, this
1126 keymap makes the following bindings:
1130 @code{minibuffer-completion-help}
1133 @code{minibuffer-complete-word}
1136 @code{minibuffer-complete}
1140 with other characters bound as in @code{minibuffer-local-map}
1141 (@pxref{Definition of minibuffer-local-map}).
1144 @defvar minibuffer-local-must-match-map
1145 @code{completing-read} uses this value as the local keymap when an
1146 exact match of one of the completions is required. Therefore, no keys
1147 are bound to @code{exit-minibuffer}, the command that exits the
1148 minibuffer unconditionally. By default, this keymap makes the following
1153 @code{minibuffer-completion-help}
1156 @code{minibuffer-complete-word}
1159 @code{minibuffer-complete}
1162 @code{minibuffer-complete-and-exit}
1165 @code{minibuffer-complete-and-exit}
1169 with other characters bound as in @code{minibuffer-local-map}.
1172 @defvar minibuffer-local-filename-completion-map
1173 This is like @code{minibuffer-local-completion-map}
1174 except that it does not bind @key{SPC}. This keymap is used by the
1175 function @code{read-file-name}.
1178 @defvar minibuffer-local-filename-must-match-map
1179 This is like @code{minibuffer-local-must-match-map}
1180 except that it does not bind @key{SPC}. This keymap is used by the
1181 function @code{read-file-name}.
1184 @node High-Level Completion
1185 @subsection High-Level Completion Functions
1187 This section describes the higher-level convenient functions for
1188 reading certain sorts of names with completion.
1190 In most cases, you should not call these functions in the middle of a
1191 Lisp function. When possible, do all minibuffer input as part of
1192 reading the arguments for a command, in the @code{interactive}
1193 specification. @xref{Defining Commands}.
1195 @defun read-buffer prompt &optional default require-match
1196 This function reads the name of a buffer and returns it as a string.
1197 The argument @var{default} is the default name to use, the value to
1198 return if the user exits with an empty minibuffer. If non-@code{nil},
1199 it should be a string, a list of strings, or a buffer. If it is
1200 a list, the default value is the first element of this list. It is
1201 mentioned in the prompt, but is not inserted in the minibuffer as
1204 The argument @var{prompt} should be a string ending with a colon and a
1205 space. If @var{default} is non-@code{nil}, the function inserts it in
1206 @var{prompt} before the colon to follow the convention for reading from
1207 the minibuffer with a default value (@pxref{Programming Tips}).
1209 The optional argument @var{require-match} has the same meaning as in
1210 @code{completing-read}. @xref{Minibuffer Completion}.
1212 In the following example, the user enters @samp{minibuffer.t}, and
1213 then types @key{RET}. The argument @var{require-match} is @code{t},
1214 and the only buffer name starting with the given input is
1215 @samp{minibuffer.texi}, so that name is the value.
1218 (read-buffer "Buffer name: " "foo" t)
1220 ;; @r{After evaluation of the preceding expression,}
1221 ;; @r{the following prompt appears,}
1222 ;; @r{with an empty minibuffer:}
1226 ---------- Buffer: Minibuffer ----------
1227 Buffer name (default foo): @point{}
1228 ---------- Buffer: Minibuffer ----------
1232 ;; @r{The user types @kbd{minibuffer.t @key{RET}}.}
1233 @result{} "minibuffer.texi"
1238 @defopt read-buffer-function
1239 This variable specifies how to read buffer names. The function is
1240 called with the arguments passed to @code{read-buffer}. For example,
1241 if you set this variable to @code{iswitchb-read-buffer}, all Emacs
1242 commands that call @code{read-buffer} to read a buffer name will
1243 actually use the @code{iswitchb} package to read it.
1246 @defopt read-buffer-completion-ignore-case
1247 If this variable is non-@code{nil}, @code{read-buffer} ignores case
1248 when performing completion.
1251 @defun read-command prompt &optional default
1252 This function reads the name of a command and returns it as a Lisp
1253 symbol. The argument @var{prompt} is used as in
1254 @code{read-from-minibuffer}. Recall that a command is anything for
1255 which @code{commandp} returns @code{t}, and a command name is a symbol
1256 for which @code{commandp} returns @code{t}. @xref{Interactive Call}.
1258 The argument @var{default} specifies what to return if the user enters
1259 null input. It can be a symbol, a string or a list of strings. If it
1260 is a string, @code{read-command} interns it before returning it.
1261 If it is a list, @code{read-command} returns the first element of this list.
1262 If @var{default} is @code{nil}, that means no default has been
1263 specified; then if the user enters null input, the return value is
1264 @code{(intern "")}, that is, a symbol whose name is an empty string.
1267 (read-command "Command name? ")
1270 ;; @r{After evaluation of the preceding expression,}
1271 ;; @r{the following prompt appears with an empty minibuffer:}
1275 ---------- Buffer: Minibuffer ----------
1277 ---------- Buffer: Minibuffer ----------
1282 If the user types @kbd{forward-c @key{RET}}, then this function returns
1283 @code{forward-char}.
1285 The @code{read-command} function is a simplified interface to
1286 @code{completing-read}. It uses the variable @code{obarray} so as to
1287 complete in the set of extant Lisp symbols, and it uses the
1288 @code{commandp} predicate so as to accept only command names:
1290 @cindex @code{commandp} example
1293 (read-command @var{prompt})
1295 (intern (completing-read @var{prompt} obarray
1301 @defun read-variable prompt &optional default
1302 @anchor{Definition of read-variable}
1303 This function reads the name of a user variable and returns it as a
1306 The argument @var{default} specifies the default value to return if
1307 the user enters null input. It can be a symbol, a string, or a list
1308 of strings. If it is a string, @code{read-variable} interns it to
1309 make the default value. If it is a list, @code{read-variable} interns
1310 the first element. If @var{default} is @code{nil}, that means no
1311 default has been specified; then if the user enters null input, the
1312 return value is @code{(intern "")}.
1316 (read-variable "Variable name? ")
1318 ;; @r{After evaluation of the preceding expression,}
1319 ;; @r{the following prompt appears,}
1320 ;; @r{with an empty minibuffer:}
1324 ---------- Buffer: Minibuffer ----------
1325 Variable name? @point{}
1326 ---------- Buffer: Minibuffer ----------
1331 If the user then types @kbd{fill-p @key{RET}}, @code{read-variable}
1332 returns @code{fill-prefix}.
1334 In general, @code{read-variable} is similar to @code{read-command},
1335 but uses the predicate @code{user-variable-p} instead of
1338 @cindex @code{user-variable-p} example
1341 (read-variable @var{prompt})
1344 (completing-read @var{prompt} obarray
1345 'user-variable-p t nil))
1350 @deffn Command read-color &optional prompt convert allow-empty display
1351 This function reads a string that is a color specification, either the
1352 color's name or an RGB hex value such as @code{#RRRGGGBBB}. It
1353 prompts with @var{prompt} (default: @code{"Color (name or #RGB triplet):"})
1354 and provides completion for color names, but not for hex RGB values.
1355 In addition to names of standard colors, completion candidates include
1356 the foreground and background colors at point.
1358 Valid RGB values are described in @ref{Color Names}.
1360 The function's return value is the string typed by the user in the
1361 minibuffer. However, when called interactively or if the optional
1362 argument @var{convert} is non-@code{nil}, it converts any input color
1363 name into the corresponding RGB value string and instead returns that.
1364 This function requires a valid color specification to be input.
1365 Empty color names are allowed when @code{allow-empty} is
1366 non-@code{nil} and the user enters null input.
1368 Interactively, or when @var{display} is non-@code{nil}, the return
1369 value is also displayed in the echo area.
1372 See also the functions @code{read-coding-system} and
1373 @code{read-non-nil-coding-system}, in @ref{User-Chosen Coding Systems},
1374 and @code{read-input-method-name}, in @ref{Input Methods}.
1376 @node Reading File Names
1377 @subsection Reading File Names
1378 @cindex read file names
1379 @cindex prompt for file name
1381 The high-level completion functions @code{read-file-name},
1382 @code{read-directory-name}, and @code{read-shell-command} are designed
1383 to read file names, directory names, and shell commands respectively.
1384 They provide special features, including automatic insertion of the
1387 @defun read-file-name prompt &optional directory default require-match initial predicate
1388 This function reads a file name, prompting with @var{prompt} and
1389 providing completion.
1391 As an exception, this function reads a file name using a graphical
1392 file dialog instead of the minibuffer, if (i) it is invoked via a
1393 mouse command, and (ii) the selected frame is on a graphical display
1394 supporting such dialogs, and (iii) the variable @code{use-dialog-box}
1395 is non-@code{nil} (@pxref{Dialog Boxes,, Dialog Boxes, emacs, The GNU
1396 Emacs Manual}), and (iv) the @var{directory} argument, described
1397 below, does not specify a remote file (@pxref{Remote Files,, Remote
1398 Files, emacs, The GNU Emacs Manual}). The exact behavior when using a
1399 graphical file dialog is platform-dependent. Here, we simply document
1400 the behavior when using the minibuffer.
1402 @code{read-file-name} does not automatically expand the returned file
1403 name. You must call @code{expand-file-name} yourself if an absolute
1404 file name is required.
1406 The optional argument @var{require-match} has the same meaning as in
1407 @code{completing-read}. @xref{Minibuffer Completion}.
1409 The argument @var{directory} specifies the directory to use for
1410 completing relative file names. It should be an absolute directory
1411 name. If @code{insert-default-directory} is non-@code{nil},
1412 @var{directory} is also inserted in the minibuffer as initial input.
1413 It defaults to the current buffer's value of @code{default-directory}.
1415 If you specify @var{initial}, that is an initial file name to insert
1416 in the buffer (after @var{directory}, if that is inserted). In this
1417 case, point goes at the beginning of @var{initial}. The default for
1418 @var{initial} is @code{nil}---don't insert any file name. To see what
1419 @var{initial} does, try the command @kbd{C-x C-v}. @strong{Please
1420 note:} we recommend using @var{default} rather than @var{initial} in
1423 If @var{default} is non-@code{nil}, then the function returns
1424 @var{default} if the user exits the minibuffer with the same non-empty
1425 contents that @code{read-file-name} inserted initially. The initial
1426 minibuffer contents are always non-empty if
1427 @code{insert-default-directory} is non-@code{nil}, as it is by
1428 default. @var{default} is not checked for validity, regardless of the
1429 value of @var{require-match}. However, if @var{require-match} is
1430 non-@code{nil}, the initial minibuffer contents should be a valid file
1431 (or directory) name. Otherwise @code{read-file-name} attempts
1432 completion if the user exits without any editing, and does not return
1433 @var{default}. @var{default} is also available through the history
1436 If @var{default} is @code{nil}, @code{read-file-name} tries to find a
1437 substitute default to use in its place, which it treats in exactly the
1438 same way as if it had been specified explicitly. If @var{default} is
1439 @code{nil}, but @var{initial} is non-@code{nil}, then the default is
1440 the absolute file name obtained from @var{directory} and
1441 @var{initial}. If both @var{default} and @var{initial} are @code{nil}
1442 and the buffer is visiting a file, @code{read-file-name} uses the
1443 absolute file name of that file as default. If the buffer is not
1444 visiting a file, then there is no default. In that case, if the user
1445 types @key{RET} without any editing, @code{read-file-name} simply
1446 returns the pre-inserted contents of the minibuffer.
1448 If the user types @key{RET} in an empty minibuffer, this function
1449 returns an empty string, regardless of the value of
1450 @var{require-match}. This is, for instance, how the user can make the
1451 current buffer visit no file using @code{M-x set-visited-file-name}.
1453 If @var{predicate} is non-@code{nil}, it specifies a function of one
1454 argument that decides which file names are acceptable completion
1455 alternatives. A file name is an acceptable value if @var{predicate}
1456 returns non-@code{nil} for it.
1458 Here is an example of using @code{read-file-name}:
1462 (read-file-name "The file is ")
1464 ;; @r{After evaluation of the preceding expression,}
1465 ;; @r{the following appears in the minibuffer:}
1469 ---------- Buffer: Minibuffer ----------
1470 The file is /gp/gnu/elisp/@point{}
1471 ---------- Buffer: Minibuffer ----------
1476 Typing @kbd{manual @key{TAB}} results in the following:
1480 ---------- Buffer: Minibuffer ----------
1481 The file is /gp/gnu/elisp/manual.texi@point{}
1482 ---------- Buffer: Minibuffer ----------
1486 @c Wordy to avoid overfull hbox in smallbook mode.
1488 If the user types @key{RET}, @code{read-file-name} returns the file name
1489 as the string @code{"/gp/gnu/elisp/manual.texi"}.
1492 @defvar read-file-name-function
1493 If non-@code{nil}, this should be a function that accepts the same
1494 arguments as @code{read-file-name}. When @code{read-file-name} is
1495 called, it calls this function with the supplied arguments instead of
1496 doing its usual work.
1499 @defopt read-file-name-completion-ignore-case
1500 If this variable is non-@code{nil}, @code{read-file-name} ignores case
1501 when performing completion.
1504 @defun read-directory-name prompt &optional directory default require-match initial
1505 This function is like @code{read-file-name} but allows only directory
1506 names as completion alternatives.
1508 If @var{default} is @code{nil} and @var{initial} is non-@code{nil},
1509 @code{read-directory-name} constructs a substitute default by
1510 combining @var{directory} (or the current buffer's default directory
1511 if @var{directory} is @code{nil}) and @var{initial}. If both
1512 @var{default} and @var{initial} are @code{nil}, this function uses
1513 @var{directory} as substitute default, or the current buffer's default
1514 directory if @var{directory} is @code{nil}.
1517 @defopt insert-default-directory
1518 This variable is used by @code{read-file-name}, and thus, indirectly,
1519 by most commands reading file names. (This includes all commands that
1520 use the code letters @samp{f} or @samp{F} in their interactive form.
1521 @xref{Interactive Codes,, Code Characters for interactive}.) Its
1522 value controls whether @code{read-file-name} starts by placing the
1523 name of the default directory in the minibuffer, plus the initial file
1524 name if any. If the value of this variable is @code{nil}, then
1525 @code{read-file-name} does not place any initial input in the
1526 minibuffer (unless you specify initial input with the @var{initial}
1527 argument). In that case, the default directory is still used for
1528 completion of relative file names, but is not displayed.
1530 If this variable is @code{nil} and the initial minibuffer contents are
1531 empty, the user may have to explicitly fetch the next history element
1532 to access a default value. If the variable is non-@code{nil}, the
1533 initial minibuffer contents are always non-empty and the user can
1534 always request a default value by immediately typing @key{RET} in an
1535 unedited minibuffer. (See above.)
1541 ;; @r{Here the minibuffer starts out with the default directory.}
1542 (let ((insert-default-directory t))
1543 (read-file-name "The file is "))
1547 ---------- Buffer: Minibuffer ----------
1548 The file is ~lewis/manual/@point{}
1549 ---------- Buffer: Minibuffer ----------
1553 ;; @r{Here the minibuffer is empty and only the prompt}
1554 ;; @r{appears on its line.}
1555 (let ((insert-default-directory nil))
1556 (read-file-name "The file is "))
1560 ---------- Buffer: Minibuffer ----------
1561 The file is @point{}
1562 ---------- Buffer: Minibuffer ----------
1567 @defun read-shell-command prompt &optional initial history &rest args
1568 This function reads a shell command from the minibuffer, prompting
1569 with @var{prompt} and providing intelligent completion. It completes
1570 the first word of the command using candidates that are appropriate
1571 for command names, and the rest of the command words as file names.
1573 This function uses @code{minibuffer-local-shell-command-map} as the
1574 keymap for minibuffer input. The @var{history} argument specifies the
1575 history list to use; if is omitted or @code{nil}, it defaults to
1576 @code{shell-command-history} (@pxref{Minibuffer History,
1577 shell-command-history}). The optional argument @var{initial}
1578 specifies the initial content of the minibuffer (@pxref{Initial
1579 Input}). The rest of @var{args}, if present, are used as the
1580 @var{default} and @var{inherit-input-method} arguments in
1581 @code{read-from-minibuffer} (@pxref{Text from Minibuffer}).
1584 @defvar minibuffer-local-shell-command-map
1585 This keymap is used by @code{read-shell-command} for completing
1586 command and file names that are part of a shell command.
1589 @node Completion Variables
1590 @subsection Completion Variables
1592 Here are some variables which can be used to alter the default
1593 completion behavior.
1595 @cindex completion styles
1596 @defopt completion-styles
1597 The value of this variable is a list of completion style (symbols) to
1598 use for performing completion. A @dfn{completion style} is a set of
1599 rules for generating completions. Each symbol in occurring this list
1600 must have a corresponding entry in @code{completion-styles-alist}.
1603 @defvar completion-styles-alist
1604 This variable stores a list of available completion styles. Each
1605 element in the list has the form
1608 (@var{style} @var{try-completion} @var{all-completions} @var{doc})
1612 Here, @var{style} is the name of the completion style (a symbol),
1613 which may be used in the @code{completion-styles} variable to refer to
1614 this style; @var{try-completion} is the function that does the
1615 completion; @var{all-completions} is the function that lists the
1616 completions; and @var{doc} is a string describing the completion
1619 The @var{try-completion} and @var{all-completions} functions should
1620 each accept four arguments: @var{string}, @var{collection},
1621 @var{predicate}, and @var{point}. The @var{string}, @var{collection},
1622 and @var{predicate} arguments have the same meanings as in
1623 @code{try-completion} (@pxref{Basic Completion}), and the @var{point}
1624 argument is the position of point within @var{string}. Each function
1625 should return a non-@code{nil} value if it performed its job, and
1626 @code{nil} if it did not (e.g.@: if there is no way to complete
1627 @var{string} according to the completion style).
1629 When the user calls a completion command like
1630 @code{minibuffer-complete} (@pxref{Completion Commands}), Emacs looks
1631 for the first style listed in @code{completion-styles} and calls its
1632 @var{try-completion} function. If this function returns @code{nil},
1633 Emacs moves to the next listed completion style and calls its
1634 @var{try-completion} function, and so on until one of the
1635 @var{try-completion} functions successfully performs completion and
1636 returns a non-@code{nil} value. A similar procedure is used for
1637 listing completions, via the @var{all-completions} functions.
1639 @xref{Completion Styles,,, emacs, The GNU Emacs Manual}, for a
1640 description of the available completion styles.
1643 @defopt completion-category-overrides
1644 This variable specifies special completion styles and other completion
1645 behaviors to use when completing certain types of text. Its value
1646 should be a list of the form @code{(@var{category} . @var{alist})}.
1647 @var{category} is a symbol describing what is being completed;
1648 currently, the @code{buffer} and @code{file} categories are defined,
1649 but others can be defined via specialized completion functions
1650 (@pxref{Programmed Completion}). @var{alist} is an association list
1651 describing how completion should behave for the corresponding
1652 category. The following alist keys are supported:
1656 The value should be a list of completion styles (symbols).
1659 The value should be a value for @code{completion-cycle-threshold}
1660 (@pxref{Completion Options,,, emacs, The GNU Emacs Manual}) for this
1665 Additional alist entries may be defined in the future.
1668 @defvar completion-extra-properties
1669 This variable is used to specify extra properties of the current
1670 completion command. It is intended to be let-bound by specialized
1671 completion commands. Its value should be a list of property and value
1672 pairs. The following properties are supported:
1675 @item :annotation-function
1676 The value should be a function to add annotations in the completions
1677 buffer. This function must accept one argument, a completion, and
1678 should either return @code{nil} or a string to be displayed next to
1681 @item :exit-function
1682 The value should be a function to run after performing completion.
1683 The function should accept two arguments, @var{string} and
1684 @var{status}, where @var{string} is the text to which the field was
1685 completed and @var{status} indicates what kind of operation happened:
1686 @code{finished} if text is now complete, @code{sole} if the text
1687 cannot be further completed but completion is not finished, or
1688 @code{exact} if the text is a valid completion but may be further
1693 @node Programmed Completion
1694 @subsection Programmed Completion
1695 @cindex programmed completion
1697 Sometimes it is not possible or convenient to create an alist or
1698 an obarray containing all the intended possible completions ahead
1699 of time. In such a case, you can supply your own function to compute
1700 the completion of a given string. This is called @dfn{programmed
1701 completion}. Emacs uses programmed completion when completing file
1702 names (@pxref{File Name Completion}), among many other cases.
1704 To use this feature, pass a function as the @var{collection}
1705 argument to @code{completing-read}. The function
1706 @code{completing-read} arranges to pass your completion function along
1707 to @code{try-completion}, @code{all-completions}, and other basic
1708 completion functions, which will then let your function do all
1711 The completion function should accept three arguments:
1715 The string to be completed.
1718 A predicate function with which to filter possible matches, or
1719 @code{nil} if none. The function should call the predicate for each
1720 possible match, and ignore the match if the predicate returns
1724 A flag specifying the type of completion operation to perform. This
1725 is one of the following four values:
1729 This specifies a @code{try-completion} operation. The function should
1730 return @code{t} if the specified string is a unique and exact match;
1731 if there is more than one match, it should return the common substring
1732 of all matches (if the string is an exact match for one completion
1733 alternative but also matches other longer alternatives, the return
1734 value is the string); if there are no matches, it should return
1738 This specifies an @code{all-completions} operation. The function
1739 should return a list of all possible completions of the specified
1743 This specifies a @code{test-completion} operation. The function
1744 should return @code{t} if the specified string is an exact match for
1745 some completion alternative; @code{nil} otherwise.
1747 @item (boundaries . @var{suffix})
1748 This specifies a @code{completion-boundaries} operation. The function
1749 should return @code{(boundaries @var{start} . @var{end})}, where
1750 @var{start} is the position of the beginning boundary in the specified
1751 string, and @var{end} is the position of the end boundary in
1755 This specifies a request for information about the state of the
1756 current completion. The function should return an alist, as described
1757 below. The alist may contain any number of elements.
1761 If the flag has any other value, the completion function should return
1765 The following is a list of metadata entries that a completion function
1766 may return in response to a @code{metadata} flag argument:
1770 The value should be a symbol describing what kind of text the
1771 completion function is trying to complete. If the symbol matches one
1772 of the keys in @code{completion-category-overrides}, the usual
1773 completion behavior is overridden. @xref{Completion Variables}.
1775 @item annotation-function
1776 The value should be a function for @dfn{annotating} completions. The
1777 function should take one argument, @var{string}, which is a possible
1778 completion. It should return a string, which is displayed after the
1779 completion @var{string} in the @file{*Completions*} buffer.
1781 @item display-sort-function
1782 The value should be a function for sorting completions. The function
1783 should take one argument, a list of completion strings, and return a
1784 sorted list of completion strings. It is allowed to alter the input
1787 @item cycle-sort-function
1788 The value should be a function for sorting completions, when
1789 @code{completion-cycle-threshold} is non-@code{nil} and the user is
1790 cycling through completion alternatives. @xref{Completion Options,,,
1791 emacs, The GNU Emacs Manual}. Its argument list and return value are
1792 the same as for @code{display-sort-function}.
1795 @defun completion-table-dynamic function
1796 This function is a convenient way to write a function that can act as
1797 programmed completion function. The argument @var{function} should be
1798 a function that takes one argument, a string, and returns an alist of
1799 possible completions of it. You can think of
1800 @code{completion-table-dynamic} as a transducer between that interface
1801 and the interface for programmed completion functions.
1804 @node Completion in Buffers
1805 @subsection Completion in Ordinary Buffers
1806 @cindex inline completion
1808 @findex completion-at-point
1809 Although completion is usually done in the minibuffer, the
1810 completion facility can also be used on the text in ordinary Emacs
1811 buffers. In many major modes, in-buffer completion is performed by
1812 the @kbd{C-M-i} or @kbd{M-@key{TAB}} command, bound to
1813 @code{completion-at-point}. @xref{Symbol Completion,,, emacs, The GNU
1814 Emacs Manual}. This command uses the abnormal hook variable
1815 @code{completion-at-point-functions}:
1817 @defvar completion-at-point-functions
1818 The value of this abnormal hook should be a list of functions, which
1819 are used to compute a completion table for completing the text at
1820 point. It can be used by major modes to provide mode-specific
1821 completion tables (@pxref{Major Mode Conventions}).
1823 When the command @code{completion-at-point} runs, it calls the
1824 functions in the list one by one, without any argument. Each function
1825 should return @code{nil} if it is unable to produce a completion table
1826 for the text at point. Otherwise it should return a list of the form
1829 (@var{start} @var{end} @var{collection} . @var{props})
1833 @var{start} and @var{end} delimit the text to complete (which should
1834 enclose point). @var{collection} is a completion table for completing
1835 that text, in a form suitable for passing as the second argument to
1836 @code{try-completion} (@pxref{Basic Completion}); completion
1837 alternatives will be generated from this completion table in the usual
1838 way, via the completion styles defined in @code{completion-styles}
1839 (@pxref{Completion Variables}). @var{props} is a property list for
1840 additional information; any of the properties in
1841 @code{completion-extra-properties} are recognized (@pxref{Completion
1842 Variables}), as well as the following additional ones:
1846 The value should be a predicate that completion candidates need to
1850 If the value is @code{no}, then if the completion table fails to match
1851 the text at point, then @code{completion-at-point} moves on to the
1852 next function in @code{completion-at-point-functions} instead of
1853 reporting a completion failure.
1856 A function in @code{completion-at-point-functions} may also return a
1857 function. In that case, that returned function is called, with no
1858 argument, and it is entirely responsible for performing the
1859 completion. We discourage this usage; it is intended to help convert
1860 old code to using @code{completion-at-point}.
1862 The first function in @code{completion-at-point-functions} to return a
1863 non-@code{nil} value is used by @code{completion-at-point}. The
1864 remaining functions are not called. The exception to this is when
1865 there is a @code{:exclusive} specification, as described above.
1868 The following function provides a convenient way to perform
1869 completion on an arbitrary stretch of text in an Emacs buffer:
1871 @defun completion-in-region start end collection &optional predicate
1872 This function completes the text in the current buffer between the
1873 positions @var{start} and @var{end}, using @var{collection}. The
1874 argument @var{collection} has the same meaning as in
1875 @code{try-completion} (@pxref{Basic Completion}).
1877 This function inserts the completion text directly into the current
1878 buffer. Unlike @code{completing-read} (@pxref{Minibuffer
1879 Completion}), it does not activate the minibuffer.
1881 For this function to work, point must be somewhere between @var{start}
1886 @node Yes-or-No Queries
1887 @section Yes-or-No Queries
1888 @cindex asking the user questions
1889 @cindex querying the user
1890 @cindex yes-or-no questions
1892 This section describes functions used to ask the user a yes-or-no
1893 question. The function @code{y-or-n-p} can be answered with a single
1894 character; it is useful for questions where an inadvertent wrong answer
1895 will not have serious consequences. @code{yes-or-no-p} is suitable for
1896 more momentous questions, since it requires three or four characters to
1899 If either of these functions is called in a command that was invoked
1900 using the mouse---more precisely, if @code{last-nonmenu-event}
1901 (@pxref{Command Loop Info}) is either @code{nil} or a list---then it
1902 uses a dialog box or pop-up menu to ask the question. Otherwise, it
1903 uses keyboard input. You can force use of the mouse or use of keyboard
1904 input by binding @code{last-nonmenu-event} to a suitable value around
1907 Strictly speaking, @code{yes-or-no-p} uses the minibuffer and
1908 @code{y-or-n-p} does not; but it seems best to describe them together.
1910 @defun y-or-n-p prompt
1911 This function asks the user a question, expecting input in the echo
1912 area. It returns @code{t} if the user types @kbd{y}, @code{nil} if the
1913 user types @kbd{n}. This function also accepts @key{SPC} to mean yes
1914 and @key{DEL} to mean no. It accepts @kbd{C-]} to mean ``quit'', like
1915 @kbd{C-g}, because the question might look like a minibuffer and for
1916 that reason the user might try to use @kbd{C-]} to get out. The answer
1917 is a single character, with no @key{RET} needed to terminate it. Upper
1918 and lower case are equivalent.
1920 ``Asking the question'' means printing @var{prompt} in the echo area,
1921 followed by the string @w{@samp{(y or n) }}. If the input is not one of
1922 the expected answers (@kbd{y}, @kbd{n}, @kbd{@key{SPC}},
1923 @kbd{@key{DEL}}, or something that quits), the function responds
1924 @samp{Please answer y or n.}, and repeats the request.
1926 This function does not actually use the minibuffer, since it does not
1927 allow editing of the answer. It actually uses the echo area (@pxref{The
1928 Echo Area}), which uses the same screen space as the minibuffer. The
1929 cursor moves to the echo area while the question is being asked.
1931 The answers and their meanings, even @samp{y} and @samp{n}, are not
1932 hardwired. The keymap @code{query-replace-map} specifies them.
1933 @xref{Search and Replace}.
1935 In the following example, the user first types @kbd{q}, which is
1936 invalid. At the next prompt the user types @kbd{y}.
1940 (y-or-n-p "Do you need a lift? ")
1942 ;; @r{After evaluation of the preceding expression,}
1943 ;; @r{the following prompt appears in the echo area:}
1947 ---------- Echo area ----------
1948 Do you need a lift? (y or n)
1949 ---------- Echo area ----------
1952 ;; @r{If the user then types @kbd{q}, the following appears:}
1955 ---------- Echo area ----------
1956 Please answer y or n. Do you need a lift? (y or n)
1957 ---------- Echo area ----------
1960 ;; @r{When the user types a valid answer,}
1961 ;; @r{it is displayed after the question:}
1964 ---------- Echo area ----------
1965 Do you need a lift? (y or n) y
1966 ---------- Echo area ----------
1971 We show successive lines of echo area messages, but only one actually
1972 appears on the screen at a time.
1975 @defun y-or-n-p-with-timeout prompt seconds default
1976 Like @code{y-or-n-p}, except that if the user fails to answer within
1977 @var{seconds} seconds, this function stops waiting and returns
1978 @var{default}. It works by setting up a timer; see @ref{Timers}.
1979 The argument @var{seconds} may be an integer or a floating point number.
1982 @defun yes-or-no-p prompt
1983 This function asks the user a question, expecting input in the
1984 minibuffer. It returns @code{t} if the user enters @samp{yes},
1985 @code{nil} if the user types @samp{no}. The user must type @key{RET} to
1986 finalize the response. Upper and lower case are equivalent.
1988 @code{yes-or-no-p} starts by displaying @var{prompt} in the echo area,
1989 followed by @w{@samp{(yes or no) }}. The user must type one of the
1990 expected responses; otherwise, the function responds @samp{Please answer
1991 yes or no.}, waits about two seconds and repeats the request.
1993 @code{yes-or-no-p} requires more work from the user than
1994 @code{y-or-n-p} and is appropriate for more crucial decisions.
2000 (yes-or-no-p "Do you really want to remove everything? ")
2002 ;; @r{After evaluation of the preceding expression,}
2003 ;; @r{the following prompt appears,}
2004 ;; @r{with an empty minibuffer:}
2008 ---------- Buffer: minibuffer ----------
2009 Do you really want to remove everything? (yes or no)
2010 ---------- Buffer: minibuffer ----------
2015 If the user first types @kbd{y @key{RET}}, which is invalid because this
2016 function demands the entire word @samp{yes}, it responds by displaying
2017 these prompts, with a brief pause between them:
2021 ---------- Buffer: minibuffer ----------
2022 Please answer yes or no.
2023 Do you really want to remove everything? (yes or no)
2024 ---------- Buffer: minibuffer ----------
2029 @node Multiple Queries
2030 @section Asking Multiple Y-or-N Questions
2032 When you have a series of similar questions to ask, such as ``Do you
2033 want to save this buffer'' for each buffer in turn, you should use
2034 @code{map-y-or-n-p} to ask the collection of questions, rather than
2035 asking each question individually. This gives the user certain
2036 convenient facilities such as the ability to answer the whole series at
2039 @defun map-y-or-n-p prompter actor list &optional help action-alist no-cursor-in-echo-area
2040 This function asks the user a series of questions, reading a
2041 single-character answer in the echo area for each one.
2043 The value of @var{list} specifies the objects to ask questions about.
2044 It should be either a list of objects or a generator function. If it is
2045 a function, it should expect no arguments, and should return either the
2046 next object to ask about, or @code{nil} meaning stop asking questions.
2048 The argument @var{prompter} specifies how to ask each question. If
2049 @var{prompter} is a string, the question text is computed like this:
2052 (format @var{prompter} @var{object})
2056 where @var{object} is the next object to ask about (as obtained from
2059 If not a string, @var{prompter} should be a function of one argument
2060 (the next object to ask about) and should return the question text. If
2061 the value is a string, that is the question to ask the user. The
2062 function can also return @code{t} meaning do act on this object (and
2063 don't ask the user), or @code{nil} meaning ignore this object (and don't
2066 The argument @var{actor} says how to act on the answers that the user
2067 gives. It should be a function of one argument, and it is called with
2068 each object that the user says yes for. Its argument is always an
2069 object obtained from @var{list}.
2071 If the argument @var{help} is given, it should be a list of this form:
2074 (@var{singular} @var{plural} @var{action})
2078 where @var{singular} is a string containing a singular noun that
2079 describes the objects conceptually being acted on, @var{plural} is the
2080 corresponding plural noun, and @var{action} is a transitive verb
2081 describing what @var{actor} does.
2083 If you don't specify @var{help}, the default is @code{("object"
2084 "objects" "act on")}.
2086 Each time a question is asked, the user may enter @kbd{y}, @kbd{Y}, or
2087 @key{SPC} to act on that object; @kbd{n}, @kbd{N}, or @key{DEL} to skip
2088 that object; @kbd{!} to act on all following objects; @key{ESC} or
2089 @kbd{q} to exit (skip all following objects); @kbd{.} (period) to act on
2090 the current object and then exit; or @kbd{C-h} to get help. These are
2091 the same answers that @code{query-replace} accepts. The keymap
2092 @code{query-replace-map} defines their meaning for @code{map-y-or-n-p}
2093 as well as for @code{query-replace}; see @ref{Search and Replace}.
2095 You can use @var{action-alist} to specify additional possible answers
2096 and what they mean. It is an alist of elements of the form
2097 @code{(@var{char} @var{function} @var{help})}, each of which defines one
2098 additional answer. In this element, @var{char} is a character (the
2099 answer); @var{function} is a function of one argument (an object from
2100 @var{list}); @var{help} is a string.
2102 When the user responds with @var{char}, @code{map-y-or-n-p} calls
2103 @var{function}. If it returns non-@code{nil}, the object is considered
2104 ``acted upon'', and @code{map-y-or-n-p} advances to the next object in
2105 @var{list}. If it returns @code{nil}, the prompt is repeated for the
2108 Normally, @code{map-y-or-n-p} binds @code{cursor-in-echo-area} while
2109 prompting. But if @var{no-cursor-in-echo-area} is non-@code{nil}, it
2112 If @code{map-y-or-n-p} is called in a command that was invoked using the
2113 mouse---more precisely, if @code{last-nonmenu-event} (@pxref{Command
2114 Loop Info}) is either @code{nil} or a list---then it uses a dialog box
2115 or pop-up menu to ask the question. In this case, it does not use
2116 keyboard input or the echo area. You can force use of the mouse or use
2117 of keyboard input by binding @code{last-nonmenu-event} to a suitable
2118 value around the call.
2120 The return value of @code{map-y-or-n-p} is the number of objects acted on.
2123 @node Reading a Password
2124 @section Reading a Password
2125 @cindex passwords, reading
2127 To read a password to pass to another program, you can use the
2128 function @code{read-passwd}.
2130 @defun read-passwd prompt &optional confirm default
2131 This function reads a password, prompting with @var{prompt}. It does
2132 not echo the password as the user types it; instead, it echoes @samp{.}
2133 for each character in the password.
2135 The optional argument @var{confirm}, if non-@code{nil}, says to read the
2136 password twice and insist it must be the same both times. If it isn't
2137 the same, the user has to type it over and over until the last two
2140 The optional argument @var{default} specifies the default password to
2141 return if the user enters empty input. If @var{default} is @code{nil},
2142 then @code{read-passwd} returns the null string in that case.
2145 @node Minibuffer Commands
2146 @section Minibuffer Commands
2148 This section describes some commands meant for use in the
2151 @deffn Command exit-minibuffer
2152 This command exits the active minibuffer. It is normally bound to
2153 keys in minibuffer local keymaps.
2156 @deffn Command self-insert-and-exit
2157 This command exits the active minibuffer after inserting the last
2158 character typed on the keyboard (found in @code{last-command-event};
2159 @pxref{Command Loop Info}).
2162 @deffn Command previous-history-element n
2163 This command replaces the minibuffer contents with the value of the
2164 @var{n}th previous (older) history element.
2167 @deffn Command next-history-element n
2168 This command replaces the minibuffer contents with the value of the
2169 @var{n}th more recent history element.
2172 @deffn Command previous-matching-history-element pattern n
2173 This command replaces the minibuffer contents with the value of the
2174 @var{n}th previous (older) history element that matches @var{pattern} (a
2175 regular expression).
2178 @deffn Command next-matching-history-element pattern n
2179 This command replaces the minibuffer contents with the value of the
2180 @var{n}th next (newer) history element that matches @var{pattern} (a
2181 regular expression).
2184 @node Minibuffer Windows
2185 @section Minibuffer Windows
2186 @cindex minibuffer windows
2188 These functions access and select minibuffer windows
2189 and test whether they are active.
2191 @defun active-minibuffer-window
2192 This function returns the currently active minibuffer window, or
2193 @code{nil} if none is currently active.
2196 @defun minibuffer-window &optional frame
2197 @anchor{Definition of minibuffer-window}
2198 This function returns the minibuffer window used for frame @var{frame}.
2199 If @var{frame} is @code{nil}, that stands for the current frame. Note
2200 that the minibuffer window used by a frame need not be part of that
2201 frame---a frame that has no minibuffer of its own necessarily uses some
2202 other frame's minibuffer window.
2205 @defun set-minibuffer-window window
2206 This function specifies @var{window} as the minibuffer window to use.
2207 This affects where the minibuffer is displayed if you put text in it
2208 without invoking the usual minibuffer commands. It has no effect on
2209 the usual minibuffer input functions because they all start by
2210 choosing the minibuffer window according to the current frame.
2214 @defun window-minibuffer-p &optional window
2215 This function returns non-@code{nil} if @var{window} is a minibuffer
2217 @var{window} defaults to the selected window.
2220 It is not correct to determine whether a given window is a minibuffer by
2221 comparing it with the result of @code{(minibuffer-window)}, because
2222 there can be more than one minibuffer window if there is more than one
2225 @defun minibuffer-window-active-p window
2226 This function returns non-@code{nil} if @var{window}, assumed to be
2227 a minibuffer window, is currently active.
2230 @node Minibuffer Contents
2231 @section Minibuffer Contents
2233 These functions access the minibuffer prompt and contents.
2235 @defun minibuffer-prompt
2236 This function returns the prompt string of the currently active
2237 minibuffer. If no minibuffer is active, it returns @code{nil}.
2240 @defun minibuffer-prompt-end
2241 This function returns the current
2242 position of the end of the minibuffer prompt, if a minibuffer is
2243 current. Otherwise, it returns the minimum valid buffer position.
2246 @defun minibuffer-prompt-width
2247 This function returns the current display-width of the minibuffer
2248 prompt, if a minibuffer is current. Otherwise, it returns zero.
2251 @defun minibuffer-contents
2252 This function returns the editable
2253 contents of the minibuffer (that is, everything except the prompt) as
2254 a string, if a minibuffer is current. Otherwise, it returns the
2255 entire contents of the current buffer.
2258 @defun minibuffer-contents-no-properties
2259 This is like @code{minibuffer-contents}, except that it does not copy text
2260 properties, just the characters themselves. @xref{Text Properties}.
2263 @defun minibuffer-completion-contents
2264 This is like @code{minibuffer-contents}, except that it returns only
2265 the contents before point. That is the part that completion commands
2266 operate on. @xref{Minibuffer Completion}.
2269 @defun delete-minibuffer-contents
2270 This function erases the editable contents of the minibuffer (that is,
2271 everything except the prompt), if a minibuffer is current. Otherwise,
2272 it erases the entire current buffer.
2275 @node Recursive Mini
2276 @section Recursive Minibuffers
2277 @cindex recursive minibuffers
2279 These functions and variables deal with recursive minibuffers
2280 (@pxref{Recursive Editing}):
2282 @defun minibuffer-depth
2283 This function returns the current depth of activations of the
2284 minibuffer, a nonnegative integer. If no minibuffers are active, it
2288 @defopt enable-recursive-minibuffers
2289 If this variable is non-@code{nil}, you can invoke commands (such as
2290 @code{find-file}) that use minibuffers even while the minibuffer window
2291 is active. Such invocation produces a recursive editing level for a new
2292 minibuffer. The outer-level minibuffer is invisible while you are
2293 editing the inner one.
2295 If this variable is @code{nil}, you cannot invoke minibuffer
2296 commands when the minibuffer window is active, not even if you switch to
2297 another window to do it.
2301 If a command name has a property @code{enable-recursive-minibuffers}
2302 that is non-@code{nil}, then the command can use the minibuffer to read
2303 arguments even if it is invoked from the minibuffer. A command can
2304 also achieve this by binding @code{enable-recursive-minibuffers}
2305 to @code{t} in the interactive declaration (@pxref{Using Interactive}).
2306 The minibuffer command @code{next-matching-history-element} (normally
2307 @kbd{M-s} in the minibuffer) does the latter.
2309 @node Minibuffer Misc
2310 @section Minibuffer Miscellany
2312 @defun minibufferp &optional buffer-or-name
2313 This function returns non-@code{nil} if @var{buffer-or-name} is a
2314 minibuffer. If @var{buffer-or-name} is omitted, it tests the current
2318 @defvar minibuffer-setup-hook
2319 This is a normal hook that is run whenever the minibuffer is entered.
2323 @defvar minibuffer-exit-hook
2324 This is a normal hook that is run whenever the minibuffer is exited.
2328 @defvar minibuffer-help-form
2329 @anchor{Definition of minibuffer-help-form}
2330 The current value of this variable is used to rebind @code{help-form}
2331 locally inside the minibuffer (@pxref{Help Functions}).
2334 @defvar minibuffer-scroll-window
2335 @anchor{Definition of minibuffer-scroll-window}
2336 If the value of this variable is non-@code{nil}, it should be a window
2337 object. When the function @code{scroll-other-window} is called in the
2338 minibuffer, it scrolls this window.
2341 @defun minibuffer-selected-window
2342 This function returns the window which was selected when the
2343 minibuffer was entered. If selected window is not a minibuffer
2344 window, it returns @code{nil}.
2347 @defopt max-mini-window-height
2348 This variable specifies the maximum height for resizing minibuffer
2349 windows. If a float, it specifies a fraction of the height of the
2350 frame. If an integer, it specifies a number of lines.
2353 @defun minibuffer-message string &rest args
2354 This function displays @var{string} temporarily at the end of the
2355 minibuffer text, for two seconds, or until the next input event
2356 arrives, whichever comes first. If @var{args} is non-@code{nil}, the
2357 actual message is obtained by passing @var{string} and @var{args}
2358 through @code{format}. @xref{Formatting Strings}.