Commit 60236b0d authored by Chong Yidong's avatar Chong Yidong
Browse files

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.
parent 888ab661
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}).
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
@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 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.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment