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 @node Minibuffers, Command Loop, Read and Print, Top
8 @cindex arguments, reading
9 @cindex complex arguments
12 A @dfn{minibuffer} is a special buffer that Emacs commands use to
13 read arguments more complicated than the single numeric prefix
14 argument. These arguments include file names, buffer names, and
15 command names (as in @kbd{M-x}). The minibuffer is displayed on the
16 bottom line of the frame, in the same place as the echo area
17 (@pxref{The Echo Area}), but only while it is in use for reading an
21 * Intro to Minibuffers:: Basic information about minibuffers.
22 * Text from Minibuffer:: How to read a straight text string.
23 * Object from Minibuffer:: How to read a Lisp object or expression.
24 * Minibuffer History:: Recording previous minibuffer inputs
25 so the user can reuse them.
26 * Initial Input:: Specifying initial contents for the minibuffer.
27 * Completion:: How to invoke and customize completion.
28 * Yes-or-No Queries:: Asking a question with a simple answer.
29 * Multiple Queries:: Asking a series of similar questions.
30 * Reading a Password:: Reading a password from the terminal.
31 * Minibuffer Commands:: Commands used as key bindings in minibuffers.
32 * Minibuffer Contents:: How such commands access the minibuffer text.
33 * Minibuffer Windows:: Operating on the special minibuffer windows.
34 * Recursive Mini:: Whether recursive entry to minibuffer is allowed.
35 * Minibuffer Misc:: Various customization hooks and variables.
38 @node Intro to Minibuffers
39 @section Introduction to Minibuffers
41 In most ways, a minibuffer is a normal Emacs buffer. Most operations
42 @emph{within} a buffer, such as editing commands, work normally in a
43 minibuffer. However, many operations for managing buffers do not apply
44 to minibuffers. The name of a minibuffer always has the form @w{@samp{
45 *Minibuf-@var{number}*}}, and it cannot be changed. Minibuffers are
46 displayed only in special windows used only for minibuffers; these
47 windows always appear at the bottom of a frame. (Sometimes frames have
48 no minibuffer window, and sometimes a special kind of frame contains
49 nothing but a minibuffer window; see @ref{Minibuffers and Frames}.)
51 The text in the minibuffer always starts with the @dfn{prompt string},
52 the text that was specified by the program that is using the minibuffer
53 to tell the user what sort of input to type. This text is marked
54 read-only so you won't accidentally delete or change it. It is also
55 marked as a field (@pxref{Fields}), so that certain motion functions,
56 including @code{beginning-of-line}, @code{forward-word},
57 @code{forward-sentence}, and @code{forward-paragraph}, stop at the
58 boundary between the prompt and the actual text.
60 The minibuffer's window is normally a single line; it grows
61 automatically if the contents require more space. You can explicitly
62 resize it temporarily with the window sizing commands; it reverts to
63 its normal size when the minibuffer is exited. You can resize it
64 permanently by using the window sizing commands in the frame's other
65 window, when the minibuffer is not active. If the frame contains just
66 a minibuffer, you can change the minibuffer's size by changing the
69 Use of the minibuffer reads input events, and that alters the values
70 of variables such as @code{this-command} and @code{last-command}
71 (@pxref{Command Loop Info}). Your program should bind them around the
72 code that uses the minibuffer, if you do not want that to change them.
74 Under some circumstances, a command can use a minibuffer even if
75 there is an active minibuffer; such minibuffers are called a
76 @dfn{recursive minibuffer}. The first minibuffer is named
77 @w{@samp{ *Minibuf-0*}}. Recursive minibuffers are named by
78 incrementing the number at the end of the name. (The names begin with
79 a space so that they won't show up in normal buffer lists.) Of
80 several recursive minibuffers, the innermost (or most recently
81 entered) is the active minibuffer. We usually call this ``the''
82 minibuffer. You can permit or forbid recursive minibuffers by setting
83 the variable @code{enable-recursive-minibuffers}, or by putting
84 properties of that name on command symbols (@xref{Recursive Mini}.)
86 Like other buffers, a minibuffer uses a local keymap
87 (@pxref{Keymaps}) to specify special key bindings. The function that
88 invokes the minibuffer also sets up its local map according to the job
89 to be done. @xref{Text from Minibuffer}, for the non-completion
90 minibuffer local maps. @xref{Completion Commands}, for the minibuffer
91 local maps for completion.
93 When Emacs is running in batch mode, any request to read from the
94 minibuffer actually reads a line from the standard input descriptor that
95 was supplied when Emacs was started.
97 @node Text from Minibuffer
98 @section Reading Text Strings with the Minibuffer
100 The most basic primitive for minibuffer input is
101 @code{read-from-minibuffer}, which can be used to read either a string
102 or a Lisp object in textual form. The function @code{read-regexp} is
103 used for reading regular expressions (@pxref{Regular Expressions}),
104 which are a special kind of string. There are also specialized
105 functions for reading commands, variables, file names, etc.@:
106 (@pxref{Completion}).
108 In most cases, you should not call minibuffer input functions in the
109 middle of a Lisp function. Instead, do all minibuffer input as part of
110 reading the arguments for a command, in the @code{interactive}
111 specification. @xref{Defining Commands}.
113 @defun read-from-minibuffer prompt-string &optional initial-contents keymap read hist default inherit-input-method
114 This function is the most general way to get input from the
115 minibuffer. By default, it accepts arbitrary text and returns it as a
116 string; however, if @var{read} is non-@code{nil}, then it uses
117 @code{read} to convert the text into a Lisp object (@pxref{Input
120 The first thing this function does is to activate a minibuffer and
121 display it with @var{prompt-string} as the prompt. This value must be a
122 string. Then the user can edit text in the minibuffer.
124 When the user types a command to exit the minibuffer,
125 @code{read-from-minibuffer} constructs the return value from the text in
126 the minibuffer. Normally it returns a string containing that text.
127 However, if @var{read} is non-@code{nil}, @code{read-from-minibuffer}
128 reads the text and returns the resulting Lisp object, unevaluated.
129 (@xref{Input Functions}, for information about reading.)
131 The argument @var{default} specifies default values to make available
132 through the history commands. It should be a string, a list of
133 strings, or @code{nil}. The string or strings become the minibuffer's
134 ``future history,'' available to the user with @kbd{M-n}.
136 If @var{read} is non-@code{nil}, then @var{default} is also used
137 as the input to @code{read}, if the user enters empty input.
138 If @var{default} is a list of strings, the first string is used as the input.
139 If @var{default} is @code{nil}, empty input results in an @code{end-of-file} error.
140 However, in the usual case (where @var{read} is @code{nil}),
141 @code{read-from-minibuffer} ignores @var{default} when the user enters
142 empty input and returns an empty string, @code{""}. In this respect,
143 it differs from all the other minibuffer input functions in this chapter.
145 If @var{keymap} is non-@code{nil}, that keymap is the local keymap to
146 use in the minibuffer. If @var{keymap} is omitted or @code{nil}, the
147 value of @code{minibuffer-local-map} is used as the keymap. Specifying
148 a keymap is the most important way to customize the minibuffer for
149 various applications such as completion.
151 The argument @var{hist} specifies which history list variable to use
152 for saving the input and for history commands used in the minibuffer.
153 It defaults to @code{minibuffer-history}. @xref{Minibuffer History}.
155 If the variable @code{minibuffer-allow-text-properties} is
156 non-@code{nil}, then the string which is returned includes whatever text
157 properties were present in the minibuffer. Otherwise all the text
158 properties are stripped when the value is returned.
160 If the argument @var{inherit-input-method} is non-@code{nil}, then the
161 minibuffer inherits the current input method (@pxref{Input Methods}) and
162 the setting of @code{enable-multibyte-characters} (@pxref{Text
163 Representations}) from whichever buffer was current before entering the
166 Use of @var{initial-contents} is mostly deprecated; we recommend using
167 a non-@code{nil} value only in conjunction with specifying a cons cell
168 for @var{hist}. @xref{Initial Input}.
171 @defun read-string prompt &optional initial history default inherit-input-method
172 This function reads a string from the minibuffer and returns it. The
173 arguments @var{prompt}, @var{initial}, @var{history} and
174 @var{inherit-input-method} are used as in @code{read-from-minibuffer}.
175 The keymap used is @code{minibuffer-local-map}.
177 The optional argument @var{default} is used as in
178 @code{read-from-minibuffer}, except that, if non-@code{nil}, it also
179 specifies a default value to return if the user enters null input. As
180 in @code{read-from-minibuffer} it should be a string, a list of
181 strings, or @code{nil} which is equivalent to an empty string. When
182 @var{default} is a string, that string is the default value. When it
183 is a list of strings, the first string is the default value. (All
184 these strings are available to the user in the ``future minibuffer
187 This function works by calling the
188 @code{read-from-minibuffer} function:
192 (read-string @var{prompt} @var{initial} @var{history} @var{default} @var{inherit})
195 (read-from-minibuffer @var{prompt} @var{initial} nil nil
196 @var{history} @var{default} @var{inherit})))
197 (if (and (equal value "") @var{default})
198 (if (consp @var{default}) (car @var{default}) @var{default})
204 @defun read-regexp prompt &optional default-value
205 This function reads a regular expression as a string from the
206 minibuffer and returns it. The argument @var{prompt} is used as in
207 @code{read-from-minibuffer}. The keymap used is
208 @code{minibuffer-local-map}, and @code{regexp-history} is used as the
209 history list (@pxref{Minibuffer History, regexp-history}).
211 The optional argument @var{default-value} specifies a default value to
212 return if the user enters null input; it should be a string, or
213 @code{nil} which is equivalent to an empty string.
215 In addition, @code{read-regexp} collects a few useful candidates for
216 input and passes them to @code{read-from-minibuffer}, to make them
217 available to the user as the ``future minibuffer history list''
218 (@pxref{Minibuffer History, future list,, emacs, The GNU Emacs
219 Manual}). These candidates are:
223 The word or symbol at point.
225 The last regexp used in an incremental search.
227 The last string used in an incremental search.
229 The last string or pattern used in query-replace commands.
232 This function works by calling the @code{read-from-minibuffer}
233 function, after computing the list of defaults as described above.
236 @defvar minibuffer-allow-text-properties
237 If this variable is @code{nil}, then @code{read-from-minibuffer} strips
238 all text properties from the minibuffer input before returning it.
239 This variable also affects @code{read-string}. However,
240 @code{read-no-blanks-input} (see below), as well as
241 @code{read-minibuffer} and related functions (@pxref{Object from
242 Minibuffer,, Reading Lisp Objects With the Minibuffer}), and all
243 functions that do minibuffer input with completion, discard text
244 properties unconditionally, regardless of the value of this variable.
247 @defvar minibuffer-local-map
249 @anchor{Definition of minibuffer-local-map}
250 @c avoid page break at anchor; work around Texinfo deficiency
251 is the default local keymap for reading from the minibuffer. By
252 default, it makes the following bindings:
256 @code{exit-minibuffer}
259 @code{exit-minibuffer}
262 @code{abort-recursive-edit}
266 @code{next-history-element}
270 @code{previous-history-element}
273 @code{next-matching-history-element}
276 @code{previous-matching-history-element}
280 @c In version 18, initial is required
282 @defun read-no-blanks-input prompt &optional initial inherit-input-method
283 This function reads a string from the minibuffer, but does not allow
284 whitespace characters as part of the input: instead, those characters
285 terminate the input. The arguments @var{prompt}, @var{initial}, and
286 @var{inherit-input-method} are used as in @code{read-from-minibuffer}.
288 This is a simplified interface to the @code{read-from-minibuffer}
289 function, and passes the value of the @code{minibuffer-local-ns-map}
290 keymap as the @var{keymap} argument for that function. Since the keymap
291 @code{minibuffer-local-ns-map} does not rebind @kbd{C-q}, it @emph{is}
292 possible to put a space into the string, by quoting it.
294 This function discards text properties, regardless of the value of
295 @code{minibuffer-allow-text-properties}.
299 (read-no-blanks-input @var{prompt} @var{initial})
301 (let (minibuffer-allow-text-properties)
302 (read-from-minibuffer @var{prompt} @var{initial} minibuffer-local-ns-map))
307 @defvar minibuffer-local-ns-map
308 This built-in variable is the keymap used as the minibuffer local keymap
309 in the function @code{read-no-blanks-input}. By default, it makes the
310 following bindings, in addition to those of @code{minibuffer-local-map}:
314 @cindex @key{SPC} in minibuffer
315 @code{exit-minibuffer}
318 @cindex @key{TAB} in minibuffer
319 @code{exit-minibuffer}
322 @cindex @kbd{?} in minibuffer
323 @code{self-insert-and-exit}
327 @node Object from Minibuffer
328 @section Reading Lisp Objects with the Minibuffer
330 This section describes functions for reading Lisp objects with the
333 @defun read-minibuffer prompt &optional initial
334 This function reads a Lisp object using the minibuffer, and returns it
335 without evaluating it. The arguments @var{prompt} and @var{initial} are
336 used as in @code{read-from-minibuffer}.
338 This is a simplified interface to the
339 @code{read-from-minibuffer} function:
343 (read-minibuffer @var{prompt} @var{initial})
345 (let (minibuffer-allow-text-properties)
346 (read-from-minibuffer @var{prompt} @var{initial} nil t))
350 Here is an example in which we supply the string @code{"(testing)"} as
356 "Enter an expression: " (format "%s" '(testing)))
358 ;; @r{Here is how the minibuffer is displayed:}
362 ---------- Buffer: Minibuffer ----------
363 Enter an expression: (testing)@point{}
364 ---------- Buffer: Minibuffer ----------
369 The user can type @key{RET} immediately to use the initial input as a
370 default, or can edit the input.
373 @defun eval-minibuffer prompt &optional initial
374 This function reads a Lisp expression using the minibuffer, evaluates
375 it, then returns the result. The arguments @var{prompt} and
376 @var{initial} are used as in @code{read-from-minibuffer}.
378 This function simply evaluates the result of a call to
379 @code{read-minibuffer}:
383 (eval-minibuffer @var{prompt} @var{initial})
385 (eval (read-minibuffer @var{prompt} @var{initial}))
390 @defun edit-and-eval-command prompt form
391 This function reads a Lisp expression in the minibuffer, and then
392 evaluates it. The difference between this command and
393 @code{eval-minibuffer} is that here the initial @var{form} is not
394 optional and it is treated as a Lisp object to be converted to printed
395 representation rather than as a string of text. It is printed with
396 @code{prin1}, so if it is a string, double-quote characters (@samp{"})
397 appear in the initial text. @xref{Output Functions}.
399 The first thing @code{edit-and-eval-command} does is to activate the
400 minibuffer with @var{prompt} as the prompt. Then it inserts the printed
401 representation of @var{form} in the minibuffer, and lets the user edit it.
402 When the user exits the minibuffer, the edited text is read with
403 @code{read} and then evaluated. The resulting value becomes the value
404 of @code{edit-and-eval-command}.
406 In the following example, we offer the user an expression with initial
407 text which is a valid form already:
411 (edit-and-eval-command "Please edit: " '(forward-word 1))
413 ;; @r{After evaluation of the preceding expression,}
414 ;; @r{the following appears in the minibuffer:}
418 ---------- Buffer: Minibuffer ----------
419 Please edit: (forward-word 1)@point{}
420 ---------- Buffer: Minibuffer ----------
425 Typing @key{RET} right away would exit the minibuffer and evaluate the
426 expression, thus moving point forward one word.
427 @code{edit-and-eval-command} returns @code{nil} in this example.
430 @node Minibuffer History
431 @section Minibuffer History
432 @cindex minibuffer history
435 A @dfn{minibuffer history list} records previous minibuffer inputs
436 so the user can reuse them conveniently. It is a variable whose value
437 is a list of strings (previous inputs), most recent first.
439 There are many separate minibuffer history lists, used for different
440 kinds of inputs. It's the Lisp programmer's job to specify the right
441 history list for each use of the minibuffer.
443 You specify a minibuffer history list with the optional @var{hist}
444 argument to @code{read-from-minibuffer} or @code{completing-read}.
445 Here are the possible values for it:
449 Use @var{variable} (a symbol) as the history list.
451 @item (@var{variable} . @var{startpos})
452 Use @var{variable} (a symbol) as the history list, and assume that the
453 initial history position is @var{startpos} (a nonnegative integer).
455 Specifying 0 for @var{startpos} is equivalent to just specifying the
456 symbol @var{variable}. @code{previous-history-element} will display
457 the most recent element of the history list in the minibuffer. If you
458 specify a positive @var{startpos}, the minibuffer history functions
459 behave as if @code{(elt @var{variable} (1- @var{STARTPOS}))} were the
460 history element currently shown in the minibuffer.
462 For consistency, you should also specify that element of the history
463 as the initial minibuffer contents, using the @var{initial} argument
464 to the minibuffer input function (@pxref{Initial Input}).
467 If you don't specify @var{hist}, then the default history list
468 @code{minibuffer-history} is used. For other standard history lists,
469 see below. You can also create your own history list variable; just
470 initialize it to @code{nil} before the first use.
472 Both @code{read-from-minibuffer} and @code{completing-read} add new
473 elements to the history list automatically, and provide commands to
474 allow the user to reuse items on the list. The only thing your program
475 needs to do to use a history list is to initialize it and to pass its
476 name to the input functions when you wish. But it is safe to modify the
477 list by hand when the minibuffer input functions are not using it.
479 Emacs functions that add a new element to a history list can also
480 delete old elements if the list gets too long. The variable
481 @code{history-length} specifies the maximum length for most history
482 lists. To specify a different maximum length for a particular history
483 list, put the length in the @code{history-length} property of the
484 history list symbol. The variable @code{history-delete-duplicates}
485 specifies whether to delete duplicates in history.
487 @defun add-to-history history-var newelt &optional maxelt keep-all
488 This function adds a new element @var{newelt}, if it isn't the empty
489 string, to the history list stored in the variable @var{history-var},
490 and returns the updated history list. It limits the list length to
491 the value of @var{maxelt} (if non-@code{nil}) or @code{history-length}
492 (described below). The possible values of @var{maxelt} have the same
493 meaning as the values of @code{history-length}.
495 Normally, @code{add-to-history} removes duplicate members from the
496 history list if @code{history-delete-duplicates} is non-@code{nil}.
497 However, if @var{keep-all} is non-@code{nil}, that says not to remove
498 duplicates, and to add @var{newelt} to the list even if it is empty.
501 @defvar history-add-new-input
502 If the value of this variable is @code{nil}, standard functions that
503 read from the minibuffer don't add new elements to the history list.
504 This lets Lisp programs explicitly manage input history by using
505 @code{add-to-history}. By default, @code{history-add-new-input} is
506 set to a non-@code{nil} value.
509 @defopt history-length
510 The value of this variable specifies the maximum length for all
511 history lists that don't specify their own maximum lengths. If the
512 value is @code{t}, that means there is no maximum (don't delete old
513 elements). The value of @code{history-length} property of the history
514 list variable's symbol, if set, overrides this variable for that
515 particular history list.
518 @defopt history-delete-duplicates
519 If the value of this variable is @code{t}, that means when adding a
520 new history element, all previous identical elements are deleted.
523 Here are some of the standard minibuffer history list variables:
525 @defvar minibuffer-history
526 The default history list for minibuffer history input.
529 @defvar query-replace-history
530 A history list for arguments to @code{query-replace} (and similar
531 arguments to other commands).
534 @defvar file-name-history
535 A history list for file-name arguments.
538 @defvar buffer-name-history
539 A history list for buffer-name arguments.
542 @defvar regexp-history
543 A history list for regular expression arguments.
546 @defvar extended-command-history
547 A history list for arguments that are names of extended commands.
550 @defvar shell-command-history
551 A history list for arguments that are shell commands.
554 @defvar read-expression-history
555 A history list for arguments that are Lisp expressions to evaluate.
559 @section Initial Input
561 Several of the functions for minibuffer input have an argument called
562 @var{initial} or @var{initial-contents}. This is a mostly-deprecated
563 feature for specifying that the minibuffer should start out with
564 certain text, instead of empty as usual.
566 If @var{initial} is a string, the minibuffer starts out containing the
567 text of the string, with point at the end, when the user starts to
568 edit the text. If the user simply types @key{RET} to exit the
569 minibuffer, it will use the initial input string to determine the
572 @strong{We discourage use of a non-@code{nil} value for
573 @var{initial}}, because initial input is an intrusive interface.
574 History lists and default values provide a much more convenient method
575 to offer useful default inputs to the user.
577 There is just one situation where you should specify a string for an
578 @var{initial} argument. This is when you specify a cons cell for the
579 @var{hist} or @var{history} argument. @xref{Minibuffer History}.
581 @var{initial} can also be a cons cell of the form @code{(@var{string}
582 . @var{position})}. This means to insert @var{string} in the
583 minibuffer but put point at @var{position} within the string's text.
585 As a historical accident, @var{position} was implemented
586 inconsistently in different functions. In @code{completing-read},
587 @var{position}'s value is interpreted as origin-zero; that is, a value
588 of 0 means the beginning of the string, 1 means after the first
589 character, etc. In @code{read-minibuffer}, and the other
590 non-completion minibuffer input functions that support this argument,
591 1 means the beginning of the string 2 means after the first character,
594 Use of a cons cell as the value for @var{initial} arguments is
595 deprecated in user code.
601 @dfn{Completion} is a feature that fills in the rest of a name
602 starting from an abbreviation for it. Completion works by comparing the
603 user's input against a list of valid names and determining how much of
604 the name is determined uniquely by what the user has typed. For
605 example, when you type @kbd{C-x b} (@code{switch-to-buffer}) and then
606 type the first few letters of the name of the buffer to which you wish
607 to switch, and then type @key{TAB} (@code{minibuffer-complete}), Emacs
608 extends the name as far as it can.
610 Standard Emacs commands offer completion for names of symbols, files,
611 buffers, and processes; with the functions in this section, you can
612 implement completion for other kinds of names.
614 The @code{try-completion} function is the basic primitive for
615 completion: it returns the longest determined completion of a given
616 initial string, with a given set of strings to match against.
618 The function @code{completing-read} provides a higher-level interface
619 for completion. A call to @code{completing-read} specifies how to
620 determine the list of valid names. The function then activates the
621 minibuffer with a local keymap that binds a few keys to commands useful
622 for completion. Other functions provide convenient simple interfaces
623 for reading certain kinds of names with completion.
626 * Basic Completion:: Low-level functions for completing strings.
627 * Minibuffer Completion:: Invoking the minibuffer with completion.
628 * Completion Commands:: Minibuffer commands that do completion.
629 * High-Level Completion:: Convenient special cases of completion
630 (reading buffer name, file name, etc.).
631 * Reading File Names:: Using completion to read file names and
633 * Completion Variables:: Variables controlling completion behavior.
634 * Programmed Completion:: Writing your own completion function.
635 * Completion in Buffers:: Completing text in ordinary buffers.
638 @node Basic Completion
639 @subsection Basic Completion Functions
641 The following completion functions have nothing in themselves to do
642 with minibuffers. We describe them here to keep them near the
643 higher-level completion features that do use the minibuffer.
645 @defun try-completion string collection &optional predicate
646 This function returns the longest common substring of all possible
647 completions of @var{string} in @var{collection}.
649 @cindex completion table
650 The @var{collection} argument is called the @dfn{completion table}.
651 Its value must be a list of strings, an alist whose keys are strings
652 or symbols, an obarray, a hash table, or a completion function.
654 Completion compares @var{string} against each of the permissible
655 completions specified by @var{collection}. If no permissible
656 completions match, @code{try-completion} returns @code{nil}. If there
657 is just one matching completion, and the match is exact, it returns
658 @code{t}. Otherwise, it returns the longest initial sequence common
659 to all possible matching completions.
661 If @var{collection} is an alist (@pxref{Association Lists}), the
662 permissible completions are the elements of the alist that are either
663 strings, or conses whose @sc{car} is a string or symbol.
664 Symbols are converted to strings using @code{symbol-name}. Other
665 elements of the alist are ignored. (Remember that in Emacs Lisp, the
666 elements of alists do not @emph{have} to be conses.) In particular, a
667 list of strings is allowed, even though we usually do not
668 think of such lists as alists.
670 @cindex obarray in completion
671 If @var{collection} is an obarray (@pxref{Creating Symbols}), the names
672 of all symbols in the obarray form the set of permissible completions. The
673 global variable @code{obarray} holds an obarray containing the names of
674 all interned Lisp symbols.
676 Note that the only valid way to make a new obarray is to create it
677 empty and then add symbols to it one by one using @code{intern}.
678 Also, you cannot intern a given symbol in more than one obarray.
680 If @var{collection} is a hash table, then the keys that are strings
681 are the possible completions. Other keys are ignored.
683 You can also use a function as @var{collection}. Then the function is
684 solely responsible for performing completion; @code{try-completion}
685 returns whatever this function returns. The function is called with
686 three arguments: @var{string}, @var{predicate} and @code{nil} (the
687 reason for the third argument is so that the same function can be used
688 in @code{all-completions} and do the appropriate thing in either
689 case). @xref{Programmed Completion}.
691 If the argument @var{predicate} is non-@code{nil}, then it must be a
692 function of one argument, unless @var{collection} is a hash table, in
693 which case it should be a function of two arguments. It is used to
694 test each possible match, and the match is accepted only if
695 @var{predicate} returns non-@code{nil}. The argument given to
696 @var{predicate} is either a string or a cons cell (the @sc{car} of
697 which is a string) from the alist, or a symbol (@emph{not} a symbol
698 name) from the obarray. If @var{collection} is a hash table,
699 @var{predicate} is called with two arguments, the string key and the
702 In addition, to be acceptable, a completion must also match all the
703 regular expressions in @code{completion-regexp-list}. (Unless
704 @var{collection} is a function, in which case that function has to
705 handle @code{completion-regexp-list} itself.)
707 In the first of the following examples, the string @samp{foo} is
708 matched by three of the alist @sc{car}s. All of the matches begin with
709 the characters @samp{fooba}, so that is the result. In the second
710 example, there is only one possible match, and it is exact, so the value
717 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)))
722 (try-completion "foo" '(("barfoo" 2) ("foo" 3)))
727 In the following example, numerous symbols begin with the characters
728 @samp{forw}, and all of them begin with the word @samp{forward}. In
729 most of the symbols, this is followed with a @samp{-}, but not in all,
730 so no more than @samp{forward} can be completed.
734 (try-completion "forw" obarray)
739 Finally, in the following example, only two of the three possible
740 matches pass the predicate @code{test} (the string @samp{foobaz} is
741 too short). Both of those begin with the string @samp{foobar}.
746 (> (length (car s)) 6))
752 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
759 @defun all-completions string collection &optional predicate nospace
760 This function returns a list of all possible completions of
761 @var{string}. The arguments to this function (aside from
762 @var{nospace}) are the same as those of @code{try-completion}. Also,
763 this function uses @code{completion-regexp-list} in the same way that
764 @code{try-completion} does.
766 The optional argument @var{nospace} is obsolete. If it is
767 non-@code{nil}, completions that start with a space are ignored unless
768 @var{string} starts with a space.
770 If @var{collection} is a function, it is called with three arguments:
771 @var{string}, @var{predicate} and @code{t}; then @code{all-completions}
772 returns whatever the function returns. @xref{Programmed Completion}.
774 Here is an example, using the function @code{test} shown in the
775 example for @code{try-completion}:
780 (> (length (car s)) 6))
787 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
789 @result{} ("foobar1" "foobar2")
794 @defun test-completion string collection &optional predicate
795 @anchor{Definition of test-completion}
796 This function returns non-@code{nil} if @var{string} is a valid
797 completion alternative specified by @var{collection} and
798 @var{predicate}. The arguments are the same as in
799 @code{try-completion}. For instance, if @var{collection} is a list of
800 strings, this is true if @var{string} appears in the list and
801 @var{predicate} is satisfied.
803 This function uses @code{completion-regexp-list} in the same
804 way that @code{try-completion} does.
806 If @var{predicate} is non-@code{nil} and if @var{collection} contains
807 several strings that are equal to each other, as determined by
808 @code{compare-strings} according to @code{completion-ignore-case},
809 then @var{predicate} should accept either all or none of them.
810 Otherwise, the return value of @code{test-completion} is essentially
813 If @var{collection} is a function, it is called with three arguments,
814 the values @var{string}, @var{predicate} and @code{lambda}; whatever
815 it returns, @code{test-completion} returns in turn.
818 @defun completion-boundaries string collection predicate suffix
819 This function returns the boundaries of the field on which @var{collection}
820 will operate, assuming that @var{string} holds the text before point
821 and @var{suffix} holds the text after point.
823 Normally completion operates on the whole string, so for all normal
824 collections, this will always return @code{(0 . (length
825 @var{suffix}))}. But more complex completion such as completion on
826 files is done one field at a time. For example, completion of
827 @code{"/usr/sh"} will include @code{"/usr/share/"} but not
828 @code{"/usr/share/doc"} even if @code{"/usr/share/doc"} exists.
829 Also @code{all-completions} on @code{"/usr/sh"} will not include
830 @code{"/usr/share/"} but only @code{"share/"}. So if @var{string} is
831 @code{"/usr/sh"} and @var{suffix} is @code{"e/doc"},
832 @code{completion-boundaries} will return @code{(5 . 1)} which tells us
833 that the @var{collection} will only return completion information that
834 pertains to the area after @code{"/usr/"} and before @code{"/doc"}.
837 If you store a completion alist in a variable, you should mark the
838 variable as ``risky'' with a non-@code{nil}
839 @code{risky-local-variable} property. @xref{File Local Variables}.
841 @defvar completion-ignore-case
842 If the value of this variable is non-@code{nil}, case is not
843 considered significant in completion. Within @code{read-file-name},
844 this variable is overridden by
845 @code{read-file-name-completion-ignore-case} (@pxref{Reading File
846 Names}); within @code{read-buffer}, it is overridden by
847 @code{read-buffer-completion-ignore-case} (@pxref{High-Level
851 @defvar completion-regexp-list
852 This is a list of regular expressions. The completion functions only
853 consider a completion acceptable if it matches all regular expressions
854 in this list, with @code{case-fold-search} (@pxref{Searching and Case})
855 bound to the value of @code{completion-ignore-case}.
858 @defmac lazy-completion-table var fun
859 This macro provides a way to initialize the variable @var{var} as a
860 collection for completion in a lazy way, not computing its actual
861 contents until they are first needed. You use this macro to produce a
862 value that you store in @var{var}. The actual computation of the
863 proper value is done the first time you do completion using @var{var}.
864 It is done by calling @var{fun} with no arguments. The
865 value @var{fun} returns becomes the permanent value of @var{var}.
867 Here is a usage example:
870 (defvar foo (lazy-completion-table foo make-my-alist))
874 @node Minibuffer Completion
875 @subsection Completion and the Minibuffer
876 @cindex minibuffer completion
877 @cindex reading from minibuffer with completion
879 This section describes the basic interface for reading from the
880 minibuffer with completion.
882 @defun completing-read prompt collection &optional predicate require-match initial hist default inherit-input-method
883 This function reads a string in the minibuffer, assisting the user by
884 providing completion. It activates the minibuffer with prompt
885 @var{prompt}, which must be a string.
887 The actual completion is done by passing the completion table
888 @var{collection} and the completion predicate @var{predicate} to the
889 function @code{try-completion} (@pxref{Basic Completion}). This
890 happens in certain commands bound in the local keymaps used for
891 completion. Some of these commands also call @code{test-completion}.
892 Thus, if @var{predicate} is non-@code{nil}, it should be compatible
893 with @var{collection} and @code{completion-ignore-case}.
894 @xref{Definition of test-completion}.
896 The value of the optional argument @var{require-match} determines how
897 the user may exit the minibuffer:
901 If @code{nil}, the usual minibuffer exit commands work regardless of
902 the input in the minibuffer.
905 If @code{t}, the usual minibuffer exit commands won't exit unless the
906 input completes to an element of @var{collection}.
909 If @code{confirm}, the user can exit with any input, but is asked for
910 confirmation if the input is not an element of @var{collection}.
913 If @code{confirm-after-completion}, the user can exit with any input,
914 but is asked for confirmation if the preceding command was a
915 completion command (i.e., one of the commands in
916 @code{minibuffer-confirm-exit-commands}) and the resulting input is
917 not an element of @var{collection}. @xref{Completion Commands}.
920 Any other value of @var{require-match} behaves like @code{t}, except
921 that the exit commands won't exit if it performs completion.
924 However, empty input is always permitted, regardless of the value of
925 @var{require-match}; in that case, @code{completing-read} returns the
926 first element of @var{default}, if it is a list; @code{""}, if
927 @var{default} is @code{nil}; or @var{default}. The string or strings
928 in @var{default} are also available to the user through the history
931 The function @code{completing-read} uses
932 @code{minibuffer-local-completion-map} as the keymap if
933 @var{require-match} is @code{nil}, and uses
934 @code{minibuffer-local-must-match-map} if @var{require-match} is
935 non-@code{nil}. @xref{Completion Commands}.
937 The argument @var{hist} specifies which history list variable to use for
938 saving the input and for minibuffer history commands. It defaults to
939 @code{minibuffer-history}. @xref{Minibuffer History}.
941 The argument @var{initial} is mostly deprecated; we recommend using a
942 non-@code{nil} value only in conjunction with specifying a cons cell
943 for @var{hist}. @xref{Initial Input}. For default input, use
944 @var{default} instead.
946 If the argument @var{inherit-input-method} is non-@code{nil}, then the
947 minibuffer inherits the current input method (@pxref{Input
948 Methods}) and the setting of @code{enable-multibyte-characters}
949 (@pxref{Text Representations}) from whichever buffer was current before
950 entering the minibuffer.
952 If the built-in variable @code{completion-ignore-case} is
953 non-@code{nil}, completion ignores case when comparing the input
954 against the possible matches. @xref{Basic Completion}. In this mode
955 of operation, @var{predicate} must also ignore case, or you will get
958 Here's an example of using @code{completing-read}:
964 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
969 ;; @r{After evaluation of the preceding expression,}
970 ;; @r{the following appears in the minibuffer:}
972 ---------- Buffer: Minibuffer ----------
973 Complete a foo: fo@point{}
974 ---------- Buffer: Minibuffer ----------
979 If the user then types @kbd{@key{DEL} @key{DEL} b @key{RET}},
980 @code{completing-read} returns @code{barfoo}.
982 The @code{completing-read} function binds variables to pass
983 information to the commands that actually do completion.
984 They are described in the following section.
987 @defvar completing-read-function
988 The value of this variable must be a function, which is called by
989 @code{completing-read} to actually do its work. It should accept the
990 same arguments as @code{completing-read}. This can be bound to a
991 different function to completely override the normal behavior of
992 @code{completing-read}.
995 @node Completion Commands
996 @subsection Minibuffer Commands that Do Completion
998 This section describes the keymaps, commands and user options used
999 in the minibuffer to do completion.
1001 @defvar minibuffer-completion-table
1002 The value of this variable is the completion table used for completion
1003 in the minibuffer. This is the global variable that contains what
1004 @code{completing-read} passes to @code{try-completion}. It is used by
1005 minibuffer completion commands such as
1006 @code{minibuffer-complete-word}.
1009 @defvar minibuffer-completion-predicate
1010 This variable's value is the predicate that @code{completing-read}
1011 passes to @code{try-completion}. The variable is also used by the other
1012 minibuffer completion functions.
1015 @defvar minibuffer-completion-confirm
1016 This variable determines whether Emacs asks for confirmation before
1017 exiting the minibuffer; @code{completing-read} binds this variable,
1018 and the function @code{minibuffer-complete-and-exit} checks the value
1019 before exiting. If the value is @code{nil}, confirmation is not
1020 required. If the value is @code{confirm}, the user may exit with an
1021 input that is not a valid completion alternative, but Emacs asks for
1022 confirmation. If the value is @code{confirm-after-completion}, the
1023 user may exit with an input that is not a valid completion
1024 alternative, but Emacs asks for confirmation if the user submitted the
1025 input right after any of the completion commands in
1026 @code{minibuffer-confirm-exit-commands}.
1029 @defvar minibuffer-confirm-exit-commands
1030 This variable holds a list of commands that cause Emacs to ask for
1031 confirmation before exiting the minibuffer, if the @var{require-match}
1032 argument to @code{completing-read} is @code{confirm-after-completion}.
1033 The confirmation is requested if the user attempts to exit the
1034 minibuffer immediately after calling any command in this list.
1037 @deffn Command minibuffer-complete-word
1038 This function completes the minibuffer contents by at most a single
1039 word. Even if the minibuffer contents have only one completion,
1040 @code{minibuffer-complete-word} does not add any characters beyond the
1041 first character that is not a word constituent. @xref{Syntax Tables}.
1044 @deffn Command minibuffer-complete
1045 This function completes the minibuffer contents as far as possible.
1048 @deffn Command minibuffer-complete-and-exit
1049 This function completes the minibuffer contents, and exits if
1050 confirmation is not required, i.e., if
1051 @code{minibuffer-completion-confirm} is @code{nil}. If confirmation
1052 @emph{is} required, it is given by repeating this command
1053 immediately---the command is programmed to work without confirmation
1054 when run twice in succession.
1057 @deffn Command minibuffer-completion-help
1058 This function creates a list of the possible completions of the
1059 current minibuffer contents. It works by calling @code{all-completions}
1060 using the value of the variable @code{minibuffer-completion-table} as
1061 the @var{collection} argument, and the value of
1062 @code{minibuffer-completion-predicate} as the @var{predicate} argument.
1063 The list of completions is displayed as text in a buffer named
1064 @file{*Completions*}.
1067 @defun display-completion-list completions &optional common-substring
1068 This function displays @var{completions} to the stream in
1069 @code{standard-output}, usually a buffer. (@xref{Read and Print}, for more
1070 information about streams.) The argument @var{completions} is normally
1071 a list of completions just returned by @code{all-completions}, but it
1072 does not have to be. Each element may be a symbol or a string, either
1073 of which is simply printed. It can also be a list of two strings,
1074 which is printed as if the strings were concatenated. The first of
1075 the two strings is the actual completion, the second string serves as
1078 The argument @var{common-substring} is the prefix that is common to
1079 all the completions. With normal Emacs completion, it is usually the
1080 same as the string that was completed. @code{display-completion-list}
1081 uses this to highlight text in the completion list for better visual
1082 feedback. This is not needed in the minibuffer; for minibuffer
1083 completion, you can pass @code{nil}.
1085 This function is called by @code{minibuffer-completion-help}. The
1086 most common way to use it is together with
1087 @code{with-output-to-temp-buffer}, like this:
1090 (with-output-to-temp-buffer "*Completions*"
1091 (display-completion-list
1092 (all-completions (buffer-string) my-alist)
1097 @defopt completion-auto-help
1098 If this variable is non-@code{nil}, the completion commands
1099 automatically display a list of possible completions whenever nothing
1100 can be completed because the next character is not uniquely determined.
1103 @defvar minibuffer-local-completion-map
1104 @code{completing-read} uses this value as the local keymap when an
1105 exact match of one of the completions is not required. By default, this
1106 keymap makes the following bindings:
1110 @code{minibuffer-completion-help}
1113 @code{minibuffer-complete-word}
1116 @code{minibuffer-complete}
1120 with other characters bound as in @code{minibuffer-local-map}
1121 (@pxref{Definition of minibuffer-local-map}).
1124 @defvar minibuffer-local-must-match-map
1125 @code{completing-read} uses this value as the local keymap when an
1126 exact match of one of the completions is required. Therefore, no keys
1127 are bound to @code{exit-minibuffer}, the command that exits the
1128 minibuffer unconditionally. By default, this keymap makes the following
1133 @code{minibuffer-completion-help}
1136 @code{minibuffer-complete-word}
1139 @code{minibuffer-complete}
1142 @code{minibuffer-complete-and-exit}
1145 @code{minibuffer-complete-and-exit}
1149 with other characters bound as in @code{minibuffer-local-map}.
1152 @defvar minibuffer-local-filename-completion-map
1153 This is like @code{minibuffer-local-completion-map}
1154 except that it does not bind @key{SPC}. This keymap is used by the
1155 function @code{read-file-name}.
1158 @defvar minibuffer-local-filename-must-match-map
1159 This is like @code{minibuffer-local-must-match-map}
1160 except that it does not bind @key{SPC}. This keymap is used by the
1161 function @code{read-file-name}.
1164 @node High-Level Completion
1165 @subsection High-Level Completion Functions
1167 This section describes the higher-level convenient functions for
1168 reading certain sorts of names with completion.
1170 In most cases, you should not call these functions in the middle of a
1171 Lisp function. When possible, do all minibuffer input as part of
1172 reading the arguments for a command, in the @code{interactive}
1173 specification. @xref{Defining Commands}.
1175 @defun read-buffer prompt &optional default require-match
1176 This function reads the name of a buffer and returns it as a string.
1177 The argument @var{default} is the default name to use, the value to
1178 return if the user exits with an empty minibuffer. If non-@code{nil},
1179 it should be a string, a list of strings, or a buffer. If it is
1180 a list, the default value is the first element of this list. It is
1181 mentioned in the prompt, but is not inserted in the minibuffer as
1184 The argument @var{prompt} should be a string ending with a colon and a
1185 space. If @var{default} is non-@code{nil}, the function inserts it in
1186 @var{prompt} before the colon to follow the convention for reading from
1187 the minibuffer with a default value (@pxref{Programming Tips}).
1189 The optional argument @var{require-match} has the same meaning as in
1190 @code{completing-read}. @xref{Minibuffer Completion}.
1192 In the following example, the user enters @samp{minibuffer.t}, and
1193 then types @key{RET}. The argument @var{require-match} is @code{t},
1194 and the only buffer name starting with the given input is
1195 @samp{minibuffer.texi}, so that name is the value.
1198 (read-buffer "Buffer name: " "foo" t)
1200 ;; @r{After evaluation of the preceding expression,}
1201 ;; @r{the following prompt appears,}
1202 ;; @r{with an empty minibuffer:}
1206 ---------- Buffer: Minibuffer ----------
1207 Buffer name (default foo): @point{}
1208 ---------- Buffer: Minibuffer ----------
1212 ;; @r{The user types @kbd{minibuffer.t @key{RET}}.}
1213 @result{} "minibuffer.texi"
1218 @defopt read-buffer-function
1219 This variable specifies how to read buffer names. The function is
1220 called with the arguments passed to @code{read-buffer}. For example,
1221 if you set this variable to @code{iswitchb-read-buffer}, all Emacs
1222 commands that call @code{read-buffer} to read a buffer name will
1223 actually use the @code{iswitchb} package to read it.
1226 @defopt read-buffer-completion-ignore-case
1227 If this variable is non-@code{nil}, @code{read-buffer} ignores case
1228 when performing completion.
1231 @defun read-command prompt &optional default
1232 This function reads the name of a command and returns it as a Lisp
1233 symbol. The argument @var{prompt} is used as in
1234 @code{read-from-minibuffer}. Recall that a command is anything for
1235 which @code{commandp} returns @code{t}, and a command name is a symbol
1236 for which @code{commandp} returns @code{t}. @xref{Interactive Call}.
1238 The argument @var{default} specifies what to return if the user enters
1239 null input. It can be a symbol, a string or a list of strings. If it
1240 is a string, @code{read-command} interns it before returning it.
1241 If it is a list, @code{read-command} returns the first element of this list.
1242 If @var{default} is @code{nil}, that means no default has been
1243 specified; then if the user enters null input, the return value is
1244 @code{(intern "")}, that is, a symbol whose name is an empty string.
1247 (read-command "Command name? ")
1250 ;; @r{After evaluation of the preceding expression,}
1251 ;; @r{the following prompt appears with an empty minibuffer:}
1255 ---------- Buffer: Minibuffer ----------
1257 ---------- Buffer: Minibuffer ----------
1262 If the user types @kbd{forward-c @key{RET}}, then this function returns
1263 @code{forward-char}.
1265 The @code{read-command} function is a simplified interface to
1266 @code{completing-read}. It uses the variable @code{obarray} so as to
1267 complete in the set of extant Lisp symbols, and it uses the
1268 @code{commandp} predicate so as to accept only command names:
1270 @cindex @code{commandp} example
1273 (read-command @var{prompt})
1275 (intern (completing-read @var{prompt} obarray
1281 @defun read-variable prompt &optional default
1282 @anchor{Definition of read-variable}
1283 This function reads the name of a user variable and returns it as a
1286 The argument @var{default} specifies the default value to return if
1287 the user enters null input. It can be a symbol, a string, or a list
1288 of strings. If it is a string, @code{read-variable} interns it to
1289 make the default value. If it is a list, @code{read-variable} interns
1290 the first element. If @var{default} is @code{nil}, that means no
1291 default has been specified; then if the user enters null input, the
1292 return value is @code{(intern "")}.
1296 (read-variable "Variable name? ")
1298 ;; @r{After evaluation of the preceding expression,}
1299 ;; @r{the following prompt appears,}
1300 ;; @r{with an empty minibuffer:}
1304 ---------- Buffer: Minibuffer ----------
1305 Variable name? @point{}
1306 ---------- Buffer: Minibuffer ----------
1311 If the user then types @kbd{fill-p @key{RET}}, @code{read-variable}
1312 returns @code{fill-prefix}.
1314 In general, @code{read-variable} is similar to @code{read-command},
1315 but uses the predicate @code{custom-variable-p} instead of
1318 @cindex @code{custom-variable-p} example
1321 (read-variable @var{prompt})
1324 (completing-read @var{prompt} obarray
1325 'custom-variable-p t nil))
1330 @deffn Command read-color &optional prompt convert allow-empty display
1331 This function reads a string that is a color specification, either the
1332 color's name or an RGB hex value such as @code{#RRRGGGBBB}. It
1333 prompts with @var{prompt} (default: @code{"Color (name or #RGB triplet):"})
1334 and provides completion for color names, but not for hex RGB values.
1335 In addition to names of standard colors, completion candidates include
1336 the foreground and background colors at point.
1338 Valid RGB values are described in @ref{Color Names}.
1340 The function's return value is the string typed by the user in the
1341 minibuffer. However, when called interactively or if the optional
1342 argument @var{convert} is non-@code{nil}, it converts any input color
1343 name into the corresponding RGB value string and instead returns that.
1344 This function requires a valid color specification to be input.
1345 Empty color names are allowed when @code{allow-empty} is
1346 non-@code{nil} and the user enters null input.
1348 Interactively, or when @var{display} is non-@code{nil}, the return
1349 value is also displayed in the echo area.
1352 See also the functions @code{read-coding-system} and
1353 @code{read-non-nil-coding-system}, in @ref{User-Chosen Coding Systems},
1354 and @code{read-input-method-name}, in @ref{Input Methods}.
1356 @node Reading File Names
1357 @subsection Reading File Names
1358 @cindex read file names
1359 @cindex prompt for file name
1361 The high-level completion functions @code{read-file-name},
1362 @code{read-directory-name}, and @code{read-shell-command} are designed
1363 to read file names, directory names, and shell commands respectively.
1364 They provide special features, including automatic insertion of the
1367 @defun read-file-name prompt &optional directory default require-match initial predicate
1368 This function reads a file name, prompting with @var{prompt} and
1369 providing completion.
1371 As an exception, this function reads a file name using a graphical
1372 file dialog instead of the minibuffer, if (i) it is invoked via a
1373 mouse command, and (ii) the selected frame is on a graphical display
1374 supporting such dialogs, and (iii) the variable @code{use-dialog-box}
1375 is non-@code{nil} (@pxref{Dialog Boxes,, Dialog Boxes, emacs, The GNU
1376 Emacs Manual}), and (iv) the @var{directory} argument, described
1377 below, does not specify a remote file (@pxref{Remote Files,, Remote
1378 Files, emacs, The GNU Emacs Manual}). The exact behavior when using a
1379 graphical file dialog is platform-dependent. Here, we simply document
1380 the behavior when using the minibuffer.
1382 @code{read-file-name} does not automatically expand the returned file
1383 name. You must call @code{expand-file-name} yourself if an absolute
1384 file name is required.
1386 The optional argument @var{require-match} has the same meaning as in
1387 @code{completing-read}. @xref{Minibuffer Completion}.
1389 The argument @var{directory} specifies the directory to use for
1390 completing relative file names. It should be an absolute directory
1391 name. If @code{insert-default-directory} is non-@code{nil},
1392 @var{directory} is also inserted in the minibuffer as initial input.
1393 It defaults to the current buffer's value of @code{default-directory}.
1395 If you specify @var{initial}, that is an initial file name to insert
1396 in the buffer (after @var{directory}, if that is inserted). In this
1397 case, point goes at the beginning of @var{initial}. The default for
1398 @var{initial} is @code{nil}---don't insert any file name. To see what
1399 @var{initial} does, try the command @kbd{C-x C-v}. @strong{Please
1400 note:} we recommend using @var{default} rather than @var{initial} in
1403 If @var{default} is non-@code{nil}, then the function returns
1404 @var{default} if the user exits the minibuffer with the same non-empty
1405 contents that @code{read-file-name} inserted initially. The initial
1406 minibuffer contents are always non-empty if
1407 @code{insert-default-directory} is non-@code{nil}, as it is by
1408 default. @var{default} is not checked for validity, regardless of the
1409 value of @var{require-match}. However, if @var{require-match} is
1410 non-@code{nil}, the initial minibuffer contents should be a valid file
1411 (or directory) name. Otherwise @code{read-file-name} attempts
1412 completion if the user exits without any editing, and does not return
1413 @var{default}. @var{default} is also available through the history
1416 If @var{default} is @code{nil}, @code{read-file-name} tries to find a
1417 substitute default to use in its place, which it treats in exactly the
1418 same way as if it had been specified explicitly. If @var{default} is
1419 @code{nil}, but @var{initial} is non-@code{nil}, then the default is
1420 the absolute file name obtained from @var{directory} and
1421 @var{initial}. If both @var{default} and @var{initial} are @code{nil}
1422 and the buffer is visiting a file, @code{read-file-name} uses the
1423 absolute file name of that file as default. If the buffer is not
1424 visiting a file, then there is no default. In that case, if the user
1425 types @key{RET} without any editing, @code{read-file-name} simply
1426 returns the pre-inserted contents of the minibuffer.
1428 If the user types @key{RET} in an empty minibuffer, this function
1429 returns an empty string, regardless of the value of
1430 @var{require-match}. This is, for instance, how the user can make the
1431 current buffer visit no file using @code{M-x set-visited-file-name}.
1433 If @var{predicate} is non-@code{nil}, it specifies a function of one
1434 argument that decides which file names are acceptable completion
1435 alternatives. A file name is an acceptable value if @var{predicate}
1436 returns non-@code{nil} for it.
1438 Here is an example of using @code{read-file-name}:
1442 (read-file-name "The file is ")
1444 ;; @r{After evaluation of the preceding expression,}
1445 ;; @r{the following appears in the minibuffer:}
1449 ---------- Buffer: Minibuffer ----------
1450 The file is /gp/gnu/elisp/@point{}
1451 ---------- Buffer: Minibuffer ----------
1456 Typing @kbd{manual @key{TAB}} results in the following:
1460 ---------- Buffer: Minibuffer ----------
1461 The file is /gp/gnu/elisp/manual.texi@point{}
1462 ---------- Buffer: Minibuffer ----------
1466 @c Wordy to avoid overfull hbox in smallbook mode.
1468 If the user types @key{RET}, @code{read-file-name} returns the file name
1469 as the string @code{"/gp/gnu/elisp/manual.texi"}.
1472 @defvar read-file-name-function
1473 If non-@code{nil}, this should be a function that accepts the same
1474 arguments as @code{read-file-name}. When @code{read-file-name} is
1475 called, it calls this function with the supplied arguments instead of
1476 doing its usual work.
1479 @defopt read-file-name-completion-ignore-case
1480 If this variable is non-@code{nil}, @code{read-file-name} ignores case
1481 when performing completion.
1484 @defun read-directory-name prompt &optional directory default require-match initial
1485 This function is like @code{read-file-name} but allows only directory
1486 names as completion alternatives.
1488 If @var{default} is @code{nil} and @var{initial} is non-@code{nil},
1489 @code{read-directory-name} constructs a substitute default by
1490 combining @var{directory} (or the current buffer's default directory
1491 if @var{directory} is @code{nil}) and @var{initial}. If both
1492 @var{default} and @var{initial} are @code{nil}, this function uses
1493 @var{directory} as substitute default, or the current buffer's default
1494 directory if @var{directory} is @code{nil}.
1497 @defopt insert-default-directory
1498 This variable is used by @code{read-file-name}, and thus, indirectly,
1499 by most commands reading file names. (This includes all commands that
1500 use the code letters @samp{f} or @samp{F} in their interactive form.
1501 @xref{Interactive Codes,, Code Characters for interactive}.) Its
1502 value controls whether @code{read-file-name} starts by placing the
1503 name of the default directory in the minibuffer, plus the initial file
1504 name if any. If the value of this variable is @code{nil}, then
1505 @code{read-file-name} does not place any initial input in the
1506 minibuffer (unless you specify initial input with the @var{initial}
1507 argument). In that case, the default directory is still used for
1508 completion of relative file names, but is not displayed.
1510 If this variable is @code{nil} and the initial minibuffer contents are
1511 empty, the user may have to explicitly fetch the next history element
1512 to access a default value. If the variable is non-@code{nil}, the
1513 initial minibuffer contents are always non-empty and the user can
1514 always request a default value by immediately typing @key{RET} in an
1515 unedited minibuffer. (See above.)
1521 ;; @r{Here the minibuffer starts out with the default directory.}
1522 (let ((insert-default-directory t))
1523 (read-file-name "The file is "))
1527 ---------- Buffer: Minibuffer ----------
1528 The file is ~lewis/manual/@point{}
1529 ---------- Buffer: Minibuffer ----------
1533 ;; @r{Here the minibuffer is empty and only the prompt}
1534 ;; @r{appears on its line.}
1535 (let ((insert-default-directory nil))
1536 (read-file-name "The file is "))
1540 ---------- Buffer: Minibuffer ----------
1541 The file is @point{}
1542 ---------- Buffer: Minibuffer ----------
1547 @defun read-shell-command prompt &optional initial-contents hist &rest args
1548 This function reads a shell command from the minibuffer, prompting
1549 with @var{prompt} and providing intelligent completion. It completes
1550 the first word of the command using candidates that are appropriate
1551 for command names, and the rest of the command words as file names.
1553 This function uses @code{minibuffer-local-shell-command-map} as the
1554 keymap for minibuffer input. The @var{hist} argument specifies the
1555 history list to use; if is omitted or @code{nil}, it defaults to
1556 @code{shell-command-history} (@pxref{Minibuffer History,
1557 shell-command-history}). The optional argument @var{initial-contents}
1558 specifies the initial content of the minibuffer (@pxref{Initial
1559 Input}). The rest of @var{args}, if present, are used as the
1560 @var{default} and @var{inherit-input-method} arguments in
1561 @code{read-from-minibuffer} (@pxref{Text from Minibuffer}).
1564 @defvar minibuffer-local-shell-command-map
1565 This keymap is used by @code{read-shell-command} for completing
1566 command and file names that are part of a shell command.
1569 @node Completion Variables
1570 @subsection Completion Variables
1572 Here are some variables which can be used to alter the default
1573 completion behavior.
1575 @cindex completion styles
1576 @defopt completion-styles
1577 The value of this variable is a list of completion style (symbols) to
1578 use for performing completion. A @dfn{completion style} is a set of
1579 rules for generating completions. Each symbol in occurring this list
1580 must have a corresponding entry in @code{completion-styles-alist}.
1583 @defvar completion-styles-alist
1584 This variable stores a list of available completion styles. Each
1585 element in the list has the form
1588 (@var{style} @var{try-completion} @var{all-completions} @var{doc})
1592 Here, @var{style} is the name of the completion style (a symbol),
1593 which may be used in the @code{completion-styles} variable to refer to
1594 this style; @var{try-completion} is the function that does the
1595 completion; @var{all-completions} is the function that lists the
1596 completions; and @var{doc} is a string describing the completion
1599 The @var{try-completion} and @var{all-completions} functions should
1600 each accept four arguments: @var{string}, @var{collection},
1601 @var{predicate}, and @var{point}. The @var{string}, @var{collection},
1602 and @var{predicate} arguments have the same meanings as in
1603 @code{try-completion} (@pxref{Basic Completion}), and the @var{point}
1604 argument is the position of point within @var{string}. Each function
1605 should return a non-@code{nil} value if it performed its job, and
1606 @code{nil} if it did not (e.g.@: if there is no way to complete
1607 @var{string} according to the completion style).
1609 When the user calls a completion command like
1610 @code{minibuffer-complete} (@pxref{Completion Commands}), Emacs looks
1611 for the first style listed in @code{completion-styles} and calls its
1612 @var{try-completion} function. If this function returns @code{nil},
1613 Emacs moves to the next listed completion style and calls its
1614 @var{try-completion} function, and so on until one of the
1615 @var{try-completion} functions successfully performs completion and
1616 returns a non-@code{nil} value. A similar procedure is used for
1617 listing completions, via the @var{all-completions} functions.
1619 @xref{Completion Styles,,, emacs, The GNU Emacs Manual}, for a
1620 description of the available completion styles.
1623 @defopt completion-category-overrides
1624 This variable specifies special completion styles and other completion
1625 behaviors to use when completing certain types of text. Its value
1626 should be a list of the form @code{(@var{category} . @var{alist})}.
1627 @var{category} is a symbol describing what is being completed;
1628 currently, the @code{buffer} and @code{file} categories are defined,
1629 but others can be defined via specialized completion functions
1630 (@pxref{Programmed Completion}). @var{alist} is an association list
1631 describing how completion should behave for the corresponding
1632 category. The following alist keys are supported:
1636 The value should be a list of completion styles (symbols).
1639 The value should be a value for @code{completion-cycle-threshold}
1640 (@pxref{Completion Options,,, emacs, The GNU Emacs Manual}) for this
1645 Additional alist entries may be defined in the future.
1648 @defvar completion-extra-properties
1649 This variable is used to specify extra properties of the current
1650 completion command. It is intended to be let-bound by specialized
1651 completion commands. Its value should be a list of property and value
1652 pairs. The following properties are supported:
1655 @item :annotation-function
1656 The value should be a function to add annotations in the completions
1657 buffer. This function must accept one argument, a completion, and
1658 should either return @code{nil} or a string to be displayed next to
1661 @item :exit-function
1662 The value should be a function to run after performing completion.
1663 The function should accept two arguments, @var{string} and
1664 @var{status}, where @var{string} is the text to which the field was
1665 completed and @var{status} indicates what kind of operation happened:
1666 @code{finished} if text is now complete, @code{sole} if the text
1667 cannot be further completed but completion is not finished, or
1668 @code{exact} if the text is a valid completion but may be further
1673 @node Programmed Completion
1674 @subsection Programmed Completion
1675 @cindex programmed completion
1677 Sometimes it is not possible or convenient to create an alist or
1678 an obarray containing all the intended possible completions ahead
1679 of time. In such a case, you can supply your own function to compute
1680 the completion of a given string. This is called @dfn{programmed
1681 completion}. Emacs uses programmed completion when completing file
1682 names (@pxref{File Name Completion}), among many other cases.
1684 To use this feature, pass a function as the @var{collection}
1685 argument to @code{completing-read}. The function
1686 @code{completing-read} arranges to pass your completion function along
1687 to @code{try-completion}, @code{all-completions}, and other basic
1688 completion functions, which will then let your function do all
1691 The completion function should accept three arguments:
1695 The string to be completed.
1698 A predicate function with which to filter possible matches, or
1699 @code{nil} if none. The function should call the predicate for each
1700 possible match, and ignore the match if the predicate returns
1704 A flag specifying the type of completion operation to perform. This
1705 is one of the following four values:
1709 This specifies a @code{try-completion} operation. The function should
1710 return @code{t} if the specified string is a unique and exact match;
1711 if there is more than one match, it should return the common substring
1712 of all matches (if the string is an exact match for one completion
1713 alternative but also matches other longer alternatives, the return
1714 value is the string); if there are no matches, it should return
1718 This specifies an @code{all-completions} operation. The function
1719 should return a list of all possible completions of the specified
1723 This specifies a @code{test-completion} operation. The function
1724 should return @code{t} if the specified string is an exact match for
1725 some completion alternative; @code{nil} otherwise.
1727 @item (boundaries . @var{suffix})
1728 This specifies a @code{completion-boundaries} operation. The function
1729 should return @code{(boundaries START . END)}, where START is the
1730 position of the beginning boundary in the specified string, and END is
1731 the position of the end boundary in SUFFIX.
1734 This specifies a request for information about the state of the
1735 current completion. The function should return an alist, as described
1736 below. The alist may contain any number of elements.
1740 If the flag has any other value, the completion function should return
1744 The following is a list of metadata entries that a completion function
1745 may return in response to a @code{metadata} flag argument:
1749 The value should be a symbol describing what kind of text the
1750 completion function is trying to complete. If the symbol matches one
1751 of the keys in @code{completion-category-overrides}, the usual
1752 completion behavior is overridden. @xref{Completion Variables}.
1754 @item annotation-function
1755 The value should be a function for @dfn{annotating} completions. The
1756 function should take one argument, @var{string}, which is a possible
1757 completion. It should return a string, which is displayed after the
1758 completion @var{string} in the @file{*Completions*} buffer.
1760 @item display-sort-function
1761 The value should be a function for sorting completions. The function
1762 should take one argument, a list of completion strings, and return a
1763 sorted list of completion strings. It is allowed to alter the input
1766 @item cycle-sort-function
1767 The value should be a function for sorting completions, when
1768 @code{completion-cycle-threshold} is non-@code{nil} and the user is
1769 cycling through completion alternatives. @xref{Completion Options,,,
1770 emacs, The GNU Emacs Manual}. Its argument list and return value are
1771 the same as for @code{display-sort-function}.
1774 @defun completion-table-dynamic function
1775 This function is a convenient way to write a function that can act as
1776 programmed completion function. The argument @var{function} should be
1777 a function that takes one argument, a string, and returns an alist of
1778 possible completions of it. You can think of
1779 @code{completion-table-dynamic} as a transducer between that interface
1780 and the interface for programmed completion functions.
1783 @node Completion in Buffers
1784 @subsection Completion in Ordinary Buffers
1785 @cindex inline completion
1787 @findex completion-at-point
1788 Although completion is usually done in the minibuffer, the
1789 completion facility can also be used on the text in ordinary Emacs
1790 buffers. In many major modes, in-buffer completion is performed by
1791 the @kbd{C-M-i} or @kbd{M-@key{TAB}} command, bound to
1792 @code{completion-at-point}. @xref{Symbol Completion,,, emacs, The GNU
1793 Emacs Manual}. This command uses the abnormal hook variable
1794 @code{completion-at-point-functions}:
1796 @defvar completion-at-point-functions
1797 The value of this abnormal hook should be a list of functions, which
1798 are used to compute a completion table for completing the text at
1799 point. It can be used by major modes to provide mode-specific
1800 completion tables (@pxref{Major Mode Conventions}).
1802 When the command @code{completion-at-point} runs, it calls the
1803 functions in the list one by one, without any argument. Each function
1804 should return @code{nil} if it is unable to produce a completion table
1805 for the text at point. Otherwise it should return a list of the form
1808 (@var{start} @var{end} @var{collection} . @var{props})
1812 @var{start} and @var{end} delimit the text to complete (which should
1813 enclose point). @var{collection} is a completion table for completing
1814 that text, in a form suitable for passing as the second argument to
1815 @code{try-completion} (@pxref{Basic Completion}); completion
1816 alternatives will be generated from this completion table in the usual
1817 way, via the completion styles defined in @code{completion-styles}
1818 (@pxref{Completion Variables}). @var{props} is a property list for
1819 additional information; any of the properties in
1820 @code{completion-extra-properties} are recognized (@pxref{Completion
1821 Variables}), as well as the following additional ones:
1825 The value should be a predicate that completion candidates need to
1829 If the value is @code{no}, then if the completion table fails to match
1830 the text at point, then @code{completion-at-point} moves on to the
1831 next function in @code{completion-at-point-functions} instead of
1832 reporting a completion failure.
1835 A function in @code{completion-at-point-functions} may also return a
1836 function. In that case, that returned function is called, with no
1837 argument, and it is entirely responsible for performing the
1838 completion. We discourage this usage; it is intended to help convert
1839 old code to using @code{completion-at-point}.
1841 The first function in @code{completion-at-point-functions} to return a
1842 non-@code{nil} value is used by @code{completion-at-point}. The
1843 remaining functions are not called. The exception to this is when
1844 there is a @code{:exclusive} specification, as described above.
1847 The following function provides a convenient way to perform
1848 completion on an arbitrary stretch of text in an Emacs buffer:
1850 @defun completion-in-region start end collection &optional predicate
1851 This function completes the text in the current buffer between the
1852 positions @var{start} and @var{end}, using @var{collection}. The
1853 argument @var{collection} has the same meaning as in
1854 @code{try-completion} (@pxref{Basic Completion}).
1856 This function inserts the completion text directly into the current
1857 buffer. Unlike @code{completing-read} (@pxref{Minibuffer
1858 Completion}), it does not activate the minibuffer.
1860 For this function to work, point must be somewhere between @var{start}
1865 @node Yes-or-No Queries
1866 @section Yes-or-No Queries
1867 @cindex asking the user questions
1868 @cindex querying the user
1869 @cindex yes-or-no questions
1871 This section describes functions used to ask the user a yes-or-no
1872 question. The function @code{y-or-n-p} can be answered with a single
1873 character; it is useful for questions where an inadvertent wrong answer
1874 will not have serious consequences. @code{yes-or-no-p} is suitable for
1875 more momentous questions, since it requires three or four characters to
1878 If either of these functions is called in a command that was invoked
1879 using the mouse---more precisely, if @code{last-nonmenu-event}
1880 (@pxref{Command Loop Info}) is either @code{nil} or a list---then it
1881 uses a dialog box or pop-up menu to ask the question. Otherwise, it
1882 uses keyboard input. You can force use of the mouse or use of keyboard
1883 input by binding @code{last-nonmenu-event} to a suitable value around
1886 Strictly speaking, @code{yes-or-no-p} uses the minibuffer and
1887 @code{y-or-n-p} does not; but it seems best to describe them together.
1889 @defun y-or-n-p prompt
1890 This function asks the user a question, expecting input in the echo
1891 area. It returns @code{t} if the user types @kbd{y}, @code{nil} if the
1892 user types @kbd{n}. This function also accepts @key{SPC} to mean yes
1893 and @key{DEL} to mean no. It accepts @kbd{C-]} to mean ``quit,'' like
1894 @kbd{C-g}, because the question might look like a minibuffer and for
1895 that reason the user might try to use @kbd{C-]} to get out. The answer
1896 is a single character, with no @key{RET} needed to terminate it. Upper
1897 and lower case are equivalent.
1899 ``Asking the question'' means printing @var{prompt} in the echo area,
1900 followed by the string @w{@samp{(y or n) }}. If the input is not one of
1901 the expected answers (@kbd{y}, @kbd{n}, @kbd{@key{SPC}},
1902 @kbd{@key{DEL}}, or something that quits), the function responds
1903 @samp{Please answer y or n.}, and repeats the request.
1905 This function does not actually use the minibuffer, since it does not
1906 allow editing of the answer. It actually uses the echo area (@pxref{The
1907 Echo Area}), which uses the same screen space as the minibuffer. The
1908 cursor moves to the echo area while the question is being asked.
1910 The answers and their meanings, even @samp{y} and @samp{n}, are not
1911 hardwired. The keymap @code{query-replace-map} specifies them.
1912 @xref{Search and Replace}.
1914 In the following example, the user first types @kbd{q}, which is
1915 invalid. At the next prompt the user types @kbd{y}.
1919 (y-or-n-p "Do you need a lift? ")
1921 ;; @r{After evaluation of the preceding expression,}
1922 ;; @r{the following prompt appears in the echo area:}
1926 ---------- Echo area ----------
1927 Do you need a lift? (y or n)
1928 ---------- Echo area ----------
1931 ;; @r{If the user then types @kbd{q}, the following appears:}
1934 ---------- Echo area ----------
1935 Please answer y or n. Do you need a lift? (y or n)
1936 ---------- Echo area ----------
1939 ;; @r{When the user types a valid answer,}
1940 ;; @r{it is displayed after the question:}
1943 ---------- Echo area ----------
1944 Do you need a lift? (y or n) y
1945 ---------- Echo area ----------
1950 We show successive lines of echo area messages, but only one actually
1951 appears on the screen at a time.
1954 @defun y-or-n-p-with-timeout prompt seconds default-value
1955 Like @code{y-or-n-p}, except that if the user fails to answer within
1956 @var{seconds} seconds, this function stops waiting and returns
1957 @var{default-value}. It works by setting up a timer; see @ref{Timers}.
1958 The argument @var{seconds} may be an integer or a floating point number.
1961 @defun yes-or-no-p prompt
1962 This function asks the user a question, expecting input in the
1963 minibuffer. It returns @code{t} if the user enters @samp{yes},
1964 @code{nil} if the user types @samp{no}. The user must type @key{RET} to
1965 finalize the response. Upper and lower case are equivalent.
1967 @code{yes-or-no-p} starts by displaying @var{prompt} in the echo area,
1968 followed by @w{@samp{(yes or no) }}. The user must type one of the
1969 expected responses; otherwise, the function responds @samp{Please answer
1970 yes or no.}, waits about two seconds and repeats the request.
1972 @code{yes-or-no-p} requires more work from the user than
1973 @code{y-or-n-p} and is appropriate for more crucial decisions.
1979 (yes-or-no-p "Do you really want to remove everything? ")
1981 ;; @r{After evaluation of the preceding expression,}
1982 ;; @r{the following prompt appears,}
1983 ;; @r{with an empty minibuffer:}
1987 ---------- Buffer: minibuffer ----------
1988 Do you really want to remove everything? (yes or no)
1989 ---------- Buffer: minibuffer ----------
1994 If the user first types @kbd{y @key{RET}}, which is invalid because this
1995 function demands the entire word @samp{yes}, it responds by displaying
1996 these prompts, with a brief pause between them:
2000 ---------- Buffer: minibuffer ----------
2001 Please answer yes or no.
2002 Do you really want to remove everything? (yes or no)
2003 ---------- Buffer: minibuffer ----------
2008 @node Multiple Queries
2009 @section Asking Multiple Y-or-N Questions
2011 When you have a series of similar questions to ask, such as ``Do you
2012 want to save this buffer'' for each buffer in turn, you should use
2013 @code{map-y-or-n-p} to ask the collection of questions, rather than
2014 asking each question individually. This gives the user certain
2015 convenient facilities such as the ability to answer the whole series at
2018 @defun map-y-or-n-p prompter actor list &optional help action-alist no-cursor-in-echo-area
2019 This function asks the user a series of questions, reading a
2020 single-character answer in the echo area for each one.
2022 The value of @var{list} specifies the objects to ask questions about.
2023 It should be either a list of objects or a generator function. If it is
2024 a function, it should expect no arguments, and should return either the
2025 next object to ask about, or @code{nil} meaning stop asking questions.
2027 The argument @var{prompter} specifies how to ask each question. If
2028 @var{prompter} is a string, the question text is computed like this:
2031 (format @var{prompter} @var{object})
2035 where @var{object} is the next object to ask about (as obtained from
2038 If not a string, @var{prompter} should be a function of one argument
2039 (the next object to ask about) and should return the question text. If
2040 the value is a string, that is the question to ask the user. The
2041 function can also return @code{t} meaning do act on this object (and
2042 don't ask the user), or @code{nil} meaning ignore this object (and don't
2045 The argument @var{actor} says how to act on the answers that the user
2046 gives. It should be a function of one argument, and it is called with
2047 each object that the user says yes for. Its argument is always an
2048 object obtained from @var{list}.
2050 If the argument @var{help} is given, it should be a list of this form:
2053 (@var{singular} @var{plural} @var{action})
2057 where @var{singular} is a string containing a singular noun that
2058 describes the objects conceptually being acted on, @var{plural} is the
2059 corresponding plural noun, and @var{action} is a transitive verb
2060 describing what @var{actor} does.
2062 If you don't specify @var{help}, the default is @code{("object"
2063 "objects" "act on")}.
2065 Each time a question is asked, the user may enter @kbd{y}, @kbd{Y}, or
2066 @key{SPC} to act on that object; @kbd{n}, @kbd{N}, or @key{DEL} to skip
2067 that object; @kbd{!} to act on all following objects; @key{ESC} or
2068 @kbd{q} to exit (skip all following objects); @kbd{.} (period) to act on
2069 the current object and then exit; or @kbd{C-h} to get help. These are
2070 the same answers that @code{query-replace} accepts. The keymap
2071 @code{query-replace-map} defines their meaning for @code{map-y-or-n-p}
2072 as well as for @code{query-replace}; see @ref{Search and Replace}.
2074 You can use @var{action-alist} to specify additional possible answers
2075 and what they mean. It is an alist of elements of the form
2076 @code{(@var{char} @var{function} @var{help})}, each of which defines one
2077 additional answer. In this element, @var{char} is a character (the
2078 answer); @var{function} is a function of one argument (an object from
2079 @var{list}); @var{help} is a string.
2081 When the user responds with @var{char}, @code{map-y-or-n-p} calls
2082 @var{function}. If it returns non-@code{nil}, the object is considered
2083 ``acted upon,'' and @code{map-y-or-n-p} advances to the next object in
2084 @var{list}. If it returns @code{nil}, the prompt is repeated for the
2087 Normally, @code{map-y-or-n-p} binds @code{cursor-in-echo-area} while
2088 prompting. But if @var{no-cursor-in-echo-area} is non-@code{nil}, it
2091 If @code{map-y-or-n-p} is called in a command that was invoked using the
2092 mouse---more precisely, if @code{last-nonmenu-event} (@pxref{Command
2093 Loop Info}) is either @code{nil} or a list---then it uses a dialog box
2094 or pop-up menu to ask the question. In this case, it does not use
2095 keyboard input or the echo area. You can force use of the mouse or use
2096 of keyboard input by binding @code{last-nonmenu-event} to a suitable
2097 value around the call.
2099 The return value of @code{map-y-or-n-p} is the number of objects acted on.
2102 @node Reading a Password
2103 @section Reading a Password
2104 @cindex passwords, reading
2106 To read a password to pass to another program, you can use the
2107 function @code{read-passwd}.
2109 @defun read-passwd prompt &optional confirm default
2110 This function reads a password, prompting with @var{prompt}. It does
2111 not echo the password as the user types it; instead, it echoes @samp{.}
2112 for each character in the password.
2114 The optional argument @var{confirm}, if non-@code{nil}, says to read the
2115 password twice and insist it must be the same both times. If it isn't
2116 the same, the user has to type it over and over until the last two
2119 The optional argument @var{default} specifies the default password to
2120 return if the user enters empty input. If @var{default} is @code{nil},
2121 then @code{read-passwd} returns the null string in that case.
2124 @node Minibuffer Commands
2125 @section Minibuffer Commands
2127 This section describes some commands meant for use in the
2130 @deffn Command exit-minibuffer
2131 This command exits the active minibuffer. It is normally bound to
2132 keys in minibuffer local keymaps.
2135 @deffn Command self-insert-and-exit
2136 This command exits the active minibuffer after inserting the last
2137 character typed on the keyboard (found in @code{last-command-event};
2138 @pxref{Command Loop Info}).
2141 @deffn Command previous-history-element n
2142 This command replaces the minibuffer contents with the value of the
2143 @var{n}th previous (older) history element.
2146 @deffn Command next-history-element n
2147 This command replaces the minibuffer contents with the value of the
2148 @var{n}th more recent history element.
2151 @deffn Command previous-matching-history-element pattern n
2152 This command replaces the minibuffer contents with the value of the
2153 @var{n}th previous (older) history element that matches @var{pattern} (a
2154 regular expression).
2157 @deffn Command next-matching-history-element pattern n
2158 This command replaces the minibuffer contents with the value of the
2159 @var{n}th next (newer) history element that matches @var{pattern} (a
2160 regular expression).
2163 @node Minibuffer Windows
2164 @section Minibuffer Windows
2165 @cindex minibuffer windows
2167 These functions access and select minibuffer windows
2168 and test whether they are active.
2170 @defun active-minibuffer-window
2171 This function returns the currently active minibuffer window, or
2172 @code{nil} if none is currently active.
2175 @defun minibuffer-window &optional frame
2176 @anchor{Definition of minibuffer-window}
2177 This function returns the minibuffer window used for frame @var{frame}.
2178 If @var{frame} is @code{nil}, that stands for the current frame. Note
2179 that the minibuffer window used by a frame need not be part of that
2180 frame---a frame that has no minibuffer of its own necessarily uses some
2181 other frame's minibuffer window.
2184 @defun set-minibuffer-window window
2185 This function specifies @var{window} as the minibuffer window to use.
2186 This affects where the minibuffer is displayed if you put text in it
2187 without invoking the usual minibuffer commands. It has no effect on
2188 the usual minibuffer input functions because they all start by
2189 choosing the minibuffer window according to the current frame.
2193 @defun window-minibuffer-p &optional window
2194 This function returns non-@code{nil} if @var{window} is a minibuffer
2196 @var{window} defaults to the selected window.
2199 It is not correct to determine whether a given window is a minibuffer by
2200 comparing it with the result of @code{(minibuffer-window)}, because
2201 there can be more than one minibuffer window if there is more than one
2204 @defun minibuffer-window-active-p window
2205 This function returns non-@code{nil} if @var{window}, assumed to be
2206 a minibuffer window, is currently active.
2209 @node Minibuffer Contents
2210 @section Minibuffer Contents
2212 These functions access the minibuffer prompt and contents.
2214 @defun minibuffer-prompt
2215 This function returns the prompt string of the currently active
2216 minibuffer. If no minibuffer is active, it returns @code{nil}.
2219 @defun minibuffer-prompt-end
2220 This function returns the current
2221 position of the end of the minibuffer prompt, if a minibuffer is
2222 current. Otherwise, it returns the minimum valid buffer position.
2225 @defun minibuffer-prompt-width
2226 This function returns the current display-width of the minibuffer
2227 prompt, if a minibuffer is current. Otherwise, it returns zero.
2230 @defun minibuffer-contents
2231 This function returns the editable
2232 contents of the minibuffer (that is, everything except the prompt) as
2233 a string, if a minibuffer is current. Otherwise, it returns the
2234 entire contents of the current buffer.
2237 @defun minibuffer-contents-no-properties
2238 This is like @code{minibuffer-contents}, except that it does not copy text
2239 properties, just the characters themselves. @xref{Text Properties}.
2242 @defun minibuffer-completion-contents
2243 This is like @code{minibuffer-contents}, except that it returns only
2244 the contents before point. That is the part that completion commands
2245 operate on. @xref{Minibuffer Completion}.
2248 @defun delete-minibuffer-contents
2249 This function erases the editable contents of the minibuffer (that is,
2250 everything except the prompt), if a minibuffer is current. Otherwise,
2251 it erases the entire current buffer.
2254 @node Recursive Mini
2255 @section Recursive Minibuffers
2256 @cindex recursive minibuffers
2258 These functions and variables deal with recursive minibuffers
2259 (@pxref{Recursive Editing}):
2261 @defun minibuffer-depth
2262 This function returns the current depth of activations of the
2263 minibuffer, a nonnegative integer. If no minibuffers are active, it
2267 @defopt enable-recursive-minibuffers
2268 If this variable is non-@code{nil}, you can invoke commands (such as
2269 @code{find-file}) that use minibuffers even while the minibuffer window
2270 is active. Such invocation produces a recursive editing level for a new
2271 minibuffer. The outer-level minibuffer is invisible while you are
2272 editing the inner one.
2274 If this variable is @code{nil}, you cannot invoke minibuffer
2275 commands when the minibuffer window is active, not even if you switch to
2276 another window to do it.
2280 If a command name has a property @code{enable-recursive-minibuffers}
2281 that is non-@code{nil}, then the command can use the minibuffer to read
2282 arguments even if it is invoked from the minibuffer. A command can
2283 also achieve this by binding @code{enable-recursive-minibuffers}
2284 to @code{t} in the interactive declaration (@pxref{Using Interactive}).
2285 The minibuffer command @code{next-matching-history-element} (normally
2286 @kbd{M-s} in the minibuffer) does the latter.
2288 @node Minibuffer Misc
2289 @section Minibuffer Miscellany
2291 @defun minibufferp &optional buffer-or-name
2292 This function returns non-@code{nil} if @var{buffer-or-name} is a
2293 minibuffer. If @var{buffer-or-name} is omitted, it tests the current
2297 @defvar minibuffer-setup-hook
2298 This is a normal hook that is run whenever the minibuffer is entered.
2302 @defvar minibuffer-exit-hook
2303 This is a normal hook that is run whenever the minibuffer is exited.
2307 @defvar minibuffer-help-form
2308 @anchor{Definition of minibuffer-help-form}
2309 The current value of this variable is used to rebind @code{help-form}
2310 locally inside the minibuffer (@pxref{Help Functions}).
2313 @defvar minibuffer-scroll-window
2314 @anchor{Definition of minibuffer-scroll-window}
2315 If the value of this variable is non-@code{nil}, it should be a window
2316 object. When the function @code{scroll-other-window} is called in the
2317 minibuffer, it scrolls this window.
2320 @defun minibuffer-selected-window
2321 This function returns the window which was selected when the
2322 minibuffer was entered. If selected window is not a minibuffer
2323 window, it returns @code{nil}.
2326 @defopt max-mini-window-height
2327 This variable specifies the maximum height for resizing minibuffer
2328 windows. If a float, it specifies a fraction of the height of the
2329 frame. If an integer, it specifies a number of lines.
2332 @defun minibuffer-message string &rest args
2333 This function displays @var{string} temporarily at the end of the
2334 minibuffer text, for two seconds, or until the next input event
2335 arrives, whichever comes first. If @var{args} is non-@code{nil}, the
2336 actual message is obtained by passing @var{string} and @var{args}
2337 through @code{format}. @xref{Formatting Strings}.