Docstring and manual updates for completion-at-point-functions.
* doc/lispref/minibuf.texi (Basic Completion): Define "completion table". Move completion-in-region to Completion in Buffers node. (Completion Commands): Use "completion table" terminology. (Completion in Buffers): New node. * doc/lispref/modes.texi (Hooks): add-hook can be used for abnormal hooks too. (Setting Hooks): Update minor mode usage example. (Major Mode Conventions): Note that completion-at-point-functions should be altered locally. Add xref to Completion in Buffers. * lisp/minibuffer.el (completion-at-point-functions): Doc fix.
This commit is contained in:
Chong Yidong
parent
888ab66104
commit
60236b0dca
8 changed files with 154 additions and 69 deletions
|
|
@ -1,3 +1,15 @@
|
|||
2012-02-15 Chong Yidong <cyd@gnu.org>
|
||||
|
||||
* minibuf.texi (Basic Completion): Define "completion table".
|
||||
Move completion-in-region to Completion in Buffers node.
|
||||
(Completion Commands): Use "completion table" terminology.
|
||||
(Completion in Buffers): New node.
|
||||
|
||||
* modes.texi (Hooks): add-hook can be used for abnormal hooks too.
|
||||
(Setting Hooks): Update minor mode usage example.
|
||||
(Major Mode Conventions): Note that completion-at-point-functions
|
||||
should be altered locally. Add xref to Completion in Buffers.
|
||||
|
||||
2012-02-15 Glenn Morris <rgm@gnu.org>
|
||||
|
||||
* processes.texi (Network): Document open-network-stream :parameters.
|
||||
|
|
|
|||
|
|
@ -654,6 +654,7 @@ Completion
|
|||
shell commands.
|
||||
* Completion Styles:: Specifying rules for performing completion.
|
||||
* Programmed Completion:: Writing your own completion-function.
|
||||
* Completion in Buffers:: Completing text in ordinary buffers.
|
||||
|
||||
Command Loop
|
||||
|
||||
|
|
|
|||
|
|
@ -633,6 +633,7 @@ for reading certain kinds of names with completion.
|
|||
shell commands.
|
||||
* Completion Styles:: Specifying rules for performing completion.
|
||||
* Programmed Completion:: Writing your own completion-function.
|
||||
* Completion in Buffers:: Completing text in ordinary buffers.
|
||||
@end menu
|
||||
|
||||
@node Basic Completion
|
||||
|
|
@ -644,10 +645,12 @@ 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, an alist whose keys are
|
||||
strings or symbols, an obarray, a hash table, or a completion function
|
||||
(@pxref{Programmed Completion}).
|
||||
completions of @var{string} in @var{collection}.
|
||||
|
||||
@cindex completion table
|
||||
The @var{collection} argument is called the @dfn{completion table}.
|
||||
Its value must be a list of strings, an alist whose keys are strings
|
||||
or symbols, an obarray, a hash table, or a completion function.
|
||||
|
||||
Completion compares @var{string} against each of the permissible
|
||||
completions specified by @var{collection}. If no permissible
|
||||
|
|
@ -678,13 +681,13 @@ Also, you cannot intern a given symbol in more than one obarray.
|
|||
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 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
|
||||
function can be used in @code{all-completions} and do the appropriate
|
||||
thing in either case). @xref{Programmed Completion}.
|
||||
You can also use 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 function can be used
|
||||
in @code{all-completions} and do the appropriate 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
|
||||
|
|
@ -862,30 +865,13 @@ proper value is done the first time you do completion using @var{var}.
|
|||
It is done by calling @var{fun} with no arguments. The
|
||||
value @var{fun} returns becomes the permanent value of @var{var}.
|
||||
|
||||
Here is an example of use:
|
||||
Here is a usage example:
|
||||
|
||||
@smallexample
|
||||
(defvar foo (lazy-completion-table foo make-my-alist))
|
||||
@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
|
||||
|
|
@ -899,13 +885,14 @@ This function reads a string in the minibuffer, assisting the user by
|
|||
providing completion. It activates the minibuffer with prompt
|
||||
@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} (@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 actual completion is done by passing the completion table
|
||||
@var{collection} and the completion predicate @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:
|
||||
|
|
@ -1005,10 +992,11 @@ They are described in the following section.
|
|||
in the minibuffer to do completion.
|
||||
|
||||
@defvar minibuffer-completion-table
|
||||
The value of this variable is the collection used for completion in
|
||||
the minibuffer. This is the global variable that contains what
|
||||
The value of this variable is the completion table used for completion
|
||||
in the minibuffer. This is the global variable that contains what
|
||||
@code{completing-read} passes to @code{try-completion}. It is used by
|
||||
minibuffer completion commands such as @code{minibuffer-complete-word}.
|
||||
minibuffer completion commands such as
|
||||
@code{minibuffer-complete-word}.
|
||||
@end defvar
|
||||
|
||||
@defvar minibuffer-completion-predicate
|
||||
|
|
@ -1717,6 +1705,87 @@ 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
|
||||
|
||||
@findex completion-at-point
|
||||
Although completion is usually done in the minibuffer, the
|
||||
completion facility can also be used on the text in ordinary Emacs
|
||||
buffers. In many major modes, in-buffer completion is performed by
|
||||
the @kbd{C-M-i} or @kbd{M-@key{TAB}} command, bound to
|
||||
@code{completion-at-point}. @xref{Symbol Completion,,, emacs, The GNU
|
||||
Emacs Manual}. This command uses the abnormal hook variable
|
||||
@code{completion-at-point-functions}:
|
||||
|
||||
@defvar completion-at-point-functions
|
||||
The value of this abnormal hook should be a list of functions, which
|
||||
are used to compute a completion table for completing the text at
|
||||
point. It can be used by major modes to provide mode-specific
|
||||
completion tables (@pxref{Major Mode Conventions}).
|
||||
|
||||
When the command @code{completion-at-point} runs, it calls the
|
||||
functions in the list one by one, without any argument. Each function
|
||||
should return @code{nil} if it is unable to produce a completion table
|
||||
for the text at point. Otherwise it should return a list of the form
|
||||
|
||||
@example
|
||||
(@var{start} @var{end} @var{collection} . @var{props})
|
||||
@end example
|
||||
|
||||
@noindent
|
||||
@var{start} and @var{end} delimit the text to complete (which should
|
||||
enclose point). @var{collection} is a completion table for completing
|
||||
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
|
||||
additional information; the following optional properties are
|
||||
recognized:
|
||||
|
||||
@table @code
|
||||
@item :predicate
|
||||
The value should be a predicate that completion candidates need to
|
||||
satisfy.
|
||||
|
||||
@item :exclusive
|
||||
If the value is @code{no}, then if the completion table fails to match
|
||||
the text at point, then @code{completion-at-point} moves on to the
|
||||
next function in @code{completion-at-point-functions} instead of
|
||||
reporting a completion failure.
|
||||
@end table
|
||||
|
||||
A function in @code{completion-at-point-functions} may also return a
|
||||
function. In that case, that returned function is called, with no
|
||||
argument, and it is entirely responsible for performing the
|
||||
completion. We discourage this usage; it is intended to help convert
|
||||
old code to using @code{completion-at-point}.
|
||||
|
||||
The first function in @code{completion-at-point-functions} to return a
|
||||
non-@code{nil} value is used by @code{completion-at-point}. The
|
||||
remaining functions are not called. The exception to this is when
|
||||
there is a @code{:exclusive} specification, as described above.
|
||||
@end defvar
|
||||
|
||||
The following function 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 Yes-or-No Queries
|
||||
@section Yes-or-No Queries
|
||||
@cindex asking the user questions
|
||||
|
|
|
|||
|
|
@ -48,17 +48,16 @@ you it is normal. We try to make all hooks normal, as much as
|
|||
possible, so that you can use them in a uniform way.
|
||||
|
||||
Every major mode command is supposed to run a normal hook called the
|
||||
@dfn{mode hook} as the one of the last steps of initialization. This
|
||||
makes it easy for a user to customize the behavior of the mode, by
|
||||
overriding the buffer-local variable assignments already made by the
|
||||
mode. Most minor mode functions also run a mode hook at the end. But
|
||||
hooks are used in other contexts too. For example, the hook
|
||||
@code{suspend-hook} runs just before Emacs suspends itself
|
||||
(@pxref{Suspending Emacs}).
|
||||
@dfn{mode hook} as one of the last steps of initialization. This makes
|
||||
it easy for a user to customize the behavior of the mode, by overriding
|
||||
the buffer-local variable assignments already made by the mode. Most
|
||||
minor mode functions also run a mode hook at the end. But hooks are
|
||||
used in other contexts too. For example, the hook @code{suspend-hook}
|
||||
runs just before Emacs suspends itself (@pxref{Suspending Emacs}).
|
||||
|
||||
The recommended way to add a hook function to a normal hook is by
|
||||
calling @code{add-hook} (see below). The hook functions may be any of
|
||||
the valid kinds of functions that @code{funcall} accepts (@pxref{What
|
||||
The recommended way to add a hook function to a hook is by calling
|
||||
@code{add-hook} (@pxref{Setting Hooks}). The hook functions may be any
|
||||
of the valid kinds of functions that @code{funcall} accepts (@pxref{What
|
||||
Is a Function}). Most normal hook variables are initially void;
|
||||
@code{add-hook} knows how to deal with this. You can add hooks either
|
||||
globally or buffer-locally with @code{add-hook}.
|
||||
|
|
@ -178,7 +177,7 @@ calls @code{wrap-function} with arguments @code{fun} and @code{args}.
|
|||
in Lisp Interaction mode:
|
||||
|
||||
@example
|
||||
(add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)
|
||||
(add-hook 'lisp-interaction-mode-hook 'auto-fill-mode)
|
||||
@end example
|
||||
|
||||
@defun add-hook hook function &optional append local
|
||||
|
|
@ -202,13 +201,13 @@ If @var{function} has a non-@code{nil} property
|
|||
changing major modes) won't delete it from the hook variable's local
|
||||
value.
|
||||
|
||||
It is best to design your hook functions so that the order in which
|
||||
they are executed does not matter. Any dependence on the order is
|
||||
asking for trouble. However, the order is predictable: normally,
|
||||
@var{function} goes at the front of the hook list, so it will be
|
||||
executed first (barring another @code{add-hook} call). If the
|
||||
optional argument @var{append} is non-@code{nil}, the new hook
|
||||
function goes at the end of the hook list and will be executed last.
|
||||
For a normal hook, hook functions should be designed so that the order
|
||||
in which they are executed does not matter. Any dependence on the order
|
||||
is asking for trouble. However, the order is predictable: normally,
|
||||
@var{function} goes at the front of the hook list, so it is executed
|
||||
first (barring another @code{add-hook} call). If the optional argument
|
||||
@var{append} is non-@code{nil}, the new hook function goes at the end of
|
||||
the hook list and is executed last.
|
||||
|
||||
@code{add-hook} can handle the cases where @var{hook} is void or its
|
||||
value is a single function; it sets or changes the value to a list of
|
||||
|
|
@ -302,8 +301,8 @@ initialization, function and variable names, and hooks.
|
|||
|
||||
If you use the @code{define-derived-mode} macro, it will take care of
|
||||
many of these conventions automatically. @xref{Derived Modes}. Note
|
||||
also that fundamental mode is an exception to many of these conventions,
|
||||
because its definition is to present the global state of Emacs.
|
||||
also that Fundamental mode is an exception to many of these conventions,
|
||||
because it represents the default state of Emacs.
|
||||
|
||||
The following list of conventions is only partial. Each major mode
|
||||
should aim for consistency in general with other Emacs major modes, as
|
||||
|
|
@ -460,8 +459,9 @@ The mode can specify a local value for
|
|||
this mode.
|
||||
|
||||
@item
|
||||
The mode can specify how to complete various keywords by adding
|
||||
to the special hook @code{completion-at-point-functions}.
|
||||
The mode can specify how to complete various keywords by adding one or
|
||||
more buffer-local entries to the special hook
|
||||
@code{completion-at-point-functions}. @xref{Completion in Buffers}.
|
||||
|
||||
@item
|
||||
Use @code{defvar} or @code{defcustom} to set mode-related variables, so
|
||||
|
|
@ -555,16 +555,15 @@ In the comments that document the file, you should provide a sample
|
|||
@cindex mode loading
|
||||
The top-level forms in the file defining the mode should be written so
|
||||
that they may be evaluated more than once without adverse consequences.
|
||||
Even if you never load the file more than once, someone else will.
|
||||
@end itemize
|
||||
|
||||
@node Auto Major Mode
|
||||
@subsection How Emacs Chooses a Major Mode
|
||||
@cindex major mode, automatic selection
|
||||
|
||||
Based on information in the file name or in the file itself, Emacs
|
||||
automatically selects a major mode for the new buffer when a file is
|
||||
visited. It also processes local variables specified in the file text.
|
||||
When Emacs visits a file, it automatically selects a major mode for
|
||||
the buffer based on information in the file name or in the file itself.
|
||||
It also processes local variables specified in the file text.
|
||||
|
||||
@deffn Command normal-mode &optional find-file
|
||||
This function establishes the proper major mode and buffer-local variable
|
||||
|
|
|
|||
|
|
@ -675,6 +675,7 @@ Completion
|
|||
shell commands.
|
||||
* Completion Styles:: Specifying rules for performing completion.
|
||||
* Programmed Completion:: Writing your own completion-function.
|
||||
* Completion in Buffers:: Completing text in ordinary buffers.
|
||||
|
||||
Command Loop
|
||||
|
||||
|
|
|
|||
|
|
@ -674,6 +674,7 @@ Completion
|
|||
shell commands.
|
||||
* Completion Styles:: Specifying rules for performing completion.
|
||||
* Programmed Completion:: Writing your own completion-function.
|
||||
* Completion in Buffers:: Completing text in ordinary buffers.
|
||||
|
||||
Command Loop
|
||||
|
||||
|
|
|
|||
|
|
@ -5,6 +5,8 @@
|
|||
|
||||
2012-02-15 Chong Yidong <cyd@gnu.org>
|
||||
|
||||
* minibuffer.el (completion-at-point-functions): Doc fix.
|
||||
|
||||
* custom.el (defcustom): Doc fix; note use of defvar.
|
||||
|
||||
2012-02-15 Glenn Morris <rgm@gnu.org>
|
||||
|
|
|
|||
|
|
@ -1550,16 +1550,16 @@ the mode if ARG is omitted or nil."
|
|||
Each function on this hook is called in turns without any argument and should
|
||||
return either nil to mean that it is not applicable at point,
|
||||
or a function of no argument to perform completion (discouraged),
|
||||
or a list of the form (START END COLLECTION &rest PROPS) where
|
||||
or a list of the form (START END COLLECTION . PROPS) where
|
||||
START and END delimit the entity to complete and should include point,
|
||||
COLLECTION is the completion table to use to complete it, and
|
||||
PROPS is a property list for additional information.
|
||||
Currently supported properties are all the properties that can appear in
|
||||
`completion-extra-properties' plus:
|
||||
`:predicate' a predicate that completion candidates need to satisfy.
|
||||
`:exclusive' If `no', means that if the completion data does not match the
|
||||
text at point failure, then instead of reporting a completion failure,
|
||||
the completion should try the next completion function.")
|
||||
`:exclusive' If `no', means that if the completion table fails to
|
||||
match the text at point, then instead of reporting a completion
|
||||
failure, the completion should try the next completion function.")
|
||||
|
||||
(defvar completion--capf-misbehave-funs nil
|
||||
"List of functions found on `completion-at-point-functions' that misbehave.
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue