mirror/emacs
1
0
Fork 0
mirror of https://git.savannah.gnu.org/git/emacs.git synced 2025-01-02 11:21:42 +00:00
Code Issues Releases Activity

(Text from Minibuffer): Various corrections and clarifications.

Browse Source 
(Object from Minibuffer): Correct Lisp description of read-minibuffer.
(Minibuffer History): Clarify description of cons values for HISTORY arguments.
(Basic Completion): Various corrections and clarifications.
Add completion-regexp-list.
(Minibuffer Completion): Correct and clarify description of completing-read.
(Completion Commands): Mention partial-completion-mode.
Various other minor changes.
(High-Level Completion): Various corrections and clarifications.
(Reading File Names): Ditto.
(Minibuffer Misc): Ditto.
This commit is contained in:
Luc Teirlinck 2004-02-04 03:08:59 +00:00
parent 13c5d120fc
commit 4b574f3d8e
2 changed files with 245 additions and 106 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
lispref/ChangeLog
View File

@ -1,3 +1,21 @@
2004-02-03 Luc Teirlinck <teirllm@auburn.edu>
* minibuf.texi (Text from Minibuffer): Various corrections and
clarifications.
(Object from Minibuffer): Correct Lisp description of
read-minibuffer.
(Minibuffer History): Clarify description of cons values for
HISTORY arguments.
(Basic Completion): Various corrections and clarifications. Add
completion-regexp-list.
(Minibuffer Completion): Correct and clarify description of
completing-read.
(Completion Commands): Mention partial-completion-mode. Various
other minor changes.
(High-Level Completion): Various corrections and clarifications.
(Reading File Names): Ditto.
(Minibuffer Misc): Ditto.
2004-01-26 Luc Teirlinck <teirllm@auburn.edu>
* strings.texi (Text Comparison): assoc-string also matches

333
lispref/minibuf.texi
View File

@ -135,13 +135,17 @@ 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{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.
through the history commands. It should be a string, or @code{nil}.
If non-@code{nil}, the user can access it using
@code{next-history-element}, usually bound in the minibuffer to
@kbd{M-n}. 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.
(If @var{read} is non-@code{nil} and @var{default} is @code{nil}, empty
input results in an @code{end-of-file} error.) However, in the usual
case (where @var{read} is @code{nil}), @code{read-from-minibuffer}
ignores @var{default} when the user enters empty input and 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
@ -171,8 +175,9 @@ 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.
@var{string} in the minibuffer but put point at @emph{one-indexed}
@var{position} in the minibuffer, rather than at the end. Any integer
value less or equal to one puts point at the beginning of the string.
@strong{Usage note:} The @var{initial-contents} argument and the
@var{default} argument are two alternative features for more or less the
@ -180,21 +185,21 @@ 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.
the minibuffer on other occasions. For an exception to this rule,
see @ref{Minibuffer History}.
@end defun
@defun read-string prompt &optional initial history default inherit-input-method
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}.
arguments @var{prompt}, @var{initial}, @var{history} and
@var{inherit-input-method} are used as in @code{read-from-minibuffer}.
The keymap used is @code{minibuffer-local-map}.
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} specifies a default value to return if
the user enters null input; it should be a string. The optional
argument @var{inherit-input-method} specifies whether to inherit the
current buffer's input method.
The optional argument @var{default} is used as in
@code{read-from-minibuffer}, except that, if non-@code{nil}, it also
specifies a default value to return if the user enters null input. As
in @code{read-from-minibuffer} it should be a string, or @code{nil},
which is equivalent to an empty string.
This function is a simplified interface to the
@code{read-from-minibuffer} function:
@ -206,7 +211,7 @@ This function is a simplified interface to the
(let ((value
(read-from-minibuffer @var{prompt} @var{initial} nil nil
@var{history} @var{default} @var{inherit})))
(if (equal value "")
(if (and (equal value "") @var{default})
@var{default}
value))
@end group
@ -216,13 +221,15 @@ This function is a simplified interface to the
@defvar minibuffer-allow-text-properties
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.
This variable also affects @code{read-string}. However,
@code{read-no-blanks-input} (see below), as well as
@code{read-minibuffer} and related functions (@pxref{Object from
Minibuffer,, Reading Lisp Objects With the Minibuffer}), and all
functions that do minibuffer input with completion, discard text
properties unconditionally, regardless of the value of this variable.
@end defvar
@anchor{Definition of minibuffer-local-map}
@defvar minibuffer-local-map
This is the default local keymap for reading from the minibuffer. By
default, it makes the following bindings:
@ -243,10 +250,10 @@ default, it makes the following bindings:
@item @kbd{M-p}
@code{previous-history-element}
@item @kbd{M-r}
@item @kbd{M-s}
@code{next-matching-history-element}
@item @kbd{M-s}
@item @kbd{M-r}
@code{previous-matching-history-element}
@end table
@end defvar
@ -265,11 +272,15 @@ 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.
This function discards text properties, regardless of the value of
@code{minibuffer-allow-text-properties}.
@smallexample
@group
(read-no-blanks-input @var{prompt} @var{initial})
@equiv{}
(read-from-minibuffer @var{prompt} @var{initial} minibuffer-local-ns-map)
(let (minibuffer-allow-text-properties)
(read-from-minibuffer @var{prompt} @var{initial} minibuffer-local-ns-map))
@end group
@end smallexample
@end defun
@ -312,7 +323,8 @@ This is a simplified interface to the
@group
(read-minibuffer @var{prompt} @var{initial})
@equiv{}
(read-from-minibuffer @var{prompt} @var{initial} nil t)
(let (minibuffer-allow-text-properties)
(read-from-minibuffer @var{prompt} @var{initial} nil t))
@end group
@end smallexample
@ -421,11 +433,16 @@ Use @var{variable} (a symbol) as the history list.
@item (@var{variable} . @var{startpos})
Use @var{variable} (a symbol) as the history list, and assume that the
initial history position is @var{startpos} (an integer, counting from
zero which specifies the most recent element of the history).
initial history position is @var{startpos} (a nonnegative integer).
If you specify @var{startpos}, then you should also specify that element
of the history as the initial minibuffer contents, for consistency.
Specifying 0 for @var{startpos} is equivalent to just specifying the
symbol @var{variable}. @code{previous-history-element} will display
the most recent element of the history list in the minibuffer. If you
specify a positive @var{startpos}, the minibuffer history functions
behave as if @code{(elt @var{variable} (1- @var{STARTPOS}))} were the
history element currently shown in the minibuffer. For consistency,
you should also specify that element of the history as the initial
minibuffer contents.
@end table
If you don't specify @var{hist}, then the default history list
@ -539,8 +556,9 @@ the higher-level completion features that do use the minibuffer.
@defun try-completion string collection &optional predicate
This function returns the longest common substring of all possible
completions of @var{string} in @var{collection}. The value of
@var{collection} must be a list of strings, an alist, an obarray, or a
function that implements a virtual set of strings (see below).
@var{collection} must be a list of strings, an alist, an obarray, a
hash table, or a function that implements a virtual set of strings
(see below).
Completion compares @var{string} against each of the permissible
completions specified by @var{collection}; if the beginning of the
@ -552,7 +570,12 @@ longest initial sequence common to all the permissible completions that
match.
If @var{collection} is an alist (@pxref{Association Lists}), the
@sc{car}s of the alist elements form the set of permissible completions.
permissible completions are the elements of the alist that are either
strings or conses whose @sc{car} is a string. Other elements of the
alist are ignored. (Remember that in Emacs Lisp, the elements of
alists do not @emph{have} to be conses.) As all elements of the alist
can be strings, this case actually includes lists of strings, even
though we usually do not think of such lists as alists.
@cindex obarray in completion
If @var{collection} is an obarray (@pxref{Creating Symbols}), the names
@ -564,6 +587,9 @@ Note that the only valid way to make a new obarray is to create it
empty and then add symbols to it one by one using @code{intern}.
Also, you cannot intern a given symbol in more than one obarray.
If @var{collection} is a hash table, then the keys that are strings
are the possible completions. Other keys are ignored.
You can also use a symbol that is a function as @var{collection}. Then
the function is solely responsible for performing completion;
@code{try-completion} returns whatever this function returns. The
@ -573,11 +599,20 @@ function can be used in @code{all-completions} and do the appropriate
thing in either case.) @xref{Programmed Completion}.
If the argument @var{predicate} is non-@code{nil}, then it must be a
function of one argument. It is used to test each possible match, and
the match is accepted only if @var{predicate} returns non-@code{nil}.
The argument given to @var{predicate} is either a string from the
list, a cons cell from the alist (the @sc{car} of which is a string)
or a symbol (@emph{not} a symbol name) from the obarray.
function of one argument, unless @var{collection} is a hash table, in
which case it should be a function of two arguments. It is used to
test each possible match, and the match is accepted only if
@var{predicate} returns non-@code{nil}. The argument given to
@var{predicate} is either a string or a cons cell (the @sc{car} of
which is a string) from the alist, or a symbol (@emph{not} a symbol
name) from the obarray. If @var{collection} is a hash table,
@var{predicate} is called with two arguments, the string key and the
associated value.
In addition, to be acceptable, a completion must also match all the
regular expressions in @code{completion-regexp-list}. (Unless
@var{collection} is a function, in which case that function has to
handle @code{completion-regexp-list} itself.)
In the first of the following examples, the string @samp{foo} is
matched by three of the alist @sc{car}s. All of the matches begin with
@ -633,10 +668,13 @@ too short). Both of those begin with the string @samp{foobar}.
@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 (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.
@var{string}. The arguments to this function (aside from
@var{nospace}) are the same as those of @code{try-completion}. Also,
this function uses @code{completion-regexp-list} in the same way that
@code{try-completion} does. The optional argument @var{nospace} only
matters if @var{string} is the empty string. In that case, if
@var{nospace} is non-@code{nil}, completions that start with a space
are ignored.
If @var{collection} is a function, it is called with three arguments:
@var{string}, @var{predicate} and @code{t}; then @code{all-completions}
@ -662,13 +700,24 @@ example for @code{try-completion}:
@end smallexample
@end defun
@anchor{Definition of test-completion}
@defun test-completion string collection &optional predicate
This function returns non-@code{nil} if @var{string} is a valid
completion possibility specified by @var{collection} and
@var{predicate}. The other arguments are the same as in
@code{try-completion}. For instance, if @var{collection} is a list,
this is true if @var{string} appears in the list and @var{predicate}
is satisfied.
@var{predicate}. The arguments are the same as in
@code{try-completion}. For instance, if @var{collection} is a list of
strings, this is true if @var{string} appears in the list and
@var{predicate} is satisfied.
@code{test-completion} uses @code{completion-regexp-list} in the same
way that @code{try-completion} does.
If @var{predicate} is non-@code{nil} and if @var{collection} contains
several strings that are equal to each other, as determined by
@code{compare-strings} according to @code{completion-ignore-case},
then @var{predicate} should accept either all or none of them.
Otherwise, the return value of @code{test-completion} is essentially
unpredictable.
If @var{collection} is a function, it is called with three arguments,
the values @var{string}, @var{predicate} and @code{lambda}; whatever
@ -680,6 +729,13 @@ If the value of this variable is non-@code{nil}, Emacs does not
consider case significant in completion.
@end defvar
@defvar completion-regexp-list
This is a list of regular expressions. The completion functions only
consider a completion acceptable if it matches all regular expressions
in this list, with @code{case-fold-search} (@pxref{Searching and Case})
bound to the value of @code{completion-ignore-case}.
@end defvar
@defmac lazy-completion-table var fun &rest args
This macro provides a way to initialize the variable @var{var} as a
collection for completion in a lazy way, not computing its actual
@ -711,8 +767,12 @@ providing completion. It activates the minibuffer with prompt
@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
certain commands bound in the local keymaps used for completion.
@var{predicate} to the function @code{try-completion}. This happens
in certain commands bound in the local keymaps used for completion.
Some of these commands also call @code{test-completion}. Thus, if
@var{predicate} is non-@code{nil}, it should be compatible with
@var{collection} and @code{completion-ignore-case}. @xref{Definition
of test-completion}.
If @var{require-match} is @code{nil}, the exit commands work regardless
of the input in the minibuffer. If @var{require-match} is @code{t}, the
@ -723,19 +783,13 @@ input already in the buffer matches an element of @var{collection}.
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.
@var{default}, or @code{""}, if @var{default} is @code{nil}. 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
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}
as the keymap if @var{require-match} is @code{nil}, and uses
The function @code{completing-read} 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}.
@ -744,15 +798,21 @@ saving the input and for minibuffer history commands. It defaults to
@code{minibuffer-history}. @xref{Minibuffer History}.
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}.
into the minibuffer as part of the input, with point at the end. Then
it allows the user to edit the input, providing several commands to
attempt completion. @var{initial} can also be a cons cell of the form
@code{(@var{string} . @var{position})}. In that case, point is put at
@emph{zero-indexed} position @var{position} in @var{string}. Note
that this is different from @code{read-from-minibuffer} and related
functions, which use a one-indexed position. 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.
default and edit it, and it is always available. For an exception to
this rule, see @ref{Minibuffer History}.
If the argument @var{inherit-input-method} is non-@code{nil}, then the
minibuffer inherits the current input method (@pxref{Input
@ -799,8 +859,11 @@ see @ref{Completion Commands}.
@node Completion Commands
@subsection Minibuffer Commands that Do Completion
This section describes the keymaps, commands and user options used in
the minibuffer to do completion.
This section describes the keymaps, commands and user options used
in the minibuffer to do completion. The description refers to the
situation when @code{partial-completion-mode} is disabled (as it is by
default). When enabled, this minor mode uses its own alternatives to
some of the commands described below.
@defvar minibuffer-local-completion-map
@code{completing-read} uses this value as the local keymap when an
@ -820,7 +883,7 @@ keymap makes the following bindings:
@noindent
with other characters bound as in @code{minibuffer-local-map}
(@pxref{Text from Minibuffer}).
(@pxref{Definition of minibuffer-local-map}).
@end defvar
@defvar minibuffer-local-must-match-map
@ -852,8 +915,8 @@ with other characters bound as in @code{minibuffer-local-map}.
@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
The value of this variable is the collection used for completion in
the minibuffer. This is the global variable that contains what
@code{completing-read} passes to @code{try-completion}. It is used by
minibuffer completion commands such as @code{minibuffer-complete-word}.
@end defvar
@ -907,8 +970,10 @@ This function displays @var{completions} to the stream in
information about streams.) The argument @var{completions} is normally
a list of completions just returned by @code{all-completions}, but it
does not have to be. Each element may be a symbol or a string, either
of which is simply printed, or a list of two strings, which is printed
as if the strings were concatenated.
of which is simply printed. It can also be a list of two strings,
which is printed as if the strings were concatenated. The first of
the two strings is the actual completion, the second string serves as
annotation.
This function is called by @code{minibuffer-completion-help}. The
most common way to use it is together with
@ -948,9 +1013,10 @@ is not inserted in the minibuffer as initial input.
If @var{existing} is non-@code{nil}, then the name specified must be
that of an existing buffer. The usual commands to exit the minibuffer
do not exit if the text is not valid, and @key{RET} does completion to
attempt to find a valid name. (However, @var{default} is not checked
for validity; it is returned, whatever it is, if the user exits with the
minibuffer empty.)
attempt to find a valid name. If @var{existing} is neither @code{nil}
nor @code{t}, confirmation is required after completion. (However,
@var{default} is not checked for validity; it is returned, whatever it
is, if the user exits with the minibuffer empty.)
In the following example, the user enters @samp{minibuffer.t}, and
then types @key{RET}. The argument @var{existing} is @code{t}, and the
@ -996,7 +1062,8 @@ The argument @var{default} 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}.
enters null input, the return value is @code{(intern "")}, that is, a
symbol whose name is an empty string.
@example
(read-command "Command name? ")
@ -1041,7 +1108,7 @@ The argument @var{default} 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}
is @code{nil}, that means no default has been specified; then if the
user enters null input, the return value is @code{nil}.
user enters null input, the return value is @code{(intern "")}.
@example
@group
@ -1090,10 +1157,7 @@ of the default directory.
@defun read-file-name prompt &optional directory default existing initial predicate
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
types @key{RET}. @var{default} is not checked for validity; it is
returned, whatever it is, if the user exits with the minibuffer empty.
@var{prompt} and providing completion.
If @var{existing} is non-@code{nil}, then the user must specify the name
of an existing file; @key{RET} performs completion to make the name
@ -1104,10 +1168,10 @@ value of @var{existing} is neither @code{nil} nor @code{t}, then
acceptable.
The argument @var{directory} specifies the directory to use for
completion of relative file names. If @code{insert-default-directory}
is non-@code{nil}, @var{directory} is also inserted in the minibuffer as
initial input. It defaults to the current buffer's value of
@code{default-directory}.
completion of relative file names. It should be an absolute directory
name. If @code{insert-default-directory} is non-@code{nil},
@var{directory} is also inserted in the minibuffer as initial input.
It defaults to the current buffer's value of @code{default-directory}.
@c Emacs 19 feature
If you specify @var{initial}, that is an initial file name to insert
@ -1118,11 +1182,45 @@ case, point goes at the beginning of @var{initial}. The default for
note:} we recommend using @var{default} rather than @var{initial} in
most cases.
If @var{default} is non-@code{nil}, then the function returns
@var{default} if the user exits the minibuffer with the same non-empty
contents that @code{read-file-name} inserted initially. The initial
minibuffer contents are always non-empty if
@code{insert-default-directory} is non-@code{nil}, as it is by
default. @var{default} is not checked for validity, regardless of the
value of @var{existing}. However, if @var{existing} is
non-@code{nil}, the initial minibuffer contents should be a valid file
(or directory) name. Otherwise @code{read-file-name} attempts
completion if the user exits without any editing, and does not return
@var{default}. @var{default} is also available through the history
commands.
If @var{default} is @code{nil}, @code{read-file-name} tries to find a
substitute default to use in its place, which it treats in exactly the
same way as if it had been specified explicitly. If @var{default} is
@code{nil}, but @var{initial} is non-@code{nil}, then the default is
the absolute file name obtained from @var{directory} and
@var{initial}. If both @var{default} and @var{initial} are @code{nil}
and the buffer is visiting a file, @code{read-file-name} uses the
absolute file name of that file as default. If the buffer is not
visiting a file, then there is no default. In that case, if the user
types @key{RET} without any editing, @code{read-file-name} simply
returns the pre-inserted contents of the minibuffer.
If the user types @key{RET} in an empty minibuffer, this function
returns an empty string, regardless of the value of @var{existing}.
This is, for instance, how the user can make the current buffer visit
no file using @code{M-x set-visited-file-name}.
If @var{predicate} is non-@code{nil}, it specifies a function of one
argument that decides which file names are acceptable completion
possibilities. A file name is an acceptable value if @var{predicate}
returns non-@code{nil} for it.
@code{read-file-name} does not automatically expand file names. You
must call @code{expand-file-name} yourself if an absolute file name is
required.
Here is an example:
@example
@ -1160,17 +1258,35 @@ as the string @code{"/gp/gnu/elisp/manual.texi"}.
@defun read-directory-name prompt &optional directory default existing initial
This function is like @code{read-file-name} but allows only directory
names as completion possibilities.
If @var{default} is @code{nil} and @var{initial} is non-@code{nil},
@code{read-directory-name} constructs a substitute default by
combining @var{directory} (or the current buffer's default directory
if @var{directory} is @code{nil}) and @var{initial}. If both
@var{default} and @var{initial} are @code{nil}, this function uses the
current buffer's default directory as substitute default, ignoring
@var{directory}.
@end defun
@defopt insert-default-directory
This variable is used by @code{read-file-name}. Its value controls
whether @code{read-file-name} starts by placing the name of the default
directory in the minibuffer, plus the initial file name if any. If the
value of this variable is @code{nil}, then @code{read-file-name} does
not place any initial input in the minibuffer (unless you specify
initial input with the @var{initial} argument). In that case, the
default directory is still used for completion of relative file names,
but is not displayed.
This variable is used by @code{read-file-name}, and thus, indirectly,
by most commands reading file names. (This includes all commands that
use the code letters @samp{f} or @samp{F} in their interactive form.
@xref{Interactive Codes,, Code Characters for interactive}.) Its
value controls whether @code{read-file-name} starts by placing the
name of the default directory in the minibuffer, plus the initial file
name if any. If the value of this variable is @code{nil}, then
@code{read-file-name} does not place any initial input in the
minibuffer (unless you specify initial input with the @var{initial}
argument). In that case, the default directory is still used for
completion of relative file names, but is not displayed.
If this variable is @code{nil} and the initial minibuffer contents are
empty, the user may have to explicitly fetch the next history element
to access a default value. If the variable is non-@code{nil}, the
initial minibuffer contents are always non-empty and the user can
always request a default value by immediately typing @key{RET} in an
unedited minibuffer. (See above.)
For example:
@ -1627,9 +1743,10 @@ The current value of this variable is used to rebind @code{help-form}
locally inside the minibuffer (@pxref{Help Functions}).
@end defvar
@defun minibufferp &optional buffer
This function returns non-@code{nil} if @var{buffer} is a minibuffer.
If @var{buffer} is omitted, it tests the current buffer.
@defun minibufferp &optional buffer-or-name
This function returns non-@code{nil} if @var{buffer-or-name} is a
minibuffer. If @var{buffer-or-name} is omitted, it tests the current
buffer.
@end defun
@defun active-minibuffer-window
@ -1654,8 +1771,10 @@ choosing the minibuffer window according to the current frame.
@end defun
@c Emacs 19 feature
@defun window-minibuffer-p window
This function returns non-@code{nil} if @var{window} is a minibuffer window.
@defun window-minibuffer-p &optional window
This function returns non-@code{nil} if @var{window} is a minibuffer
window.
@var{window} defaults to the selected window.
@end defun
It is not correct to determine whether a given window is a minibuffer by
@ -1704,14 +1823,16 @@ another window to do it.
@c Emacs 19 feature
If a command name has a property @code{enable-recursive-minibuffers}
that is non-@code{nil}, then the command can use the minibuffer to read
arguments even if it is invoked from the minibuffer. The minibuffer
command @code{next-matching-history-element} (normally @kbd{M-s} in the
minibuffer) uses this feature.
arguments even if it is invoked from the minibuffer. A command can
also achieve this by binding @code{enable-recursive-minibuffers}
to @code{t} in the interactive declaration (@pxref{Using Interactive}).
The minibuffer command @code{next-matching-history-element} (normally
@kbd{M-s} in the minibuffer) does the latter.
@defun minibuffer-message string &optional timeout
@defun minibuffer-message string
This function displays @var{string} temporarily at the end of the
minibuffer text, for @var{timeout} seconds. (The default is 2
seconds.)
minibuffer text, for two seconds, or until the next input event
arrives, whichever comes first.
@end defun
@ignore