@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, 2001
+@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
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
@end defvar
@defvar buffer-name-history
-@tindex buffer-name-history
A history list for buffer-name arguments.
@end defvar
@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 (@pxref{Input
Methods}) and the setting of @code{enable-multibyte-characters}
@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.
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
- This function is useful for reading passwords.
+ To read a password to pass to another program, you can use the
+function @code{read-passwd}.
-@defun read-password prompt default
-@tindex read-password
-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.
+@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.
+
+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.
+
+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.
+@defun minibuffer-prompt-end
+@tindex 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 the minimum valid buffer position.
+@end defun
+
+@defun minibuffer-contents
+@tindex minibuffer-contents
+This function, available starting in Emacs 21, returns the editable
+contents of the minibuffer (that is, everything except the prompt) as
+a string, if a minibuffer is current. Otherwise, it returns the
+entire contents of the current buffer.
+@end defun
+
+@defun minibuffer-contents-no-properties
+@tindex minibuffer-contents-no-properties
+This is like @code{minibuffer-contents}, except that it does not copy text
+properties, just the characters themselves. @xref{Text Properties}.
+@end defun
+
+@defun delete-minibuffer-contents
+@tindex delete-minibuffer-contents
+This function, available starting in Emacs 21, erases the editable
+contents of the minibuffer (that is, everything except the prompt), if
+a minibuffer is current. Otherwise, it erases the entire buffer.
+@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