From ea0ff31442804544d4096f1e7eaff9ecb10e479d Mon Sep 17 00:00:00 2001 From: Chong Yidong Date: Fri, 6 Apr 2012 14:39:35 +0800 Subject: [PATCH] * doc/lispref/minibuf.texi (Programmed Completion): Document metadata method. (Completion Variables): Document completion-category-overrides. --- doc/lispref/ChangeLog | 7 +++- doc/lispref/minibuf.texi | 87 ++++++++++++++++++++++++++++++++++------ 2 files changed, 80 insertions(+), 14 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 86f0a91a33f..afd6700ef61 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,9 +1,12 @@ +2012-04-06 Chong Yidong + + * minibuf.texi (Programmed Completion): Document metadata method. + (Completion Variables): Document completion-category-overrides. + 2012-04-05 Chong Yidong * anti.texi (Antinews): Rewrite for Emacs 23. - * minibuf.texi (Programmed Completion): Document metadata method. - 2012-04-04 Chong Yidong * minibuf.texi (Programmed Completion): Remove obsolete variable diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi index 8e1bd4bf5ee..4e11bc30d49 100644 --- a/doc/lispref/minibuf.texi +++ b/doc/lispref/minibuf.texi @@ -1575,12 +1575,10 @@ completion behavior. @cindex completion styles @defopt completion-styles -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}. +The value of this variable is a list of completion style (symbols) to +use for performing completion. A @dfn{completion style} is a set of +rules for generating completions. Each symbol in occurring this list +must have a corresponding entry in @code{completion-styles-alist}. @end defopt @defvar completion-styles-alist @@ -1588,15 +1586,16 @@ This variable stores a list of available completion styles. Each element in the list has the form @example -(@var{name} @var{try-completion} @var{all-completions} @var{doc}) +(@var{style} @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. +Here, @var{style} is the name of the completion style (a symbol), +which may be used in the @code{completion-styles} variable 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}, @@ -1622,6 +1621,31 @@ listing completions, via the @var{all-completions} functions. description of the available completion styles. @end defvar +@defopt completion-category-overrides +This variable specifies special completion styles and other completion +behaviors to use when completing certain types of text. Its value +should be a list of the form @code{(@var{category} . @var{alist})}. +@var{category} is a symbol describing what is being completed; +currently, the @code{buffer} and @code{file} categories are defined, +but others can be defined via specialized completion functions +(@pxref{Programmed Completion}). @var{alist} is an association list +describing how completion should behave for the corresponding +category. The following alist keys are supported: + +@table @code +@item styles +The value should be a list of completion styles (symbols). + +@item cycle +The value should be a value for @code{completion-cycle-threshold} +(@pxref{Completion Options,,, emacs, The GNU Emacs Manual}) for this +category. +@end table + +@noindent +Additional alist entries may be defined in the future. +@end defopt + @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 @@ -1706,9 +1730,48 @@ 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. + +@item metadata +This specifies a request for information about the state of the +current completion. The function should return an alist, as described +below. The alist may contain any number of elements. @end table + +@noindent +If the flag has any other value, the completion function should return +@code{nil}. @end itemize +The following is a list of metadata entries that a completion function +may return in response to a @code{metadata} flag argument: + +@table @code +@item category +The value should be a symbol describing what kind of text the +completion function is trying to complete. If the symbol matches one +of the keys in @code{completion-category-overrides}, the usual +completion behavior is overridden. @xref{Completion Variables}. + +@item annotation-function +The value should be a function for @dfn{annotating} completions. The +function should take one argument, @var{string}, which is a possible +completion. It should return a string, which is displayed after the +completion @var{string} in the @samp{*Completions*} buffer. + +@item display-sort-function +The value should be a function for sorting completions. The function +should take one argument, a list of completion strings, and return a +sorted list of completion strings. It is allowed to alter the input +list destructively. + +@item cycle-sort-function +The value should be a function for sorting completions, when +@code{completion-cycle-threshold} is non-@code{nil} and the user is +cycling through completion alternatives. @xref{Completion Options,,, +emacs, The GNU Emacs Manual}. Its argument list and return value are +the same as for @code{display-sort-function}. +@end table + @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