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. ...@@ -824,7 +824,11 @@ it returns, @code{test-completion} returns in turn.
@defvar completion-ignore-case @defvar completion-ignore-case
If the value of this variable is non-@code{nil}, Emacs does not 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 @end defvar
@defvar completion-regexp-list @defvar completion-regexp-list
...@@ -871,15 +875,33 @@ Some of these commands also call @code{test-completion}. Thus, if ...@@ -871,15 +875,33 @@ Some of these commands also call @code{test-completion}. Thus, if
@var{collection} and @code{completion-ignore-case}. @xref{Definition @var{collection} and @code{completion-ignore-case}. @xref{Definition
of test-completion}. of test-completion}.
If @var{require-match} is @code{nil}, the exit commands work regardless The value of the optional argument @var{require-match} determines how
of the input in the minibuffer. If @var{require-match} is @code{t}, the the user may exit the minibuffer:
usual minibuffer exit commands won't exit unless the input completes to
an element of @var{collection}. If @var{require-match} is @itemize @bullet
@code{confirm-only}, the user can exit with any input, but she will @item
be asked for a confirmation if the input is not an element of If @code{nil}, the usual minibuffer exit commands work regardless of
@var{collection}. Any other value of @var{require-match} behaves like the input in the minibuffer.
@code{t}, except that the exit commands won't exit if it does non-null
completion. @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 However, empty input is always permitted, regardless of the value of
@var{require-match}; in that case, @code{completing-read} returns the @var{require-match}; in that case, @code{completing-read} returns the
...@@ -948,12 +970,7 @@ They are described in the following section. ...@@ -948,12 +970,7 @@ They are described in the following section.
@subsection Minibuffer Commands that Do Completion @subsection Minibuffer Commands that Do Completion
This section describes the keymaps, commands and user options used This section describes the keymaps, commands and user options used
in the minibuffer to do completion. The description refers to the in the minibuffer to do completion.
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.
@defvar minibuffer-completion-table @defvar minibuffer-completion-table
The value of this variable is the collection used for completion in The value of this variable is the collection used for completion in
...@@ -969,10 +986,25 @@ minibuffer completion functions. ...@@ -969,10 +986,25 @@ minibuffer completion functions.
@end defvar @end defvar
@defvar minibuffer-completion-confirm @defvar minibuffer-completion-confirm
When the value of this variable is non-@code{nil}, Emacs asks for This variable determines whether Emacs asks for confirmation before
confirmation of a completion before exiting the minibuffer. exiting the minibuffer; @code{completing-read} binds this variable,
@code{completing-read} binds this variable, and the function and the function @code{minibuffer-complete-and-exit} checks the value
@code{minibuffer-complete-and-exit} checks the value before exiting. 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 @end defvar
@deffn Command minibuffer-complete-word @deffn Command minibuffer-complete-word
...@@ -1113,7 +1145,7 @@ Lisp function. When possible, do all minibuffer input as part of ...@@ -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} reading the arguments for a command, in the @code{interactive}
specification. @xref{Defining Commands}. 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. 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 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}, 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 ...@@ -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 @var{prompt} before the colon to follow the convention for reading from
the minibuffer with a default value (@pxref{Programming Tips}). the minibuffer with a default value (@pxref{Programming Tips}).
If @var{existing} is non-@code{nil}, then the name specified must be The optional argument @var{require-match} has the same meaning as in
that of an existing buffer. The usual commands to exit the minibuffer @code{completing-read}. @xref{Minibuffer Completion}.
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.)
In the following example, the user enters @samp{minibuffer.t}, and In the following example, the user enters @samp{minibuffer.t}, and
then types @key{RET}. The argument @var{existing} is @code{t}, and the then types @key{RET}. The argument @var{require-match} is @code{t},
only buffer name starting with the given input is and the only buffer name starting with the given input is
@samp{minibuffer.texi}, so that name is the value. @samp{minibuffer.texi}, so that name is the value.
@example @example
...@@ -1168,6 +1195,11 @@ that call @code{read-buffer} to read a buffer name will actually use the ...@@ -1168,6 +1195,11 @@ that call @code{read-buffer} to read a buffer name will actually use the
@code{iswitchb} package to read it. @code{iswitchb} package to read it.
@end defvar @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 @defun read-command prompt &optional default
This function reads the name of a command and returns it as a Lisp This function reads the name of a command and returns it as a Lisp
symbol. The argument @var{prompt} is used as in symbol. The argument @var{prompt} is used as in
...@@ -1302,23 +1334,18 @@ and @code{read-input-method-name}, in @ref{Input Methods}. ...@@ -1302,23 +1334,18 @@ and @code{read-input-method-name}, in @ref{Input Methods}.
for reading file names and shell commands. They provide special for reading file names and shell commands. They provide special
features including automatic insertion of the default directory. 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 This function reads a file name in the minibuffer, prompting with
@var{prompt} and providing completion. @var{prompt} and providing completion.
If @var{existing} is non-@code{nil}, then the user must specify the name The optional argument @var{require-match} has the same meaning as in
of an existing file; @key{RET} performs completion to make the name @code{completing-read}. @xref{Minibuffer Completion}.
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.
@code{read-file-name} uses @code{read-file-name} uses
@code{minibuffer-local-filename-completion-map} as the keymap if @code{minibuffer-local-filename-completion-map} as the keymap if
@var{existing} is @code{nil}, and uses @var{require-match} is @code{nil}, and uses
@code{minibuffer-local-filename-must-match-map} if @var{existing} is @code{minibuffer-local-filename-must-match-map} if @var{require-match}
non-@code{nil}. @xref{Completion Commands}. is non-@code{nil}. @xref{Completion Commands}.
The argument @var{directory} specifies the directory to use for The argument @var{directory} specifies the directory to use for
completion of relative file names. It should be an absolute directory 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 ...@@ -1341,7 +1368,7 @@ contents that @code{read-file-name} inserted initially. The initial
minibuffer contents are always non-empty if minibuffer contents are always non-empty if
@code{insert-default-directory} is non-@code{nil}, as it is by @code{insert-default-directory} is non-@code{nil}, as it is by
default. @var{default} is not checked for validity, regardless of the 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 non-@code{nil}, the initial minibuffer contents should be a valid file
(or directory) name. Otherwise @code{read-file-name} attempts (or directory) name. Otherwise @code{read-file-name} attempts
completion if the user exits without any editing, and does not return 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 ...@@ -1361,9 +1388,9 @@ types @key{RET} without any editing, @code{read-file-name} simply
returns the pre-inserted contents of the minibuffer. returns the pre-inserted contents of the minibuffer.
If the user types @key{RET} in an empty minibuffer, this function If the user types @key{RET} in an empty minibuffer, this function
returns an empty string, regardless of the value of @var{existing}. returns an empty string, regardless of the value of
This is, for instance, how the user can make the current buffer visit @var{require-match}. This is, for instance, how the user can make the
no file using @code{M-x set-visited-file-name}. 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 If @var{predicate} is non-@code{nil}, it specifies a function of one
argument that decides which file names are acceptable completion 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 ...@@ -1420,7 +1447,7 @@ If this variable is non-@code{nil}, @code{read-file-name} ignores case
when performing completion. when performing completion.
@end defvar @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 This function is like @code{read-file-name} but allows only directory
names as completion possibilities. 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