@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
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
-screen, in the same place as the echo area, but only while it is in
-use for reading an argument.
+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.
* 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
@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
+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-contents} is a string, @code{read-from-minibuffer}
-inserts it into the minibuffer, leaving point at the end. The
-minibuffer appears with this text as its contents.
+string. Then the user can edit text in the minibuffer.
-@strong{Usage note:} The @var{initial-contents} argument and the
-@var{default} argument are two alternative features for the same job.
-It usually does not make sense to use both at once. In most cases, you
-should use @var{default}, since this permits the user to insert the
-default value but does not burden the user with deleting it from the
-minibuffer.
+When the user types a command to exit the minibuffer,
+@code{read-from-minibuffer} constructs the return value from the text in
+the minibuffer. Normally it returns a string containing that text.
+However, if @var{read} is non-@code{nil}, @code{read-from-minibuffer}
+reads the text and returns the resulting Lisp object, unevaluated.
+(@xref{Input Functions}, for information about reading.)
-@c Emacs 19 feature
-The value of @var{initial-contents} 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 point @var{position} characters
-from the beginning, rather than at the end.
+The argument @var{default} specifies a default value to make available
+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}
+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.
If @var{keymap} is non-@code{nil}, that keymap is the local keymap to
use in the minibuffer. If @var{keymap} is omitted or @code{nil}, the
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,
-@code{read-from-minibuffer} uses the text in the minibuffer to produce
-its return value. Normally it simply makes a string containing that
-text. However, if @var{read} is non-@code{nil},
-@code{read-from-minibuffer} reads the text and returns the resulting
-Lisp object, unevaluated. (@xref{Input Functions}, for information
-about reading.)
-
If the variable @code{minibuffer-allow-text-properties} is
non-@code{nil}, then the string which is returned includes whatever text
properties were present in the minibuffer. Otherwise all the text
properties are stripped when the value is returned.
-The argument @var{default} specifies a default value to make available
-through the history list. It should be a string, or @code{nil}. If
-@var{read} is non-@code{nil}, then @var{default} is passed through
-@code{read}, just as ordinary user input would be. Unlike many other
-minibuffer functions, this function does @emph{not} return @var{default}
-if the user enters empty input. It returns @code{""} in that case.
-
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
+user starts to edit the text. The minibuffer appears with this text as
+its initial contents.
+
+Alternatively, @var{initial-contents} can be a cons cell of the form
+@code{(@var{string} . @var{position})}. This means to insert
+@var{string} in the minibuffer but put point @var{position} characters
+from the beginning, rather than at the end.
+
+@strong{Usage note:} The @var{initial-contents} argument and the
+@var{default} argument are two alternative features for more or less the
+same job. It does not make sense to use both features in a single call
+to @code{read-from-minibuffer}. In general, we recommend using
+@var{default}, since this permits the user to insert the default value
+when it is wanted, but does not burden the user with deleting it from
+the minibuffer on other occasions.
@end defun
@defun read-string prompt &optional initial history default inherit-input-method
@group
(read-string @var{prompt} @var{initial} @var{history} @var{default} @var{inherit})
@equiv{}
-(read-from-minibuffer @var{prompt} @var{initial} nil nil
- @var{history} @var{default} @var{inherit})
+(let ((value
+ (read-from-minibuffer @var{prompt} @var{initial} nil nil
+ @var{history} @var{default} @var{inherit})))
+ (if (equal value "")
+ @var{default}
+ value))
@end group
@end smallexample
@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
default, it makes the following bindings:
@table @asis
-@item @key{LFD}
+@item @kbd{C-j}
@code{exit-minibuffer}
@item @key{RET}
@cindex minibuffer history
@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 actually a
symbol, not a list; it is a variable whose value is a list of strings
(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
list for each use of the minibuffer.
-The basic minibuffer input functions @code{read-from-minibuffer} and
+ 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:
of the history as the initial minibuffer contents, for consistency.
@end table
-If you don't specify @var{hist}, then the default history list
+ 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.
-Both @code{read-from-minibuffer} and @code{completing-read} add new
+ 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.
+ Here are some of the standard minibuffer history list variables:
+
@defvar minibuffer-history
The default history list for minibuffer history input.
@end defvar
@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 parameters to this function are the same as to
-@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}:
@defun completing-read prompt collection &optional predicate require-match initial hist default inherit-input-method
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.
+@var{prompt}, which must be a string.
The actual completion is done by passing @var{collection} and
@var{predicate} to the function @code{try-completion}. This happens in
However, empty input is always permitted, regardless of the value of
@var{require-match}; in that case, @code{completing-read} returns
-@var{default}.
+@var{default}. The value of @var{default} (if non-@code{nil}) is also
+available to the user through the history commands.
The user can exit with null input by typing @key{RET} with an empty
minibuffer. Then @code{completing-read} returns @code{""}. This is how
saving the input and for minibuffer history commands. It defaults to
@code{minibuffer-history}. @xref{Minibuffer History}.
-The optional argument @var{default} specifies a default value to return
-if the user enters null input; it should 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.
+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.
@item @key{TAB}
@code{minibuffer-complete}
-@item @key{LFD}
+@item @kbd{C-j}
@code{minibuffer-complete-and-exit}
@item @key{RET}
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.
for which @code{commandp} returns @code{t}. @xref{Interactive Call}.
The argument @var{default} specifies what to return if the user enters
-null input. It can be a symbol or a string, but the value returned by
-@code{read-command} is always a symbol. If @var{default} is @code{nil},
-that means no default has been specified; then if the user enters null
-input, the return value is @code{nil}.
+null input. It can be a symbol or a string; if it is a string,
+@code{read-command} interns it before returning it. If @var{default} is
+@code{nil}, that means no default has been specified; then if the user
+enters null input, the return value is @code{nil}.
@example
(read-command "Command name? ")
symbol.
The argument @var{default} specifies what to return if the user enters
-null input. It can be a symbol or a string, but the value returned by
-@code{read-variable} is always a symbol. If @var{default} is
-@code{nil}, that means no default has been specified; then if the user
-enters null input, the return value is @code{nil}.
+null input. It can be a symbol or a string; if it is a string,
+@code{read-variable} interns it before returning it. If @var{default}
+is @code{nil}, that means no default has been specified; then if the
+user enters null input, the return value is @code{nil}.
@example
@group
@end example
@end defun
-@tindex read-coding-system
-@defun read-coding-system prompt default
-This function reads a coding system using the minibuffer, prompting with
-string @var{prompt}, and returns the coding system name as a symbol. If
-the user tries to enter null input, it asks the user to try again.
-@xref{Coding Systems}.
-@end defun
-
-@tindex read-non-nil-coding-system
-@defun read-non-nil-coding-system prompt
-This function reads a coding system using the minibuffer, prompting with
-string @var{prompt},and returns the coding system name as a symbol. If
-the user enters null input, it returns @var{default-coding-system}.
-which should be a symbol or a string. @xref{Coding Systems}.
-@end defun
+ See also the functions @code{read-coding-system} and
+@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}.
+@var{initial} does, try the command @kbd{C-x C-v}. @strong{Note:} we
+recommend using @var{default} rather than @var{initial} in most cases.
Here is an example:
matches no possibility.
If the string is an exact match for one possibility, but also matches
-other longer possibilities, the function shuold return the string, not
+other longer possibilities, the function should return the string, not
@code{t}.
@item
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}.
-@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.
+@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.
+@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
@defopt enable-recursive-minibuffers
If this variable is non-@code{nil}, you can invoke commands (such as
-@code{find-file}) that use minibuffers even while in the minibuffer
-window. Such invocation produces a recursive editing level for a new
+@code{find-file}) that use minibuffers even while the minibuffer window
+is active. 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.
+If this variable is @code{nil}, you cannot invoke minibuffer
+commands when the minibuffer window is active, not even if you switch to
+another window to do it.
@end defopt
@c Emacs 19 feature