63 |
just a minibuffer, you can change the minibuffer's size by changing the |
just a minibuffer, you can change the minibuffer's size by changing the |
64 |
frame's size. |
frame's size. |
65 |
|
|
66 |
|
Use of the minibuffer reads input events, and that alters the values |
67 |
|
of variables such as @code{this-command} and @code{last-command} |
68 |
|
(@pxref{Command Loop Info}). Your program should bind them around the |
69 |
|
code that uses the minibuffer, if you do not want that to change them. |
70 |
|
|
71 |
If a command uses a minibuffer while there is an active minibuffer, |
If a command uses a minibuffer while there is an active minibuffer, |
72 |
this is called a @dfn{recursive minibuffer}. The first minibuffer is |
this is called a @dfn{recursive minibuffer}. The first minibuffer is |
73 |
named @w{@samp{ *Minibuf-0*}}. Recursive minibuffers are named by |
named @w{@samp{ *Minibuf-0*}}. Recursive minibuffers are named by |
89 |
|
|
90 |
@item |
@item |
91 |
@code{minibuffer-local-ns-map} is similar, except that @key{SPC} exits |
@code{minibuffer-local-ns-map} is similar, except that @key{SPC} exits |
92 |
just like @key{RET}. This is used mainly for Mocklisp compatibility. |
just like @key{RET}. |
93 |
|
|
94 |
@item |
@item |
95 |
@code{minibuffer-local-completion-map} is for permissive completion. |
@code{minibuffer-local-completion-map} is for permissive completion. |
189 |
@code{read-from-minibuffer}. The keymap used is |
@code{read-from-minibuffer}. The keymap used is |
190 |
@code{minibuffer-local-map}. |
@code{minibuffer-local-map}. |
191 |
|
|
192 |
The optional argument @var{history}, if non-nil, specifies a history |
The optional argument @var{history}, if non-@code{nil}, specifies a |
193 |
list and optionally the initial position in the list. The optional |
history list and optionally the initial position in the list. The |
194 |
argument @var{default} specifies a default value to return if the user |
optional argument @var{default} specifies a default value to return if |
195 |
enters null input; it should be a string. The optional argument |
the user enters null input; it should be a string. The optional |
196 |
@var{inherit-input-method} specifies whether to inherit the current |
argument @var{inherit-input-method} specifies whether to inherit the |
197 |
buffer's input method. |
current buffer's input method. |
198 |
|
|
199 |
This function is a simplified interface to the |
This function is a simplified interface to the |
200 |
@code{read-from-minibuffer} function: |
@code{read-from-minibuffer} function: |
525 |
* High-Level Completion:: Convenient special cases of completion |
* High-Level Completion:: Convenient special cases of completion |
526 |
(reading buffer name, file name, etc.) |
(reading buffer name, file name, etc.) |
527 |
* Reading File Names:: Using completion to read file names. |
* Reading File Names:: Using completion to read file names. |
528 |
* Programmed Completion:: Finding the completions for a given file name. |
* Programmed Completion:: Writing your own completion-function. |
529 |
@end menu |
@end menu |
530 |
|
|
531 |
@node Basic Completion |
@node Basic Completion |
532 |
@subsection Basic Completion Functions |
@subsection Basic Completion Functions |
533 |
|
|
534 |
The two functions @code{try-completion} and @code{all-completions} |
The functions @code{try-completion}, @code{all-completions} and |
535 |
have nothing in themselves to do with minibuffers. We describe them in |
@code{test-completion} have nothing in themselves to do with |
536 |
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 |
537 |
features that do use the minibuffer. |
the higher-level completion features that do use the minibuffer. |
538 |
|
|
539 |
@defun try-completion string collection &optional predicate |
@defun try-completion string collection &optional predicate |
540 |
This function returns the longest common substring of all possible |
This function returns the longest common substring of all possible |
541 |
completions of @var{string} in @var{collection}. The value of |
completions of @var{string} in @var{collection}. The value of |
542 |
@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 |
543 |
implements a virtual set of strings (see below). |
function that implements a virtual set of strings (see below). |
544 |
|
|
545 |
Completion compares @var{string} against each of the permissible |
Completion compares @var{string} against each of the permissible |
546 |
completions specified by @var{collection}; if the beginning of the |
completions specified by @var{collection}; if the beginning of the |
564 |
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}. |
565 |
Also, you cannot intern a given symbol in more than one obarray. |
Also, you cannot intern a given symbol in more than one obarray. |
566 |
|
|
|
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. |
|
|
|
|
567 |
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 |
568 |
the function is solely responsible for performing completion; |
the function is solely responsible for performing completion; |
569 |
@code{try-completion} returns whatever this function returns. The |
@code{try-completion} returns whatever this function returns. The |
572 |
function can be used in @code{all-completions} and do the appropriate |
function can be used in @code{all-completions} and do the appropriate |
573 |
thing in either case.) @xref{Programmed Completion}. |
thing in either case.) @xref{Programmed Completion}. |
574 |
|
|
575 |
|
If the argument @var{predicate} is non-@code{nil}, then it must be a |
576 |
|
function of one argument. It is used to test each possible match, and |
577 |
|
the match is accepted only if @var{predicate} returns non-@code{nil}. |
578 |
|
The argument given to @var{predicate} is either a string from the |
579 |
|
list, a cons cell from the alist (the @sc{car} of which is a string) |
580 |
|
or a symbol (@emph{not} a symbol name) from the obarray. |
581 |
|
|
582 |
In the first of the following examples, the string @samp{foo} is |
In the first of the following examples, the string @samp{foo} is |
583 |
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 |
584 |
the characters @samp{fooba}, so that is the result. In the second |
the characters @samp{fooba}, so that is the result. In the second |
662 |
@end smallexample |
@end smallexample |
663 |
@end defun |
@end defun |
664 |
|
|
665 |
|
@defun test-completion string collection &optional predicate |
666 |
|
This function returns non-@code{nil} if @var{string} is a valid |
667 |
|
completion possibility specified by @var{collection} and |
668 |
|
@var{predicate}. The other arguments are the same as in |
669 |
|
@code{try-completion}. For instance, if @var{collection} is a list, |
670 |
|
this is true if @var{string} appears in the list and @var{predicate} |
671 |
|
is satisfied. |
672 |
|
|
673 |
|
If @var{collection} is a function, it is called with three arguments, |
674 |
|
the values @var{string}, @var{predicate} and @code{lambda}; whatever |
675 |
|
it returns, @code{test-completion} returns in turn. |
676 |
|
@end defun |
677 |
|
|
678 |
@defvar completion-ignore-case |
@defvar completion-ignore-case |
679 |
If the value of this variable is |
If the value of this variable is non-@code{nil}, Emacs does not |
680 |
non-@code{nil}, Emacs does not consider case significant in completion. |
consider case significant in completion. |
681 |
@end defvar |
@end defvar |
682 |
|
|
683 |
|
@defmac lazy-completion-table var fun &rest args |
684 |
|
This macro provides a way to initialize the variable @var{var} as a |
685 |
|
collection for completion in a lazy way, not computing its actual |
686 |
|
contents until they are first needed. You use this macro to produce a |
687 |
|
value that you store in @var{var}. The actual computation of the |
688 |
|
proper value is done the first time you do completion using @var{var}. |
689 |
|
It is done by calling @var{fun} with the arguments @var{args}. The |
690 |
|
value @var{fun} returns becomes the permanent value of @var{var}. |
691 |
|
|
692 |
|
Here are two examples of use: |
693 |
|
|
694 |
|
@example |
695 |
|
(defvar foo (lazy-completion-table foo make-my-alist 'global)) |
696 |
|
|
697 |
|
(make-local-variable 'bar) |
698 |
|
(setq bar (lazy-completion-table foo make-my-alist 'local) |
699 |
|
@end example |
700 |
|
@end defmac |
701 |
|
|
702 |
@node Minibuffer Completion |
@node Minibuffer Completion |
703 |
@subsection Completion and the Minibuffer |
@subsection Completion and the Minibuffer |
704 |
|
|
1088 |
file name. It provides special features including automatic insertion |
file name. It provides special features including automatic insertion |
1089 |
of the default directory. |
of the default directory. |
1090 |
|
|
1091 |
@defun read-file-name prompt &optional directory default existing initial |
@defun read-file-name prompt &optional directory default existing initial predicate |
1092 |
This function reads a file name in the minibuffer, prompting with |
This function reads a file name in the minibuffer, prompting with |
1093 |
@var{prompt} and providing completion. If @var{default} is |
@var{prompt} and providing completion. If @var{default} is |
1094 |
non-@code{nil}, then the function returns @var{default} if the user just |
non-@code{nil}, then the function returns @var{default} if the user just |
1110 |
@code{default-directory}. |
@code{default-directory}. |
1111 |
|
|
1112 |
@c Emacs 19 feature |
@c Emacs 19 feature |
1113 |
If you specify @var{initial}, that is an initial file name to insert in |
If you specify @var{initial}, that is an initial file name to insert |
1114 |
the buffer (after @var{directory}, if that is inserted). In this |
in the buffer (after @var{directory}, if that is inserted). In this |
1115 |
case, point goes at the beginning of @var{initial}. The default for |
case, point goes at the beginning of @var{initial}. The default for |
1116 |
@var{initial} is @code{nil}---don't insert any file name. To see what |
@var{initial} is @code{nil}---don't insert any file name. To see what |
1117 |
@var{initial} does, try the command @kbd{C-x C-v}. @strong{Note:} we |
@var{initial} does, try the command @kbd{C-x C-v}. @strong{Please |
1118 |
recommend using @var{default} rather than @var{initial} in most cases. |
note:} we recommend using @var{default} rather than @var{initial} in |
1119 |
|
most cases. |
1120 |
|
|
1121 |
|
If @var{predicate} is non-@code{nil}, it specifies a function of one |
1122 |
|
argument that decides which file names are acceptable completion |
1123 |
|
possibilities. A file name is an acceptable value if @var{predicate} |
1124 |
|
returns non-@code{nil} for it. |
1125 |
|
|
1126 |
Here is an example: |
Here is an example: |
1127 |
|
|
1157 |
as the string @code{"/gp/gnu/elisp/manual.texi"}. |
as the string @code{"/gp/gnu/elisp/manual.texi"}. |
1158 |
@end defun |
@end defun |
1159 |
|
|
1160 |
|
@defun read-directory-name prompt &optional directory default existing initial |
1161 |
|
This function is like @code{read-file-name} but allows only directory |
1162 |
|
names as completion possibilities. |
1163 |
|
@end defun |
1164 |
|
|
1165 |
@defopt insert-default-directory |
@defopt insert-default-directory |
1166 |
This variable is used by @code{read-file-name}. Its value controls |
This variable is used by @code{read-file-name}. Its value controls |
1167 |
whether @code{read-file-name} starts by placing the name of the default |
whether @code{read-file-name} starts by placing the name of the default |
1251 |
string. |
string. |
1252 |
|
|
1253 |
@item |
@item |
1254 |
@code{lambda} specifies a test for an exact match. The completion |
@code{lambda} specifies @code{test-completion}. The completion |
1255 |
function should return @code{t} if the specified string is an exact |
function should return @code{t} if the specified string is an exact |
1256 |
match for some possibility; @code{nil} otherwise. |
match for some possibility; @code{nil} otherwise. |
1257 |
@end itemize |
@end itemize |
1259 |
It would be consistent and clean for completion functions to allow |
It would be consistent and clean for completion functions to allow |
1260 |
lambda expressions (lists that are functions) as well as function |
lambda expressions (lists that are functions) as well as function |
1261 |
symbols as @var{collection}, but this is impossible. Lists as |
symbols as @var{collection}, but this is impossible. Lists as |
1262 |
completion tables are already assigned another meaning---as alists. It |
completion tables already have other meanings, and it would be |
1263 |
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 |
1264 |
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 |
1265 |
to use for completion to be encapsulated in a symbol. |
completion to be encapsulated in a symbol. |
1266 |
|
|
1267 |
Emacs uses programmed completion when completing file names. |
Emacs uses programmed completion when completing file names. |
1268 |
@xref{File Name Completion}. |
@xref{File Name Completion}. |
1269 |
|
|
1270 |
|
@defmac dynamic-completion-table function |
1271 |
|
This macro is a convenient way to write a function that can act as |
1272 |
|
programmed completion function. The argument @var{function} should be |
1273 |
|
a function that takes one argument, a string, and returns an alist of |
1274 |
|
possible completions of it. You can think of |
1275 |
|
@code{dynamic-completion-table} as a transducer between that interface |
1276 |
|
and the interface for programmed completion functions. |
1277 |
|
@end defmac |
1278 |
|
|
1279 |
@node Yes-or-No Queries |
@node Yes-or-No Queries |
1280 |
@section Yes-or-No Queries |
@section Yes-or-No Queries |
1281 |
@cindex asking the user questions |
@cindex asking the user questions |
1627 |
locally inside the minibuffer (@pxref{Help Functions}). |
locally inside the minibuffer (@pxref{Help Functions}). |
1628 |
@end defvar |
@end defvar |
1629 |
|
|
1630 |
|
@defun minibufferp &optional buffer |
1631 |
|
This function returns non-@code{nil} if @var{buffer} is a minibuffer. |
1632 |
|
If @var{buffer} is omitted, it tests the current buffer. |
1633 |
|
@end defun |
1634 |
|
|
1635 |
@defun active-minibuffer-window |
@defun active-minibuffer-window |
1636 |
This function returns the currently active minibuffer window, or |
This function returns the currently active minibuffer window, or |
1637 |
@code{nil} if none is currently active. |
@code{nil} if none is currently active. |
1666 |
minibuffer, it scrolls this window. |
minibuffer, it scrolls this window. |
1667 |
@end defvar |
@end defvar |
1668 |
|
|
1669 |
|
@defun minibuffer-selected-window |
1670 |
|
This function returns the window which was selected when the |
1671 |
|
minibuffer was entered. If selected window is not a minibuffer |
1672 |
|
window, it returns @code{nil}. |
1673 |
|
@end defun |
1674 |
|
|
1675 |
Finally, some functions and variables deal with recursive minibuffers |
Finally, some functions and variables deal with recursive minibuffers |
1676 |
(@pxref{Recursive Editing}): |
(@pxref{Recursive Editing}): |
1677 |
|
|
1699 |
arguments even if it is invoked from the minibuffer. The minibuffer |
arguments even if it is invoked from the minibuffer. The minibuffer |
1700 |
command @code{next-matching-history-element} (normally @kbd{M-s} in the |
command @code{next-matching-history-element} (normally @kbd{M-s} in the |
1701 |
minibuffer) uses this feature. |
minibuffer) uses this feature. |
1702 |
|
|
1703 |
|
@defun minibuffer-message string &optional timeout |
1704 |
|
This function displays @var{string} temporarily at the end of the |
1705 |
|
minibuffer text, for @var{timeout} seconds. (The default is 2 |
1706 |
|
seconds.) |
1707 |
|
@end defun |
1708 |
|
|
1709 |
|
@ignore |
1710 |
|
arch-tag: bba7f945-9078-477f-a2ce-18818a6e1218 |
1711 |
|
@end ignore |