@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
@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
@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
@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
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},
@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
@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
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
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
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
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.
HCoop / bpt / emacs.git / commitdiff