@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 Free Software Foundation, Inc.
+@c 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011
+@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.
set to a non-@code{nil} value.
@end defvar
-@defvar history-length
+@defopt history-length
The value of this variable specifies the maximum length for all
history lists that don't specify their own maximum lengths. If the
-value is @code{t}, that means there no maximum (don't delete old
+value is @code{t}, that means there is no maximum (don't delete old
elements). The value of @code{history-length} property of the history
list variable's symbol, if set, overrides this variable for that
particular history list.
-@end defvar
+@end defopt
-@defvar history-delete-duplicates
+@defopt history-delete-duplicates
If the value of this variable is @code{t}, that means when adding a
new history element, all previous identical elements are deleted.
-@end defvar
+@end defopt
Here are some of the standard minibuffer history list variables:
@menu
* Basic Completion:: Low-level functions for completing strings.
- (These are too low level to use the minibuffer.)
* Minibuffer Completion:: Invoking the minibuffer with completion.
* Completion Commands:: Minibuffer commands that do completion.
* High-Level Completion:: Convenient special cases of completion
- (reading buffer name, file name, etc.)
+ (reading buffer name, file name, etc.).
* Reading File Names:: Using completion to read file names and
shell commands.
* Completion Styles:: Specifying rules for performing completion.
@node Basic Completion
@subsection Basic Completion Functions
- The completion functions @code{try-completion},
-@code{all-completions} and @code{test-completion} have nothing in
-themselves to do with minibuffers. We describe them in this chapter
-so as to keep them near the higher-level completion features that do
-use the minibuffer.
-
- 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.
+ The following completion functions have nothing in themselves to do
+with minibuffers. We describe them here to keep them near the
+higher-level completion features that do use the minibuffer.
@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 function that implements a virtual set of
-strings (see below).
+obarray, a hash table, or a completion function (@pxref{Programmed
+Completion}).
Completion compares @var{string} against each of the permissible
-completions specified by @var{collection}; if the beginning of the
-permissible completion equals @var{string}, it matches. If no permissible
-completions match, @code{try-completion} returns @code{nil}. If only
-one permissible completion matches, and the match is exact, then
-@code{try-completion} returns @code{t}. Otherwise, the value is the
-longest initial sequence common to all the permissible completions that
-match.
+completions specified by @var{collection}. If no permissible
+completions match, @code{try-completion} returns @code{nil}. If there
+is just one matching completion, and the match is exact, it returns
+@code{t}. Otherwise, it returns the longest initial sequence common
+to all possible matching completions.
If @var{collection} is an alist (@pxref{Association Lists}), the
permissible completions are the elements of the alist that are either
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;
+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
+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}.
+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
@var{string}. The arguments to this function (aside from
@var{nospace}) are the same as those of @code{try-completion}. Also,
this function uses @code{completion-regexp-list} in the same way that
-@code{try-completion} does. The optional argument @var{nospace} only
-matters if @var{string} is the empty string. In that case, if
-@var{nospace} is non-@code{nil}, completions that start with a space
-are ignored.
+@code{try-completion} does.
+
+The optional argument @var{nospace} is obsolete. If it is
+non-@code{nil}, completions that start with a space are ignored unless
+@var{string} starts with a space.
If @var{collection} is a function, it is called with three arguments:
@var{string}, @var{predicate} and @code{t}; then @code{all-completions}
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
@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
@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}. 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}.
+@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:
@end example
@end defun
-@defvar 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.
-@end defvar
+@defopt read-buffer-function
+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
-@defvar read-buffer-completion-ignore-case
+@defopt read-buffer-completion-ignore-case
If this variable is non-@code{nil}, @code{read-buffer} ignores case
when performing completion.
-@end defvar
+@end defopt
@defun read-command prompt &optional default
This function reads the name of a command and returns it as a Lisp
except that 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{nill}, the return
+Interactively, or when @var{display} is non-@code{nil}, the return
value is also displayed in the echo area.
@end deffn
@cindex read file names
@cindex prompt for file name
- Here is a couple of other high-level completion functions, designed
-for reading file names and shell commands. They provide special
-features including automatic insertion of the default directory.
+ The high-level completion functions @code{read-file-name},
+@code{read-directory-name}, and @code{read-shell-command} are designed
+to read file names, directory names, and shell commands respectively.
+They provide special features, including automatic insertion of the
+default directory.
@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.
+This function reads a file name, prompting with @var{prompt} and
+providing completion.
+
+As an exception, this function reads a file name using a graphical
+file dialog instead of the minibuffer, if (i) it is invoked via a
+mouse command, and (ii) the selected frame is on a graphical display
+supporting such dialogs, and (iii) the variable @code{use-dialog-box}
+is non-@code{nil} (@pxref{Dialog Boxes,, Dialog Boxes, emacs, The GNU
+Emacs Manual}), and (iv) the @var{directory} argument, described
+below, does not specify a remote file (@pxref{Remote Files,, Remote
+Files, emacs, The GNU Emacs Manual}). The exact behavior when using a
+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}.
@var{directory} is also inserted in the minibuffer as initial input.
It defaults to the current buffer's value of @code{default-directory}.
-@c Emacs 19 feature
If you specify @var{initial}, that is an initial file name to insert
in the buffer (after @var{directory}, if that is inserted). In this
case, point goes at the beginning of @var{initial}. The default for
doing its usual work.
@end defvar
-@defvar read-file-name-completion-ignore-case
+@defopt read-file-name-completion-ignore-case
If this variable is non-@code{nil}, @code{read-file-name} ignores case
when performing completion.
-@end defvar
+@end defopt
@defun read-directory-name prompt &optional directory default require-match initial
This function is like @code{read-file-name} but allows only directory
@var{all-completions} functions.
@end defvar
- By default, @code{completion-styles-alist} contains four pre-defined
+ By default, @code{completion-styles-alist} contains five pre-defined
completion styles: @code{basic}, a basic completion style;
@code{partial-completion}, which does partial completion (completing
each word in the input separately); @code{emacs22}, which performs
-completion according to the rules used in Emacs 22; and
-@code{emacs21}, which performs completion according to the rules used
-in Emacs 21.
+completion according to the rules used in Emacs 22; @code{emacs21},
+which performs completion according to the rules used in Emacs 21; and
+@code{initials}, which completes acronyms and initialisms.
@node Programmed Completion
@subsection 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}.
+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.
+
+@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
+in the string to complete, and END is the position of the end boundary
+in SUFFIX.
@end itemize
It would be consistent and clean for completion functions to allow
function. So you must arrange for any function you wish to use for
completion to be encapsulated in a symbol.
- Emacs uses programmed completion when completing file names.
-@xref{File Name Completion}.
-
@defun completion-table-dynamic function
This function is a convenient way to write a function that can act as
programmed completion function. The argument @var{function} should be
and the interface for programmed completion functions.
@end defun
+@defvar completion-annotate-function
+The value of this variable, if non-@code{nil}, should be a function
+for ``annotating'' the entries in the @samp{*Completions*} buffer.
+The function should accept a single argument, the completion string
+for an entry. It should return an additional string to display next
+to that entry in the @samp{*Completions*} buffer, or @code{nil} if no
+additional string is to be displayed.
+
+The function can determine the collection used for the current
+completion via the variable @code{minibuffer-completion-table}
+(@pxref{Completion Commands}).
+@end defvar
+
@node Yes-or-No Queries
@section Yes-or-No Queries
@cindex asking the user questions
frame. If an integer, it specifies a number of lines.
@end defopt
-@defun minibuffer-message string
+@defun minibuffer-message string &rest args
This function displays @var{string} temporarily at the end of the
minibuffer text, for two seconds, or until the next input event
-arrives, whichever comes first.
+arrives, whichever comes first. If @var{args} is non-@code{nil}, the
+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