@c -*-texinfo-*-
@c This is part of the XEmacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1997 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1997 Free Software Foundation, Inc.
@c See the file lispref.texi for copying conditions.
@setfilename ../../info/minibuf.info
@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:: 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}.)
@code{minibuffer-local-map} is 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
reading the arguments for a command, in the @code{interactive} spec.
@xref{Defining Commands}.
-@defun read-from-minibuffer prompt-string &optional initial-contents keymap read hist
+@defun read-from-minibuffer prompt-string &optional initial-contents keymap read hist abbrev-table default
This function is the most general way to get input through the
minibuffer. By default, it accepts arbitrary text and returns it as a
string; however, if @var{read} is non-@code{nil}, then it uses
@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.
@var{string} in the minibuffer but put point @var{position} characters
from the beginning, rather than at the end.
+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.)
+
+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{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
value of @code{minibuffer-local-map} is used as the keymap. Specifying
a keymap is the most important way to customize the minibuffer for
various applications such as completion.
+The argument @var{abbrev-table} specifies @code{local-abbrev-table} in
+the minibuffer (@pxref{Standard Abbrev Tables}).
+
The argument @var{hist} specifies which history list variable to use
for saving the input and for history commands used in the minibuffer.
It defaults to @code{minibuffer-history}. @xref{Minibuffer History}.
@code{read-from-minibuffer} reads the text and returns the resulting
Lisp object, unevaluated. (@xref{Input Functions}, for information
about reading.)
+
+@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. However, if user is supposed to edit
+default value, @var{initial-contents} may be preferred.
@end defun
-@defun read-string prompt &optional initial
+@defun read-string prompt &optional initial history default-value
This function reads a string from the minibuffer and returns it. The
arguments @var{prompt} and @var{initial} are used as in
@code{read-from-minibuffer}. The keymap used is
@code{minibuffer-local-map}.
-This is a simplified interface to the
+The optional argument @var{history}, if non-@code{nil}, specifies a history
+list and optionally the initial position in the list. The optional
+argument @var{default-value} specifies a default value to return if the user
+enters null input; it should be a string.
+
+This function is a simplified interface to the
@code{read-from-minibuffer} function:
@smallexample
@group
-(read-string @var{prompt} @var{initial})
+(read-string @var{prompt} @var{initial} @var{history} @var{default})
@equiv{}
-(read-from-minibuffer @var{prompt} @var{initial} nil nil nil)
+(read-from-minibuffer @var{prompt} @var{initial} nil nil
+ @var{history} nil @var{default})))
@end group
@end smallexample
@end defun
default, it makes the following bindings:
@table @asis
-@item @key{LFD}
+@item @kbd{C-j}
@code{exit-minibuffer}
@item @key{RET}
@end table
@end defvar
-@c In version 18, initial is required
-@c Emacs 19 feature
-@defun read-no-blanks-input prompt &optional initial
-This function reads a string from the minibuffer, but does not allow
-whitespace characters as part of the input: instead, those characters
-terminate the input. The arguments @var{prompt} and @var{initial} are
-used as in @code{read-from-minibuffer}.
-
-This is a simplified interface to the @code{read-from-minibuffer}
-function, and passes the value of the @code{minibuffer-local-ns-map}
-keymap as the @var{keymap} argument for that function. Since the keymap
-@code{minibuffer-local-ns-map} does not rebind @kbd{C-q}, it @emph{is}
-possible to put a space into the string, by quoting it.
-
-@smallexample
-@group
-(read-no-blanks-input @var{prompt} @var{initial})
-@equiv{}
-(read-from-minibuffer @var{prompt} @var{initial} minibuffer-local-ns-map)
-@end group
-@end smallexample
-@end defun
-
-@defvar minibuffer-local-ns-map
-This built-in variable is the keymap used as the minibuffer local keymap
-in the function @code{read-no-blanks-input}. By default, it makes the
-following bindings, in addition to those of @code{minibuffer-local-map}:
-
-@table @asis
-@item @key{SPC}
-@cindex @key{SPC} in minibuffer
-@code{exit-minibuffer}
-
-@item @key{TAB}
-@cindex @key{TAB} in minibuffer
-@code{exit-minibuffer}
-
-@item @kbd{?}
-@cindex @kbd{?} in minibuffer
-@code{self-insert-and-exit}
-@end table
-@end defvar
-
@node Object from Minibuffer
@section Reading Lisp Objects with the Minibuffer
This section describes functions for reading Lisp objects with the
minibuffer.
-@defun read-minibuffer prompt &optional initial
-This function reads a Lisp object in the minibuffer and returns it,
+@defun read-expression prompt &optional initial history default-value
+This function reads a Lisp object using the minibuffer, and returns it
without evaluating it. The arguments @var{prompt} and @var{initial} are
used as in @code{read-from-minibuffer}.
+The optional argument @var{history}, if non-@code{nil}, specifies a history
+list and optionally the initial position in the list. The optional
+argument @var{default-value} specifies a default value to return if the
+user enters null input; it should be a string.
+
This is a simplified interface to the
@code{read-from-minibuffer} function:
@smallexample
@group
-(read-minibuffer @var{prompt} @var{initial})
+(read-expression @var{prompt} @var{initial} @var{history} @var{default-value})
@equiv{}
-(read-from-minibuffer @var{prompt} @var{initial} nil t)
+(read-from-minibuffer @var{prompt} @var{initial} nil t
+ @var{history} nil @var{default-value})
@end group
@end smallexample
@smallexample
@group
-(read-minibuffer
+(read-expression
"Enter an expression: " (format "%s" '(testing)))
;; @r{Here is how the minibuffer is displayed:}
default, or can edit the input.
@end defun
-@defun eval-minibuffer prompt &optional initial
-This function reads a Lisp expression in the minibuffer, evaluates it,
-then returns the result. The arguments @var{prompt} and @var{initial}
-are used as in @code{read-from-minibuffer}.
+@defun read-minibuffer prompt &optional initial history default-value
+
+This is a FSF Emacs compatible function. Use @code{read-expression}
+instead.
+@end defun
+
+@defun eval-minibuffer prompt &optional initial history default-value
+This function reads a Lisp expression using the minibuffer, evaluates
+it, then returns the result. The arguments @var{prompt} and
+@var{initial} are used as in @code{read-from-minibuffer}.
+
+The optional argument @var{history}, if non-@code{nil}, specifies a history
+list and optionally the initial position in the list. The optional
+argument @var{default-value} specifies a default value to return if the
+user enters null input; it should be a string.
This function simply evaluates the result of a call to
-@code{read-minibuffer}:
+@code{read-expression}:
@smallexample
@group
(eval-minibuffer @var{prompt} @var{initial})
@equiv{}
-(eval (read-minibuffer @var{prompt} @var{initial}))
+(eval (read-expression @var{prompt} @var{initial}))
@end group
@end smallexample
@end defun
-@defun edit-and-eval-command prompt form
+@defun edit-and-eval-command prompt form &optional history
This function reads a Lisp expression in the minibuffer, and then
evaluates it. The difference between this command and
@code{eval-minibuffer} is that here the initial @var{form} is not
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
-representation of @var{form} in the minibuffer, and lets the user edit.
+representation of @var{form} in the minibuffer, and lets the user edit it.
When the user exits the minibuffer, the edited text is read with
@code{read} and then evaluated. The resulting value becomes the value
of @code{edit-and-eval-command}.
@group
(edit-and-eval-command "Please edit: " '(forward-word 1))
-;; @r{After evaluation of the preceding expression,}
+;; @r{After evaluation of the preceding expression,}
;; @r{the following appears in the minibuffer:}
@end group
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
features that do use the minibuffer.
@defun try-completion string collection &optional predicate
-This function returns the longest common substring of all possible
+This function returns the longest common prefix of all possible
completions of @var{string} in @var{collection}. The value of
@var{collection} must be an alist, an obarray, or a function that
implements a virtual set of strings (see below).
@smallexample
@group
-(try-completion
+(try-completion
"foo"
'(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)))
@result{} "fooba"
@smallexample
@group
-(defun test (s)
+(defun test (s)
(> (length (car s)) 6))
@result{} test
@end group
@group
-(try-completion
+(try-completion
"foo"
- '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
+ '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
'test)
@result{} "foobar"
@end group
@end smallexample
@end defun
-@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}.
+@defun all-completions string collection &optional predicate
+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}.
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}:
@smallexample
@group
-(defun test (s)
+(defun test (s)
(> (length (car s)) 6))
@result{} test
@end group
@group
-(all-completions
+(all-completions
"foo"
'(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
'test)
@end defun
@defvar completion-ignore-case
-If the value of this variable is
+If the value of this variable is
non-@code{nil}, XEmacs does not consider case significant in completion.
@end defvar
This section describes the basic interface for reading from the
minibuffer with completion.
-@defun completing-read prompt collection &optional predicate require-match initial hist
+@defun completing-read prompt collection &optional predicate require-match initial hist default
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
@var{collection}. If @var{require-match} is @code{nil}, the exit
commands work regardless of the input in the minibuffer.
+However, empty input is always permitted, regardless of the value of
+@var{require-match}; in that case, @code{completing-read} returns
+@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{nil}. This is
-how the user requests whatever default the command uses for the value
-being read. The user can return using @key{RET} in this way regardless
-of the value of @var{require-match}.
+minibuffer. Then @code{completing-read} returns @code{""}. This is how
+the user requests whatever default the command uses for the value being
+read. The user can return using @key{RET} in this way regardless of the
+value of @var{require-match}, and regardless of whether the empty string
+is included in @var{collection}.
The function @code{completing-read} works by calling
-@code{read-minibuffer}. It uses @code{minibuffer-local-completion-map}
+@code{read-expression}. It uses @code{minibuffer-local-completion-map}
as the keymap if @var{require-match} is @code{nil}, and uses
@code{minibuffer-local-must-match-map} if @var{require-match} is
non-@code{nil}. @xref{Completion Commands}.
@end group
@group
-;; @r{After evaluation of the preceding expression,}
+;; @r{After evaluation of the preceding expression,}
;; @r{the following appears in the minibuffer:}
---------- Buffer: Minibuffer ----------
@item @key{TAB}
@code{minibuffer-complete}
-@item @key{LFD}
+@item @kbd{C-j}
@code{minibuffer-complete-and-exit}
@item @key{RET}
@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 confirmation
+@code{minibuffer-completion-confirm} is @code{nil}. If confirmation
@emph{is} required, it is given by repeating this command
immediately---the command is programmed to work without confirmation
when run twice in succession.
@samp{*Completions*}.
@end deffn
-@defun display-completion-list completions
+@defun display-completion-list completions &rest cl-keys
This function displays @var{completions} to the stream in
@code{standard-output}, usually a buffer. (@xref{Read and Print}, for more
information about streams.) The argument @var{completions} is normally
@example
(read-buffer "Buffer name? " "foo" t)
@group
-;; @r{After evaluation of the preceding expression,}
+;; @r{After evaluation of the preceding expression,}
;; @r{the following prompt appears,}
;; @r{with an empty minibuffer:}
@end group
@end example
@end defun
-@defun read-command prompt
+@defun read-command prompt &optional default-value
This function reads the name of a command and returns it as a Lisp
symbol. The argument @var{prompt} is used as in
@code{read-from-minibuffer}. Recall that a command is anything for
which @code{commandp} returns @code{t}, and a command name is a symbol
for which @code{commandp} returns @code{t}. @xref{Interactive Call}.
+The argument @var{default-value} specifies what to return if the user
+enters 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? ")
@group
-;; @r{After evaluation of the preceding expression,}
+;; @r{After evaluation of the preceding expression,}
;; @r{the following prompt appears with an empty minibuffer:}
@end group
@group
----------- Buffer: Minibuffer ----------
-Command name?
+---------- Buffer: Minibuffer ----------
+Command name?
---------- Buffer: Minibuffer ----------
@end group
@end example
@group
(read-command @var{prompt})
@equiv{}
-(intern (completing-read @var{prompt} obarray
+(intern (completing-read @var{prompt} obarray
'commandp t nil))
@end group
@end example
@end defun
-@defun read-variable prompt
+@defun read-variable prompt &optional default-value
This function reads the name of a user variable and returns it as a
symbol.
+The argument @var{default-value} specifies what to return if the user
+enters 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-value}
+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
(read-variable "Variable name? ")
-;; @r{After evaluation of the preceding expression,}
-;; @r{the following prompt appears,}
+;; @r{After evaluation of the preceding expression,}
+;; @r{the following prompt appears,}
;; @r{with an empty minibuffer:}
@end group
file name. It provides special features including automatic insertion
of the default directory.
-@defun read-file-name prompt &optional directory default existing initial
+@defun read-file-name prompt &optional directory default existing initial history
This function reads a file name in the minibuffer, prompting with
@var{prompt} and providing completion. If @var{default} is
non-@code{nil}, then the function returns @var{default} if the user just
@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}.
-Here is an example:
+Here is an example:
@example
@group
(read-file-name "The file is ")
-;; @r{After evaluation of the preceding expression,}
+;; @r{After evaluation of the preceding expression,}
;; @r{the following appears in the minibuffer:}
@end group
@item
@code{nil} specifies @code{try-completion}. The completion function
should return the completion of the specified string, or @code{t} if the
-string is an exact match already, or @code{nil} if the string matches no
-possibility.
+string is a unique and exact match already, or @code{nil} if the string
+matches no possibility.
+
+If the string is an exact match for one possibility, but also matches
+other longer possibilities, the function should return the string, not
+@code{t}.
@item
@code{t} specifies @code{all-completions}. The completion function
@group
(y-or-n-p "Do you need a lift? ")
-;; @r{After evaluation of the preceding expression,}
+;; @r{After evaluation of the preceding expression,}
;; @r{the following prompt appears in the echo area:}
@end group
@group
---------- Echo area ----------
-Do you need a lift? (y or n)
+Do you need a lift? (y or n)
---------- Echo area ----------
@end group
@group
---------- Echo area ----------
-Please answer y or n. Do you need a lift? (y or n)
+Please answer y or n. Do you need a lift? (y or n)
---------- Echo area ----------
@end group
@group
(yes-or-no-p "Do you really want to remove everything? ")
-;; @r{After evaluation of the preceding expression,}
-;; @r{the following prompt appears,}
+;; @r{After evaluation of the preceding expression,}
+;; @r{the following prompt appears,}
;; @r{with an empty minibuffer:}
@end group
@group
---------- Buffer: minibuffer ----------
-Do you really want to remove everything? (yes or no)
+Do you really want to remove everything? (yes or no)
---------- Buffer: minibuffer ----------
@end group
@end smallexample
The return value of @code{map-y-or-n-p} is the number of objects acted on.
@end defun
+@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.
+
+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. It is translated to @samp{.}
+and inserted in the minibuffer. If @var{default} is @code{nil}, then
+@code{read-passwd} returns the null string in that case.
+@end defun
+
+@defopt passwd-invert-frame-when-keyboard-grabbed
+If non-@code{nil}, swap the foreground and background colors of all faces while
+reading a password. Default values is @code{t}, unless feature
+@code{infodock} is provided.
+@end defopt
+
+@defopt passwd-echo
+This specifies the character echoed when typing a password. When @code{nil},
+nothing is echoed.
+@end defopt
+
@node Minibuffer Misc
@section Minibuffer Miscellany
@end defun
@c Emacs 19 feature
-@defun window-minibuffer-p window
+@defun window-minibuffer-p &optional window
This function returns non-@code{nil} if @var{window} is a minibuffer window.
@end defun
@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 window is selected. If you switch windows while in the
minibuffer, you can always invoke minibuffer commands while some other
window is selected.
@end defopt
in this fashion, just use an evaluated interactive spec and bind
@code{enable-recursive-minibuffers} while reading from the minibuffer.
See the definition of @code{next-matching-history-element} in
-@file{lisp/prim/minibuf.el}.
+@file{lisp/minibuf.el}.