(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.
-* Programmed Completion:: Writing your own completion-function.
+* Completion Variables:: Variables controlling completion behavior.
+* Programmed Completion:: Writing your own completion function.
* Completion in Buffers:: Completing text in ordinary buffers.
@end menu
@defun test-completion string collection &optional predicate
@anchor{Definition of test-completion}
This function returns non-@code{nil} if @var{string} is a valid
-completion possibility specified by @var{collection} and
+completion alternative specified by @var{collection} and
@var{predicate}. The arguments are the same as in
@code{try-completion}. For instance, if @var{collection} is a list of
strings, this is true if @var{string} appears in the list and
If @var{predicate} is non-@code{nil}, it specifies a function of one
argument that decides which file names are acceptable completion
-possibilities. A file name is an acceptable value if @var{predicate}
+alternatives. A file name is an acceptable value if @var{predicate}
returns non-@code{nil} for it.
Here is an example of using @code{read-file-name}:
@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.
+names as completion alternatives.
If @var{default} is @code{nil} and @var{initial} is non-@code{nil},
@code{read-directory-name} constructs a substitute default by
command and file names that are part of a shell command.
@end defvar
-@node Completion Styles
-@subsection Completion Styles
-@cindex completion styles
+@node Completion Variables
+@subsection Completion Variables
- A @dfn{completion style} is a set of rules for generating
-completions. The user option @code{completion-styles} stores a list
-of completion styles, which are represented by symbols.
+ Here are some variables which can be used to alter the default
+completion behavior.
+@cindex completion styles
@defopt completion-styles
-This is a list of completion style symbols to use for performing
-completion. Each completion style in this list must be defined in
+The value of this variable is a list of completion styles to use for
+performing completion. A @dfn{completion style} is a set of rules for
+generating completions.
+
+Each style listed in this variable must be one of those defined in
@code{completion-styles-alist}.
@end defopt
@defvar completion-styles-alist
This variable stores a list of available completion styles. Each
-element in the list must have the form @samp{(@var{name}
-@var{try-completion} @var{all-completions})}. Here, @var{name} is the
-name of the completion style (a symbol), which may be used in
-@code{completion-styles-alist} to refer to this style.
-
-@var{try-completion} is the function that does the completion, and
-@var{all-completions} is the function that lists the completions.
-These functions should accept four arguments: @var{string},
-@var{collection}, @var{predicate}, and @var{point}. The @var{string},
-@var{collection}, and @var{predicate} arguments have the same meanings
-as in @code{try-completion} (@pxref{Basic Completion}), and the
-@var{point} argument is the position of point within @var{string}.
-Each function should return a non-@code{nil} value if it performed its
-job, and @code{nil} if it did not (e.g., if there is no way to
-complete @var{string} according to the completion style).
-
-When the user calls a completion command, such as
+element in the list has the form
+
+@example
+(@var{name} @var{try-completion} @var{all-completions} @var{doc})
+@end example
+
+@noindent
+Here, @var{name} is the name of the completion style (a symbol), which
+may be used in @code{completion-styles-alist} to refer to this style;
+@var{try-completion} is the function that does the completion;
+@var{all-completions} is the function that lists the completions; and
+@var{doc} is a string describing the completion style.
+
+The @var{try-completion} and @var{all-completions} functions should
+each accept four arguments: @var{string}, @var{collection},
+@var{predicate}, and @var{point}. The @var{string}, @var{collection},
+and @var{predicate} arguments have the same meanings as in
+@code{try-completion} (@pxref{Basic Completion}), and the @var{point}
+argument is the position of point within @var{string}. Each function
+should return a non-@code{nil} value if it performed its job, and
+@code{nil} if it did not (e.g.@: if there is no way to complete
+@var{string} according to the completion style).
+
+When the user calls a completion command like
@code{minibuffer-complete} (@pxref{Completion Commands}), Emacs looks
for the first style listed in @code{completion-styles} and calls its
@var{try-completion} function. If this function returns @code{nil},
-Emacs moves to the next completion style listed in
-@code{completion-styles} and calls its @var{try-completion} function,
-and so on until one of the @var{try-completion} functions successfully
-performs completion and returns a non-@code{nil} value. A similar
-procedure is used for listing completions, via the
-@var{all-completions} functions.
+Emacs moves to the next listed completion style and calls its
+@var{try-completion} function, and so on until one of the
+@var{try-completion} functions successfully performs completion and
+returns a non-@code{nil} value. A similar procedure is used for
+listing completions, via the @var{all-completions} functions.
+
+@xref{Completion Styles,,, emacs, The GNU Emacs Manual}, for a
+description of the available completion styles.
@end defvar
- 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; @code{emacs21},
-which performs completion according to the rules used in Emacs 21; and
-@code{initials}, which completes acronyms and initialisms.
+@defvar completion-extra-properties
+This variable is used to specify extra properties of the current
+completion command. It is intended to be let-bound by specialized
+completion commands. Its value should be a list of property and value
+pairs. The following properties are supported:
+
+@table @code
+@item :annotation-function
+The value should be a function to add annotations in the completions
+buffer. This function must accept one argument, a completion, and
+should either return @code{nil} or a string to be displayed next to
+the completion.
+
+@item :exit-function
+The value should be a function to run after performing completion.
+The function should accept two arguments, @var{string} and
+@var{status}, where @var{string} is the text to which the field was
+completed and @var{status} indicates what kind of operation happened:
+@code{finished} if text is now complete, @code{sole} if the text
+cannot be further completed but completion is not finished, or
+@code{exact} if the text is a valid completion but may be further
+completed.
+@end table
+@end defvar
@node Programmed Completion
@subsection Programmed Completion
The string to be completed.
@item
-The predicate function to filter possible matches, or @code{nil} if
-none. Your function should call the predicate for each possible match,
-and ignore the possible match if the predicate returns @code{nil}.
+A predicate function with which to filter possible matches, or
+@code{nil} if none. The function should call the predicate for each
+possible match, and ignore the match if the predicate returns
+@code{nil}.
@item
-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
+A flag specifying the type of completion operation to perform. This
+is one of the following four values:
- There are currently four methods, i.e. four flag values, one for
-each of the four different basic operations:
-
-@itemize @bullet
-@item
-@code{nil} specifies @code{try-completion}. The completion function
-should return the completion of the specified string, or @code{t} if the
-string is a unique and exact match already, or @code{nil} if the string
-matches no possibility.
-
-If the string is an exact match for one possibility, but also matches
-other longer possibilities, the function should return the string, not
-@code{t}.
-
-@item
-@code{t} specifies @code{all-completions}. The completion function
+@table @code
+@item nil
+This specifies a @code{try-completion} operation. The function should
+return @code{t} if the specified string is a unique and exact match;
+if there is more than one match, it should return the common substring
+of all matches (if the string is an exact match for one completion
+alternative but also matches other longer alternatives, the return
+value is the string); if there are no matches, it should return
+@code{nil}.
+
+@item t
+This specifies an @code{all-completions} operation. The function
should return a list of all possible completions of the specified
string.
-@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 lambda
+This specifies a @code{test-completion} operation. The function
+should return @code{t} if the specified string is an exact match for
+some completion alternative; @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 the string to complete, and END is the position of the end boundary
-in SUFFIX.
+@item (boundaries . @var{suffix})
+This specifies a @code{completion-boundaries} operation. The function
+should return @code{(boundaries START . END)}, where START is the
+position of the beginning boundary in the specified string, and END is
+the position of the end boundary in SUFFIX.
+@end table
@end itemize
@defun completion-table-dynamic function
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 Completion in Buffers
@subsection Completion in Ordinary Buffers
@cindex inline completion
@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
+(@pxref{Completion Variables}). @var{props} is a property list for
additional information; the following optional properties are
recognized:
HCoop / bpt / emacs.git / blobdiff