os.texi "Startup Summary" small changes
[emacs.git] / doc / lispref / minibuf.texi
blob1224d80fdf89394dfcd6b22876669cb86e29977f
1 @c -*-texinfo-*-
2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-1999, 2001-2012
4 @c   Free Software Foundation, Inc.
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../../info/minibuf
7 @node Minibuffers, Command Loop, Read and Print, Top
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
14 read arguments more complicated than the single numeric prefix
15 argument.  These arguments include file names, buffer names, and
16 command names (as in @kbd{M-x}).  The minibuffer is displayed on the
17 bottom line of the frame, in the same place as the echo area
18 (@pxref{The Echo Area}), but only while it is in use for reading an
19 argument.
21 @menu
22 * Intro to Minibuffers::      Basic information about minibuffers.
23 * Text from Minibuffer::      How to read a straight text string.
24 * Object from Minibuffer::    How to read a Lisp object or expression.
25 * Minibuffer History::        Recording previous minibuffer inputs
26                                 so the user can reuse them.
27 * Initial Input::             Specifying initial contents for the minibuffer.
28 * Completion::                How to invoke and customize completion.
29 * Yes-or-No Queries::         Asking a question with a simple answer.
30 * Multiple Queries::          Asking a series of similar questions.
31 * Reading a Password::        Reading a password from the terminal.
32 * Minibuffer Commands::       Commands used as key bindings in minibuffers.
33 * Minibuffer Contents::       How such commands access the minibuffer text.
34 * Minibuffer Windows::        Operating on the special minibuffer windows.
35 * Recursive Mini::            Whether recursive entry to minibuffer is allowed.
36 * Minibuffer Misc::           Various customization hooks and variables.
37 @end menu
39 @node Intro to Minibuffers
40 @section Introduction to Minibuffers
42   In most ways, a minibuffer is a normal Emacs buffer.  Most operations
43 @emph{within} a buffer, such as editing commands, work normally in a
44 minibuffer.  However, many operations for managing buffers do not apply
45 to minibuffers.  The name of a minibuffer always has the form @w{@samp{
46 *Minibuf-@var{number}*}}, and it cannot be changed.  Minibuffers are
47 displayed only in special windows used only for minibuffers; these
48 windows always appear at the bottom of a frame.  (Sometimes frames have
49 no minibuffer window, and sometimes a special kind of frame contains
50 nothing but a minibuffer window; see @ref{Minibuffers and Frames}.)
52   The text in the minibuffer always starts with the @dfn{prompt string},
53 the text that was specified by the program that is using the minibuffer
54 to tell the user what sort of input to type.  This text is marked
55 read-only so you won't accidentally delete or change it.  It is also
56 marked as a field (@pxref{Fields}), so that certain motion functions,
57 including @code{beginning-of-line}, @code{forward-word},
58 @code{forward-sentence}, and @code{forward-paragraph}, stop at the
59 boundary between the prompt and the actual text.
61   The minibuffer's window is normally a single line; it grows
62 automatically if the contents require more space.  You can explicitly
63 resize it temporarily with the window sizing commands; it reverts to
64 its normal size when the minibuffer is exited.  You can resize it
65 permanently by using the window sizing commands in the frame's other
66 window, when the minibuffer is not active.  If the frame contains just
67 a minibuffer, you can change the minibuffer's size by changing the
68 frame's size.
70   Use of the minibuffer reads input events, and that alters the values
71 of variables such as @code{this-command} and @code{last-command}
72 (@pxref{Command Loop Info}).  Your program should bind them around the
73 code that uses the minibuffer, if you do not want that to change them.
75   Under some circumstances, a command can use a minibuffer even if
76 there is an active minibuffer; such minibuffers are called a
77 @dfn{recursive minibuffer}.  The first minibuffer is named
78 @w{@samp{ *Minibuf-0*}}.  Recursive minibuffers are named by
79 incrementing the number at the end of the name.  (The names begin with
80 a space so that they won't show up in normal buffer lists.)  Of
81 several recursive minibuffers, the innermost (or most recently
82 entered) is the active minibuffer.  We usually call this ``the''
83 minibuffer.  You can permit or forbid recursive minibuffers by setting
84 the variable @code{enable-recursive-minibuffers}, or by putting
85 properties of that name on command symbols (@xref{Recursive Mini}.)
87   Like other buffers, a minibuffer uses a local keymap
88 (@pxref{Keymaps}) to specify special key bindings.  The function that
89 invokes the minibuffer also sets up its local map according to the job
90 to be done.  @xref{Text from Minibuffer}, for the non-completion
91 minibuffer local maps.  @xref{Completion Commands}, for the minibuffer
92 local maps for completion.
94   When Emacs is running in batch mode, any request to read from the
95 minibuffer actually reads a line from the standard input descriptor that
96 was supplied when Emacs was started.
98 @node Text from Minibuffer
99 @section Reading Text Strings with the Minibuffer
101   The most basic primitive for minibuffer input is
102 @code{read-from-minibuffer}, which can be used to read either a string
103 or a Lisp object in textual form.  The function @code{read-regexp} is
104 used for reading regular expressions (@pxref{Regular Expressions}),
105 which are a special kind of string.  There are also specialized
106 functions for reading commands, variables, file names, etc.@:
107 (@pxref{Completion}).
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 from 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 default values to make available
133 through the history commands.  It should be a string, a list of
134 strings, or @code{nil}.  The string or strings become the minibuffer's
135 ``future history,'' available to the user with @kbd{M-n}.
137 If @var{read} is non-@code{nil}, then @var{default} is also used
138 as the input to @code{read}, if the user enters empty input.
139 If @var{default} is a list of strings, the first string is used as the input.
140 If @var{default} is @code{nil}, empty input results in an @code{end-of-file} error.
141 However, in the usual case (where @var{read} is @code{nil}),
142 @code{read-from-minibuffer} ignores @var{default} when the user enters
143 empty input and returns an empty string, @code{""}.  In this respect,
144 it differs from all the other minibuffer input functions in this chapter.
146 If @var{keymap} is non-@code{nil}, that keymap is the local keymap to
147 use in the minibuffer.  If @var{keymap} is omitted or @code{nil}, the
148 value of @code{minibuffer-local-map} is used as the keymap.  Specifying
149 a keymap is the most important way to customize the minibuffer for
150 various applications such as completion.
152 The argument @var{hist} specifies which history list variable to use
153 for saving the input and for history commands used in the minibuffer.
154 It defaults to @code{minibuffer-history}.  @xref{Minibuffer History}.
156 If the variable @code{minibuffer-allow-text-properties} is
157 non-@code{nil}, then the string which is returned includes whatever text
158 properties were present in the minibuffer.  Otherwise all the text
159 properties are stripped when the value is returned.
161 If the argument @var{inherit-input-method} is non-@code{nil}, then the
162 minibuffer inherits the current input method (@pxref{Input Methods}) and
163 the setting of @code{enable-multibyte-characters} (@pxref{Text
164 Representations}) from whichever buffer was current before entering the
165 minibuffer.
167 Use of @var{initial-contents} is mostly deprecated; we recommend using
168 a non-@code{nil} value only in conjunction with specifying a cons cell
169 for @var{hist}.  @xref{Initial Input}.
170 @end defun
172 @defun read-string prompt &optional initial history default inherit-input-method
173 This function reads a string from the minibuffer and returns it.  The
174 arguments @var{prompt}, @var{initial}, @var{history} and
175 @var{inherit-input-method} are used as in @code{read-from-minibuffer}.
176 The keymap used is @code{minibuffer-local-map}.
178 The optional argument @var{default} is used as in
179 @code{read-from-minibuffer}, except that, if non-@code{nil}, it also
180 specifies a default value to return if the user enters null input.  As
181 in @code{read-from-minibuffer} it should be a string, a list of
182 strings, or @code{nil} which is equivalent to an empty string.  When
183 @var{default} is a string, that string is the default value.  When it
184 is a list of strings, the first string is the default value.  (All
185 these strings are available to the user in the ``future minibuffer
186 history.'')
188 This function works by calling the
189 @code{read-from-minibuffer} function:
191 @smallexample
192 @group
193 (read-string @var{prompt} @var{initial} @var{history} @var{default} @var{inherit})
194 @equiv{}
195 (let ((value
196        (read-from-minibuffer @var{prompt} @var{initial} nil nil
197                              @var{history} @var{default} @var{inherit})))
198   (if (and (equal value "") @var{default})
199       (if (consp @var{default}) (car @var{default}) @var{default})
200     value))
201 @end group
202 @end smallexample
203 @end defun
205 @defun read-regexp prompt &optional default-value
206 This function reads a regular expression as a string from the
207 minibuffer and returns it.  The argument @var{prompt} is used as in
208 @code{read-from-minibuffer}.  The keymap used is
209 @code{minibuffer-local-map}, and @code{regexp-history} is used as the
210 history list (@pxref{Minibuffer History, regexp-history}).
212 The optional argument @var{default-value} specifies a default value to
213 return if the user enters null input; it should be a string, or
214 @code{nil} which is equivalent to an empty string.
216 In addition, @code{read-regexp} collects a few useful candidates for
217 input and passes them to @code{read-from-minibuffer}, to make them
218 available to the user as the ``future minibuffer history list''
219 (@pxref{Minibuffer History, future list,, emacs, The GNU Emacs
220 Manual}).  These candidates are:
222 @itemize @minus
223 @item
224 The word or symbol at point.
225 @item
226 The last regexp used in an incremental search.
227 @item
228 The last string used in an incremental search.
229 @item
230 The last string or pattern used in query-replace commands.
231 @end itemize
233 This function works by calling the @code{read-from-minibuffer}
234 function, after computing the list of defaults as described above.
235 @end defun
237 @defvar minibuffer-allow-text-properties
238 If this variable is @code{nil}, then @code{read-from-minibuffer} strips
239 all text properties from the minibuffer input before returning it.
240 This variable also affects @code{read-string}.  However,
241 @code{read-no-blanks-input} (see below), as well as
242 @code{read-minibuffer} and related functions (@pxref{Object from
243 Minibuffer,, Reading Lisp Objects With the Minibuffer}), and all
244 functions that do minibuffer input with completion, discard text
245 properties unconditionally, regardless of the value of this variable.
246 @end defvar
248 @defvar minibuffer-local-map
249 This
250 @anchor{Definition of minibuffer-local-map}
251 @c avoid page break at anchor; work around Texinfo deficiency
252 is the default local keymap for reading from the minibuffer.  By
253 default, it makes the following bindings:
255 @table @asis
256 @item @kbd{C-j}
257 @code{exit-minibuffer}
259 @item @key{RET}
260 @code{exit-minibuffer}
262 @item @kbd{C-g}
263 @code{abort-recursive-edit}
265 @item @kbd{M-n}
266 @itemx @key{DOWN}
267 @code{next-history-element}
269 @item @kbd{M-p}
270 @itemx @key{UP}
271 @code{previous-history-element}
273 @item @kbd{M-s}
274 @code{next-matching-history-element}
276 @item @kbd{M-r}
277 @code{previous-matching-history-element}
278 @end table
279 @end defvar
281 @c In version 18, initial is required
282 @c Emacs 19 feature
283 @defun read-no-blanks-input prompt &optional initial inherit-input-method
284 This function reads a string from the minibuffer, but does not allow
285 whitespace characters as part of the input: instead, those characters
286 terminate the input.  The arguments @var{prompt}, @var{initial}, and
287 @var{inherit-input-method} are used as in @code{read-from-minibuffer}.
289 This is a simplified interface to the @code{read-from-minibuffer}
290 function, and passes the value of the @code{minibuffer-local-ns-map}
291 keymap as the @var{keymap} argument for that function.  Since the keymap
292 @code{minibuffer-local-ns-map} does not rebind @kbd{C-q}, it @emph{is}
293 possible to put a space into the string, by quoting it.
295 This function discards text properties, regardless of the value of
296 @code{minibuffer-allow-text-properties}.
298 @smallexample
299 @group
300 (read-no-blanks-input @var{prompt} @var{initial})
301 @equiv{}
302 (let (minibuffer-allow-text-properties)
303   (read-from-minibuffer @var{prompt} @var{initial} minibuffer-local-ns-map))
304 @end group
305 @end smallexample
306 @end defun
308 @defvar minibuffer-local-ns-map
309 This built-in variable is the keymap used as the minibuffer local keymap
310 in the function @code{read-no-blanks-input}.  By default, it makes the
311 following bindings, in addition to those of @code{minibuffer-local-map}:
313 @table @asis
314 @item @key{SPC}
315 @cindex @key{SPC} in minibuffer
316 @code{exit-minibuffer}
318 @item @key{TAB}
319 @cindex @key{TAB} in minibuffer
320 @code{exit-minibuffer}
322 @item @kbd{?}
323 @cindex @kbd{?} in minibuffer
324 @code{self-insert-and-exit}
325 @end table
326 @end defvar
328 @node Object from Minibuffer
329 @section Reading Lisp Objects with the Minibuffer
331   This section describes functions for reading Lisp objects with the
332 minibuffer.
334 @defun read-minibuffer prompt &optional initial
335 This function reads a Lisp object using the minibuffer, and returns it
336 without evaluating it.  The arguments @var{prompt} and @var{initial} are
337 used as in @code{read-from-minibuffer}.
339 This is a simplified interface to the
340 @code{read-from-minibuffer} function:
342 @smallexample
343 @group
344 (read-minibuffer @var{prompt} @var{initial})
345 @equiv{}
346 (let (minibuffer-allow-text-properties)
347   (read-from-minibuffer @var{prompt} @var{initial} nil t))
348 @end group
349 @end smallexample
351 Here is an example in which we supply the string @code{"(testing)"} as
352 initial input:
354 @smallexample
355 @group
356 (read-minibuffer
357  "Enter an expression: " (format "%s" '(testing)))
359 ;; @r{Here is how the minibuffer is displayed:}
360 @end group
362 @group
363 ---------- Buffer: Minibuffer ----------
364 Enter an expression: (testing)@point{}
365 ---------- Buffer: Minibuffer ----------
366 @end group
367 @end smallexample
369 @noindent
370 The user can type @key{RET} immediately to use the initial input as a
371 default, or can edit the input.
372 @end defun
374 @defun eval-minibuffer prompt &optional initial
375 This function reads a Lisp expression using the minibuffer, evaluates
376 it, then returns the result.  The arguments @var{prompt} and
377 @var{initial} are used as in @code{read-from-minibuffer}.
379 This function simply evaluates the result of a call to
380 @code{read-minibuffer}:
382 @smallexample
383 @group
384 (eval-minibuffer @var{prompt} @var{initial})
385 @equiv{}
386 (eval (read-minibuffer @var{prompt} @var{initial}))
387 @end group
388 @end smallexample
389 @end defun
391 @defun edit-and-eval-command prompt form
392 This function reads a Lisp expression in the minibuffer, and then
393 evaluates it.  The difference between this command and
394 @code{eval-minibuffer} is that here the initial @var{form} is not
395 optional and it is treated as a Lisp object to be converted to printed
396 representation rather than as a string of text.  It is printed with
397 @code{prin1}, so if it is a string, double-quote characters (@samp{"})
398 appear in the initial text.  @xref{Output Functions}.
400 The first thing @code{edit-and-eval-command} does is to activate the
401 minibuffer with @var{prompt} as the prompt.  Then it inserts the printed
402 representation of @var{form} in the minibuffer, and lets the user edit it.
403 When the user exits the minibuffer, the edited text is read with
404 @code{read} and then evaluated.  The resulting value becomes the value
405 of @code{edit-and-eval-command}.
407 In the following example, we offer the user an expression with initial
408 text which is a valid form already:
410 @smallexample
411 @group
412 (edit-and-eval-command "Please edit: " '(forward-word 1))
414 ;; @r{After evaluation of the preceding expression,}
415 ;;   @r{the following appears in the minibuffer:}
416 @end group
418 @group
419 ---------- Buffer: Minibuffer ----------
420 Please edit: (forward-word 1)@point{}
421 ---------- Buffer: Minibuffer ----------
422 @end group
423 @end smallexample
425 @noindent
426 Typing @key{RET} right away would exit the minibuffer and evaluate the
427 expression, thus moving point forward one word.
428 @code{edit-and-eval-command} returns @code{nil} in this example.
429 @end defun
431 @node Minibuffer History
432 @section Minibuffer History
433 @cindex minibuffer history
434 @cindex history list
436   A @dfn{minibuffer history list} records previous minibuffer inputs
437 so the user can reuse them conveniently.  It is a variable whose value
438 is a list of strings (previous inputs), most recent first.
440   There are many separate minibuffer history lists, used for different
441 kinds of inputs.  It's the Lisp programmer's job to specify the right
442 history list for each use of the minibuffer.
444   You specify a minibuffer history list with the optional @var{hist}
445 argument to @code{read-from-minibuffer} or @code{completing-read}.
446 Here are the possible values for it:
448 @table @asis
449 @item @var{variable}
450 Use @var{variable} (a symbol) as the history list.
452 @item (@var{variable} . @var{startpos})
453 Use @var{variable} (a symbol) as the history list, and assume that the
454 initial history position is @var{startpos} (a nonnegative integer).
456 Specifying 0 for @var{startpos} is equivalent to just specifying the
457 symbol @var{variable}.  @code{previous-history-element} will display
458 the most recent element of the history list in the minibuffer.  If you
459 specify a positive @var{startpos}, the minibuffer history functions
460 behave as if @code{(elt @var{variable} (1- @var{STARTPOS}))} were the
461 history element currently shown in the minibuffer.
463 For consistency, you should also specify that element of the history
464 as the initial minibuffer contents, using the @var{initial} argument
465 to the minibuffer input function (@pxref{Initial Input}).
466 @end table
468   If you don't specify @var{hist}, then the default history list
469 @code{minibuffer-history} is used.  For other standard history lists,
470 see below.  You can also create your own history list variable; just
471 initialize it to @code{nil} before the first use.
473   Both @code{read-from-minibuffer} and @code{completing-read} add new
474 elements to the history list automatically, and provide commands to
475 allow the user to reuse items on the list.  The only thing your program
476 needs to do to use a history list is to initialize it and to pass its
477 name to the input functions when you wish.  But it is safe to modify the
478 list by hand when the minibuffer input functions are not using it.
480   Emacs functions that add a new element to a history list can also
481 delete old elements if the list gets too long.  The variable
482 @code{history-length} specifies the maximum length for most history
483 lists.  To specify a different maximum length for a particular history
484 list, put the length in the @code{history-length} property of the
485 history list symbol.  The variable @code{history-delete-duplicates}
486 specifies whether to delete duplicates in history.
488 @defun add-to-history history-var newelt &optional maxelt keep-all
489 This function adds a new element @var{newelt}, if it isn't the empty
490 string, to the history list stored in the variable @var{history-var},
491 and returns the updated history list.  It limits the list length to
492 the value of @var{maxelt} (if non-@code{nil}) or @code{history-length}
493 (described below).  The possible values of @var{maxelt} have the same
494 meaning as the values of @code{history-length}.
496 Normally, @code{add-to-history} removes duplicate members from the
497 history list if @code{history-delete-duplicates} is non-@code{nil}.
498 However, if @var{keep-all} is non-@code{nil}, that says not to remove
499 duplicates, and to add @var{newelt} to the list even if it is empty.
500 @end defun
502 @defvar history-add-new-input
503 If the value of this variable is @code{nil}, standard functions that
504 read from the minibuffer don't add new elements to the history list.
505 This lets Lisp programs explicitly manage input history by using
506 @code{add-to-history}.  By default, @code{history-add-new-input} is
507 set to a non-@code{nil} value.
508 @end defvar
510 @defopt history-length
511 The value of this variable specifies the maximum length for all
512 history lists that don't specify their own maximum lengths.  If the
513 value is @code{t}, that means there is no maximum (don't delete old
514 elements).  The value of @code{history-length} property of the history
515 list variable's symbol, if set, overrides this variable for that
516 particular history list.
517 @end defopt
519 @defopt history-delete-duplicates
520 If the value of this variable is @code{t}, that means when adding a
521 new history element, all previous identical elements are deleted.
522 @end defopt
524   Here are some of the standard minibuffer history list variables:
526 @defvar minibuffer-history
527 The default history list for minibuffer history input.
528 @end defvar
530 @defvar query-replace-history
531 A history list for arguments to @code{query-replace} (and similar
532 arguments to other commands).
533 @end defvar
535 @defvar file-name-history
536 A history list for file-name arguments.
537 @end defvar
539 @defvar buffer-name-history
540 A history list for buffer-name arguments.
541 @end defvar
543 @defvar regexp-history
544 A history list for regular expression arguments.
545 @end defvar
547 @defvar extended-command-history
548 A history list for arguments that are names of extended commands.
549 @end defvar
551 @defvar shell-command-history
552 A history list for arguments that are shell commands.
553 @end defvar
555 @defvar read-expression-history
556 A history list for arguments that are Lisp expressions to evaluate.
557 @end defvar
559 @node Initial Input
560 @section Initial Input
562 Several of the functions for minibuffer input have an argument called
563 @var{initial} or @var{initial-contents}.  This is a mostly-deprecated
564 feature for specifying that the minibuffer should start out with
565 certain text, instead of empty as usual.
567 If @var{initial} is a string, the minibuffer starts out containing the
568 text of the string, with point at the end, when the user starts to
569 edit the text.  If the user simply types @key{RET} to exit the
570 minibuffer, it will use the initial input string to determine the
571 value to return.
573 @strong{We discourage use of a non-@code{nil} value for
574 @var{initial}}, because initial input is an intrusive interface.
575 History lists and default values provide a much more convenient method
576 to offer useful default inputs to the user.
578 There is just one situation where you should specify a string for an
579 @var{initial} argument.  This is when you specify a cons cell for the
580 @var{hist} or @var{history} argument.  @xref{Minibuffer History}.
582 @var{initial} can also be a cons cell of the form @code{(@var{string}
583 . @var{position})}.  This means to insert @var{string} in the
584 minibuffer but put point at @var{position} within the string's text.
586 As a historical accident, @var{position} was implemented
587 inconsistently in different functions.  In @code{completing-read},
588 @var{position}'s value is interpreted as origin-zero; that is, a value
589 of 0 means the beginning of the string, 1 means after the first
590 character, etc.  In @code{read-minibuffer}, and the other
591 non-completion minibuffer input functions that support this argument,
592 1 means the beginning of the string 2 means after the first character,
593 etc.
595 Use of a cons cell as the value for @var{initial} arguments is
596 deprecated in user code.
598 @node Completion
599 @section Completion
600 @cindex completion
602   @dfn{Completion} is a feature that fills in the rest of a name
603 starting from an abbreviation for it.  Completion works by comparing the
604 user's input against a list of valid names and determining how much of
605 the name is determined uniquely by what the user has typed.  For
606 example, when you type @kbd{C-x b} (@code{switch-to-buffer}) and then
607 type the first few letters of the name of the buffer to which you wish
608 to switch, and then type @key{TAB} (@code{minibuffer-complete}), Emacs
609 extends the name as far as it can.
611   Standard Emacs commands offer completion for names of symbols, files,
612 buffers, and processes; with the functions in this section, you can
613 implement completion for other kinds of names.
615   The @code{try-completion} function is the basic primitive for
616 completion: it returns the longest determined completion of a given
617 initial string, with a given set of strings to match against.
619   The function @code{completing-read} provides a higher-level interface
620 for completion.  A call to @code{completing-read} specifies how to
621 determine the list of valid names.  The function then activates the
622 minibuffer with a local keymap that binds a few keys to commands useful
623 for completion.  Other functions provide convenient simple interfaces
624 for reading certain kinds of names with completion.
626 @menu
627 * Basic Completion::       Low-level functions for completing strings.
628 * Minibuffer Completion::  Invoking the minibuffer with completion.
629 * Completion Commands::    Minibuffer commands that do completion.
630 * High-Level Completion::  Convenient special cases of completion
631                              (reading buffer name, file name, etc.).
632 * Reading File Names::     Using completion to read file names and
633                              shell commands.
634 * Completion Styles::      Specifying rules for performing completion.
635 * Programmed Completion::  Writing your own completion-function.
636 * Completion in Buffers::  Completing text in ordinary buffers.
637 @end menu
639 @node Basic Completion
640 @subsection Basic Completion Functions
642   The following completion functions have nothing in themselves to do
643 with minibuffers.  We describe them here to keep them near the
644 higher-level completion features that do use the minibuffer.
646 @defun try-completion string collection &optional predicate
647 This function returns the longest common substring of all possible
648 completions of @var{string} in @var{collection}.
650 @cindex completion table
651 The @var{collection} argument is called the @dfn{completion table}.
652 Its value must be a list of strings, an alist whose keys are strings
653 or symbols, an obarray, a hash table, or a completion function.
655 Completion compares @var{string} against each of the permissible
656 completions specified by @var{collection}.  If no permissible
657 completions match, @code{try-completion} returns @code{nil}.  If there
658 is just one matching completion, and the match is exact, it returns
659 @code{t}.  Otherwise, it returns the longest initial sequence common
660 to all possible matching completions.
662 If @var{collection} is an alist (@pxref{Association Lists}), the
663 permissible completions are the elements of the alist that are either
664 strings, or conses whose @sc{car} is a string or symbol.
665 Symbols are converted to strings using @code{symbol-name}.  Other
666 elements of the alist are ignored. (Remember that in Emacs Lisp, the
667 elements of alists do not @emph{have} to be conses.)  In particular, a
668 list of strings is allowed, even though we usually do not
669 think of such lists as alists.
671 @cindex obarray in completion
672 If @var{collection} is an obarray (@pxref{Creating Symbols}), the names
673 of all symbols in the obarray form the set of permissible completions.  The
674 global variable @code{obarray} holds an obarray containing the names of
675 all interned Lisp symbols.
677 Note that the only valid way to make a new obarray is to create it
678 empty and then add symbols to it one by one using @code{intern}.
679 Also, you cannot intern a given symbol in more than one obarray.
681 If @var{collection} is a hash table, then the keys that are strings
682 are the possible completions.  Other keys are ignored.
684 You can also use a function as @var{collection}.  Then the function is
685 solely responsible for performing completion; @code{try-completion}
686 returns whatever this function returns.  The function is called with
687 three arguments: @var{string}, @var{predicate} and @code{nil} (the
688 reason for the third argument is so that the same function can be used
689 in @code{all-completions} and do the appropriate thing in either
690 case).  @xref{Programmed Completion}.
692 If the argument @var{predicate} is non-@code{nil}, then it must be a
693 function of one argument, unless @var{collection} is a hash table, in
694 which case it should be a function of two arguments.  It is used to
695 test each possible match, and the match is accepted only if
696 @var{predicate} returns non-@code{nil}.  The argument given to
697 @var{predicate} is either a string or a cons cell (the @sc{car} of
698 which is a string) from the alist, or a symbol (@emph{not} a symbol
699 name) from the obarray.  If @var{collection} is a hash table,
700 @var{predicate} is called with two arguments, the string key and the
701 associated value.
703 In addition, to be acceptable, a completion must also match all the
704 regular expressions in @code{completion-regexp-list}.  (Unless
705 @var{collection} is a function, in which case that function has to
706 handle @code{completion-regexp-list} itself.)
708 In the first of the following examples, the string @samp{foo} is
709 matched by three of the alist @sc{car}s.  All of the matches begin with
710 the characters @samp{fooba}, so that is the result.  In the second
711 example, there is only one possible match, and it is exact, so the value
712 is @code{t}.
714 @smallexample
715 @group
716 (try-completion
717  "foo"
718  '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)))
719      @result{} "fooba"
720 @end group
722 @group
723 (try-completion "foo" '(("barfoo" 2) ("foo" 3)))
724      @result{} t
725 @end group
726 @end smallexample
728 In the following example, numerous symbols begin with the characters
729 @samp{forw}, and all of them begin with the word @samp{forward}.  In
730 most of the symbols, this is followed with a @samp{-}, but not in all,
731 so no more than @samp{forward} can be completed.
733 @smallexample
734 @group
735 (try-completion "forw" obarray)
736      @result{} "forward"
737 @end group
738 @end smallexample
740 Finally, in the following example, only two of the three possible
741 matches pass the predicate @code{test} (the string @samp{foobaz} is
742 too short).  Both of those begin with the string @samp{foobar}.
744 @smallexample
745 @group
746 (defun test (s)
747   (> (length (car s)) 6))
748      @result{} test
749 @end group
750 @group
751 (try-completion
752  "foo"
753  '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
754  'test)
755      @result{} "foobar"
756 @end group
757 @end smallexample
758 @end defun
760 @defun all-completions string collection &optional predicate nospace
761 This function returns a list of all possible completions of
762 @var{string}.  The arguments to this function (aside from
763 @var{nospace}) are the same as those of @code{try-completion}.  Also,
764 this function uses @code{completion-regexp-list} in the same way that
765 @code{try-completion} does.
767 The optional argument @var{nospace} is obsolete.  If it is
768 non-@code{nil}, completions that start with a space are ignored unless
769 @var{string} starts with a space.
771 If @var{collection} is a function, it is called with three arguments:
772 @var{string}, @var{predicate} and @code{t}; then @code{all-completions}
773 returns whatever the function returns.  @xref{Programmed Completion}.
775 Here is an example, using the function @code{test} shown in the
776 example for @code{try-completion}:
778 @smallexample
779 @group
780 (defun test (s)
781   (> (length (car s)) 6))
782      @result{} test
783 @end group
785 @group
786 (all-completions
787  "foo"
788  '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
789  'test)
790      @result{} ("foobar1" "foobar2")
791 @end group
792 @end smallexample
793 @end defun
795 @defun test-completion string collection &optional predicate
796 @anchor{Definition of test-completion}
797 This function returns non-@code{nil} if @var{string} is a valid
798 completion possibility specified by @var{collection} and
799 @var{predicate}.  The arguments are the same as in
800 @code{try-completion}.  For instance, if @var{collection} is a list of
801 strings, this is true if @var{string} appears in the list and
802 @var{predicate} is satisfied.
804 This function uses @code{completion-regexp-list} in the same
805 way that @code{try-completion} does.
807 If @var{predicate} is non-@code{nil} and if @var{collection} contains
808 several strings that are equal to each other, as determined by
809 @code{compare-strings} according to @code{completion-ignore-case},
810 then @var{predicate} should accept either all or none of them.
811 Otherwise, the return value of @code{test-completion} is essentially
812 unpredictable.
814 If @var{collection} is a function, it is called with three arguments,
815 the values @var{string}, @var{predicate} and @code{lambda}; whatever
816 it returns, @code{test-completion} returns in turn.
817 @end defun
819 @defun completion-boundaries string collection predicate suffix
820 This function returns the boundaries of the field on which @var{collection}
821 will operate, assuming that @var{string} holds the text before point
822 and @var{suffix} holds the text after point.
824 Normally completion operates on the whole string, so for all normal
825 collections, this will always return @code{(0 . (length
826 @var{suffix}))}.  But more complex completion such as completion on
827 files is done one field at a time.  For example, completion of
828 @code{"/usr/sh"} will include @code{"/usr/share/"} but not
829 @code{"/usr/share/doc"} even if @code{"/usr/share/doc"} exists.
830 Also @code{all-completions} on @code{"/usr/sh"} will not include
831 @code{"/usr/share/"} but only @code{"share/"}.  So if @var{string} is
832 @code{"/usr/sh"} and @var{suffix} is @code{"e/doc"},
833 @code{completion-boundaries} will return @code{(5 . 1)} which tells us
834 that the @var{collection} will only return completion information that
835 pertains to the area after @code{"/usr/"} and before @code{"/doc"}.
836 @end defun
838 If you store a completion alist in a variable, you should mark the
839 variable as ``risky'' with a non-@code{nil}
840 @code{risky-local-variable} property.  @xref{File Local Variables}.
842 @defvar completion-ignore-case
843 If the value of this variable is non-@code{nil}, case is not
844 considered significant in completion.  Within @code{read-file-name},
845 this variable is overridden by
846 @code{read-file-name-completion-ignore-case} (@pxref{Reading File
847 Names}); within @code{read-buffer}, it is overridden by
848 @code{read-buffer-completion-ignore-case} (@pxref{High-Level
849 Completion}).
850 @end defvar
852 @defvar completion-regexp-list
853 This is a list of regular expressions.  The completion functions only
854 consider a completion acceptable if it matches all regular expressions
855 in this list, with @code{case-fold-search} (@pxref{Searching and Case})
856 bound to the value of @code{completion-ignore-case}.
857 @end defvar
859 @defmac lazy-completion-table var fun
860 This macro provides a way to initialize the variable @var{var} as a
861 collection for completion in a lazy way, not computing its actual
862 contents until they are first needed.  You use this macro to produce a
863 value that you store in @var{var}.  The actual computation of the
864 proper value is done the first time you do completion using @var{var}.
865 It is done by calling @var{fun} with no arguments.  The
866 value @var{fun} returns becomes the permanent value of @var{var}.
868 Here is a usage example:
870 @smallexample
871 (defvar foo (lazy-completion-table foo make-my-alist))
872 @end smallexample
873 @end defmac
875 @node Minibuffer Completion
876 @subsection Completion and the Minibuffer
877 @cindex minibuffer completion
878 @cindex reading from minibuffer with completion
880   This section describes the basic interface for reading from the
881 minibuffer with completion.
883 @defun completing-read prompt collection &optional predicate require-match initial hist default inherit-input-method
884 This function reads a string in the minibuffer, assisting the user by
885 providing completion.  It activates the minibuffer with prompt
886 @var{prompt}, which must be a string.
888 The actual completion is done by passing the completion table
889 @var{collection} and the completion predicate @var{predicate} to the
890 function @code{try-completion} (@pxref{Basic Completion}).  This
891 happens in certain commands bound in the local keymaps used for
892 completion.  Some of these commands also call @code{test-completion}.
893 Thus, if @var{predicate} is non-@code{nil}, it should be compatible
894 with @var{collection} and @code{completion-ignore-case}.
895 @xref{Definition of test-completion}.
897 The value of the optional argument @var{require-match} determines how
898 the user may exit the minibuffer:
900 @itemize @bullet
901 @item
902 If @code{nil}, the usual minibuffer exit commands work regardless of
903 the input in the minibuffer.
905 @item
906 If @code{t}, the usual minibuffer exit commands won't exit unless the
907 input completes to an element of @var{collection}.
909 @item
910 If @code{confirm}, the user can exit with any input, but is asked for
911 confirmation if the input is not an element of @var{collection}.
913 @item
914 If @code{confirm-after-completion}, the user can exit with any input,
915 but is asked for confirmation if the preceding command was a
916 completion command (i.e., one of the commands in
917 @code{minibuffer-confirm-exit-commands}) and the resulting input is
918 not an element of @var{collection}.  @xref{Completion Commands}.
920 @item
921 Any other value of @var{require-match} behaves like @code{t}, except
922 that the exit commands won't exit if it performs completion.
923 @end itemize
925 However, empty input is always permitted, regardless of the value of
926 @var{require-match}; in that case, @code{completing-read} returns the
927 first element of @var{default}, if it is a list; @code{""}, if
928 @var{default} is @code{nil}; or @var{default}.  The string or strings
929 in @var{default} are also available to the user through the history
930 commands.
932 The function @code{completing-read} uses
933 @code{minibuffer-local-completion-map} as the keymap if
934 @var{require-match} is @code{nil}, and uses
935 @code{minibuffer-local-must-match-map} if @var{require-match} is
936 non-@code{nil}.  @xref{Completion Commands}.
938 The argument @var{hist} specifies which history list variable to use for
939 saving the input and for minibuffer history commands.  It defaults to
940 @code{minibuffer-history}.  @xref{Minibuffer History}.
942 The argument @var{initial} is mostly deprecated; we recommend using a
943 non-@code{nil} value only in conjunction with specifying a cons cell
944 for @var{hist}.  @xref{Initial Input}.  For default input, use
945 @var{default} instead.
947 If the argument @var{inherit-input-method} is non-@code{nil}, then the
948 minibuffer inherits the current input method (@pxref{Input
949 Methods}) and the setting of @code{enable-multibyte-characters}
950 (@pxref{Text Representations}) from whichever buffer was current before
951 entering the minibuffer.
953 If the built-in variable @code{completion-ignore-case} is
954 non-@code{nil}, completion ignores case when comparing the input
955 against the possible matches.  @xref{Basic Completion}.  In this mode
956 of operation, @var{predicate} must also ignore case, or you will get
957 surprising results.
959 Here's an example of using @code{completing-read}:
961 @smallexample
962 @group
963 (completing-read
964  "Complete a foo: "
965  '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
966  nil t "fo")
967 @end group
969 @group
970 ;; @r{After evaluation of the preceding expression,}
971 ;;   @r{the following appears in the minibuffer:}
973 ---------- Buffer: Minibuffer ----------
974 Complete a foo: fo@point{}
975 ---------- Buffer: Minibuffer ----------
976 @end group
977 @end smallexample
979 @noindent
980 If the user then types @kbd{@key{DEL} @key{DEL} b @key{RET}},
981 @code{completing-read} returns @code{barfoo}.
983 The @code{completing-read} function binds variables to pass
984 information to the commands that actually do completion.
985 They are described in the following section.
986 @end defun
988 @node Completion Commands
989 @subsection Minibuffer Commands that Do Completion
991   This section describes the keymaps, commands and user options used
992 in the minibuffer to do completion.
994 @defvar minibuffer-completion-table
995 The value of this variable is the completion table used for completion
996 in the minibuffer.  This is the global variable that contains what
997 @code{completing-read} passes to @code{try-completion}.  It is used by
998 minibuffer completion commands such as
999 @code{minibuffer-complete-word}.
1000 @end defvar
1002 @defvar minibuffer-completion-predicate
1003 This variable's value is the predicate that @code{completing-read}
1004 passes to @code{try-completion}.  The variable is also used by the other
1005 minibuffer completion functions.
1006 @end defvar
1008 @defvar minibuffer-completion-confirm
1009 This variable determines whether Emacs asks for confirmation before
1010 exiting the minibuffer; @code{completing-read} binds this variable,
1011 and the function @code{minibuffer-complete-and-exit} checks the value
1012 before exiting.  If the value is @code{nil}, confirmation is not
1013 required.  If the value is @code{confirm}, the user may exit with an
1014 input that is not a valid completion alternative, but Emacs asks for
1015 confirmation.  If the value is @code{confirm-after-completion}, the
1016 user may exit with an input that is not a valid completion
1017 alternative, but Emacs asks for confirmation if the user submitted the
1018 input right after any of the completion commands in
1019 @code{minibuffer-confirm-exit-commands}.
1020 @end defvar
1022 @defvar minibuffer-confirm-exit-commands
1023 This variable holds a list of commands that cause Emacs to ask for
1024 confirmation before exiting the minibuffer, if the @var{require-match}
1025 argument to @code{completing-read} is @code{confirm-after-completion}.
1026 The confirmation is requested if the user attempts to exit the
1027 minibuffer immediately after calling any command in this list.
1028 @end defvar
1030 @deffn Command minibuffer-complete-word
1031 This function completes the minibuffer contents by at most a single
1032 word.  Even if the minibuffer contents have only one completion,
1033 @code{minibuffer-complete-word} does not add any characters beyond the
1034 first character that is not a word constituent.  @xref{Syntax Tables}.
1035 @end deffn
1037 @deffn Command minibuffer-complete
1038 This function completes the minibuffer contents as far as possible.
1039 @end deffn
1041 @deffn Command minibuffer-complete-and-exit
1042 This function completes the minibuffer contents, and exits if
1043 confirmation is not required, i.e., if
1044 @code{minibuffer-completion-confirm} is @code{nil}.  If confirmation
1045 @emph{is} required, it is given by repeating this command
1046 immediately---the command is programmed to work without confirmation
1047 when run twice in succession.
1048 @end deffn
1050 @deffn Command minibuffer-completion-help
1051 This function creates a list of the possible completions of the
1052 current minibuffer contents.  It works by calling @code{all-completions}
1053 using the value of the variable @code{minibuffer-completion-table} as
1054 the @var{collection} argument, and the value of
1055 @code{minibuffer-completion-predicate} as the @var{predicate} argument.
1056 The list of completions is displayed as text in a buffer named
1057 @samp{*Completions*}.
1058 @end deffn
1060 @defun display-completion-list completions &optional common-substring
1061 This function displays @var{completions} to the stream in
1062 @code{standard-output}, usually a buffer.  (@xref{Read and Print}, for more
1063 information about streams.)  The argument @var{completions} is normally
1064 a list of completions just returned by @code{all-completions}, but it
1065 does not have to be.  Each element may be a symbol or a string, either
1066 of which is simply printed.  It can also be a list of two strings,
1067 which is printed as if the strings were concatenated.  The first of
1068 the two strings is the actual completion, the second string serves as
1069 annotation.
1071 The argument @var{common-substring} is the prefix that is common to
1072 all the completions.  With normal Emacs completion, it is usually the
1073 same as the string that was completed.  @code{display-completion-list}
1074 uses this to highlight text in the completion list for better visual
1075 feedback.  This is not needed in the minibuffer; for minibuffer
1076 completion, you can pass @code{nil}.
1078 This function is called by @code{minibuffer-completion-help}.  The
1079 most common way to use it is together with
1080 @code{with-output-to-temp-buffer}, like this:
1082 @example
1083 (with-output-to-temp-buffer "*Completions*"
1084   (display-completion-list
1085     (all-completions (buffer-string) my-alist)
1086     (buffer-string)))
1087 @end example
1088 @end defun
1090 @defopt completion-auto-help
1091 If this variable is non-@code{nil}, the completion commands
1092 automatically display a list of possible completions whenever nothing
1093 can be completed because the next character is not uniquely determined.
1094 @end defopt
1096 @defvar minibuffer-local-completion-map
1097 @code{completing-read} uses this value as the local keymap when an
1098 exact match of one of the completions is not required.  By default, this
1099 keymap makes the following bindings:
1101 @table @asis
1102 @item @kbd{?}
1103 @code{minibuffer-completion-help}
1105 @item @key{SPC}
1106 @code{minibuffer-complete-word}
1108 @item @key{TAB}
1109 @code{minibuffer-complete}
1110 @end table
1112 @noindent
1113 with other characters bound as in @code{minibuffer-local-map}
1114 (@pxref{Definition of minibuffer-local-map}).
1115 @end defvar
1117 @defvar minibuffer-local-must-match-map
1118 @code{completing-read} uses this value as the local keymap when an
1119 exact match of one of the completions is required.  Therefore, no keys
1120 are bound to @code{exit-minibuffer}, the command that exits the
1121 minibuffer unconditionally.  By default, this keymap makes the following
1122 bindings:
1124 @table @asis
1125 @item @kbd{?}
1126 @code{minibuffer-completion-help}
1128 @item @key{SPC}
1129 @code{minibuffer-complete-word}
1131 @item @key{TAB}
1132 @code{minibuffer-complete}
1134 @item @kbd{C-j}
1135 @code{minibuffer-complete-and-exit}
1137 @item @key{RET}
1138 @code{minibuffer-complete-and-exit}
1139 @end table
1141 @noindent
1142 with other characters bound as in @code{minibuffer-local-map}.
1143 @end defvar
1145 @defvar minibuffer-local-filename-completion-map
1146 This is like @code{minibuffer-local-completion-map}
1147 except that it does not bind @key{SPC}.  This keymap is used by the
1148 function @code{read-file-name}.
1149 @end defvar
1151 @defvar minibuffer-local-filename-must-match-map
1152 This is like @code{minibuffer-local-must-match-map}
1153 except that it does not bind @key{SPC}.  This keymap is used by the
1154 function @code{read-file-name}.
1155 @end defvar
1157 @node High-Level Completion
1158 @subsection High-Level Completion Functions
1160   This section describes the higher-level convenient functions for
1161 reading certain sorts of names with completion.
1163   In most cases, you should not call these functions in the middle of a
1164 Lisp function.  When possible, do all minibuffer input as part of
1165 reading the arguments for a command, in the @code{interactive}
1166 specification.  @xref{Defining Commands}.
1168 @defun read-buffer prompt &optional default require-match
1169 This function reads the name of a buffer and returns it as a string.
1170 The argument @var{default} is the default name to use, the value to
1171 return if the user exits with an empty minibuffer.  If non-@code{nil},
1172 it should be a string, a list of strings, or a buffer.  If it is
1173 a list, the default value is the first element of this list.  It is
1174 mentioned in the prompt, but is not inserted in the minibuffer as
1175 initial input.
1177 The argument @var{prompt} should be a string ending with a colon and a
1178 space.  If @var{default} is non-@code{nil}, the function inserts it in
1179 @var{prompt} before the colon to follow the convention for reading from
1180 the minibuffer with a default value (@pxref{Programming Tips}).
1182 The optional argument @var{require-match} has the same meaning as in
1183 @code{completing-read}.  @xref{Minibuffer Completion}.
1185 In the following example, the user enters @samp{minibuffer.t}, and
1186 then types @key{RET}.  The argument @var{require-match} is @code{t},
1187 and the only buffer name starting with the given input is
1188 @samp{minibuffer.texi}, so that name is the value.
1190 @example
1191 (read-buffer "Buffer name: " "foo" t)
1192 @group
1193 ;; @r{After evaluation of the preceding expression,}
1194 ;;   @r{the following prompt appears,}
1195 ;;   @r{with an empty minibuffer:}
1196 @end group
1198 @group
1199 ---------- Buffer: Minibuffer ----------
1200 Buffer name (default foo): @point{}
1201 ---------- Buffer: Minibuffer ----------
1202 @end group
1204 @group
1205 ;; @r{The user types @kbd{minibuffer.t @key{RET}}.}
1206      @result{} "minibuffer.texi"
1207 @end group
1208 @end example
1209 @end defun
1211 @defopt read-buffer-function
1212 This variable specifies how to read buffer names.  The function is
1213 called with the arguments passed to @code{read-buffer}.  For example,
1214 if you set this variable to @code{iswitchb-read-buffer}, all Emacs
1215 commands that call @code{read-buffer} to read a buffer name will
1216 actually use the @code{iswitchb} package to read it.
1217 @end defopt
1219 @defopt read-buffer-completion-ignore-case
1220 If this variable is non-@code{nil}, @code{read-buffer} ignores case
1221 when performing completion.
1222 @end defopt
1224 @defun read-command prompt &optional default
1225 This function reads the name of a command and returns it as a Lisp
1226 symbol.  The argument @var{prompt} is used as in
1227 @code{read-from-minibuffer}.  Recall that a command is anything for
1228 which @code{commandp} returns @code{t}, and a command name is a symbol
1229 for which @code{commandp} returns @code{t}.  @xref{Interactive Call}.
1231 The argument @var{default} specifies what to return if the user enters
1232 null input.  It can be a symbol, a string or a list of strings.  If it
1233 is a string, @code{read-command} interns it before returning it.
1234 If it is a list, @code{read-command} returns the first element of this list.
1235 If @var{default} is @code{nil}, that means no default has been
1236 specified; then if the user enters null input, the return value is
1237 @code{(intern "")}, that is, a symbol whose name is an empty string.
1239 @example
1240 (read-command "Command name? ")
1242 @group
1243 ;; @r{After evaluation of the preceding expression,}
1244 ;;   @r{the following prompt appears with an empty minibuffer:}
1245 @end group
1247 @group
1248 ---------- Buffer: Minibuffer ----------
1249 Command name?
1250 ---------- Buffer: Minibuffer ----------
1251 @end group
1252 @end example
1254 @noindent
1255 If the user types @kbd{forward-c @key{RET}}, then this function returns
1256 @code{forward-char}.
1258 The @code{read-command} function is a simplified interface to
1259 @code{completing-read}.  It uses the variable @code{obarray} so as to
1260 complete in the set of extant Lisp symbols, and it uses the
1261 @code{commandp} predicate so as to accept only command names:
1263 @cindex @code{commandp} example
1264 @example
1265 @group
1266 (read-command @var{prompt})
1267 @equiv{}
1268 (intern (completing-read @var{prompt} obarray
1269                          'commandp t nil))
1270 @end group
1271 @end example
1272 @end defun
1274 @defun read-variable prompt &optional default
1275 @anchor{Definition of read-variable}
1276 This function reads the name of a user variable and returns it as a
1277 symbol.
1279 The argument @var{default} specifies the default value to return if
1280 the user enters null input.  It can be a symbol, a string, or a list
1281 of strings.  If it is a string, @code{read-variable} interns it to
1282 make the default value.  If it is a list, @code{read-variable} interns
1283 the first element.  If @var{default} is @code{nil}, that means no
1284 default has been specified; then if the user enters null input, the
1285 return value is @code{(intern "")}.
1287 @example
1288 @group
1289 (read-variable "Variable name? ")
1291 ;; @r{After evaluation of the preceding expression,}
1292 ;;   @r{the following prompt appears,}
1293 ;;   @r{with an empty minibuffer:}
1294 @end group
1296 @group
1297 ---------- Buffer: Minibuffer ----------
1298 Variable name? @point{}
1299 ---------- Buffer: Minibuffer ----------
1300 @end group
1301 @end example
1303 @noindent
1304 If the user then types @kbd{fill-p @key{RET}}, @code{read-variable}
1305 returns @code{fill-prefix}.
1307 In general, @code{read-variable} is similar to @code{read-command},
1308 but uses the predicate @code{user-variable-p} instead of
1309 @code{commandp}:
1311 @cindex @code{user-variable-p} example
1312 @example
1313 @group
1314 (read-variable @var{prompt})
1315 @equiv{}
1316 (intern
1317  (completing-read @var{prompt} obarray
1318                   'user-variable-p t nil))
1319 @end group
1320 @end example
1321 @end defun
1323 @deffn Command read-color &optional prompt convert allow-empty display
1324 This function reads a string that is a color specification, either the
1325 color's name or an RGB hex value such as @code{#RRRGGGBBB}.  It
1326 prompts with @var{prompt} (default: @code{"Color (name or #RGB triplet):"})
1327 and provides completion for color names, but not for hex RGB values.
1328 In addition to names of standard colors, completion candidates include
1329 the foreground and background colors at point.
1331 Valid RGB values are described in @ref{Color Names}.
1333 The function's return value is the string typed by the user in the
1334 minibuffer.  However, when called interactively or if the optional
1335 argument @var{convert} is non-@code{nil}, it converts any input color
1336 name into the corresponding RGB value string and instead returns that.
1337 This function requires a valid color specification to be input.
1338 Empty color names are allowed when @code{allow-empty} is
1339 non-@code{nil} and the user enters null input.
1341 Interactively, or when @var{display} is non-@code{nil}, the return
1342 value is also displayed in the echo area.
1343 @end deffn
1345   See also the functions @code{read-coding-system} and
1346 @code{read-non-nil-coding-system}, in @ref{User-Chosen Coding Systems},
1347 and @code{read-input-method-name}, in @ref{Input Methods}.
1349 @node Reading File Names
1350 @subsection Reading File Names
1351 @cindex read file names
1352 @cindex prompt for file name
1354   The high-level completion functions @code{read-file-name},
1355 @code{read-directory-name}, and @code{read-shell-command} are designed
1356 to read file names, directory names, and shell commands respectively.
1357 They provide special features, including automatic insertion of the
1358 default directory.
1360 @defun read-file-name prompt &optional directory default require-match initial predicate
1361 This function reads a file name, prompting with @var{prompt} and
1362 providing completion.
1364 As an exception, this function reads a file name using a graphical
1365 file dialog instead of the minibuffer, if (i) it is invoked via a
1366 mouse command, and (ii) the selected frame is on a graphical display
1367 supporting such dialogs, and (iii) the variable @code{use-dialog-box}
1368 is non-@code{nil} (@pxref{Dialog Boxes,, Dialog Boxes, emacs, The GNU
1369 Emacs Manual}), and (iv) the @var{directory} argument, described
1370 below, does not specify a remote file (@pxref{Remote Files,, Remote
1371 Files, emacs, The GNU Emacs Manual}).  The exact behavior when using a
1372 graphical file dialog is platform-dependent.  Here, we simply document
1373 the behavior when using the minibuffer.
1375 @code{read-file-name} does not automatically expand the returned file
1376 name.  You must call @code{expand-file-name} yourself if an absolute
1377 file name is required.
1379 The optional argument @var{require-match} has the same meaning as in
1380 @code{completing-read}.  @xref{Minibuffer Completion}.  If
1381 @var{require-match} is @code{nil}, the local keymap in the minibuffer
1382 is @code{minibuffer-local-filename-completion-map}; otherwise, it is
1383 @code{minibuffer-local-filename-must-match-map}.  @xref{Completion
1384 Commands}.
1386 The argument @var{directory} specifies the directory to use for
1387 completing relative file names.  It should be an absolute directory
1388 name.  If @code{insert-default-directory} is non-@code{nil},
1389 @var{directory} is also inserted in the minibuffer as initial input.
1390 It defaults to the current buffer's value of @code{default-directory}.
1392 If you specify @var{initial}, that is an initial file name to insert
1393 in the buffer (after @var{directory}, if that is inserted).  In this
1394 case, point goes at the beginning of @var{initial}.  The default for
1395 @var{initial} is @code{nil}---don't insert any file name.  To see what
1396 @var{initial} does, try the command @kbd{C-x C-v}.  @strong{Please
1397 note:} we recommend using @var{default} rather than @var{initial} in
1398 most cases.
1400 If @var{default} is non-@code{nil}, then the function returns
1401 @var{default} if the user exits the minibuffer with the same non-empty
1402 contents that @code{read-file-name} inserted initially.  The initial
1403 minibuffer contents are always non-empty if
1404 @code{insert-default-directory} is non-@code{nil}, as it is by
1405 default.  @var{default} is not checked for validity, regardless of the
1406 value of @var{require-match}.  However, if @var{require-match} is
1407 non-@code{nil}, the initial minibuffer contents should be a valid file
1408 (or directory) name.  Otherwise @code{read-file-name} attempts
1409 completion if the user exits without any editing, and does not return
1410 @var{default}.  @var{default} is also available through the history
1411 commands.
1413 If @var{default} is @code{nil}, @code{read-file-name} tries to find a
1414 substitute default to use in its place, which it treats in exactly the
1415 same way as if it had been specified explicitly.  If @var{default} is
1416 @code{nil}, but @var{initial} is non-@code{nil}, then the default is
1417 the absolute file name obtained from @var{directory} and
1418 @var{initial}.  If both @var{default} and @var{initial} are @code{nil}
1419 and the buffer is visiting a file, @code{read-file-name} uses the
1420 absolute file name of that file as default.  If the buffer is not
1421 visiting a file, then there is no default.  In that case, if the user
1422 types @key{RET} without any editing, @code{read-file-name} simply
1423 returns the pre-inserted contents of the minibuffer.
1425 If the user types @key{RET} in an empty minibuffer, this function
1426 returns an empty string, regardless of the value of
1427 @var{require-match}.  This is, for instance, how the user can make the
1428 current buffer visit no file using @code{M-x set-visited-file-name}.
1430 If @var{predicate} is non-@code{nil}, it specifies a function of one
1431 argument that decides which file names are acceptable completion
1432 possibilities.  A file name is an acceptable value if @var{predicate}
1433 returns non-@code{nil} for it.
1435 Here is an example of using @code{read-file-name}:
1437 @example
1438 @group
1439 (read-file-name "The file is ")
1441 ;; @r{After evaluation of the preceding expression,}
1442 ;;   @r{the following appears in the minibuffer:}
1443 @end group
1445 @group
1446 ---------- Buffer: Minibuffer ----------
1447 The file is /gp/gnu/elisp/@point{}
1448 ---------- Buffer: Minibuffer ----------
1449 @end group
1450 @end example
1452 @noindent
1453 Typing @kbd{manual @key{TAB}} results in the following:
1455 @example
1456 @group
1457 ---------- Buffer: Minibuffer ----------
1458 The file is /gp/gnu/elisp/manual.texi@point{}
1459 ---------- Buffer: Minibuffer ----------
1460 @end group
1461 @end example
1463 @c Wordy to avoid overfull hbox in smallbook mode.
1464 @noindent
1465 If the user types @key{RET}, @code{read-file-name} returns the file name
1466 as the string @code{"/gp/gnu/elisp/manual.texi"}.
1467 @end defun
1469 @defvar read-file-name-function
1470 If non-@code{nil}, this should be a function that accepts the same
1471 arguments as @code{read-file-name}.  When @code{read-file-name} is
1472 called, it calls this function with the supplied arguments instead of
1473 doing its usual work.
1474 @end defvar
1476 @defopt read-file-name-completion-ignore-case
1477 If this variable is non-@code{nil}, @code{read-file-name} ignores case
1478 when performing completion.
1479 @end defopt
1481 @defun read-directory-name prompt &optional directory default require-match initial
1482 This function is like @code{read-file-name} but allows only directory
1483 names as completion possibilities.
1485 If @var{default} is @code{nil} and @var{initial} is non-@code{nil},
1486 @code{read-directory-name} constructs a substitute default by
1487 combining @var{directory} (or the current buffer's default directory
1488 if @var{directory} is @code{nil}) and @var{initial}.  If both
1489 @var{default} and @var{initial} are @code{nil}, this function uses
1490 @var{directory} as substitute default, or the current buffer's default
1491 directory if @var{directory} is @code{nil}.
1492 @end defun
1494 @defopt insert-default-directory
1495 This variable is used by @code{read-file-name}, and thus, indirectly,
1496 by most commands reading file names.  (This includes all commands that
1497 use the code letters @samp{f} or @samp{F} in their interactive form.
1498 @xref{Interactive Codes,, Code Characters for interactive}.)  Its
1499 value controls whether @code{read-file-name} starts by placing the
1500 name of the default directory in the minibuffer, plus the initial file
1501 name if any.  If the value of this variable is @code{nil}, then
1502 @code{read-file-name} does not place any initial input in the
1503 minibuffer (unless you specify initial input with the @var{initial}
1504 argument).  In that case, the default directory is still used for
1505 completion of relative file names, but is not displayed.
1507 If this variable is @code{nil} and the initial minibuffer contents are
1508 empty, the user may have to explicitly fetch the next history element
1509 to access a default value.  If the variable is non-@code{nil}, the
1510 initial minibuffer contents are always non-empty and the user can
1511 always request a default value by immediately typing @key{RET} in an
1512 unedited minibuffer.  (See above.)
1514 For example:
1516 @example
1517 @group
1518 ;; @r{Here the minibuffer starts out with the default directory.}
1519 (let ((insert-default-directory t))
1520   (read-file-name "The file is "))
1521 @end group
1523 @group
1524 ---------- Buffer: Minibuffer ----------
1525 The file is ~lewis/manual/@point{}
1526 ---------- Buffer: Minibuffer ----------
1527 @end group
1529 @group
1530 ;; @r{Here the minibuffer is empty and only the prompt}
1531 ;;   @r{appears on its line.}
1532 (let ((insert-default-directory nil))
1533   (read-file-name "The file is "))
1534 @end group
1536 @group
1537 ---------- Buffer: Minibuffer ----------
1538 The file is @point{}
1539 ---------- Buffer: Minibuffer ----------
1540 @end group
1541 @end example
1542 @end defopt
1544 @defun read-shell-command prompt &optional initial-contents hist &rest args
1545 This function reads a shell command from the minibuffer, prompting
1546 with @var{prompt} and providing intelligent completion.  It completes
1547 the first word of the command using candidates that are appropriate
1548 for command names, and the rest of the command words as file names.
1550 This function uses @code{minibuffer-local-shell-command-map} as the
1551 keymap for minibuffer input.  The @var{hist} argument specifies the
1552 history list to use; if is omitted or @code{nil}, it defaults to
1553 @code{shell-command-history} (@pxref{Minibuffer History,
1554 shell-command-history}).  The optional argument @var{initial-contents}
1555 specifies the initial content of the minibuffer (@pxref{Initial
1556 Input}).  The rest of @var{args}, if present, are used as the
1557 @var{default} and @var{inherit-input-method} arguments in
1558 @code{read-from-minibuffer} (@pxref{Text from Minibuffer}).
1559 @end defun
1561 @defvar minibuffer-local-shell-command-map
1562 This keymap is used by @code{read-shell-command} for completing
1563 command and file names that are part of a shell command.
1564 @end defvar
1566 @node Completion Styles
1567 @subsection Completion Styles
1568 @cindex completion styles
1570   A @dfn{completion style} is a set of rules for generating
1571 completions.  The user option @code{completion-styles} stores a list
1572 of completion styles, which are represented by symbols.
1574 @defopt completion-styles
1575 This is a list of completion style symbols to use for performing
1576 completion.  Each completion style in this list must be defined in
1577 @code{completion-styles-alist}.
1578 @end defopt
1580 @defvar completion-styles-alist
1581 This variable stores a list of available completion styles.  Each
1582 element in the list must have the form @samp{(@var{name}
1583 @var{try-completion} @var{all-completions})}.  Here, @var{name} is the
1584 name of the completion style (a symbol), which may be used in
1585 @code{completion-styles-alist} to refer to this style.
1587 @var{try-completion} is the function that does the completion, and
1588 @var{all-completions} is the function that lists the completions.
1589 These functions should accept four arguments: @var{string},
1590 @var{collection}, @var{predicate}, and @var{point}.  The @var{string},
1591 @var{collection}, and @var{predicate} arguments have the same meanings
1592 as in @code{try-completion} (@pxref{Basic Completion}), and the
1593 @var{point} argument is the position of point within @var{string}.
1594 Each function should return a non-@code{nil} value if it performed its
1595 job, and @code{nil} if it did not (e.g., if there is no way to
1596 complete @var{string} according to the completion style).
1598 When the user calls a completion command, such as
1599 @code{minibuffer-complete} (@pxref{Completion Commands}), Emacs looks
1600 for the first style listed in @code{completion-styles} and calls its
1601 @var{try-completion} function.  If this function returns @code{nil},
1602 Emacs moves to the next completion style listed in
1603 @code{completion-styles} and calls its @var{try-completion} function,
1604 and so on until one of the @var{try-completion} functions successfully
1605 performs completion and returns a non-@code{nil} value.  A similar
1606 procedure is used for listing completions, via the
1607 @var{all-completions} functions.
1608 @end defvar
1610   By default, @code{completion-styles-alist} contains five pre-defined
1611 completion styles: @code{basic}, a basic completion style;
1612 @code{partial-completion}, which does partial completion (completing
1613 each word in the input separately); @code{emacs22}, which performs
1614 completion according to the rules used in Emacs 22; @code{emacs21},
1615 which performs completion according to the rules used in Emacs 21; and
1616 @code{initials}, which completes acronyms and initialisms.
1618 @node Programmed Completion
1619 @subsection Programmed Completion
1620 @cindex programmed completion
1622   Sometimes it is not possible or convenient to create an alist or
1623 an obarray containing all the intended possible completions ahead
1624 of time.  In such a case, you can supply your own function to compute
1625 the completion of a given string.  This is called @dfn{programmed
1626 completion}.  Emacs uses programmed completion when completing file
1627 names (@pxref{File Name Completion}), among many other cases.
1629   To use this feature, pass a function as the @var{collection}
1630 argument to @code{completing-read}.  The function
1631 @code{completing-read} arranges to pass your completion function along
1632 to @code{try-completion}, @code{all-completions}, and other basic
1633 completion functions, which will then let your function do all
1634 the work.
1636   The completion function should accept three arguments:
1638 @itemize @bullet
1639 @item
1640 The string to be completed.
1642 @item
1643 The predicate function to filter possible matches, or @code{nil} if
1644 none.  Your function should call the predicate for each possible match,
1645 and ignore the possible match if the predicate returns @code{nil}.
1647 @item
1648 A flag specifying the type of operation.  The best way to think about
1649 it is that the function stands for an object (in the
1650 ``object-oriented'' sense of the word), and this third argument
1651 specifies which method to run.
1652 @end itemize
1654   There are currently four methods, i.e. four flag values, one for
1655 each of the four different basic operations:
1657 @itemize @bullet
1658 @item
1659 @code{nil} specifies @code{try-completion}.  The completion function
1660 should return the completion of the specified string, or @code{t} if the
1661 string is a unique and exact match already, or @code{nil} if the string
1662 matches no possibility.
1664 If the string is an exact match for one possibility, but also matches
1665 other longer possibilities, the function should return the string, not
1666 @code{t}.
1668 @item
1669 @code{t} specifies @code{all-completions}.  The completion function
1670 should return a list of all possible completions of the specified
1671 string.
1673 @item
1674 @code{lambda} specifies @code{test-completion}.  The completion
1675 function should return @code{t} if the specified string is an exact
1676 match for some possibility; @code{nil} otherwise.
1678 @item
1679 @code{(boundaries . SUFFIX)} specifies @code{completion-boundaries}.
1680 The function should return a value of the form @code{(boundaries
1681 START . END)} where START is the position of the beginning boundary
1682 in the string to complete, and END is the position of the end boundary
1683 in SUFFIX.
1684 @end itemize
1686 @defun completion-table-dynamic function
1687 This function is a convenient way to write a function that can act as
1688 programmed completion function.  The argument @var{function} should be
1689 a function that takes one argument, a string, and returns an alist of
1690 possible completions of it.  You can think of
1691 @code{completion-table-dynamic} as a transducer between that interface
1692 and the interface for programmed completion functions.
1693 @end defun
1695 @defvar completion-annotate-function
1696 The value of this variable, if non-@code{nil}, should be a function
1697 for ``annotating'' the entries in the @samp{*Completions*} buffer.
1698 The function should accept a single argument, the completion string
1699 for an entry.  It should return an additional string to display next
1700 to that entry in the @samp{*Completions*} buffer, or @code{nil} if no
1701 additional string is to be displayed.
1703 The function can determine the collection used for the current
1704 completion via the variable @code{minibuffer-completion-table}
1705 (@pxref{Completion Commands}).
1706 @end defvar
1708 @node Completion in Buffers
1709 @subsection Completion in Ordinary Buffers
1710 @cindex inline completion
1712 @findex completion-at-point
1713   Although completion is usually done in the minibuffer, the
1714 completion facility can also be used on the text in ordinary Emacs
1715 buffers.  In many major modes, in-buffer completion is performed by
1716 the @kbd{C-M-i} or @kbd{M-@key{TAB}} command, bound to
1717 @code{completion-at-point}.  @xref{Symbol Completion,,, emacs, The GNU
1718 Emacs Manual}.  This command uses the abnormal hook variable
1719 @code{completion-at-point-functions}:
1721 @defvar completion-at-point-functions
1722 The value of this abnormal hook should be a list of functions, which
1723 are used to compute a completion table for completing the text at
1724 point.  It can be used by major modes to provide mode-specific
1725 completion tables (@pxref{Major Mode Conventions}).
1727 When the command @code{completion-at-point} runs, it calls the
1728 functions in the list one by one, without any argument.  Each function
1729 should return @code{nil} if it is unable to produce a completion table
1730 for the text at point.  Otherwise it should return a list of the form
1732 @example
1733 (@var{start} @var{end} @var{collection} . @var{props})
1734 @end example
1736 @noindent
1737 @var{start} and @var{end} delimit the text to complete (which should
1738 enclose point).  @var{collection} is a completion table for completing
1739 that text, in a form suitable for passing as the second argument to
1740 @code{try-completion} (@pxref{Basic Completion}); completion
1741 alternatives will be generated from this completion table in the usual
1742 way, via the completion styles defined in @code{completion-styles}
1743 (@pxref{Completion Styles}).  @var{props} is a property list for
1744 additional information; the following optional properties are
1745 recognized:
1747 @table @code
1748 @item :predicate
1749 The value should be a predicate that completion candidates need to
1750 satisfy.
1752 @item :exclusive
1753 If the value is @code{no}, then if the completion table fails to match
1754 the text at point, then @code{completion-at-point} moves on to the
1755 next function in @code{completion-at-point-functions} instead of
1756 reporting a completion failure.
1757 @end table
1759 A function in @code{completion-at-point-functions} may also return a
1760 function.  In that case, that returned function is called, with no
1761 argument, and it is entirely responsible for performing the
1762 completion.  We discourage this usage; it is intended to help convert
1763 old code to using @code{completion-at-point}.
1765 The first function in @code{completion-at-point-functions} to return a
1766 non-@code{nil} value is used by @code{completion-at-point}.  The
1767 remaining functions are not called.  The exception to this is when
1768 there is a @code{:exclusive} specification, as described above.
1769 @end defvar
1771   The following function provides a convenient way to perform
1772 completion on an arbitrary stretch of text in an Emacs buffer:
1774 @defun completion-in-region start end collection &optional predicate
1775 This function completes the text in the current buffer between the
1776 positions @var{start} and @var{end}, using @var{collection}.  The
1777 argument @var{collection} has the same meaning as in
1778 @code{try-completion} (@pxref{Basic Completion}).
1780 This function inserts the completion text directly into the current
1781 buffer.  Unlike @code{completing-read} (@pxref{Minibuffer
1782 Completion}), it does not activate the minibuffer.
1784 For this function to work, point must be somewhere between @var{start}
1785 and @var{end}.
1786 @end defun
1789 @node Yes-or-No Queries
1790 @section Yes-or-No Queries
1791 @cindex asking the user questions
1792 @cindex querying the user
1793 @cindex yes-or-no questions
1795   This section describes functions used to ask the user a yes-or-no
1796 question.  The function @code{y-or-n-p} can be answered with a single
1797 character; it is useful for questions where an inadvertent wrong answer
1798 will not have serious consequences.  @code{yes-or-no-p} is suitable for
1799 more momentous questions, since it requires three or four characters to
1800 answer.
1802    If either of these functions is called in a command that was invoked
1803 using the mouse---more precisely, if @code{last-nonmenu-event}
1804 (@pxref{Command Loop Info}) is either @code{nil} or a list---then it
1805 uses a dialog box or pop-up menu to ask the question.  Otherwise, it
1806 uses keyboard input.  You can force use of the mouse or use of keyboard
1807 input by binding @code{last-nonmenu-event} to a suitable value around
1808 the call.
1810   Strictly speaking, @code{yes-or-no-p} uses the minibuffer and
1811 @code{y-or-n-p} does not; but it seems best to describe them together.
1813 @defun y-or-n-p prompt
1814 This function asks the user a question, expecting input in the echo
1815 area.  It returns @code{t} if the user types @kbd{y}, @code{nil} if the
1816 user types @kbd{n}.  This function also accepts @key{SPC} to mean yes
1817 and @key{DEL} to mean no.  It accepts @kbd{C-]} to mean ``quit,'' like
1818 @kbd{C-g}, because the question might look like a minibuffer and for
1819 that reason the user might try to use @kbd{C-]} to get out.  The answer
1820 is a single character, with no @key{RET} needed to terminate it.  Upper
1821 and lower case are equivalent.
1823 ``Asking the question'' means printing @var{prompt} in the echo area,
1824 followed by the string @w{@samp{(y or n) }}.  If the input is not one of
1825 the expected answers (@kbd{y}, @kbd{n}, @kbd{@key{SPC}},
1826 @kbd{@key{DEL}}, or something that quits), the function responds
1827 @samp{Please answer y or n.}, and repeats the request.
1829 This function does not actually use the minibuffer, since it does not
1830 allow editing of the answer.  It actually uses the echo area (@pxref{The
1831 Echo Area}), which uses the same screen space as the minibuffer.  The
1832 cursor moves to the echo area while the question is being asked.
1834 The answers and their meanings, even @samp{y} and @samp{n}, are not
1835 hardwired.  The keymap @code{query-replace-map} specifies them.
1836 @xref{Search and Replace}.
1838 In the following example, the user first types @kbd{q}, which is
1839 invalid.  At the next prompt the user types @kbd{y}.
1841 @smallexample
1842 @group
1843 (y-or-n-p "Do you need a lift? ")
1845 ;; @r{After evaluation of the preceding expression,}
1846 ;;   @r{the following prompt appears in the echo area:}
1847 @end group
1849 @group
1850 ---------- Echo area ----------
1851 Do you need a lift? (y or n)
1852 ---------- Echo area ----------
1853 @end group
1855 ;; @r{If the user then types @kbd{q}, the following appears:}
1857 @group
1858 ---------- Echo area ----------
1859 Please answer y or n.  Do you need a lift? (y or n)
1860 ---------- Echo area ----------
1861 @end group
1863 ;; @r{When the user types a valid answer,}
1864 ;;   @r{it is displayed after the question:}
1866 @group
1867 ---------- Echo area ----------
1868 Do you need a lift? (y or n) y
1869 ---------- Echo area ----------
1870 @end group
1871 @end smallexample
1873 @noindent
1874 We show successive lines of echo area messages, but only one actually
1875 appears on the screen at a time.
1876 @end defun
1878 @defun y-or-n-p-with-timeout prompt seconds default-value
1879 Like @code{y-or-n-p}, except that if the user fails to answer within
1880 @var{seconds} seconds, this function stops waiting and returns
1881 @var{default-value}.  It works by setting up a timer; see @ref{Timers}.
1882 The argument @var{seconds} may be an integer or a floating point number.
1883 @end defun
1885 @defun yes-or-no-p prompt
1886 This function asks the user a question, expecting input in the
1887 minibuffer.  It returns @code{t} if the user enters @samp{yes},
1888 @code{nil} if the user types @samp{no}.  The user must type @key{RET} to
1889 finalize the response.  Upper and lower case are equivalent.
1891 @code{yes-or-no-p} starts by displaying @var{prompt} in the echo area,
1892 followed by @w{@samp{(yes or no) }}.  The user must type one of the
1893 expected responses; otherwise, the function responds @samp{Please answer
1894 yes or no.}, waits about two seconds and repeats the request.
1896 @code{yes-or-no-p} requires more work from the user than
1897 @code{y-or-n-p} and is appropriate for more crucial decisions.
1899 Here is an example:
1901 @smallexample
1902 @group
1903 (yes-or-no-p "Do you really want to remove everything? ")
1905 ;; @r{After evaluation of the preceding expression,}
1906 ;;   @r{the following prompt appears,}
1907 ;;   @r{with an empty minibuffer:}
1908 @end group
1910 @group
1911 ---------- Buffer: minibuffer ----------
1912 Do you really want to remove everything? (yes or no)
1913 ---------- Buffer: minibuffer ----------
1914 @end group
1915 @end smallexample
1917 @noindent
1918 If the user first types @kbd{y @key{RET}}, which is invalid because this
1919 function demands the entire word @samp{yes}, it responds by displaying
1920 these prompts, with a brief pause between them:
1922 @smallexample
1923 @group
1924 ---------- Buffer: minibuffer ----------
1925 Please answer yes or no.
1926 Do you really want to remove everything? (yes or no)
1927 ---------- Buffer: minibuffer ----------
1928 @end group
1929 @end smallexample
1930 @end defun
1932 @node Multiple Queries
1933 @section Asking Multiple Y-or-N Questions
1935   When you have a series of similar questions to ask, such as ``Do you
1936 want to save this buffer'' for each buffer in turn, you should use
1937 @code{map-y-or-n-p} to ask the collection of questions, rather than
1938 asking each question individually.  This gives the user certain
1939 convenient facilities such as the ability to answer the whole series at
1940 once.
1942 @defun map-y-or-n-p prompter actor list &optional help action-alist no-cursor-in-echo-area
1943 This function asks the user a series of questions, reading a
1944 single-character answer in the echo area for each one.
1946 The value of @var{list} specifies the objects to ask questions about.
1947 It should be either a list of objects or a generator function.  If it is
1948 a function, it should expect no arguments, and should return either the
1949 next object to ask about, or @code{nil} meaning stop asking questions.
1951 The argument @var{prompter} specifies how to ask each question.  If
1952 @var{prompter} is a string, the question text is computed like this:
1954 @example
1955 (format @var{prompter} @var{object})
1956 @end example
1958 @noindent
1959 where @var{object} is the next object to ask about (as obtained from
1960 @var{list}).
1962 If not a string, @var{prompter} should be a function of one argument
1963 (the next object to ask about) and should return the question text.  If
1964 the value is a string, that is the question to ask the user.  The
1965 function can also return @code{t} meaning do act on this object (and
1966 don't ask the user), or @code{nil} meaning ignore this object (and don't
1967 ask the user).
1969 The argument @var{actor} says how to act on the answers that the user
1970 gives.  It should be a function of one argument, and it is called with
1971 each object that the user says yes for.  Its argument is always an
1972 object obtained from @var{list}.
1974 If the argument @var{help} is given, it should be a list of this form:
1976 @example
1977 (@var{singular} @var{plural} @var{action})
1978 @end example
1980 @noindent
1981 where @var{singular} is a string containing a singular noun that
1982 describes the objects conceptually being acted on, @var{plural} is the
1983 corresponding plural noun, and @var{action} is a transitive verb
1984 describing what @var{actor} does.
1986 If you don't specify @var{help}, the default is @code{("object"
1987 "objects" "act on")}.
1989 Each time a question is asked, the user may enter @kbd{y}, @kbd{Y}, or
1990 @key{SPC} to act on that object; @kbd{n}, @kbd{N}, or @key{DEL} to skip
1991 that object; @kbd{!} to act on all following objects; @key{ESC} or
1992 @kbd{q} to exit (skip all following objects); @kbd{.} (period) to act on
1993 the current object and then exit; or @kbd{C-h} to get help.  These are
1994 the same answers that @code{query-replace} accepts.  The keymap
1995 @code{query-replace-map} defines their meaning for @code{map-y-or-n-p}
1996 as well as for @code{query-replace}; see @ref{Search and Replace}.
1998 You can use @var{action-alist} to specify additional possible answers
1999 and what they mean.  It is an alist of elements of the form
2000 @code{(@var{char} @var{function} @var{help})}, each of which defines one
2001 additional answer.  In this element, @var{char} is a character (the
2002 answer); @var{function} is a function of one argument (an object from
2003 @var{list}); @var{help} is a string.
2005 When the user responds with @var{char}, @code{map-y-or-n-p} calls
2006 @var{function}.  If it returns non-@code{nil}, the object is considered
2007 ``acted upon,'' and @code{map-y-or-n-p} advances to the next object in
2008 @var{list}.  If it returns @code{nil}, the prompt is repeated for the
2009 same object.
2011 Normally, @code{map-y-or-n-p} binds @code{cursor-in-echo-area} while
2012 prompting.  But if @var{no-cursor-in-echo-area} is non-@code{nil}, it
2013 does not do that.
2015 If @code{map-y-or-n-p} is called in a command that was invoked using the
2016 mouse---more precisely, if @code{last-nonmenu-event} (@pxref{Command
2017 Loop Info}) is either @code{nil} or a list---then it uses a dialog box
2018 or pop-up menu to ask the question.  In this case, it does not use
2019 keyboard input or the echo area.  You can force use of the mouse or use
2020 of keyboard input by binding @code{last-nonmenu-event} to a suitable
2021 value around the call.
2023 The return value of @code{map-y-or-n-p} is the number of objects acted on.
2024 @end defun
2026 @node Reading a Password
2027 @section Reading a Password
2028 @cindex passwords, reading
2030   To read a password to pass to another program, you can use the
2031 function @code{read-passwd}.
2033 @defun read-passwd prompt &optional confirm default
2034 This function reads a password, prompting with @var{prompt}.  It does
2035 not echo the password as the user types it; instead, it echoes @samp{.}
2036 for each character in the password.
2038 The optional argument @var{confirm}, if non-@code{nil}, says to read the
2039 password twice and insist it must be the same both times.  If it isn't
2040 the same, the user has to type it over and over until the last two
2041 times match.
2043 The optional argument @var{default} specifies the default password to
2044 return if the user enters empty input.  If @var{default} is @code{nil},
2045 then @code{read-passwd} returns the null string in that case.
2046 @end defun
2048 @node Minibuffer Commands
2049 @section Minibuffer Commands
2051   This section describes some commands meant for use in the
2052 minibuffer.
2054 @deffn Command exit-minibuffer
2055 This command exits the active minibuffer.  It is normally bound to
2056 keys in minibuffer local keymaps.
2057 @end deffn
2059 @deffn Command self-insert-and-exit
2060 This command exits the active minibuffer after inserting the last
2061 character typed on the keyboard (found in @code{last-command-event};
2062 @pxref{Command Loop Info}).
2063 @end deffn
2065 @deffn Command previous-history-element n
2066 This command replaces the minibuffer contents with the value of the
2067 @var{n}th previous (older) history element.
2068 @end deffn
2070 @deffn Command next-history-element n
2071 This command replaces the minibuffer contents with the value of the
2072 @var{n}th more recent history element.
2073 @end deffn
2075 @deffn Command previous-matching-history-element pattern n
2076 This command replaces the minibuffer contents with the value of the
2077 @var{n}th previous (older) history element that matches @var{pattern} (a
2078 regular expression).
2079 @end deffn
2081 @deffn Command next-matching-history-element pattern n
2082 This command replaces the minibuffer contents with the value of the
2083 @var{n}th next (newer) history element that matches @var{pattern} (a
2084 regular expression).
2085 @end deffn
2087 @node Minibuffer Windows
2088 @section Minibuffer Windows
2089 @cindex minibuffer windows
2091   These functions access and select minibuffer windows
2092 and test whether they are active.
2094 @defun active-minibuffer-window
2095 This function returns the currently active minibuffer window, or
2096 @code{nil} if none is currently active.
2097 @end defun
2099 @defun minibuffer-window &optional frame
2100 @anchor{Definition of minibuffer-window}
2101 This function returns the minibuffer window used for frame @var{frame}.
2102 If @var{frame} is @code{nil}, that stands for the current frame.  Note
2103 that the minibuffer window used by a frame need not be part of that
2104 frame---a frame that has no minibuffer of its own necessarily uses some
2105 other frame's minibuffer window.
2106 @end defun
2108 @defun set-minibuffer-window window
2109 This function specifies @var{window} as the minibuffer window to use.
2110 This affects where the minibuffer is displayed if you put text in it
2111 without invoking the usual minibuffer commands.  It has no effect on
2112 the usual minibuffer input functions because they all start by
2113 choosing the minibuffer window according to the current frame.
2114 @end defun
2116 @c Emacs 19 feature
2117 @defun window-minibuffer-p &optional window
2118 This function returns non-@code{nil} if @var{window} is a minibuffer
2119 window.
2120 @var{window} defaults to the selected window.
2121 @end defun
2123 It is not correct to determine whether a given window is a minibuffer by
2124 comparing it with the result of @code{(minibuffer-window)}, because
2125 there can be more than one minibuffer window if there is more than one
2126 frame.
2128 @defun minibuffer-window-active-p window
2129 This function returns non-@code{nil} if @var{window}, assumed to be
2130 a minibuffer window, is currently active.
2131 @end defun
2133 @node Minibuffer Contents
2134 @section Minibuffer Contents
2136   These functions access the minibuffer prompt and contents.
2138 @defun minibuffer-prompt
2139 This function returns the prompt string of the currently active
2140 minibuffer.  If no minibuffer is active, it returns @code{nil}.
2141 @end defun
2143 @defun minibuffer-prompt-end
2144 This function returns the current
2145 position of the end of the minibuffer prompt, if a minibuffer is
2146 current.  Otherwise, it returns the minimum valid buffer position.
2147 @end defun
2149 @defun minibuffer-prompt-width
2150 This function returns the current display-width of the minibuffer
2151 prompt, if a minibuffer is current.  Otherwise, it returns zero.
2152 @end defun
2154 @defun minibuffer-contents
2155 This function returns the editable
2156 contents of the minibuffer (that is, everything except the prompt) as
2157 a string, if a minibuffer is current.  Otherwise, it returns the
2158 entire contents of the current buffer.
2159 @end defun
2161 @defun minibuffer-contents-no-properties
2162 This is like @code{minibuffer-contents}, except that it does not copy text
2163 properties, just the characters themselves.  @xref{Text Properties}.
2164 @end defun
2166 @defun minibuffer-completion-contents
2167 This is like @code{minibuffer-contents}, except that it returns only
2168 the contents before point.  That is the part that completion commands
2169 operate on.  @xref{Minibuffer Completion}.
2170 @end defun
2172 @defun delete-minibuffer-contents
2173 This function erases the editable contents of the minibuffer (that is,
2174 everything except the prompt), if a minibuffer is current.  Otherwise,
2175 it erases the entire current buffer.
2176 @end defun
2178 @node Recursive Mini
2179 @section Recursive Minibuffers
2180 @cindex recursive minibuffers
2182   These functions and variables deal with recursive minibuffers
2183 (@pxref{Recursive Editing}):
2185 @defun minibuffer-depth
2186 This function returns the current depth of activations of the
2187 minibuffer, a nonnegative integer.  If no minibuffers are active, it
2188 returns zero.
2189 @end defun
2191 @defopt enable-recursive-minibuffers
2192 If this variable is non-@code{nil}, you can invoke commands (such as
2193 @code{find-file}) that use minibuffers even while the minibuffer window
2194 is active.  Such invocation produces a recursive editing level for a new
2195 minibuffer.  The outer-level minibuffer is invisible while you are
2196 editing the inner one.
2198 If this variable is @code{nil}, you cannot invoke minibuffer
2199 commands when the minibuffer window is active, not even if you switch to
2200 another window to do it.
2201 @end defopt
2203 @c Emacs 19 feature
2204 If a command name has a property @code{enable-recursive-minibuffers}
2205 that is non-@code{nil}, then the command can use the minibuffer to read
2206 arguments even if it is invoked from the minibuffer.  A command can
2207 also achieve this by binding @code{enable-recursive-minibuffers}
2208 to @code{t} in the interactive declaration (@pxref{Using Interactive}).
2209 The minibuffer command @code{next-matching-history-element} (normally
2210 @kbd{M-s} in the minibuffer) does the latter.
2212 @node Minibuffer Misc
2213 @section Minibuffer Miscellany
2215 @defun minibufferp &optional buffer-or-name
2216 This function returns non-@code{nil} if @var{buffer-or-name} is a
2217 minibuffer.  If @var{buffer-or-name} is omitted, it tests the current
2218 buffer.
2219 @end defun
2221 @defvar minibuffer-setup-hook
2222 This is a normal hook that is run whenever the minibuffer is entered.
2223 @xref{Hooks}.
2224 @end defvar
2226 @defvar minibuffer-exit-hook
2227 This is a normal hook that is run whenever the minibuffer is exited.
2228 @xref{Hooks}.
2229 @end defvar
2231 @defvar minibuffer-help-form
2232 @anchor{Definition of minibuffer-help-form}
2233 The current value of this variable is used to rebind @code{help-form}
2234 locally inside the minibuffer (@pxref{Help Functions}).
2235 @end defvar
2237 @defvar minibuffer-scroll-window
2238 @anchor{Definition of minibuffer-scroll-window}
2239 If the value of this variable is non-@code{nil}, it should be a window
2240 object.  When the function @code{scroll-other-window} is called in the
2241 minibuffer, it scrolls this window.
2242 @end defvar
2244 @defun minibuffer-selected-window
2245 This function returns the window which was selected when the
2246 minibuffer was entered.  If selected window is not a minibuffer
2247 window, it returns @code{nil}.
2248 @end defun
2250 @defopt max-mini-window-height
2251 This variable specifies the maximum height for resizing minibuffer
2252 windows.  If a float, it specifies a fraction of the height of the
2253 frame.  If an integer, it specifies a number of lines.
2254 @end defopt
2256 @defun minibuffer-message string &rest args
2257 This function displays @var{string} temporarily at the end of the
2258 minibuffer text, for two seconds, or until the next input event
2259 arrives, whichever comes first.  If @var{args} is non-@code{nil}, the
2260 actual message is obtained by passing @var{string} and @var{args}
2261 through @code{format}.  @xref{Formatting Strings}.
2262 @end defun