From 637821cd30f9bd3b523d032e2dda22ffee853d51 Mon Sep 17 00:00:00 2001 From: Stefan Monnier Date: Sun, 30 May 2010 17:18:35 -0400 Subject: [PATCH] * doc/lispref/minibuf.texi (Basic Completion): Document completion-boundaries. (Programmed Completion): Document the new fourth method for boundaries. * .bzrignore: Ignore new files from trunk, which appear if you use colocated branches (i.e. "bzr switch"). --- ChangeLog | 5 +++++ doc/lispref/ChangeLog | 5 +++++ doc/lispref/minibuf.texi | 44 +++++++++++++++++++++++++++++++++------- 3 files changed, 47 insertions(+), 7 deletions(-) diff --git a/ChangeLog b/ChangeLog index b218314d2a..5317cbeb7e 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +2010-05-30 Stefan Monnier + + * .bzrignore: Ignore new files from trunk, which appear if you use + colocated branches (i.e. "bzr switch"). + 2010-05-10 Miles Bader * configure.in: Get rid of "unix" pre-defined macro when diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 93e958c074..f07fb257a3 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,8 @@ +2010-05-30 Stefan Monnier + + * minibuf.texi (Basic Completion): Document completion-boundaries. + (Programmed Completion): Document the new fourth method for boundaries. + 2010-05-07 Chong Yidong * Version 23.2 released. diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi index 66b4cb096c..841c882318 100644 --- a/doc/lispref/minibuf.texi +++ b/doc/lispref/minibuf.texi @@ -812,6 +812,24 @@ unpredictable. If @var{collection} is a function, it is called with three arguments, the values @var{string}, @var{predicate} and @code{lambda}; whatever it returns, @code{test-completion} returns in turn. + +@defun completion-boundaries string collection predicate suffix +This function returns the boundaries of the field on which @var{collection} +will operate, assuming that @var{string} holds the text before point +and @var{suffix} holds the text after point. + +Normally completion operates on the whole string, so for all normal +collections, this will always return @code{(0 . (length +@var{suffix}))}. But more complex completion such as completion on +files is done one field at a time. For example, completion of +@code{"/usr/sh"} will include @code{"/usr/share/"} but not +@code{"/usr/share/doc"} even if @code{"/usr/share/doc"} exists. +Also @code{all-completions} on @code{"/usr/sh"} will not include +@code{"/usr/share/"} but only @code{"share/"}. So if @var{string} is +@code{"/usr/sh"} and @var{suffix} is @code{"e/doc"}, +@code{completion-boundaries} will return @code{(5 . 1)} which tells us +that the @var{collection} will only return completion information that +pertains to the area after @code{"/usr/"} and before @code{"/doc"}. @end defun If you store a completion alist in a variable, you should mark the @@ -1618,13 +1636,14 @@ containing all the intended possible completions. In such a case, you can supply your own function to compute the completion of a given string. This is called @dfn{programmed completion}. Emacs uses programmed completion when completing file names (@pxref{File Name -Completion}). +Completion}), among many other cases. - To use this feature, pass a symbol with a function definition as the -@var{collection} argument to @code{completing-read}. The function + To use this feature, pass a function as the @var{collection} +argument to @code{completing-read}. The function @code{completing-read} arranges to pass your completion function along -to @code{try-completion} and @code{all-completions}, which will then let -your function do all the work. +to @code{try-completion}, @code{all-completions}, and other basic +completion functions, which will then let your function do all +the work. The completion function should accept three arguments: @@ -1638,10 +1657,14 @@ none. Your function should call the predicate for each possible match, and ignore the possible match if the predicate returns @code{nil}. @item -A flag specifying the type of operation. +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 - There are three flag values for three operations: + There are currently four methods, i.e. four flag values, one for + each of the four different basic operations: @itemize @bullet @item @@ -1663,6 +1686,13 @@ string. @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 +@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 +in the string to complete, and END is the position of the end boundary +in SUFFIX. @end itemize It would be consistent and clean for completion functions to allow -- 2.20.1