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.
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 Windows:: Operating on the special minibuffer windows.
33 * Minibuffer Contents:: How such commands access the minibuffer text.
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 @c See http://debbugs.gnu.org/11276
61 The minibuffer's window is normally a single line; it grows
62 automatically if the contents require more space. Whilst it is
63 active, you can explicitly resize it temporarily with the window
64 sizing commands; it reverts to its normal size when the minibuffer is
65 exited. When the minibuffer is not active, you can resize it
66 permanently by using the window sizing commands in the frame's other
67 window, or dragging the mode line with the mouse. (Due to details of
68 the current implementation, for this to work @code{resize-mini-windows}
69 must be @code{nil}.) If the frame contains just a minibuffer, you can
70 change the minibuffer's size by changing the frame's size.
72 Use of the minibuffer reads input events, and that alters the values
73 of variables such as @code{this-command} and @code{last-command}
74 (@pxref{Command Loop Info}). Your program should bind them around the
75 code that uses the minibuffer, if you do not want that to change them.
77 Under some circumstances, a command can use a minibuffer even if
78 there is an active minibuffer; such a minibuffer is called a
79 @dfn{recursive minibuffer}. The first minibuffer is named
80 @w{@samp{ *Minibuf-1*}}. Recursive minibuffers are named by
81 incrementing the number at the end of the name. (The names begin with
82 a space so that they won't show up in normal buffer lists.) Of
83 several recursive minibuffers, the innermost (or most recently
84 entered) is the active minibuffer. We usually call this ``the''
85 minibuffer. You can permit or forbid recursive minibuffers by setting
86 the variable @code{enable-recursive-minibuffers}, or by putting
87 properties of that name on command symbols (@xref{Recursive Mini}.)
89 Like other buffers, a minibuffer uses a local keymap
90 (@pxref{Keymaps}) to specify special key bindings. The function that
91 invokes the minibuffer also sets up its local map according to the job
92 to be done. @xref{Text from Minibuffer}, for the non-completion
93 minibuffer local maps. @xref{Completion Commands}, for the minibuffer
94 local maps for completion.
96 @cindex inactive minibuffer
97 When a minibuffer is inactive, its major mode is
98 @code{minibuffer-inactive-mode}, with keymap
99 @code{minibuffer-inactive-mode-map}. This is only really useful if
100 the minibuffer is in a separate frame. @xref{Minibuffers and Frames}.
102 When Emacs is running in batch mode, any request to read from the
103 minibuffer actually reads a line from the standard input descriptor that
104 was supplied when Emacs was started.
106 @node Text from Minibuffer
107 @section Reading Text Strings with the Minibuffer
109 The most basic primitive for minibuffer input is
110 @code{read-from-minibuffer}, which can be used to read either a string
111 or a Lisp object in textual form. The function @code{read-regexp} is
112 used for reading regular expressions (@pxref{Regular Expressions}),
113 which are a special kind of string. There are also specialized
114 functions for reading commands, variables, file names, etc.@:
115 (@pxref{Completion}).
117 In most cases, you should not call minibuffer input functions in the
118 middle of a Lisp function. Instead, do all minibuffer input as part of
119 reading the arguments for a command, in the @code{interactive}
120 specification. @xref{Defining Commands}.
122 @defun read-from-minibuffer prompt &optional initial keymap read history default inherit-input-method
123 This function is the most general way to get input from the
124 minibuffer. By default, it accepts arbitrary text and returns it as a
125 string; however, if @var{read} is non-@code{nil}, then it uses
126 @code{read} to convert the text into a Lisp object (@pxref{Input
129 The first thing this function does is to activate a minibuffer and
130 display it with @var{prompt} (which must be a string) as the
131 prompt. Then the user can edit text in the minibuffer.
133 When the user types a command to exit the minibuffer,
134 @code{read-from-minibuffer} constructs the return value from the text in
135 the minibuffer. Normally it returns a string containing that text.
136 However, if @var{read} is non-@code{nil}, @code{read-from-minibuffer}
137 reads the text and returns the resulting Lisp object, unevaluated.
138 (@xref{Input Functions}, for information about reading.)
140 The argument @var{default} specifies default values to make available
141 through the history commands. It should be a string, a list of
142 strings, or @code{nil}. The string or strings become the minibuffer's
143 ``future history'', available to the user with @kbd{M-n}.
145 If @var{read} is non-@code{nil}, then @var{default} is also used
146 as the input to @code{read}, if the user enters empty input.
147 If @var{default} is a list of strings, the first string is used as the input.
148 If @var{default} is @code{nil}, empty input results in an @code{end-of-file} error.
149 However, in the usual case (where @var{read} is @code{nil}),
150 @code{read-from-minibuffer} ignores @var{default} when the user enters
151 empty input and returns an empty string, @code{""}. In this respect,
152 it differs from all the other minibuffer input functions in this chapter.
154 If @var{keymap} is non-@code{nil}, that keymap is the local keymap to
155 use in the minibuffer. If @var{keymap} is omitted or @code{nil}, the
156 value of @code{minibuffer-local-map} is used as the keymap. Specifying
157 a keymap is the most important way to customize the minibuffer for
158 various applications such as completion.
160 The argument @var{history} specifies a history list variable to use
161 for saving the input and for history commands used in the minibuffer.
162 It defaults to @code{minibuffer-history}. You can optionally specify
163 a starting position in the history list as well. @xref{Minibuffer History}.
165 If the variable @code{minibuffer-allow-text-properties} is
166 non-@code{nil}, then the string that is returned includes whatever text
167 properties were present in the minibuffer. Otherwise all the text
168 properties are stripped when the value is returned.
170 If the argument @var{inherit-input-method} is non-@code{nil}, then the
171 minibuffer inherits the current input method (@pxref{Input Methods}) and
172 the setting of @code{enable-multibyte-characters} (@pxref{Text
173 Representations}) from whichever buffer was current before entering the
176 Use of @var{initial} is mostly deprecated; we recommend using
177 a non-@code{nil} value only in conjunction with specifying a cons cell
178 for @var{history}. @xref{Initial Input}.
181 @defun read-string prompt &optional initial history default inherit-input-method
182 This function reads a string from the minibuffer and returns it. The
183 arguments @var{prompt}, @var{initial}, @var{history} and
184 @var{inherit-input-method} are used as in @code{read-from-minibuffer}.
185 The keymap used is @code{minibuffer-local-map}.
187 The optional argument @var{default} is used as in
188 @code{read-from-minibuffer}, except that, if non-@code{nil}, it also
189 specifies a default value to return if the user enters null input. As
190 in @code{read-from-minibuffer} it should be a string, a list of
191 strings, or @code{nil}, which is equivalent to an empty string. When
192 @var{default} is a string, that string is the default value. When it
193 is a list of strings, the first string is the default value. (All
194 these strings are available to the user in the ``future minibuffer
197 This function works by calling the
198 @code{read-from-minibuffer} function:
202 (read-string @var{prompt} @var{initial} @var{history} @var{default} @var{inherit})
205 (read-from-minibuffer @var{prompt} @var{initial} nil nil
206 @var{history} @var{default} @var{inherit})))
207 (if (and (equal value "") @var{default})
208 (if (consp @var{default}) (car @var{default}) @var{default})
214 @defun read-regexp prompt &optional default history
215 This function reads a regular expression as a string from the
216 minibuffer and returns it. The argument @var{prompt} is used as in
217 @code{read-from-minibuffer}.
219 The optional argument @var{default} specifies a default value to
220 return if the user enters null input; it should be a string, or
221 @code{nil}, which is equivalent to an empty string.
223 The optional argument @var{history}, if non-@code{nil}, is a symbol
224 specifying a minibuffer history list to use (@pxref{Minibuffer
225 History}). If it is omitted or @code{nil}, the history list defaults
226 to @code{regexp-history}.
228 @code{read-regexp} also collects a few useful candidates for input and
229 passes them to @code{read-from-minibuffer}, to make them available to
230 the user as the ``future minibuffer history list'' (@pxref{Minibuffer
231 History, future list,, emacs, The GNU Emacs Manual}). These
236 The word or symbol at point.
238 The last regexp used in an incremental search.
240 The last string used in an incremental search.
242 The last string or pattern used in query-replace commands.
245 This function works by calling the @code{read-from-minibuffer}
246 function, after computing the list of defaults as described above.
249 @defvar minibuffer-allow-text-properties
250 If this variable is @code{nil}, then @code{read-from-minibuffer}
251 and @code{read-string} strip all text properties from the minibuffer
252 input before returning it. However,
253 @code{read-no-blanks-input} (see below), as well as
254 @code{read-minibuffer} and related functions (@pxref{Object from
255 Minibuffer,, Reading Lisp Objects With the Minibuffer}), and all
256 functions that do minibuffer input with completion, discard text
257 properties unconditionally, regardless of the value of this variable.
260 @defvar minibuffer-local-map
262 @anchor{Definition of minibuffer-local-map}
263 @c avoid page break at anchor; work around Texinfo deficiency
264 is the default local keymap for reading from the minibuffer. By
265 default, it makes the following bindings:
269 @code{exit-minibuffer}
272 @code{exit-minibuffer}
275 @code{abort-recursive-edit}
279 @code{next-history-element}
283 @code{previous-history-element}
286 @code{next-matching-history-element}
289 @code{previous-matching-history-element}
292 @c Does not seem worth/appropriate mentioning.
293 @item @kbd{C-@key{TAB}}
294 @code{file-cache-minibuffer-complete}
299 @c In version 18, initial is required
301 @defun read-no-blanks-input prompt &optional initial inherit-input-method
302 This function reads a string from the minibuffer, but does not allow
303 whitespace characters as part of the input: instead, those characters
304 terminate the input. The arguments @var{prompt}, @var{initial}, and
305 @var{inherit-input-method} are used as in @code{read-from-minibuffer}.
307 This is a simplified interface to the @code{read-from-minibuffer}
308 function, and passes the value of the @code{minibuffer-local-ns-map}
309 keymap as the @var{keymap} argument for that function. Since the keymap
310 @code{minibuffer-local-ns-map} does not rebind @kbd{C-q}, it @emph{is}
311 possible to put a space into the string, by quoting it.
313 This function discards text properties, regardless of the value of
314 @code{minibuffer-allow-text-properties}.
318 (read-no-blanks-input @var{prompt} @var{initial})
320 (let (minibuffer-allow-text-properties)
321 (read-from-minibuffer @var{prompt} @var{initial} minibuffer-local-ns-map))
326 @c Slightly unfortunate name, suggesting it might be related to the
328 @defvar minibuffer-local-ns-map
329 This built-in variable is the keymap used as the minibuffer local keymap
330 in the function @code{read-no-blanks-input}. By default, it makes the
331 following bindings, in addition to those of @code{minibuffer-local-map}:
335 @cindex @key{SPC} in minibuffer
336 @code{exit-minibuffer}
339 @cindex @key{TAB} in minibuffer
340 @code{exit-minibuffer}
343 @cindex @kbd{?} in minibuffer
344 @code{self-insert-and-exit}
348 @node Object from Minibuffer
349 @section Reading Lisp Objects with the Minibuffer
351 This section describes functions for reading Lisp objects with the
354 @defun read-minibuffer prompt &optional initial
355 This function reads a Lisp object using the minibuffer, and returns it
356 without evaluating it. The arguments @var{prompt} and @var{initial} are
357 used as in @code{read-from-minibuffer}.
359 This is a simplified interface to the
360 @code{read-from-minibuffer} function:
364 (read-minibuffer @var{prompt} @var{initial})
366 (let (minibuffer-allow-text-properties)
367 (read-from-minibuffer @var{prompt} @var{initial} nil t))
371 Here is an example in which we supply the string @code{"(testing)"} as
377 "Enter an expression: " (format "%s" '(testing)))
379 ;; @r{Here is how the minibuffer is displayed:}
383 ---------- Buffer: Minibuffer ----------
384 Enter an expression: (testing)@point{}
385 ---------- Buffer: Minibuffer ----------
390 The user can type @key{RET} immediately to use the initial input as a
391 default, or can edit the input.
394 @defun eval-minibuffer prompt &optional initial
395 This function reads a Lisp expression using the minibuffer, evaluates
396 it, then returns the result. The arguments @var{prompt} and
397 @var{initial} are used as in @code{read-from-minibuffer}.
399 This function simply evaluates the result of a call to
400 @code{read-minibuffer}:
404 (eval-minibuffer @var{prompt} @var{initial})
406 (eval (read-minibuffer @var{prompt} @var{initial}))
411 @defun edit-and-eval-command prompt form
412 This function reads a Lisp expression in the minibuffer, evaluates it,
413 then returns the result. The difference between this command and
414 @code{eval-minibuffer} is that here the initial @var{form} is not
415 optional and it is treated as a Lisp object to be converted to printed
416 representation rather than as a string of text. It is printed with
417 @code{prin1}, so if it is a string, double-quote characters (@samp{"})
418 appear in the initial text. @xref{Output Functions}.
420 In the following example, we offer the user an expression with initial
421 text that is already a valid form:
425 (edit-and-eval-command "Please edit: " '(forward-word 1))
427 ;; @r{After evaluation of the preceding expression,}
428 ;; @r{the following appears in the minibuffer:}
432 ---------- Buffer: Minibuffer ----------
433 Please edit: (forward-word 1)@point{}
434 ---------- Buffer: Minibuffer ----------
439 Typing @key{RET} right away would exit the minibuffer and evaluate the
440 expression, thus moving point forward one word.
443 @node Minibuffer History
444 @section Minibuffer History
445 @cindex minibuffer history
448 A @dfn{minibuffer history list} records previous minibuffer inputs
449 so the user can reuse them conveniently. It is a variable whose value
450 is a list of strings (previous inputs), most recent first.
452 There are many separate minibuffer history lists, used for different
453 kinds of inputs. It's the Lisp programmer's job to specify the right
454 history list for each use of the minibuffer.
456 You specify a minibuffer history list with the optional @var{history}
457 argument to @code{read-from-minibuffer} or @code{completing-read}.
458 Here are the possible values for it:
462 Use @var{variable} (a symbol) as the history list.
464 @item (@var{variable} . @var{startpos})
465 Use @var{variable} (a symbol) as the history list, and assume that the
466 initial history position is @var{startpos} (a nonnegative integer).
468 Specifying 0 for @var{startpos} is equivalent to just specifying the
469 symbol @var{variable}. @code{previous-history-element} will display
470 the most recent element of the history list in the minibuffer. If you
471 specify a positive @var{startpos}, the minibuffer history functions
472 behave as if @code{(elt @var{variable} (1- @var{startpos}))} were the
473 history element currently shown in the minibuffer.
475 For consistency, you should also specify that element of the history
476 as the initial minibuffer contents, using the @var{initial} argument
477 to the minibuffer input function (@pxref{Initial Input}).
480 If you don't specify @var{history}, then the default history list
481 @code{minibuffer-history} is used. For other standard history lists,
482 see below. You can also create your own history list variable; just
483 initialize it to @code{nil} before the first use.
485 Both @code{read-from-minibuffer} and @code{completing-read} add new
486 elements to the history list automatically, and provide commands to
487 allow the user to reuse items on the list. The only thing your program
488 needs to do to use a history list is to initialize it and to pass its
489 name to the input functions when you wish. But it is safe to modify the
490 list by hand when the minibuffer input functions are not using it.
492 Emacs functions that add a new element to a history list can also
493 delete old elements if the list gets too long. The variable
494 @code{history-length} specifies the maximum length for most history
495 lists. To specify a different maximum length for a particular history
496 list, put the length in the @code{history-length} property of the
497 history list symbol. The variable @code{history-delete-duplicates}
498 specifies whether to delete duplicates in history.
500 @defun add-to-history history-var newelt &optional maxelt keep-all
501 This function adds a new element @var{newelt}, if it isn't the empty
502 string, to the history list stored in the variable @var{history-var},
503 and returns the updated history list. It limits the list length to
504 the value of @var{maxelt} (if non-@code{nil}) or @code{history-length}
505 (described below). The possible values of @var{maxelt} have the same
506 meaning as the values of @code{history-length}.
508 Normally, @code{add-to-history} removes duplicate members from the
509 history list if @code{history-delete-duplicates} is non-@code{nil}.
510 However, if @var{keep-all} is non-@code{nil}, that says not to remove
511 duplicates, and to add @var{newelt} to the list even if it is empty.
514 @defvar history-add-new-input
515 If the value of this variable is @code{nil}, standard functions that
516 read from the minibuffer don't add new elements to the history list.
517 This lets Lisp programs explicitly manage input history by using
518 @code{add-to-history}. The default value is @code{t}.
521 @defopt history-length
522 The value of this variable specifies the maximum length for all
523 history lists that don't specify their own maximum lengths. If the
524 value is @code{t}, that means there is no maximum (don't delete old
525 elements). If a history list variable's symbol has a non-@code{nil}
526 @code{history-length} property, it overrides this variable for that
527 particular history list.
530 @defopt history-delete-duplicates
531 If the value of this variable is @code{t}, that means when adding a
532 new history element, all previous identical elements are deleted.
535 Here are some of the standard minibuffer history list variables:
537 @defvar minibuffer-history
538 The default history list for minibuffer history input.
541 @defvar query-replace-history
542 A history list for arguments to @code{query-replace} (and similar
543 arguments to other commands).
546 @defvar file-name-history
547 A history list for file-name arguments.
550 @defvar buffer-name-history
551 A history list for buffer-name arguments.
554 @defvar regexp-history
555 A history list for regular expression arguments.
558 @defvar extended-command-history
559 A history list for arguments that are names of extended commands.
562 @defvar shell-command-history
563 A history list for arguments that are shell commands.
566 @defvar read-expression-history
567 A history list for arguments that are Lisp expressions to evaluate.
570 @defvar face-name-history
571 A history list for arguments that are faces.
574 @c Less common: coding-system-history, input-method-history,
575 @c command-history, grep-history, grep-find-history,
576 @c read-envvar-name-history, setenv-history, yes-or-no-p-history.
579 @section Initial Input
581 Several of the functions for minibuffer input have an argument called
582 @var{initial}. This is a mostly-deprecated
583 feature for specifying that the minibuffer should start out with
584 certain text, instead of empty as usual.
586 If @var{initial} is a string, the minibuffer starts out containing the
587 text of the string, with point at the end, when the user starts to
588 edit the text. If the user simply types @key{RET} to exit the
589 minibuffer, it will use the initial input string to determine the
592 @strong{We discourage use of a non-@code{nil} value for
593 @var{initial}}, because initial input is an intrusive interface.
594 History lists and default values provide a much more convenient method
595 to offer useful default inputs to the user.
597 There is just one situation where you should specify a string for an
598 @var{initial} argument. This is when you specify a cons cell for the
599 @var{history} argument. @xref{Minibuffer History}.
601 @var{initial} can also be a cons cell of the form @code{(@var{string}
602 . @var{position})}. This means to insert @var{string} in the
603 minibuffer but put point at @var{position} within the string's text.
605 As a historical accident, @var{position} was implemented
606 inconsistently in different functions. In @code{completing-read},
607 @var{position}'s value is interpreted as origin-zero; that is, a value
608 of 0 means the beginning of the string, 1 means after the first
609 character, etc. In @code{read-minibuffer}, and the other
610 non-completion minibuffer input functions that support this argument,
611 1 means the beginning of the string, 2 means after the first character,
614 Use of a cons cell as the value for @var{initial} arguments is deprecated.
620 @dfn{Completion} is a feature that fills in the rest of a name
621 starting from an abbreviation for it. Completion works by comparing the
622 user's input against a list of valid names and determining how much of
623 the name is determined uniquely by what the user has typed. For
624 example, when you type @kbd{C-x b} (@code{switch-to-buffer}) and then
625 @c "This is the sort of English up with which I will not put."
626 type the first few letters of the name of the buffer to which you wish
627 to switch, and then type @key{TAB} (@code{minibuffer-complete}), Emacs
628 extends the name as far as it can.
630 Standard Emacs commands offer completion for names of symbols, files,
631 buffers, and processes; with the functions in this section, you can
632 implement completion for other kinds of names.
634 The @code{try-completion} function is the basic primitive for
635 completion: it returns the longest determined completion of a given
636 initial string, with a given set of strings to match against.
638 The function @code{completing-read} provides a higher-level interface
639 for completion. A call to @code{completing-read} specifies how to
640 determine the list of valid names. The function then activates the
641 minibuffer with a local keymap that binds a few keys to commands useful
642 for completion. Other functions provide convenient simple interfaces
643 for reading certain kinds of names with completion.
646 * Basic Completion:: Low-level functions for completing strings.
647 * Minibuffer Completion:: Invoking the minibuffer with completion.
648 * Completion Commands:: Minibuffer commands that do completion.
649 * High-Level Completion:: Convenient special cases of completion
650 (reading buffer names, variable names, etc.).
651 * Reading File Names:: Using completion to read file names and
653 * Completion Variables:: Variables controlling completion behavior.
654 * Programmed Completion:: Writing your own completion function.
655 * Completion in Buffers:: Completing text in ordinary buffers.
658 @node Basic Completion
659 @subsection Basic Completion Functions
661 The following completion functions have nothing in themselves to do
662 with minibuffers. We describe them here to keep them near the
663 higher-level completion features that do use the minibuffer.
665 @defun try-completion string collection &optional predicate
666 This function returns the longest common substring of all possible
667 completions of @var{string} in @var{collection}.
669 @cindex completion table
670 @var{collection} is called the @dfn{completion table}. Its value must
671 be a list of strings or cons cells, an obarray, a hash table, or a
674 @code{try-completion} compares @var{string} against each of the
675 permissible completions specified by the completion table. If no
676 permissible completions match, it returns @code{nil}. If there is
677 just one matching completion, and the match is exact, it returns
678 @code{t}. Otherwise, it returns the longest initial sequence common
679 to all possible matching completions.
681 If @var{collection} is an list, the permissible completions are
682 specified by the elements of the list, each of which should be either
683 a string, or a cons cell whose @sc{car} is either a string or a symbol
684 (a symbol is converted to a string using @code{symbol-name}). If the
685 list contains elements of any other type, those are ignored.
687 @cindex obarray in completion
688 If @var{collection} is an obarray (@pxref{Creating Symbols}), the names
689 of all symbols in the obarray form the set of permissible completions.
691 If @var{collection} is a hash table, then the keys that are strings
692 are the possible completions. Other keys are ignored.
694 You can also use a function as @var{collection}. Then the function is
695 solely responsible for performing completion; @code{try-completion}
696 returns whatever this function returns. The function is called with
697 three arguments: @var{string}, @var{predicate} and @code{nil} (the
698 third argument is so that the same function can be used
699 in @code{all-completions} and do the appropriate thing in either
700 case). @xref{Programmed Completion}.
702 If the argument @var{predicate} is non-@code{nil}, then it must be a
703 function of one argument, unless @var{collection} is a hash table, in
704 which case it should be a function of two arguments. It is used to
705 test each possible match, and the match is accepted only if
706 @var{predicate} returns non-@code{nil}. The argument given to
707 @var{predicate} is either a string or a cons cell (the @sc{car} of
708 which is a string) from the alist, or a symbol (@emph{not} a symbol
709 name) from the obarray. If @var{collection} is a hash table,
710 @var{predicate} is called with two arguments, the string key and the
713 In addition, to be acceptable, a completion must also match all the
714 regular expressions in @code{completion-regexp-list}. (Unless
715 @var{collection} is a function, in which case that function has to
716 handle @code{completion-regexp-list} itself.)
718 In the first of the following examples, the string @samp{foo} is
719 matched by three of the alist @sc{car}s. All of the matches begin with
720 the characters @samp{fooba}, so that is the result. In the second
721 example, there is only one possible match, and it is exact, so the
722 return value is @code{t}.
728 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)))
733 (try-completion "foo" '(("barfoo" 2) ("foo" 3)))
738 In the following example, numerous symbols begin with the characters
739 @samp{forw}, and all of them begin with the word @samp{forward}. In
740 most of the symbols, this is followed with a @samp{-}, but not in all,
741 so no more than @samp{forward} can be completed.
745 (try-completion "forw" obarray)
750 Finally, in the following example, only two of the three possible
751 matches pass the predicate @code{test} (the string @samp{foobaz} is
752 too short). Both of those begin with the string @samp{foobar}.
757 (> (length (car s)) 6))
763 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
770 @c Removed obsolete argument nospace.
771 @defun all-completions string collection &optional predicate
772 This function returns a list of all possible completions of
773 @var{string}. The arguments to this function
774 @c (aside from @var{nospace})
775 are the same as those of @code{try-completion}, and it
776 uses @code{completion-regexp-list} in the same way that
777 @code{try-completion} does.
780 The optional argument @var{nospace} is obsolete. If it is
781 non-@code{nil}, completions that start with a space are ignored unless
782 @var{string} starts with a space.
785 If @var{collection} is a function, it is called with three arguments:
786 @var{string}, @var{predicate} and @code{t}; then @code{all-completions}
787 returns whatever the function returns. @xref{Programmed Completion}.
789 Here is an example, using the function @code{test} shown in the
790 example for @code{try-completion}:
795 (> (length (car s)) 6))
802 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
804 @result{} ("foobar1" "foobar2")
809 @defun test-completion string collection &optional predicate
810 @anchor{Definition of test-completion}
811 This function returns non-@code{nil} if @var{string} is a valid
812 completion alternative specified by @var{collection} and
813 @var{predicate}. The arguments are the same as in
814 @code{try-completion}. For instance, if @var{collection} is a list of
815 strings, this is true if @var{string} appears in the list and
816 @var{predicate} is satisfied.
818 This function uses @code{completion-regexp-list} in the same
819 way that @code{try-completion} does.
821 If @var{predicate} is non-@code{nil} and if @var{collection} contains
822 several strings that are equal to each other, as determined by
823 @code{compare-strings} according to @code{completion-ignore-case},
824 then @var{predicate} should accept either all or none of them.
825 Otherwise, the return value of @code{test-completion} is essentially
828 If @var{collection} is a function, it is called with three arguments,
829 the values @var{string}, @var{predicate} and @code{lambda}; whatever
830 it returns, @code{test-completion} returns in turn.
833 @defun completion-boundaries string collection predicate suffix
834 This function returns the boundaries of the field on which @var{collection}
835 will operate, assuming that @var{string} holds the text before point
836 and @var{suffix} holds the text after point.
838 Normally completion operates on the whole string, so for all normal
839 collections, this will always return @code{(0 . (length
840 @var{suffix}))}. But more complex completion such as completion on
841 files is done one field at a time. For example, completion of
842 @code{"/usr/sh"} will include @code{"/usr/share/"} but not
843 @code{"/usr/share/doc"} even if @code{"/usr/share/doc"} exists.
844 Also @code{all-completions} on @code{"/usr/sh"} will not include
845 @code{"/usr/share/"} but only @code{"share/"}. So if @var{string} is
846 @code{"/usr/sh"} and @var{suffix} is @code{"e/doc"},
847 @code{completion-boundaries} will return @code{(5 . 1)} which tells us
848 that the @var{collection} will only return completion information that
849 pertains to the area after @code{"/usr/"} and before @code{"/doc"}.
852 If you store a completion alist in a variable, you should mark the
853 variable as ``risky'' by giving it a non-@code{nil}
854 @code{risky-local-variable} property. @xref{File Local Variables}.
856 @defvar completion-ignore-case
857 If the value of this variable is non-@code{nil}, case is not
858 considered significant in completion. Within @code{read-file-name},
859 this variable is overridden by
860 @code{read-file-name-completion-ignore-case} (@pxref{Reading File
861 Names}); within @code{read-buffer}, it is overridden by
862 @code{read-buffer-completion-ignore-case} (@pxref{High-Level
866 @defvar completion-regexp-list
867 This is a list of regular expressions. The completion functions only
868 consider a completion acceptable if it matches all regular expressions
869 in this list, with @code{case-fold-search} (@pxref{Searching and Case})
870 bound to the value of @code{completion-ignore-case}.
873 @defmac lazy-completion-table var fun
874 This macro provides a way to initialize the variable @var{var} as a
875 collection for completion in a lazy way, not computing its actual
876 contents until they are first needed. You use this macro to produce a
877 value that you store in @var{var}. The actual computation of the
878 proper value is done the first time you do completion using @var{var}.
879 It is done by calling @var{fun} with no arguments. The
880 value @var{fun} returns becomes the permanent value of @var{var}.
885 (defvar foo (lazy-completion-table foo make-my-alist))
889 @c FIXME? completion-table-with-context?
891 @findex completion-table-case-fold
892 @findex completion-table-in-turn
893 @findex completion-table-subvert
894 @findex completion-table-with-predicate
895 @findex completion-table-with-terminator
896 There are several functions that take an existing completion table and
897 return a modified version. @code{completion-table-case-fold} returns
898 a case-insensitive table. @code{completion-table-in-turn} combines
899 multiple input tables. @code{completion-table-subvert} alters a table
900 to use a different initial prefix.
901 @code{completion-table-with-terminator} adds a terminating string.
902 @code{completion-table-with-predicate} filters a table with a
906 @node Minibuffer Completion
907 @subsection Completion and the Minibuffer
908 @cindex minibuffer completion
909 @cindex reading from minibuffer with completion
911 This section describes the basic interface for reading from the
912 minibuffer with completion.
914 @defun completing-read prompt collection &optional predicate require-match initial history default inherit-input-method
915 This function reads a string in the minibuffer, assisting the user by
916 providing completion. It activates the minibuffer with prompt
917 @var{prompt}, which must be a string.
919 The actual completion is done by passing the completion table
920 @var{collection} and the completion predicate @var{predicate} to the
921 function @code{try-completion} (@pxref{Basic Completion}). This
922 happens in certain commands bound in the local keymaps used for
923 completion. Some of these commands also call @code{test-completion}.
924 Thus, if @var{predicate} is non-@code{nil}, it should be compatible
925 with @var{collection} and @code{completion-ignore-case}.
926 @xref{Definition of test-completion}.
928 The value of the optional argument @var{require-match} determines how
929 the user may exit the minibuffer:
933 If @code{nil}, the usual minibuffer exit commands work regardless of
934 the input in the minibuffer.
937 If @code{t}, the usual minibuffer exit commands won't exit unless the
938 input completes to an element of @var{collection}.
941 If @code{confirm}, the user can exit with any input, but is asked for
942 confirmation if the input is not an element of @var{collection}.
945 If @code{confirm-after-completion}, the user can exit with any input,
946 but is asked for confirmation if the preceding command was a
947 completion command (i.e., one of the commands in
948 @code{minibuffer-confirm-exit-commands}) and the resulting input is
949 not an element of @var{collection}. @xref{Completion Commands}.
952 Any other value of @var{require-match} behaves like @code{t}, except
953 that the exit commands won't exit if it performs completion.
956 However, empty input is always permitted, regardless of the value of
957 @var{require-match}; in that case, @code{completing-read} returns the
958 first element of @var{default}, if it is a list; @code{""}, if
959 @var{default} is @code{nil}; or @var{default}. The string or strings
960 in @var{default} are also available to the user through the history
963 The function @code{completing-read} uses
964 @code{minibuffer-local-completion-map} as the keymap if
965 @var{require-match} is @code{nil}, and uses
966 @code{minibuffer-local-must-match-map} if @var{require-match} is
967 non-@code{nil}. @xref{Completion Commands}.
969 The argument @var{history} specifies which history list variable to use for
970 saving the input and for minibuffer history commands. It defaults to
971 @code{minibuffer-history}. @xref{Minibuffer History}.
973 The argument @var{initial} is mostly deprecated; we recommend using a
974 non-@code{nil} value only in conjunction with specifying a cons cell
975 for @var{history}. @xref{Initial Input}. For default input, use
976 @var{default} instead.
978 If the argument @var{inherit-input-method} is non-@code{nil}, then the
979 minibuffer inherits the current input method (@pxref{Input
980 Methods}) and the setting of @code{enable-multibyte-characters}
981 (@pxref{Text Representations}) from whichever buffer was current before
982 entering the minibuffer.
984 If the variable @code{completion-ignore-case} is
985 non-@code{nil}, completion ignores case when comparing the input
986 against the possible matches. @xref{Basic Completion}. In this mode
987 of operation, @var{predicate} must also ignore case, or you will get
990 Here's an example of using @code{completing-read}:
996 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
1001 ;; @r{After evaluation of the preceding expression,}
1002 ;; @r{the following appears in the minibuffer:}
1004 ---------- Buffer: Minibuffer ----------
1005 Complete a foo: fo@point{}
1006 ---------- Buffer: Minibuffer ----------
1011 If the user then types @kbd{@key{DEL} @key{DEL} b @key{RET}},
1012 @code{completing-read} returns @code{barfoo}.
1014 The @code{completing-read} function binds variables to pass
1015 information to the commands that actually do completion.
1016 They are described in the following section.
1019 @defvar completing-read-function
1020 The value of this variable must be a function, which is called by
1021 @code{completing-read} to actually do its work. It should accept the
1022 same arguments as @code{completing-read}. This can be bound to a
1023 different function to completely override the normal behavior of
1024 @code{completing-read}.
1027 @node Completion Commands
1028 @subsection Minibuffer Commands that Do Completion
1030 This section describes the keymaps, commands and user options used
1031 in the minibuffer to do completion.
1033 @defvar minibuffer-completion-table
1034 The value of this variable is the completion table used for completion
1035 in the minibuffer. This is the global variable that contains what
1036 @code{completing-read} passes to @code{try-completion}. It is used by
1037 minibuffer completion commands such as
1038 @code{minibuffer-complete-word}.
1041 @defvar minibuffer-completion-predicate
1042 This variable's value is the predicate that @code{completing-read}
1043 passes to @code{try-completion}. The variable is also used by the other
1044 minibuffer completion functions.
1047 @defvar minibuffer-completion-confirm
1048 This variable determines whether Emacs asks for confirmation before
1049 exiting the minibuffer; @code{completing-read} binds this variable,
1050 and the function @code{minibuffer-complete-and-exit} checks the value
1051 before exiting. If the value is @code{nil}, confirmation is not
1052 required. If the value is @code{confirm}, the user may exit with an
1053 input that is not a valid completion alternative, but Emacs asks for
1054 confirmation. If the value is @code{confirm-after-completion}, the
1055 user may exit with an input that is not a valid completion
1056 alternative, but Emacs asks for confirmation if the user submitted the
1057 input right after any of the completion commands in
1058 @code{minibuffer-confirm-exit-commands}.
1061 @defvar minibuffer-confirm-exit-commands
1062 This variable holds a list of commands that cause Emacs to ask for
1063 confirmation before exiting the minibuffer, if the @var{require-match}
1064 argument to @code{completing-read} is @code{confirm-after-completion}.
1065 The confirmation is requested if the user attempts to exit the
1066 minibuffer immediately after calling any command in this list.
1069 @deffn Command minibuffer-complete-word
1070 This function completes the minibuffer contents by at most a single
1071 word. Even if the minibuffer contents have only one completion,
1072 @code{minibuffer-complete-word} does not add any characters beyond the
1073 first character that is not a word constituent. @xref{Syntax Tables}.
1076 @deffn Command minibuffer-complete
1077 This function completes the minibuffer contents as far as possible.
1080 @deffn Command minibuffer-complete-and-exit
1081 This function completes the minibuffer contents, and exits if
1082 confirmation is not required, i.e., if
1083 @code{minibuffer-completion-confirm} is @code{nil}. If confirmation
1084 @emph{is} required, it is given by repeating this command
1085 immediately---the command is programmed to work without confirmation
1086 when run twice in succession.
1089 @deffn Command minibuffer-completion-help
1090 This function creates a list of the possible completions of the
1091 current minibuffer contents. It works by calling @code{all-completions}
1092 using the value of the variable @code{minibuffer-completion-table} as
1093 the @var{collection} argument, and the value of
1094 @code{minibuffer-completion-predicate} as the @var{predicate} argument.
1095 The list of completions is displayed as text in a buffer named
1096 @file{*Completions*}.
1099 @defun display-completion-list completions &optional common-substring
1100 This function displays @var{completions} to the stream in
1101 @code{standard-output}, usually a buffer. (@xref{Read and Print}, for more
1102 information about streams.) The argument @var{completions} is normally
1103 a list of completions just returned by @code{all-completions}, but it
1104 does not have to be. Each element may be a symbol or a string, either
1105 of which is simply printed. It can also be a list of two strings,
1106 which is printed as if the strings were concatenated. The first of
1107 the two strings is the actual completion, the second string serves as
1110 The argument @var{common-substring} is the prefix that is common to
1111 all the completions. With normal Emacs completion, it is usually the
1112 same as the string that was completed. @code{display-completion-list}
1113 uses this to highlight text in the completion list for better visual
1114 feedback. This is not needed in the minibuffer; for minibuffer
1115 completion, you can pass @code{nil}.
1117 This function is called by @code{minibuffer-completion-help}. A
1118 common way to use it is together with
1119 @code{with-output-to-temp-buffer}, like this:
1122 (with-output-to-temp-buffer "*Completions*"
1123 (display-completion-list
1124 (all-completions (buffer-string) my-alist)
1129 @defopt completion-auto-help
1130 If this variable is non-@code{nil}, the completion commands
1131 automatically display a list of possible completions whenever nothing
1132 can be completed because the next character is not uniquely determined.
1135 @defvar minibuffer-local-completion-map
1136 @code{completing-read} uses this value as the local keymap when an
1137 exact match of one of the completions is not required. By default, this
1138 keymap makes the following bindings:
1142 @code{minibuffer-completion-help}
1145 @code{minibuffer-complete-word}
1148 @code{minibuffer-complete}
1152 and uses @code{minibuffer-local-map} as its parent keymap
1153 (@pxref{Definition of minibuffer-local-map}).
1156 @defvar minibuffer-local-must-match-map
1157 @code{completing-read} uses this value as the local keymap when an
1158 exact match of one of the completions is required. Therefore, no keys
1159 are bound to @code{exit-minibuffer}, the command that exits the
1160 minibuffer unconditionally. By default, this keymap makes the following
1165 @code{minibuffer-complete-and-exit}
1168 @code{minibuffer-complete-and-exit}
1172 and uses @code{minibuffer-local-completion-map} as its parent keymap.
1175 @defvar minibuffer-local-filename-completion-map
1176 This is a sparse keymap that simply unbinds @key{SPC}; because
1177 filenames can contain spaces. The function @code{read-file-name}
1178 combines this keymap with either @code{minibuffer-local-completion-map}
1179 or @code{minibuffer-local-must-match-map}.
1183 @node High-Level Completion
1184 @subsection High-Level Completion Functions
1186 This section describes the higher-level convenience functions for
1187 reading certain sorts of names with completion.
1189 In most cases, you should not call these functions in the middle of a
1190 Lisp function. When possible, do all minibuffer input as part of
1191 reading the arguments for a command, in the @code{interactive}
1192 specification. @xref{Defining Commands}.
1194 @defun read-buffer prompt &optional default require-match
1195 This function reads the name of a buffer and returns it as a string.
1196 The argument @var{default} is the default name to use, the value to
1197 return if the user exits with an empty minibuffer. If non-@code{nil},
1198 it should be a string, a list of strings, or a buffer. If it is
1199 a list, the default value is the first element of this list. It is
1200 mentioned in the prompt, but is not inserted in the minibuffer as
1203 The argument @var{prompt} should be a string ending with a colon and a
1204 space. If @var{default} is non-@code{nil}, the function inserts it in
1205 @var{prompt} before the colon to follow the convention for reading from
1206 the minibuffer with a default value (@pxref{Programming Tips}).
1208 The optional argument @var{require-match} has the same meaning as in
1209 @code{completing-read}. @xref{Minibuffer Completion}.
1211 In the following example, the user enters @samp{minibuffer.t}, and
1212 then types @key{RET}. The argument @var{require-match} is @code{t},
1213 and the only buffer name starting with the given input is
1214 @samp{minibuffer.texi}, so that name is the value.
1217 (read-buffer "Buffer name: " "foo" t)
1219 ;; @r{After evaluation of the preceding expression,}
1220 ;; @r{the following prompt appears,}
1221 ;; @r{with an empty minibuffer:}
1225 ---------- Buffer: Minibuffer ----------
1226 Buffer name (default foo): @point{}
1227 ---------- Buffer: Minibuffer ----------
1231 ;; @r{The user types @kbd{minibuffer.t @key{RET}}.}
1232 @result{} "minibuffer.texi"
1237 @defopt read-buffer-function
1238 This variable, if non-@code{nil}, specifies a function for reading
1239 buffer names. @code{read-buffer} calls this function instead of doing
1240 its usual work, with the same arguments passed to @code{read-buffer}.
1243 @defopt read-buffer-completion-ignore-case
1244 If this variable is non-@code{nil}, @code{read-buffer} ignores case
1245 when performing completion.
1248 @defun read-command prompt &optional default
1249 This function reads the name of a command and returns it as a Lisp
1250 symbol. The argument @var{prompt} is used as in
1251 @code{read-from-minibuffer}. Recall that a command is anything for
1252 which @code{commandp} returns @code{t}, and a command name is a symbol
1253 for which @code{commandp} returns @code{t}. @xref{Interactive Call}.
1255 The argument @var{default} specifies what to return if the user enters
1256 null input. It can be a symbol, a string or a list of strings. If it
1257 is a string, @code{read-command} interns it before returning it.
1258 If it is a list, @code{read-command} interns the first element of this list.
1259 If @var{default} is @code{nil}, that means no default has been
1260 specified; then if the user enters null input, the return value is
1261 @code{(intern "")}, that is, a symbol whose name is an empty string.
1264 (read-command "Command name? ")
1267 ;; @r{After evaluation of the preceding expression,}
1268 ;; @r{the following prompt appears with an empty minibuffer:}
1272 ---------- Buffer: Minibuffer ----------
1274 ---------- Buffer: Minibuffer ----------
1279 If the user types @kbd{forward-c @key{RET}}, then this function returns
1280 @code{forward-char}.
1282 The @code{read-command} function is a simplified interface to
1283 @code{completing-read}. It uses the variable @code{obarray} so as to
1284 complete in the set of extant Lisp symbols, and it uses the
1285 @code{commandp} predicate so as to accept only command names:
1287 @cindex @code{commandp} example
1290 (read-command @var{prompt})
1292 (intern (completing-read @var{prompt} obarray
1298 @defun read-variable prompt &optional default
1299 @anchor{Definition of read-variable}
1300 This function reads the name of a customizable variable and returns it
1301 as a symbol. Its arguments have the same form as those of
1302 @code{read-command}. It behaves just like @code{read-command}, except
1303 that it uses the predicate @code{custom-variable-p} instead of
1307 @deffn Command read-color &optional prompt convert allow-empty display
1308 This function reads a string that is a color specification, either the
1309 color's name or an RGB hex value such as @code{#RRRGGGBBB}. It
1310 prompts with @var{prompt} (default: @code{"Color (name or #RGB triplet):"})
1311 and provides completion for color names, but not for hex RGB values.
1312 In addition to names of standard colors, completion candidates include
1313 the foreground and background colors at point.
1315 Valid RGB values are described in @ref{Color Names}.
1317 The function's return value is the string typed by the user in the
1318 minibuffer. However, when called interactively or if the optional
1319 argument @var{convert} is non-@code{nil}, it converts any input color
1320 name into the corresponding RGB value string and instead returns that.
1321 This function requires a valid color specification to be input.
1322 Empty color names are allowed when @var{allow-empty} is
1323 non-@code{nil} and the user enters null input.
1325 Interactively, or when @var{display} is non-@code{nil}, the return
1326 value is also displayed in the echo area.
1329 See also the functions @code{read-coding-system} and
1330 @code{read-non-nil-coding-system}, in @ref{User-Chosen Coding Systems},
1331 and @code{read-input-method-name}, in @ref{Input Methods}.
1333 @node Reading File Names
1334 @subsection Reading File Names
1335 @cindex read file names
1336 @cindex prompt for file name
1338 The high-level completion functions @code{read-file-name},
1339 @code{read-directory-name}, and @code{read-shell-command} are designed
1340 to read file names, directory names, and shell commands, respectively.
1341 They provide special features, including automatic insertion of the
1344 @defun read-file-name prompt &optional directory default require-match initial predicate
1345 This function reads a file name, prompting with @var{prompt} and
1346 providing completion.
1348 As an exception, this function reads a file name using a graphical
1349 file dialog instead of the minibuffer, if all of the following are
1354 It is invoked via a mouse command.
1357 The selected frame is on a graphical display supporting such dialogs.
1360 The variable @code{use-dialog-box} is non-@code{nil}.
1361 @xref{Dialog Boxes,, Dialog Boxes, emacs, The GNU Emacs Manual}.
1364 The @var{directory} argument, described below, does not specify a
1365 remote file. @xref{Remote Files,, Remote Files, emacs, The GNU Emacs Manual}.
1369 The exact behavior when using a graphical file dialog is
1370 platform-dependent. Here, we simply document the behavior when using
1373 @code{read-file-name} does not automatically expand the returned file
1374 name. You must call @code{expand-file-name} yourself if an absolute
1375 file name is required.
1377 The optional argument @var{require-match} has the same meaning as in
1378 @code{completing-read}. @xref{Minibuffer Completion}.
1380 The argument @var{directory} specifies the directory to use for
1381 completing relative file names. It should be an absolute directory
1382 name. If the variable @code{insert-default-directory} is non-@code{nil},
1383 @var{directory} is also inserted in the minibuffer as initial input.
1384 It defaults to the current buffer's value of @code{default-directory}.
1386 If you specify @var{initial}, that is an initial file name to insert
1387 in the buffer (after @var{directory}, if that is inserted). In this
1388 case, point goes at the beginning of @var{initial}. The default for
1389 @var{initial} is @code{nil}---don't insert any file name. To see what
1390 @var{initial} does, try the command @kbd{C-x C-v} in a buffer visiting
1391 a file. @strong{Please note:} we recommend using @var{default} rather
1392 than @var{initial} in most cases.
1394 If @var{default} is non-@code{nil}, then the function returns
1395 @var{default} if the user exits the minibuffer with the same non-empty
1396 contents that @code{read-file-name} inserted initially. The initial
1397 minibuffer contents are always non-empty if
1398 @code{insert-default-directory} is non-@code{nil}, as it is by
1399 default. @var{default} is not checked for validity, regardless of the
1400 value of @var{require-match}. However, if @var{require-match} is
1401 non-@code{nil}, the initial minibuffer contents should be a valid file
1402 (or directory) name. Otherwise @code{read-file-name} attempts
1403 completion if the user exits without any editing, and does not return
1404 @var{default}. @var{default} is also available through the history
1407 If @var{default} is @code{nil}, @code{read-file-name} tries to find a
1408 substitute default to use in its place, which it treats in exactly the
1409 same way as if it had been specified explicitly. If @var{default} is
1410 @code{nil}, but @var{initial} is non-@code{nil}, then the default is
1411 the absolute file name obtained from @var{directory} and
1412 @var{initial}. If both @var{default} and @var{initial} are @code{nil}
1413 and the buffer is visiting a file, @code{read-file-name} uses the
1414 absolute file name of that file as default. If the buffer is not
1415 visiting a file, then there is no default. In that case, if the user
1416 types @key{RET} without any editing, @code{read-file-name} simply
1417 returns the pre-inserted contents of the minibuffer.
1419 If the user types @key{RET} in an empty minibuffer, this function
1420 returns an empty string, regardless of the value of
1421 @var{require-match}. This is, for instance, how the user can make the
1422 current buffer visit no file using @kbd{M-x set-visited-file-name}.
1424 If @var{predicate} is non-@code{nil}, it specifies a function of one
1425 argument that decides which file names are acceptable completion
1426 alternatives. A file name is an acceptable value if @var{predicate}
1427 returns non-@code{nil} for it.
1429 Here is an example of using @code{read-file-name}:
1433 (read-file-name "The file is ")
1435 ;; @r{After evaluation of the preceding expression,}
1436 ;; @r{the following appears in the minibuffer:}
1440 ---------- Buffer: Minibuffer ----------
1441 The file is /gp/gnu/elisp/@point{}
1442 ---------- Buffer: Minibuffer ----------
1447 Typing @kbd{manual @key{TAB}} results in the following:
1451 ---------- Buffer: Minibuffer ----------
1452 The file is /gp/gnu/elisp/manual.texi@point{}
1453 ---------- Buffer: Minibuffer ----------
1457 @c Wordy to avoid overfull hbox in smallbook mode.
1459 If the user types @key{RET}, @code{read-file-name} returns the file name
1460 as the string @code{"/gp/gnu/elisp/manual.texi"}.
1463 @defvar read-file-name-function
1464 If non-@code{nil}, this should be a function that accepts the same
1465 arguments as @code{read-file-name}. When @code{read-file-name} is
1466 called, it calls this function with the supplied arguments instead of
1467 doing its usual work.
1470 @defopt read-file-name-completion-ignore-case
1471 If this variable is non-@code{nil}, @code{read-file-name} ignores case
1472 when performing completion.
1475 @defun read-directory-name prompt &optional directory default require-match initial
1476 This function is like @code{read-file-name} but allows only directory
1477 names as completion alternatives.
1479 If @var{default} is @code{nil} and @var{initial} is non-@code{nil},
1480 @code{read-directory-name} constructs a substitute default by
1481 combining @var{directory} (or the current buffer's default directory
1482 if @var{directory} is @code{nil}) and @var{initial}. If both
1483 @var{default} and @var{initial} are @code{nil}, this function uses
1484 @var{directory} as substitute default, or the current buffer's default
1485 directory if @var{directory} is @code{nil}.
1488 @defopt insert-default-directory
1489 This variable is used by @code{read-file-name}, and thus, indirectly,
1490 by most commands reading file names. (This includes all commands that
1491 use the code letters @samp{f} or @samp{F} in their interactive form.
1492 @xref{Interactive Codes,, Code Characters for interactive}.) Its
1493 value controls whether @code{read-file-name} starts by placing the
1494 name of the default directory in the minibuffer, plus the initial file
1495 name, if any. If the value of this variable is @code{nil}, then
1496 @code{read-file-name} does not place any initial input in the
1497 minibuffer (unless you specify initial input with the @var{initial}
1498 argument). In that case, the default directory is still used for
1499 completion of relative file names, but is not displayed.
1501 If this variable is @code{nil} and the initial minibuffer contents are
1502 empty, the user may have to explicitly fetch the next history element
1503 to access a default value. If the variable is non-@code{nil}, the
1504 initial minibuffer contents are always non-empty and the user can
1505 always request a default value by immediately typing @key{RET} in an
1506 unedited minibuffer. (See above.)
1512 ;; @r{Here the minibuffer starts out with the default directory.}
1513 (let ((insert-default-directory t))
1514 (read-file-name "The file is "))
1518 ---------- Buffer: Minibuffer ----------
1519 The file is ~lewis/manual/@point{}
1520 ---------- Buffer: Minibuffer ----------
1524 ;; @r{Here the minibuffer is empty and only the prompt}
1525 ;; @r{appears on its line.}
1526 (let ((insert-default-directory nil))
1527 (read-file-name "The file is "))
1531 ---------- Buffer: Minibuffer ----------
1532 The file is @point{}
1533 ---------- Buffer: Minibuffer ----------
1538 @defun read-shell-command prompt &optional initial history &rest args
1539 This function reads a shell command from the minibuffer, prompting
1540 with @var{prompt} and providing intelligent completion. It completes
1541 the first word of the command using candidates that are appropriate
1542 for command names, and the rest of the command words as file names.
1544 This function uses @code{minibuffer-local-shell-command-map} as the
1545 keymap for minibuffer input. The @var{history} argument specifies the
1546 history list to use; if is omitted or @code{nil}, it defaults to
1547 @code{shell-command-history} (@pxref{Minibuffer History,
1548 shell-command-history}). The optional argument @var{initial}
1549 specifies the initial content of the minibuffer (@pxref{Initial
1550 Input}). The rest of @var{args}, if present, are used as the
1551 @var{default} and @var{inherit-input-method} arguments in
1552 @code{read-from-minibuffer} (@pxref{Text from Minibuffer}).
1555 @defvar minibuffer-local-shell-command-map
1556 This keymap is used by @code{read-shell-command} for completing
1557 command and file names that are part of a shell command. It uses
1558 @code{minibuffer-local-map} as its parent keymap, and binds @key{TAB}
1559 to @code{completion-at-point}.
1562 @node Completion Variables
1563 @subsection Completion Variables
1565 Here are some variables that can be used to alter the default
1566 completion behavior.
1568 @cindex completion styles
1569 @defopt completion-styles
1570 The value of this variable is a list of completion style (symbols) to
1571 use for performing completion. A @dfn{completion style} is a set of
1572 rules for generating completions. Each symbol occurring this list
1573 must have a corresponding entry in @code{completion-styles-alist}.
1576 @defvar completion-styles-alist
1577 This variable stores a list of available completion styles. Each
1578 element in the list has the form
1581 (@var{style} @var{try-completion} @var{all-completions} @var{doc})
1585 Here, @var{style} is the name of the completion style (a symbol),
1586 which may be used in the @code{completion-styles} variable to refer to
1587 this style; @var{try-completion} is the function that does the
1588 completion; @var{all-completions} is the function that lists the
1589 completions; and @var{doc} is a string describing the completion
1592 The @var{try-completion} and @var{all-completions} functions should
1593 each accept four arguments: @var{string}, @var{collection},
1594 @var{predicate}, and @var{point}. The @var{string}, @var{collection},
1595 and @var{predicate} arguments have the same meanings as in
1596 @code{try-completion} (@pxref{Basic Completion}), and the @var{point}
1597 argument is the position of point within @var{string}. Each function
1598 should return a non-@code{nil} value if it performed its job, and
1599 @code{nil} if it did not (e.g.@: if there is no way to complete
1600 @var{string} according to the completion style).
1602 When the user calls a completion command like
1603 @code{minibuffer-complete} (@pxref{Completion Commands}), Emacs looks
1604 for the first style listed in @code{completion-styles} and calls its
1605 @var{try-completion} function. If this function returns @code{nil},
1606 Emacs moves to the next listed completion style and calls its
1607 @var{try-completion} function, and so on until one of the
1608 @var{try-completion} functions successfully performs completion and
1609 returns a non-@code{nil} value. A similar procedure is used for
1610 listing completions, via the @var{all-completions} functions.
1612 @xref{Completion Styles,,, emacs, The GNU Emacs Manual}, for a
1613 description of the available completion styles.
1616 @defopt completion-category-overrides
1617 This variable specifies special completion styles and other completion
1618 behaviors to use when completing certain types of text. Its value
1619 should be an alist with elements of the form @code{(@var{category}
1620 . @var{alist})}. @var{category} is a symbol describing what is being
1621 completed; currently, the @code{buffer}, @code{file}, and
1622 @code{unicode-name} categories are defined, but others can be defined
1623 via specialized completion functions (@pxref{Programmed Completion}).
1624 @var{alist} is an association list describing how completion should
1625 behave for the corresponding category. The following alist keys are
1630 The value should be a list of completion styles (symbols).
1633 The value should be a value for @code{completion-cycle-threshold}
1634 (@pxref{Completion Options,,, emacs, The GNU Emacs Manual}) for this
1639 Additional alist entries may be defined in the future.
1642 @defvar completion-extra-properties
1643 This variable is used to specify extra properties of the current
1644 completion command. It is intended to be let-bound by specialized
1645 completion commands. Its value should be a list of property and value
1646 pairs. The following properties are supported:
1649 @item :annotation-function
1650 The value should be a function to add annotations in the completions
1651 buffer. This function must accept one argument, a completion, and
1652 should either return @code{nil} or a string to be displayed next to
1655 @item :exit-function
1656 The value should be a function to run after performing completion.
1657 The function should accept two arguments, @var{string} and
1658 @var{status}, where @var{string} is the text to which the field was
1659 completed, and @var{status} indicates what kind of operation happened:
1660 @code{finished} if text is now complete, @code{sole} if the text
1661 cannot be further completed but completion is not finished, or
1662 @code{exact} if the text is a valid completion but may be further
1667 @node Programmed Completion
1668 @subsection Programmed Completion
1669 @cindex programmed completion
1671 Sometimes it is not possible or convenient to create an alist or
1672 an obarray containing all the intended possible completions ahead
1673 of time. In such a case, you can supply your own function to compute
1674 the completion of a given string. This is called @dfn{programmed
1675 completion}. Emacs uses programmed completion when completing file
1676 names (@pxref{File Name Completion}), among many other cases.
1678 To use this feature, pass a function as the @var{collection}
1679 argument to @code{completing-read}. The function
1680 @code{completing-read} arranges to pass your completion function along
1681 to @code{try-completion}, @code{all-completions}, and other basic
1682 completion functions, which will then let your function do all
1685 The completion function should accept three arguments:
1689 The string to be completed.
1692 A predicate function with which to filter possible matches, or
1693 @code{nil} if none. The function should call the predicate for each
1694 possible match, and ignore the match if the predicate returns
1698 A flag specifying the type of completion operation to perform. This
1699 is one of the following four values:
1703 This specifies a @code{try-completion} operation. The function should
1704 return @code{t} if the specified string is a unique and exact match;
1705 if there is more than one match, it should return the common substring
1706 of all matches (if the string is an exact match for one completion
1707 alternative but also matches other longer alternatives, the return
1708 value is the string); if there are no matches, it should return
1712 This specifies an @code{all-completions} operation. The function
1713 should return a list of all possible completions of the specified
1717 This specifies a @code{test-completion} operation. The function
1718 should return @code{t} if the specified string is an exact match for
1719 some completion alternative; @code{nil} otherwise.
1721 @item (boundaries . @var{suffix})
1722 This specifies a @code{completion-boundaries} operation. The function
1723 should return @code{(boundaries @var{start} . @var{end})}, where
1724 @var{start} is the position of the beginning boundary in the specified
1725 string, and @var{end} is the position of the end boundary in
1729 This specifies a request for information about the state of the
1730 current completion. The return value should have the form
1731 @code{(metadata . @var{alist})}, where @var{alist} is an alist whose
1732 elements are described below.
1736 If the flag has any other value, the completion function should return
1740 The following is a list of metadata entries that a completion function
1741 may return in response to a @code{metadata} flag argument:
1745 The value should be a symbol describing what kind of text the
1746 completion function is trying to complete. If the symbol matches one
1747 of the keys in @code{completion-category-overrides}, the usual
1748 completion behavior is overridden. @xref{Completion Variables}.
1750 @item annotation-function
1751 The value should be a function for @dfn{annotating} completions. The
1752 function should take one argument, @var{string}, which is a possible
1753 completion. It should return a string, which is displayed after the
1754 completion @var{string} in the @file{*Completions*} buffer.
1756 @item display-sort-function
1757 The value should be a function for sorting completions. The function
1758 should take one argument, a list of completion strings, and return a
1759 sorted list of completion strings. It is allowed to alter the input
1762 @item cycle-sort-function
1763 The value should be a function for sorting completions, when
1764 @code{completion-cycle-threshold} is non-@code{nil} and the user is
1765 cycling through completion alternatives. @xref{Completion Options,,,
1766 emacs, The GNU Emacs Manual}. Its argument list and return value are
1767 the same as for @code{display-sort-function}.
1770 @defun completion-table-dynamic function
1771 This function is a convenient way to write a function that can act as
1772 a programmed completion function. The argument @var{function} should be
1773 a function that takes one argument, a string, and returns an alist of
1774 possible completions of it. You can think of
1775 @code{completion-table-dynamic} as a transducer between that interface
1776 and the interface for programmed completion functions.
1779 @node Completion in Buffers
1780 @subsection Completion in Ordinary Buffers
1781 @cindex inline completion
1783 @findex completion-at-point
1784 Although completion is usually done in the minibuffer, the
1785 completion facility can also be used on the text in ordinary Emacs
1786 buffers. In many major modes, in-buffer completion is performed by
1787 the @kbd{C-M-i} or @kbd{M-@key{TAB}} command, bound to
1788 @code{completion-at-point}. @xref{Symbol Completion,,, emacs, The GNU
1789 Emacs Manual}. This command uses the abnormal hook variable
1790 @code{completion-at-point-functions}:
1792 @defvar completion-at-point-functions
1793 The value of this abnormal hook should be a list of functions, which
1794 are used to compute a completion table for completing the text at
1795 point. It can be used by major modes to provide mode-specific
1796 completion tables (@pxref{Major Mode Conventions}).
1798 When the command @code{completion-at-point} runs, it calls the
1799 functions in the list one by one, without any argument. Each function
1800 should return @code{nil} if it is unable to produce a completion table
1801 for the text at point. Otherwise it should return a list of the form
1804 (@var{start} @var{end} @var{collection} . @var{props})
1808 @var{start} and @var{end} delimit the text to complete (which should
1809 enclose point). @var{collection} is a completion table for completing
1810 that text, in a form suitable for passing as the second argument to
1811 @code{try-completion} (@pxref{Basic Completion}); completion
1812 alternatives will be generated from this completion table in the usual
1813 way, via the completion styles defined in @code{completion-styles}
1814 (@pxref{Completion Variables}). @var{props} is a property list for
1815 additional information; any of the properties in
1816 @code{completion-extra-properties} are recognized (@pxref{Completion
1817 Variables}), as well as the following additional ones:
1821 The value should be a predicate that completion candidates need to
1825 If the value is @code{no}, then if the completion table fails to match
1826 the text at point, @code{completion-at-point} moves on to the
1827 next function in @code{completion-at-point-functions} instead of
1828 reporting a completion failure.
1831 A function in @code{completion-at-point-functions} may also return a
1832 function. In that case, that returned function is called, with no
1833 argument, and it is entirely responsible for performing the
1834 completion. We discourage this usage; it is intended to help convert
1835 old code to using @code{completion-at-point}.
1837 The first function in @code{completion-at-point-functions} to return a
1838 non-@code{nil} value is used by @code{completion-at-point}. The
1839 remaining functions are not called. The exception to this is when
1840 there is an @code{:exclusive} specification, as described above.
1843 The following function provides a convenient way to perform
1844 completion on an arbitrary stretch of text in an Emacs buffer:
1846 @defun completion-in-region start end collection &optional predicate
1847 This function completes the text in the current buffer between the
1848 positions @var{start} and @var{end}, using @var{collection}. The
1849 argument @var{collection} has the same meaning as in
1850 @code{try-completion} (@pxref{Basic Completion}).
1852 This function inserts the completion text directly into the current
1853 buffer. Unlike @code{completing-read} (@pxref{Minibuffer
1854 Completion}), it does not activate the minibuffer.
1856 For this function to work, point must be somewhere between @var{start}
1861 @node Yes-or-No Queries
1862 @section Yes-or-No Queries
1863 @cindex asking the user questions
1864 @cindex querying the user
1865 @cindex yes-or-no questions
1867 This section describes functions used to ask the user a yes-or-no
1868 question. The function @code{y-or-n-p} can be answered with a single
1869 character; it is useful for questions where an inadvertent wrong answer
1870 will not have serious consequences. @code{yes-or-no-p} is suitable for
1871 more momentous questions, since it requires three or four characters to
1874 If either of these functions is called in a command that was invoked
1875 using the mouse---more precisely, if @code{last-nonmenu-event}
1876 (@pxref{Command Loop Info}) is either @code{nil} or a list---then it
1877 uses a dialog box or pop-up menu to ask the question. Otherwise, it
1878 uses keyboard input. You can force use either of the mouse or of keyboard
1879 input by binding @code{last-nonmenu-event} to a suitable value around
1882 Strictly speaking, @code{yes-or-no-p} uses the minibuffer and
1883 @code{y-or-n-p} does not; but it seems best to describe them together.
1885 @defun y-or-n-p prompt
1886 This function asks the user a question, expecting input in the echo
1887 area. It returns @code{t} if the user types @kbd{y}, @code{nil} if the
1888 user types @kbd{n}. This function also accepts @key{SPC} to mean yes
1889 and @key{DEL} to mean no. It accepts @kbd{C-]} to mean ``quit'', like
1890 @kbd{C-g}, because the question might look like a minibuffer and for
1891 that reason the user might try to use @kbd{C-]} to get out. The answer
1892 is a single character, with no @key{RET} needed to terminate it. Upper
1893 and lower case are equivalent.
1895 ``Asking the question'' means printing @var{prompt} in the echo area,
1896 followed by the string @w{@samp{(y or n) }}. If the input is not one of
1897 the expected answers (@kbd{y}, @kbd{n}, @kbd{@key{SPC}},
1898 @kbd{@key{DEL}}, or something that quits), the function responds
1899 @samp{Please answer y or n.}, and repeats the request.
1901 This function does not actually use the minibuffer, since it does not
1902 allow editing of the answer. It actually uses the echo area (@pxref{The
1903 Echo Area}), which uses the same screen space as the minibuffer. The
1904 cursor moves to the echo area while the question is being asked.
1906 The answers and their meanings, even @samp{y} and @samp{n}, are not
1907 hardwired, and are specified by the keymap @code{query-replace-map}
1908 (@pxref{Search and Replace}). In particular, if the user enters the
1909 special responses @code{recenter}, @code{scroll-up},
1910 @code{scroll-down}, @code{scroll-other-window}, or
1911 @code{scroll-other-window-down} (respectively bound to @kbd{C-l},
1912 @kbd{C-v}, @kbd{M-v}, @kbd{C-M-v} and @kbd{C-M-S-v} in
1913 @code{query-replace-map}), this function performs the specified window
1914 recentering or scrolling operation, and poses the question again.
1917 We show successive lines of echo area messages, but only one actually
1918 appears on the screen at a time.
1921 @defun y-or-n-p-with-timeout prompt seconds default
1922 Like @code{y-or-n-p}, except that if the user fails to answer within
1923 @var{seconds} seconds, this function stops waiting and returns
1924 @var{default}. It works by setting up a timer; see @ref{Timers}.
1925 The argument @var{seconds} may be an integer or a floating point number.
1928 @defun yes-or-no-p prompt
1929 This function asks the user a question, expecting input in the
1930 minibuffer. It returns @code{t} if the user enters @samp{yes},
1931 @code{nil} if the user types @samp{no}. The user must type @key{RET} to
1932 finalize the response. Upper and lower case are equivalent.
1934 @code{yes-or-no-p} starts by displaying @var{prompt} in the echo area,
1935 followed by @w{@samp{(yes or no) }}. The user must type one of the
1936 expected responses; otherwise, the function responds @samp{Please answer
1937 yes or no.}, waits about two seconds and repeats the request.
1939 @code{yes-or-no-p} requires more work from the user than
1940 @code{y-or-n-p} and is appropriate for more crucial decisions.
1946 (yes-or-no-p "Do you really want to remove everything? ")
1948 ;; @r{After evaluation of the preceding expression,}
1949 ;; @r{the following prompt appears,}
1950 ;; @r{with an empty minibuffer:}
1954 ---------- Buffer: minibuffer ----------
1955 Do you really want to remove everything? (yes or no)
1956 ---------- Buffer: minibuffer ----------
1961 If the user first types @kbd{y @key{RET}}, which is invalid because this
1962 function demands the entire word @samp{yes}, it responds by displaying
1963 these prompts, with a brief pause between them:
1967 ---------- Buffer: minibuffer ----------
1968 Please answer yes or no.
1969 Do you really want to remove everything? (yes or no)
1970 ---------- Buffer: minibuffer ----------
1975 @node Multiple Queries
1976 @section Asking Multiple Y-or-N Questions
1978 When you have a series of similar questions to ask, such as ``Do you
1979 want to save this buffer'' for each buffer in turn, you should use
1980 @code{map-y-or-n-p} to ask the collection of questions, rather than
1981 asking each question individually. This gives the user certain
1982 convenient facilities such as the ability to answer the whole series at
1985 @defun map-y-or-n-p prompter actor list &optional help action-alist no-cursor-in-echo-area
1986 This function asks the user a series of questions, reading a
1987 single-character answer in the echo area for each one.
1989 The value of @var{list} specifies the objects to ask questions about.
1990 It should be either a list of objects or a generator function. If it is
1991 a function, it should expect no arguments, and should return either the
1992 next object to ask about, or @code{nil}, meaning to stop asking questions.
1994 The argument @var{prompter} specifies how to ask each question. If
1995 @var{prompter} is a string, the question text is computed like this:
1998 (format @var{prompter} @var{object})
2002 where @var{object} is the next object to ask about (as obtained from
2005 If not a string, @var{prompter} should be a function of one argument
2006 (the next object to ask about) and should return the question text. If
2007 the value is a string, that is the question to ask the user. The
2008 function can also return @code{t}, meaning do act on this object (and
2009 don't ask the user), or @code{nil}, meaning ignore this object (and don't
2012 The argument @var{actor} says how to act on the answers that the user
2013 gives. It should be a function of one argument, and it is called with
2014 each object that the user says yes for. Its argument is always an
2015 object obtained from @var{list}.
2017 If the argument @var{help} is given, it should be a list of this form:
2020 (@var{singular} @var{plural} @var{action})
2024 where @var{singular} is a string containing a singular noun that
2025 describes the objects conceptually being acted on, @var{plural} is the
2026 corresponding plural noun, and @var{action} is a transitive verb
2027 describing what @var{actor} does.
2029 If you don't specify @var{help}, the default is @code{("object"
2030 "objects" "act on")}.
2032 Each time a question is asked, the user may enter @kbd{y}, @kbd{Y}, or
2033 @key{SPC} to act on that object; @kbd{n}, @kbd{N}, or @key{DEL} to skip
2034 that object; @kbd{!} to act on all following objects; @key{ESC} or
2035 @kbd{q} to exit (skip all following objects); @kbd{.} (period) to act on
2036 the current object and then exit; or @kbd{C-h} to get help. These are
2037 the same answers that @code{query-replace} accepts. The keymap
2038 @code{query-replace-map} defines their meaning for @code{map-y-or-n-p}
2039 as well as for @code{query-replace}; see @ref{Search and Replace}.
2041 You can use @var{action-alist} to specify additional possible answers
2042 and what they mean. It is an alist of elements of the form
2043 @code{(@var{char} @var{function} @var{help})}, each of which defines one
2044 additional answer. In this element, @var{char} is a character (the
2045 answer); @var{function} is a function of one argument (an object from
2046 @var{list}); @var{help} is a string.
2048 When the user responds with @var{char}, @code{map-y-or-n-p} calls
2049 @var{function}. If it returns non-@code{nil}, the object is considered
2050 ``acted upon'', and @code{map-y-or-n-p} advances to the next object in
2051 @var{list}. If it returns @code{nil}, the prompt is repeated for the
2054 Normally, @code{map-y-or-n-p} binds @code{cursor-in-echo-area} while
2055 prompting. But if @var{no-cursor-in-echo-area} is non-@code{nil}, it
2058 If @code{map-y-or-n-p} is called in a command that was invoked using the
2059 mouse---more precisely, if @code{last-nonmenu-event} (@pxref{Command
2060 Loop Info}) is either @code{nil} or a list---then it uses a dialog box
2061 or pop-up menu to ask the question. In this case, it does not use
2062 keyboard input or the echo area. You can force use either of the mouse or
2063 of keyboard input by binding @code{last-nonmenu-event} to a suitable
2064 value around the call.
2066 The return value of @code{map-y-or-n-p} is the number of objects acted on.
2068 @c FIXME An example of this would be more useful than all the
2069 @c preceding examples of simple things.
2071 @node Reading a Password
2072 @section Reading a Password
2073 @cindex passwords, reading
2075 To read a password to pass to another program, you can use the
2076 function @code{read-passwd}.
2078 @defun read-passwd prompt &optional confirm default
2079 This function reads a password, prompting with @var{prompt}. It does
2080 not echo the password as the user types it; instead, it echoes @samp{.}
2081 for each character in the password.
2083 The optional argument @var{confirm}, if non-@code{nil}, says to read the
2084 password twice and insist it must be the same both times. If it isn't
2085 the same, the user has to type it over and over until the last two
2088 The optional argument @var{default} specifies the default password to
2089 return if the user enters empty input. If @var{default} is @code{nil},
2090 then @code{read-passwd} returns the null string in that case.
2093 @node Minibuffer Commands
2094 @section Minibuffer Commands
2096 This section describes some commands meant for use in the
2099 @deffn Command exit-minibuffer
2100 This command exits the active minibuffer. It is normally bound to
2101 keys in minibuffer local keymaps.
2104 @deffn Command self-insert-and-exit
2105 This command exits the active minibuffer after inserting the last
2106 character typed on the keyboard (found in @code{last-command-event};
2107 @pxref{Command Loop Info}).
2110 @deffn Command previous-history-element n
2111 This command replaces the minibuffer contents with the value of the
2112 @var{n}th previous (older) history element.
2115 @deffn Command next-history-element n
2116 This command replaces the minibuffer contents with the value of the
2117 @var{n}th more recent history element.
2120 @deffn Command previous-matching-history-element pattern n
2121 This command replaces the minibuffer contents with the value of the
2122 @var{n}th previous (older) history element that matches @var{pattern} (a
2123 regular expression).
2126 @deffn Command next-matching-history-element pattern n
2127 This command replaces the minibuffer contents with the value of the
2128 @var{n}th next (newer) history element that matches @var{pattern} (a
2129 regular expression).
2132 @deffn Command previous-complete-history-element n
2133 This command replaces the minibuffer contents with the value of the
2134 @var{n}th previous (older) history element that completes the current
2135 contents of the minibuffer before the point.
2138 @deffn Command next-complete-history-element n
2139 This command replaces the minibuffer contents with the value of the
2140 @var{n}th next (newer) history element that completes the current
2141 contents of the minibuffer before the point.
2145 @node Minibuffer Windows
2146 @section Minibuffer Windows
2147 @cindex minibuffer windows
2149 These functions access and select minibuffer windows
2150 and test whether they are active.
2152 @defun active-minibuffer-window
2153 This function returns the currently active minibuffer window, or
2154 @code{nil} if there is none.
2157 @defun minibuffer-window &optional frame
2158 @anchor{Definition of minibuffer-window}
2159 This function returns the minibuffer window used for frame @var{frame}.
2160 If @var{frame} is @code{nil}, that stands for the current frame. Note
2161 that the minibuffer window used by a frame need not be part of that
2162 frame---a frame that has no minibuffer of its own necessarily uses some
2163 other frame's minibuffer window.
2166 @defun set-minibuffer-window window
2167 This function specifies @var{window} as the minibuffer window to use.
2168 This affects where the minibuffer is displayed if you put text in it
2169 without invoking the usual minibuffer commands. It has no effect on
2170 the usual minibuffer input functions because they all start by
2171 choosing the minibuffer window according to the current frame.
2175 @defun window-minibuffer-p &optional window
2176 This function returns non-@code{nil} if @var{window} is a minibuffer
2178 @var{window} defaults to the selected window.
2181 It is not correct to determine whether a given window is a minibuffer by
2182 comparing it with the result of @code{(minibuffer-window)}, because
2183 there can be more than one minibuffer window if there is more than one
2186 @defun minibuffer-window-active-p window
2187 This function returns non-@code{nil} if @var{window} is the currently
2188 active minibuffer window.
2191 @node Minibuffer Contents
2192 @section Minibuffer Contents
2194 These functions access the minibuffer prompt and contents.
2196 @defun minibuffer-prompt
2197 This function returns the prompt string of the currently active
2198 minibuffer. If no minibuffer is active, it returns @code{nil}.
2201 @defun minibuffer-prompt-end
2202 This function returns the current
2203 position of the end of the minibuffer prompt, if a minibuffer is
2204 current. Otherwise, it returns the minimum valid buffer position.
2207 @defun minibuffer-prompt-width
2208 This function returns the current display-width of the minibuffer
2209 prompt, if a minibuffer is current. Otherwise, it returns zero.
2212 @defun minibuffer-contents
2213 This function returns the editable
2214 contents of the minibuffer (that is, everything except the prompt) as
2215 a string, if a minibuffer is current. Otherwise, it returns the
2216 entire contents of the current buffer.
2219 @defun minibuffer-contents-no-properties
2220 This is like @code{minibuffer-contents}, except that it does not copy text
2221 properties, just the characters themselves. @xref{Text Properties}.
2224 @defun minibuffer-completion-contents
2225 This is like @code{minibuffer-contents}, except that it returns only
2226 the contents before point. That is the part that completion commands
2227 operate on. @xref{Minibuffer Completion}.
2230 @defun delete-minibuffer-contents
2231 This function erases the editable contents of the minibuffer (that is,
2232 everything except the prompt), if a minibuffer is current. Otherwise,
2233 it erases the entire current buffer.
2236 @node Recursive Mini
2237 @section Recursive Minibuffers
2238 @cindex recursive minibuffers
2240 These functions and variables deal with recursive minibuffers
2241 (@pxref{Recursive Editing}):
2243 @defun minibuffer-depth
2244 This function returns the current depth of activations of the
2245 minibuffer, a nonnegative integer. If no minibuffers are active, it
2249 @defopt enable-recursive-minibuffers
2250 If this variable is non-@code{nil}, you can invoke commands (such as
2251 @code{find-file}) that use minibuffers even while the minibuffer window
2252 is active. Such invocation produces a recursive editing level for a new
2253 minibuffer. The outer-level minibuffer is invisible while you are
2254 editing the inner one.
2256 If this variable is @code{nil}, you cannot invoke minibuffer
2257 commands when the minibuffer window is active, not even if you switch to
2258 another window to do it.
2262 If a command name has a property @code{enable-recursive-minibuffers}
2263 that is non-@code{nil}, then the command can use the minibuffer to read
2264 arguments even if it is invoked from the minibuffer. A command can
2265 also achieve this by binding @code{enable-recursive-minibuffers}
2266 to @code{t} in the interactive declaration (@pxref{Using Interactive}).
2267 The minibuffer command @code{next-matching-history-element} (normally
2268 @kbd{M-s} in the minibuffer) does the latter.
2270 @node Minibuffer Misc
2271 @section Minibuffer Miscellany
2273 @defun minibufferp &optional buffer-or-name
2274 This function returns non-@code{nil} if @var{buffer-or-name} is a
2275 minibuffer. If @var{buffer-or-name} is omitted, it tests the current
2279 @defvar minibuffer-setup-hook
2280 This is a normal hook that is run whenever the minibuffer is entered.
2284 @defvar minibuffer-exit-hook
2285 This is a normal hook that is run whenever the minibuffer is exited.
2289 @defvar minibuffer-help-form
2290 @anchor{Definition of minibuffer-help-form}
2291 The current value of this variable is used to rebind @code{help-form}
2292 locally inside the minibuffer (@pxref{Help Functions}).
2295 @defvar minibuffer-scroll-window
2296 @anchor{Definition of minibuffer-scroll-window}
2297 If the value of this variable is non-@code{nil}, it should be a window
2298 object. When the function @code{scroll-other-window} is called in the
2299 minibuffer, it scrolls this window.
2302 @defun minibuffer-selected-window
2303 This function returns the window that was selected when the
2304 minibuffer was entered. If selected window is not a minibuffer
2305 window, it returns @code{nil}.
2308 @defopt max-mini-window-height
2309 This variable specifies the maximum height for resizing minibuffer
2310 windows. If a float, it specifies a fraction of the height of the
2311 frame. If an integer, it specifies a number of lines.
2314 @vindex minibuffer-message-timeout
2315 @defun minibuffer-message string &rest args
2316 This function displays @var{string} temporarily at the end of the
2317 minibuffer text, for a few seconds, or until the next input event
2318 arrives, whichever comes first. The variable
2319 @code{minibuffer-message-timeout} specifies the number of seconds to
2320 wait in the absence of input. It defaults to 2. If @var{args} is
2321 non-@code{nil}, the actual message is obtained by passing @var{string}
2322 and @var{args} through @code{format}. @xref{Formatting Strings}.
2325 @deffn Command minibuffer-inactive-mode
2326 This is the major mode used in inactive minibuffers. It uses
2327 keymap @code{minibuffer-inactive-mode-map}. This can be useful
2328 if the minibuffer is in a separate frame. @xref{Minibuffers and Frames}.