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 * Minibuffer Misc:: Various customization hooks and variables.
31 @node Intro to Minibuffers
32 @section Introduction to Minibuffers
34 In most ways, a minibuffer is a normal XEmacs buffer. Most operations
35 @emph{within} a buffer, such as editing commands, work normally in a
36 minibuffer. However, many operations for managing buffers do not apply
37 to minibuffers. The name of a minibuffer always has the form @w{@samp{
38 *Minibuf-@var{number}}}, and it cannot be changed. Minibuffers are
39 displayed only in special windows used only for minibuffers; these
40 windows always appear at the bottom of a frame. (Sometime frames have
41 no minibuffer window, and sometimes a special kind of frame contains
42 nothing but a minibuffer window; see @ref{Minibuffers and Frames}.)
44 The minibuffer's window is normally a single line. You can resize it
45 temporarily with the window sizing commands; it reverts to its normal
46 size when the minibuffer is exited. You can resize it permanently by
47 using the window sizing commands in the frame's other window, when the
48 minibuffer is not active. If the frame contains just a minibuffer, you
49 can change the minibuffer's size by changing the frame's size.
51 If a command uses a minibuffer while there is an active minibuffer,
52 this is called a @dfn{recursive minibuffer}. The first minibuffer is
53 named @w{@samp{ *Minibuf-0*}}. Recursive minibuffers are named by
54 incrementing the number at the end of the name. (The names begin with a
55 space so that they won't show up in normal buffer lists.) Of several
56 recursive minibuffers, the innermost (or most recently entered) is the
57 active minibuffer. We usually call this ``the'' minibuffer. You can
58 permit or forbid recursive minibuffers by setting the variable
59 @code{enable-recursive-minibuffers}.
61 Like other buffers, a minibuffer may use any of several local keymaps
62 (@pxref{Keymaps}); these contain various exit commands and in some cases
63 completion commands (@pxref{Completion}).
67 @code{minibuffer-local-map} is for ordinary input (no completion).
70 @code{minibuffer-local-ns-map} is similar, except that @key{SPC} exits
71 just like @key{RET}. This is used mainly for Mocklisp compatibility.
74 @code{minibuffer-local-completion-map} is for permissive completion.
77 @code{minibuffer-local-must-match-map} is for strict completion and
78 for cautious completion.
81 @node Text from Minibuffer
82 @section Reading Text Strings with the Minibuffer
84 Most often, the minibuffer is used to read text as a string. It can
85 also be used to read a Lisp object in textual form. The most basic
86 primitive for minibuffer input is @code{read-from-minibuffer}; it can do
89 In most cases, you should not call minibuffer input functions in the
90 middle of a Lisp function. Instead, do all minibuffer input as part of
91 reading the arguments for a command, in the @code{interactive} spec.
92 @xref{Defining Commands}.
94 @defun read-from-minibuffer prompt-string &optional initial-contents keymap read hist
95 This function is the most general way to get input through the
96 minibuffer. By default, it accepts arbitrary text and returns it as a
97 string; however, if @var{read} is non-@code{nil}, then it uses
98 @code{read} to convert the text into a Lisp object (@pxref{Input
101 The first thing this function does is to activate a minibuffer and
102 display it with @var{prompt-string} as the prompt. This value must be a
105 Then, if @var{initial-contents} is a string, @code{read-from-minibuffer}
106 inserts it into the minibuffer, leaving point at the end. The
107 minibuffer appears with this text as its contents.
110 The value of @var{initial-contents} may also be a cons cell of the form
111 @code{(@var{string} . @var{position})}. This means to insert
112 @var{string} in the minibuffer but put point @var{position} characters
113 from the beginning, rather than at the end.
115 If @var{keymap} is non-@code{nil}, that keymap is the local keymap to
116 use in the minibuffer. If @var{keymap} is omitted or @code{nil}, the
117 value of @code{minibuffer-local-map} is used as the keymap. Specifying
118 a keymap is the most important way to customize the minibuffer for
119 various applications such as completion.
121 The argument @var{hist} specifies which history list variable to use
122 for saving the input and for history commands used in the minibuffer.
123 It defaults to @code{minibuffer-history}. @xref{Minibuffer History}.
125 When the user types a command to exit the minibuffer,
126 @code{read-from-minibuffer} uses the text in the minibuffer to produce
127 its return value. Normally it simply makes a string containing that
128 text. However, if @var{read} is non-@code{nil},
129 @code{read-from-minibuffer} reads the text and returns the resulting
130 Lisp object, unevaluated. (@xref{Input Functions}, for information
134 @defun read-string prompt &optional initial
135 This function reads a string from the minibuffer and returns it. The
136 arguments @var{prompt} and @var{initial} are used as in
137 @code{read-from-minibuffer}. The keymap used is
138 @code{minibuffer-local-map}.
140 This is a simplified interface to the
141 @code{read-from-minibuffer} function:
145 (read-string @var{prompt} @var{initial})
147 (read-from-minibuffer @var{prompt} @var{initial} nil nil nil)
152 @defvar minibuffer-local-map
153 This is the default local keymap for reading from the minibuffer. By
154 default, it makes the following bindings:
158 @code{exit-minibuffer}
161 @code{exit-minibuffer}
164 @code{abort-recursive-edit}
167 @code{next-history-element}
170 @code{previous-history-element}
173 @code{next-matching-history-element}
176 @code{previous-matching-history-element}
180 @c In version 18, initial is required
182 @defun read-no-blanks-input prompt &optional initial
183 This function reads a string from the minibuffer, but does not allow
184 whitespace characters as part of the input: instead, those characters
185 terminate the input. The arguments @var{prompt} and @var{initial} are
186 used as in @code{read-from-minibuffer}.
188 This is a simplified interface to the @code{read-from-minibuffer}
189 function, and passes the value of the @code{minibuffer-local-ns-map}
190 keymap as the @var{keymap} argument for that function. Since the keymap
191 @code{minibuffer-local-ns-map} does not rebind @kbd{C-q}, it @emph{is}
192 possible to put a space into the string, by quoting it.
196 (read-no-blanks-input @var{prompt} @var{initial})
198 (read-from-minibuffer @var{prompt} @var{initial} minibuffer-local-ns-map)
203 @defvar minibuffer-local-ns-map
204 This built-in variable is the keymap used as the minibuffer local keymap
205 in the function @code{read-no-blanks-input}. By default, it makes the
206 following bindings, in addition to those of @code{minibuffer-local-map}:
210 @cindex @key{SPC} in minibuffer
211 @code{exit-minibuffer}
214 @cindex @key{TAB} in minibuffer
215 @code{exit-minibuffer}
218 @cindex @kbd{?} in minibuffer
219 @code{self-insert-and-exit}
223 @node Object from Minibuffer
224 @section Reading Lisp Objects with the Minibuffer
226 This section describes functions for reading Lisp objects with the
229 @defun read-minibuffer prompt &optional initial
230 This function reads a Lisp object in the minibuffer and returns it,
231 without evaluating it. The arguments @var{prompt} and @var{initial} are
232 used as in @code{read-from-minibuffer}.
234 This is a simplified interface to the
235 @code{read-from-minibuffer} function:
239 (read-minibuffer @var{prompt} @var{initial})
241 (read-from-minibuffer @var{prompt} @var{initial} nil t)
245 Here is an example in which we supply the string @code{"(testing)"} as
251 "Enter an expression: " (format "%s" '(testing)))
253 ;; @r{Here is how the minibuffer is displayed:}
257 ---------- Buffer: Minibuffer ----------
258 Enter an expression: (testing)@point{}
259 ---------- Buffer: Minibuffer ----------
264 The user can type @key{RET} immediately to use the initial input as a
265 default, or can edit the input.
268 @defun eval-minibuffer prompt &optional initial
269 This function reads a Lisp expression in the minibuffer, evaluates it,
270 then returns the result. The arguments @var{prompt} and @var{initial}
271 are used as in @code{read-from-minibuffer}.
273 This function simply evaluates the result of a call to
274 @code{read-minibuffer}:
278 (eval-minibuffer @var{prompt} @var{initial})
280 (eval (read-minibuffer @var{prompt} @var{initial}))
285 @defun edit-and-eval-command prompt form
286 This function reads a Lisp expression in the minibuffer, and then
287 evaluates it. The difference between this command and
288 @code{eval-minibuffer} is that here the initial @var{form} is not
289 optional and it is treated as a Lisp object to be converted to printed
290 representation rather than as a string of text. It is printed with
291 @code{prin1}, so if it is a string, double-quote characters (@samp{"})
292 appear in the initial text. @xref{Output Functions}.
294 The first thing @code{edit-and-eval-command} does is to activate the
295 minibuffer with @var{prompt} as the prompt. Then it inserts the printed
296 representation of @var{form} in the minibuffer, and lets the user edit.
297 When the user exits the minibuffer, the edited text is read with
298 @code{read} and then evaluated. The resulting value becomes the value
299 of @code{edit-and-eval-command}.
301 In the following example, we offer the user an expression with initial
302 text which is a valid form already:
306 (edit-and-eval-command "Please edit: " '(forward-word 1))
308 ;; @r{After evaluation of the preceding expression,}
309 ;; @r{the following appears in the minibuffer:}
313 ---------- Buffer: Minibuffer ----------
314 Please edit: (forward-word 1)@point{}
315 ---------- Buffer: Minibuffer ----------
320 Typing @key{RET} right away would exit the minibuffer and evaluate the
321 expression, thus moving point forward one word.
322 @code{edit-and-eval-command} returns @code{t} in this example.
325 @node Minibuffer History
326 @section Minibuffer History
327 @cindex minibuffer history
330 A @dfn{minibuffer history list} records previous minibuffer inputs so
331 the user can reuse them conveniently. A history list is actually a
332 symbol, not a list; it is a variable whose value is a list of strings
333 (previous inputs), most recent first.
335 There are many separate history lists, used for different kinds of
336 inputs. It's the Lisp programmer's job to specify the right history
337 list for each use of the minibuffer.
339 The basic minibuffer input functions @code{read-from-minibuffer} and
340 @code{completing-read} both accept an optional argument named @var{hist}
341 which is how you specify the history list. Here are the possible
346 Use @var{variable} (a symbol) as the history list.
348 @item (@var{variable} . @var{startpos})
349 Use @var{variable} (a symbol) as the history list, and assume that the
350 initial history position is @var{startpos} (an integer, counting from
351 zero which specifies the most recent element of the history).
353 If you specify @var{startpos}, then you should also specify that element
354 of the history as the initial minibuffer contents, for consistency.
357 If you don't specify @var{hist}, then the default history list
358 @code{minibuffer-history} is used. For other standard history lists,
359 see below. You can also create your own history list variable; just
360 initialize it to @code{nil} before the first use.
362 Both @code{read-from-minibuffer} and @code{completing-read} add new
363 elements to the history list automatically, and provide commands to
364 allow the user to reuse items on the list. The only thing your program
365 needs to do to use a history list is to initialize it and to pass its
366 name to the input functions when you wish. But it is safe to modify the
367 list by hand when the minibuffer input functions are not using it.
369 @defvar minibuffer-history
370 The default history list for minibuffer history input.
373 @defvar query-replace-history
374 A history list for arguments to @code{query-replace} (and similar
375 arguments to other commands).
378 @defvar file-name-history
379 A history list for file name arguments.
382 @defvar regexp-history
383 A history list for regular expression arguments.
386 @defvar extended-command-history
387 A history list for arguments that are names of extended commands.
390 @defvar shell-command-history
391 A history list for arguments that are shell commands.
394 @defvar read-expression-history
395 A history list for arguments that are Lisp expressions to evaluate.
398 @defvar Info-minibuffer-history
399 A history list for Info mode's minibuffer.
402 @defvar Manual-page-minibuffer-history
403 A history list for @code{manual-entry}.
406 There are many other minibuffer history lists, defined by various
407 libraries. An @kbd{M-x apropos} search for @samp{history} should prove
408 fruitful in discovering them.
414 @dfn{Completion} is a feature that fills in the rest of a name
415 starting from an abbreviation for it. Completion works by comparing the
416 user's input against a list of valid names and determining how much of
417 the name is determined uniquely by what the user has typed. For
418 example, when you type @kbd{C-x b} (@code{switch-to-buffer}) and then
419 type the first few letters of the name of the buffer to which you wish
420 to switch, and then type @key{TAB} (@code{minibuffer-complete}), Emacs
421 extends the name as far as it can.
423 Standard XEmacs commands offer completion for names of symbols, files,
424 buffers, and processes; with the functions in this section, you can
425 implement completion for other kinds of names.
427 The @code{try-completion} function is the basic primitive for
428 completion: it returns the longest determined completion of a given
429 initial string, with a given set of strings to match against.
431 The function @code{completing-read} provides a higher-level interface
432 for completion. A call to @code{completing-read} specifies how to
433 determine the list of valid names. The function then activates the
434 minibuffer with a local keymap that binds a few keys to commands useful
435 for completion. Other functions provide convenient simple interfaces
436 for reading certain kinds of names with completion.
439 * Basic Completion:: Low-level functions for completing strings.
440 (These are too low level to use the minibuffer.)
441 * Minibuffer Completion:: Invoking the minibuffer with completion.
442 * Completion Commands:: Minibuffer commands that do completion.
443 * High-Level Completion:: Convenient special cases of completion
444 (reading buffer name, file name, etc.)
445 * Reading File Names:: Using completion to read file names.
446 * Programmed Completion:: Finding the completions for a given file name.
449 @node Basic Completion
450 @subsection Basic Completion Functions
452 The two functions @code{try-completion} and @code{all-completions}
453 have nothing in themselves to do with minibuffers. We describe them in
454 this chapter so as to keep them near the higher-level completion
455 features that do use the minibuffer.
457 @defun try-completion string collection &optional predicate
458 This function returns the longest common substring of all possible
459 completions of @var{string} in @var{collection}. The value of
460 @var{collection} must be an alist, an obarray, or a function that
461 implements a virtual set of strings (see below).
463 Completion compares @var{string} against each of the permissible
464 completions specified by @var{collection}; if the beginning of the
465 permissible completion equals @var{string}, it matches. If no permissible
466 completions match, @code{try-completion} returns @code{nil}. If only
467 one permissible completion matches, and the match is exact, then
468 @code{try-completion} returns @code{t}. Otherwise, the value is the
469 longest initial sequence common to all the permissible completions that
472 If @var{collection} is an alist (@pxref{Association Lists}), the
473 @sc{car}s of the alist elements form the set of permissible completions.
475 @cindex obarray in completion
476 If @var{collection} is an obarray (@pxref{Creating Symbols}), the names
477 of all symbols in the obarray form the set of permissible completions. The
478 global variable @code{obarray} holds an obarray containing the names of
479 all interned Lisp symbols.
481 Note that the only valid way to make a new obarray is to create it
482 empty and then add symbols to it one by one using @code{intern}.
483 Also, you cannot intern a given symbol in more than one obarray.
485 If the argument @var{predicate} is non-@code{nil}, then it must be a
486 function of one argument. It is used to test each possible match, and
487 the match is accepted only if @var{predicate} returns non-@code{nil}.
488 The argument given to @var{predicate} is either a cons cell from the alist
489 (the @sc{car} of which is a string) or else it is a symbol (@emph{not} a
490 symbol name) from the obarray.
492 You can also use a symbol that is a function as @var{collection}. Then
493 the function is solely responsible for performing completion;
494 @code{try-completion} returns whatever this function returns. The
495 function is called with three arguments: @var{string}, @var{predicate}
496 and @code{nil}. (The reason for the third argument is so that the same
497 function can be used in @code{all-completions} and do the appropriate
498 thing in either case.) @xref{Programmed Completion}.
500 In the first of the following examples, the string @samp{foo} is
501 matched by three of the alist @sc{car}s. All of the matches begin with
502 the characters @samp{fooba}, so that is the result. In the second
503 example, there is only one possible match, and it is exact, so the value
510 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)))
515 (try-completion "foo" '(("barfoo" 2) ("foo" 3)))
520 In the following example, numerous symbols begin with the characters
521 @samp{forw}, and all of them begin with the word @samp{forward}. In
522 most of the symbols, this is followed with a @samp{-}, but not in all,
523 so no more than @samp{forward} can be completed.
527 (try-completion "forw" obarray)
532 Finally, in the following example, only two of the three possible
533 matches pass the predicate @code{test} (the string @samp{foobaz} is
534 too short). Both of those begin with the string @samp{foobar}.
539 (> (length (car s)) 6))
545 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
552 @defun all-completions string collection &optional predicate nospace
553 This function returns a list of all possible completions of
554 @var{string}. The parameters to this function are the same as to
555 @code{try-completion}.
557 If @var{collection} is a function, it is called with three arguments:
558 @var{string}, @var{predicate} and @code{t}; then @code{all-completions}
559 returns whatever the function returns. @xref{Programmed Completion}.
561 If @var{nospace} is non-@code{nil}, completions that start with a space
562 are ignored unless @var{string} also starts with a space.
564 Here is an example, using the function @code{test} shown in the
565 example for @code{try-completion}:
570 (> (length (car s)) 6))
577 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
579 @result{} ("foobar1" "foobar2")
584 @defvar completion-ignore-case
585 If the value of this variable is
586 non-@code{nil}, XEmacs does not consider case significant in completion.
589 @node Minibuffer Completion
590 @subsection Completion and the Minibuffer
592 This section describes the basic interface for reading from the
593 minibuffer with completion.
595 @defun completing-read prompt collection &optional predicate require-match initial hist
596 This function reads a string in the minibuffer, assisting the user by
597 providing completion. It activates the minibuffer with prompt
598 @var{prompt}, which must be a string. If @var{initial} is
599 non-@code{nil}, @code{completing-read} inserts it into the minibuffer as
600 part of the input. Then it allows the user to edit the input, providing
601 several commands to attempt completion.
603 The actual completion is done by passing @var{collection} and
604 @var{predicate} to the function @code{try-completion}. This happens in
605 certain commands bound in the local keymaps used for completion.
607 If @var{require-match} is @code{t}, the usual minibuffer exit commands
608 won't exit unless the input completes to an element of @var{collection}.
609 If @var{require-match} is neither @code{nil} nor @code{t}, then the exit
610 commands won't exit unless the input typed is itself an element of
611 @var{collection}. If @var{require-match} is @code{nil}, the exit
612 commands work regardless of the input in the minibuffer.
614 The user can exit with null input by typing @key{RET} with an empty
615 minibuffer. Then @code{completing-read} returns @code{nil}. This is
616 how the user requests whatever default the command uses for the value
617 being read. The user can return using @key{RET} in this way regardless
618 of the value of @var{require-match}.
620 The function @code{completing-read} works by calling
621 @code{read-minibuffer}. It uses @code{minibuffer-local-completion-map}
622 as the keymap if @var{require-match} is @code{nil}, and uses
623 @code{minibuffer-local-must-match-map} if @var{require-match} is
624 non-@code{nil}. @xref{Completion Commands}.
626 The argument @var{hist} specifies which history list variable to use for
627 saving the input and for minibuffer history commands. It defaults to
628 @code{minibuffer-history}. @xref{Minibuffer History}.
630 Completion ignores case when comparing the input against the possible
631 matches, if the built-in variable @code{completion-ignore-case} is
632 non-@code{nil}. @xref{Basic Completion}.
634 Here's an example of using @code{completing-read}:
640 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
645 ;; @r{After evaluation of the preceding expression,}
646 ;; @r{the following appears in the minibuffer:}
648 ---------- Buffer: Minibuffer ----------
649 Complete a foo: fo@point{}
650 ---------- Buffer: Minibuffer ----------
655 If the user then types @kbd{@key{DEL} @key{DEL} b @key{RET}},
656 @code{completing-read} returns @code{barfoo}.
658 The @code{completing-read} function binds three variables to pass
659 information to the commands that actually do completion. These
660 variables are @code{minibuffer-completion-table},
661 @code{minibuffer-completion-predicate} and
662 @code{minibuffer-completion-confirm}. For more information about them,
663 see @ref{Completion Commands}.
666 @node Completion Commands
667 @subsection Minibuffer Commands That Do Completion
669 This section describes the keymaps, commands and user options used in
670 the minibuffer to do completion.
672 @defvar minibuffer-local-completion-map
673 @code{completing-read} uses this value as the local keymap when an
674 exact match of one of the completions is not required. By default, this
675 keymap makes the following bindings:
679 @code{minibuffer-completion-help}
682 @code{minibuffer-complete-word}
685 @code{minibuffer-complete}
689 with other characters bound as in @code{minibuffer-local-map}
690 (@pxref{Text from Minibuffer}).
693 @defvar minibuffer-local-must-match-map
694 @code{completing-read} uses this value as the local keymap when an
695 exact match of one of the completions is required. Therefore, no keys
696 are bound to @code{exit-minibuffer}, the command that exits the
697 minibuffer unconditionally. By default, this keymap makes the following
702 @code{minibuffer-completion-help}
705 @code{minibuffer-complete-word}
708 @code{minibuffer-complete}
711 @code{minibuffer-complete-and-exit}
714 @code{minibuffer-complete-and-exit}
718 with other characters bound as in @code{minibuffer-local-map}.
721 @defvar minibuffer-completion-table
722 The value of this variable is the alist or obarray used for completion
723 in the minibuffer. This is the global variable that contains what
724 @code{completing-read} passes to @code{try-completion}. It is used by
725 minibuffer completion commands such as @code{minibuffer-complete-word}.
728 @defvar minibuffer-completion-predicate
729 This variable's value is the predicate that @code{completing-read}
730 passes to @code{try-completion}. The variable is also used by the other
731 minibuffer completion functions.
734 @deffn Command minibuffer-complete-word
735 This function completes the minibuffer contents by at most a single
736 word. Even if the minibuffer contents have only one completion,
737 @code{minibuffer-complete-word} does not add any characters beyond the
738 first character that is not a word constituent. @xref{Syntax Tables}.
741 @deffn Command minibuffer-complete
742 This function completes the minibuffer contents as far as possible.
745 @deffn Command minibuffer-complete-and-exit
746 This function completes the minibuffer contents, and exits if
747 confirmation is not required, i.e., if
748 @code{minibuffer-completion-confirm} is non-@code{nil}. If confirmation
749 @emph{is} required, it is given by repeating this command
750 immediately---the command is programmed to work without confirmation
751 when run twice in succession.
754 @defvar minibuffer-completion-confirm
755 When the value of this variable is non-@code{nil}, XEmacs asks for
756 confirmation of a completion before exiting the minibuffer. The
757 function @code{minibuffer-complete-and-exit} checks the value of this
758 variable before it exits.
761 @deffn Command minibuffer-completion-help
762 This function creates a list of the possible completions of the
763 current minibuffer contents. It works by calling @code{all-completions}
764 using the value of the variable @code{minibuffer-completion-table} as
765 the @var{collection} argument, and the value of
766 @code{minibuffer-completion-predicate} as the @var{predicate} argument.
767 The list of completions is displayed as text in a buffer named
768 @samp{*Completions*}.
771 @defun display-completion-list completions
772 This function displays @var{completions} to the stream in
773 @code{standard-output}, usually a buffer. (@xref{Read and Print}, for more
774 information about streams.) The argument @var{completions} is normally
775 a list of completions just returned by @code{all-completions}, but it
776 does not have to be. Each element may be a symbol or a string, either
777 of which is simply printed, or a list of two strings, which is printed
778 as if the strings were concatenated.
780 This function is called by @code{minibuffer-completion-help}. The
781 most common way to use it is together with
782 @code{with-output-to-temp-buffer}, like this:
785 (with-output-to-temp-buffer "*Completions*"
786 (display-completion-list
787 (all-completions (buffer-string) my-alist)))
791 @defopt completion-auto-help
792 If this variable is non-@code{nil}, the completion commands
793 automatically display a list of possible completions whenever nothing
794 can be completed because the next character is not uniquely determined.
797 @node High-Level Completion
798 @subsection High-Level Completion Functions
800 This section describes the higher-level convenient functions for
801 reading certain sorts of names with completion.
803 In most cases, you should not call these functions in the middle of a
804 Lisp function. When possible, do all minibuffer input as part of
805 reading the arguments for a command, in the @code{interactive} spec.
806 @xref{Defining Commands}.
808 @defun read-buffer prompt &optional default existing
809 This function reads the name of a buffer and returns it as a string.
810 The argument @var{default} is the default name to use, the value to
811 return if the user exits with an empty minibuffer. If non-@code{nil},
812 it should be a string or a buffer. It is mentioned in the prompt, but
813 is not inserted in the minibuffer as initial input.
815 If @var{existing} is non-@code{nil}, then the name specified must be
816 that of an existing buffer. The usual commands to exit the minibuffer
817 do not exit if the text is not valid, and @key{RET} does completion to
818 attempt to find a valid name. (However, @var{default} is not checked
819 for validity; it is returned, whatever it is, if the user exits with the
822 In the following example, the user enters @samp{minibuffer.t}, and
823 then types @key{RET}. The argument @var{existing} is @code{t}, and the
824 only buffer name starting with the given input is
825 @samp{minibuffer.texi}, so that name is the value.
828 (read-buffer "Buffer name? " "foo" t)
830 ;; @r{After evaluation of the preceding expression,}
831 ;; @r{the following prompt appears,}
832 ;; @r{with an empty minibuffer:}
836 ---------- Buffer: Minibuffer ----------
837 Buffer name? (default foo) @point{}
838 ---------- Buffer: Minibuffer ----------
842 ;; @r{The user types @kbd{minibuffer.t @key{RET}}.}
843 @result{} "minibuffer.texi"
848 @defun read-command prompt
849 This function reads the name of a command and returns it as a Lisp
850 symbol. The argument @var{prompt} is used as in
851 @code{read-from-minibuffer}. Recall that a command is anything for
852 which @code{commandp} returns @code{t}, and a command name is a symbol
853 for which @code{commandp} returns @code{t}. @xref{Interactive Call}.
856 (read-command "Command name? ")
859 ;; @r{After evaluation of the preceding expression,}
860 ;; @r{the following prompt appears with an empty minibuffer:}
864 ---------- Buffer: Minibuffer ----------
866 ---------- Buffer: Minibuffer ----------
871 If the user types @kbd{forward-c @key{RET}}, then this function returns
874 The @code{read-command} function is a simplified interface to the
875 function @code{completing-read}. It uses the variable @code{obarray} so
876 as to complete in the set of extant Lisp symbols, and it uses the
877 @code{commandp} predicate so as to accept only command names:
879 @cindex @code{commandp} example
882 (read-command @var{prompt})
884 (intern (completing-read @var{prompt} obarray
890 @defun read-variable prompt
891 This function reads the name of a user variable and returns it as a
896 (read-variable "Variable name? ")
898 ;; @r{After evaluation of the preceding expression,}
899 ;; @r{the following prompt appears,}
900 ;; @r{with an empty minibuffer:}
904 ---------- Buffer: Minibuffer ----------
905 Variable name? @point{}
906 ---------- Buffer: Minibuffer ----------
911 If the user then types @kbd{fill-p @key{RET}}, @code{read-variable}
912 returns @code{fill-prefix}.
914 This function is similar to @code{read-command}, but uses the
915 predicate @code{user-variable-p} instead of @code{commandp}:
917 @cindex @code{user-variable-p} example
920 (read-variable @var{prompt})
923 (completing-read @var{prompt} obarray
924 'user-variable-p t nil))
929 @node Reading File Names
930 @subsection Reading File Names
932 Here is another high-level completion function, designed for reading a
933 file name. It provides special features including automatic insertion
934 of the default directory.
936 @defun read-file-name prompt &optional directory default existing initial
937 This function reads a file name in the minibuffer, prompting with
938 @var{prompt} and providing completion. If @var{default} is
939 non-@code{nil}, then the function returns @var{default} if the user just
940 types @key{RET}. @var{default} is not checked for validity; it is
941 returned, whatever it is, if the user exits with the minibuffer empty.
943 If @var{existing} is non-@code{nil}, then the user must specify the name
944 of an existing file; @key{RET} performs completion to make the name
945 valid if possible, and then refuses to exit if it is not valid. If the
946 value of @var{existing} is neither @code{nil} nor @code{t}, then
947 @key{RET} also requires confirmation after completion. If
948 @var{existing} is @code{nil}, then the name of a nonexistent file is
951 The argument @var{directory} specifies the directory to use for
952 completion of relative file names. If @code{insert-default-directory}
953 is non-@code{nil}, @var{directory} is also inserted in the minibuffer as
954 initial input. It defaults to the current buffer's value of
955 @code{default-directory}.
958 If you specify @var{initial}, that is an initial file name to insert in
959 the buffer (after with @var{directory}, if that is inserted). In this
960 case, point goes at the beginning of @var{initial}. The default for
961 @var{initial} is @code{nil}---don't insert any file name. To see what
962 @var{initial} does, try the command @kbd{C-x C-v}.
968 (read-file-name "The file is ")
970 ;; @r{After evaluation of the preceding expression,}
971 ;; @r{the following appears in the minibuffer:}
975 ---------- Buffer: Minibuffer ----------
976 The file is /gp/gnu/elisp/@point{}
977 ---------- Buffer: Minibuffer ----------
982 Typing @kbd{manual @key{TAB}} results in the following:
986 ---------- Buffer: Minibuffer ----------
987 The file is /gp/gnu/elisp/manual.texi@point{}
988 ---------- Buffer: Minibuffer ----------
992 @c Wordy to avoid overfull hbox in smallbook mode.
994 If the user types @key{RET}, @code{read-file-name} returns the file name
995 as the string @code{"/gp/gnu/elisp/manual.texi"}.
998 @defopt insert-default-directory
999 This variable is used by @code{read-file-name}. Its value controls
1000 whether @code{read-file-name} starts by placing the name of the default
1001 directory in the minibuffer, plus the initial file name if any. If the
1002 value of this variable is @code{nil}, then @code{read-file-name} does
1003 not place any initial input in the minibuffer (unless you specify
1004 initial input with the @var{initial} argument). In that case, the
1005 default directory is still used for completion of relative file names,
1006 but is not displayed.
1012 ;; @r{Here the minibuffer starts out with the default directory.}
1013 (let ((insert-default-directory t))
1014 (read-file-name "The file is "))
1018 ---------- Buffer: Minibuffer ----------
1019 The file is ~lewis/manual/@point{}
1020 ---------- Buffer: Minibuffer ----------
1024 ;; @r{Here the minibuffer is empty and only the prompt}
1025 ;; @r{appears on its line.}
1026 (let ((insert-default-directory nil))
1027 (read-file-name "The file is "))
1031 ---------- Buffer: Minibuffer ----------
1032 The file is @point{}
1033 ---------- Buffer: Minibuffer ----------
1038 @node Programmed Completion
1039 @subsection Programmed Completion
1040 @cindex programmed completion
1042 Sometimes it is not possible to create an alist or an obarray
1043 containing all the intended possible completions. In such a case, you
1044 can supply your own function to compute the completion of a given string.
1045 This is called @dfn{programmed completion}.
1047 To use this feature, pass a symbol with a function definition as the
1048 @var{collection} argument to @code{completing-read}. The function
1049 @code{completing-read} arranges to pass your completion function along
1050 to @code{try-completion} and @code{all-completions}, which will then let
1051 your function do all the work.
1053 The completion function should accept three arguments:
1057 The string to be completed.
1060 The predicate function to filter possible matches, or @code{nil} if
1061 none. Your function should call the predicate for each possible match,
1062 and ignore the possible match if the predicate returns @code{nil}.
1065 A flag specifying the type of operation.
1068 There are three flag values for three operations:
1072 @code{nil} specifies @code{try-completion}. The completion function
1073 should return the completion of the specified string, or @code{t} if the
1074 string is an exact match already, or @code{nil} if the string matches no
1078 @code{t} specifies @code{all-completions}. The completion function
1079 should return a list of all possible completions of the specified
1083 @code{lambda} specifies a test for an exact match. The completion
1084 function should return @code{t} if the specified string is an exact
1085 match for some possibility; @code{nil} otherwise.
1088 It would be consistent and clean for completion functions to allow
1089 lambda expressions (lists that are functions) as well as function
1090 symbols as @var{collection}, but this is impossible. Lists as
1091 completion tables are already assigned another meaning---as alists. It
1092 would be unreliable to fail to handle an alist normally because it is
1093 also a possible function. So you must arrange for any function you wish
1094 to use for completion to be encapsulated in a symbol.
1096 Emacs uses programmed completion when completing file names.
1097 @xref{File Name Completion}.
1099 @node Yes-or-No Queries
1100 @section Yes-or-No Queries
1101 @cindex asking the user questions
1102 @cindex querying the user
1103 @cindex yes-or-no questions
1105 This section describes functions used to ask the user a yes-or-no
1106 question. The function @code{y-or-n-p} can be answered with a single
1107 character; it is useful for questions where an inadvertent wrong answer
1108 will not have serious consequences. @code{yes-or-no-p} is suitable for
1109 more momentous questions, since it requires three or four characters to
1110 answer. Variations of these functions can be used to ask a yes-or-no
1111 question using a dialog box, or optionally using one.
1113 If either of these functions is called in a command that was invoked
1114 using the mouse, then it uses a dialog box or pop-up menu to ask the
1115 question. Otherwise, it uses keyboard input.
1117 Strictly speaking, @code{yes-or-no-p} uses the minibuffer and
1118 @code{y-or-n-p} does not; but it seems best to describe them together.
1120 @defun y-or-n-p prompt
1121 This function asks the user a question, expecting input in the echo
1122 area. It returns @code{t} if the user types @kbd{y}, @code{nil} if the
1123 user types @kbd{n}. This function also accepts @key{SPC} to mean yes
1124 and @key{DEL} to mean no. It accepts @kbd{C-]} to mean ``quit'', like
1125 @kbd{C-g}, because the question might look like a minibuffer and for
1126 that reason the user might try to use @kbd{C-]} to get out. The answer
1127 is a single character, with no @key{RET} needed to terminate it. Upper
1128 and lower case are equivalent.
1130 ``Asking the question'' means printing @var{prompt} in the echo area,
1131 followed by the string @w{@samp{(y or n) }}. If the input is not one of
1132 the expected answers (@kbd{y}, @kbd{n}, @kbd{@key{SPC}},
1133 @kbd{@key{DEL}}, or something that quits), the function responds
1134 @samp{Please answer y or n.}, and repeats the request.
1136 This function does not actually use the minibuffer, since it does not
1137 allow editing of the answer. It actually uses the echo area (@pxref{The
1138 Echo Area}), which uses the same screen space as the minibuffer. The
1139 cursor moves to the echo area while the question is being asked.
1141 The answers and their meanings, even @samp{y} and @samp{n}, are not
1142 hardwired. The keymap @code{query-replace-map} specifies them.
1143 @xref{Search and Replace}.
1145 In the following example, the user first types @kbd{q}, which is
1146 invalid. At the next prompt the user types @kbd{y}.
1150 (y-or-n-p "Do you need a lift? ")
1152 ;; @r{After evaluation of the preceding expression,}
1153 ;; @r{the following prompt appears in the echo area:}
1157 ---------- Echo area ----------
1158 Do you need a lift? (y or n)
1159 ---------- Echo area ----------
1162 ;; @r{If the user then types @kbd{q}, the following appears:}
1165 ---------- Echo area ----------
1166 Please answer y or n. Do you need a lift? (y or n)
1167 ---------- Echo area ----------
1170 ;; @r{When the user types a valid answer,}
1171 ;; @r{it is displayed after the question:}
1174 ---------- Echo area ----------
1175 Do you need a lift? (y or n) y
1176 ---------- Echo area ----------
1181 We show successive lines of echo area messages, but only one actually
1182 appears on the screen at a time.
1185 @defun yes-or-no-p prompt
1186 This function asks the user a question, expecting input in the
1187 minibuffer. It returns @code{t} if the user enters @samp{yes},
1188 @code{nil} if the user types @samp{no}. The user must type @key{RET} to
1189 finalize the response. Upper and lower case are equivalent.
1191 @code{yes-or-no-p} starts by displaying @var{prompt} in the echo area,
1192 followed by @w{@samp{(yes or no) }}. The user must type one of the
1193 expected responses; otherwise, the function responds @samp{Please answer
1194 yes or no.}, waits about two seconds and repeats the request.
1196 @code{yes-or-no-p} requires more work from the user than
1197 @code{y-or-n-p} and is appropriate for more crucial decisions.
1203 (yes-or-no-p "Do you really want to remove everything? ")
1205 ;; @r{After evaluation of the preceding expression,}
1206 ;; @r{the following prompt appears,}
1207 ;; @r{with an empty minibuffer:}
1211 ---------- Buffer: minibuffer ----------
1212 Do you really want to remove everything? (yes or no)
1213 ---------- Buffer: minibuffer ----------
1218 If the user first types @kbd{y @key{RET}}, which is invalid because this
1219 function demands the entire word @samp{yes}, it responds by displaying
1220 these prompts, with a brief pause between them:
1224 ---------- Buffer: minibuffer ----------
1225 Please answer yes or no.
1226 Do you really want to remove everything? (yes or no)
1227 ---------- Buffer: minibuffer ----------
1232 @c The rest is XEmacs stuff
1233 @defun yes-or-no-p-dialog-box prompt
1234 This function asks the user a ``y or n'' question with a popup dialog
1235 box. It returns @code{t} if the answer is ``yes''. @var{prompt} is the
1236 string to display to ask the question.
1239 The following functions ask a question either in the minibuffer or a
1240 dialog box, depending on whether the last user event (which presumably
1241 invoked this command) was a keyboard or mouse event. When XEmacs is
1242 running on a window system, the functions @code{y-or-n-p} and
1243 @code{yes-or-no-p} are replaced with the following functions, so that
1244 menu items bring up dialog boxes instead of minibuffer questions.
1246 @defun y-or-n-p-maybe-dialog-box prompt
1247 This function asks user a ``y or n'' question, using either a dialog box
1248 or the minibuffer, as appropriate.
1251 @defun yes-or-no-p-maybe-dialog-box prompt
1252 This function asks user a ``yes or no'' question, using either a dialog
1253 box or the minibuffer, as appropriate.
1256 @node Multiple Queries
1257 @section Asking Multiple Y-or-N Questions
1259 When you have a series of similar questions to ask, such as ``Do you
1260 want to save this buffer'' for each buffer in turn, you should use
1261 @code{map-y-or-n-p} to ask the collection of questions, rather than
1262 asking each question individually. This gives the user certain
1263 convenient facilities such as the ability to answer the whole series at
1266 @defun map-y-or-n-p prompter actor list &optional help action-alist
1267 This function, new in Emacs 19, asks the user a series of questions,
1268 reading a single-character answer in the echo area for each one.
1270 The value of @var{list} specifies the objects to ask questions about.
1271 It should be either a list of objects or a generator function. If it is
1272 a function, it should expect no arguments, and should return either the
1273 next object to ask about, or @code{nil} meaning stop asking questions.
1275 The argument @var{prompter} specifies how to ask each question. If
1276 @var{prompter} is a string, the question text is computed like this:
1279 (format @var{prompter} @var{object})
1283 where @var{object} is the next object to ask about (as obtained from
1286 If not a string, @var{prompter} should be a function of one argument
1287 (the next object to ask about) and should return the question text. If
1288 the value is a string, that is the question to ask the user. The
1289 function can also return @code{t} meaning do act on this object (and
1290 don't ask the user), or @code{nil} meaning ignore this object (and don't
1293 The argument @var{actor} says how to act on the answers that the user
1294 gives. It should be a function of one argument, and it is called with
1295 each object that the user says yes for. Its argument is always an
1296 object obtained from @var{list}.
1298 If the argument @var{help} is given, it should be a list of this form:
1301 (@var{singular} @var{plural} @var{action})
1305 where @var{singular} is a string containing a singular noun that
1306 describes the objects conceptually being acted on, @var{plural} is the
1307 corresponding plural noun, and @var{action} is a transitive verb
1308 describing what @var{actor} does.
1310 If you don't specify @var{help}, the default is @code{("object"
1311 "objects" "act on")}.
1313 Each time a question is asked, the user may enter @kbd{y}, @kbd{Y}, or
1314 @key{SPC} to act on that object; @kbd{n}, @kbd{N}, or @key{DEL} to skip
1315 that object; @kbd{!} to act on all following objects; @key{ESC} or
1316 @kbd{q} to exit (skip all following objects); @kbd{.} (period) to act on
1317 the current object and then exit; or @kbd{C-h} to get help. These are
1318 the same answers that @code{query-replace} accepts. The keymap
1319 @code{query-replace-map} defines their meaning for @code{map-y-or-n-p}
1320 as well as for @code{query-replace}; see @ref{Search and Replace}.
1322 You can use @var{action-alist} to specify additional possible answers
1323 and what they mean. It is an alist of elements of the form
1324 @code{(@var{char} @var{function} @var{help})}, each of which defines one
1325 additional answer. In this element, @var{char} is a character (the
1326 answer); @var{function} is a function of one argument (an object from
1327 @var{list}); @var{help} is a string.
1329 When the user responds with @var{char}, @code{map-y-or-n-p} calls
1330 @var{function}. If it returns non-@code{nil}, the object is considered
1331 ``acted upon'', and @code{map-y-or-n-p} advances to the next object in
1332 @var{list}. If it returns @code{nil}, the prompt is repeated for the
1335 If @code{map-y-or-n-p} is called in a command that was invoked using the
1336 mouse---more precisely, if @code{last-nonmenu-event} (@pxref{Command
1337 Loop Info}) is either @code{nil} or a list---then it uses a dialog box
1338 or pop-up menu to ask the question. In this case, it does not use
1339 keyboard input or the echo area. You can force use of the mouse or use
1340 of keyboard input by binding @code{last-nonmenu-event} to a suitable
1341 value around the call.
1343 The return value of @code{map-y-or-n-p} is the number of objects acted on.
1346 @node Minibuffer Misc
1347 @section Minibuffer Miscellany
1349 This section describes some basic functions and variables related to
1352 @deffn Command exit-minibuffer
1353 This command exits the active minibuffer. It is normally bound to
1354 keys in minibuffer local keymaps.
1357 @deffn Command self-insert-and-exit
1358 This command exits the active minibuffer after inserting the last
1359 character typed on the keyboard (found in @code{last-command-char};
1360 @pxref{Command Loop Info}).
1363 @deffn Command previous-history-element n
1364 This command replaces the minibuffer contents with the value of the
1365 @var{n}th previous (older) history element.
1368 @deffn Command next-history-element n
1369 This command replaces the minibuffer contents with the value of the
1370 @var{n}th more recent history element.
1373 @deffn Command previous-matching-history-element pattern
1374 This command replaces the minibuffer contents with the value of the
1375 previous (older) history element that matches @var{pattern} (a regular
1379 @deffn Command next-matching-history-element pattern
1380 This command replaces the minibuffer contents with the value of the next
1381 (newer) history element that matches @var{pattern} (a regular
1385 @defun minibuffer-prompt
1386 This function returns the prompt string of the currently active
1387 minibuffer. If no minibuffer is active, it returns @code{nil}.
1390 @defun minibuffer-prompt-width
1391 This function returns the display width of the prompt string of the
1392 currently active minibuffer. If no minibuffer is active, it returns 0.
1395 @defvar minibuffer-setup-hook
1396 This is a normal hook that is run whenever the minibuffer is entered.
1400 @defvar minibuffer-exit-hook
1401 This is a normal hook that is run whenever the minibuffer is exited.
1405 @defvar minibuffer-help-form
1406 The current value of this variable is used to rebind @code{help-form}
1407 locally inside the minibuffer (@pxref{Help Functions}).
1410 @defun active-minibuffer-window
1411 This function returns the currently active minibuffer window, or
1412 @code{nil} if none is currently active.
1415 @defun minibuffer-window &optional frame
1416 This function returns the minibuffer window used for frame @var{frame}.
1417 If @var{frame} is @code{nil}, that stands for the current frame. Note
1418 that the minibuffer window used by a frame need not be part of that
1419 frame---a frame that has no minibuffer of its own necessarily uses some
1420 other frame's minibuffer window.
1424 @defun window-minibuffer-p window
1425 This function returns non-@code{nil} if @var{window} is a minibuffer window.
1428 It is not correct to determine whether a given window is a minibuffer by
1429 comparing it with the result of @code{(minibuffer-window)}, because
1430 there can be more than one minibuffer window if there is more than one
1433 @defun minibuffer-window-active-p window
1434 This function returns non-@code{nil} if @var{window}, assumed to be
1435 a minibuffer window, is currently active.
1438 @defvar minibuffer-scroll-window
1439 If the value of this variable is non-@code{nil}, it should be a window
1440 object. When the function @code{scroll-other-window} is called in the
1441 minibuffer, it scrolls this window.
1444 Finally, some functions and variables deal with recursive minibuffers
1445 (@pxref{Recursive Editing}):
1447 @defun minibuffer-depth
1448 This function returns the current depth of activations of the
1449 minibuffer, a nonnegative integer. If no minibuffers are active, it
1453 @defopt enable-recursive-minibuffers
1454 If this variable is non-@code{nil}, you can invoke commands (such as
1455 @code{find-file}) that use minibuffers even while in the minibuffer
1456 window. Such invocation produces a recursive editing level for a new
1457 minibuffer. The outer-level minibuffer is invisible while you are
1458 editing the inner one.
1460 This variable only affects invoking the minibuffer while the
1461 minibuffer window is selected. If you switch windows while in the
1462 minibuffer, you can always invoke minibuffer commands while some other
1467 In FSF Emacs 19, if a command name has a property
1468 @code{enable-recursive-minibuffers} that is non-@code{nil}, then the
1469 command can use the minibuffer to read arguments even if it is invoked
1470 from the minibuffer. The minibuffer command
1471 @code{next-matching-history-element} (normally @kbd{M-s} in the
1472 minibuffer) uses this feature.
1474 This is not implemented in XEmacs because it is a kludge. If you
1475 want to explicitly set the value of @code{enable-recursive-minibuffers}
1476 in this fashion, just use an evaluated interactive spec and bind
1477 @code{enable-recursive-minibuffers} while reading from the minibuffer.
1478 See the definition of @code{next-matching-history-element} in
1479 @file{lisp/prim/minibuf.el}.