Commit 793da230 authored by Richard M. Stallman's avatar Richard M. Stallman
Browse files

*** empty log message ***

parent e333e864
...@@ -41,7 +41,7 @@ windows always appear at the bottom of a frame. (Sometime frames have ...@@ -41,7 +41,7 @@ windows always appear at the bottom of a frame. (Sometime frames have
no minibuffer window, and sometimes a special kind of frame contains no minibuffer window, and sometimes a special kind of frame contains
nothing but a minibuffer window; see @ref{Minibuffers and Frames}.) nothing but a minibuffer window; see @ref{Minibuffers and Frames}.)
The minibuffers window is normally a single line. You can resize it The minibuffer's window is normally a single line. You can resize it
temporarily with the window sizing commands; it reverts to its normal temporarily with the window sizing commands; it reverts to its normal
size when the minibuffer is exited. You can resize it permanently by size when the minibuffer is exited. You can resize it permanently by
using the window sizing commands in the frame's other window, when the using the window sizing commands in the frame's other window, when the
...@@ -82,10 +82,10 @@ for cautious completion. ...@@ -82,10 +82,10 @@ for cautious completion.
@node Text from Minibuffer @node Text from Minibuffer
@section Reading Text Strings with the Minibuffer @section Reading Text Strings with the Minibuffer
Most often, the minibuffer is used to read text which is returned as a Most often, the minibuffer is used to read text as a string. It can
string. It can also be used to read a Lisp object in textual form. The also be used to read a Lisp object in textual form. The most basic
most basic primitive for minibuffer input is primitive for minibuffer input is @code{read-from-minibuffer}; it can do
@code{read-from-minibuffer}; it can do either one. either one.
@defun read-from-minibuffer prompt-string &optional initial-contents keymap read hist @defun read-from-minibuffer prompt-string &optional initial-contents keymap read hist
This function is the most general way to get input through the This function is the most general way to get input through the
...@@ -140,7 +140,7 @@ This is a simplified interface to the ...@@ -140,7 +140,7 @@ This is a simplified interface to the
@group @group
(read-string @var{prompt} @var{initial}) (read-string @var{prompt} @var{initial})
@equiv{} @equiv{}
(read-from-minibuffer @var{prompt} @var{initial} nil nil) (read-from-minibuffer @var{prompt} @var{initial} nil nil nil)
@end group @end group
@end smallexample @end smallexample
@end defun @end defun
...@@ -223,8 +223,11 @@ following bindings: ...@@ -223,8 +223,11 @@ following bindings:
@cindex @kbd{?} in minibuffer @cindex @kbd{?} in minibuffer
@code{self-insert-and-exit} @code{self-insert-and-exit}
@item @kbd{M-n} and @kbd{M-p} @item @kbd{M-n}
@code{next-history-element} and @code{previous-history-element} @code{next-history-element}
@item @kbd{M-p}
@code{previous-history-element}
@item @kbd{M-r} @item @kbd{M-r}
@code{next-matching-history-element} @code{next-matching-history-element}
...@@ -241,12 +244,11 @@ following bindings: ...@@ -241,12 +244,11 @@ following bindings:
minibuffer. minibuffer.
@defun read-minibuffer prompt &optional initial @defun read-minibuffer prompt &optional initial
This function reads a Lisp object in the minibuffer and returns it, This function reads a Lisp object in the minibuffer and returns it,
without evaluating it. The arguments @var{prompt} and @var{initial} are without evaluating it. The arguments @var{prompt} and @var{initial} are
used as in @code{read-from-minibuffer}; in particular, @var{initial} used as in @code{read-from-minibuffer}.
must be a string or @code{nil}.
This is a simplified interface to the This is a simplified interface to the
@code{read-from-minibuffer} function: @code{read-from-minibuffer} function:
@smallexample @smallexample
...@@ -281,11 +283,11 @@ default, or can edit the input. ...@@ -281,11 +283,11 @@ default, or can edit the input.
@end defun @end defun
@defun eval-minibuffer prompt &optional initial @defun eval-minibuffer prompt &optional initial
This function reads a Lisp expression in the minibuffer, evaluates it, This function reads a Lisp expression in the minibuffer, evaluates it,
then returns the result. The arguments @var{prompt} and @var{initial} then returns the result. The arguments @var{prompt} and @var{initial}
are used as in @code{read-from-minibuffer}. are used as in @code{read-from-minibuffer}.
This function simply evaluates the result of a call to This function simply evaluates the result of a call to
@code{read-minibuffer}: @code{read-minibuffer}:
@smallexample @smallexample
...@@ -298,7 +300,7 @@ are used as in @code{read-from-minibuffer}. ...@@ -298,7 +300,7 @@ are used as in @code{read-from-minibuffer}.
@end defun @end defun
@defun edit-and-eval-command prompt form @defun edit-and-eval-command prompt form
This function reads a Lisp expression in the minibuffer, and then This function reads a Lisp expression in the minibuffer, and then
evaluates it. The difference between this command and evaluates it. The difference between this command and
@code{eval-minibuffer} is that here the initial @var{form} is not @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 optional and it is treated as a Lisp object to be converted to printed
...@@ -306,21 +308,21 @@ representation rather than as a string of text. It is printed with ...@@ -306,21 +308,21 @@ representation rather than as a string of text. It is printed with
@code{prin1}, so if it is a string, double-quote characters (@samp{"}) @code{prin1}, so if it is a string, double-quote characters (@samp{"})
appear in the initial text. @xref{Output Functions}. appear in the initial text. @xref{Output Functions}.
The first thing @code{edit-and-eval-command} does is to activate the 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 minibuffer with @var{prompt} as the prompt. Then it inserts the printed
representation of @var{form} in the minibuffer, and lets the user edit. representation of @var{form} in the minibuffer, and lets the user edit.
When the user exits the minibuffer, the edited text is read with When the user exits the minibuffer, the edited text is read with
@code{read} and then evaluated. The resulting value becomes the value @code{read} and then evaluated. The resulting value becomes the value
of @code{edit-and-eval-command}. of @code{edit-and-eval-command}.
In the following example, we offer the user an expression with initial In the following example, we offer the user an expression with initial
text which is a valid form already: text which is a valid form already:
@smallexample @smallexample
@group @group
(edit-and-eval-command "Please edit: " '(forward-word 1)) (edit-and-eval-command "Please edit: " '(forward-word 1))
;; @r{After evaluating the preceding expression,} ;; @r{After evaluation of the preceding expression,}
;; @r{the following appears in the minibuffer:} ;; @r{the following appears in the minibuffer:}
@end group @end group
...@@ -343,9 +345,9 @@ expression, thus moving point forward one word. ...@@ -343,9 +345,9 @@ expression, thus moving point forward one word.
@cindex history list @cindex history list
A @dfn{minibuffer history list} records previous minibuffer inputs so A @dfn{minibuffer history list} records previous minibuffer inputs so
the user can reuse them conveniently. A history list is a symbol, a the user can reuse them conveniently. A history list is actually a
variable whose value is a list of strings (previous inputs), most recent symbol, not a list; it is a variable whose value is a list of strings
first. (previous inputs), most recent first.
There are many separate history lists, used for different kinds of There are many separate history lists, used for different kinds of
inputs. It's the Lisp programmer's job to specify the right history inputs. It's the Lisp programmer's job to specify the right history
...@@ -452,10 +454,15 @@ for reading certain kinds of names with completion. ...@@ -452,10 +454,15 @@ for reading certain kinds of names with completion.
@node Basic Completion @node Basic Completion
@subsection Basic Completion Functions @subsection Basic Completion Functions
The two functions @code{try-completion} and @code{all-completions}
have nothing in themselves to do with minibuffers. We describe them in
this chapter so as to keep them near the higher-level completion
features that do use the minibuffer.
@defun try-completion string collection &optional predicate @defun try-completion string collection &optional predicate
This function returns the longest common substring of all possible This function returns the longest common substring of all possible
completions of @var{string} in @var{collection}. The value of completions of @var{string} in @var{collection}. The value of
@var{collection} must be an alist, an obarray, or a function which @var{collection} must be an alist, an obarray, or a function that
implements a virtual set of strings (see below). implements a virtual set of strings (see below).
Completion compares @var{string} against each of the permissible Completion compares @var{string} against each of the permissible
...@@ -487,8 +494,8 @@ The argument given to @var{predicate} is either a cons cell from the alist ...@@ -487,8 +494,8 @@ 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 (the @sc{car} of which is a string) or else it is a symbol (@emph{not} a
symbol name) from the obarray. symbol name) from the obarray.
You can also use a function symbol as @var{collection}. Then the You can also use a symbol that is a function as @var{collection}. Then
function is solely responsible for performing completion; the function is solely responsible for performing completion;
@code{try-completion} returns whatever this function returns. The @code{try-completion} returns whatever this function returns. The
function is called with three arguments: @var{string}, @var{predicate} function is called with three arguments: @var{string}, @var{predicate}
and @code{nil}. (The reason for the third argument is so that the same and @code{nil}. (The reason for the third argument is so that the same
...@@ -541,7 +548,7 @@ too short). Both of those begin with the string @samp{foobar}. ...@@ -541,7 +548,7 @@ too short). Both of those begin with the string @samp{foobar}.
(try-completion (try-completion
"foo" "foo"
'(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)) '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
'test) 'test)
@result{} "foobar" @result{} "foobar"
@end group @end group
@end smallexample @end smallexample
...@@ -570,7 +577,7 @@ example for @code{try-completion}: ...@@ -570,7 +577,7 @@ example for @code{try-completion}:
(all-completions (all-completions
"foo" "foo"
'(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)) '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
(function test)) 'test)
@result{} ("foobar1" "foobar2") @result{} ("foobar1" "foobar2")
@end group @end group
@end smallexample @end smallexample
...@@ -581,11 +588,6 @@ If the value of this variable is ...@@ -581,11 +588,6 @@ If the value of this variable is
non-@code{nil}, Emacs does not consider case significant in completion. non-@code{nil}, Emacs does not consider case significant in completion.
@end defvar @end defvar
The two functions @code{try-completion} and @code{all-completions}
have nothing in themselves to do with minibuffers. We describe them in
this chapter so as to keep them near the higher-level completion
features that do use the minibuffer.
@node Minibuffer Completion @node Minibuffer Completion
@subsection Completion and the Minibuffer @subsection Completion and the Minibuffer
...@@ -608,13 +610,14 @@ If @var{require-match} is @code{t}, the usual minibuffer exit commands ...@@ -608,13 +610,14 @@ If @var{require-match} is @code{t}, the usual minibuffer exit commands
won't exit unless the input completes to an element of @var{collection}. won't exit unless the input completes to an element of @var{collection}.
If @var{require-match} is neither @code{nil} nor @code{t}, then the exit If @var{require-match} is neither @code{nil} nor @code{t}, then the exit
commands won't exit unless the input typed is itself an element of commands won't exit unless the input typed is itself an element of
@var{collection}. @var{collection}. If @var{require-match} is @code{nil}, the exit
commands work regardless of the input in the minibuffer.
The function @code{completing-read} works by calling The function @code{completing-read} works by calling
@code{read-minibuffer}. It uses @code{minibuffer-local-completion-map} @code{read-minibuffer}. It uses @code{minibuffer-local-completion-map}
as the keymap if @var{require-match} is @code{nil}, and uses as the keymap if @var{require-match} is @code{nil}, and uses
@code{minibuffer-local-must-match-map} if @var{require-match} is @code{minibuffer-local-must-match-map} if @var{require-match} is
non-@code{nil}. non-@code{nil}. @xref{Completion Commands}.
The argument @var{hist} specifies which history list variable to use for The argument @var{hist} specifies which history list variable to use for
saving the input and for minibuffer history commands. It defaults to saving the input and for minibuffer history commands. It defaults to
...@@ -635,7 +638,7 @@ Here's an example of using @code{completing-read}: ...@@ -635,7 +638,7 @@ Here's an example of using @code{completing-read}:
@end group @end group
@group @group
;; @r{After evaluating the preceding expression,} ;; @r{After evaluation of the preceding expression,}
;; @r{the following appears in the minibuffer:} ;; @r{the following appears in the minibuffer:}
---------- Buffer: Minibuffer ---------- ---------- Buffer: Minibuffer ----------
...@@ -649,22 +652,11 @@ If the user then types @kbd{@key{DEL} @key{DEL} b @key{RET}}, ...@@ -649,22 +652,11 @@ If the user then types @kbd{@key{DEL} @key{DEL} b @key{RET}},
@code{completing-read} returns @code{barfoo}. @code{completing-read} returns @code{barfoo}.
The @code{completing-read} function binds three variables to pass The @code{completing-read} function binds three variables to pass
information to the commands which actually do completion. Here they information to the commands that actually do completion. These
are: variables are @code{minibuffer-completion-table},
@code{minibuffer-completion-predicate} and
@table @code @code{minibuffer-completion-confirm}. For more information about them,
@item minibuffer-completion-table see @ref{Completion Commands}.
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 @end defun
@node Completion Commands @node Completion Commands
...@@ -674,7 +666,7 @@ in the @code{minibuffer-complete-and-exit} function. ...@@ -674,7 +666,7 @@ in the @code{minibuffer-complete-and-exit} function.
the minibuffer to do completion. the minibuffer to do completion.
@defvar minibuffer-local-completion-map @defvar minibuffer-local-completion-map
@code{completing-read} uses this value as the local keymap when an @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 exact match of one of the completions is not required. By default, this
keymap makes the following bindings: keymap makes the following bindings:
...@@ -690,13 +682,14 @@ keymap makes the following bindings: ...@@ -690,13 +682,14 @@ keymap makes the following bindings:
@end table @end table
@noindent @noindent
with other characters bound as in @code{minibuffer-local-map}. with other characters bound as in @code{minibuffer-local-map}
(@pxref{Text from Minibuffer}).
@end defvar @end defvar
@defvar minibuffer-local-must-match-map @defvar minibuffer-local-must-match-map
@code{completing-read} uses this value as the local keymap when an @code{completing-read} uses this value as the local keymap when an
exact match of one of the completions is required. Therefore, no keys exact match of one of the completions is required. Therefore, no keys
are bound to @code{exit-minibuffer}, the command which exits the are bound to @code{exit-minibuffer}, the command that exits the
minibuffer unconditionally. By default, this keymap makes the following minibuffer unconditionally. By default, this keymap makes the following
bindings: bindings:
...@@ -749,7 +742,9 @@ This function completes the minibuffer contents as far as possible. ...@@ -749,7 +742,9 @@ This function completes the minibuffer contents as far as possible.
This function completes the minibuffer contents, and exits if This function completes the minibuffer contents, and exits if
confirmation is not required, i.e., if confirmation is not required, i.e., if
@code{minibuffer-completion-confirm} is non-@code{nil}. If confirmation @code{minibuffer-completion-confirm} is non-@code{nil}. If confirmation
@emph{is} required, it is given by repeating this command immediately. @emph{is} required, it is given by repeating this command
immediately---the command is programmed to work without confirmation
when run twice in succession.
@end deffn @end deffn
@defvar minibuffer-completion-confirm @defvar minibuffer-completion-confirm
...@@ -809,11 +804,11 @@ it should be a string or a buffer. It is mentioned in the prompt, but ...@@ -809,11 +804,11 @@ it should be a string or a buffer. It is mentioned in the prompt, but
is not inserted in the minibuffer as initial input. is not inserted in the minibuffer as initial input.
If @var{existing} is non-@code{nil}, then the name specified must be If @var{existing} is non-@code{nil}, then the name specified must be
that of an existing buffer. The usual commands to exit the that of an existing buffer. The usual commands to exit the minibuffer
minibuffer do not exit if the text is not valid, and @key{RET} does do not exit if the text is not valid, and @key{RET} does completion to
completion to attempt to find a valid name. (However, @var{default} is attempt to find a valid name. (However, @var{default} is not checked
not checked for this; it is returned, whatever it is, if the user exits for validity; it is returned, whatever it is, if the user exits with the
with the minibuffer empty.) minibuffer empty.)
In the following example, the user enters @samp{minibuffer.t}, and In the following example, the user enters @samp{minibuffer.t}, and
then types @key{RET}. The argument @var{existing} is @code{t}, and the then types @key{RET}. The argument @var{existing} is @code{t}, and the
...@@ -823,7 +818,7 @@ only buffer name starting with the given input is ...@@ -823,7 +818,7 @@ only buffer name starting with the given input is
@example @example
(read-buffer "Buffer name? " "foo" t) (read-buffer "Buffer name? " "foo" t)
@group @group
;; @r{After evaluating the preceding expression,} ;; @r{After evaluation of the preceding expression,}
;; @r{the following prompt appears,} ;; @r{the following prompt appears,}
;; @r{with an empty minibuffer:} ;; @r{with an empty minibuffer:}
@end group @end group
...@@ -852,7 +847,7 @@ for which @code{commandp} returns @code{t}. @xref{Interactive Call}. ...@@ -852,7 +847,7 @@ for which @code{commandp} returns @code{t}. @xref{Interactive Call}.
(read-command "Command name? ") (read-command "Command name? ")
@group @group
;; @r{After evaluating the preceding expression,} ;; @r{After evaluation of the preceding expression,}
;; @r{the following prompt appears with an empty minibuffer:} ;; @r{the following prompt appears with an empty minibuffer:}
@end group @end group
...@@ -891,7 +886,7 @@ symbol. ...@@ -891,7 +886,7 @@ symbol.
@group @group
(read-variable "Variable name? ") (read-variable "Variable name? ")
;; @r{After evaluating the preceding expression,} ;; @r{After evaluation of the preceding expression,}
;; @r{the following prompt appears,} ;; @r{the following prompt appears,}
;; @r{with an empty minibuffer:} ;; @r{with an empty minibuffer:}
@end group @end group
...@@ -933,25 +928,29 @@ of the default directory. ...@@ -933,25 +928,29 @@ of the default directory.
This function reads a file name in the minibuffer, prompting with This function reads a file name in the minibuffer, prompting with
@var{prompt} and providing completion. If @var{default} is @var{prompt} and providing completion. If @var{default} is
non-@code{nil}, then the function returns @var{default} if the user just non-@code{nil}, then the function returns @var{default} if the user just
types @key{RET}. types @key{RET}. @var{default} is not checked for validity; it is
returned, whatever it is, if the user exits with the minibuffer empty.
If @var{existing} is non-@code{nil}, then the name must refer to an If @var{existing} is non-@code{nil}, then the user must specify the name
existing file; then @key{RET} performs completion to make the name valid of an existing file; @key{RET} performs completion to make the name
if possible, and then refuses to exit if it is not valid. If the value valid if possible, and then refuses to exit if it is not valid. If the
of @var{existing} is neither @code{nil} nor @code{t}, then @key{RET} value of @var{existing} is neither @code{nil} nor @code{t}, then
also requires confirmation after completion. @key{RET} also requires confirmation after completion. If
@var{existing} is @code{nil}, then the name of a nonexistent file is
acceptable.
The argument @var{directory} specifies the directory to use for The argument @var{directory} specifies the directory to use for
completion of relative file names. Usually it is inserted in the completion of relative file names. If @code{insert-default-directory}
minibuffer as initial input as well. It defaults to the current is non-@code{nil}, @var{directory} is also inserted in the minibuffer as
buffer's value of @code{default-directory}. initial input. It defaults to the current buffer's value of
@code{default-directory}.
@c Emacs 19 feature @c Emacs 19 feature
If you specify @var{initial}, that is an initial file name to insert in 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 the buffer (after with @var{directory}, if that is inserted). In this
@var{directory}, before @var{initial}. The default for @var{initial} is case, point goes at the beginning of @var{initial}. The default for
@code{nil}---don't insert any file name. To see what @var{initial} @var{initial} is @code{nil}---don't insert any file name. To see what
does, try the command @kbd{C-x C-v}. @var{initial} does, try the command @kbd{C-x C-v}.
Here is an example: Here is an example:
...@@ -959,7 +958,7 @@ Here is an example: ...@@ -959,7 +958,7 @@ Here is an example:
@group @group
(read-file-name "The file is ") (read-file-name "The file is ")
;; @r{After evaluating the preceding expression,} ;; @r{After evaluation of the preceding expression,}
;; @r{the following appears in the minibuffer:} ;; @r{the following appears in the minibuffer:}
@end group @end group
...@@ -1036,10 +1035,10 @@ can supply your own function to compute the completion of a given string. ...@@ -1036,10 +1035,10 @@ can supply your own function to compute the completion of a given string.
This is called @dfn{programmed completion}. This is called @dfn{programmed completion}.
To use this feature, pass a symbol with a function definition as the To use this feature, pass a symbol with a function definition as the
@var{collection} argument to @code{completing-read}. This function @var{collection} argument to @code{completing-read}. The function
arranges to pass your completion function along to @code{try-completion} @code{completing-read} arranges to pass your completion function along
and @code{all-completions}, which will then let your function do all the to @code{try-completion} and @code{all-completions}, which will then let
work. your function do all the work.
The completion function should accept three arguments: The completion function should accept three arguments:
...@@ -1077,7 +1076,7 @@ match for some possibility; @code{nil} otherwise. ...@@ -1077,7 +1076,7 @@ match for some possibility; @code{nil} otherwise.
@end itemize @end itemize
It would be consistent and clean for completion functions to allow It would be consistent and clean for completion functions to allow
lambda expressions (lists which are functions) as well as function lambda expressions (lists tha are functions) as well as function
symbols as @var{collection}, but this is impossible. Lists as symbols as @var{collection}, but this is impossible. Lists as
completion tables are already assigned another meaning---as alists. It completion tables are already assigned another meaning---as alists. It
would be unreliable to fail to handle an alist normally because it is would be unreliable to fail to handle an alist normally because it is
...@@ -1104,7 +1103,7 @@ answer. ...@@ -1104,7 +1103,7 @@ answer.
@code{y-or-n-p} does not; but it seems best to describe them together. @code{y-or-n-p} does not; but it seems best to describe them together.
@defun y-or-n-p prompt @defun y-or-n-p prompt
This function asks the user a question, expecting input in the echo 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 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 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 and @key{DEL} to mean no. It accepts @kbd{C-]} to mean ``quit'', like
...@@ -1113,35 +1112,35 @@ that reason the user might try to use @kbd{C-]} to get out. The answer ...@@ -1113,35 +1112,35 @@ 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 is a single character, with no @key{RET} needed to terminate it. Upper
and lower case are equivalent. and lower case are equivalent.
``Asking the question'' means printing @var{prompt} in the echo area, ``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 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}}, the expected answers (@kbd{y}, @kbd{n}, @kbd{@key{SPC}},
@kbd{@key{DEL}}, or something that quits), the function responds @kbd{@key{DEL}}, or something that quits), the function responds
@samp{Please answer y or n.}, and repeats the request. @samp{Please answer y or n.}, and repeats the request.
This function does not actually use the minibuffer, since it does not 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 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 Echo Area}), which uses the same screen space as the minibuffer. The
cursor moves to the echo area while the question is being asked. cursor moves to the echo area while the question is being asked.
The answers and their meanings, even @samp{y} and @samp{n}, are not The answers and their meanings, even @samp{y} and @samp{n}, are not
hardwired. The keymap @code{query-replace-map} specifies them. hardwired. The keymap @code{query-replace-map} specifies them.
@xref{Search and Replace}. @xref{Search and Replace}.
If @code{y-or-n-p} is called in a command that was invoked using the If @code{y-or-n-p} is called in a command that was invoked using the
mouse---more precisely, if @code{last-nonmenu-event} (@pxref{Command mouse---more precisely, if @code{last-nonmenu-event} (@pxref{Command
Loop Info}) is either @code{nil} or a mouse event---then it uses a Loop Info}) is either @code{nil} or a mouse event---then it uses a
dialog box or pop-up menu to ask the question. In this case, it does dialog box or pop-up menu to ask the question. In this case, it does
not use keyboard input or the echo area. not use keyboard input or the echo area.
In the following example, the user first types @kbd{q}, which is In the following example, the user first types @kbd{q}, which is
invalid. At the next prompt the user types @kbd{y}. invalid. At the next prompt the user types @kbd{y}.
@smallexample @smallexample
@group @group
(y-or-n-p "Do you need a lift? ") (y-or-n-p "Do you need a lift? ")
;; @r{After evaluating the preceding expression,} ;; @r{After evaluation of the preceding expression,}
;; @r{the following prompt appears in the echo area:} ;; @r{the following prompt appears in the echo area:}
@end group @end group
...@@ -1175,20 +1174,20 @@ appears on the screen at a time. ...@@ -1175,20 +1174,20 @@ appears on the screen at a time.
@end defun @end defun
@defun yes-or-no-p prompt @defun yes-or-no-p prompt
This function asks the user a question, expecting input in minibuffer. This function asks the user a question, expecting input in the
It returns @code{t} if the user enters @samp{yes}, @code{nil} if the minibuffer. It returns @code{t} if the user enters @samp{yes},
user types @samp{no}. The user must type @key{RET} to finalize the @code{nil} if the user types @samp{no}. The user must type @key{RET} to
response. Upper and lower case are equivalent. finalize the response. Upper and lower case are equivalent.
@code{yes-or-no-p} starts by displaying @var{prompt} in the echo area, @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 followed by @w{@samp{(yes or no) }}. The user must type one of the
expected responses; otherwise, the function responds @samp{Please answer expected responses; otherwise, the function responds @samp{Please answer
yes or no.}, waits about two seconds and repeats the request. yes or no.}, waits about two seconds and repeats the request.
@code{yes-or-no-p} requires more work from the user than @code{yes-or-no-p} requires more work from the user than
@code{y-or-n-p} and is appropriate for more crucial decisions. @code{y-or-n-p} and is appropriate for more crucial decisions.
If @code{yes-or-no-p} is called in a command that was invoked using If @code{yes-or-no-p} is called in a command that was invoked using
the mouse---more precisely, if @code{last-nonmenu-event} (@pxref{Command the mouse---more precisely, if @code{last-nonmenu-event} (@pxref{Command
Loop Info}) is either @code{nil} or a mouse event---then it uses a Loop Info}) is either @code{nil} or a mouse event---then it uses a
dialog box or pop-up menu to ask the question. In this case, it does dialog box or pop-up menu to ask the question. In this case, it does
...@@ -1200,7 +1199,7 @@ Here is an example: ...@@ -1200,7 +1199,7 @@ Here is an example:
@group @group
(yes-or-no-p "Do you really want to remove everything? ") (yes-or-no-p "Do you really want to remove everything? ")
;; @r{After evaluating the preceding expression,} ;; @r{After evaluation of the preceding expression,}
;; @r{the following prompt appears,} ;; @r{the following prompt appears,}
;; @r{with an empty minibuffer:} ;; @r{with an empty minibuffer:}
@end group @end group
...@@ -1230,6 +1229,13 @@ Do you really want to remove everything? (yes or no) ...@@ -1230,6 +1229,13 @@ Do you really want to remove everything? (yes or no)
@node Multiple Queries @node Multiple Queries
@section Asking Multiple Y-or-N Questions @section Asking Multiple Y-or-N Questions