⟦f67564f4c⟧

TextFile

@setfilename ../info/minibuffers
@node Minibuffers, Command Loop, Streams, Top
@chapter Minibuffers

@cindex complex arguments
  A @dfn{minibuffer} is a special buffer used by Emacs commands
to read arguments more complicated than the single numeric prefix
argument.

  In most ways, a minibuffer is a normal Emacs buffer.  Although some
operations for managing buffers do not apply to minibuffers, most
operations @emph{within} a buffer, such as editing commands, work
normally in the minibuffer.  But minibuffers cannot be deleted or
renamed.  (In fact, a minibuffer, once created, is never deleted by
Emacs, even after the user exits from the minibuffer.)

  The minibuffer has its own window, from which it cannot be
separated.  The window is the single line at the bottom of the screen;
it can be temporarily resized with the window sizing commands.

  A @dfn{recursive minibuffer} may be created when there is an active
minibuffer and a command is invoked that requires input from a
minibuffer.  Recursive minibuffers may be allowed or disallowed by
setting the variable @code{enable-recursive-minibuffers}.  Of several
recursive minibuffers, the innermost, or most recently entered, one is
the active minibuffer.  It is the only one that is displayed in a
window.

  The first minibuffer is named @samp{ *Minibuf-0*}.  Recursive
minibuffers are named by incrementing the number at the end of the name.
All minibuffer names begin with a space so that they won't show up in
normal buffer lists.  

  The minibuffer may use one of several local keymaps; they contain
various completion and exit commands.

@itemize @bullet
@item
@code{minibuffer-local-map} is used 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

@menu
* Reading Text or Objects::     
* Completion::  
* Yes or No Queries::   
* Minibuffer Odds and Ends::    
@end menu

@node Reading Text or Objects, Completion, Minibuffers, Minibuffers
@section Reading Text or Objects

  The main use of the minibuffer is to read text.  One extension of
that is to treat the text as a Lisp object, and return that.

@menu
* Reading Lisp Objects in the Minibuffer::      
@end menu

@defun read-from-minibuffer  prompt-string &optional initial keymap read

  This function is perhaps the most general way to get
input in the minibuffer: it reads an arbitrary string and returns
it.

  First, @var{prompt-string} is printed in the minibuffer.
@var{prompt-string} must be a string.

  Then, if @var{initial} is non-@code{nil}, the value of @var{initial}
is inserted into the minibuffer.  @var{initial} is considered to be
part of the user's input, at least to begin with, and so it can be
edited normally.

  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.

  Finally, if @var{read} is non-@code{nil}, Emacs interprets the result
as a Lisp object and @code{read-from-minibuffer} returns that object,
unevaluated.  Otherwise, it returns the minibuffer contents as a string.

  For example, suppose you save the last string the user searched for
in the variable @code{last-search-string}, and offer it for editing
the next time.  To get a search string, you might want to call
@code{read-from-minibuffer} as follows.

@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)
     @result{} "Nope"
@end example

@noindent
Here is the minibuffer after evaluating the call to
@code{read-from-minibuffer} but before typing in the characters
@samp{pe} and @key{RET}

@group
@example
---------- Buffer: Minibuffer ----------
Find string: No@point{}
---------- Buffer: Minibuffer ----------
@end example
@end group

@end defun

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

  This function is a simplified call 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

@defun read-no-blanks-input prompt &optional initial
  This function reads a string from the minibuffer, but does not allow
the user to type blanks.  @var{prompt} and @var{initial} are the same
as in @code{read-from-minibuffer}.  Typing a blank @emph{exits} the
minibuffer.

  This function is a simplified call to @code{read-from-minibuffer}.
The @code{read-no-blanks-input} function uses the
@code{minibuffer-local-ns-map} keymap.  Since
@code{read-no-blanks-input} does not redefine @code{quoted-insert}, it
@emph{is} possible to put a space into the string, by quoting it.
Also, of course, you may rebind the keys in
@code{minibuffer-local-ns-map}.

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

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

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

@item SPC
@kindex SPC in minibuffer
@code{exit-minibuffer}

@item TAB
@kindex TAB in minibuffer
@code{exit-minibuffer}

@item RET
@code{exit-minibuffer}

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

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

@defvar minibuffer-local-map
  This is the default keymap for reading from the minibuffer.  It is the
keymap used by the minibuf for local bindings when spaces are allowed in
the minibuffer.

By default, it makes the following bindings:

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

@item RET
@code{exit-minibuffer}

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

@node Reading Lisp Objects in the Minibuffer,  , Reading Text or Objects, Reading Text or Objects
@subsection Reading Lisp Objects in the Minibuffer

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

@defun read-minibuffer prompt &optional initial
  This function reads a Lisp object in the minibuffer and returns it,
unevaluated.  @var{prompt} and @var{initial} are the same as in
@code{read-from-minibuffer}.

  This function is a simplified call 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:

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

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

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

@noindent
In this example, @samp{(testing)} is inserted initially, and may be
edited by the user.
@end defun

@defun eval-minibuffer prompt &optional initial
  This function reads a Lisp expression in the minibuffer, then
evaluates it, returning the result.  @var{prompt} and @var{initial}
are the same 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 from @code{eval-minibuffer} is that the
initial @var{form} is not optional and it is not expected to be a
string.  @var{form} is printed with @code{prin1}, so if it is a string,
double quotes characters, @samp{"}, will appear in the initial text.

  First, @var{prompt} is printed in the minibuffer.  Then @var{form}
is converted to its print representation and inserted into the
minibuffer as input, like @var{initial} in
@code{read-from-minibuffer}.  When the user exits the minibuffer, the
new form is evaluated.  The resulting value is the value of 
@code{edit-and-eval-command}.

  In the following example, the user is offered an expression with an
incomplete name for a function call within it:

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

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

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

@noindent
The user may edit the minibuffer, for example, by typing:
@samp{@key{DEL} @kbd{word 1)}}.  This action edits the form to create a
complete expression: @code{(forward-word 1)}.  Typing @key{RET} then
causes Emacs to evaluate the expression, which will move point forward
one word.  @code{edit-and-eval-command} returns @code{nil} in this
example.
@end defun

@node Completion, Yes or No Queries, Reading Text or Objects, Minibuffers
@section Completion
@cindex completion

  Emacs will attempt to complete the name of a symbol, file, or buffer
if you type a part of it.  This saves typing and makes life easier.
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 will try to extend the name as far as it can.

  Completion works for functions such as @code{switch-to-buffer} or
@code{describe-function} because Emacs keeps track of the names
of all the buffers and the names of all the functions and is able to
search through those names to locate those that begin with the letters
you type.

  The functions described in this section handle completion in a
fairly general way.  The @code{try-completion} function is at the heart
of the completion routines.  It returns the longest possible substring
for a given initial string, and set of strings to match against.  Other
functions perform completion for various other specifications.

  The function @code{completing-read} provides a higher-level interface
for completion.  A call to @code{completing-read} specifies what should
be completed, and how.  The function then switches to the minibuffer
where the local keymap binds a few keys to functions useful for
completion.

  For information about functions that complete filenames,
@pxref{Filename Completion}; for functions that complete symbols,
@pxref{Lisp Symbol Completion}.

@menu
* Basic Completion::
* Completion Reading::
* High-level Completion::
@end menu

@node Basic Completion, Completion Reading, 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 alist (@pxref{Association Lists}),
the first element of each pair in the association list is tested to
see whether it begins with @var{string}.  All elements that match are
then compared.  The longest initial sequence common to all matches is
returned as a string.  If none is matched, @code{try-completion}
returns @code{nil}.  If only one element is matched, and the match is
exact, then @code{try-completion} returns @code{t}.

@cindex obarray in completion
  If @var{alist-or-obarray} is an obarray (@pxref{Creating and Interning Symbols}), the print names of all symbols in the obarray are tested for
matches.  (The global variable @code{obarray} holds an obarray
containing the names of all interned Lisp symbols.)

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

  In the first of the following examples, the string @samp{foo} is
matched by three of the alist pairs.  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
@code{t} is returned.

@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}, but
only one does not contain the additional character @samp{-}.

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

  In the following example, @code{test} is defined as 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

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 Completion Reading, High-level Completion, Basic Completion, Completion
@comment  node-name,  next,  previous,  up
@subsection Functions and Variables for Reading with Completion

Here are the functions and variables for dealing with 
completion while reading from the minibuffer.

@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.  First, it prints @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 function performs completion using @var{alist-or-obarray} and
@var{predicate} in the same way that @code{try-completion} does.

  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 if the built-in variable
@code{completion-ignore-case} is non-@code{nil}.

  The @code{completing-read} function also binds three special
variables, the first two of which are passed to the
@code{read-minibuffer} function, the last of which is checked by the
@code{minibuffer-complete-and-exit} function.

@table @code
@item minibuffer-completion-table
The value of this variable is bound to @var{alist-or-obarray} argument.

@item minibuffer-completion-predicate
The @var{predicate} argument is bound to the value of this variable.

@item minibuffer-completion-confirm
The @var{require-match} argument is bound to the value of this variable.
@end table

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
---------- Buffer: Minibuffer ----------
@end example

@noindent
If in this case, the user types @code{@key{DEL} @key{DEL} b
@key{RET}}, Emacs will return @code{barfoo}.
@end defun

@defvar minibuffer-local-completion-map
  @code{completing-read} uses this value as the local map 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 the value of this variableas the local map
when an exact match of one of the completions is required.  Therefore, no
keys are bound to @code{exit-minibuffer}.

By default, this variable 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{read-minibuffer}.
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 that
@code{completing-read} passes to @code{read-minibuffer}.  The variable
also used by the other minibuffer completion functions.
@end defvar

  Here are the interactive commands and user options that are people
use directly for completion in the minibuffer.

@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 a
confirmation @emph{is} required, and is given, repeating this command
will exit.
@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 using @code{all-completions} passed the
values of @code{minibuffer-completion-table} and
@code{minibuffer-completion-predicate}.  Emacs displays the list in the
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.)  @var{completions} is normally the list of
completions just made.  Each element may be a symbol or a string, either
of which is simply printed, or a list of two strings, which are printed
as if concatenated.

  This function is called by @code{minibuffer-completion-help}.
@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

@node High-level Completion,  , Completion Reading, Completion
@comment  node-name,  next,  previous,  up
@subsection High-level Completion  Functions

Here are functions for reading from the minibuffer with
completion.

@defun read-buffer prompt &optional default existing
  This function reads the name of a buffer and returns it as a
string.  @var{default} (which must be a string if it is supplied) is
printed along with the prompt and is the value to return if the user
simply exits.  @var{default} is therefore not an initial value in the sense 
of @code{read-from-minibuffer}.

  If @var{existing} is non-@code{nil}, then any name the user types must
be the name of an existing buffer.  (However, even if @var{existing} is
non-@code{nil}, @var{default} need not be the name of an existing
buffer.)

  In the following example, the user enters @samp{minibuffer.t}, and
then types @key{RET}.  The only buffer name starting with that string is
@samp{minibuffer.texinfo}, so that name is returned.

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

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

---------- Buffer: Minibuffer ----------
Buffer name? (default foo) 
---------- Buffer: Minibuffer ----------
@end example

@noindent
The user types @code{minibuffer.t @key{RET}} and the result is
@code{minibuffer.texinfo}.
@end defun

@defun read-file-name prompt directory &optional default mustmatch
  This function reads a file name in the minibuffer, prompting with
@var{prompt}.  The function provides completion for the name.  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{mustmatch} is non-@code{nil}, then the name must refer to an
existing file.  If the value of @var{mustmatch} is neither
non-@code{nil} nor non-@code{t}, then Emacs also requires confirmation
after completion.

@var{directory} defaults to the current buffer's default directory.

For example, after evaluating the following expression,

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

@noindent
the following appears in the minibuffer:

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

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

@example
---------- Buffer: Minibuffer ----------
The file is /gp/gnu/elisp/manual.texinfo
---------- Buffer: Minibuffer ----------
@end example

@noindent
Then, after typing @key{RET}, Emacs will return
@code{"/gp/gnu/elisp/manual.texinfo"}.
@end defun

@defopt insert-default-directory
  This variable is used by @code{read-file-name}.  The value of the
variable determines if, when reading a filename in the minibuffer, Emacs
should start by placing the name of the default directory in the
minibuffer.  If the value of this variable is @code{nil}, then Emacs
will not place anything into the minibuffer.  In that case, the default
directory will still be used, but it will not be displayed.

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

---------- Buffer: Minibuffer ----------
The file is ~lewis/manual/ 
---------- Buffer: Minibuffer ----------

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

---------- Buffer: Minibuffer ----------
The file is
---------- Buffer: Minibuffer ----------
@end example
@end defopt

@defun read-command prompt
  This function reads the name of a command and returns it as a Lisp
symbol.  @var{prompt} is the same as in @code{read-from-minibuffer}.
Recall that a command is merely a function with an interactive calling
specification.

@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 in this case, the user types @code{forward-c @key{RET}}, then Emacs
will return @code{forward-char}.

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

@findex commandp @r{example}
@vindex obarray
@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.  This function is analogous to @code{read-command}; it 
uses the predicate @code{user-variable-p} instead of @code{commandp}.

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

(read-variable "Variable name? ")

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

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

@noindent
If in this case, the user types @code{fill-p @key{RET}}, then Emacs
will return @code{fill-prefix}.
@end defun



The functions described in this chapter deal with general completion
in the minibuffer.  Emacs Lisp also provides functions for filename
completion (@pxref{Filename Completion}) and Lisp symbol completion
(@pxref{Lisp Symbol Completion}).

@node Yes or No Queries, Minibuffer Odds and Ends, Completion, Minibuffers
@section Yes or No Queries

@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 @samp{y}, @code{nil}
if the user types @samp{n}.  Only a single character is needed to
answer, with no @key{RET} to end the input.  The function also accepts
@key{SPC} to mean yes and @key{DEL} to mean no.  Upper and lowercase
are not equivalent.

  Asking the question means print @var{prompt} in the echo area,
followed by the string @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.

  In the following example, the user first types @kbd{q}, which is
invalid.  At the next prompt the user types @kbd{n}.  Note that we
show successive lines of minibuffer prompts here.  In fact, only one
will appear at any time.

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

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

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

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

@example
---------- Echo area ----------
Please answer y or n.  Do you need a lift? (y or n) 
---------- Echo area ----------
@end example
@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 types @kbd{yes},
@code{nil} if the user types @kbd{no}.  A return must be typed to end the 
response.  Upper and lowercase are not equivalent.

  @code{yes-or-no-p} requires more work from the user than
@code{y-or-n-p} and is used for correspondingly more critical actions.

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

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

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

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

@noindent
If the user first enters @kbd{y}, which is invalid because it must be
the entire word @kbd{yes}, Emacs responds by erasing the @kbd{y} and
displaying:

@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 Odds and Ends,  , Yes or No Queries, Minibuffers
@comment  node-name,  next,  previous,  up
@section Minibuffer Odds and Ends

Some basic operations and functions are defined here. 

@deffn Command exit-minibuffer
  This function terminates the present minibuffer read.  It is
only useful if bound to a key.
@end deffn

@deffn Command self-insert-and-exit
  This function terminates minibuffer input after inserting
@code{last-command-char} (@pxref{Command Loop Info}).
@end deffn

Some objects are special to the minibuffer:

@defvar minibuffer-help-form
  The global or ambient 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.
This is always the same window.  It cannot be deleted.
@end defun

@defvar minibuffer-scroll-window
  If the value of this built-in variable is non-@code{nil}, it should
be a window object.  When the function @code{scroll-other-window} is
called in the minibuffer, Emacs will scroll the
@code{minibuffer-scroll-window} window.
@end defvar

@defvar minibuffer-local-map
  This variable is the default keymap Emacs uses as the local map
when reading from the minibuffer.  By default,
it makes the following bindings:

@table @key

@kindex LFD in minibuffer
@item LFD
@code{exit-minibuffer}

@kindex RET in minibuffer
@item RET
@code{exit-minibuffer}

@kindex C-g in minibuffer
@item @kbd{C-g}
@code{abort-recursive-edit}
@end table

Almost all the examples in this chapter assume @key{RET} is bound to
@code{exit-minibuffer}.  Some examples also assume @key{DEL} deletes
the character before point.
@end defvar

Finally, some functions and variables deal with recursive minibuffers:

@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, while in the minbuffer window.
This produces a recursive editing level for a new minbuffer.  The
outer-level minibuffer is invisible while you are editing the inner one.

This variable only affects invoking the minibuffer while in the
minibuffer itself, since it is always possible to invoke a minibuffer
from a different window, even if the minibuffer is active.
@end defopt
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦f67564f4c⟧ TextFile

Derivation

TextFile
