*** empty log message ***
[emacs.git] / lispref / minibuf.texi
blob96a5e1a99ac8406fc0f1e4ccbe77a34d9817b36d
1 @c -*-texinfo-*-
2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001
4 @c   Free Software Foundation, Inc. 
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../info/minibuf
7 @node Minibuffers, Command Loop, Read and Print, Top
8 @chapter Minibuffers
9 @cindex arguments, reading
10 @cindex complex arguments
11 @cindex minibuffer
13   A @dfn{minibuffer} is a special buffer that Emacs commands use to read
14 arguments more complicated than the single numeric prefix argument.
15 These arguments include file names, buffer names, and command names (as
16 in @kbd{M-x}).  The minibuffer is displayed on the bottom line of the
17 frame, in the same place as the echo area, but only while it is in use
18 for reading an argument.
20 @menu
21 * Intro to Minibuffers::      Basic information about minibuffers.
22 * Text from Minibuffer::      How to read a straight text string.
23 * Object from Minibuffer::    How to read a Lisp object or expression.
24 * Minibuffer History::        Recording previous minibuffer inputs
25                                 so the user can reuse them.
26 * Completion::                How to invoke and customize completion.
27 * Yes-or-No Queries::         Asking a question with a simple answer.
28 * Multiple Queries::          Asking a series of similar questions.
29 * Reading a Password::        Reading a password from the terminal.
30 * Minibuffer Misc::           Various customization hooks and variables.
31 @end menu
33 @node Intro to Minibuffers
34 @section Introduction to Minibuffers
36   In most ways, a minibuffer is a normal Emacs buffer.  Most operations
37 @emph{within} a buffer, such as editing commands, work normally in a
38 minibuffer.  However, many operations for managing buffers do not apply
39 to minibuffers.  The name of a minibuffer always has the form @w{@samp{
40 *Minibuf-@var{number}}}, and it cannot be changed.  Minibuffers are
41 displayed only in special windows used only for minibuffers; these
42 windows always appear at the bottom of a frame.  (Sometimes frames have
43 no minibuffer window, and sometimes a special kind of frame contains
44 nothing but a minibuffer window; see @ref{Minibuffers and Frames}.)
46   The text in the minibuffer always starts with the @dfn{prompt string},
47 the text that was specified by the program that is using the minibuffer
48 to tell the user what sort of input to type.  This text is marked
49 read-only so you won't accidentally delete or change it.  It is also
50 marked as a field (@pxref{Fields}), so that certain motion functions,
51 including @code{beginning-of-line}, @code{forward-word},
52 @code{forward-sentence}, and @code{forward-paragraph}, stop at the
53 boundary between the prompt and the actual text.  (In older Emacs
54 versions, the prompt was displayed using a special mechanism and was not
55 part of the buffer contents.)
57   The minibuffer's window is normally a single line; it grows
58 automatically if necessary if the contents require more space.  You can
59 explicitly resize it temporarily with the window sizing commands; it
60 reverts to its normal size when the minibuffer is exited.  You can
61 resize it permanently by using the window sizing commands in the frame's
62 other window, when the minibuffer is not active.  If the frame contains
63 just a minibuffer, you can change the minibuffer's size by changing the
64 frame's size.
66   If a command uses a minibuffer while there is an active minibuffer,
67 this is called a @dfn{recursive minibuffer}.  The first minibuffer is
68 named @w{@samp{ *Minibuf-0*}}.  Recursive minibuffers are named by
69 incrementing the number at the end of the name.  (The names begin with a
70 space so that they won't show up in normal buffer lists.)  Of several
71 recursive minibuffers, the innermost (or most recently entered) is the
72 active minibuffer.  We usually call this ``the'' minibuffer.  You can
73 permit or forbid recursive minibuffers by setting the variable
74 @code{enable-recursive-minibuffers} or by putting properties of that
75 name on command symbols (@pxref{Minibuffer Misc}).
77   Like other buffers, a minibuffer may use any of several local keymaps
78 (@pxref{Keymaps}); these contain various exit commands and in some cases
79 completion commands (@pxref{Completion}).
81 @itemize @bullet
82 @item
83 @code{minibuffer-local-map} is for ordinary input (no completion).
85 @item
86 @code{minibuffer-local-ns-map} is similar, except that @key{SPC} exits
87 just like @key{RET}.  This is used mainly for Mocklisp compatibility.
89 @item
90 @code{minibuffer-local-completion-map} is for permissive completion.
92 @item
93 @code{minibuffer-local-must-match-map} is for strict completion and
94 for cautious completion.
95 @end itemize
97   When Emacs is running in batch mode, any request to read from the
98 minibuffer actually reads a line from the standard input descriptor that
99 was supplied when Emacs was started.
101 @node Text from Minibuffer
102 @section Reading Text Strings with the Minibuffer
104   Most often, the minibuffer is used to read text as a string.  It can
105 also be used to read a Lisp object in textual form.  The most basic
106 primitive for minibuffer input is @code{read-from-minibuffer}; it can do
107 either one.
109   In most cases, you should not call minibuffer input functions in the
110 middle of a Lisp function.  Instead, do all minibuffer input as part of
111 reading the arguments for a command, in the @code{interactive}
112 specification.  @xref{Defining Commands}.
114 @defun read-from-minibuffer prompt-string &optional initial-contents keymap read hist default inherit-input-method
115 This function is the most general way to get input through the
116 minibuffer.  By default, it accepts arbitrary text and returns it as a
117 string; however, if @var{read} is non-@code{nil}, then it uses
118 @code{read} to convert the text into a Lisp object (@pxref{Input
119 Functions}).
121 The first thing this function does is to activate a minibuffer and
122 display it with @var{prompt-string} as the prompt.  This value must be a
123 string.  Then the user can edit text in the minibuffer.
125 When the user types a command to exit the minibuffer,
126 @code{read-from-minibuffer} constructs the return value from the text in
127 the minibuffer.  Normally it returns a string containing that text.
128 However, if @var{read} is non-@code{nil}, @code{read-from-minibuffer}
129 reads the text and returns the resulting Lisp object, unevaluated.
130 (@xref{Input Functions}, for information about reading.)
132 The argument @var{default} specifies a default value to make available
133 through the history commands.  It should be a string, or @code{nil}.  If
134 @var{read} is non-@code{nil}, then @var{default} is also used as the
135 input to @code{read}, if the user enters empty input.  However, in the
136 usual case (where @var{read} is @code{nil}), @code{read-from-minibuffer}
137 does not return @var{default} when the user enters empty input; it
138 returns an empty string, @code{""}.  In this respect, it is different
139 from all the other minibuffer input functions in this chapter.
141 If @var{keymap} is non-@code{nil}, that keymap is the local keymap to
142 use in the minibuffer.  If @var{keymap} is omitted or @code{nil}, the
143 value of @code{minibuffer-local-map} is used as the keymap.  Specifying
144 a keymap is the most important way to customize the minibuffer for
145 various applications such as completion.
147 The argument @var{hist} specifies which history list variable to use
148 for saving the input and for history commands used in the minibuffer.
149 It defaults to @code{minibuffer-history}.  @xref{Minibuffer History}.
151 If the variable @code{minibuffer-allow-text-properties} is
152 non-@code{nil}, then the string which is returned includes whatever text
153 properties were present in the minibuffer.  Otherwise all the text
154 properties are stripped when the value is returned.
156 If the argument @var{inherit-input-method} is non-@code{nil}, then the
157 minibuffer inherits the current input method (@pxref{Input Methods}) and
158 the setting of @code{enable-multibyte-characters} (@pxref{Text
159 Representations}) from whichever buffer was current before entering the
160 minibuffer.
162 If @var{initial-contents} is a string, @code{read-from-minibuffer}
163 inserts it into the minibuffer, leaving point at the end, before the
164 user starts to edit the text.  The minibuffer appears with this text as
165 its initial contents.
167 Alternatively, @var{initial-contents} can be a cons cell of the form
168 @code{(@var{string} . @var{position})}.  This means to insert
169 @var{string} in the minibuffer but put point @var{position} characters
170 from the beginning, rather than at the end.
172 @strong{Usage note:} The @var{initial-contents} argument and the
173 @var{default} argument are two alternative features for more or less the
174 same job.  It does not make sense to use both features in a single call
175 to @code{read-from-minibuffer}.  In general, we recommend using
176 @var{default}, since this permits the user to insert the default value
177 when it is wanted, but does not burden the user with deleting it from
178 the minibuffer on other occasions.
179 @end defun
181 @defun read-string prompt &optional initial history default inherit-input-method
182 This function reads a string from the minibuffer and returns it.  The
183 arguments @var{prompt} and @var{initial} are used as in
184 @code{read-from-minibuffer}.  The keymap used is
185 @code{minibuffer-local-map}.
187 The optional argument @var{history}, if non-nil, specifies a history
188 list and optionally the initial position in the list.  The optional
189 argument @var{default} specifies a default value to return if the user
190 enters null input; it should be a string.  The optional argument
191 @var{inherit-input-method} specifies whether to inherit the current
192 buffer's input method.
194 This function is a simplified interface to the
195 @code{read-from-minibuffer} function:
197 @smallexample
198 @group
199 (read-string @var{prompt} @var{initial} @var{history} @var{default} @var{inherit})
200 @equiv{}
201 (let ((value
202        (read-from-minibuffer @var{prompt} @var{initial} nil nil
203                              @var{history} @var{default} @var{inherit})))
204   (if (equal value "")
205       @var{default}
206     value))
207 @end group
208 @end smallexample
209 @end defun
211 @defvar minibuffer-allow-text-properties
212 If this variable is @code{nil}, then @code{read-from-minibuffer} strips
213 all text properties from the minibuffer input before returning it.
214 Since all minibuffer input uses @code{read-from-minibuffer}, this
215 variable applies to all minibuffer input.
217 Note that the completion functions discard text properties unconditionally,
218 regardless of the value of this variable.
219 @end defvar
221 @defvar minibuffer-local-map
222 This is the default local keymap for reading from the minibuffer.  By
223 default, it makes the following bindings:
225 @table @asis
226 @item @kbd{C-j}
227 @code{exit-minibuffer}
229 @item @key{RET}
230 @code{exit-minibuffer}
232 @item @kbd{C-g}
233 @code{abort-recursive-edit}
235 @item @kbd{M-n}
236 @code{next-history-element}
238 @item @kbd{M-p}
239 @code{previous-history-element}
241 @item @kbd{M-r}
242 @code{next-matching-history-element}
244 @item @kbd{M-s}
245 @code{previous-matching-history-element}
246 @end table
247 @end defvar
249 @c In version 18, initial is required
250 @c Emacs 19 feature
251 @defun read-no-blanks-input prompt &optional initial inherit-input-method
252 This function reads a string from the minibuffer, but does not allow
253 whitespace characters as part of the input: instead, those characters
254 terminate the input.  The arguments @var{prompt}, @var{initial}, and
255 @var{inherit-input-method} are used as in @code{read-from-minibuffer}.
257 This is a simplified interface to the @code{read-from-minibuffer}
258 function, and passes the value of the @code{minibuffer-local-ns-map}
259 keymap as the @var{keymap} argument for that function.  Since the keymap
260 @code{minibuffer-local-ns-map} does not rebind @kbd{C-q}, it @emph{is}
261 possible to put a space into the string, by quoting it.
263 @smallexample
264 @group
265 (read-no-blanks-input @var{prompt} @var{initial})
266 @equiv{}
267 (read-from-minibuffer @var{prompt} @var{initial} minibuffer-local-ns-map)
268 @end group
269 @end smallexample
270 @end defun
272 @defvar minibuffer-local-ns-map
273 This built-in variable is the keymap used as the minibuffer local keymap
274 in the function @code{read-no-blanks-input}.  By default, it makes the
275 following bindings, in addition to those of @code{minibuffer-local-map}:
277 @table @asis
278 @item @key{SPC}
279 @cindex @key{SPC} in minibuffer
280 @code{exit-minibuffer}
282 @item @key{TAB}
283 @cindex @key{TAB} in minibuffer
284 @code{exit-minibuffer}
286 @item @kbd{?}
287 @cindex @kbd{?} in minibuffer
288 @code{self-insert-and-exit}
289 @end table
290 @end defvar
292 @node Object from Minibuffer
293 @section Reading Lisp Objects with the Minibuffer
295   This section describes functions for reading Lisp objects with the
296 minibuffer.
298 @defun read-minibuffer prompt &optional initial
299 This function reads a Lisp object using the minibuffer, and returns it
300 without evaluating it.  The arguments @var{prompt} and @var{initial} are
301 used as in @code{read-from-minibuffer}.
303 This is a simplified interface to the
304 @code{read-from-minibuffer} function:
306 @smallexample
307 @group
308 (read-minibuffer @var{prompt} @var{initial})
309 @equiv{}
310 (read-from-minibuffer @var{prompt} @var{initial} nil t)
311 @end group
312 @end smallexample
314 Here is an example in which we supply the string @code{"(testing)"} as
315 initial input:
317 @smallexample
318 @group
319 (read-minibuffer
320  "Enter an expression: " (format "%s" '(testing)))
322 ;; @r{Here is how the minibuffer is displayed:}
323 @end group
325 @group
326 ---------- Buffer: Minibuffer ----------
327 Enter an expression: (testing)@point{}
328 ---------- Buffer: Minibuffer ----------
329 @end group
330 @end smallexample
332 @noindent
333 The user can type @key{RET} immediately to use the initial input as a
334 default, or can edit the input.
335 @end defun
337 @defun eval-minibuffer prompt &optional initial
338 This function reads a Lisp expression using the minibuffer, evaluates
339 it, then returns the result.  The arguments @var{prompt} and
340 @var{initial} are used as in @code{read-from-minibuffer}.
342 This function simply evaluates the result of a call to
343 @code{read-minibuffer}:
345 @smallexample
346 @group
347 (eval-minibuffer @var{prompt} @var{initial})
348 @equiv{}
349 (eval (read-minibuffer @var{prompt} @var{initial}))
350 @end group
351 @end smallexample
352 @end defun
354 @defun edit-and-eval-command prompt form
355 This function reads a Lisp expression in the minibuffer, and then
356 evaluates it.  The difference between this command and
357 @code{eval-minibuffer} is that here the initial @var{form} is not
358 optional and it is treated as a Lisp object to be converted to printed
359 representation rather than as a string of text.  It is printed with
360 @code{prin1}, so if it is a string, double-quote characters (@samp{"})
361 appear in the initial text.  @xref{Output Functions}.
363 The first thing @code{edit-and-eval-command} does is to activate the
364 minibuffer with @var{prompt} as the prompt.  Then it inserts the printed
365 representation of @var{form} in the minibuffer, and lets the user edit it.
366 When the user exits the minibuffer, the edited text is read with
367 @code{read} and then evaluated.  The resulting value becomes the value
368 of @code{edit-and-eval-command}.
370 In the following example, we offer the user an expression with initial
371 text which is a valid form already:
373 @smallexample
374 @group
375 (edit-and-eval-command "Please edit: " '(forward-word 1))
377 ;; @r{After evaluation of the preceding expression,} 
378 ;;   @r{the following appears in the minibuffer:}
379 @end group
381 @group
382 ---------- Buffer: Minibuffer ----------
383 Please edit: (forward-word 1)@point{}
384 ---------- Buffer: Minibuffer ----------
385 @end group
386 @end smallexample
388 @noindent
389 Typing @key{RET} right away would exit the minibuffer and evaluate the
390 expression, thus moving point forward one word.
391 @code{edit-and-eval-command} returns @code{nil} in this example.
392 @end defun
394 @node Minibuffer History
395 @section Minibuffer History
396 @cindex minibuffer history
397 @cindex history list
399   A @dfn{minibuffer history list} records previous minibuffer inputs so
400 the user can reuse them conveniently.  A history list is actually a
401 symbol, not a list; it is a variable whose value is a list of strings
402 (previous inputs), most recent first.
404   There are many separate history lists, used for different kinds of
405 inputs.  It's the Lisp programmer's job to specify the right history
406 list for each use of the minibuffer.
408   The basic minibuffer input functions @code{read-from-minibuffer} and
409 @code{completing-read} both accept an optional argument named @var{hist}
410 which is how you specify the history list.  Here are the possible
411 values:
413 @table @asis
414 @item @var{variable}
415 Use @var{variable} (a symbol) as the history list.
417 @item (@var{variable} . @var{startpos})
418 Use @var{variable} (a symbol) as the history list, and assume that the
419 initial history position is @var{startpos} (an integer, counting from
420 zero which specifies the most recent element of the history).
422 If you specify @var{startpos}, then you should also specify that element
423 of the history as the initial minibuffer contents, for consistency.
424 @end table
426   If you don't specify @var{hist}, then the default history list
427 @code{minibuffer-history} is used.  For other standard history lists,
428 see below.  You can also create your own history list variable; just
429 initialize it to @code{nil} before the first use.
431   Both @code{read-from-minibuffer} and @code{completing-read} add new
432 elements to the history list automatically, and provide commands to
433 allow the user to reuse items on the list.  The only thing your program
434 needs to do to use a history list is to initialize it and to pass its
435 name to the input functions when you wish.  But it is safe to modify the
436 list by hand when the minibuffer input functions are not using it.
438   Here are some of the standard minibuffer history list variables:
440 @defvar minibuffer-history
441 The default history list for minibuffer history input.
442 @end defvar
444 @defvar query-replace-history
445 A history list for arguments to @code{query-replace} (and similar
446 arguments to other commands).
447 @end defvar
449 @defvar file-name-history
450 A history list for file-name arguments.
451 @end defvar
453 @defvar buffer-name-history
454 A history list for buffer-name arguments.
455 @end defvar
457 @defvar regexp-history
458 A history list for regular expression arguments.
459 @end defvar
461 @defvar extended-command-history
462 A history list for arguments that are names of extended commands.
463 @end defvar
465 @defvar shell-command-history
466 A history list for arguments that are shell commands.
467 @end defvar
469 @defvar read-expression-history
470 A history list for arguments that are Lisp expressions to evaluate.
471 @end defvar
473 @node Completion
474 @section Completion
475 @cindex completion
477   @dfn{Completion} is a feature that fills in the rest of a name
478 starting from an abbreviation for it.  Completion works by comparing the
479 user's input against a list of valid names and determining how much of
480 the name is determined uniquely by what the user has typed.  For
481 example, when you type @kbd{C-x b} (@code{switch-to-buffer}) and then
482 type the first few letters of the name of the buffer to which you wish
483 to switch, and then type @key{TAB} (@code{minibuffer-complete}), Emacs
484 extends the name as far as it can.
486   Standard Emacs commands offer completion for names of symbols, files,
487 buffers, and processes; with the functions in this section, you can
488 implement completion for other kinds of names.
490   The @code{try-completion} function is the basic primitive for
491 completion: it returns the longest determined completion of a given
492 initial string, with a given set of strings to match against.
494   The function @code{completing-read} provides a higher-level interface
495 for completion.  A call to @code{completing-read} specifies how to
496 determine the list of valid names.  The function then activates the
497 minibuffer with a local keymap that binds a few keys to commands useful
498 for completion.  Other functions provide convenient simple interfaces
499 for reading certain kinds of names with completion.
501 @menu
502 * Basic Completion::       Low-level functions for completing strings.
503                              (These are too low level to use the minibuffer.)
504 * Minibuffer Completion::  Invoking the minibuffer with completion.
505 * Completion Commands::    Minibuffer commands that do completion.
506 * High-Level Completion::  Convenient special cases of completion
507                              (reading buffer name, file name, etc.)
508 * Reading File Names::     Using completion to read file names.
509 * Programmed Completion::  Finding the completions for a given file name.
510 @end menu
512 @node Basic Completion
513 @subsection Basic Completion Functions
515   The two functions @code{try-completion} and @code{all-completions}
516 have nothing in themselves to do with minibuffers.  We describe them in
517 this chapter so as to keep them near the higher-level completion
518 features that do use the minibuffer.
520 @defun try-completion string collection &optional predicate
521 This function returns the longest common substring of all possible
522 completions of @var{string} in @var{collection}.  The value of
523 @var{collection} must be an alist, an obarray, or a function that
524 implements a virtual set of strings (see below).
526 Completion compares @var{string} against each of the permissible
527 completions specified by @var{collection}; if the beginning of the
528 permissible completion equals @var{string}, it matches.  If no permissible
529 completions match, @code{try-completion} returns @code{nil}.  If only
530 one permissible completion matches, and the match is exact, then
531 @code{try-completion} returns @code{t}.  Otherwise, the value is the
532 longest initial sequence common to all the permissible completions that
533 match.
535 If @var{collection} is an alist (@pxref{Association Lists}), the
536 @sc{car}s of the alist elements form the set of permissible completions.
538 @cindex obarray in completion
539 If @var{collection} is an obarray (@pxref{Creating Symbols}), the names
540 of all symbols in the obarray form the set of permissible completions.  The
541 global variable @code{obarray} holds an obarray containing the names of
542 all interned Lisp symbols.
544 Note that the only valid way to make a new obarray is to create it
545 empty and then add symbols to it one by one using @code{intern}.
546 Also, you cannot intern a given symbol in more than one obarray.
548 If the argument @var{predicate} is non-@code{nil}, then it must be a
549 function of one argument.  It is used to test each possible match, and
550 the match is accepted only if @var{predicate} returns non-@code{nil}.
551 The argument given to @var{predicate} is either a cons cell from the alist
552 (the @sc{car} of which is a string) or else it is a symbol (@emph{not} a
553 symbol name) from the obarray.
555 You can also use a symbol that is a function as @var{collection}.  Then
556 the function is solely responsible for performing completion;
557 @code{try-completion} returns whatever this function returns.  The
558 function is called with three arguments: @var{string}, @var{predicate}
559 and @code{nil}.  (The reason for the third argument is so that the same
560 function can be used in @code{all-completions} and do the appropriate
561 thing in either case.)  @xref{Programmed Completion}.
563 In the first of the following examples, the string @samp{foo} is
564 matched by three of the alist @sc{car}s.  All of the matches begin with
565 the characters @samp{fooba}, so that is the result.  In the second
566 example, there is only one possible match, and it is exact, so the value
567 is @code{t}.
569 @smallexample
570 @group
571 (try-completion 
572  "foo"
573  '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)))
574      @result{} "fooba"
575 @end group
577 @group
578 (try-completion "foo" '(("barfoo" 2) ("foo" 3)))
579      @result{} t
580 @end group
581 @end smallexample
583 In the following example, numerous symbols begin with the characters
584 @samp{forw}, and all of them begin with the word @samp{forward}.  In
585 most of the symbols, this is followed with a @samp{-}, but not in all,
586 so no more than @samp{forward} can be completed.
588 @smallexample
589 @group
590 (try-completion "forw" obarray)
591      @result{} "forward"
592 @end group
593 @end smallexample
595 Finally, in the following example, only two of the three possible
596 matches pass the predicate @code{test} (the string @samp{foobaz} is
597 too short).  Both of those begin with the string @samp{foobar}.
599 @smallexample
600 @group
601 (defun test (s) 
602   (> (length (car s)) 6))
603      @result{} test
604 @end group
605 @group
606 (try-completion 
607  "foo"
608  '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)) 
609  'test)
610      @result{} "foobar"
611 @end group
612 @end smallexample
613 @end defun
615 @defun all-completions string collection &optional predicate nospace
616 This function returns a list of all possible completions of
617 @var{string}.  The arguments to this function (aside from @var{nospace})
618 are the same as those of @code{try-completion}.  If @var{nospace} is
619 non-@code{nil}, completions that start with a space are ignored unless
620 @var{string} also starts with a space.
622 If @var{collection} is a function, it is called with three arguments:
623 @var{string}, @var{predicate} and @code{t}; then @code{all-completions}
624 returns whatever the function returns.  @xref{Programmed Completion}.
626 Here is an example, using the function @code{test} shown in the
627 example for @code{try-completion}:
629 @smallexample
630 @group
631 (defun test (s) 
632   (> (length (car s)) 6))
633      @result{} test
634 @end group
636 @group
637 (all-completions  
638  "foo"
639  '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
640  'test)
641      @result{} ("foobar1" "foobar2")
642 @end group
643 @end smallexample
644 @end defun
646 @defvar completion-ignore-case
647 If the value of this variable is 
648 non-@code{nil}, Emacs does not consider case significant in completion.
649 @end defvar
651 @node Minibuffer Completion
652 @subsection Completion and the Minibuffer
654   This section describes the basic interface for reading from the
655 minibuffer with completion.
657 @defun completing-read prompt collection &optional predicate require-match initial hist default inherit-input-method
658 This function reads a string in the minibuffer, assisting the user by
659 providing completion.  It activates the minibuffer with prompt
660 @var{prompt}, which must be a string.
662 The actual completion is done by passing @var{collection} and
663 @var{predicate} to the function @code{try-completion}.  This happens in
664 certain commands bound in the local keymaps used for completion.
666 If @var{require-match} is @code{nil}, the exit commands work regardless
667 of the input in the minibuffer.  If @var{require-match} is @code{t}, the
668 usual minibuffer exit commands won't exit unless the input completes to
669 an element of @var{collection}.  If @var{require-match} is neither
670 @code{nil} nor @code{t}, then the exit commands won't exit unless the
671 input already in the buffer matches an element of @var{collection}.
673 However, empty input is always permitted, regardless of the value of
674 @var{require-match}; in that case, @code{completing-read} returns
675 @var{default}.  The value of @var{default} (if non-@code{nil}) is also
676 available to the user through the history commands.
678 The user can exit with null input by typing @key{RET} with an empty
679 minibuffer.  Then @code{completing-read} returns @code{""}.  This is how
680 the user requests whatever default the command uses for the value being
681 read.  The user can return using @key{RET} in this way regardless of the
682 value of @var{require-match}, and regardless of whether the empty string
683 is included in @var{collection}.
685 The function @code{completing-read} works by calling
686 @code{read-minibuffer}.  It uses @code{minibuffer-local-completion-map}
687 as the keymap if @var{require-match} is @code{nil}, and uses
688 @code{minibuffer-local-must-match-map} if @var{require-match} is
689 non-@code{nil}.  @xref{Completion Commands}.
691 The argument @var{hist} specifies which history list variable to use for
692 saving the input and for minibuffer history commands.  It defaults to
693 @code{minibuffer-history}.  @xref{Minibuffer History}.
695 If @var{initial} is non-@code{nil}, @code{completing-read} inserts it
696 into the minibuffer as part of the input.  Then it allows the user to
697 edit the input, providing several commands to attempt completion.
698 In most cases, we recommend using @var{default}, and not @var{initial}.
700 @strong{We discourage use of a non-@code{nil} value for
701 @var{initial}}, because it is an intrusive interface.  The history
702 list feature (which did not exist when we introduced @var{initial})
703 offers a far more convenient and general way for the user to get the
704 default and edit it, and it is always available.
706 If the argument @var{inherit-input-method} is non-@code{nil}, then the
707 minibuffer inherits the current input method (@pxref{Input
708 Methods}) and the setting of @code{enable-multibyte-characters}
709 (@pxref{Text Representations}) from whichever buffer was current before
710 entering the minibuffer.
712 Completion ignores case when comparing the input against the possible
713 matches, if the built-in variable @code{completion-ignore-case} is
714 non-@code{nil}.  @xref{Basic Completion}.
716 Here's an example of using @code{completing-read}:
718 @smallexample
719 @group
720 (completing-read
721  "Complete a foo: "
722  '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
723  nil t "fo")
724 @end group
726 @group
727 ;; @r{After evaluation of the preceding expression,} 
728 ;;   @r{the following appears in the minibuffer:}
730 ---------- Buffer: Minibuffer ----------
731 Complete a foo: fo@point{}
732 ---------- Buffer: Minibuffer ----------
733 @end group
734 @end smallexample
736 @noindent
737 If the user then types @kbd{@key{DEL} @key{DEL} b @key{RET}},
738 @code{completing-read} returns @code{barfoo}.
740 The @code{completing-read} function binds three variables to pass
741 information to the commands that actually do completion.  These
742 variables are @code{minibuffer-completion-table},
743 @code{minibuffer-completion-predicate} and
744 @code{minibuffer-completion-confirm}.  For more information about them,
745 see @ref{Completion Commands}.
746 @end defun
748 @node Completion Commands
749 @subsection Minibuffer Commands that Do Completion
751   This section describes the keymaps, commands and user options used in
752 the minibuffer to do completion.
754 @defvar minibuffer-local-completion-map
755 @code{completing-read} uses this value as the local keymap when an
756 exact match of one of the completions is not required.  By default, this
757 keymap makes the following bindings:
759 @table @asis
760 @item @kbd{?}
761 @code{minibuffer-completion-help}
763 @item @key{SPC}
764 @code{minibuffer-complete-word}
766 @item @key{TAB}
767 @code{minibuffer-complete}
768 @end table
770 @noindent
771 with other characters bound as in @code{minibuffer-local-map}
772 (@pxref{Text from Minibuffer}).
773 @end defvar
775 @defvar minibuffer-local-must-match-map
776 @code{completing-read} uses this value as the local keymap when an
777 exact match of one of the completions is required.  Therefore, no keys
778 are bound to @code{exit-minibuffer}, the command that exits the
779 minibuffer unconditionally.  By default, this keymap makes the following
780 bindings:
782 @table @asis
783 @item @kbd{?}
784 @code{minibuffer-completion-help}
786 @item @key{SPC}
787 @code{minibuffer-complete-word}
789 @item @key{TAB}
790 @code{minibuffer-complete}
792 @item @kbd{C-j}
793 @code{minibuffer-complete-and-exit}
795 @item @key{RET}
796 @code{minibuffer-complete-and-exit}
797 @end table
799 @noindent
800 with other characters bound as in @code{minibuffer-local-map}.
801 @end defvar
803 @defvar minibuffer-completion-table
804 The value of this variable is the alist or obarray used for completion
805 in the minibuffer.  This is the global variable that contains what
806 @code{completing-read} passes to @code{try-completion}.  It is used by
807 minibuffer completion commands such as @code{minibuffer-complete-word}.
808 @end defvar
810 @defvar minibuffer-completion-predicate
811 This variable's value is the predicate that @code{completing-read}
812 passes to @code{try-completion}.  The variable is also used by the other
813 minibuffer completion functions.
814 @end defvar
816 @deffn Command minibuffer-complete-word
817 This function completes the minibuffer contents by at most a single
818 word.  Even if the minibuffer contents have only one completion,
819 @code{minibuffer-complete-word} does not add any characters beyond the
820 first character that is not a word constituent.  @xref{Syntax Tables}.
821 @end deffn
823 @deffn Command minibuffer-complete
824 This function completes the minibuffer contents as far as possible.
825 @end deffn
827 @deffn Command minibuffer-complete-and-exit
828 This function completes the minibuffer contents, and exits if
829 confirmation is not required, i.e., if
830 @code{minibuffer-completion-confirm} is @code{nil}.  If confirmation
831 @emph{is} required, it is given by repeating this command
832 immediately---the command is programmed to work without confirmation
833 when run twice in succession.
834 @end deffn
836 @defvar minibuffer-completion-confirm
837 When the value of this variable is non-@code{nil}, Emacs asks for
838 confirmation of a completion before exiting the minibuffer.  The
839 function @code{minibuffer-complete-and-exit} checks the value of this
840 variable before it exits.
841 @end defvar
843 @deffn Command minibuffer-completion-help
844 This function creates a list of the possible completions of the
845 current minibuffer contents.  It works by calling @code{all-completions}
846 using the value of the variable @code{minibuffer-completion-table} as
847 the @var{collection} argument, and the value of
848 @code{minibuffer-completion-predicate} as the @var{predicate} argument.
849 The list of completions is displayed as text in a buffer named
850 @samp{*Completions*}.
851 @end deffn
853 @defun display-completion-list completions
854 This function displays @var{completions} to the stream in
855 @code{standard-output}, usually a buffer.  (@xref{Read and Print}, for more
856 information about streams.)  The argument @var{completions} is normally
857 a list of completions just returned by @code{all-completions}, but it
858 does not have to be.  Each element may be a symbol or a string, either
859 of which is simply printed, or a list of two strings, which is printed
860 as if the strings were concatenated.
862 This function is called by @code{minibuffer-completion-help}.  The
863 most common way to use it is together with
864 @code{with-output-to-temp-buffer}, like this:
866 @example
867 (with-output-to-temp-buffer "*Completions*"
868   (display-completion-list
869     (all-completions (buffer-string) my-alist)))
870 @end example
871 @end defun
873 @defopt completion-auto-help
874 If this variable is non-@code{nil}, the completion commands
875 automatically display a list of possible completions whenever nothing
876 can be completed because the next character is not uniquely determined.
877 @end defopt
879 @node High-Level Completion
880 @subsection High-Level Completion  Functions
882   This section describes the higher-level convenient functions for
883 reading certain sorts of names with completion.
885   In most cases, you should not call these functions in the middle of a
886 Lisp function.  When possible, do all minibuffer input as part of
887 reading the arguments for a command, in the @code{interactive}
888 specification.  @xref{Defining Commands}.
890 @defun read-buffer prompt &optional default existing
891 This function reads the name of a buffer and returns it as a string.
892 The argument @var{default} is the default name to use, the value to
893 return if the user exits with an empty minibuffer.  If non-@code{nil},
894 it should be a string or a buffer.  It is mentioned in the prompt, but
895 is not inserted in the minibuffer as initial input.
897 If @var{existing} is non-@code{nil}, then the name specified must be
898 that of an existing buffer.  The usual commands to exit the minibuffer
899 do not exit if the text is not valid, and @key{RET} does completion to
900 attempt to find a valid name.  (However, @var{default} is not checked
901 for validity; it is returned, whatever it is, if the user exits with the
902 minibuffer empty.)
904 In the following example, the user enters @samp{minibuffer.t}, and
905 then types @key{RET}.  The argument @var{existing} is @code{t}, and the
906 only buffer name starting with the given input is
907 @samp{minibuffer.texi}, so that name is the value.
909 @example
910 (read-buffer "Buffer name? " "foo" t)
911 @group
912 ;; @r{After evaluation of the preceding expression,} 
913 ;;   @r{the following prompt appears,}
914 ;;   @r{with an empty minibuffer:}
915 @end group
917 @group
918 ---------- Buffer: Minibuffer ----------
919 Buffer name? (default foo) @point{}
920 ---------- Buffer: Minibuffer ----------
921 @end group
923 @group
924 ;; @r{The user types @kbd{minibuffer.t @key{RET}}.}
925      @result{} "minibuffer.texi"
926 @end group
927 @end example
928 @end defun
930 @defvar read-buffer-function
931 This variable specifies how to read buffer names.  For example, if you
932 set this variable to @code{iswitchb-read-buffer}, all Emacs commands
933 that call @code{read-buffer} to read a buffer name will actually use the
934 @code{iswitchb} package to read it.
935 @end defvar
937 @defun read-command prompt &optional default
938 This function reads the name of a command and returns it as a Lisp
939 symbol.  The argument @var{prompt} is used as in
940 @code{read-from-minibuffer}.  Recall that a command is anything for
941 which @code{commandp} returns @code{t}, and a command name is a symbol
942 for which @code{commandp} returns @code{t}.  @xref{Interactive Call}.
944 The argument @var{default} specifies what to return if the user enters
945 null input.  It can be a symbol or a string; if it is a string,
946 @code{read-command} interns it before returning it.  If @var{default} is
947 @code{nil}, that means no default has been specified; then if the user
948 enters null input, the return value is @code{nil}.
950 @example
951 (read-command "Command name? ")
953 @group
954 ;; @r{After evaluation of the preceding expression,} 
955 ;;   @r{the following prompt appears with an empty minibuffer:}
956 @end group
958 @group
959 ---------- Buffer: Minibuffer ---------- 
960 Command name?  
961 ---------- Buffer: Minibuffer ----------
962 @end group
963 @end example
965 @noindent
966 If the user types @kbd{forward-c @key{RET}}, then this function returns
967 @code{forward-char}.
969 The @code{read-command} function is a simplified interface to
970 @code{completing-read}.  It uses the variable @code{obarray} so as to
971 complete in the set of extant Lisp symbols, and it uses the
972 @code{commandp} predicate so as to accept only command names:
974 @cindex @code{commandp} example
975 @example
976 @group
977 (read-command @var{prompt})
978 @equiv{}
979 (intern (completing-read @var{prompt} obarray 
980                          'commandp t nil))
981 @end group
982 @end example
983 @end defun
985 @defun read-variable prompt &optional default
986 This function reads the name of a user variable and returns it as a
987 symbol.
989 The argument @var{default} specifies what to return if the user enters
990 null input.  It can be a symbol or a string; if it is a string,
991 @code{read-variable} interns it before returning it.  If @var{default}
992 is @code{nil}, that means no default has been specified; then if the
993 user enters null input, the return value is @code{nil}.
995 @example
996 @group
997 (read-variable "Variable name? ")
999 ;; @r{After evaluation of the preceding expression,} 
1000 ;;   @r{the following prompt appears,} 
1001 ;;   @r{with an empty minibuffer:}
1002 @end group
1004 @group
1005 ---------- Buffer: Minibuffer ----------
1006 Variable name? @point{}
1007 ---------- Buffer: Minibuffer ----------
1008 @end group
1009 @end example
1011 @noindent
1012 If the user then types @kbd{fill-p @key{RET}}, @code{read-variable}
1013 returns @code{fill-prefix}.
1015 This function is similar to @code{read-command}, but uses the
1016 predicate @code{user-variable-p} instead of @code{commandp}:
1018 @cindex @code{user-variable-p} example
1019 @example
1020 @group
1021 (read-variable @var{prompt})
1022 @equiv{}
1023 (intern
1024  (completing-read @var{prompt} obarray
1025                   'user-variable-p t nil))
1026 @end group
1027 @end example
1028 @end defun
1030   See also the functions @code{read-coding-system} and
1031 @code{read-non-nil-coding-system}, in @ref{User-Chosen Coding Systems}.
1033 @node Reading File Names
1034 @subsection Reading File Names
1036   Here is another high-level completion function, designed for reading a
1037 file name.  It provides special features including automatic insertion
1038 of the default directory.
1040 @defun read-file-name prompt &optional directory default existing initial
1041 This function reads a file name in the minibuffer, prompting with
1042 @var{prompt} and providing completion.  If @var{default} is
1043 non-@code{nil}, then the function returns @var{default} if the user just
1044 types @key{RET}.  @var{default} is not checked for validity; it is
1045 returned, whatever it is, if the user exits with the minibuffer empty.
1047 If @var{existing} is non-@code{nil}, then the user must specify the name
1048 of an existing file; @key{RET} performs completion to make the name
1049 valid if possible, and then refuses to exit if it is not valid.  If the
1050 value of @var{existing} is neither @code{nil} nor @code{t}, then
1051 @key{RET} also requires confirmation after completion.  If
1052 @var{existing} is @code{nil}, then the name of a nonexistent file is
1053 acceptable.
1055 The argument @var{directory} specifies the directory to use for
1056 completion of relative file names.  If @code{insert-default-directory}
1057 is non-@code{nil}, @var{directory} is also inserted in the minibuffer as
1058 initial input.  It defaults to the current buffer's value of
1059 @code{default-directory}.
1061 @c Emacs 19 feature
1062 If you specify @var{initial}, that is an initial file name to insert in
1063 the buffer (after @var{directory}, if that is inserted).  In this
1064 case, point goes at the beginning of @var{initial}.  The default for
1065 @var{initial} is @code{nil}---don't insert any file name.  To see what
1066 @var{initial} does, try the command @kbd{C-x C-v}.  @strong{Note:} we
1067 recommend using @var{default} rather than @var{initial} in most cases.
1069 Here is an example: 
1071 @example
1072 @group
1073 (read-file-name "The file is ")
1075 ;; @r{After evaluation of the preceding expression,} 
1076 ;;   @r{the following appears in the minibuffer:}
1077 @end group
1079 @group
1080 ---------- Buffer: Minibuffer ----------
1081 The file is /gp/gnu/elisp/@point{}
1082 ---------- Buffer: Minibuffer ----------
1083 @end group
1084 @end example
1086 @noindent
1087 Typing @kbd{manual @key{TAB}} results in the following:
1089 @example
1090 @group
1091 ---------- Buffer: Minibuffer ----------
1092 The file is /gp/gnu/elisp/manual.texi@point{}
1093 ---------- Buffer: Minibuffer ----------
1094 @end group
1095 @end example
1097 @c Wordy to avoid overfull hbox in smallbook mode.
1098 @noindent
1099 If the user types @key{RET}, @code{read-file-name} returns the file name
1100 as the string @code{"/gp/gnu/elisp/manual.texi"}.
1101 @end defun
1103 @defopt insert-default-directory
1104 This variable is used by @code{read-file-name}.  Its value controls
1105 whether @code{read-file-name} starts by placing the name of the default
1106 directory in the minibuffer, plus the initial file name if any.  If the
1107 value of this variable is @code{nil}, then @code{read-file-name} does
1108 not place any initial input in the minibuffer (unless you specify
1109 initial input with the @var{initial} argument).  In that case, the
1110 default directory is still used for completion of relative file names,
1111 but is not displayed.
1113 For example:
1115 @example
1116 @group
1117 ;; @r{Here the minibuffer starts out with the default directory.}
1118 (let ((insert-default-directory t))
1119   (read-file-name "The file is "))
1120 @end group
1122 @group
1123 ---------- Buffer: Minibuffer ----------
1124 The file is ~lewis/manual/@point{}
1125 ---------- Buffer: Minibuffer ----------
1126 @end group
1128 @group
1129 ;; @r{Here the minibuffer is empty and only the prompt}
1130 ;;   @r{appears on its line.}
1131 (let ((insert-default-directory nil))
1132   (read-file-name "The file is "))
1133 @end group
1135 @group
1136 ---------- Buffer: Minibuffer ----------
1137 The file is @point{}
1138 ---------- Buffer: Minibuffer ----------
1139 @end group
1140 @end example
1141 @end defopt
1143 @node Programmed Completion
1144 @subsection Programmed Completion
1145 @cindex programmed completion
1147   Sometimes it is not possible to create an alist or an obarray
1148 containing all the intended possible completions.  In such a case, you
1149 can supply your own function to compute the completion of a given string.
1150 This is called @dfn{programmed completion}.
1152   To use this feature, pass a symbol with a function definition as the
1153 @var{collection} argument to @code{completing-read}.  The function
1154 @code{completing-read} arranges to pass your completion function along
1155 to @code{try-completion} and @code{all-completions}, which will then let
1156 your function do all the work.
1158   The completion function should accept three arguments:
1160 @itemize @bullet
1161 @item
1162 The string to be completed.
1164 @item
1165 The predicate function to filter possible matches, or @code{nil} if
1166 none.  Your function should call the predicate for each possible match,
1167 and ignore the possible match if the predicate returns @code{nil}.
1169 @item
1170 A flag specifying the type of operation.
1171 @end itemize
1173   There are three flag values for three operations:
1175 @itemize @bullet
1176 @item
1177 @code{nil} specifies @code{try-completion}.  The completion function
1178 should return the completion of the specified string, or @code{t} if the
1179 string is a unique and exact match already, or @code{nil} if the string
1180 matches no possibility.
1182 If the string is an exact match for one possibility, but also matches
1183 other longer possibilities, the function should return the string, not
1184 @code{t}.
1186 @item
1187 @code{t} specifies @code{all-completions}.  The completion function
1188 should return a list of all possible completions of the specified
1189 string.
1191 @item
1192 @code{lambda} specifies a test for an exact match.  The completion
1193 function should return @code{t} if the specified string is an exact
1194 match for some possibility; @code{nil} otherwise.
1195 @end itemize
1197   It would be consistent and clean for completion functions to allow
1198 lambda expressions (lists that are functions) as well as function
1199 symbols as @var{collection}, but this is impossible.  Lists as
1200 completion tables are already assigned another meaning---as alists.  It
1201 would be unreliable to fail to handle an alist normally because it is
1202 also a possible function.  So you must arrange for any function you wish
1203 to use for completion to be encapsulated in a symbol.
1205   Emacs uses programmed completion when completing file names.
1206 @xref{File Name Completion}.
1208 @node Yes-or-No Queries
1209 @section Yes-or-No Queries
1210 @cindex asking the user questions
1211 @cindex querying the user
1212 @cindex yes-or-no questions
1214   This section describes functions used to ask the user a yes-or-no
1215 question.  The function @code{y-or-n-p} can be answered with a single
1216 character; it is useful for questions where an inadvertent wrong answer
1217 will not have serious consequences.  @code{yes-or-no-p} is suitable for
1218 more momentous questions, since it requires three or four characters to
1219 answer.
1221    If either of these functions is called in a command that was invoked
1222 using the mouse---more precisely, if @code{last-nonmenu-event}
1223 (@pxref{Command Loop Info}) is either @code{nil} or a list---then it
1224 uses a dialog box or pop-up menu to ask the question.  Otherwise, it
1225 uses keyboard input.  You can force use of the mouse or use of keyboard
1226 input by binding @code{last-nonmenu-event} to a suitable value around
1227 the call.
1229   Strictly speaking, @code{yes-or-no-p} uses the minibuffer and
1230 @code{y-or-n-p} does not; but it seems best to describe them together.
1232 @defun y-or-n-p prompt
1233 This function asks the user a question, expecting input in the echo
1234 area.  It returns @code{t} if the user types @kbd{y}, @code{nil} if the
1235 user types @kbd{n}.  This function also accepts @key{SPC} to mean yes
1236 and @key{DEL} to mean no.  It accepts @kbd{C-]} to mean ``quit'', like
1237 @kbd{C-g}, because the question might look like a minibuffer and for
1238 that reason the user might try to use @kbd{C-]} to get out.  The answer
1239 is a single character, with no @key{RET} needed to terminate it.  Upper
1240 and lower case are equivalent.
1242 ``Asking the question'' means printing @var{prompt} in the echo area,
1243 followed by the string @w{@samp{(y or n) }}.  If the input is not one of
1244 the expected answers (@kbd{y}, @kbd{n}, @kbd{@key{SPC}},
1245 @kbd{@key{DEL}}, or something that quits), the function responds
1246 @samp{Please answer y or n.}, and repeats the request.
1248 This function does not actually use the minibuffer, since it does not
1249 allow editing of the answer.  It actually uses the echo area (@pxref{The
1250 Echo Area}), which uses the same screen space as the minibuffer.  The
1251 cursor moves to the echo area while the question is being asked.
1253 The answers and their meanings, even @samp{y} and @samp{n}, are not
1254 hardwired.  The keymap @code{query-replace-map} specifies them.
1255 @xref{Search and Replace}.
1257 In the following example, the user first types @kbd{q}, which is
1258 invalid.  At the next prompt the user types @kbd{y}.
1260 @smallexample
1261 @group
1262 (y-or-n-p "Do you need a lift? ")
1264 ;; @r{After evaluation of the preceding expression,} 
1265 ;;   @r{the following prompt appears in the echo area:}
1266 @end group
1268 @group
1269 ---------- Echo area ----------
1270 Do you need a lift? (y or n) 
1271 ---------- Echo area ----------
1272 @end group
1274 ;; @r{If the user then types @kbd{q}, the following appears:}
1276 @group
1277 ---------- Echo area ----------
1278 Please answer y or n.  Do you need a lift? (y or n) 
1279 ---------- Echo area ----------
1280 @end group
1282 ;; @r{When the user types a valid answer,}
1283 ;;   @r{it is displayed after the question:}
1285 @group
1286 ---------- Echo area ----------
1287 Do you need a lift? (y or n) y
1288 ---------- Echo area ----------
1289 @end group
1290 @end smallexample
1292 @noindent
1293 We show successive lines of echo area messages, but only one actually
1294 appears on the screen at a time.
1295 @end defun
1297 @defun y-or-n-p-with-timeout prompt seconds default-value
1298 Like @code{y-or-n-p}, except that if the user fails to answer within
1299 @var{seconds} seconds, this function stops waiting and returns
1300 @var{default-value}.  It works by setting up a timer; see @ref{Timers}.
1301 The argument @var{seconds} may be an integer or a floating point number.
1302 @end defun
1304 @defun yes-or-no-p prompt
1305 This function asks the user a question, expecting input in the
1306 minibuffer.  It returns @code{t} if the user enters @samp{yes},
1307 @code{nil} if the user types @samp{no}.  The user must type @key{RET} to
1308 finalize the response.  Upper and lower case are equivalent.
1310 @code{yes-or-no-p} starts by displaying @var{prompt} in the echo area,
1311 followed by @w{@samp{(yes or no) }}.  The user must type one of the
1312 expected responses; otherwise, the function responds @samp{Please answer
1313 yes or no.}, waits about two seconds and repeats the request.
1315 @code{yes-or-no-p} requires more work from the user than
1316 @code{y-or-n-p} and is appropriate for more crucial decisions.
1318 Here is an example:
1320 @smallexample
1321 @group
1322 (yes-or-no-p "Do you really want to remove everything? ")
1324 ;; @r{After evaluation of the preceding expression,} 
1325 ;;   @r{the following prompt appears,} 
1326 ;;   @r{with an empty minibuffer:}
1327 @end group
1329 @group
1330 ---------- Buffer: minibuffer ----------
1331 Do you really want to remove everything? (yes or no) 
1332 ---------- Buffer: minibuffer ----------
1333 @end group
1334 @end smallexample
1336 @noindent
1337 If the user first types @kbd{y @key{RET}}, which is invalid because this
1338 function demands the entire word @samp{yes}, it responds by displaying
1339 these prompts, with a brief pause between them:
1341 @smallexample
1342 @group
1343 ---------- Buffer: minibuffer ----------
1344 Please answer yes or no.
1345 Do you really want to remove everything? (yes or no)
1346 ---------- Buffer: minibuffer ----------
1347 @end group
1348 @end smallexample
1349 @end defun
1351 @node Multiple Queries
1352 @section Asking Multiple Y-or-N Questions
1354   When you have a series of similar questions to ask, such as ``Do you
1355 want to save this buffer'' for each buffer in turn, you should use
1356 @code{map-y-or-n-p} to ask the collection of questions, rather than
1357 asking each question individually.  This gives the user certain
1358 convenient facilities such as the ability to answer the whole series at
1359 once.
1361 @defun map-y-or-n-p prompter actor list &optional help action-alist no-cursor-in-echo-area
1362 This function asks the user a series of questions, reading a
1363 single-character answer in the echo area for each one.
1365 The value of @var{list} specifies the objects to ask questions about.
1366 It should be either a list of objects or a generator function.  If it is
1367 a function, it should expect no arguments, and should return either the
1368 next object to ask about, or @code{nil} meaning stop asking questions.
1370 The argument @var{prompter} specifies how to ask each question.  If
1371 @var{prompter} is a string, the question text is computed like this:
1373 @example
1374 (format @var{prompter} @var{object})
1375 @end example
1377 @noindent
1378 where @var{object} is the next object to ask about (as obtained from
1379 @var{list}).
1381 If not a string, @var{prompter} should be a function of one argument
1382 (the next object to ask about) and should return the question text.  If
1383 the value is a string, that is the question to ask the user.  The
1384 function can also return @code{t} meaning do act on this object (and
1385 don't ask the user), or @code{nil} meaning ignore this object (and don't
1386 ask the user).
1388 The argument @var{actor} says how to act on the answers that the user
1389 gives.  It should be a function of one argument, and it is called with
1390 each object that the user says yes for.  Its argument is always an
1391 object obtained from @var{list}.
1393 If the argument @var{help} is given, it should be a list of this form:
1395 @example
1396 (@var{singular} @var{plural} @var{action})
1397 @end example
1399 @noindent
1400 where @var{singular} is a string containing a singular noun that
1401 describes the objects conceptually being acted on, @var{plural} is the
1402 corresponding plural noun, and @var{action} is a transitive verb
1403 describing what @var{actor} does.
1405 If you don't specify @var{help}, the default is @code{("object"
1406 "objects" "act on")}.
1408 Each time a question is asked, the user may enter @kbd{y}, @kbd{Y}, or
1409 @key{SPC} to act on that object; @kbd{n}, @kbd{N}, or @key{DEL} to skip
1410 that object; @kbd{!} to act on all following objects; @key{ESC} or
1411 @kbd{q} to exit (skip all following objects); @kbd{.} (period) to act on
1412 the current object and then exit; or @kbd{C-h} to get help.  These are
1413 the same answers that @code{query-replace} accepts.  The keymap
1414 @code{query-replace-map} defines their meaning for @code{map-y-or-n-p}
1415 as well as for @code{query-replace}; see @ref{Search and Replace}.
1417 You can use @var{action-alist} to specify additional possible answers
1418 and what they mean.  It is an alist of elements of the form
1419 @code{(@var{char} @var{function} @var{help})}, each of which defines one
1420 additional answer.  In this element, @var{char} is a character (the
1421 answer); @var{function} is a function of one argument (an object from
1422 @var{list}); @var{help} is a string.
1424 When the user responds with @var{char}, @code{map-y-or-n-p} calls
1425 @var{function}.  If it returns non-@code{nil}, the object is considered
1426 ``acted upon'', and @code{map-y-or-n-p} advances to the next object in
1427 @var{list}.  If it returns @code{nil}, the prompt is repeated for the
1428 same object.
1430 Normally, @code{map-y-or-n-p} binds @code{cursor-in-echo-area} while
1431 prompting.  But if @var{no-cursor-in-echo-area} is non-@code{nil}, it
1432 does not do that.
1434 If @code{map-y-or-n-p} is called in a command that was invoked using the
1435 mouse---more precisely, if @code{last-nonmenu-event} (@pxref{Command
1436 Loop Info}) is either @code{nil} or a list---then it uses a dialog box
1437 or pop-up menu to ask the question.  In this case, it does not use
1438 keyboard input or the echo area.  You can force use of the mouse or use
1439 of keyboard input by binding @code{last-nonmenu-event} to a suitable
1440 value around the call.
1442 The return value of @code{map-y-or-n-p} is the number of objects acted on.
1443 @end defun
1445 @node Reading a Password
1446 @section Reading a Password
1447 @cindex passwords, reading
1449   To read a password to pass to another program, you can use the
1450 function @code{read-passwd}.
1452 @defun read-passwd prompt &optional confirm default
1453 This function reads a password, prompting with @var{prompt}.  It does
1454 not echo the password as the user types it; instead, it echoes @samp{.}
1455 for each character in the password.
1457 The optional argument @var{confirm}, if non-@code{nil}, says to read the
1458 password twice and insist it must be the same both times.  If it isn't
1459 the same, the user has to type it over and over until the last two
1460 times match.
1462 The optional argument @var{default} specifies the default password to
1463 return if the user enters empty input.  If @var{default} is @code{nil},
1464 then @code{read-passwd} returns the null string in that case.
1465 @end defun
1467 @node Minibuffer Misc
1468 @section Minibuffer Miscellany
1470   This section describes some basic functions and variables related to
1471 minibuffers.
1473 @deffn Command exit-minibuffer
1474 This command exits the active minibuffer.  It is normally bound to
1475 keys in minibuffer local keymaps.
1476 @end deffn
1478 @deffn Command self-insert-and-exit
1479 This command exits the active minibuffer after inserting the last
1480 character typed on the keyboard (found in @code{last-command-char};
1481 @pxref{Command Loop Info}).
1482 @end deffn
1484 @deffn Command previous-history-element n
1485 This command replaces the minibuffer contents with the value of the
1486 @var{n}th previous (older) history element.
1487 @end deffn
1489 @deffn Command next-history-element n
1490 This command replaces the minibuffer contents with the value of the
1491 @var{n}th more recent history element.
1492 @end deffn
1494 @deffn Command previous-matching-history-element pattern n
1495 This command replaces the minibuffer contents with the value of the
1496 @var{n}th previous (older) history element that matches @var{pattern} (a
1497 regular expression).
1498 @end deffn
1500 @deffn Command next-matching-history-element pattern n
1501 This command replaces the minibuffer contents with the value of the
1502 @var{n}th next (newer) history element that matches @var{pattern} (a
1503 regular expression).
1504 @end deffn
1506 @defun minibuffer-prompt
1507 This function returns the prompt string of the currently active
1508 minibuffer.  If no minibuffer is active, it returns @code{nil}.
1509 @end defun
1511 @defun minibuffer-prompt-end
1512 @tindex minibuffer-prompt-end
1513 This function, available starting in Emacs 21, returns the current
1514 position of the end of the minibuffer prompt, if a minibuffer is
1515 current.  Otherwise, it returns the minimum valid buffer position.
1516 @end defun
1518 @defun minibuffer-contents
1519 @tindex minibuffer-contents
1520 This function, available starting in Emacs 21, returns the editable
1521 contents of the minibuffer (that is, everything except the prompt) as
1522 a string, if a minibuffer is current.  Otherwise, it returns the
1523 entire contents of the current buffer.
1524 @end defun
1526 @defun minibuffer-contents-no-properties
1527 @tindex minibuffer-contents-no-properties
1528 This is like @code{minibuffer-contents}, except that it does not copy text
1529 properties, just the characters themselves.  @xref{Text Properties}.
1530 @end defun
1532 @defun delete-minibuffer-contents
1533 @tindex delete-minibuffer-contents
1534 This function, available starting in Emacs 21, erases the editable
1535 contents of the minibuffer (that is, everything except the prompt), if
1536 a minibuffer is current.  Otherwise, it erases the entire buffer.
1537 @end defun
1539 @defun minibuffer-prompt-width
1540 This function returns the current display-width of the minibuffer
1541 prompt, if a minibuffer is current.  Otherwise, it returns zero.
1542 @end defun
1544 @defvar minibuffer-setup-hook
1545 This is a normal hook that is run whenever the minibuffer is entered.
1546 @xref{Hooks}.
1547 @end defvar
1549 @defvar minibuffer-exit-hook
1550 This is a normal hook that is run whenever the minibuffer is exited.
1551 @xref{Hooks}.
1552 @end defvar
1554 @defvar minibuffer-help-form
1555 The current value of this variable is used to rebind @code{help-form}
1556 locally inside the minibuffer (@pxref{Help Functions}).
1557 @end defvar
1559 @defun active-minibuffer-window
1560 This function returns the currently active minibuffer window, or
1561 @code{nil} if none is currently active.
1562 @end defun
1564 @defun minibuffer-window &optional frame
1565 This function returns the minibuffer window used for frame @var{frame}.
1566 If @var{frame} is @code{nil}, that stands for the current frame.  Note
1567 that the minibuffer window used by a frame need not be part of that
1568 frame---a frame that has no minibuffer of its own necessarily uses some
1569 other frame's minibuffer window.
1570 @end defun
1572 @c Emacs 19 feature
1573 @defun window-minibuffer-p window
1574 This function returns non-@code{nil} if @var{window} is a minibuffer window.
1575 @end defun
1577 It is not correct to determine whether a given window is a minibuffer by
1578 comparing it with the result of @code{(minibuffer-window)}, because
1579 there can be more than one minibuffer window if there is more than one
1580 frame.
1582 @defun minibuffer-window-active-p window
1583 This function returns non-@code{nil} if @var{window}, assumed to be
1584 a minibuffer window, is currently active.
1585 @end defun
1587 @defvar minibuffer-scroll-window
1588 If the value of this variable is non-@code{nil}, it should be a window
1589 object.  When the function @code{scroll-other-window} is called in the
1590 minibuffer, it scrolls this window.
1591 @end defvar
1593 Finally, some functions and variables deal with recursive minibuffers
1594 (@pxref{Recursive Editing}):
1596 @defun minibuffer-depth
1597 This function returns the current depth of activations of the
1598 minibuffer, a nonnegative integer.  If no minibuffers are active, it
1599 returns zero.
1600 @end defun
1602 @defopt enable-recursive-minibuffers
1603 If this variable is non-@code{nil}, you can invoke commands (such as
1604 @code{find-file}) that use minibuffers even while the minibuffer window
1605 is active.  Such invocation produces a recursive editing level for a new
1606 minibuffer.  The outer-level minibuffer is invisible while you are
1607 editing the inner one.
1609 If this variable is @code{nil}, you cannot invoke minibuffer
1610 commands when the minibuffer window is active, not even if you switch to
1611 another window to do it.
1612 @end defopt
1614 @c Emacs 19 feature
1615 If a command name has a property @code{enable-recursive-minibuffers}
1616 that is non-@code{nil}, then the command can use the minibuffer to read
1617 arguments even if it is invoked from the minibuffer.  The minibuffer
1618 command @code{next-matching-history-element} (normally @kbd{M-s} in the
1619 minibuffer) uses this feature.