@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/minibuf
@node Minibuffers, Command Loop, Read and Print, Top
* 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.
-* Reading a Password:: Function for reading a password.
+* Reading a Password:: Reading a password from the terminal.
* Minibuffer Misc:: Various customization hooks and variables.
@end menu
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
+windows always appear at the bottom of a frame. (Sometimes frames have
no minibuffer window, and sometimes a special kind of frame contains
nothing but a minibuffer window; see @ref{Minibuffers and Frames}.)
- The minibuffer's window is normally a single line. You can resize it
-temporarily with the window sizing commands; it reverts to its normal
-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
-minibuffer is not active. If the frame contains just a minibuffer, you
-can change the minibuffer's size by changing the frame's size.
+ The text in the minibuffer always starts with the @dfn{prompt string},
+the text that was specified by the program that is using the minibuffer
+to tell the user what sort of input to type. This text is marked
+read-only so you won't accidentally delete or change it. It is also
+marked as a field (@pxref{Fields}), so that certain motion functions,
+including @code{beginning-of-line}, @code{forward-word},
+@code{forward-sentence}, and @code{forward-paragraph}, stop at the
+boundary between the prompt and the actual text. (In older Emacs
+versions, the prompt was displayed using a special mechanism and was not
+part of the buffer contents.)
+
+ The minibuffer's window is normally a single line; it grows
+automatically if necessary if the contents require more space. You can
+explicitly resize it temporarily with the window sizing commands; it
+reverts to its normal 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 minibuffer is not active. If the frame contains
+just a minibuffer, you can change the minibuffer's size by changing the
+frame's size.
If a command uses a minibuffer while there is an active minibuffer,
this is called a @dfn{recursive minibuffer}. The first minibuffer is
for cautious completion.
@end itemize
+ When Emacs is running in batch mode, any request to read from the
+minibuffer actually reads a line from the standard input descriptor that
+was supplied when Emacs was started.
+
@node Text from Minibuffer
@section Reading Text Strings with the Minibuffer
In most cases, you should not call minibuffer input functions in the
middle of a Lisp function. Instead, do all minibuffer input as part of
-reading the arguments for a command, in the @code{interactive} spec.
-@xref{Defining Commands}.
+reading the arguments for a command, in the @code{interactive}
+specification. @xref{Defining Commands}.
@defun read-from-minibuffer prompt-string &optional initial-contents keymap read hist default inherit-input-method
This function is the most general way to get input through the
through the history commands. It should be a string, or @code{nil}. If
@var{read} is non-@code{nil}, then @var{default} is also used as the
input to @code{read}, if the user enters empty input. However, in the
-usual case (where @var{read} is @code{nil}, @code{read-from-minibuffer}
+usual case (where @var{read} is @code{nil}), @code{read-from-minibuffer}
does not return @var{default} when the user enters empty input; it
returns an empty string, @code{""}. In this respect, it is different
from all the other minibuffer input functions in this chapter.
properties are stripped when the value is returned.
If the argument @var{inherit-input-method} is non-@code{nil}, then the
-minibuffer inherits the current input method and the setting of
-@code{enable-multibyte-characters} from whichever buffer was current
-before entering the minibuffer.
+minibuffer inherits the current input method (@pxref{Input Methods}) and
+the setting of @code{enable-multibyte-characters} (@pxref{Text
+Representations}) from whichever buffer was current before entering the
+minibuffer.
If @var{initial-contents} is a string, @code{read-from-minibuffer}
inserts it into the minibuffer, leaving point at the end, before the
@end defun
@defvar minibuffer-allow-text-properties
-If this variable is non-@code{nil}, then @code{read-from-minibuffer}
-strips all text properties from the string before returning the string.
+If this variable is @code{nil}, then @code{read-from-minibuffer} strips
+all text properties from the minibuffer input before returning it.
Since all minibuffer input uses @code{read-from-minibuffer}, this
variable applies to all minibuffer input.
+
+Note that the completion functions discard text properties unconditionally,
+regardless of the value of this variable.
@end defvar
@defvar minibuffer-local-map
@end defvar
@defvar file-name-history
-A history list for file name arguments.
+A history list for file-name arguments.
+@end defvar
+
+@defvar buffer-name-history
+A history list for buffer-name arguments.
@end defvar
@defvar regexp-history
@defun all-completions string collection &optional predicate nospace
This function returns a list of all possible completions of
-@var{string}. The arguments to this function are the same as those of
-@code{try-completion}.
+@var{string}. The arguments to this function (aside from @var{nospace})
+are the same as those of @code{try-completion}. If @var{nospace} is
+non-@code{nil}, completions that start with a space are ignored unless
+@var{string} also starts with a space.
If @var{collection} is a function, it is called with three arguments:
@var{string}, @var{predicate} and @code{t}; then @code{all-completions}
returns whatever the function returns. @xref{Programmed Completion}.
-If @var{nospace} is non-@code{nil}, completions that start with a space
-are ignored unless @var{string} also starts with a space.
-
Here is an example, using the function @code{test} shown in the
example for @code{try-completion}:
edit the input, providing several commands to attempt completion.
In most cases, we recommend using @var{default}, and not @var{initial}.
+@strong{We discourage use of a non-@code{nil} value for
+@var{initial}}, because it is an intrusive interface. The history
+list feature (which did not exist when we introduced @var{initial})
+offers a far more convenient and general way for the user to get the
+default and edit it, and it is always available.
+
If the argument @var{inherit-input-method} is non-@code{nil}, then the
-minibuffer inherits the current input method and the setting of
-@code{enable-multibyte-characters} from whichever buffer was current
-before entering the minibuffer. @xref{Input Methods,,, emacs, The GNU
-Emacs Manual}.
+minibuffer inherits the current input method (@pxref{Input
+Methods}) and the setting of @code{enable-multibyte-characters}
+(@pxref{Text Representations}) from whichever buffer was current before
+entering the minibuffer.
Completion ignores case when comparing the input against the possible
matches, if the built-in variable @code{completion-ignore-case} is
@end defun
@node Completion Commands
-@subsection Minibuffer Commands That Do Completion
+@subsection Minibuffer Commands that Do Completion
This section describes the keymaps, commands and user options used in
the minibuffer to do completion.
In most cases, you should not call these functions in the middle of a
Lisp function. When possible, do all minibuffer input as part of
-reading the arguments for a command, in the @code{interactive} spec.
-@xref{Defining Commands}.
+reading the arguments for a command, in the @code{interactive}
+specification. @xref{Defining Commands}.
@defun read-buffer prompt &optional default existing
This function reads the name of a buffer and returns it as a string.
@end defun
See also the functions @code{read-coding-system} and
-@code{read-non-nil-coding-system}, in @ref{Lisp and Coding Systems}.
+@code{read-non-nil-coding-system}, in @ref{User-Chosen Coding Systems}.
@node Reading File Names
@subsection Reading File Names
@c Emacs 19 feature
If you specify @var{initial}, that is an initial file name to insert in
-the buffer (after with @var{directory}, if that is inserted). In this
+the buffer (after @var{directory}, if that is inserted). In this
case, point goes at the beginning of @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}. @strong{Note:} we
convenient facilities such as the ability to answer the whole series at
once.
-@defun map-y-or-n-p prompter actor list &optional help action-alist
+@defun map-y-or-n-p prompter actor list &optional help action-alist no-cursor-in-echo-area
This function asks the user a series of questions, reading a
single-character answer in the echo area for each one.
@var{list}. If it returns @code{nil}, the prompt is repeated for the
same object.
+Normally, @code{map-y-or-n-p} binds @code{cursor-in-echo-area} while
+prompting. But if @var{no-cursor-in-echo-area} is non-@code{nil}, it
+does not do that.
+
If @code{map-y-or-n-p} is called in a command that was invoked using the
mouse---more precisely, if @code{last-nonmenu-event} (@pxref{Command
Loop Info}) is either @code{nil} or a list---then it uses a dialog box
@node Reading a Password
@section Reading a Password
+@cindex passwords, reading
+
+ To read a password to pass to another program, you can use the
+function @code{read-passwd}.
+
+@defun read-passwd prompt &optional confirm default
+This function reads a password, prompting with @var{prompt}. It does
+not echo the password as the user types it; instead, it echoes @samp{.}
+for each character in the password.
- This function is useful for reading passwords.
+The optional argument @var{confirm}, if non-@code{nil}, says to read the
+password twice and insist it must be the same both times. If it isn't
+the same, the user has to type it over and over until the last two
+times match.
-@tindex read-password
-@defun read-password prompt default
-This function reads a password, echoing @samp{.} in the echo area
-for each character entered, and returns it as a string. It prompts
-with @var{prompt}, and returns @var{default} if the user enters the
-null string.
+The optional argument @var{default} specifies the default password to
+return if the user enters empty input. If @var{default} is @code{nil},
+then @code{read-passwd} returns the null string in that case.
@end defun
@node Minibuffer Misc
@var{n}th more recent history element.
@end deffn
-@deffn Command previous-matching-history-element pattern
+@deffn Command previous-matching-history-element pattern n
This command replaces the minibuffer contents with the value of the
-previous (older) history element that matches @var{pattern} (a regular
-expression).
+@var{n}th previous (older) history element that matches @var{pattern} (a
+regular expression).
@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} (a regular
-expression).
+@deffn Command next-matching-history-element pattern n
+This command replaces the minibuffer contents with the value of the
+@var{n}th next (newer) history element that matches @var{pattern} (a
+regular expression).
@end deffn
@defun minibuffer-prompt
minibuffer. If no minibuffer is active, it returns @code{nil}.
@end defun
-@defun minibuffer-prompt-width
-This function returns the display width of the prompt string of the
-currently active minibuffer. If no minibuffer is active, it returns 0.
+@tindex minibuffer-prompt-end
+@defun minibuffer-prompt-end
+This function, available starting in Emacs 21, returns the current
+position of the end of the minibuffer prompt, if a minibuffer is
+current. Otherwise, it returns zero.
+@end defun
+
+@defun minubuffer-prompt-width
+This function returns the current display-width of the minibuffer
+prompt, if a minibuffer is current. Otherwise, it returns zero.
@end defun
@defvar minibuffer-setup-hook