526 |
@node Basic Completion |
@node Basic Completion |
527 |
@subsection Basic Completion Functions |
@subsection Basic Completion Functions |
528 |
|
|
529 |
The two functions @code{try-completion} and @code{all-completions} |
The functions @code{try-completion}, @code{all-completions} and |
530 |
have nothing in themselves to do with minibuffers. We describe them in |
@code{test-completion} have nothing in themselves to do with |
531 |
this chapter so as to keep them near the higher-level completion |
minibuffers. We describe them in this chapter so as to keep them near |
532 |
features that do use the minibuffer. |
the higher-level completion features that do use the minibuffer. |
533 |
|
|
534 |
@defun try-completion string collection &optional predicate |
@defun try-completion string collection &optional predicate |
535 |
This function returns the longest common substring of all possible |
This function returns the longest common substring of all possible |
536 |
completions of @var{string} in @var{collection}. The value of |
completions of @var{string} in @var{collection}. The value of |
537 |
@var{collection} must be an alist, an obarray, or a function that |
@var{collection} must be a list of strings, an alist, an obarray, or a |
538 |
implements a virtual set of strings (see below). |
function that implements a virtual set of strings (see below). |
539 |
|
|
540 |
Completion compares @var{string} against each of the permissible |
Completion compares @var{string} against each of the permissible |
541 |
completions specified by @var{collection}; if the beginning of the |
completions specified by @var{collection}; if the beginning of the |
559 |
empty and then add symbols to it one by one using @code{intern}. |
empty and then add symbols to it one by one using @code{intern}. |
560 |
Also, you cannot intern a given symbol in more than one obarray. |
Also, you cannot intern a given symbol in more than one obarray. |
561 |
|
|
|
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. |
|
|
|
|
562 |
You can also use a symbol that is a function as @var{collection}. Then |
You can also use a symbol that is a function as @var{collection}. Then |
563 |
the function is solely responsible for performing completion; |
the function is solely responsible for performing completion; |
564 |
@code{try-completion} returns whatever this function returns. The |
@code{try-completion} returns whatever this function returns. The |
567 |
function can be used in @code{all-completions} and do the appropriate |
function can be used in @code{all-completions} and do the appropriate |
568 |
thing in either case.) @xref{Programmed Completion}. |
thing in either case.) @xref{Programmed Completion}. |
569 |
|
|
570 |
|
If the argument @var{predicate} is non-@code{nil}, then it must be a |
571 |
|
function of one argument. It is used to test each possible match, and |
572 |
|
the match is accepted only if @var{predicate} returns non-@code{nil}. |
573 |
|
The argument given to @var{predicate} is either a string from the |
574 |
|
list, a cons cell from the alist (the @sc{car} of which is a string) |
575 |
|
or a symbol (@emph{not} a symbol name) from the obarray. |
576 |
|
|
577 |
In the first of the following examples, the string @samp{foo} is |
In the first of the following examples, the string @samp{foo} is |
578 |
matched by three of the alist @sc{car}s. All of the matches begin with |
matched by three of the alist @sc{car}s. All of the matches begin with |
579 |
the characters @samp{fooba}, so that is the result. In the second |
the characters @samp{fooba}, so that is the result. In the second |
657 |
@end smallexample |
@end smallexample |
658 |
@end defun |
@end defun |
659 |
|
|
660 |
|
@defun test-completion string collection &optional predicate |
661 |
|
This function returns non-@code{nil} if @var{string} is a valid |
662 |
|
completion possibility specified by @var{collection} and |
663 |
|
@var{predicate}. The other arguments are the same as in |
664 |
|
@code{try-completion}. For instance, if @var{collection} is a list, |
665 |
|
this is true if @var{string} appears in the list and @var{predicate} |
666 |
|
is satisfied. |
667 |
|
|
668 |
|
If @var{collection} is a function, it is called with three arguments, |
669 |
|
the values @var{string}, @var{predicate} and @code{lambda}; whatever |
670 |
|
it returns, @code{test-completion} returns in turn. |
671 |
|
@end defun |
672 |
|
|
673 |
@defvar completion-ignore-case |
@defvar completion-ignore-case |
674 |
If the value of this variable is |
If the value of this variable is non-@code{nil}, Emacs does not |
675 |
non-@code{nil}, Emacs does not consider case significant in completion. |
consider case significant in completion. |
676 |
@end defvar |
@end defvar |
677 |
|
|
678 |
@defmac lazy-completion-table var fun &rest args |
@defmac lazy-completion-table var fun &rest args |
679 |
This macro provides a way to initialize the variable @var{var} as a |
This macro provides a way to initialize the variable @var{var} as a |
680 |
completion table in a lazy way, not computing its actual contents |
collection for completion in a lazy way, not computing its actual |
681 |
until they are first needed. You use this macro to produce a value |
contents until they are first needed. You use this macro to produce a |
682 |
that you store in @var{var}. The actual computation of the proper |
value that you store in @var{var}. The actual computation of the |
683 |
value is done the first time you do completion using @var{var}. It is |
proper value is done the first time you do completion using @var{var}. |
684 |
done by calling @var{fun} with the arguments @var{args}. The value |
It is done by calling @var{fun} with the arguments @var{args}. The |
685 |
@var{fun} returns becomes the permanent value of @var{var}. |
value @var{fun} returns becomes the permanent value of @var{var}. |
686 |
|
|
687 |
|
Here are two examples of use: |
688 |
|
|
689 |
@example |
@example |
690 |
(defvar foo (lazy-completion-table foo make-my-alist 'global)) |
(defvar foo (lazy-completion-table foo make-my-alist 'global)) |
691 |
|
|
692 |
(make-local-variable 'bar) |
(make-local-variable 'bar) |
693 |
(setq bar (lazy-completion-table foo make-my-alist 'local) |
(setq bar (lazy-completion-table foo make-my-alist 'local) |
694 |
@end example |
@end example |
1235 |
string. |
string. |
1236 |
|
|
1237 |
@item |
@item |
1238 |
@code{lambda} specifies a test for an exact match. The completion |
@code{lambda} specifies @code{test-completion}. The completion |
1239 |
function should return @code{t} if the specified string is an exact |
function should return @code{t} if the specified string is an exact |
1240 |
match for some possibility; @code{nil} otherwise. |
match for some possibility; @code{nil} otherwise. |
1241 |
@end itemize |
@end itemize |
1243 |
It would be consistent and clean for completion functions to allow |
It would be consistent and clean for completion functions to allow |
1244 |
lambda expressions (lists that are functions) as well as function |
lambda expressions (lists that are functions) as well as function |
1245 |
symbols as @var{collection}, but this is impossible. Lists as |
symbols as @var{collection}, but this is impossible. Lists as |
1246 |
completion tables are already assigned another meaning---as alists. It |
completion tables already have other meanings, and it would be |
1247 |
would be unreliable to fail to handle an alist normally because it is |
unreliable to treat one differently just because it is also a possible |
1248 |
also a possible function. So you must arrange for any function you wish |
function. So you must arrange for any function you wish to use for |
1249 |
to use for completion to be encapsulated in a symbol. |
completion to be encapsulated in a symbol. |
1250 |
|
|
1251 |
Emacs uses programmed completion when completing file names. |
Emacs uses programmed completion when completing file names. |
1252 |
@xref{File Name Completion}. |
@xref{File Name Completion}. |
1611 |
locally inside the minibuffer (@pxref{Help Functions}). |
locally inside the minibuffer (@pxref{Help Functions}). |
1612 |
@end defvar |
@end defvar |
1613 |
|
|
1614 |
|
@defun minibufferp &optional buffer |
1615 |
|
This function returns non-@code{nil} if @var{buffer} is a minibuffer. |
1616 |
|
If @var{buffer} is omitted, it tests the current buffer. |
1617 |
|
@end defun |
1618 |
|
|
1619 |
@defun active-minibuffer-window |
@defun active-minibuffer-window |
1620 |
This function returns the currently active minibuffer window, or |
This function returns the currently active minibuffer window, or |
1621 |
@code{nil} if none is currently active. |
@code{nil} if none is currently active. |