@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, 2002,
-@c 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2012
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/minibuf
@node Minibuffers, Command Loop, Read and Print, Top
* Intro to Minibuffers:: Basic information about minibuffers.
* Text from Minibuffer:: How to read a straight text string.
* Object from Minibuffer:: How to read a Lisp object or expression.
-* Minibuffer History:: Recording previous minibuffer inputs
- so the user can reuse them.
+* Minibuffer History:: Recording previous minibuffer inputs
+ so the user can reuse them.
* Initial Input:: Specifying initial contents for the minibuffer.
* Completion:: How to invoke and customize completion.
* Yes-or-No Queries:: Asking a question with a simple answer.
-* Multiple Queries:: Asking a series of similar questions.
-* Reading a Password:: Reading a password from the terminal.
+* Multiple Queries:: Asking a series of similar questions.
+* Reading a Password:: Reading a password from the terminal.
* Minibuffer Commands:: Commands used as key bindings in minibuffers.
* Minibuffer Contents:: How such commands access the minibuffer text.
* Minibuffer Windows:: Operating on the special minibuffer windows.
@cindex minibuffer history
@cindex history list
- A @dfn{minibuffer history list} records previous minibuffer inputs so
-the user can reuse them conveniently. A history list is actually a
-symbol, not a list; it is a variable whose value is a list of strings
-(previous inputs), most recent first.
+ A @dfn{minibuffer history list} records previous minibuffer inputs
+so the user can reuse them conveniently. It is a variable whose value
+is a list of strings (previous inputs), most recent first.
- There are many separate history lists, used for different kinds of
-inputs. It's the Lisp programmer's job to specify the right history
-list for each use of the minibuffer.
+ There are many separate minibuffer history lists, used for different
+kinds of inputs. It's the Lisp programmer's job to specify the right
+history list for each use of the minibuffer.
- You specify the history list with the optional @var{hist} argument
-to either @code{read-from-minibuffer} or @code{completing-read}. Here
-are the possible values for it:
+ You specify a minibuffer history list with the optional @var{hist}
+argument to @code{read-from-minibuffer} or @code{completing-read}.
+Here are the possible values for it:
@table @asis
@item @var{variable}
shell commands.
* Completion Styles:: Specifying rules for performing completion.
* Programmed Completion:: Writing your own completion-function.
+* Completion in Buffers:: Completing text in ordinary buffers.
@end menu
@node Basic Completion
@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 or symbols, an alist, an
-obarray, a hash table, or a completion function (@pxref{Programmed
-Completion}).
+completions of @var{string} in @var{collection}.
+
+@cindex completion table
+The @var{collection} argument is called the @dfn{completion table}.
+Its value must be a list of strings, an alist whose keys are strings
+or symbols, an obarray, a hash table, or a completion function.
Completion compares @var{string} against each of the permissible
completions specified by @var{collection}. If no permissible
If @var{collection} is an alist (@pxref{Association Lists}), the
permissible completions are the elements of the alist that are either
-strings, symbols, or conses whose @sc{car} is a string or symbol.
+strings, or conses whose @sc{car} is a string or symbol.
Symbols are converted to strings using @code{symbol-name}. Other
elements of the alist are ignored. (Remember that in Emacs Lisp, the
elements of alists do not @emph{have} to be conses.) In particular, a
-list of strings or symbols is allowed, even though we usually do not
+list of strings is allowed, even though we usually do not
think of such lists as alists.
@cindex obarray in completion
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
-function is called with three arguments: @var{string}, @var{predicate}
-and @code{nil} (the reason for the third argument is so that the same
-function can be used in @code{all-completions} and do the appropriate
-thing in either case). @xref{Programmed Completion}.
+You can also use a function as @var{collection}. Then the function is
+solely responsible for performing completion; @code{try-completion}
+returns whatever this function returns. The function is called with
+three arguments: @var{string}, @var{predicate} and @code{nil} (the
+reason for the third argument is so that the same 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, unless @var{collection} is a hash table, in
it returns, @code{test-completion} returns in turn.
@end defun
+@defun completion-boundaries string collection predicate suffix
+This function returns the boundaries of the field on which @var{collection}
+will operate, assuming that @var{string} holds the text before point
+and @var{suffix} holds the text after point.
+
+Normally completion operates on the whole string, so for all normal
+collections, this will always return @code{(0 . (length
+@var{suffix}))}. But more complex completion such as completion on
+files is done one field at a time. For example, completion of
+@code{"/usr/sh"} will include @code{"/usr/share/"} but not
+@code{"/usr/share/doc"} even if @code{"/usr/share/doc"} exists.
+Also @code{all-completions} on @code{"/usr/sh"} will not include
+@code{"/usr/share/"} but only @code{"share/"}. So if @var{string} is
+@code{"/usr/sh"} and @var{suffix} is @code{"e/doc"},
+@code{completion-boundaries} will return @code{(5 . 1)} which tells us
+that the @var{collection} will only return completion information that
+pertains to the area after @code{"/usr/"} and before @code{"/doc"}.
+@end defun
+
If you store a completion alist in a variable, you should mark the
variable as ``risky'' with a non-@code{nil}
@code{risky-local-variable} property. @xref{File Local Variables}.
@defvar completion-ignore-case
-If the value of this variable is non-@code{nil}, Emacs does not
-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}).
+If the value of this variable is non-@code{nil}, case is not
+considered significant in completion. Within @code{read-file-name},
+this variable is overridden by
+@code{read-file-name-completion-ignore-case} (@pxref{Reading File
+Names}); within @code{read-buffer}, it is overridden by
+@code{read-buffer-completion-ignore-case} (@pxref{High-Level
+Completion}).
@end defvar
@defvar completion-regexp-list
It is done by calling @var{fun} with no arguments. The
value @var{fun} returns becomes the permanent value of @var{var}.
-Here is an example of use:
+Here is a usage example:
@smallexample
(defvar foo (lazy-completion-table foo make-my-alist))
@end smallexample
@end defmac
-The function @code{completion-in-region} provides a convenient way to
-perform completion on an arbitrary stretch of text in an Emacs buffer:
-
-@defun completion-in-region start end collection &optional predicate
-This function completes the text in the current buffer between the
-positions @var{start} and @var{end}, using @var{collection}. The
-argument @var{collection} has the same meaning as in
-@code{try-completion} (@pxref{Basic Completion}).
-
-This function inserts the completion text directly into the current
-buffer. Unlike @code{completing-read} (@pxref{Minibuffer
-Completion}), it does not activate the minibuffer.
-
-For this function to work, point must be somewhere between @var{start}
-and @var{end}.
-@end defun
-
@node Minibuffer Completion
@subsection Completion and the Minibuffer
@cindex minibuffer completion
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} (@pxref{Basic
-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}.
+The actual completion is done by passing the completion table
+@var{collection} and the completion predicate @var{predicate} to the
+function @code{try-completion} (@pxref{Basic 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}.
The value of the optional argument @var{require-match} determines how
the user may exit the minibuffer:
in the minibuffer to do completion.
@defvar minibuffer-completion-table
-The value of this variable is the collection used for completion in
-the minibuffer. This is the global variable that contains what
+The value of this variable is the completion table 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}.
+minibuffer completion commands such as
+@code{minibuffer-complete-word}.
@end defvar
@defvar minibuffer-completion-predicate
@end defun
@defopt read-buffer-function
-This variable specifies how to read buffer names. For example, if you
-set this variable to @code{iswitchb-read-buffer}, all Emacs commands
-that call @code{read-buffer} to read a buffer name will actually use the
-@code{iswitchb} package to read it.
+This variable specifies how to read buffer names. The function is
+called with the arguments passed to @code{read-buffer}. For example,
+if you set this variable to @code{iswitchb-read-buffer}, all Emacs
+commands that call @code{read-buffer} to read a buffer name will
+actually use the @code{iswitchb} package to read it.
@end defopt
@defopt read-buffer-completion-ignore-case
@deffn Command read-color &optional prompt convert allow-empty display
This function reads a string that is a color specification, either the
color's name or an RGB hex value such as @code{#RRRGGGBBB}. It
-prompts with @var{prompt} (default: @code{"Color (name or #R+G+B+):"})
+prompts with @var{prompt} (default: @code{"Color (name or #RGB triplet):"})
and provides completion for color names, but not for hex RGB values.
In addition to names of standard colors, completion candidates include
the foreground and background colors at point.
Valid RGB values are described in @ref{Color Names}.
-The function's return value is the color name typed by the user in the
+The function's return value is the string typed by the user in the
minibuffer. However, when called interactively or if the optional
-argument @var{convert} is non-@code{nil}, it converts the name into
-the color's RGB value and returns that value as a string. If an
-invalid color name was specified, this function signals an error,
-except that empty color names are allowed when @code{allow-empty} is
+argument @var{convert} is non-@code{nil}, it converts any input color
+name into the corresponding RGB value string and instead returns that.
+This function requires a valid color specification to be input.
+Empty color names are allowed when @code{allow-empty} is
non-@code{nil} and the user enters null input.
Interactively, or when @var{display} is non-@code{nil}, the return
graphical file dialog is platform-dependent. Here, we simply document
the behavior when using the minibuffer.
-The optional argument @var{require-match} has the same meaning as in
-@code{completing-read}. @xref{Minibuffer Completion}.
+@code{read-file-name} does not automatically expand the returned file
+name. You must call @code{expand-file-name} yourself if an absolute
+file name is required.
-@code{read-file-name} uses
-@code{minibuffer-local-filename-completion-map} as the keymap if
-@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 optional argument @var{require-match} has the same meaning as in
+@code{completing-read}. @xref{Minibuffer Completion}. If
+@var{require-match} is @code{nil}, the local keymap in the minibuffer
+is @code{minibuffer-local-filename-completion-map}; otherwise, it is
+@code{minibuffer-local-filename-must-match-map}. @xref{Completion
+Commands}.
The argument @var{directory} specifies the directory to use for
-completion of relative file names. It should be an absolute directory
+completing 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}.
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:
+Here is an example of using @code{read-file-name}:
@example
@group
@subsection Programmed Completion
@cindex programmed completion
- Sometimes it is not possible to create an alist or an obarray
-containing all the intended possible completions. In such a case, you
-can supply your own function to compute the completion of a given
-string. This is called @dfn{programmed completion}. Emacs uses
-programmed completion when completing file names (@pxref{File Name
-Completion}).
+ Sometimes it is not possible or convenient to create an alist or
+an obarray containing all the intended possible completions ahead
+of time. In such a case, you can supply your own function to compute
+the completion of a given string. This is called @dfn{programmed
+completion}. Emacs uses programmed completion when completing file
+names (@pxref{File Name Completion}), among many other cases.
- To use this feature, pass a symbol with a function definition as the
-@var{collection} argument to @code{completing-read}. The function
+ To use this feature, pass a function as the @var{collection}
+argument to @code{completing-read}. The function
@code{completing-read} arranges to pass your completion function along
-to @code{try-completion} and @code{all-completions}, which will then let
-your function do all the work.
+to @code{try-completion}, @code{all-completions}, and other basic
+completion functions, which will then let your function do all
+the work.
The completion function should accept three arguments:
and ignore the possible match if the predicate returns @code{nil}.
@item
-A flag specifying the type of operation.
+A flag specifying the type of operation. The best way to think about
+it is that the function stands for an object (in the
+``object-oriented'' sense of the word), and this third argument
+specifies which method to run.
@end itemize
- There are three flag values for three operations:
+ There are currently four methods, i.e. four flag values, one for
+each of the four different basic operations:
@itemize @bullet
@item
@code{lambda} specifies @code{test-completion}. The completion
function should return @code{t} if the specified string is an exact
match for some possibility; @code{nil} otherwise.
-@end itemize
- It would be consistent and clean for completion functions to allow
-lambda expressions (lists that are functions) as well as function
-symbols as @var{collection}, but this is impossible. Lists as
-completion tables already have other meanings, and it would be
-unreliable to treat one differently just because it is also a possible
-function. So you must arrange for any function you wish to use for
-completion to be encapsulated in a symbol.
+@item
+@code{(boundaries . SUFFIX)} specifies @code{completion-boundaries}.
+The function should return a value of the form @code{(boundaries
+START . END)} where START is the position of the beginning boundary
+in the string to complete, and END is the position of the end boundary
+in SUFFIX.
+@end itemize
@defun completion-table-dynamic function
This function is a convenient way to write a function that can act as
(@pxref{Completion Commands}).
@end defvar
+@node Completion in Buffers
+@subsection Completion in Ordinary Buffers
+@cindex inline completion
+
+@findex completion-at-point
+ Although completion is usually done in the minibuffer, the
+completion facility can also be used on the text in ordinary Emacs
+buffers. In many major modes, in-buffer completion is performed by
+the @kbd{C-M-i} or @kbd{M-@key{TAB}} command, bound to
+@code{completion-at-point}. @xref{Symbol Completion,,, emacs, The GNU
+Emacs Manual}. This command uses the abnormal hook variable
+@code{completion-at-point-functions}:
+
+@defvar completion-at-point-functions
+The value of this abnormal hook should be a list of functions, which
+are used to compute a completion table for completing the text at
+point. It can be used by major modes to provide mode-specific
+completion tables (@pxref{Major Mode Conventions}).
+
+When the command @code{completion-at-point} runs, it calls the
+functions in the list one by one, without any argument. Each function
+should return @code{nil} if it is unable to produce a completion table
+for the text at point. Otherwise it should return a list of the form
+
+@example
+(@var{start} @var{end} @var{collection} . @var{props})
+@end example
+
+@noindent
+@var{start} and @var{end} delimit the text to complete (which should
+enclose point). @var{collection} is a completion table for completing
+that text, in a form suitable for passing as the second argument to
+@code{try-completion} (@pxref{Basic Completion}); completion
+alternatives will be generated from this completion table in the usual
+way, via the completion styles defined in @code{completion-styles}
+(@pxref{Completion Styles}). @var{props} is a property list for
+additional information; the following optional properties are
+recognized:
+
+@table @code
+@item :predicate
+The value should be a predicate that completion candidates need to
+satisfy.
+
+@item :exclusive
+If the value is @code{no}, then if the completion table fails to match
+the text at point, then @code{completion-at-point} moves on to the
+next function in @code{completion-at-point-functions} instead of
+reporting a completion failure.
+@end table
+
+A function in @code{completion-at-point-functions} may also return a
+function. In that case, that returned function is called, with no
+argument, and it is entirely responsible for performing the
+completion. We discourage this usage; it is intended to help convert
+old code to using @code{completion-at-point}.
+
+The first function in @code{completion-at-point-functions} to return a
+non-@code{nil} value is used by @code{completion-at-point}. The
+remaining functions are not called. The exception to this is when
+there is a @code{:exclusive} specification, as described above.
+@end defvar
+
+ The following function provides a convenient way to perform
+completion on an arbitrary stretch of text in an Emacs buffer:
+
+@defun completion-in-region start end collection &optional predicate
+This function completes the text in the current buffer between the
+positions @var{start} and @var{end}, using @var{collection}. The
+argument @var{collection} has the same meaning as in
+@code{try-completion} (@pxref{Basic Completion}).
+
+This function inserts the completion text directly into the current
+buffer. Unlike @code{completing-read} (@pxref{Minibuffer
+Completion}), it does not activate the minibuffer.
+
+For this function to work, point must be somewhere between @var{start}
+and @var{end}.
+@end defun
+
+
@node Yes-or-No Queries
@section Yes-or-No Queries
@cindex asking the user questions
actual message is obtained by passing @var{string} and @var{args}
through @code{format}. @xref{Formatting Strings}.
@end defun
-
-@ignore
- arch-tag: bba7f945-9078-477f-a2ce-18818a6e1218
-@end ignore