Commit b613b1dc authored by Chong Yidong's avatar Chong Yidong
Browse files

(Basic Completion): Note that read-file-name-completion-ignore-case

and read-buffer-completion-ignore-case can override
completion-ignore-case.
(Minibuffer Completion): Document completing-read changes.
(Completion Commands): Avoid mentioning partial completion mode.
Document minibuffer-completion-confirm changes, and
minibuffer-confirm-exit-commands.
(High-Level Completion): Document new require-match behavior for
read-buffer.  Document read-buffer-completion-ignore-case.
(Reading File Names): Document new require-match behavior for
read-file-name.
parent d897e8ee
......@@ -824,7 +824,11 @@ it returns, @code{test-completion} returns in turn.
@defvar completion-ignore-case
If the value of this variable is non-@code{nil}, Emacs does not
consider case significant in completion.
consider case significant in completion. Note, however, that this
variable is overridden by @code{read-file-name-completion-ignore-case}
within @code{read-file-name} (@pxref{Reading File Names}), and by
@code{read-buffer-completion-ignore-case} within @code{read-buffer}
(@pxref{High-Level Completion}).
@end defvar
@defvar completion-regexp-list
......@@ -871,15 +875,33 @@ Some of these commands also call @code{test-completion}. Thus, if
@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
usual minibuffer exit commands won't exit unless the input completes to
an element of @var{collection}. If @var{require-match} is
@code{confirm-only}, the user can exit with any input, but she will
be asked for a confirmation if the input is not an element of
@var{collection}. Any other value of @var{require-match} behaves like
@code{t}, except that the exit commands won't exit if it does non-null
completion.
The value of the optional argument @var{require-match} determines how
the user may exit the minibuffer:
@itemize @bullet
@item
If @code{nil}, the usual minibuffer exit commands work regardless of
the input in the minibuffer.
@item
If @code{t}, the usual minibuffer exit commands won't exit unless the
input completes to an element of @var{collection}.
@item
If @code{confirm}, the user can exit with any input, but is asked for
confirmation if the input is not an element of @var{collection}.
@item
If @code{confirm-after-completion}, the user can exit with any input,
but is asked for confirmation if the preceding command was a
completion command (i.e., one of the commands in
@code{minibuffer-confirm-exit-commands}) and the resulting input is
not an element of @var{collection}. @xref{Completion Commands}.
@item
Any other value of @var{require-match} behaves like @code{t}, except
that the exit commands won't exit if it performs completion.
@end itemize
However, empty input is always permitted, regardless of the value of
@var{require-match}; in that case, @code{completing-read} returns the
......@@ -948,12 +970,7 @@ They are described in the following section.
@subsection Minibuffer Commands that 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 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. @xref{Completion Options,,,
emacs, The GNU Emacs Manual}, for a short description of Partial
Completion mode.
in the minibuffer to do completion.
@defvar minibuffer-completion-table
The value of this variable is the collection used for completion in
......@@ -969,10 +986,25 @@ minibuffer completion functions.
@end defvar
@defvar minibuffer-completion-confirm
When the value of this variable is non-@code{nil}, Emacs asks for
confirmation of a completion before exiting the minibuffer.
@code{completing-read} binds this variable, and the function
@code{minibuffer-complete-and-exit} checks the value before exiting.
This variable determines whether Emacs asks for confirmation before
exiting the minibuffer; @code{completing-read} binds this variable,
and the function @code{minibuffer-complete-and-exit} checks the value
before exiting. If the value is @code{nil}, confirmation is not
required. If the value is @code{confirm}, the user may exit with an
input that is not a valid completion alternative, but Emacs asks for
confirmation. If the value is @code{confirm-after-completion}, the
user may exit with an input that is not a valid completion
alternative, but Emacs asks for confirmation if the user submitted the
input right after any of the completion commands in
@code{minibuffer-confirm-exit-commands}.
@end defvar
@defvar minibuffer-confirm-exit-commands
This variable holds a list of commands that cause Emacs to ask for
confirmation before exiting the minibuffer, if the @var{require-match}
argument to @code{completing-read} is @code{confirm-after-completion}.
The confirmation is requested if the user attempts to exit the
minibuffer immediately after calling any command in this list.
@end defvar
@deffn Command minibuffer-complete-word
......@@ -1113,7 +1145,7 @@ Lisp function. When possible, do all minibuffer input as part of
reading the arguments for a command, in the @code{interactive}
specification. @xref{Defining Commands}.
@defun read-buffer prompt &optional default existing
@defun read-buffer prompt &optional default require-match
This function reads the name of a buffer and returns it as a string.
The argument @var{default} is the default name to use, the value to
return if the user exits with an empty minibuffer. If non-@code{nil},
......@@ -1127,17 +1159,12 @@ space. If @var{default} is non-@code{nil}, the function inserts it in
@var{prompt} before the colon to follow the convention for reading from
the minibuffer with a default value (@pxref{Programming Tips}).
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. 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.)
The optional argument @var{require-match} has the same meaning as in
@code{completing-read}. @xref{Minibuffer Completion}.
In the following example, the user enters @samp{minibuffer.t}, and
then types @key{RET}. The argument @var{existing} is @code{t}, and the
only buffer name starting with the given input is
then types @key{RET}. The argument @var{require-match} is @code{t},
and the only buffer name starting with the given input is
@samp{minibuffer.texi}, so that name is the value.
@example
......@@ -1168,6 +1195,11 @@ that call @code{read-buffer} to read a buffer name will actually use the
@code{iswitchb} package to read it.
@end defvar
@defvar read-buffer-completion-ignore-case
If this variable is non-@code{nil}, @code{read-buffer} ignores case
when performing completion.
@end defvar
@defun read-command prompt &optional default
This function reads the name of a command and returns it as a Lisp
symbol. The argument @var{prompt} is used as in
......@@ -1302,23 +1334,18 @@ and @code{read-input-method-name}, in @ref{Input Methods}.
for reading file names and shell commands. They provide special
features including automatic insertion of the default directory.
@defun read-file-name prompt &optional directory default existing initial predicate
@defun read-file-name prompt &optional directory default require-match initial predicate
This function reads a file name in the minibuffer, prompting with
@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
valid if possible, and then refuses to exit if it is not valid. If the
value of @var{existing} is neither @code{nil} nor @code{t}, then
@key{RET} also requires confirmation after completion. If
@var{existing} is @code{nil}, then the name of a nonexistent file is
acceptable.
The optional argument @var{require-match} has the same meaning as in
@code{completing-read}. @xref{Minibuffer Completion}.
@code{read-file-name} uses
@code{minibuffer-local-filename-completion-map} as the keymap if
@var{existing} is @code{nil}, and uses
@code{minibuffer-local-filename-must-match-map} if @var{existing} is
non-@code{nil}. @xref{Completion Commands}.
@var{require-match} is @code{nil}, and uses
@code{minibuffer-local-filename-must-match-map} if @var{require-match}
is non-@code{nil}. @xref{Completion Commands}.
The argument @var{directory} specifies the directory to use for
completion of relative file names. It should be an absolute directory
......@@ -1341,7 +1368,7 @@ 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
value of @var{require-match}. However, if @var{require-match} 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
......@@ -1361,9 +1388,9 @@ 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}.
returns an empty string, regardless of the value of
@var{require-match}. 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
......@@ -1420,7 +1447,7 @@ If this variable is non-@code{nil}, @code{read-file-name} ignores case
when performing completion.
@end defvar
@defun read-directory-name prompt &optional directory default existing initial
@defun read-directory-name prompt &optional directory default require-match initial
This function is like @code{read-file-name} but allows only directory
names as completion possibilities.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment