# HG changeset patch # User Chong Yidong # Date 1237265654 0 # Node ID 25d094256b42d135beca158c37c39ac76d63a494 # Parent 6192629dc5c92adfd13de3966fdd960c0bdc6e05 (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. diff -r 6192629dc5c9 -r 25d094256b42 doc/lispref/minibuf.texi --- a/doc/lispref/minibuf.texi Tue Mar 17 04:54:03 2009 +0000 +++ b/doc/lispref/minibuf.texi Tue Mar 17 04:54:14 2009 +0000 @@ -824,7 +824,11 @@ @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 @@ @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 @@ @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 @@ @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 @@ 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 @@ @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 @@ @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 @@ 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 @@ 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 @@ 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 @@ 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.