changeset 51989:13ba58726a52

(Basic Completion): Describe test-completion. Collections can be lists of strings. Clean up lazy-completion-table. (Programmed Completion): Mention test-completion. Clarify why lambda expressions are not accepted. (Minibuffer Misc): Describe minibufferp.

--- a/lispref/minibuf.texi	Mon Jul 21 21:36:55 2003 +0000
+++ b/lispref/minibuf.texi	Tue Jul 22 15:13:58 2003 +0000
@@ -526,16 +526,16 @@
 @node Basic Completion
 @subsection Basic Completion Functions
 
-  The two functions @code{try-completion} and @code{all-completions}
-have nothing in themselves to do with minibuffers.  We describe them in
-this chapter so as to keep them near the higher-level completion
-features that do use the minibuffer.
+  The functions @code{try-completion}, @code{all-completions} and
+@code{test-completion} have nothing in themselves to do with
+minibuffers.  We describe them in this chapter so as to keep them near
+the 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 an alist, an obarray, or a function that
-implements a virtual set of strings (see below).
+@var{collection} must be a list of strings, an alist, an obarray, or a
+function that implements a virtual set of strings (see below).
 
 Completion compares @var{string} against each of the permissible
 completions specified by @var{collection}; if the beginning of the
@@ -559,13 +559,6 @@
 empty and then add symbols to it one by one using @code{intern}.
 Also, you cannot intern a given symbol in more than one obarray.
 
-If the argument @var{predicate} is non-@code{nil}, then it must be a
-function of one argument.  It is used to test each possible match, and
-the match is accepted only if @var{predicate} returns non-@code{nil}.
-The argument given to @var{predicate} is either a cons cell from the alist
-(the @sc{car} of which is a string) or else it is a symbol (@emph{not} a
-symbol name) from the obarray.
-
 You can also use a symbol that is a function as @var{collection}.  Then
 the function is solely responsible for performing completion;
 @code{try-completion} returns whatever this function returns.  The
@@ -574,6 +567,13 @@
 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.  It is used to test each possible match, and
+the match is accepted only if @var{predicate} returns non-@code{nil}.
+The argument given to @var{predicate} is either a string from the
+list, a cons cell from the alist (the @sc{car} of which is a string)
+or a symbol (@emph{not} a symbol name) from the obarray.
+
 In the first of the following examples, the string @samp{foo} is
 matched by three of the alist @sc{car}s.  All of the matches begin with
 the characters @samp{fooba}, so that is the result.  In the second
@@ -657,22 +657,38 @@
 @end smallexample
 @end defun
 
+@defun test-completion string collection &optional predicate
+This function returns non-@code{nil} if @var{string} is a valid
+completion possibility specified by @var{collection} and
+@var{predicate}.  The other arguments are the same as in
+@code{try-completion}.  For instance, if @var{collection} is a list,
+this is true if @var{string} appears in the list and @var{predicate}
+is satisfied.
+
+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.
+@end defun
+
 @defvar completion-ignore-case
-If the value of this variable is
-non-@code{nil}, Emacs does not consider case significant in completion.
+If the value of this variable is non-@code{nil}, Emacs does not
+consider case significant in completion.
 @end defvar
 
 @defmac lazy-completion-table var fun &rest args
 This macro provides a way to initialize the variable @var{var} as a
-completion table in a lazy way, not computing its actual contents
-until they are first needed.  You use this macro to produce a value
-that you store in @var{var}.  The actual computation of the proper
-value is done the first time you do completion using @var{var}.  It is
-done by calling @var{fun} with the arguments @var{args}.  The value
-@var{fun} returns becomes the permanent value of @var{var}.
+collection for completion in a lazy way, not computing its actual
+contents until they are first needed.  You use this macro to produce a
+value that you store in @var{var}.  The actual computation of the
+proper value is done the first time you do completion using @var{var}.
+It is done by calling @var{fun} with the arguments @var{args}.  The
+value @var{fun} returns becomes the permanent value of @var{var}.
+
+Here are two examples of use:
 
 @example
 (defvar foo (lazy-completion-table foo make-my-alist 'global))
+
 (make-local-variable 'bar)
 (setq bar (lazy-completion-table foo make-my-alist 'local)
 @end example
@@ -1219,7 +1235,7 @@
 string.
 
 @item
-@code{lambda} specifies a test for an exact match.  The completion
+@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.
 @end itemize
@@ -1227,10 +1243,10 @@
   It would be consistent and clean for completion functions to allow
 lambda expressions (lists that are functions) as well as function
 symbols as @var{collection}, but this is impossible.  Lists as
-completion tables are already assigned another meaning---as alists.  It
-would be unreliable to fail to handle an alist normally because it is
-also a possible function.  So you must arrange for any function you wish
-to use for completion to be encapsulated in a symbol.
+completion tables already have other meanings, and it would be
+unreliable to treat one differently just because it is also a possible
+function.  So you must arrange for any function you wish to use for
+completion to be encapsulated in a symbol.
 
   Emacs uses programmed completion when completing file names.
 @xref{File Name Completion}.
@@ -1595,6 +1611,11 @@
 locally inside the minibuffer (@pxref{Help Functions}).
 @end defvar
 
+@defun minibufferp &optional buffer
+This function returns non-@code{nil} if @var{buffer} is a minibuffer.
+If @var{buffer} is omitted, it tests the current buffer.
+@end defun
+
 @defun active-minibuffer-window
 This function returns the currently active minibuffer window, or
 @code{nil} if none is currently active.