@c -*-texinfo-*-
@c This is part of the XEmacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc. 
@c See the file lispref.texi for copying conditions.
@setfilename ../../info/minibuf.info
@node Minibuffers, Command Loop, Streams, Top
@chapter Minibuffers
@cindex arguments, reading
@cindex complex arguments
@cindex minibuffer

  A @dfn{minibuffer} is a special buffer that XEmacs 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.

@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.
* Minibuffer History::	      Recording previous minibuffer inputs
				so the user can reuse them.
* Completion::                How to invoke and customize completion.
* Yes-or-No Queries::         Asking a question with a simple answer.
* Multiple Queries::	      Asking a series of similar questions.
* Minibuffer Misc::           Various customization hooks and variables.
@end menu

@node Intro to Minibuffers
@section Introduction to Minibuffers

  In most ways, a minibuffer is a normal XEmacs 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.  Minibuffers are
displayed only in special windows used only for minibuffers; these
windows always appear at the bottom of a frame.  (Sometime frames have
no minibuffer window, and sometimes a special kind of frame contains
nothing but a minibuffer window; see @ref{Minibuffers and Frames}.)

  The minibuffers window is normally a single line; you can resize it
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.  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}).

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

@node Text from Minibuffer
@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 hist
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 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 XEmacs editing
commands.

@c Emacs 19 feature
The value of @var{initial} may also be a cons cell of the form
@code{(@var{string} . @var{position})}.  This means to insert
@var{string} in the minibuffer but put the cursor @var{position}
characters from the beginning, rather than at the end.

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.

The argument @var{hist} specifies which history list variable to use
for saving the input and for history commands used in the minibuffer.
It defaults to @code{minibuffer-history}.  @xref{Minibuffer History}.

When the user types a command to exit the minibuffer, the current
minibuffer contents are usually made into a string which becomes the
value of @code{read-from-minibuffer}.  However, if @var{read} is
non-@code{nil}, @code{read-from-minibuffer} converts the result to a
Lisp object, and 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:

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

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:

@smallexample
@group
(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 group
@end smallexample

This technique is no longer preferred for most applications; it is
usually better to use a history list.
@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 is a simplified interface to the
@code{read-from-minibuffer} function:

@smallexample
@group
(read-string @var{prompt} @var{initial})
@equiv{}
(read-from-minibuffer @var{prompt} @var{initial} nil nil)
@end group
@end smallexample
@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}

@item @kbd{M-n} and @kbd{M-p}
@code{next-history-element} and @code{previous-history-element}

@item @kbd{M-r}
@code{next-matching-history-element}

@item @kbd{M-s}
@code{previous-matching-history-element}
@end table
@end defvar

@c In version 18, initial is required
@c Emacs 19 feature
@defun read-no-blanks-input prompt &optional 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 is a simplified interface to the @code{read-from-minibuffer}
function, and passes the value of the @code{minibuffer-local-ns-map}
keymap 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.

@smallexample
@group
(read-no-blanks-input @var{prompt} @var{initial})
@equiv{}
(read-from-minibuffer @var{prompt} @var{initial} minibuffer-local-ns-map)
@end group
@end smallexample
@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 @asis
@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 @kbd{C-g}
@code{abort-recursive-edit}

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

@item @kbd{M-n} and @kbd{M-p}
@code{next-history-element} and @code{previous-history-element}

@item @kbd{M-r}
@code{next-matching-history-element}

@item @kbd{M-s}
@code{previous-matching-history-element}
@end table
@end defvar

@node Object from Minibuffer
@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,
without evaluating it.  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 is a simplified interface to the
@code{read-from-minibuffer} function:

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

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

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

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

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

@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}:

@smallexample
@group
(eval-minibuffer @var{prompt} @var{initial})
@equiv{}
(eval (read-minibuffer @var{prompt} @var{initial}))
@end group
@end smallexample
@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{"})
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.  Then it inserts the printed
representation of @var{form} in the minibuffer, and lets the user 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:

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

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

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

@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 Minibuffer History
@section Minibuffer History
@cindex minibuffer history
@cindex history list

A minibuffer history list records previous minibuffer inputs so the user
can reuse them conveniently.  There are many separate history lists
which contain different kinds of inputs.  The Lisp programmer's job is
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:

@table @asis
@item @var{variable}
If you specify a variable (a symbol), that variable is the history
list.

@item (@var{variable} . @var{startpos})
If you specify a cons cell of this form, then @var{variable} is the
history list variable, and @var{startpos} specifies the initial history
position (an integer, counting from zero which specifies the most recent
element of the history).

If you specify @var{startpos}, then you should also specify that element
of the history as @var{initial}, for consistency.
@end table

If you don't specify @var{hist}, then the default history list
@code{minibuffer-history} is used.  For other standard history lists,
see below.  You can also create your own history list variable; just
initialize it to @code{nil} before the first use.  The value of the
history list variable is a list of strings, most recent first.

Both @code{read-from-minibuffer} and @code{completing-read} add new
elements to the history list automatically, and provide commands to
allow the user to reuse items on the list.  The only thing your program
needs to do to use a history list is to initialize it and to pass its
name to the input functions when you wish.  But it is safe to modify the
list by hand when the minibuffer input functions are not using it.

@defvar minibuffer-history
The default history list for minibuffer history input.
@end defvar

@defvar query-replace-history
A history list for arguments to @code{query-replace} (and similar
arguments to other commands).
@end defvar

@defvar file-name-history
A history list for file name arguments.
@end defvar

@node Completion
@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}),
XEmacs extends the name as far as it can.  Standard XEmacs 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
@subsection Basic Completion Functions

@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 an alist, an obarray, or a function which
implements a virtual set of strings.

  If @var{collection} is an alist (@pxref{Association Lists}),
completion compares the @sc{car} of each cons cell in it 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, the
value is the longest initial sequence common to all the matching strings
in the alist.

@cindex obarray in completion
  If @var{collection} is an obarray (@pxref{Creating Symbols}), the
names of all symbols in the obarray form the space of possible
completions.  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.)

  Note that the only valid way to make a new obarray is to create it
empty and then add symbols to it one by one using @code{intern}.
Also, you cannot intern a given symbol in more than one obarray.

  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 symbol as @var{collection}.
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}.

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

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

  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.

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

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

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

@defun all-completions string collection &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{collection} 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 function @code{test} shown in the
example for @code{try-completion}:

@smallexample
@group
(defun test (s) 
  (> (length (car s)) 6))
     @result{} test
@end group

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

@defvar completion-ignore-case
  If the value of this variable is 
non-@code{nil}, XEmacs 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
@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 a symbol with a function definition as the
@var{collection} argument to @code{completing-read}.  This command
arranges 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 predicate 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

  It would be consistent and clean for completion functions to allow
lambda expressions (lists which are functions) as well as function
symbols as @var{collection}, but this is impossible.  Lists as
completion tables are already assigned another meaning---as alists.  It
would be unreliable to fail to handle an alist normally because it is
also a possible function.  So you must arrange for any function you wish
to use for completion to be encapsulated in a symbol.

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

@node Minibuffer Completion
@subsection Completion and the Minibuffer

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

@defun completing-read prompt collection &optional predicate require-match initial hist
  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{collection} 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 is not allowed to exit
unless the input completes to an element of @var{collection}.  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{collection}.  To accomplish this, @code{completing-read}
calls @code{read-minibuffer}.  It uses the value of
@code{minibuffer-local-completion-map} as the keymap if
@var{require-match} is @code{nil}, and uses
@code{minibuffer-local-must-match-map} if @var{require-match} is
non-@code{nil}.

The argument @var{hist} specifies which history list variable to use for
saving the input and for minibuffer history commands.  It defaults to
@code{minibuffer-history}.  @xref{Minibuffer History}.

  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:

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

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

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

@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 the @var{collection} 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
@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 @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}.
@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 @asis
@item @kbd{?}
@code{minibuffer-completion-help}

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

@item @key{TAB}
@code{minibuffer-complete}

@item @key{LFD}
@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 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
This variable's value 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 have only one completion,
@code{minibuffer-complete-word} does 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}, XEmacs 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}
using the value of the variable @code{minibuffer-completion-table} as
the @var{collection} argument, and the value of
@code{minibuffer-completion-predicate} as the @var{predicate} argument.
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 in
@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}.  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)))
@end example
@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
@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 do not exit if the text is not valid, and @key{RET} does
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.

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

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

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

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

     @result{} "minibuffer.texi"
@end group
@end smallexample
@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}.

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

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

@group
---------- Buffer: Minibuffer ---------- 
Command name?  
---------- Buffer: Minibuffer ----------
@end group
@end smallexample

@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 the
@code{completing-read} function.  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
@smallexample
@group
(read-command @var{prompt})
@equiv{}
(intern (completing-read @var{prompt} obarray 'commandp t nil))
@end group
@end smallexample
@end defun

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

@smallexample
@group
(read-variable "Variable name? ")

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

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

@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
@smallexample
@group
(read-variable @var{prompt})
@equiv{}
(intern
 (completing-read @var{prompt} obarray 'user-variable-p t nil))
@end group
@end smallexample
@end defun

@node Reading File Names
@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 initial
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 function returns @var{default} 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.

@c Emacs 19 feature
If you specify @var{initial}, that is an initial file name to insert in
the buffer along with @var{directory}.  In this case, point goes after
@var{directory}, before @var{initial}.  The default for @var{initial} is
@code{nil}---don't insert any file name.  To see what @var{initial}
does, try the command @kbd{C-x C-v}.

Here is an example: 

@smallexample
@group
(read-file-name "The file is ")

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

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

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

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

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

@defopt insert-default-directory
This variable is used by @code{read-file-name}.  Its value controls
whether @code{read-file-name} starts by placing the name of the default
directory in the minibuffer, plus the initial file name if any.  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:

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

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

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

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

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

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

@node Lisp Symbol 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}), this command attempts 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-}.

@smallexample
@group
---------- Buffer: foo.el ----------
(forwa@point{}
---------- Buffer: foo.el ----------
@end group

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

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

@node Yes-or-No Queries
@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.  Variations of these functions can be used to ask a yes-or-no
question using a dialog box, or optionally using one.

  Strictly speaking, not all of these functions use the minibuffer; 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.  It accepts @kbd{C-]} to mean ``quit'', like
@kbd{C-g}, because the question might look like a minibuffer and for
that reason the user might try to use @kbd{C-]} to get out.  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}},
@kbd{@key{DEL}}, or something that quits), 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.

  The meanings of answers, even @samp{y} and @samp{n}, are not
hardwired.  They are controlled by the keymap @code{query-replace-map}.
@xref{Replacement}.

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

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

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

@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,}
;;   @r{it is displayed after the question:}

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

@noindent
Note that we show successive lines of echo area messages here.  Only one
actually appears 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:

@smallexample
@group
(yes-or-no-p "Do you really want to remove everything? ")

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

@group
---------- Buffer: minibuffer ----------
Do you really want to remove everything? (yes or no) 
---------- Buffer: minibuffer ----------
@end group
@end smallexample

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

@smallexample
@group
---------- Buffer: minibuffer ----------
Please answer yes or no.
Do you really want to remove everything? (yes or no)
---------- Buffer: minibuffer ----------
@end group
@end smallexample
@end defun

@c The rest is XEmacs stuff
@defun yes-or-no-p-dialog-box prompt
This function asks the user a ``y or n'' question with a popup dialog
box.  It returns @code{t} if the answer is ``yes''.  @var{prompt} is the
string to display to ask the question.
@end defun

The following functions ask a question either in the minibuffer or a
dialog box, depending on whether the last user event (which presumably
invoked this command) was a keyboard or mouse event.  When XEmacs is
running on a window system, the functions @code{y-or-n-p} and
@code{yes-or-no-p} are replaced with the following functions, so that
menu items bring up dialog boxes instead of minibuffer questions.

@defun y-or-n-p-maybe-dialog-box prompt
This function asks user a ``y or n'' question, using either a dialog box
or the minibuffer, as appropriate.
@end defun

@defun yes-or-no-p-maybe-dialog-box prompt
This function asks user a ``yes or no'' question, using either a dialog
box or the minibuffer, as appropriate.
@end defun

@node Multiple Queries
@section Asking Multiple Y-or-N Queries

@defun map-y-or-n-p prompter actor list &optional help action-alist
This function, new in Emacs 19, asks the user a series of questions,
reading a single-character answer in the echo area for each one.

The value of @var{list} specifies what varies from question to question
within the series.  It should be either a list of objects or a generator
function.  If it is a function, it should expect no arguments, and
should return either the next object or @code{nil} meaning there are no
more questions.

The argument @var{prompter} specifies how to ask each question.  If
@var{prompter} is a string, the question text is computed like this:

@example
(format @var{prompter} @var{object})
@end example

@noindent
where @var{object} is the next object to ask about (as obtained from
@var{list}).

If not a string, @var{prompter} should be a function of one argument
(the next object to ask about) and should return the question text.

The argument @var{actor} says how to act on the answers that the user
gives.  It should be a function of one argument, and it is called with
each object that the user says yes for.  Its argument is always an
object obtained from @var{list}.

If the argument @var{help} is given, it should be a list of this form:

@example
(@var{singular} @var{plural} @var{action})
@end example

@noindent
where @var{singular} is a string containing a singular noun that
describes the objects conceptually being acted on, @var{plural} is the
corresponding plural noun, and @var{action} is a transitive verb
describing what @var{actor} does.

If you don't specify @var{help}, the default is @code{("object"
"objects" "act on")}.

Each time a question is asked, the user may enter @kbd{y}, @kbd{Y}, or
@key{SPC} to act on that object; @kbd{n}, @kbd{N}, or @key{DEL} to skip
that object; @kbd{!} to act on all following objects; @key{ESC} or
@kbd{q} to exit (skip all following objects); @kbd{.} (period) to act on
the current object and then exit; or @kbd{C-h} to get help.  These are
the same answers that @code{query-replace} accepts.  The keymap
@code{query-replace-map} defines their meaning for @code{map-y-or-n-p}
as well as for @code{query-replace}; see @ref{Replacement}.

You can use @var{action-alist} to specify additional possible answers
and what they mean.  It is an alist of elements of the form
@code{(@var{char} @var{function} @var{help})}, each of which defines one
additional answer.  In this element, @var{char} is a character (the
answer); @var{function} is a function of one argument (an object from
@var{list}); @var{help} is a string.

When the user responds with @var{char}, @code{map-y-or-n-p} calls
@var{function}.  If it returns non-@code{nil}, the object is considered
``acted upon'', and @code{map-y-or-n-p} advances to the next object in
@var{list}.  If it returns @code{nil}, the prompt is repeated for the
same object.

The return value of @code{map-y-or-n-p} is the number of objects acted on.
@end defun

@node Minibuffer Misc
@section Minibuffer Miscellany

  This section describes some basic functions and variables related to
minibuffers.

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

@deffn Command self-insert-and-exit
This command 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

@deffn Command previous-history-element n
This command replaces the minibuffer contents with the value of the
@var{n}th previous (older) history element.
@end deffn

@deffn Command next-history-element n
This command replaces the minibuffer contents with the value of the
@var{n}th more recent history element.
@end deffn

@deffn Command previous-matching-history-element pattern
This command replaces the minibuffer contents with the value of the
previous (older) history element that matches @var{pattern}.  At the
time of printing, we have not made a final decision about how to get the
pattern interactively or how to match it against history elements.
@end deffn

@deffn Command next-matching-history-element pattern
This command replaces the minibuffer contents with the value of the
next (newer) history element that matches @var{pattern}.
@end deffn

@defvar minibuffer-setup-hook
This is a normal hook that is run whenever the minibuffer is entered.
@end defvar

@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 &optional frame
This function returns the window that is used for the minibuffer.  In
Emacs 18, there is one and only one minibuffer window; this window
always exists and cannot be deleted.  In Emacs 19, each frame can have
its own minibuffer, and this function returns the minibuffer window used
for frame @var{frame} (which defaults to the currently selected frame).
@end defun

@c Emacs 19 feature
@defun window-minibuffer-p window
This function returns non-@code{nil} if @var{window} is a minibuffer window.
@end defun

It is not correct to determine whether a given window is a minibuffer by
comparing it with the result of @code{(minibuffer-window)}, because
there can be more than one minibuffer window there is more than one
frame.

@defun minibuffer-window-active-p window
This function returns non-@code{nil} if @var{window}, assumed to be
a minibuffer window, is currently active.
@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 scrolls this 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

@c Emacs 19 feature
If a command name has a property @code{enable-recursive-minibuffers}
which is non-@code{nil}, then the command can use the minibuffer to read
arguments even if it is invoked from the minibuffer.  The minibuffer
command @code{next-matching-history-element} (normally bound to
@kbd{M-s} in the minibuffer) uses this feature.
