@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999,
-@c 2001, 2004
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, 2002,
+@c 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/minibuf
@node Minibuffers, Command Loop, Read and Print, Top
@cindex complex arguments
@cindex minibuffer
- A @dfn{minibuffer} is a special buffer that Emacs commands use to read
-arguments more complicated than the single numeric prefix argument.
-These arguments include file names, buffer names, and command names (as
-in @kbd{M-x}). The minibuffer is displayed on the bottom line of the
-frame, in the same place as the echo area, but only while it is in use
-for reading an argument.
+ A @dfn{minibuffer} is a special buffer that Emacs commands use to
+read arguments more complicated than the single numeric prefix
+argument. These arguments include file names, buffer names, and
+command names (as in @kbd{M-x}). The minibuffer is displayed on the
+bottom line of the frame, in the same place as the echo area
+(@pxref{The Echo Area}), but only while it is in use for reading an
+argument.
@menu
* Intro to Minibuffers:: Basic information about minibuffers.
* Yes-or-No Queries:: Asking a question with a simple answer.
* Multiple Queries:: Asking a series of similar questions.
* Reading a Password:: Reading a password from the terminal.
+* Minibuffer Commands:: Commands used as key bindings in minibuffers.
+* Minibuffer Contents:: How such commands access the minibuffer text.
+* Minibuffer Windows:: Operating on the special minibuffer windows.
+* Recursive Mini:: Whether recursive entry to minibuffer is allowed.
* Minibuffer Misc:: Various customization hooks and variables.
@end menu
active minibuffer. We usually call this ``the'' minibuffer. You can
permit or forbid recursive minibuffers by setting the variable
@code{enable-recursive-minibuffers} or by putting properties of that
-name on command symbols (@pxref{Minibuffer Misc}).
+name on command symbols (@pxref{Recursive Mini}).
- Like other buffers, a minibuffer may use any of several local keymaps
-(@pxref{Keymaps}); these contain various exit commands and in some cases
-completion commands (@pxref{Completion}).
-
-@itemize @bullet
-@item
-@code{minibuffer-local-map} is for ordinary input (no completion).
-
-@item
-@code{minibuffer-local-ns-map} is similar, except that @key{SPC} exits
-just like @key{RET}.
-
-@item
-@code{minibuffer-local-completion-map} is for permissive completion.
-
-@item
-@code{minibuffer-local-must-match-map} is for strict completion and
-for cautious completion.
-@end itemize
+ Like other buffers, a minibuffer uses a local keymap
+(@pxref{Keymaps}) to specify special key bindings. The function that
+invokes the minibuffer also sets up its local map according to the job
+to be done. @xref{Text from Minibuffer}, for the non-completion
+minibuffer local maps. @xref{Completion Commands}, for the minibuffer
+local maps for completion.
When Emacs is running in batch mode, any request to read from the
minibuffer actually reads a line from the standard input descriptor that
Most often, the minibuffer is used to read text as a string. It can
also be used to read a Lisp object in textual form. The most basic
primitive for minibuffer input is @code{read-from-minibuffer}; it can do
-either one.
+either one. There are also specialized commands for reading
+commands, variables, file names, etc. (@pxref{Completion}).
In most cases, you should not call minibuffer input functions in the
middle of a Lisp function. Instead, do all minibuffer input as part of
@code{abort-recursive-edit}
@item @kbd{M-n}
+@itemx @key{DOWN}
@code{next-history-element}
@item @kbd{M-p}
+@itemx @key{UP}
@code{previous-history-element}
@item @kbd{M-s}
inputs. It's the Lisp programmer's job to specify the right history
list for each use of the minibuffer.
- The basic minibuffer input functions @code{read-from-minibuffer} and
-@code{completing-read} both accept an optional argument named @var{hist}
-which is how you specify the history list. Here are the possible
-values:
+ You specify the history list with the optional @var{hist} argument
+to either @code{read-from-minibuffer} or @code{completing-read}. Here
+are the possible values for it:
@table @asis
@item @var{variable}
@node Basic Completion
@subsection Basic Completion Functions
- The functions @code{try-completion}, @code{all-completions} and
-@code{test-completion} have nothing in themselves to do with
-minibuffers. We describe them in this chapter so as to keep them near
-the higher-level completion features that do use the minibuffer.
+ The completion functions @code{try-completion},
+@code{all-completions} and @code{test-completion} have nothing in
+themselves to do with minibuffers. We describe them in this chapter
+so as to keep them near the higher-level completion features that do
+use the minibuffer.
+
+ If you store a completion alist in a variable, you should mark the
+variable as ``risky'' with a non-@code{nil}
+@code{risky-local-variable} property.
@defun try-completion string collection &optional predicate
This function returns the longest common substring of all possible
completions of @var{string} in @var{collection}. The value of
-@var{collection} must be a list of strings, an alist, an obarray, a
-hash table, or a function that implements a virtual set of strings
-(see below).
+@var{collection} must be a list of strings or symbols, an alist, an
+obarray, a hash table, or a function that implements a virtual set of
+strings (see below).
Completion compares @var{string} against each of the permissible
completions specified by @var{collection}; if the beginning of the
If @var{collection} is an alist (@pxref{Association Lists}), the
permissible completions are the elements of the alist that are either
-strings or conses whose @sc{car} is a string. Other elements of the
-alist are ignored. (Remember that in Emacs Lisp, the elements of
-alists do not @emph{have} to be conses.) As all elements of the alist
-can be strings, this case actually includes lists of strings, even
-though we usually do not think of such lists as alists.
+strings, symbols, or conses whose @sc{car} is a string or symbol.
+Symbols are converted to strings using @code{symbol-name}.
+Other elements of the alist are ignored. (Remember that in Emacs Lisp,
+the elements of alists do not @emph{have} to be conses.) As all
+elements of the alist can be strings, this case actually includes
+lists of strings or symbols, even though we usually do not think of
+such lists as alists.
@cindex obarray in completion
If @var{collection} is an obarray (@pxref{Creating Symbols}), the names
bound to the value of @code{completion-ignore-case}.
@end defvar
-@defmac lazy-completion-table var fun &rest args
+@defmac lazy-completion-table var fun
This macro provides a way to initialize the variable @var{var} as a
collection for completion in a lazy way, not computing its actual
contents until they are first needed. You use this macro to produce a
value that you store in @var{var}. The actual computation of the
proper value is done the first time you do completion using @var{var}.
-It is done by calling @var{fun} with the arguments @var{args}. The
+It is done by calling @var{fun} with no arguments. The
value @var{fun} returns becomes the permanent value of @var{var}.
-Here are two examples of use:
+Here is an example of use:
-@example
-(defvar foo (lazy-completion-table foo make-my-alist 'global))
-
-(make-local-variable 'bar)
-(setq bar (lazy-completion-table foo make-my-alist 'local)
-@end example
+@smallexample
+(defvar foo (lazy-completion-table foo make-my-alist))
+@end smallexample
@end defmac
@node Minibuffer Completion
If the user then types @kbd{@key{DEL} @key{DEL} b @key{RET}},
@code{completing-read} returns @code{barfoo}.
-The @code{completing-read} function binds three variables to pass
-information to the commands that actually do completion. These
-variables are @code{minibuffer-completion-table},
-@code{minibuffer-completion-predicate} and
-@code{minibuffer-completion-confirm}. For more information about them,
-see @ref{Completion Commands}.
+The @code{completing-read} function binds variables to pass
+information to the commands that actually do completion.
+They are described in the following section.
@end defun
@node Completion Commands
emacs, The GNU Emacs Manual}, for a short description of Partial
Completion mode.
-@defvar minibuffer-local-completion-map
-@code{completing-read} uses this value as the local keymap when an
-exact match of one of the completions is not required. By default, this
-keymap makes the following bindings:
-
-@table @asis
-@item @kbd{?}
-@code{minibuffer-completion-help}
-
-@item @key{SPC}
-@code{minibuffer-complete-word}
-
-@item @key{TAB}
-@code{minibuffer-complete}
-@end table
-
-@noindent
-with other characters bound as in @code{minibuffer-local-map}
-(@pxref{Definition of minibuffer-local-map}).
-@end defvar
-
-@defvar minibuffer-local-must-match-map
-@code{completing-read} uses this value as the local keymap when an
-exact match of one of the completions is required. Therefore, no keys
-are bound to @code{exit-minibuffer}, the command that exits the
-minibuffer unconditionally. By default, this keymap makes the following
-bindings:
-
-@table @asis
-@item @kbd{?}
-@code{minibuffer-completion-help}
-
-@item @key{SPC}
-@code{minibuffer-complete-word}
-
-@item @key{TAB}
-@code{minibuffer-complete}
-
-@item @kbd{C-j}
-@code{minibuffer-complete-and-exit}
-
-@item @key{RET}
-@code{minibuffer-complete-and-exit}
-@end table
-
-@noindent
-with other characters bound as in @code{minibuffer-local-map}.
-@end defvar
-
@defvar minibuffer-completion-table
The value of this variable is the collection used for completion in
the minibuffer. This is the global variable that contains what
minibuffer completion functions.
@end defvar
+@defvar minibuffer-completion-confirm
+When the value of this variable is non-@code{nil}, Emacs asks for
+confirmation of a completion before exiting the minibuffer.
+@code{completing-read} binds this variable, and the function
+@code{minibuffer-complete-and-exit} checks the value before exiting.
+@end defvar
+
@deffn Command minibuffer-complete-word
This function completes the minibuffer contents by at most a single
word. Even if the minibuffer contents have only one completion,
when run twice in succession.
@end deffn
-@defvar minibuffer-completion-confirm
-When the value of this variable is non-@code{nil}, Emacs asks for
-confirmation of a completion before exiting the minibuffer. The
-function @code{minibuffer-complete-and-exit} checks the value of this
-variable before it exits.
-@end defvar
-
@deffn Command minibuffer-completion-help
This function creates a list of the possible completions of the
current minibuffer contents. It works by calling @code{all-completions}
@samp{*Completions*}.
@end deffn
-@defun display-completion-list completions
+@defun display-completion-list completions &optional common-substring
This function displays @var{completions} to the stream in
@code{standard-output}, usually a buffer. (@xref{Read and Print}, for more
information about streams.) The argument @var{completions} is normally
the two strings is the actual completion, the second string serves as
annotation.
+The argument @var{common-substring} is the prefix that is common to
+all the completions. With normal Emacs completion, it is usually the
+same as the string that was completed. @code{display-completion-list}
+uses this to highlight text in the completion list for better visual
+feedback. This is not needed in the minibuffer; for minibuffer
+completion, you can pass @code{nil}.
+
This function is called by @code{minibuffer-completion-help}. The
most common way to use it is together with
@code{with-output-to-temp-buffer}, like this:
@example
(with-output-to-temp-buffer "*Completions*"
(display-completion-list
- (all-completions (buffer-string) my-alist)))
+ (all-completions (buffer-string) my-alist)
+ (buffer-string)))
@end example
@end defun
can be completed because the next character is not uniquely determined.
@end defopt
+@defvar minibuffer-local-completion-map
+@code{completing-read} uses this value as the local keymap when an
+exact match of one of the completions is not required. By default, this
+keymap makes the following bindings:
+
+@table @asis
+@item @kbd{?}
+@code{minibuffer-completion-help}
+
+@item @key{SPC}
+@code{minibuffer-complete-word}
+
+@item @key{TAB}
+@code{minibuffer-complete}
+@end table
+
+@noindent
+with other characters bound as in @code{minibuffer-local-map}
+(@pxref{Definition of minibuffer-local-map}).
+@end defvar
+
+@defvar minibuffer-local-must-match-map
+@code{completing-read} uses this value as the local keymap when an
+exact match of one of the completions is required. Therefore, no keys
+are bound to @code{exit-minibuffer}, the command that exits the
+minibuffer unconditionally. By default, this keymap makes the following
+bindings:
+
+@table @asis
+@item @kbd{?}
+@code{minibuffer-completion-help}
+
+@item @key{SPC}
+@code{minibuffer-complete-word}
+
+@item @key{TAB}
+@code{minibuffer-complete}
+
+@item @kbd{C-j}
+@code{minibuffer-complete-and-exit}
+
+@item @key{RET}
+@code{minibuffer-complete-and-exit}
+@end table
+
+@noindent
+with other characters bound as in @code{minibuffer-local-map}.
+@end defvar
+
+@defvar minibuffer-local-filename-completion-map
+This is like @code{minibuffer-local-completion-map}
+except that it does not bind @key{SPC}. This keymap is used by the
+function @code{read-file-name}.
+@end defvar
+
+@defvar minibuffer-local-must-match-filename-map
+This is like @code{minibuffer-local-must-match-map}
+except that it does not bind @key{SPC}. This keymap is used by the
+function @code{read-file-name}.
+@end defvar
+
@node High-Level Completion
@subsection High-Level Completion Functions
it should be a string or a buffer. It is mentioned in the prompt, but
is not inserted in the minibuffer as initial input.
+The argument @var{prompt} should be a string ending with a colon and a
+space. If @var{default} is non-@code{nil}, the function inserts it in
+@var{prompt} before the colon to follow the convention for reading from
+the minibuffer with a default value (@pxref{Programming Tips}).
+
If @var{existing} is non-@code{nil}, then the name specified must be
that of an existing buffer. The usual commands to exit the minibuffer
do not exit if the text is not valid, and @key{RET} does completion to
@samp{minibuffer.texi}, so that name is the value.
@example
-(read-buffer "Buffer name? " "foo" t)
+(read-buffer "Buffer name: " "foo" t)
@group
;; @r{After evaluation of the preceding expression,}
;; @r{the following prompt appears,}
@group
---------- Buffer: Minibuffer ----------
-Buffer name? (default foo) @point{}
+Buffer name (default foo): @point{}
---------- Buffer: Minibuffer ----------
@end group
@end defun
See also the functions @code{read-coding-system} and
-@code{read-non-nil-coding-system}, in @ref{User-Chosen Coding Systems}.
+@code{read-non-nil-coding-system}, in @ref{User-Chosen Coding Systems},
+and @code{read-input-method-name}, in @ref{Input Methods}.
@node Reading File Names
@subsection Reading File Names
@var{existing} is @code{nil}, then the name of a nonexistent file is
acceptable.
+The function @code{read-file-name} uses
+@code{minibuffer-local-filename-completion-map} as the keymap if
+@var{existing} is @code{nil}, and uses
+@code{minibuffer-local-must-match-filename-map} if @var{existing} is
+non-@code{nil}. @xref{Completion Commands}.
+
The argument @var{directory} specifies the directory to use for
completion of relative file names. It should be an absolute directory
name. If @code{insert-default-directory} is non-@code{nil},
as the string @code{"/gp/gnu/elisp/manual.texi"}.
@end defun
+@defvar read-file-name-function
+If non-@code{nil}, this should be a function that accepts the same
+arguments as @code{read-file-name}. When @code{read-file-name} is
+called, it calls this function with the supplied arguments instead of
+doing its usual work.
+@end defvar
+
+@defvar read-file-name-completion-ignore-case
+If this variable is non-@code{nil}, @code{read-file-name} ignores case
+when performing completion.
+@end defvar
+
@defun read-directory-name prompt &optional directory default existing initial
This function is like @code{read-file-name} but allows only directory
names as completion possibilities.
@code{read-directory-name} constructs a substitute default by
combining @var{directory} (or the current buffer's default directory
if @var{directory} is @code{nil}) and @var{initial}. If both
-@var{default} and @var{initial} are @code{nil}, this function uses the
-current buffer's default directory as substitute default, ignoring
-@var{directory}.
+@var{default} and @var{initial} are @code{nil}, this function uses
+@var{directory} as substitute default, or the current buffer's default
+directory if @var{directory} is @code{nil}.
@end defun
@defopt insert-default-directory
then @code{read-passwd} returns the null string in that case.
@end defun
-@node Minibuffer Misc
-@section Minibuffer Miscellany
+@node Minibuffer Commands
+@section Minibuffer Commands
- This section describes some basic functions and variables related to
-minibuffers.
+ This section describes some commands meant for use in the
+minibuffer.
@deffn Command exit-minibuffer
This command exits the active minibuffer. It is normally bound to
regular expression).
@end deffn
-@defun minibuffer-prompt
-This function returns the prompt string of the currently active
-minibuffer. If no minibuffer is active, it returns @code{nil}.
-@end defun
-
-@defun minibuffer-prompt-end
-@tindex minibuffer-prompt-end
-This function, available starting in Emacs 21, returns the current
-position of the end of the minibuffer prompt, if a minibuffer is
-current. Otherwise, it returns the minimum valid buffer position.
-@end defun
+@node Minibuffer Windows
+@section Minibuffer Windows
-@defun minibuffer-contents
-@tindex minibuffer-contents
-This function, available starting in Emacs 21, returns the editable
-contents of the minibuffer (that is, everything except the prompt) as
-a string, if a minibuffer is current. Otherwise, it returns the
-entire contents of the current buffer.
-@end defun
-
-@defun minibuffer-contents-no-properties
-@tindex minibuffer-contents-no-properties
-This is like @code{minibuffer-contents}, except that it does not copy text
-properties, just the characters themselves. @xref{Text Properties}.
-@end defun
-
-@defun delete-minibuffer-contents
-@tindex delete-minibuffer-contents
-This function, available starting in Emacs 21, erases the editable
-contents of the minibuffer (that is, everything except the prompt), if
-a minibuffer is current. Otherwise, it erases the entire buffer.
-@end defun
-
-@defun minibuffer-prompt-width
-This function returns the current display-width of the minibuffer
-prompt, if a minibuffer is current. Otherwise, it returns zero.
-@end defun
-
-@defvar minibuffer-setup-hook
-This is a normal hook that is run whenever the minibuffer is entered.
-@xref{Hooks}.
-@end defvar
-
-@defvar minibuffer-exit-hook
-This is a normal hook that is run whenever the minibuffer is exited.
-@xref{Hooks}.
-@end defvar
-
-@defvar minibuffer-help-form
-@anchor{Definition of minibuffer-help-form}
-The current value of this variable is used to rebind @code{help-form}
-locally inside the minibuffer (@pxref{Help Functions}).
-@end defvar
-
-@defun minibufferp &optional buffer-or-name
-This function returns non-@code{nil} if @var{buffer-or-name} is a
-minibuffer. If @var{buffer-or-name} is omitted, it tests the current
-buffer.
-@end defun
+ These functions access and select minibuffer windows
+and test whether they are active.
@defun active-minibuffer-window
This function returns the currently active minibuffer window, or
a minibuffer window, is currently active.
@end defun
-@defvar minibuffer-scroll-window
-@anchor{Definition of minibuffer-scroll-window}
-If the value of this variable is non-@code{nil}, it should be a window
-object. When the function @code{scroll-other-window} is called in the
-minibuffer, it scrolls this window.
-@end defvar
+@node Minibuffer Contents
+@section Minibuffer Contents
-@defun minibuffer-selected-window
-This function returns the window which was selected when the
-minibuffer was entered. If selected window is not a minibuffer
-window, it returns @code{nil}.
+ These functions access the minibuffer prompt and contents.
+
+@defun minibuffer-prompt
+This function returns the prompt string of the currently active
+minibuffer. If no minibuffer is active, it returns @code{nil}.
@end defun
-Finally, some functions and variables deal with recursive minibuffers
+@defun minibuffer-prompt-end
+@tindex minibuffer-prompt-end
+This function returns the current
+position of the end of the minibuffer prompt, if a minibuffer is
+current. Otherwise, it returns the minimum valid buffer position.
+@end defun
+
+@defun minibuffer-prompt-width
+This function returns the current display-width of the minibuffer
+prompt, if a minibuffer is current. Otherwise, it returns zero.
+@end defun
+
+@defun minibuffer-contents
+@tindex minibuffer-contents
+This function returns the editable
+contents of the minibuffer (that is, everything except the prompt) as
+a string, if a minibuffer is current. Otherwise, it returns the
+entire contents of the current buffer.
+@end defun
+
+@defun minibuffer-contents-no-properties
+@tindex minibuffer-contents-no-properties
+This is like @code{minibuffer-contents}, except that it does not copy text
+properties, just the characters themselves. @xref{Text Properties}.
+@end defun
+
+@defun minibuffer-completion-contents
+@tindex minibuffer-completion-contents
+This is like @code{minibuffer-contents}, except that it returns only
+the contents before point. That is the part that completion commands
+operate on. @xref{Minibuffer Completion}.
+@end defun
+
+@defun delete-minibuffer-contents
+@tindex delete-minibuffer-contents
+This function erases the editable contents of the minibuffer (that is,
+everything except the prompt), if a minibuffer is current. Otherwise,
+it erases the entire current buffer.
+@end defun
+
+@node Recursive Mini
+@section Recursive Minibuffers
+
+ These functions and variables deal with recursive minibuffers
(@pxref{Recursive Editing}):
@defun minibuffer-depth
The minibuffer command @code{next-matching-history-element} (normally
@kbd{M-s} in the minibuffer) does the latter.
+@node Minibuffer Misc
+@section Minibuffer Miscellany
+
+@defun minibufferp &optional buffer-or-name
+This function returns non-@code{nil} if @var{buffer-or-name} is a
+minibuffer. If @var{buffer-or-name} is omitted, it tests the current
+buffer.
+@end defun
+
+@defvar minibuffer-setup-hook
+This is a normal hook that is run whenever the minibuffer is entered.
+@xref{Hooks}.
+@end defvar
+
+@defvar minibuffer-exit-hook
+This is a normal hook that is run whenever the minibuffer is exited.
+@xref{Hooks}.
+@end defvar
+
+@defvar minibuffer-help-form
+@anchor{Definition of minibuffer-help-form}
+The current value of this variable is used to rebind @code{help-form}
+locally inside the minibuffer (@pxref{Help Functions}).
+@end defvar
+
+@defvar minibuffer-scroll-window
+@anchor{Definition of minibuffer-scroll-window}
+If the value of this variable is non-@code{nil}, it should be a window
+object. When the function @code{scroll-other-window} is called in the
+minibuffer, it scrolls this window.
+@end defvar
+
+@defun minibuffer-selected-window
+This function returns the window which was selected when the
+minibuffer was entered. If selected window is not a minibuffer
+window, it returns @code{nil}.
+@end defun
+
+@defopt max-mini-window-height
+This variable specifies the maximum height for resizing minibuffer
+windows. If a float, it specifies a fraction of the height of the
+frame. If an integer, it specifies a number of lines.
+@end defopt
+
@defun minibuffer-message string
This function displays @var{string} temporarily at the end of the
minibuffer text, for two seconds, or until the next input event