procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Document completion-extra-properties in Lisp manual.

Browse source 
* 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.
This commit is contained in:
Chong Yidong 2012-04-04 17:19:32 +08:00
parent a7972adfd8
commit 321cc491c5
8 changed files with 130 additions and 105 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
doc/lispref/ChangeLog
View file

@ -1,5 +1,11 @@
2012-04-04 Chong Yidong <cyd@gnu.org>
* 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.

4
doc/lispref/elisp.texi
View file

@ -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

187
doc/lispref/minibuf.texi
View file

@ -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
@node Completion Variables
@subsection Completion Variables
Here are some variables which can be used to alter the default
completion behavior.
@cindex completion styles
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.
@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.
element in the list has the form
@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).
@example
(@var{name} @var{try-completion} @var{all-completions} @var{doc})
@end example
When the user calls a completion command, such as
@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:
@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}.
@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
@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:

4
doc/lispref/vol1.texi
View file

@ -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

4
doc/lispref/vol2.texi
View file

@ -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

1
etc/NEWS
View file

@ -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

2
lisp/ChangeLog
View file

@ -1,5 +1,7 @@
2012-04-04 Chong Yidong <cyd@gnu.org>
* minibuffer.el (completion-extra-properties): Doc fix.
* subr.el (delayed-warnings-hook): Doc fix.
2012-04-04 Daiki Ueno <ueno@unixuser.org>

27
lisp/minibuffer.el
View file

@ -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