From 321cc491c5843ee3af86570d5b2d59b98ba0c422 Mon Sep 17 00:00:00 2001 From: Chong Yidong Date: Wed, 4 Apr 2012 17:19:32 +0800 Subject: [PATCH] Document completion-extra-properties in Lisp manual. * doc/lispref/minibuf.texi (Programmed Completion): Remove obsolete variable completion-annotate-function. (Completion Variables): Rename from Completion Styles. Document completion-extra-properties. Document completion-styles-alist change. * lisp/minibuffer.el (completion-extra-properties): Doc fix. --- doc/lispref/ChangeLog | 6 ++ doc/lispref/elisp.texi | 4 +- doc/lispref/minibuf.texi | 191 ++++++++++++++++++++------------------- doc/lispref/vol1.texi | 4 +- doc/lispref/vol2.texi | 4 +- etc/NEWS | 1 + lisp/ChangeLog | 2 + lisp/minibuffer.el | 27 ++++-- 8 files changed, 132 insertions(+), 107 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 89e740603f..6385400572 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,5 +1,11 @@ 2012-04-04 Chong Yidong + * minibuf.texi (Programmed Completion): Remove obsolete variable + completion-annotate-function. + (Completion Variables): Rename from Completion Styles. Document + completion-extra-properties. Document completion-styles-alist + change. + * display.texi (Delayed Warnings): New node. * os.texi (Notifications): Copyedits. diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index 508b0251a7..a87a7ff3fa 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -649,8 +649,8 @@ Completion (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. Command Loop diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi index 1224d80fdf..0d7e2350bd 100644 --- a/doc/lispref/minibuf.texi +++ b/doc/lispref/minibuf.texi @@ -631,8 +631,8 @@ for reading certain kinds of names with completion. (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 @@ -795,7 +795,7 @@ example for @code{try-completion}: @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 @@ -1429,7 +1429,7 @@ 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 -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}: @@ -1480,7 +1480,7 @@ when performing completion. @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 @@ -1563,57 +1563,85 @@ This keymap is used by @code{read-shell-command} for completing 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 @@ -1640,47 +1668,41 @@ the work. 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 @@ -1692,19 +1714,6 @@ possible completions of it. You can think of 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 @@ -1740,7 +1749,7 @@ 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 +(@pxref{Completion Variables}). @var{props} is a property list for additional information; the following optional properties are recognized: diff --git a/doc/lispref/vol1.texi b/doc/lispref/vol1.texi index 52681510a5..e1fe8ba327 100644 --- a/doc/lispref/vol1.texi +++ b/doc/lispref/vol1.texi @@ -671,8 +671,8 @@ Completion (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. Command Loop diff --git a/doc/lispref/vol2.texi b/doc/lispref/vol2.texi index 3be2628f5e..650d167253 100644 --- a/doc/lispref/vol2.texi +++ b/doc/lispref/vol2.texi @@ -670,8 +670,8 @@ Completion (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. Command Loop diff --git a/etc/NEWS b/etc/NEWS index b9c6ff59ea..37785cd76e 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -1329,6 +1329,7 @@ properties of the current completion: *** Functions on `completion-at-point-functions' can return any of the properties valid for `completion-extra-properties'. ++++ *** `completion-annotate-function' is obsolete. *** New `metadata' method for completion tables. The metadata thus returned diff --git a/lisp/ChangeLog b/lisp/ChangeLog index 32bdd8630c..64177b03c4 100644 --- a/lisp/ChangeLog +++ b/lisp/ChangeLog @@ -1,5 +1,7 @@ 2012-04-04 Chong Yidong + * minibuffer.el (completion-extra-properties): Doc fix. + * subr.el (delayed-warnings-hook): Doc fix. 2012-04-04 Daiki Ueno diff --git a/lisp/minibuffer.el b/lisp/minibuffer.el index 6a6bba1352..bcc6a808d2 100644 --- a/lisp/minibuffer.el +++ b/lisp/minibuffer.el @@ -1269,17 +1269,24 @@ the completions buffer." (defvar completion-extra-properties nil "Property list of extra properties of the current completion job. These include: -`:annotation-function': Function to add annotations in the completions buffer. - The function takes a completion and should either return nil, or a string - that will be displayed next to the completion. The function can access the - completion data via `minibuffer-completion-table' and related variables. + +`:annotation-function': Function to annotate the completions buffer. + The function must accept one argument, a completion string, + and return either nil or a string which is to be displayed + next to the completion (but which is not part of the + completion). The function can access the completion data via + `minibuffer-completion-table' and related variables. + `:exit-function': Function to run after completion is performed. - The function takes at least 2 parameters (STRING and STATUS) where STRING - is the text to which the field was completed and STATUS indicates what - kind of operation happened: if text is now complete it's `finished', if text - cannot be further completed but completion is not finished, it's `sole', if - text is a valid completion but may be further completed, it's `exact', and - other STATUSes may be added in the future.") + + The function must accept two arguments, STRING and STATUS. + STRING is the text to which the field was completed, and + STATUS indicates what kind of operation happened: + `finished' - text is now complete + `sole' - text cannot be further completed but + completion is not finished + `exact' - text is a valid completion but may be further + completed.") (defvar completion-annotate-function nil -- 2.20.1