@c -*-texinfo-*-
@setfilename ../info/minibuf
@node Minibuffers, Command Loop, Streams, Top
@chapter Minibuffers
@cindex arguments, reading
@cindex complex arguments
@cindex minibuffer

  A @dfn{minibuffer} is a special buffer used by Emacs commands 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
screen, in the same place as the echo area, but only while it is in
use for reading an argument.

@menu
* Intro to Minibuffers::      Basic information about minibuffers.
* Text from Minibuffer::      How to read a straight text string.
* Object from Minibuffer::    How to read a Lisp object or expression.
* Completion::                How to invoke and customize completion.
* Yes-or-No Queries::         Asking a question with a simple answer.
* Minibuffer Misc::           Various customization hooks and variables.
@end menu

@node Intro to Minibuffers, Text from Minibuffer, Minibuffers, Minibuffers
@section Introduction to Minibuffers

  In most ways, a minibuffer is a normal Emacs buffer.  Most operations
@emph{within} a buffer, such as editing commands, work normally in a
minibuffer.  However, many operations for managing buffers do not apply
to minibuffers.  The name of a minibuffer always has the form @w{@samp{
*Minibuf-@var{number}}}, and it cannot be changed.  There is a special
window used only for minibuffers, and minibuffers cannot be displayed in
any other window.  This window is normally the single line at the bottom
of the screen; it can be resized temporarily with the window sizing
commands, but reverts to its normal size when the minibuffer is exited.

  A @dfn{recursive minibuffer} may be created when there is an active
minibuffer and a command is invoked that requires input from a
minibuffer.  The first minibuffer is named @w{@samp{ *Minibuf-0*}}.
Recursive minibuffers are named by incrementing the number at the end of
the name.  (The names begin with a space so that they won't show up in
normal buffer lists.)  Of several recursive minibuffers, the innermost
(or most recently entered) is the active minibuffer, and is the only one
that is displayed in a window.  We usually call this ``the'' minibuffer.
Recursive minibuffers may be allowed or disallowed by setting the
variable @code{enable-recursive-minibuffers}.

  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.  @xref{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}.  This is used mainly for Mocklisp compatibility.

@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.

@item
@code{repeat-complex-command-map} is for use in @kbd{C-x @key{ESC}}.
@end itemize

@node Text from Minibuffer, Object from Minibuffer, Intro to Minibuffers, Minibuffers
@section Reading Text Strings with the Minibuffer

  The minibuffer is usually used to read text which is returned as a
string, but can also be used to read a Lisp object in textual form.  The
most basic primitive for minibuffer input is
@code{read-from-minibuffer}.

@defun read-from-minibuffer prompt-string &optional initial keymap read
This function is the most general way to get input through the
minibuffer.  By default, it accepts arbitrary text and returns it as a
string; however, if @var{read} is non-@code{nil}, then it uses
@code{read} to convert the text into a Lisp object (@pxref{Input
Functions}).

The first thing this function does is to activate a minibuffer and 
display it with  @var{prompt-string} as the prompt.  This value must be a
string.

Then, if @var{initial} is non-@code{nil}, it must be a string; its
contents are inserted into the minibuffer as initial contents.  The text
thus inserted is treated as if the user had inserted it; the user can
alter it with Emacs editing commands.

If @var{keymap} is non-@code{nil}, that keymap is the local keymap to
use while reading.  If @var{keymap} is omitted or @code{nil}, the value
of @code{minibuffer-local-map} is used as the keymap.  Specifying a
keymap is the most important way to customize minibuffer input for
various applications including completion.

When the user types a command to exit the minibuffer, the current
minibuffer contents are usually made into a string which is the value of
@code{read-from-minibuffer}.  However, if @var{read} is non-@code{nil},
Emacs converts the result to a Lisp object and
@code{read-from-minibuffer} returns that object, unevaluated.

Suppose, for example, you are writing a search command and want to
record the last search string and provide it as a default for the next
search.  Suppose that the previous search string is stored in the
variable @code{last-search-string}.  Here is how you can read a search
string while providing the previous string as initial input to be
edited:

@example
(read-from-minibuffer "Find string: " last-search-string)
@end example

Assuming the value of @code{last-search-string} is @samp{No}, and
the user wants to search for @samp{Nope}, the interaction looks
like this:

@example
(setq last-search-string "No")

(read-from-minibuffer "Find string: " last-search-string)
---------- Buffer: Minibuffer ----------
Find string: No@point{}
---------- Buffer: Minibuffer ----------
;; @r{The user now types @kbd{pe @key{RET}}:}
     @result{} "Nope"
@end example
@end defun

@defun read-string prompt &optional initial
This function reads a string from the minibuffer and returns it.  The
arguments @var{prompt} and @var{initial} are used as in
@code{read-from-minibuffer}.

This function is a simplified interface to @code{read-from-minibuffer}:

@example
(read-string @var{prompt} @var{initial})
@equiv{}
(read-from-minibuffer @var{prompt} @var{initial} nil nil)
@end example
@end defun

@defvar minibuffer-local-map
This is the default local keymap for reading from the minibuffer.  It is
the keymap used by the minibuffer for local bindings in the function
@code{read-string}.  By default, it makes the following bindings:

@table @asis
@item @key{LFD}
@code{exit-minibuffer}

@item @key{RET}
@code{exit-minibuffer}

@item @kbd{C-g}
@code{abort-recursive-edit}
@end table
@end defvar

@c In version 19, initial is optional.
@defun read-no-blanks-input prompt initial
This function reads a string from the minibuffer, but does not allow
whitespace characters as part of the input: instead, those characters
terminate the input.  The arguments @var{prompt} and @var{initial} are
used as in @code{read-from-minibuffer}.

This function is a simplified interface to @code{read-from-minibuffer},
and passes the value of @code{minibuffer-local-ns-map} as the
@var{keymap} argument for that function.  Since the keymap
@code{minibuffer-local-ns-map} does not rebind @kbd{C-q}, it @emph{is}
possible to put a space into the string, by quoting it.

@group
@example
(read-no-blanks-input @var{prompt} @var{initial})
@equiv{}
(read-from-minibuffer @var{prompt} @var{initial} minibuffer-local-ns-map)
@end example
@end group
@end defun

@defvar minibuffer-local-ns-map
This built-in variable is the keymap used as the minibuffer local keymap
in the function @code{read-no-blanks-input}.  By default, it makes the
following bindings:

@table @kbd
@item @key{LFD}
@code{exit-minibuffer}

@item @key{SPC}
@cindex @key{SPC} in minibuffer
@code{exit-minibuffer}

@item @key{TAB}
@cindex @key{TAB} in minibuffer
@code{exit-minibuffer}

@item @key{RET}
@code{exit-minibuffer}

@item C-g
@code{abort-recursive-edit}

@item ?
@cindex @kbd{?} in minibuffer
@code{self-insert-and-exit}
@end table
@end defvar

@node Object from Minibuffer, Completion, Text from Minibuffer, Minibuffers
@section Reading Lisp Objects with the Minibuffer

  This section describes functions for reading Lisp objects with the
minibuffer.

@defun read-minibuffer prompt &optional initial
  This function reads a Lisp object in the minibuffer and returns it,
unevaluated.  The arguments @var{prompt} and @var{initial} are used as
in @code{read-from-minibuffer}; in particular, @var{initial} must be a
string or @code{nil}.

  This function is a simplified interface to @code{read-from-minibuffer}:

@example
(read-minibuffer @var{prompt} @var{initial})
@equiv{}
(read-from-minibuffer @var{prompt} @var{initial} nil t)
@end example

Here is an example in which we supply the string @code{"(testing)"} as
initial input:

@example
(read-minibuffer "Enter an expression: " (format "%s" '(testing)))

;;  @r{Here is how the minibuffer is displayed:}

---------- Buffer: Minibuffer ----------
Enter an expression: (testing)@point{}
---------- Buffer: Minibuffer ----------
@end example

@noindent
The user can type @key{RET} immediately to use the initial input as a
default, or can edit the input.
@end defun

@defun eval-minibuffer prompt &optional initial
  This function reads a Lisp expression in the minibuffer, evaluates it,
then returns the result.  The arguments @var{prompt} and @var{initial}
are used as in @code{read-from-minibuffer}.

  This function simply evaluates the result of a call to
@code{read-minibuffer}:

@example
(eval-minibuffer @var{prompt} @var{initial})
@equiv{}
(eval (read-minibuffer @var{prompt} @var{initial}))
@end example
@end defun

@defun edit-and-eval-command prompt form
  This function reads a Lisp expression in the minibuffer, and then
evaluates it.  The difference between this command and
@code{eval-minibuffer} is that here the initial @var{form} is not
optional and it is treated as a Lisp object to be converted to printed
representation rather than as a string of text.  It is printed with
@code{prin1}, so if it is a string, double-quote characters (@samp{"})
will appear in the initial text.  @xref{Output Functions}.

  The first thing @code{edit-and-eval-command} does is to activate the
minibuffer with @var{prompt} as the prompt.  The printed representation
of @var{form} is then inserted in the minibuffer, and the user is
allowed to edit.  When the user exits the minibuffer, the edited text is
read with @code{read} and then evaluated.  The resulting value becomes
the value of @code{edit-and-eval-command}.

  In the following example, we offer the user an expression with initial
text which is a valid form already:

@example
(edit-and-eval-command "Please edit: " '(forward-word 1))

;; @r{After evaluating the preceding expression,} 
;; @r{the following appears in the minibuffer:}

---------- Buffer: Minibuffer ----------
Please edit: (forward-word 1)@point{}
---------- Buffer: Minibuffer ----------
@end example

@noindent
Typing @key{RET} right away would exit the minibuffer and evaluate the
expression, thus moving point forward one word.
@code{edit-and-eval-command} returns @code{nil} in this example.
@end defun

@node Completion, Yes-or-No Queries, Object from Minibuffer, Minibuffers
@section Completion
@cindex completion

  @dfn{Completion} is a feature that fills in the rest of a name
starting from an abbreviation for it.  Completion works by comparing the
user's input against a list of valid names and determining how much of
the name is determined uniquely by what the user has typed.

  For example, when you type @kbd{C-x b} (@code{switch-to-buffer}) and
then type the first few letters of the name of the buffer to which you
wish to switch, and then type @key{TAB} (@code{minibuffer-complete}),
Emacs extends the name as far as it can.  Standard Emacs commands offer
completion for names of symbols, files, buffers, and processes; with the
functions in this section, you can implement completion for other kinds
of names.

  The @code{try-completion} function is the basic primitive for
completion: it returns the longest determined completion of a given
initial string, with a given set of strings to match against.

  The function @code{completing-read} provides a higher-level interface
for completion.  A call to @code{completing-read} specifies how to
determine the list of valid names.  The function then activates the
minibuffer with a local keymap that binds a few keys to commands useful
for completion.  Other functions provide convenient simple interfaces
for reading certain kinds of names with completion.

@menu
* Basic Completion::       Low-level functions for completing strings.
                             (These are too low level to use the minibuffer.)
* Programmed Completion::  Finding the completions for a given file name.
* Minibuffer Completion::  Invoking the minibuffer with completion.
* Completion Commands::    Minibuffer commands that do completion.
* High-Level Completion::  Convenient special cases of completion
                             (reading buffer name, file name, etc.)
* Reading File Names::     Using completion to read file names.
* Lisp Symbol Completion:: Completing the name of a symbol.
@end menu

@node Basic Completion, Programmed Completion, Completion, Completion
@comment  node-name,  next,  previous,  up
@subsection Basic Completion Functions

@defun try-completion string alist-or-obarray &optional predicate
  This function returns the longest common substring of all
possible completions of @var{string} in @var{alist-or-obarray}.

  If @var{alist-or-obarray} is an association list (@pxref{Association
Lists}), the @sc{car} of each cons cell in it is compared against
@var{string}; if the beginning of the @sc{car} equals @var{string}, the
cons cell matches.  If no cons cells match, @code{try-completion} returns
@code{nil}.  If only one cons cell matches, and the match is exact, then
@code{try-completion} returns @code{t}.  Otherwise, all matching strings
are compared, and the longest initial sequence common to them is
returned as a string.

@cindex obarray in completion
  If @var{alist-or-obarray} is an obarray (@pxref{Creating Symbols}),
the names of all symbols in the obarray form the space of possible
names.  They are tested and used just like the @sc{car}s of the elements
of an association list.  (The global variable @code{obarray} holds an
obarray containing the names of all interned Lisp symbols.)

  If the argument @var{predicate} is non-@code{nil}, then it must be a
function of one argument.  It is used to test each possible match, and
the match is accepted only if @var{predicate} returns non-@code{nil}.
The argument given to @var{predicate} is either a cons cell from the alist
(the @sc{car} of which is a string) or else it is a symbol (@emph{not} a
symbol name) from the obarray.

  It is also possible to use a function as @var{alist-or-obarray}.  Then
the function is solely responsible for performing completion;
@code{try-completion} returns whatever this function returns.  The
function is called with three arguments: @var{string}, @var{predicate}
and @code{nil}.  (The reason for the third argument is so that the same
function can be used in @code{all-completions} and do the appropriate
thing in either case.)  @xref{Programmed Completion}.

  In the first of the following examples, the string @samp{foo} is
matched by three of the alist @sc{car}s.  All of the matches begin with
the characters @samp{fooba}, so that is the result.  In the second
example, there is only one possible match, and it is exact, so the value
is @code{t}.

@example
(try-completion "foo"
     '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)))
     @result{} "fooba"

(try-completion "foo" '(("barfoo" 2) ("foo" 3)))
     @result{} t
@end example

  In the following example, numerous symbols begin with the characters
@samp{forw}, and all of them begin with the word @samp{forward}.  In
most of the symbols, this is followed with a @samp{-}, but not in all,
so no more than @samp{forward} can be completed.

@example
(try-completion "forw" obarray)
     @result{} "forward"
@end example

  Finally, in the following example, only two of the three possible
matches pass the predicate @code{test} (the string @samp{foobaz} is
too short).  Both of those begin with the string @samp{foobar}.

@example
(defun test (s) 
  (> (length (car s)) 6))
     @result{} test
(try-completion "foo"
     '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)) 
     'test)
     @result{} "foobar"
@end example
@end defun

@defun all-completions string alist-or-obarray &optional predicate 
  This function returns a list of all possible completions, instead of
the longest substring they share.  The parameters to this function are
the same as to @code{try-completion}.

  If @var{alist-or-obarray} is a function, it is called with three
arguments: @var{string}, @var{predicate} and @code{t}, and
@code{all-completions} returns whatever the function returns.
@xref{Programmed Completion}.

  Here is an example, using the same function @code{test} used
in the example for @code{try-completion}:

@example
(defun test (s) 
  (> (length (car s)) 6))
     @result{} test

(all-completions  "foo"
     '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
     (function test))
     @result{} ("foobar1" "foobar2")
@end example
@end defun

@defvar completion-ignore-case
  If the value of this variable is 
non-@code{nil}, Emacs does not consider case significant in completion.
@end defvar

  The two functions @code{try-completion} and @code{all-completions}
have nothing in themselves to do with minibuffers.  However,
completion is most often used there, which is why it is described in
this chapter.  

@node Programmed Completion, Minibuffer Completion, Basic Completion, Completion
@subsection Programmed Completion
@cindex programmed completion

  Sometimes it is not possible to create an alist or an obarray
containing all the intended possible completions.  In such a case, you
can supply your own function to compute the completion of a given string.
This is called @dfn{programmed completion}.

  To use this feature, pass the function as the @var{alist-or-obarray}
argument to @code{completing-read}.  This command will arrange to pass
the function along to @code{try-completion} and @code{all-completions},
which will then let your function do all the work.

  The completion function should accept three arguments:

@itemize @bullet
@item
The string to be completed.

@item
The predicate function to filter possible matches, or @code{nil} if none.
Your function should call the predicale for each possible match and ignore
the possible match if the predicate returns @code{nil}.

@item
A flag specifying the type of operation.
@end itemize

  There are three flag values for three operations:

@itemize @bullet
@item
@code{nil} specifies @code{try-completion}.  The completion function
should return the completion of the specified string, or @code{t} if the
string is an exact match already, or @code{nil} if the string matches no
possibility.

@item
@code{t} specifies @code{all-completions}.  The completion function
should return a list of all possible completions of the specified
string.

@item
@code{lambda} specifies a test for an exact match.  The completion
function should return @code{t} if the specified string is an exact
match for some possibility; @code{nil} otherwise.
@end itemize

  Emacs uses programmed completion when completing file names.
@xref{File Name Completion}.

@node Minibuffer Completion, Completion Commands, Programmed Completion, Completion
@comment  node-name,  next,  previous,  up
@subsection Completion and the Minibuffer

  This section describes the basic interface for reading from the
minibuffer with completion.

@defun completing-read prompt alist-or-obarray &optional predicate require-match initial
  This function reads a string in the minibuffer, assisting the user by
providing completion.  It activates the minibuffer with prompt
@var{prompt}, which must be a string.  If @var{initial} is
non-@code{nil}, @code{completing-read} inserts it into the minibuffer as
part of the input.  Then it allows the user to edit the input, providing
several commands to attempt completion.

  The actual completion is done by passing @var{alist-or-obarray} and
@var{predicate} to the function @code{try-completion}.  This happens in
certain commands bound in the local keymaps used for completion.

  If @var{require-match} is @code{t}, the user will not be allowed to
exit unless the input completes to an element of @var{alist-or-obarray}.
If @var{require-match} is neither @code{nil} nor @code{t}, then
@code{completing-read} does not exit unless the input typed is itself an
element of @var{alist-or-obarray}.  To accomplish this,
@code{completing-read} calls @code{read-minibuffer} with the keymap
@code{minibuffer-local-completion-map} if @var{require-match} is
@code{nil}, or else with the keymap
@code{minibuffer-local-must-match-map}, if @var{require-match} is
non-@code{nil}.

  Case is ignored when comparing the input against the possible matches
if the built-in variable @code{completion-ignore-case} is
non-@code{nil}.  @xref{Basic Completion}.

For example:

@example
(completing-read "Complete a foo: "
     '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
     nil t "fo")

;; @r{After evaluating the preceding expression,} 
;; @r{the following appears in the minibuffer:}

---------- Buffer: Minibuffer ----------
Complete a foo: fo@point{}
---------- Buffer: Minibuffer ----------
@end example

@noindent
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 which actually do completion.  Here they
are:

@table @code
@item minibuffer-completion-table
This variable is bound to @var{alist-or-obarray} argument.  It is passed
to the @code{try-completion} function.

@item minibuffer-completion-predicate
This variable is bound to the @var{predicate} argument.  It is passed to
the @code{try-completion} function.

@item minibuffer-completion-confirm
This variable is bound to the @var{require-match} argument.  It is used
in the @code{minibuffer-complete-and-exit} function.
@end table
@end defun

@node Completion Commands, High-Level Completion, Minibuffer Completion, Completion
@subsection Minibuffer Commands That Do Completion

  This section describes the keymaps, commands and user options used in
the minibuffer to do completion.

@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 @kbd
@item ?
@code{minibuffer-completion-help}

@item SPC
@code{minibuffer-complete-word}

@item TAB
@code{minibuffer-complete}

@item LFD
@code{exit-minibuffer}

@item RET
@code{exit-minibuffer}

@item C-g
@code{abort-recursive-edit}

@end table
@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 which exits the
minibuffer unconditionally.  By default, this keymap makes the following
bindings:

@table @kbd
@item ?
@code{minibuffer-completion-help}

@item SPC
@code{minibuffer-complete-word}

@item TAB
@code{minibuffer-complete}

@item LFD
@code{minibuffer-complete-and-exit}

@item RET
@code{minibuffer-complete-and-exit}

@item C-g
@code{abort-recursive-edit}
@end table
@end defvar

@defvar minibuffer-completion-table
  The value of this variable is the alist or obarray used for completion
in the minibuffer.  This is the global variable that contains what
@code{completing-read} passes to @code{try-completion}.  It is used by
all the minibuffer completion functions, such as
@code{minibuffer-complete-word}.
@end defvar

@defvar minibuffer-completion-predicate
    The value of this variable is the predicate that
@code{completing-read} passes to @code{try-completion}.  The variable is
also used by the other minibuffer completion functions.
@end defvar

@deffn Command minibuffer-complete-word
  This function completes the minibuffer contents by at most a single
word.  Even if the minibuffer contents has only one completion,
@code{minibuffer-complete-word} will not add any characters beyond the
first character that is not a word constituent.  @xref{Syntax Tables}.
@end deffn

@deffn Command minibuffer-complete
  This function completes the minibuffer contents as far as possible.
@end deffn

@deffn Command minibuffer-complete-and-exit
  This function completes the minibuffer contents, and exits if
confirmation is not required, i.e., if
@code{minibuffer-completion-confirm} is non-@code{nil}.  If confirmation
@emph{is} required, it is given by repeating this command immediately.
@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}; the values of @code{minibuffer-completion-table}
and @code{minibuffer-completion-predicate} are used as arguments.  The
list of completions is displayed as text in a buffer named
@samp{*Completions*}.
@end deffn

@defun display-completion-list completions
  This function displays @var{completions} to the stream
@code{standard-output} (usually a buffer).  (@xref{Streams}, for more
information about streams.)  The argument @var{completions} is normally
a list of completions just returned by @code{all-completions}, but it
does not have to be.  Each element may be a symbol or a string, either
of which is simply printed, or a list of two strings, which is printed
as if the strings were concatenated.

  This function is called by @code{minibuffer-completion-help}.
@end defun

@defopt completion-auto-help
  If this variable is non-@code{nil}, the completion commands
automatically display a list of possible completions whenever nothing
can be completed because the next character is not uniquely determined.
@end defopt

@node High-Level Completion, Reading File Names, Completion Commands, Completion
@comment  node-name,  next,  previous,  up
@subsection High-Level Completion  Functions

  This section describes the higher-level convenient functions for
reading certain sorts of names with completion.

@defun read-buffer prompt &optional default existing
  This function reads the name of a buffer and returns it as a string.
The argument @var{default} is the default name to use, the value to
return if the user exits with an empty minibuffer.  If non-@code{nil},
it should be a string.  It is mentioned in the prompt, but is not
inserted in the minibuffer as initial input.

  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 will not exit if the text is not valid, and @key{RET} will do
completion to attempt to find a valid name.  (However, @var{default} is
not checked for this; it is returned, whatever it is, if the user exits
with the minibuffer empty.)

  In the following example, the user enters @samp{minibuffer.t}, and
then types @key{RET}.  The argument @var{existing} is @code{t}, and the
only buffer name starting with the given input is
@samp{minibuffer.texi}, so that name is the value.

@example
(read-buffer "Buffer name? " "foo" t)

;; @r{After evaluating the preceding expression,} 
;; @r{the following prompt appears, with an empty minibuffer:}

---------- Buffer: Minibuffer ----------
Buffer name? (default foo) @point{}
---------- Buffer: Minibuffer ----------

;; @r{The user types @kbd{minibuffer.t @key{RET}}.}

     @result{} "minibuffer.texi"
@end example
@end defun

@defun read-command prompt
  This function reads the name of a command and returns it as a Lisp
symbol.  The argument @var{prompt} is used as in
@code{read-from-minibuffer}.  Recall that a command is anything for
which @code{commandp} returns @code{t}, and a command name is a symbol
for which @code{commandp} returns @code{t}.  @xref{Interactive Call}.

@example
(read-command "Command name? ")

;; @r{After evaluating the preceding expression,} 
;; @r{the following appears in the minibuffer:}

---------- Buffer: Minibuffer ---------- 
Command name?  
---------- Buffer: Minibuffer ----------
@end example

@noindent
If the user types @kbd{forward-c @key{RET}}, then this function returns
@code{forward-char}.

  The @code{read-command} function is a simplified interface to
@code{completing-read}.  It uses the @code{commandp} predicate to allow
only commands to be entered, and it uses the variable @code{obarray} so
as to be able to complete all extant Lisp symbols:

@cindex @code{commandp} example
@example
(read-command @var{prompt})
@equiv{}
(intern (completing-read @var{prompt} obarray 'commandp t nil))
@end example
@end defun

@defun read-variable prompt
  This function reads the name of a user variable and returns it as a
symbol.

@example
(read-variable "Variable name? ")

;; @r{After evaluating the preceding expression,} 
;; @r{the following prompt appears with an empty minibuffer:}

---------- Buffer: Minibuffer ----------
Variable name? @point{}
---------- Buffer: Minibuffer ----------
@end example

@noindent
If the user then types @kbd{fill-p @key{RET}}, @code{read-variable} will
return @code{fill-prefix}.

This function is similar to @code{read-command}, but uses the
predicate @code{user-variable-p} instead of @code{commandp}:

@cindex @code{user-variable-p} example
@example
(read-variable @var{prompt})
@equiv{}
(intern (completing-read @var{prompt} obarray 'user-variable-p t nil))
@end example
@end defun

@node Reading File Names, Lisp Symbol Completion, High-Level Completion, Completion
@subsection Reading File Names

  Here is another high-level completion function, designed for reading a
file name.  It provides special features including automatic insertion
of the default directory.

@defun read-file-name prompt &optional directory default existing
  This function reads a file name in the minibuffer, prompting with
@var{prompt} and providing completion.  If @var{default} is
non-@code{nil}, then the value of @var{default} will be returned by the
function if the user just types @key{RET}.

  If @var{existing} is non-@code{nil}, then the name must refer to an
existing file; then @key{RET} performs completion to make the name valid
if possible, and then refuses to exit if it is not valid.  If the value
of @var{existing} is neither @code{nil} nor @code{t}, then @key{RET}
also requires confirmation after completion.

The argument @var{directory} specifies the directory to use for
completion of relative file names.  Usually it is inserted in the
minibuffer as initial input as well.  It defaults to the current
buffer's default directory.

Here is an example: 

@example
(read-file-name "The file is ")

;; @r{After evaluating the preceding expression,} 
;; @r{the following appears in the minibuffer:}

---------- Buffer: Minibuffer ----------
The file is /gp/gnu/elisp/@point{}
---------- Buffer: Minibuffer ----------
@end example

@noindent
Typing @kbd{manual @key{TAB}} results in the following:

@example
---------- Buffer: Minibuffer ----------
The file is /gp/gnu/elisp/manual.texi@point{}
---------- Buffer: Minibuffer ----------
@end example

@noindent
If the user types @key{RET}, @code{read-file-name} returns
@code{"/gp/gnu/elisp/manual.texi"}.
@end defun

@defopt insert-default-directory
  This variable is used by @code{read-file-name}.  The value of this
variable controls whether @code{read-file-name} starts by placing the
name of the default directory in the minibuffer.  If the value of this
variable is @code{nil}, then @code{read-file-name} does not place any
initial input in the minibuffer.  In that case, the default directory is
still used for completion of relative file names, but is not displayed.

For example:

@example
;; @r{Here the minibuffer starts out containing the default directory.}

(let ((insert-default-directory t))
  (read-file-name "The file is "))

---------- Buffer: Minibuffer ----------
The file is ~lewis/manual/@point{}
---------- Buffer: Minibuffer ----------

;; @r{Here the minibuffer is empty and only the prompt appears on its line.}

(let ((insert-default-directory nil))
  (read-file-name "The file is "))

---------- Buffer: Minibuffer ----------
The file is @point{}
---------- Buffer: Minibuffer ----------
@end example
@end defopt

@node Lisp Symbol Completion,  , Reading File Names, Completion
@subsection Lisp Symbol Completion
@cindex Lisp symbol completion
@cindex symbol completion, Lisp 
@cindex completion, Lisp symbol 

  If you type a part of a symbol, and then type @kbd{M-@key{TAB}}
(@code{lisp-complete-symbol}), it will attempt to fill in as much more
of the symbol name as it can.  Not only does this save typing, but it
can help you with the name of a symbol that you have partially
forgotten.

@deffn Command lisp-complete-symbol
  This function performs completion on the symbol name preceding point.
The name is completed against the symbols in the global variable
@code{obarray}, and characters from the completion are inserted into the
buffer, making the name longer.  If there is more than one completion, a
list of all possible completions is placed in the @samp{*Help*} buffer.
The bell rings if there is no possible completion in @code{obarray}.

  If an open parenthesis immediately precedes the name, only symbols
with function definitions are considered.  (By reducing the number of
alternatives, this may succeed in completing more characters.)
Otherwise, symbols with either a function definition, a value, or at
least one property are considered.

  @code{lisp-complete-symbol} returns @code{t} if the symbol had an exact, 
and unique, match; otherwise, it returns @code{nil}.

  In the following example, the user has already inserted @samp{(forwa}
into the buffer @file{foo.el}.  The command @code{lisp-complete-symbol}
then completes the name to @samp{(forward-}.

@example
---------- Buffer: foo.el ----------
(forwa@point{}
---------- Buffer: foo.el ----------

(lisp-complete-symbol)
     @result{} nil

---------- Buffer: foo.el ----------
(forward-@point{}
---------- Buffer: foo.el ----------
@end example
@end deffn

@node Yes-or-No Queries, Minibuffer Misc, Completion, Minibuffers
@section Yes-or-No Queries
@cindex asking the user questions
@cindex querying the user
@cindex yes-or-no questions

  This section describes functions used to ask the user a yes-or-no
question.  The function @code{y-or-n-p} can be answered with a single
character; it is useful for questions where an inadvertent wrong answer
will not have serious consequences.  @code{yes-or-no-p} is suitable for
more momentous questions, since it requires three or four characters to
answer.

  Strictly speaking, @code{yes-or-no-p} uses the minibuffer and
@code{y-or-n-p} does not; but it seems best to describe them together.

@defun y-or-n-p prompt
  This function asks the user a question, expecting input in the echo
area.  It returns @code{t} if the user types @kbd{y}, @code{nil} if the
user types @kbd{n}.  This function also accepts @key{SPC} to mean yes
and @key{DEL} to mean no.  The answer is a single character, with no
@key{RET} needed to terminate it.  Upper and lower case are equivalent.

  ``Asking the question'' means printing @var{prompt} in the echo area,
followed by the string @w{@samp{(y or n) }}.  If the input is not one of the
expected answers (@kbd{y}, @kbd{n}, @kbd{@key{SPC}}, or
@kbd{@key{DEL}}), the function responds @samp{Please answer y or n.},
and repeats the request.

  This function does not actually use the minibuffer, since it does not
allow editing of the answer.  It actually uses the echo area (@pxref{The
Echo Area}), which uses the same screen space as the minibuffer.  The
cursor moves to the echo area while the question is being asked.

  In the following example, the user first types @kbd{q}, which is
invalid.  At the next prompt the user types @kbd{n}.

@example
(y-or-n-p "Do you need a lift? ")

;; @r{After evaluating the preceding expression,} 
;; @r{the following prompt appears in the echo area:}

@group
---------- Echo area ----------
Do you need a lift? (y or n) 
---------- Echo area ----------
@end group

;; @r{If the user then types @kbd{q}, the following appears:}

@group
---------- Echo area ----------
Please answer y or n.  Do you need a lift? (y or n) 
---------- Echo area ----------
@end group

;; @r{When the user types a valid answer, it is displayed after the question:}

@group
---------- Echo area ----------
Do you need a lift? (y or n) y
---------- Echo area ----------
@end group
@end example

@noindent
Note that we show successive lines of echo area messages here.  Only one
will appear on the screen at a time.
@end defun

@defun yes-or-no-p prompt
  This function asks the user a question, expecting input in minibuffer.
It returns @code{t} if the user enters @samp{yes}, @code{nil} if the
user types @samp{no}.  The user must type @key{RET} to finalize the
response.  Upper and lower case are equivalent.

  @code{yes-or-no-p} starts by displaying @var{prompt} in the echo area,
followed by @w{@samp{(yes or no) }}.  The user must type one of the
expected responses; otherwise, the function responds @samp{Please answer
yes or no.}, waits about two seconds and repeats the request.

  @code{yes-or-no-p} requires more work from the user than
@code{y-or-n-p} and is appropriate for more crucial decisions.

Here is an example:

@example
(yes-or-no-p "Do you really want to remove your entire directory? ")

;; @r{After evaluating the preceding expression,} 
;; @r{the following prompt appears with an empty minibuffer:}

---------- Buffer: minibuffer ----------
Do you really want to remove your entire directory? (yes or no) 
---------- Buffer: minibuffer ----------
@end example

@noindent
If the user first types @kbd{y @key{RET}}, which is invalid because this
function demands the entire word @samp{yes}, it responds by displaying
these prompts, with a brief pause between them:

@example
---------- Buffer: minibuffer ----------
Please answer yes or no.
Do you really want to remove your entire directory? (yes or no)
---------- Buffer: minibuffer ----------
@end example
@end defun

@node Minibuffer Misc,  , Yes-or-No Queries, Minibuffers
@comment  node-name,  next,  previous,  up
@section Minibuffer Miscellany

  Some basic minibuffer functions and variables are described in this
section.

@deffn Command exit-minibuffer
  This function exits the active minibuffer.  It is normally bound to
keys in minibuffer local keymaps.
@end deffn

@deffn Command self-insert-and-exit
  This function exits the active minibuffer after inserting the last
character typed on the keyboard (found in @code{last-command-char};
@pxref{Command Loop Info}).
@end deffn

@defvar 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 minibuffer-window
  This function returns the window that is used for the minibuffer.
There is one and only one minibuffer window in Emacs 18; this window
always exists and cannot be deleted.
@end defun

@defvar 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 will scroll the @code{minibuffer-scroll-window}
window.
@end defvar

Finally, some functions and variables deal with recursive minibuffers
(@pxref{Recursive Editing}):

@defun minibuffer-depth
  This function returns the current depth of activations of the
minibuffer, a nonnegative integer.  If no minibuffers are active, it
returns zero.
@end defun

@defopt enable-recursive-minibuffers
  If this variable is non-@code{nil}, you can invoke commands (such as
@code{find-file}) which use minibuffers even while in the minibuffer
window.  Such invocation produces a recursive editing level for a new
minibuffer.  The outer-level minibuffer is invisible while you are
editing the inner one.

This variable only affects invoking the minibuffer while the
minibuffer window is selected.   If you switch windows while in the 
minibuffer, you can always invoke minibuffer commands while some other
window is selected.
@end defopt

