2 @c This is part of the XEmacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1997 Free Software Foundation, Inc.
4 @c See the file lispref.texi for copying conditions.
5 @setfilename ../../info/minibuf.info
6 @node Minibuffers, Command Loop, Read and Print, Top
8 @cindex arguments, reading
9 @cindex complex arguments
12 A @dfn{minibuffer} is a special buffer that XEmacs commands use to read
13 arguments more complicated than the single numeric prefix argument.
14 These arguments include file names, buffer names, and command names (as
15 in @kbd{M-x}). The minibuffer is displayed on the bottom line of the
16 frame, in the same place as the echo area, but only while it is in
17 use for reading an argument.
20 * Intro to Minibuffers:: Basic information about minibuffers.
21 * Text from Minibuffer:: How to read a straight text string.
22 * Object from Minibuffer:: How to read a Lisp object or expression.
23 * Minibuffer History:: Recording previous minibuffer inputs
24 so the user can reuse them.
25 * Completion:: How to invoke and customize completion.
26 * Yes-or-No Queries:: Asking a question with a simple answer.
27 * Multiple Queries:: Asking a series of similar questions.
28 * Reading a Password:: Reading a password from the terminal.
29 * Minibuffer Misc:: Various customization hooks and variables.
32 @node Intro to Minibuffers
33 @section Introduction to Minibuffers
35 In most ways, a minibuffer is a normal XEmacs buffer. Most operations
36 @emph{within} a buffer, such as editing commands, work normally in a
37 minibuffer. However, many operations for managing buffers do not apply
38 to minibuffers. The name of a minibuffer always has the form @w{@samp{
39 *Minibuf-@var{number}}}, and it cannot be changed. Minibuffers are
40 displayed only in special windows used only for minibuffers; these
41 windows always appear at the bottom of a frame. (Sometimes frames have
42 no minibuffer window, and sometimes a special kind of frame contains
43 nothing but a minibuffer window; see @ref{Minibuffers and Frames}.)
45 The minibuffer's window is normally a single line. You can resize it
46 temporarily with the window sizing commands; it reverts to its normal
47 size when the minibuffer is exited. You can resize it permanently by
48 using the window sizing commands in the frame's other window, when the
49 minibuffer is not active. If the frame contains just a minibuffer, you
50 can change the minibuffer's size by changing the frame's size.
52 If a command uses a minibuffer while there is an active minibuffer,
53 this is called a @dfn{recursive minibuffer}. The first minibuffer is
54 named @w{@samp{ *Minibuf-0*}}. Recursive minibuffers are named by
55 incrementing the number at the end of the name. (The names begin with a
56 space so that they won't show up in normal buffer lists.) Of several
57 recursive minibuffers, the innermost (or most recently entered) is the
58 active minibuffer. We usually call this ``the'' minibuffer. You can
59 permit or forbid recursive minibuffers by setting the variable
60 @code{enable-recursive-minibuffers}.
62 Like other buffers, a minibuffer may use any of several local keymaps
63 (@pxref{Keymaps}); these contain various exit commands and in some cases
64 completion commands (@pxref{Completion}).
68 @code{minibuffer-local-map} is for ordinary input (no completion).
71 @code{minibuffer-local-completion-map} is for permissive completion.
74 @code{minibuffer-local-must-match-map} is for strict completion and
75 for cautious completion.
78 @node Text from Minibuffer
79 @section Reading Text Strings with the Minibuffer
81 Most often, the minibuffer is used to read text as a string. It can
82 also be used to read a Lisp object in textual form. The most basic
83 primitive for minibuffer input is @code{read-from-minibuffer}; it can do
86 In most cases, you should not call minibuffer input functions in the
87 middle of a Lisp function. Instead, do all minibuffer input as part of
88 reading the arguments for a command, in the @code{interactive} spec.
89 @xref{Defining Commands}.
91 @defun read-from-minibuffer prompt-string &optional initial-contents keymap read hist abbrev-table default
92 This function is the most general way to get input through the
93 minibuffer. By default, it accepts arbitrary text and returns it as a
94 string; however, if @var{read} is non-@code{nil}, then it uses
95 @code{read} to convert the text into a Lisp object (@pxref{Input
98 The first thing this function does is to activate a minibuffer and
99 display it with @var{prompt-string} as the prompt. This value must be a
102 Then, if @var{initial-contents} is a string, @code{read-from-minibuffer}
103 inserts it into the minibuffer, leaving point at the end. The
104 minibuffer appears with this text as its contents.
107 The value of @var{initial-contents} may also be a cons cell of the form
108 @code{(@var{string} . @var{position})}. This means to insert
109 @var{string} in the minibuffer but put point @var{position} characters
110 from the beginning, rather than at the end.
112 When the user types a command to exit the minibuffer,
113 @code{read-from-minibuffer} constructs the return value from the text in
114 the minibuffer. Normally it returns a string containing that text.
115 However, if @var{read} is non-@code{nil}, @code{read-from-minibuffer}
116 reads the text and returns the resulting Lisp object, unevaluated.
117 (@xref{Input Functions}, for information about reading.)
119 The argument @var{default} specifies a default value to make available
120 through the history commands. It should be a string, or @code{nil}.
122 If @var{keymap} is non-@code{nil}, that keymap is the local keymap to
123 use in the minibuffer. If @var{keymap} is omitted or @code{nil}, the
124 value of @code{minibuffer-local-map} is used as the keymap. Specifying
125 a keymap is the most important way to customize the minibuffer for
126 various applications such as completion.
128 The argument @var{abbrev-table} specifies @code{local-abbrev-table} in
129 the minibuffer (@pxref{Standard Abbrev Tables}).
131 The argument @var{hist} specifies which history list variable to use
132 for saving the input and for history commands used in the minibuffer.
133 It defaults to @code{minibuffer-history}. @xref{Minibuffer History}.
135 When the user types a command to exit the minibuffer,
136 @code{read-from-minibuffer} uses the text in the minibuffer to produce
137 its return value. Normally it simply makes a string containing that
138 text. However, if @var{read} is non-@code{nil},
139 @code{read-from-minibuffer} reads the text and returns the resulting
140 Lisp object, unevaluated. (@xref{Input Functions}, for information
143 @strong{Usage note:} The @var{initial-contents} argument and the
144 @var{default} argument are two alternative features for more or less the
145 same job. It does not make sense to use both features in a single call
146 to @code{read-from-minibuffer}. In general, we recommend using
147 @var{default}, since this permits the user to insert the default value
148 when it is wanted, but does not burden the user with deleting it from
149 the minibuffer on other occasions. However, if user is supposed to edit
150 default value, @var{initial-contents} may be preferred.
153 @defun read-string prompt &optional initial history
154 This function reads a string from the minibuffer and returns it. The
155 arguments @var{prompt} and @var{initial} are used as in
156 @code{read-from-minibuffer}. The keymap used is
157 @code{minibuffer-local-map}.
159 The optional argument @var{history}, if non-nil, specifies a history
160 list and optionally the initial position in the list.
162 This function is a simplified interface to the
163 @code{read-from-minibuffer} function:
167 (read-string @var{prompt} @var{initial})
169 (read-from-minibuffer @var{prompt} @var{initial} nil nil nil)
174 @defvar minibuffer-local-map
175 This is the default local keymap for reading from the minibuffer. By
176 default, it makes the following bindings:
180 @code{exit-minibuffer}
183 @code{exit-minibuffer}
186 @code{abort-recursive-edit}
189 @code{next-history-element}
192 @code{previous-history-element}
195 @code{next-matching-history-element}
198 @code{previous-matching-history-element}
202 @node Object from Minibuffer
203 @section Reading Lisp Objects with the Minibuffer
205 This section describes functions for reading Lisp objects with the
208 @defun read-minibuffer prompt &optional initial
209 This function reads a Lisp object using the minibuffer, and returns it
210 without evaluating it. The arguments @var{prompt} and @var{initial} are
211 used as in @code{read-from-minibuffer}.
213 This is a simplified interface to the
214 @code{read-from-minibuffer} function:
218 (read-minibuffer @var{prompt} @var{initial})
220 (read-from-minibuffer @var{prompt} @var{initial} nil t)
224 Here is an example in which we supply the string @code{"(testing)"} as
230 "Enter an expression: " (format "%s" '(testing)))
232 ;; @r{Here is how the minibuffer is displayed:}
236 ---------- Buffer: Minibuffer ----------
237 Enter an expression: (testing)@point{}
238 ---------- Buffer: Minibuffer ----------
243 The user can type @key{RET} immediately to use the initial input as a
244 default, or can edit the input.
247 @defun eval-minibuffer prompt &optional initial
248 This function reads a Lisp expression using the minibuffer, evaluates
249 it, then returns the result. The arguments @var{prompt} and
250 @var{initial} are used as in @code{read-from-minibuffer}.
252 This function simply evaluates the result of a call to
253 @code{read-minibuffer}:
257 (eval-minibuffer @var{prompt} @var{initial})
259 (eval (read-minibuffer @var{prompt} @var{initial}))
264 @defun edit-and-eval-command prompt form
265 This function reads a Lisp expression in the minibuffer, and then
266 evaluates it. The difference between this command and
267 @code{eval-minibuffer} is that here the initial @var{form} is not
268 optional and it is treated as a Lisp object to be converted to printed
269 representation rather than as a string of text. It is printed with
270 @code{prin1}, so if it is a string, double-quote characters (@samp{"})
271 appear in the initial text. @xref{Output Functions}.
273 The first thing @code{edit-and-eval-command} does is to activate the
274 minibuffer with @var{prompt} as the prompt. Then it inserts the printed
275 representation of @var{form} in the minibuffer, and lets the user edit it.
276 When the user exits the minibuffer, the edited text is read with
277 @code{read} and then evaluated. The resulting value becomes the value
278 of @code{edit-and-eval-command}.
280 In the following example, we offer the user an expression with initial
281 text which is a valid form already:
285 (edit-and-eval-command "Please edit: " '(forward-word 1))
287 ;; @r{After evaluation of the preceding expression,}
288 ;; @r{the following appears in the minibuffer:}
292 ---------- Buffer: Minibuffer ----------
293 Please edit: (forward-word 1)@point{}
294 ---------- Buffer: Minibuffer ----------
299 Typing @key{RET} right away would exit the minibuffer and evaluate the
300 expression, thus moving point forward one word.
301 @code{edit-and-eval-command} returns @code{t} in this example.
304 @node Minibuffer History
305 @section Minibuffer History
306 @cindex minibuffer history
309 A @dfn{minibuffer history list} records previous minibuffer inputs so
310 the user can reuse them conveniently. A history list is actually a
311 symbol, not a list; it is a variable whose value is a list of strings
312 (previous inputs), most recent first.
314 There are many separate history lists, used for different kinds of
315 inputs. It's the Lisp programmer's job to specify the right history
316 list for each use of the minibuffer.
318 The basic minibuffer input functions @code{read-from-minibuffer} and
319 @code{completing-read} both accept an optional argument named @var{hist}
320 which is how you specify the history list. Here are the possible
325 Use @var{variable} (a symbol) as the history list.
327 @item (@var{variable} . @var{startpos})
328 Use @var{variable} (a symbol) as the history list, and assume that the
329 initial history position is @var{startpos} (an integer, counting from
330 zero which specifies the most recent element of the history).
332 If you specify @var{startpos}, then you should also specify that element
333 of the history as the initial minibuffer contents, for consistency.
336 If you don't specify @var{hist}, then the default history list
337 @code{minibuffer-history} is used. For other standard history lists,
338 see below. You can also create your own history list variable; just
339 initialize it to @code{nil} before the first use.
341 Both @code{read-from-minibuffer} and @code{completing-read} add new
342 elements to the history list automatically, and provide commands to
343 allow the user to reuse items on the list. The only thing your program
344 needs to do to use a history list is to initialize it and to pass its
345 name to the input functions when you wish. But it is safe to modify the
346 list by hand when the minibuffer input functions are not using it.
348 Here are some of the standard minibuffer history list variables:
350 @defvar minibuffer-history
351 The default history list for minibuffer history input.
354 @defvar query-replace-history
355 A history list for arguments to @code{query-replace} (and similar
356 arguments to other commands).
359 @defvar file-name-history
360 A history list for file name arguments.
363 @defvar regexp-history
364 A history list for regular expression arguments.
367 @defvar extended-command-history
368 A history list for arguments that are names of extended commands.
371 @defvar shell-command-history
372 A history list for arguments that are shell commands.
375 @defvar read-expression-history
376 A history list for arguments that are Lisp expressions to evaluate.
379 @defvar Info-minibuffer-history
380 A history list for Info mode's minibuffer.
383 @defvar Manual-page-minibuffer-history
384 A history list for @code{manual-entry}.
387 There are many other minibuffer history lists, defined by various
388 libraries. An @kbd{M-x apropos} search for @samp{history} should prove
389 fruitful in discovering them.
395 @dfn{Completion} is a feature that fills in the rest of a name
396 starting from an abbreviation for it. Completion works by comparing the
397 user's input against a list of valid names and determining how much of
398 the name is determined uniquely by what the user has typed. For
399 example, when you type @kbd{C-x b} (@code{switch-to-buffer}) and then
400 type the first few letters of the name of the buffer to which you wish
401 to switch, and then type @key{TAB} (@code{minibuffer-complete}), Emacs
402 extends the name as far as it can.
404 Standard XEmacs commands offer completion for names of symbols, files,
405 buffers, and processes; with the functions in this section, you can
406 implement completion for other kinds of names.
408 The @code{try-completion} function is the basic primitive for
409 completion: it returns the longest determined completion of a given
410 initial string, with a given set of strings to match against.
412 The function @code{completing-read} provides a higher-level interface
413 for completion. A call to @code{completing-read} specifies how to
414 determine the list of valid names. The function then activates the
415 minibuffer with a local keymap that binds a few keys to commands useful
416 for completion. Other functions provide convenient simple interfaces
417 for reading certain kinds of names with completion.
420 * Basic Completion:: Low-level functions for completing strings.
421 (These are too low level to use the minibuffer.)
422 * Minibuffer Completion:: Invoking the minibuffer with completion.
423 * Completion Commands:: Minibuffer commands that do completion.
424 * High-Level Completion:: Convenient special cases of completion
425 (reading buffer name, file name, etc.)
426 * Reading File Names:: Using completion to read file names.
427 * Programmed Completion:: Finding the completions for a given file name.
430 @node Basic Completion
431 @subsection Basic Completion Functions
433 The two functions @code{try-completion} and @code{all-completions}
434 have nothing in themselves to do with minibuffers. We describe them in
435 this chapter so as to keep them near the higher-level completion
436 features that do use the minibuffer.
438 @defun try-completion string collection &optional predicate
439 This function returns the longest common substring of all possible
440 completions of @var{string} in @var{collection}. The value of
441 @var{collection} must be an alist, an obarray, or a function that
442 implements a virtual set of strings (see below).
444 Completion compares @var{string} against each of the permissible
445 completions specified by @var{collection}; if the beginning of the
446 permissible completion equals @var{string}, it matches. If no permissible
447 completions match, @code{try-completion} returns @code{nil}. If only
448 one permissible completion matches, and the match is exact, then
449 @code{try-completion} returns @code{t}. Otherwise, the value is the
450 longest initial sequence common to all the permissible completions that
453 If @var{collection} is an alist (@pxref{Association Lists}), the
454 @sc{car}s of the alist elements form the set of permissible completions.
456 @cindex obarray in completion
457 If @var{collection} is an obarray (@pxref{Creating Symbols}), the names
458 of all symbols in the obarray form the set of permissible completions. The
459 global variable @code{obarray} holds an obarray containing the names of
460 all interned Lisp symbols.
462 Note that the only valid way to make a new obarray is to create it
463 empty and then add symbols to it one by one using @code{intern}.
464 Also, you cannot intern a given symbol in more than one obarray.
466 If the argument @var{predicate} is non-@code{nil}, then it must be a
467 function of one argument. It is used to test each possible match, and
468 the match is accepted only if @var{predicate} returns non-@code{nil}.
469 The argument given to @var{predicate} is either a cons cell from the alist
470 (the @sc{car} of which is a string) or else it is a symbol (@emph{not} a
471 symbol name) from the obarray.
473 You can also use a symbol that is a function as @var{collection}. Then
474 the function is solely responsible for performing completion;
475 @code{try-completion} returns whatever this function returns. The
476 function is called with three arguments: @var{string}, @var{predicate}
477 and @code{nil}. (The reason for the third argument is so that the same
478 function can be used in @code{all-completions} and do the appropriate
479 thing in either case.) @xref{Programmed Completion}.
481 In the first of the following examples, the string @samp{foo} is
482 matched by three of the alist @sc{car}s. All of the matches begin with
483 the characters @samp{fooba}, so that is the result. In the second
484 example, there is only one possible match, and it is exact, so the value
491 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)))
496 (try-completion "foo" '(("barfoo" 2) ("foo" 3)))
501 In the following example, numerous symbols begin with the characters
502 @samp{forw}, and all of them begin with the word @samp{forward}. In
503 most of the symbols, this is followed with a @samp{-}, but not in all,
504 so no more than @samp{forward} can be completed.
508 (try-completion "forw" obarray)
513 Finally, in the following example, only two of the three possible
514 matches pass the predicate @code{test} (the string @samp{foobaz} is
515 too short). Both of those begin with the string @samp{foobar}.
520 (> (length (car s)) 6))
526 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
533 @defun all-completions string collection &optional predicate nospace
534 This function returns a list of all possible completions of
535 @var{string}. The arguments to this function are the same as those of
536 @code{try-completion}.
538 If @var{collection} is a function, it is called with three arguments:
539 @var{string}, @var{predicate} and @code{t}; then @code{all-completions}
540 returns whatever the function returns. @xref{Programmed Completion}.
542 If @var{nospace} is non-@code{nil}, completions that start with a space
543 are ignored unless @var{string} also starts with a space.
545 Here is an example, using the function @code{test} shown in the
546 example for @code{try-completion}:
551 (> (length (car s)) 6))
558 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
560 @result{} ("foobar1" "foobar2")
565 @defvar completion-ignore-case
566 If the value of this variable is
567 non-@code{nil}, XEmacs does not consider case significant in completion.
570 @node Minibuffer Completion
571 @subsection Completion and the Minibuffer
573 This section describes the basic interface for reading from the
574 minibuffer with completion.
576 @defun completing-read prompt collection &optional predicate require-match initial hist default
577 This function reads a string in the minibuffer, assisting the user by
578 providing completion. It activates the minibuffer with prompt
579 @var{prompt}, which must be a string. If @var{initial} is
580 non-@code{nil}, @code{completing-read} inserts it into the minibuffer as
581 part of the input. Then it allows the user to edit the input, providing
582 several commands to attempt completion.
584 The actual completion is done by passing @var{collection} and
585 @var{predicate} to the function @code{try-completion}. This happens in
586 certain commands bound in the local keymaps used for completion.
588 If @var{require-match} is @code{t}, the usual minibuffer exit commands
589 won't exit unless the input completes to an element of @var{collection}.
590 If @var{require-match} is neither @code{nil} nor @code{t}, then the exit
591 commands won't exit unless the input typed is itself an element of
592 @var{collection}. If @var{require-match} is @code{nil}, the exit
593 commands work regardless of the input in the minibuffer.
595 However, empty input is always permitted, regardless of the value of
596 @var{require-match}; in that case, @code{completing-read} returns
597 @var{default}. The value of @var{default} (if non-@code{nil}) is also
598 available to the user through the history commands.
600 The user can exit with null input by typing @key{RET} with an empty
601 minibuffer. Then @code{completing-read} returns @code{""}. This is how
602 the user requests whatever default the command uses for the value being
603 read. The user can return using @key{RET} in this way regardless of the
604 value of @var{require-match}, and regardless of whether the empty string
605 is included in @var{collection}.
607 The function @code{completing-read} works by calling
608 @code{read-minibuffer}. It uses @code{minibuffer-local-completion-map}
609 as the keymap if @var{require-match} is @code{nil}, and uses
610 @code{minibuffer-local-must-match-map} if @var{require-match} is
611 non-@code{nil}. @xref{Completion Commands}.
613 The argument @var{hist} specifies which history list variable to use for
614 saving the input and for minibuffer history commands. It defaults to
615 @code{minibuffer-history}. @xref{Minibuffer History}.
617 Completion ignores case when comparing the input against the possible
618 matches, if the built-in variable @code{completion-ignore-case} is
619 non-@code{nil}. @xref{Basic Completion}.
621 Here's an example of using @code{completing-read}:
627 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
632 ;; @r{After evaluation of the preceding expression,}
633 ;; @r{the following appears in the minibuffer:}
635 ---------- Buffer: Minibuffer ----------
636 Complete a foo: fo@point{}
637 ---------- Buffer: Minibuffer ----------
642 If the user then types @kbd{@key{DEL} @key{DEL} b @key{RET}},
643 @code{completing-read} returns @code{barfoo}.
645 The @code{completing-read} function binds three variables to pass
646 information to the commands that actually do completion. These
647 variables are @code{minibuffer-completion-table},
648 @code{minibuffer-completion-predicate} and
649 @code{minibuffer-completion-confirm}. For more information about them,
650 see @ref{Completion Commands}.
653 @node Completion Commands
654 @subsection Minibuffer Commands That Do Completion
656 This section describes the keymaps, commands and user options used in
657 the minibuffer to do completion.
659 @defvar minibuffer-local-completion-map
660 @code{completing-read} uses this value as the local keymap when an
661 exact match of one of the completions is not required. By default, this
662 keymap makes the following bindings:
666 @code{minibuffer-completion-help}
669 @code{minibuffer-complete-word}
672 @code{minibuffer-complete}
676 with other characters bound as in @code{minibuffer-local-map}
677 (@pxref{Text from Minibuffer}).
680 @defvar minibuffer-local-must-match-map
681 @code{completing-read} uses this value as the local keymap when an
682 exact match of one of the completions is required. Therefore, no keys
683 are bound to @code{exit-minibuffer}, the command that exits the
684 minibuffer unconditionally. By default, this keymap makes the following
689 @code{minibuffer-completion-help}
692 @code{minibuffer-complete-word}
695 @code{minibuffer-complete}
698 @code{minibuffer-complete-and-exit}
701 @code{minibuffer-complete-and-exit}
705 with other characters bound as in @code{minibuffer-local-map}.
708 @defvar minibuffer-completion-table
709 The value of this variable is the alist or obarray used for completion
710 in the minibuffer. This is the global variable that contains what
711 @code{completing-read} passes to @code{try-completion}. It is used by
712 minibuffer completion commands such as @code{minibuffer-complete-word}.
715 @defvar minibuffer-completion-predicate
716 This variable's value is the predicate that @code{completing-read}
717 passes to @code{try-completion}. The variable is also used by the other
718 minibuffer completion functions.
721 @deffn Command minibuffer-complete-word
722 This function completes the minibuffer contents by at most a single
723 word. Even if the minibuffer contents have only one completion,
724 @code{minibuffer-complete-word} does not add any characters beyond the
725 first character that is not a word constituent. @xref{Syntax Tables}.
728 @deffn Command minibuffer-complete
729 This function completes the minibuffer contents as far as possible.
732 @deffn Command minibuffer-complete-and-exit
733 This function completes the minibuffer contents, and exits if
734 confirmation is not required, i.e., if
735 @code{minibuffer-completion-confirm} is @code{nil}. If confirmation
736 @emph{is} required, it is given by repeating this command
737 immediately---the command is programmed to work without confirmation
738 when run twice in succession.
741 @defvar minibuffer-completion-confirm
742 When the value of this variable is non-@code{nil}, XEmacs asks for
743 confirmation of a completion before exiting the minibuffer. The
744 function @code{minibuffer-complete-and-exit} checks the value of this
745 variable before it exits.
748 @deffn Command minibuffer-completion-help
749 This function creates a list of the possible completions of the
750 current minibuffer contents. It works by calling @code{all-completions}
751 using the value of the variable @code{minibuffer-completion-table} as
752 the @var{collection} argument, and the value of
753 @code{minibuffer-completion-predicate} as the @var{predicate} argument.
754 The list of completions is displayed as text in a buffer named
755 @samp{*Completions*}.
758 @defun display-completion-list completions
759 This function displays @var{completions} to the stream in
760 @code{standard-output}, usually a buffer. (@xref{Read and Print}, for more
761 information about streams.) The argument @var{completions} is normally
762 a list of completions just returned by @code{all-completions}, but it
763 does not have to be. Each element may be a symbol or a string, either
764 of which is simply printed, or a list of two strings, which is printed
765 as if the strings were concatenated.
767 This function is called by @code{minibuffer-completion-help}. The
768 most common way to use it is together with
769 @code{with-output-to-temp-buffer}, like this:
772 (with-output-to-temp-buffer "*Completions*"
773 (display-completion-list
774 (all-completions (buffer-string) my-alist)))
778 @defopt completion-auto-help
779 If this variable is non-@code{nil}, the completion commands
780 automatically display a list of possible completions whenever nothing
781 can be completed because the next character is not uniquely determined.
784 @node High-Level Completion
785 @subsection High-Level Completion Functions
787 This section describes the higher-level convenient functions for
788 reading certain sorts of names with completion.
790 In most cases, you should not call these functions in the middle of a
791 Lisp function. When possible, do all minibuffer input as part of
792 reading the arguments for a command, in the @code{interactive} spec.
793 @xref{Defining Commands}.
795 @defun read-buffer prompt &optional default existing
796 This function reads the name of a buffer and returns it as a string.
797 The argument @var{default} is the default name to use, the value to
798 return if the user exits with an empty minibuffer. If non-@code{nil},
799 it should be a string or a buffer. It is mentioned in the prompt, but
800 is not inserted in the minibuffer as initial input.
802 If @var{existing} is non-@code{nil}, then the name specified must be
803 that of an existing buffer. The usual commands to exit the minibuffer
804 do not exit if the text is not valid, and @key{RET} does completion to
805 attempt to find a valid name. (However, @var{default} is not checked
806 for validity; it is returned, whatever it is, if the user exits with the
809 In the following example, the user enters @samp{minibuffer.t}, and
810 then types @key{RET}. The argument @var{existing} is @code{t}, and the
811 only buffer name starting with the given input is
812 @samp{minibuffer.texi}, so that name is the value.
815 (read-buffer "Buffer name? " "foo" t)
817 ;; @r{After evaluation of the preceding expression,}
818 ;; @r{the following prompt appears,}
819 ;; @r{with an empty minibuffer:}
823 ---------- Buffer: Minibuffer ----------
824 Buffer name? (default foo) @point{}
825 ---------- Buffer: Minibuffer ----------
829 ;; @r{The user types @kbd{minibuffer.t @key{RET}}.}
830 @result{} "minibuffer.texi"
835 @defun read-command prompt
836 This function reads the name of a command and returns it as a Lisp
837 symbol. The argument @var{prompt} is used as in
838 @code{read-from-minibuffer}. Recall that a command is anything for
839 which @code{commandp} returns @code{t}, and a command name is a symbol
840 for which @code{commandp} returns @code{t}. @xref{Interactive Call}.
843 (read-command "Command name? ")
846 ;; @r{After evaluation of the preceding expression,}
847 ;; @r{the following prompt appears with an empty minibuffer:}
851 ---------- Buffer: Minibuffer ----------
853 ---------- Buffer: Minibuffer ----------
858 If the user types @kbd{forward-c @key{RET}}, then this function returns
861 The @code{read-command} function is a simplified interface to the
862 function @code{completing-read}. It uses the variable @code{obarray} so
863 as to complete in the set of extant Lisp symbols, and it uses the
864 @code{commandp} predicate so as to accept only command names:
866 @cindex @code{commandp} example
869 (read-command @var{prompt})
871 (intern (completing-read @var{prompt} obarray
877 @defun read-variable prompt
878 This function reads the name of a user variable and returns it as a
883 (read-variable "Variable name? ")
885 ;; @r{After evaluation of the preceding expression,}
886 ;; @r{the following prompt appears,}
887 ;; @r{with an empty minibuffer:}
891 ---------- Buffer: Minibuffer ----------
892 Variable name? @point{}
893 ---------- Buffer: Minibuffer ----------
898 If the user then types @kbd{fill-p @key{RET}}, @code{read-variable}
899 returns @code{fill-prefix}.
901 This function is similar to @code{read-command}, but uses the
902 predicate @code{user-variable-p} instead of @code{commandp}:
904 @cindex @code{user-variable-p} example
907 (read-variable @var{prompt})
910 (completing-read @var{prompt} obarray
911 'user-variable-p t nil))
916 @node Reading File Names
917 @subsection Reading File Names
919 Here is another high-level completion function, designed for reading a
920 file name. It provides special features including automatic insertion
921 of the default directory.
923 @defun read-file-name prompt &optional directory default existing initial
924 This function reads a file name in the minibuffer, prompting with
925 @var{prompt} and providing completion. If @var{default} is
926 non-@code{nil}, then the function returns @var{default} if the user just
927 types @key{RET}. @var{default} is not checked for validity; it is
928 returned, whatever it is, if the user exits with the minibuffer empty.
930 If @var{existing} is non-@code{nil}, then the user must specify the name
931 of an existing file; @key{RET} performs completion to make the name
932 valid if possible, and then refuses to exit if it is not valid. If the
933 value of @var{existing} is neither @code{nil} nor @code{t}, then
934 @key{RET} also requires confirmation after completion. If
935 @var{existing} is @code{nil}, then the name of a nonexistent file is
938 The argument @var{directory} specifies the directory to use for
939 completion of relative file names. If @code{insert-default-directory}
940 is non-@code{nil}, @var{directory} is also inserted in the minibuffer as
941 initial input. It defaults to the current buffer's value of
942 @code{default-directory}.
945 If you specify @var{initial}, that is an initial file name to insert in
946 the buffer (after @var{directory}, if that is inserted). In this
947 case, point goes at the beginning of @var{initial}. The default for
948 @var{initial} is @code{nil}---don't insert any file name. To see what
949 @var{initial} does, try the command @kbd{C-x C-v}.
955 (read-file-name "The file is ")
957 ;; @r{After evaluation of the preceding expression,}
958 ;; @r{the following appears in the minibuffer:}
962 ---------- Buffer: Minibuffer ----------
963 The file is /gp/gnu/elisp/@point{}
964 ---------- Buffer: Minibuffer ----------
969 Typing @kbd{manual @key{TAB}} results in the following:
973 ---------- Buffer: Minibuffer ----------
974 The file is /gp/gnu/elisp/manual.texi@point{}
975 ---------- Buffer: Minibuffer ----------
979 @c Wordy to avoid overfull hbox in smallbook mode.
981 If the user types @key{RET}, @code{read-file-name} returns the file name
982 as the string @code{"/gp/gnu/elisp/manual.texi"}.
985 @defopt insert-default-directory
986 This variable is used by @code{read-file-name}. Its value controls
987 whether @code{read-file-name} starts by placing the name of the default
988 directory in the minibuffer, plus the initial file name if any. If the
989 value of this variable is @code{nil}, then @code{read-file-name} does
990 not place any initial input in the minibuffer (unless you specify
991 initial input with the @var{initial} argument). In that case, the
992 default directory is still used for completion of relative file names,
993 but is not displayed.
999 ;; @r{Here the minibuffer starts out with the default directory.}
1000 (let ((insert-default-directory t))
1001 (read-file-name "The file is "))
1005 ---------- Buffer: Minibuffer ----------
1006 The file is ~lewis/manual/@point{}
1007 ---------- Buffer: Minibuffer ----------
1011 ;; @r{Here the minibuffer is empty and only the prompt}
1012 ;; @r{appears on its line.}
1013 (let ((insert-default-directory nil))
1014 (read-file-name "The file is "))
1018 ---------- Buffer: Minibuffer ----------
1019 The file is @point{}
1020 ---------- Buffer: Minibuffer ----------
1025 @node Programmed Completion
1026 @subsection Programmed Completion
1027 @cindex programmed completion
1029 Sometimes it is not possible to create an alist or an obarray
1030 containing all the intended possible completions. In such a case, you
1031 can supply your own function to compute the completion of a given string.
1032 This is called @dfn{programmed completion}.
1034 To use this feature, pass a symbol with a function definition as the
1035 @var{collection} argument to @code{completing-read}. The function
1036 @code{completing-read} arranges to pass your completion function along
1037 to @code{try-completion} and @code{all-completions}, which will then let
1038 your function do all the work.
1040 The completion function should accept three arguments:
1044 The string to be completed.
1047 The predicate function to filter possible matches, or @code{nil} if
1048 none. Your function should call the predicate for each possible match,
1049 and ignore the possible match if the predicate returns @code{nil}.
1052 A flag specifying the type of operation.
1055 There are three flag values for three operations:
1059 @code{nil} specifies @code{try-completion}. The completion function
1060 should return the completion of the specified string, or @code{t} if the
1061 string is a unique and exact match already, or @code{nil} if the string
1062 matches no possibility.
1064 If the string is an exact match for one possibility, but also matches
1065 other longer possibilities, the function should return the string, not
1069 @code{t} specifies @code{all-completions}. The completion function
1070 should return a list of all possible completions of the specified
1074 @code{lambda} specifies a test for an exact match. The completion
1075 function should return @code{t} if the specified string is an exact
1076 match for some possibility; @code{nil} otherwise.
1079 It would be consistent and clean for completion functions to allow
1080 lambda expressions (lists that are functions) as well as function
1081 symbols as @var{collection}, but this is impossible. Lists as
1082 completion tables are already assigned another meaning---as alists. It
1083 would be unreliable to fail to handle an alist normally because it is
1084 also a possible function. So you must arrange for any function you wish
1085 to use for completion to be encapsulated in a symbol.
1087 Emacs uses programmed completion when completing file names.
1088 @xref{File Name Completion}.
1090 @node Yes-or-No Queries
1091 @section Yes-or-No Queries
1092 @cindex asking the user questions
1093 @cindex querying the user
1094 @cindex yes-or-no questions
1096 This section describes functions used to ask the user a yes-or-no
1097 question. The function @code{y-or-n-p} can be answered with a single
1098 character; it is useful for questions where an inadvertent wrong answer
1099 will not have serious consequences. @code{yes-or-no-p} is suitable for
1100 more momentous questions, since it requires three or four characters to
1101 answer. Variations of these functions can be used to ask a yes-or-no
1102 question using a dialog box, or optionally using one.
1104 If either of these functions is called in a command that was invoked
1105 using the mouse, then it uses a dialog box or pop-up menu to ask the
1106 question. Otherwise, it uses keyboard input.
1108 Strictly speaking, @code{yes-or-no-p} uses the minibuffer and
1109 @code{y-or-n-p} does not; but it seems best to describe them together.
1111 @defun y-or-n-p prompt
1112 This function asks the user a question, expecting input in the echo
1113 area. It returns @code{t} if the user types @kbd{y}, @code{nil} if the
1114 user types @kbd{n}. This function also accepts @key{SPC} to mean yes
1115 and @key{DEL} to mean no. It accepts @kbd{C-]} to mean ``quit'', like
1116 @kbd{C-g}, because the question might look like a minibuffer and for
1117 that reason the user might try to use @kbd{C-]} to get out. The answer
1118 is a single character, with no @key{RET} needed to terminate it. Upper
1119 and lower case are equivalent.
1121 ``Asking the question'' means printing @var{prompt} in the echo area,
1122 followed by the string @w{@samp{(y or n) }}. If the input is not one of
1123 the expected answers (@kbd{y}, @kbd{n}, @kbd{@key{SPC}},
1124 @kbd{@key{DEL}}, or something that quits), the function responds
1125 @samp{Please answer y or n.}, and repeats the request.
1127 This function does not actually use the minibuffer, since it does not
1128 allow editing of the answer. It actually uses the echo area (@pxref{The
1129 Echo Area}), which uses the same screen space as the minibuffer. The
1130 cursor moves to the echo area while the question is being asked.
1132 The answers and their meanings, even @samp{y} and @samp{n}, are not
1133 hardwired. The keymap @code{query-replace-map} specifies them.
1134 @xref{Search and Replace}.
1136 In the following example, the user first types @kbd{q}, which is
1137 invalid. At the next prompt the user types @kbd{y}.
1141 (y-or-n-p "Do you need a lift? ")
1143 ;; @r{After evaluation of the preceding expression,}
1144 ;; @r{the following prompt appears in the echo area:}
1148 ---------- Echo area ----------
1149 Do you need a lift? (y or n)
1150 ---------- Echo area ----------
1153 ;; @r{If the user then types @kbd{q}, the following appears:}
1156 ---------- Echo area ----------
1157 Please answer y or n. Do you need a lift? (y or n)
1158 ---------- Echo area ----------
1161 ;; @r{When the user types a valid answer,}
1162 ;; @r{it is displayed after the question:}
1165 ---------- Echo area ----------
1166 Do you need a lift? (y or n) y
1167 ---------- Echo area ----------
1172 We show successive lines of echo area messages, but only one actually
1173 appears on the screen at a time.
1176 @defun yes-or-no-p prompt
1177 This function asks the user a question, expecting input in the
1178 minibuffer. It returns @code{t} if the user enters @samp{yes},
1179 @code{nil} if the user types @samp{no}. The user must type @key{RET} to
1180 finalize the response. Upper and lower case are equivalent.
1182 @code{yes-or-no-p} starts by displaying @var{prompt} in the echo area,
1183 followed by @w{@samp{(yes or no) }}. The user must type one of the
1184 expected responses; otherwise, the function responds @samp{Please answer
1185 yes or no.}, waits about two seconds and repeats the request.
1187 @code{yes-or-no-p} requires more work from the user than
1188 @code{y-or-n-p} and is appropriate for more crucial decisions.
1194 (yes-or-no-p "Do you really want to remove everything? ")
1196 ;; @r{After evaluation of the preceding expression,}
1197 ;; @r{the following prompt appears,}
1198 ;; @r{with an empty minibuffer:}
1202 ---------- Buffer: minibuffer ----------
1203 Do you really want to remove everything? (yes or no)
1204 ---------- Buffer: minibuffer ----------
1209 If the user first types @kbd{y @key{RET}}, which is invalid because this
1210 function demands the entire word @samp{yes}, it responds by displaying
1211 these prompts, with a brief pause between them:
1215 ---------- Buffer: minibuffer ----------
1216 Please answer yes or no.
1217 Do you really want to remove everything? (yes or no)
1218 ---------- Buffer: minibuffer ----------
1223 @c The rest is XEmacs stuff
1224 @defun yes-or-no-p-dialog-box prompt
1225 This function asks the user a ``y or n'' question with a popup dialog
1226 box. It returns @code{t} if the answer is ``yes''. @var{prompt} is the
1227 string to display to ask the question.
1230 The following functions ask a question either in the minibuffer or a
1231 dialog box, depending on whether the last user event (which presumably
1232 invoked this command) was a keyboard or mouse event. When XEmacs is
1233 running on a window system, the functions @code{y-or-n-p} and
1234 @code{yes-or-no-p} are replaced with the following functions, so that
1235 menu items bring up dialog boxes instead of minibuffer questions.
1237 @defun y-or-n-p-maybe-dialog-box prompt
1238 This function asks user a ``y or n'' question, using either a dialog box
1239 or the minibuffer, as appropriate.
1242 @defun yes-or-no-p-maybe-dialog-box prompt
1243 This function asks user a ``yes or no'' question, using either a dialog
1244 box or the minibuffer, as appropriate.
1247 @node Multiple Queries
1248 @section Asking Multiple Y-or-N Questions
1250 When you have a series of similar questions to ask, such as ``Do you
1251 want to save this buffer'' for each buffer in turn, you should use
1252 @code{map-y-or-n-p} to ask the collection of questions, rather than
1253 asking each question individually. This gives the user certain
1254 convenient facilities such as the ability to answer the whole series at
1257 @defun map-y-or-n-p prompter actor list &optional help action-alist
1258 This function, new in Emacs 19, asks the user a series of questions,
1259 reading a single-character answer in the echo area for each one.
1261 The value of @var{list} specifies the objects to ask questions about.
1262 It should be either a list of objects or a generator function. If it is
1263 a function, it should expect no arguments, and should return either the
1264 next object to ask about, or @code{nil} meaning stop asking questions.
1266 The argument @var{prompter} specifies how to ask each question. If
1267 @var{prompter} is a string, the question text is computed like this:
1270 (format @var{prompter} @var{object})
1274 where @var{object} is the next object to ask about (as obtained from
1277 If not a string, @var{prompter} should be a function of one argument
1278 (the next object to ask about) and should return the question text. If
1279 the value is a string, that is the question to ask the user. The
1280 function can also return @code{t} meaning do act on this object (and
1281 don't ask the user), or @code{nil} meaning ignore this object (and don't
1284 The argument @var{actor} says how to act on the answers that the user
1285 gives. It should be a function of one argument, and it is called with
1286 each object that the user says yes for. Its argument is always an
1287 object obtained from @var{list}.
1289 If the argument @var{help} is given, it should be a list of this form:
1292 (@var{singular} @var{plural} @var{action})
1296 where @var{singular} is a string containing a singular noun that
1297 describes the objects conceptually being acted on, @var{plural} is the
1298 corresponding plural noun, and @var{action} is a transitive verb
1299 describing what @var{actor} does.
1301 If you don't specify @var{help}, the default is @code{("object"
1302 "objects" "act on")}.
1304 Each time a question is asked, the user may enter @kbd{y}, @kbd{Y}, or
1305 @key{SPC} to act on that object; @kbd{n}, @kbd{N}, or @key{DEL} to skip
1306 that object; @kbd{!} to act on all following objects; @key{ESC} or
1307 @kbd{q} to exit (skip all following objects); @kbd{.} (period) to act on
1308 the current object and then exit; or @kbd{C-h} to get help. These are
1309 the same answers that @code{query-replace} accepts. The keymap
1310 @code{query-replace-map} defines their meaning for @code{map-y-or-n-p}
1311 as well as for @code{query-replace}; see @ref{Search and Replace}.
1313 You can use @var{action-alist} to specify additional possible answers
1314 and what they mean. It is an alist of elements of the form
1315 @code{(@var{char} @var{function} @var{help})}, each of which defines one
1316 additional answer. In this element, @var{char} is a character (the
1317 answer); @var{function} is a function of one argument (an object from
1318 @var{list}); @var{help} is a string.
1320 When the user responds with @var{char}, @code{map-y-or-n-p} calls
1321 @var{function}. If it returns non-@code{nil}, the object is considered
1322 ``acted upon'', and @code{map-y-or-n-p} advances to the next object in
1323 @var{list}. If it returns @code{nil}, the prompt is repeated for the
1326 If @code{map-y-or-n-p} is called in a command that was invoked using the
1327 mouse---more precisely, if @code{last-nonmenu-event} (@pxref{Command
1328 Loop Info}) is either @code{nil} or a list---then it uses a dialog box
1329 or pop-up menu to ask the question. In this case, it does not use
1330 keyboard input or the echo area. You can force use of the mouse or use
1331 of keyboard input by binding @code{last-nonmenu-event} to a suitable
1332 value around the call.
1334 The return value of @code{map-y-or-n-p} is the number of objects acted on.
1337 @node Reading a Password
1338 @section Reading a Password
1339 @cindex passwords, reading
1341 To read a password to pass to another program, you can use the
1342 function @code{read-passwd}.
1344 @defun read-passwd prompt &optional confirm default
1345 This function reads a password, prompting with @var{prompt}. It does
1346 not echo the password as the user types it; instead, it echoes @samp{.}
1347 for each character in the password.
1349 The optional argument @var{confirm}, if non-@code{nil}, says to read the
1350 password twice and insist it must be the same both times. If it isn't
1351 the same, the user has to type it over and over until the last two
1354 The optional argument @var{default} specifies the default password to
1355 return if the user enters empty input. It is translated to @samp{.}
1356 and inserted in the minibuffer. If @var{default} is @code{nil}, then
1357 @code{read-passwd} returns the null string in that case.
1360 @defopt passwd-invert-frame-when-keyboard-grabbed
1361 If non-nil swap the foreground and background colors of all faces while
1362 reading a password. Default values is @code{t} unless feature
1363 @code{infodock} is provided.
1367 This specifies the character echoed when typing a password. When nil,
1371 @node Minibuffer Misc
1372 @section Minibuffer Miscellany
1374 This section describes some basic functions and variables related to
1377 @deffn Command exit-minibuffer
1378 This command exits the active minibuffer. It is normally bound to
1379 keys in minibuffer local keymaps.
1382 @deffn Command self-insert-and-exit
1383 This command exits the active minibuffer after inserting the last
1384 character typed on the keyboard (found in @code{last-command-char};
1385 @pxref{Command Loop Info}).
1388 @deffn Command previous-history-element n
1389 This command replaces the minibuffer contents with the value of the
1390 @var{n}th previous (older) history element.
1393 @deffn Command next-history-element n
1394 This command replaces the minibuffer contents with the value of the
1395 @var{n}th more recent history element.
1398 @deffn Command previous-matching-history-element pattern
1399 This command replaces the minibuffer contents with the value of the
1400 previous (older) history element that matches @var{pattern} (a regular
1404 @deffn Command next-matching-history-element pattern
1405 This command replaces the minibuffer contents with the value of the next
1406 (newer) history element that matches @var{pattern} (a regular
1410 @defun minibuffer-prompt
1411 This function returns the prompt string of the currently active
1412 minibuffer. If no minibuffer is active, it returns @code{nil}.
1415 @defun minibuffer-prompt-width
1416 This function returns the display width of the prompt string of the
1417 currently active minibuffer. If no minibuffer is active, it returns 0.
1420 @defvar minibuffer-setup-hook
1421 This is a normal hook that is run whenever the minibuffer is entered.
1425 @defvar minibuffer-exit-hook
1426 This is a normal hook that is run whenever the minibuffer is exited.
1430 @defvar minibuffer-help-form
1431 The current value of this variable is used to rebind @code{help-form}
1432 locally inside the minibuffer (@pxref{Help Functions}).
1435 @defun active-minibuffer-window
1436 This function returns the currently active minibuffer window, or
1437 @code{nil} if none is currently active.
1440 @defun minibuffer-window &optional frame
1441 This function returns the minibuffer window used for frame @var{frame}.
1442 If @var{frame} is @code{nil}, that stands for the current frame. Note
1443 that the minibuffer window used by a frame need not be part of that
1444 frame---a frame that has no minibuffer of its own necessarily uses some
1445 other frame's minibuffer window.
1449 @defun window-minibuffer-p window
1450 This function returns non-@code{nil} if @var{window} is a minibuffer window.
1453 It is not correct to determine whether a given window is a minibuffer by
1454 comparing it with the result of @code{(minibuffer-window)}, because
1455 there can be more than one minibuffer window if there is more than one
1458 @defun minibuffer-window-active-p window
1459 This function returns non-@code{nil} if @var{window}, assumed to be
1460 a minibuffer window, is currently active.
1463 @defvar minibuffer-scroll-window
1464 If the value of this variable is non-@code{nil}, it should be a window
1465 object. When the function @code{scroll-other-window} is called in the
1466 minibuffer, it scrolls this window.
1469 Finally, some functions and variables deal with recursive minibuffers
1470 (@pxref{Recursive Editing}):
1472 @defun minibuffer-depth
1473 This function returns the current depth of activations of the
1474 minibuffer, a nonnegative integer. If no minibuffers are active, it
1478 @defopt enable-recursive-minibuffers
1479 If this variable is non-@code{nil}, you can invoke commands (such as
1480 @code{find-file}) that use minibuffers even while the minibuffer window
1481 is active. Such invocation produces a recursive editing level for a new
1482 minibuffer. The outer-level minibuffer is invisible while you are
1483 editing the inner one.
1485 This variable only affects invoking the minibuffer while the
1486 minibuffer window is selected. If you switch windows while in the
1487 minibuffer, you can always invoke minibuffer commands while some other
1492 In FSF Emacs 19, if a command name has a property
1493 @code{enable-recursive-minibuffers} that is non-@code{nil}, then the
1494 command can use the minibuffer to read arguments even if it is invoked
1495 from the minibuffer. The minibuffer command
1496 @code{next-matching-history-element} (normally @kbd{M-s} in the
1497 minibuffer) uses this feature.
1499 This is not implemented in XEmacs because it is a kludge. If you
1500 want to explicitly set the value of @code{enable-recursive-minibuffers}
1501 in this fashion, just use an evaluated interactive spec and bind
1502 @code{enable-recursive-minibuffers} while reading from the minibuffer.
1503 See the definition of @code{next-matching-history-element} in
1504 @file{lisp/minibuf.el}.