Mercurial > emacs
annotate lispref/minibuf.texi @ 20279:69a6030e443a
(kill-region): Detect read-only text
by getting an error trying to delete it.
Handle the cases where we can, and can't, get the killed text
from the undo list with much the same code.
author | Karl Heuer <kwzh@gnu.org> |
---|---|
date | Wed, 19 Nov 1997 21:36:56 +0000 |
parents | 981e116b4ac6 |
children | 66d807bdc5b4 |
rev | line source |
---|---|
6555 | 1 @c -*-texinfo-*- |
2 @c This is part of the GNU Emacs Lisp Reference Manual. | |
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. | |
4 @c See the file elisp.texi for copying conditions. | |
5 @setfilename ../info/minibuf | |
7337
cd57cd335fff
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7221
diff
changeset
|
6 @node Minibuffers, Command Loop, Read and Print, Top |
6555 | 7 @chapter Minibuffers |
8 @cindex arguments, reading | |
9 @cindex complex arguments | |
10 @cindex minibuffer | |
11 | |
12 A @dfn{minibuffer} is a special buffer that Emacs commands use to read | |
13 arguments more complicated than the single numeric prefix argument. | |
14 These arguments include file names, buffer names, and command names (as | |
15 in @kbd{M-x}). The minibuffer is displayed on the bottom line of the | |
16 screen, in the same place as the echo area, but only while it is in | |
17 use for reading an argument. | |
18 | |
19 @menu | |
20 * Intro to Minibuffers:: Basic information about minibuffers. | |
21 * Text from Minibuffer:: How to read a straight text string. | |
22 * Object from Minibuffer:: How to read a Lisp object or expression. | |
23 * Minibuffer History:: Recording previous minibuffer inputs | |
24 so the user can reuse them. | |
25 * Completion:: How to invoke and customize completion. | |
26 * Yes-or-No Queries:: Asking a question with a simple answer. | |
27 * Multiple Queries:: Asking a series of similar questions. | |
28 * Minibuffer Misc:: Various customization hooks and variables. | |
29 @end menu | |
30 | |
31 @node Intro to Minibuffers | |
32 @section Introduction to Minibuffers | |
33 | |
34 In most ways, a minibuffer is a normal Emacs buffer. Most operations | |
35 @emph{within} a buffer, such as editing commands, work normally in a | |
36 minibuffer. However, many operations for managing buffers do not apply | |
37 to minibuffers. The name of a minibuffer always has the form @w{@samp{ | |
38 *Minibuf-@var{number}}}, and it cannot be changed. Minibuffers are | |
39 displayed only in special windows used only for minibuffers; these | |
40 windows always appear at the bottom of a frame. (Sometime frames have | |
41 no minibuffer window, and sometimes a special kind of frame contains | |
42 nothing but a minibuffer window; see @ref{Minibuffers and Frames}.) | |
43 | |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
44 The minibuffer's window is normally a single line. You can resize it |
6555 | 45 temporarily with the window sizing commands; it reverts to its normal |
46 size when the minibuffer is exited. You can resize it permanently by | |
47 using the window sizing commands in the frame's other window, when the | |
48 minibuffer is not active. If the frame contains just a minibuffer, you | |
49 can change the minibuffer's size by changing the frame's size. | |
50 | |
51 If a command uses a minibuffer while there is an active minibuffer, | |
52 this is called a @dfn{recursive minibuffer}. The first minibuffer is | |
53 named @w{@samp{ *Minibuf-0*}}. Recursive minibuffers are named by | |
54 incrementing the number at the end of the name. (The names begin with a | |
55 space so that they won't show up in normal buffer lists.) Of several | |
56 recursive minibuffers, the innermost (or most recently entered) is the | |
57 active minibuffer. We usually call this ``the'' minibuffer. You can | |
58 permit or forbid recursive minibuffers by setting the variable | |
59 @code{enable-recursive-minibuffers} or by putting properties of that | |
60 name on command symbols (@pxref{Minibuffer Misc}). | |
61 | |
62 Like other buffers, a minibuffer may use any of several local keymaps | |
63 (@pxref{Keymaps}); these contain various exit commands and in some cases | |
12098 | 64 completion commands (@pxref{Completion}). |
6555 | 65 |
66 @itemize @bullet | |
67 @item | |
68 @code{minibuffer-local-map} is for ordinary input (no completion). | |
69 | |
70 @item | |
71 @code{minibuffer-local-ns-map} is similar, except that @key{SPC} exits | |
72 just like @key{RET}. This is used mainly for Mocklisp compatibility. | |
73 | |
74 @item | |
75 @code{minibuffer-local-completion-map} is for permissive completion. | |
76 | |
77 @item | |
78 @code{minibuffer-local-must-match-map} is for strict completion and | |
79 for cautious completion. | |
80 @end itemize | |
81 | |
82 @node Text from Minibuffer | |
83 @section Reading Text Strings with the Minibuffer | |
84 | |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
85 Most often, the minibuffer is used to read text as a string. It can |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
86 also be used to read a Lisp object in textual form. The most basic |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
87 primitive for minibuffer input is @code{read-from-minibuffer}; it can do |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
88 either one. |
6555 | 89 |
12098 | 90 In most cases, you should not call minibuffer input functions in the |
91 middle of a Lisp function. Instead, do all minibuffer input as part of | |
92 reading the arguments for a command, in the @code{interactive} spec. | |
93 @xref{Defining Commands}. | |
94 | |
6555 | 95 @defun read-from-minibuffer prompt-string &optional initial-contents keymap read hist |
96 This function is the most general way to get input through the | |
97 minibuffer. By default, it accepts arbitrary text and returns it as a | |
98 string; however, if @var{read} is non-@code{nil}, then it uses | |
99 @code{read} to convert the text into a Lisp object (@pxref{Input | |
100 Functions}). | |
101 | |
102 The first thing this function does is to activate a minibuffer and | |
103 display it with @var{prompt-string} as the prompt. This value must be a | |
104 string. | |
105 | |
106 Then, if @var{initial-contents} is a string, @code{read-from-minibuffer} | |
107 inserts it into the minibuffer, leaving point at the end. The | |
108 minibuffer appears with this text as its contents. | |
109 | |
110 @c Emacs 19 feature | |
111 The value of @var{initial-contents} may also be a cons cell of the form | |
112 @code{(@var{string} . @var{position})}. This means to insert | |
113 @var{string} in the minibuffer but put point @var{position} characters | |
114 from the beginning, rather than at the end. | |
115 | |
116 If @var{keymap} is non-@code{nil}, that keymap is the local keymap to | |
117 use in the minibuffer. If @var{keymap} is omitted or @code{nil}, the | |
118 value of @code{minibuffer-local-map} is used as the keymap. Specifying | |
119 a keymap is the most important way to customize the minibuffer for | |
120 various applications such as completion. | |
121 | |
122 The argument @var{hist} specifies which history list variable to use | |
123 for saving the input and for history commands used in the minibuffer. | |
124 It defaults to @code{minibuffer-history}. @xref{Minibuffer History}. | |
125 | |
126 When the user types a command to exit the minibuffer, | |
127 @code{read-from-minibuffer} uses the text in the minibuffer to produce | |
128 its return value. Normally it simply makes a string containing that | |
129 text. However, if @var{read} is non-@code{nil}, | |
130 @code{read-from-minibuffer} reads the text and returns the resulting | |
131 Lisp object, unevaluated. (@xref{Input Functions}, for information | |
132 about reading.) | |
133 @end defun | |
134 | |
135 @defun read-string prompt &optional initial | |
136 This function reads a string from the minibuffer and returns it. The | |
137 arguments @var{prompt} and @var{initial} are used as in | |
138 @code{read-from-minibuffer}. The keymap used is | |
139 @code{minibuffer-local-map}. | |
140 | |
141 This is a simplified interface to the | |
142 @code{read-from-minibuffer} function: | |
143 | |
144 @smallexample | |
145 @group | |
146 (read-string @var{prompt} @var{initial}) | |
147 @equiv{} | |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
148 (read-from-minibuffer @var{prompt} @var{initial} nil nil nil) |
6555 | 149 @end group |
150 @end smallexample | |
151 @end defun | |
152 | |
153 @defvar minibuffer-local-map | |
154 This is the default local keymap for reading from the minibuffer. By | |
155 default, it makes the following bindings: | |
156 | |
157 @table @asis | |
158 @item @key{LFD} | |
159 @code{exit-minibuffer} | |
160 | |
161 @item @key{RET} | |
162 @code{exit-minibuffer} | |
163 | |
164 @item @kbd{C-g} | |
165 @code{abort-recursive-edit} | |
166 | |
167 @item @kbd{M-n} | |
168 @code{next-history-element} | |
169 | |
170 @item @kbd{M-p} | |
171 @code{previous-history-element} | |
172 | |
173 @item @kbd{M-r} | |
174 @code{next-matching-history-element} | |
175 | |
176 @item @kbd{M-s} | |
177 @code{previous-matching-history-element} | |
178 @end table | |
179 @end defvar | |
180 | |
181 @c In version 18, initial is required | |
182 @c Emacs 19 feature | |
183 @defun read-no-blanks-input prompt &optional initial | |
184 This function reads a string from the minibuffer, but does not allow | |
185 whitespace characters as part of the input: instead, those characters | |
186 terminate the input. The arguments @var{prompt} and @var{initial} are | |
187 used as in @code{read-from-minibuffer}. | |
188 | |
189 This is a simplified interface to the @code{read-from-minibuffer} | |
190 function, and passes the value of the @code{minibuffer-local-ns-map} | |
191 keymap as the @var{keymap} argument for that function. Since the keymap | |
192 @code{minibuffer-local-ns-map} does not rebind @kbd{C-q}, it @emph{is} | |
193 possible to put a space into the string, by quoting it. | |
194 | |
195 @smallexample | |
196 @group | |
197 (read-no-blanks-input @var{prompt} @var{initial}) | |
198 @equiv{} | |
199 (read-from-minibuffer @var{prompt} @var{initial} minibuffer-local-ns-map) | |
200 @end group | |
201 @end smallexample | |
202 @end defun | |
203 | |
204 @defvar minibuffer-local-ns-map | |
205 This built-in variable is the keymap used as the minibuffer local keymap | |
206 in the function @code{read-no-blanks-input}. By default, it makes the | |
12098 | 207 following bindings, in addition to those of @code{minibuffer-local-map}: |
6555 | 208 |
209 @table @asis | |
210 @item @key{SPC} | |
211 @cindex @key{SPC} in minibuffer | |
212 @code{exit-minibuffer} | |
213 | |
214 @item @key{TAB} | |
215 @cindex @key{TAB} in minibuffer | |
216 @code{exit-minibuffer} | |
217 | |
218 @item @kbd{?} | |
219 @cindex @kbd{?} in minibuffer | |
220 @code{self-insert-and-exit} | |
221 @end table | |
222 @end defvar | |
223 | |
224 @node Object from Minibuffer | |
225 @section Reading Lisp Objects with the Minibuffer | |
226 | |
227 This section describes functions for reading Lisp objects with the | |
228 minibuffer. | |
229 | |
230 @defun read-minibuffer prompt &optional initial | |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
231 This function reads a Lisp object in the minibuffer and returns it, |
6555 | 232 without evaluating it. The arguments @var{prompt} and @var{initial} are |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
233 used as in @code{read-from-minibuffer}. |
6555 | 234 |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
235 This is a simplified interface to the |
6555 | 236 @code{read-from-minibuffer} function: |
237 | |
238 @smallexample | |
239 @group | |
240 (read-minibuffer @var{prompt} @var{initial}) | |
241 @equiv{} | |
242 (read-from-minibuffer @var{prompt} @var{initial} nil t) | |
243 @end group | |
244 @end smallexample | |
245 | |
246 Here is an example in which we supply the string @code{"(testing)"} as | |
247 initial input: | |
248 | |
249 @smallexample | |
250 @group | |
251 (read-minibuffer | |
252 "Enter an expression: " (format "%s" '(testing))) | |
253 | |
254 ;; @r{Here is how the minibuffer is displayed:} | |
255 @end group | |
256 | |
257 @group | |
258 ---------- Buffer: Minibuffer ---------- | |
259 Enter an expression: (testing)@point{} | |
260 ---------- Buffer: Minibuffer ---------- | |
261 @end group | |
262 @end smallexample | |
263 | |
264 @noindent | |
265 The user can type @key{RET} immediately to use the initial input as a | |
266 default, or can edit the input. | |
267 @end defun | |
268 | |
269 @defun eval-minibuffer prompt &optional initial | |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
270 This function reads a Lisp expression in the minibuffer, evaluates it, |
6555 | 271 then returns the result. The arguments @var{prompt} and @var{initial} |
272 are used as in @code{read-from-minibuffer}. | |
273 | |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
274 This function simply evaluates the result of a call to |
6555 | 275 @code{read-minibuffer}: |
276 | |
277 @smallexample | |
278 @group | |
279 (eval-minibuffer @var{prompt} @var{initial}) | |
280 @equiv{} | |
281 (eval (read-minibuffer @var{prompt} @var{initial})) | |
282 @end group | |
283 @end smallexample | |
284 @end defun | |
285 | |
286 @defun edit-and-eval-command prompt form | |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
287 This function reads a Lisp expression in the minibuffer, and then |
6555 | 288 evaluates it. The difference between this command and |
289 @code{eval-minibuffer} is that here the initial @var{form} is not | |
290 optional and it is treated as a Lisp object to be converted to printed | |
291 representation rather than as a string of text. It is printed with | |
292 @code{prin1}, so if it is a string, double-quote characters (@samp{"}) | |
293 appear in the initial text. @xref{Output Functions}. | |
294 | |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
295 The first thing @code{edit-and-eval-command} does is to activate the |
6555 | 296 minibuffer with @var{prompt} as the prompt. Then it inserts the printed |
297 representation of @var{form} in the minibuffer, and lets the user edit. | |
298 When the user exits the minibuffer, the edited text is read with | |
299 @code{read} and then evaluated. The resulting value becomes the value | |
300 of @code{edit-and-eval-command}. | |
301 | |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
302 In the following example, we offer the user an expression with initial |
6555 | 303 text which is a valid form already: |
304 | |
305 @smallexample | |
306 @group | |
307 (edit-and-eval-command "Please edit: " '(forward-word 1)) | |
308 | |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
309 ;; @r{After evaluation of the preceding expression,} |
6555 | 310 ;; @r{the following appears in the minibuffer:} |
311 @end group | |
312 | |
313 @group | |
314 ---------- Buffer: Minibuffer ---------- | |
315 Please edit: (forward-word 1)@point{} | |
316 ---------- Buffer: Minibuffer ---------- | |
317 @end group | |
318 @end smallexample | |
319 | |
320 @noindent | |
321 Typing @key{RET} right away would exit the minibuffer and evaluate the | |
322 expression, thus moving point forward one word. | |
323 @code{edit-and-eval-command} returns @code{nil} in this example. | |
324 @end defun | |
325 | |
326 @node Minibuffer History | |
327 @section Minibuffer History | |
328 @cindex minibuffer history | |
329 @cindex history list | |
330 | |
331 A @dfn{minibuffer history list} records previous minibuffer inputs so | |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
332 the user can reuse them conveniently. A history list is actually a |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
333 symbol, not a list; it is a variable whose value is a list of strings |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
334 (previous inputs), most recent first. |
6555 | 335 |
336 There are many separate history lists, used for different kinds of | |
337 inputs. It's the Lisp programmer's job to specify the right history | |
338 list for each use of the minibuffer. | |
339 | |
340 The basic minibuffer input functions @code{read-from-minibuffer} and | |
341 @code{completing-read} both accept an optional argument named @var{hist} | |
342 which is how you specify the history list. Here are the possible | |
343 values: | |
344 | |
345 @table @asis | |
346 @item @var{variable} | |
347 Use @var{variable} (a symbol) as the history list. | |
348 | |
349 @item (@var{variable} . @var{startpos}) | |
350 Use @var{variable} (a symbol) as the history list, and assume that the | |
351 initial history position is @var{startpos} (an integer, counting from | |
352 zero which specifies the most recent element of the history). | |
353 | |
354 If you specify @var{startpos}, then you should also specify that element | |
355 of the history as the initial minibuffer contents, for consistency. | |
356 @end table | |
357 | |
358 If you don't specify @var{hist}, then the default history list | |
359 @code{minibuffer-history} is used. For other standard history lists, | |
360 see below. You can also create your own history list variable; just | |
361 initialize it to @code{nil} before the first use. | |
362 | |
363 Both @code{read-from-minibuffer} and @code{completing-read} add new | |
364 elements to the history list automatically, and provide commands to | |
365 allow the user to reuse items on the list. The only thing your program | |
366 needs to do to use a history list is to initialize it and to pass its | |
367 name to the input functions when you wish. But it is safe to modify the | |
368 list by hand when the minibuffer input functions are not using it. | |
369 | |
370 @defvar minibuffer-history | |
371 The default history list for minibuffer history input. | |
372 @end defvar | |
373 | |
374 @defvar query-replace-history | |
375 A history list for arguments to @code{query-replace} (and similar | |
376 arguments to other commands). | |
377 @end defvar | |
378 | |
379 @defvar file-name-history | |
380 A history list for file name arguments. | |
381 @end defvar | |
382 | |
383 @defvar regexp-history | |
384 A history list for regular expression arguments. | |
385 @end defvar | |
386 | |
387 @defvar extended-command-history | |
388 A history list for arguments that are names of extended commands. | |
389 @end defvar | |
390 | |
391 @defvar shell-command-history | |
392 A history list for arguments that are shell commands. | |
393 @end defvar | |
394 | |
395 @defvar read-expression-history | |
396 A history list for arguments that are Lisp expressions to evaluate. | |
397 @end defvar | |
398 | |
399 @node Completion | |
400 @section Completion | |
401 @cindex completion | |
402 | |
403 @dfn{Completion} is a feature that fills in the rest of a name | |
404 starting from an abbreviation for it. Completion works by comparing the | |
405 user's input against a list of valid names and determining how much of | |
406 the name is determined uniquely by what the user has typed. For | |
407 example, when you type @kbd{C-x b} (@code{switch-to-buffer}) and then | |
408 type the first few letters of the name of the buffer to which you wish | |
409 to switch, and then type @key{TAB} (@code{minibuffer-complete}), Emacs | |
410 extends the name as far as it can. | |
411 | |
412 Standard Emacs commands offer completion for names of symbols, files, | |
413 buffers, and processes; with the functions in this section, you can | |
414 implement completion for other kinds of names. | |
415 | |
416 The @code{try-completion} function is the basic primitive for | |
417 completion: it returns the longest determined completion of a given | |
418 initial string, with a given set of strings to match against. | |
419 | |
420 The function @code{completing-read} provides a higher-level interface | |
421 for completion. A call to @code{completing-read} specifies how to | |
422 determine the list of valid names. The function then activates the | |
423 minibuffer with a local keymap that binds a few keys to commands useful | |
424 for completion. Other functions provide convenient simple interfaces | |
425 for reading certain kinds of names with completion. | |
426 | |
427 @menu | |
428 * Basic Completion:: Low-level functions for completing strings. | |
429 (These are too low level to use the minibuffer.) | |
430 * Minibuffer Completion:: Invoking the minibuffer with completion. | |
431 * Completion Commands:: Minibuffer commands that do completion. | |
432 * High-Level Completion:: Convenient special cases of completion | |
433 (reading buffer name, file name, etc.) | |
434 * Reading File Names:: Using completion to read file names. | |
435 * Programmed Completion:: Finding the completions for a given file name. | |
436 @end menu | |
437 | |
438 @node Basic Completion | |
439 @subsection Basic Completion Functions | |
440 | |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
441 The two functions @code{try-completion} and @code{all-completions} |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
442 have nothing in themselves to do with minibuffers. We describe them in |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
443 this chapter so as to keep them near the higher-level completion |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
444 features that do use the minibuffer. |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
445 |
6555 | 446 @defun try-completion string collection &optional predicate |
447 This function returns the longest common substring of all possible | |
448 completions of @var{string} in @var{collection}. The value of | |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
449 @var{collection} must be an alist, an obarray, or a function that |
6555 | 450 implements a virtual set of strings (see below). |
451 | |
452 Completion compares @var{string} against each of the permissible | |
453 completions specified by @var{collection}; if the beginning of the | |
454 permissible completion equals @var{string}, it matches. If no permissible | |
455 completions match, @code{try-completion} returns @code{nil}. If only | |
456 one permissible completion matches, and the match is exact, then | |
457 @code{try-completion} returns @code{t}. Otherwise, the value is the | |
458 longest initial sequence common to all the permissible completions that | |
459 match. | |
460 | |
461 If @var{collection} is an alist (@pxref{Association Lists}), the | |
462 @sc{car}s of the alist elements form the set of permissible completions. | |
463 | |
464 @cindex obarray in completion | |
465 If @var{collection} is an obarray (@pxref{Creating Symbols}), the names | |
466 of all symbols in the obarray form the set of permissible completions. The | |
467 global variable @code{obarray} holds an obarray containing the names of | |
468 all interned Lisp symbols. | |
469 | |
470 Note that the only valid way to make a new obarray is to create it | |
471 empty and then add symbols to it one by one using @code{intern}. | |
472 Also, you cannot intern a given symbol in more than one obarray. | |
473 | |
474 If the argument @var{predicate} is non-@code{nil}, then it must be a | |
475 function of one argument. It is used to test each possible match, and | |
476 the match is accepted only if @var{predicate} returns non-@code{nil}. | |
477 The argument given to @var{predicate} is either a cons cell from the alist | |
478 (the @sc{car} of which is a string) or else it is a symbol (@emph{not} a | |
479 symbol name) from the obarray. | |
480 | |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
481 You can also use a symbol that is a function as @var{collection}. Then |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
482 the function is solely responsible for performing completion; |
6555 | 483 @code{try-completion} returns whatever this function returns. The |
484 function is called with three arguments: @var{string}, @var{predicate} | |
485 and @code{nil}. (The reason for the third argument is so that the same | |
486 function can be used in @code{all-completions} and do the appropriate | |
487 thing in either case.) @xref{Programmed Completion}. | |
488 | |
489 In the first of the following examples, the string @samp{foo} is | |
490 matched by three of the alist @sc{car}s. All of the matches begin with | |
491 the characters @samp{fooba}, so that is the result. In the second | |
492 example, there is only one possible match, and it is exact, so the value | |
493 is @code{t}. | |
494 | |
495 @smallexample | |
496 @group | |
497 (try-completion | |
498 "foo" | |
499 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))) | |
500 @result{} "fooba" | |
501 @end group | |
502 | |
503 @group | |
504 (try-completion "foo" '(("barfoo" 2) ("foo" 3))) | |
505 @result{} t | |
506 @end group | |
507 @end smallexample | |
508 | |
509 In the following example, numerous symbols begin with the characters | |
510 @samp{forw}, and all of them begin with the word @samp{forward}. In | |
511 most of the symbols, this is followed with a @samp{-}, but not in all, | |
512 so no more than @samp{forward} can be completed. | |
513 | |
514 @smallexample | |
515 @group | |
516 (try-completion "forw" obarray) | |
517 @result{} "forward" | |
518 @end group | |
519 @end smallexample | |
520 | |
521 Finally, in the following example, only two of the three possible | |
522 matches pass the predicate @code{test} (the string @samp{foobaz} is | |
523 too short). Both of those begin with the string @samp{foobar}. | |
524 | |
525 @smallexample | |
526 @group | |
527 (defun test (s) | |
528 (> (length (car s)) 6)) | |
529 @result{} test | |
530 @end group | |
531 @group | |
532 (try-completion | |
533 "foo" | |
534 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)) | |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
535 'test) |
6555 | 536 @result{} "foobar" |
537 @end group | |
538 @end smallexample | |
539 @end defun | |
540 | |
12067 | 541 @defun all-completions string collection &optional predicate nospace |
6555 | 542 This function returns a list of all possible completions of |
543 @var{string}. The parameters to this function are the same as to | |
544 @code{try-completion}. | |
545 | |
546 If @var{collection} is a function, it is called with three arguments: | |
547 @var{string}, @var{predicate} and @code{t}; then @code{all-completions} | |
548 returns whatever the function returns. @xref{Programmed Completion}. | |
549 | |
12067 | 550 If @var{nospace} is non-@code{nil}, completions that start with a space |
551 are ignored unless @var{string} also starts with a space. | |
552 | |
6555 | 553 Here is an example, using the function @code{test} shown in the |
554 example for @code{try-completion}: | |
555 | |
556 @smallexample | |
557 @group | |
558 (defun test (s) | |
559 (> (length (car s)) 6)) | |
560 @result{} test | |
561 @end group | |
562 | |
563 @group | |
564 (all-completions | |
565 "foo" | |
566 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)) | |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
567 'test) |
6555 | 568 @result{} ("foobar1" "foobar2") |
569 @end group | |
570 @end smallexample | |
571 @end defun | |
572 | |
573 @defvar completion-ignore-case | |
574 If the value of this variable is | |
575 non-@code{nil}, Emacs does not consider case significant in completion. | |
576 @end defvar | |
577 | |
578 @node Minibuffer Completion | |
579 @subsection Completion and the Minibuffer | |
580 | |
581 This section describes the basic interface for reading from the | |
582 minibuffer with completion. | |
583 | |
584 @defun completing-read prompt collection &optional predicate require-match initial hist | |
585 This function reads a string in the minibuffer, assisting the user by | |
586 providing completion. It activates the minibuffer with prompt | |
587 @var{prompt}, which must be a string. If @var{initial} is | |
588 non-@code{nil}, @code{completing-read} inserts it into the minibuffer as | |
589 part of the input. Then it allows the user to edit the input, providing | |
590 several commands to attempt completion. | |
591 | |
592 The actual completion is done by passing @var{collection} and | |
593 @var{predicate} to the function @code{try-completion}. This happens in | |
594 certain commands bound in the local keymaps used for completion. | |
595 | |
596 If @var{require-match} is @code{t}, the usual minibuffer exit commands | |
597 won't exit unless the input completes to an element of @var{collection}. | |
598 If @var{require-match} is neither @code{nil} nor @code{t}, then the exit | |
599 commands won't exit unless the input typed is itself an element of | |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
600 @var{collection}. If @var{require-match} is @code{nil}, the exit |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
601 commands work regardless of the input in the minibuffer. |
6555 | 602 |
8753 | 603 The user can exit with null input by typing @key{RET} with an empty |
16238
75913ae7ac7e
Clarify how completing-read returns an empty string.
Richard M. Stallman <rms@gnu.org>
parents:
16157
diff
changeset
|
604 minibuffer. Then @code{completing-read} returns @code{""}. This is how |
75913ae7ac7e
Clarify how completing-read returns an empty string.
Richard M. Stallman <rms@gnu.org>
parents:
16157
diff
changeset
|
605 the user requests whatever default the command uses for the value being |
75913ae7ac7e
Clarify how completing-read returns an empty string.
Richard M. Stallman <rms@gnu.org>
parents:
16157
diff
changeset
|
606 read. The user can return using @key{RET} in this way regardless of the |
75913ae7ac7e
Clarify how completing-read returns an empty string.
Richard M. Stallman <rms@gnu.org>
parents:
16157
diff
changeset
|
607 value of @var{require-match}, and regardless of whether the empty string |
75913ae7ac7e
Clarify how completing-read returns an empty string.
Richard M. Stallman <rms@gnu.org>
parents:
16157
diff
changeset
|
608 is included in @var{collection}. |
8753 | 609 |
6555 | 610 The function @code{completing-read} works by calling |
611 @code{read-minibuffer}. It uses @code{minibuffer-local-completion-map} | |
612 as the keymap if @var{require-match} is @code{nil}, and uses | |
613 @code{minibuffer-local-must-match-map} if @var{require-match} is | |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
614 non-@code{nil}. @xref{Completion Commands}. |
6555 | 615 |
616 The argument @var{hist} specifies which history list variable to use for | |
617 saving the input and for minibuffer history commands. It defaults to | |
618 @code{minibuffer-history}. @xref{Minibuffer History}. | |
619 | |
620 Completion ignores case when comparing the input against the possible | |
621 matches, if the built-in variable @code{completion-ignore-case} is | |
622 non-@code{nil}. @xref{Basic Completion}. | |
623 | |
624 Here's an example of using @code{completing-read}: | |
625 | |
626 @smallexample | |
627 @group | |
628 (completing-read | |
629 "Complete a foo: " | |
630 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)) | |
631 nil t "fo") | |
632 @end group | |
633 | |
634 @group | |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
635 ;; @r{After evaluation of the preceding expression,} |
6555 | 636 ;; @r{the following appears in the minibuffer:} |
637 | |
638 ---------- Buffer: Minibuffer ---------- | |
639 Complete a foo: fo@point{} | |
640 ---------- Buffer: Minibuffer ---------- | |
641 @end group | |
642 @end smallexample | |
643 | |
644 @noindent | |
645 If the user then types @kbd{@key{DEL} @key{DEL} b @key{RET}}, | |
646 @code{completing-read} returns @code{barfoo}. | |
647 | |
648 The @code{completing-read} function binds three variables to pass | |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
649 information to the commands that actually do completion. These |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
650 variables are @code{minibuffer-completion-table}, |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
651 @code{minibuffer-completion-predicate} and |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
652 @code{minibuffer-completion-confirm}. For more information about them, |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
653 see @ref{Completion Commands}. |
6555 | 654 @end defun |
655 | |
656 @node Completion Commands | |
657 @subsection Minibuffer Commands That Do Completion | |
658 | |
659 This section describes the keymaps, commands and user options used in | |
660 the minibuffer to do completion. | |
661 | |
662 @defvar minibuffer-local-completion-map | |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
663 @code{completing-read} uses this value as the local keymap when an |
6555 | 664 exact match of one of the completions is not required. By default, this |
665 keymap makes the following bindings: | |
666 | |
667 @table @asis | |
668 @item @kbd{?} | |
669 @code{minibuffer-completion-help} | |
670 | |
671 @item @key{SPC} | |
672 @code{minibuffer-complete-word} | |
673 | |
674 @item @key{TAB} | |
675 @code{minibuffer-complete} | |
676 @end table | |
677 | |
678 @noindent | |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
679 with other characters bound as in @code{minibuffer-local-map} |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
680 (@pxref{Text from Minibuffer}). |
6555 | 681 @end defvar |
682 | |
683 @defvar minibuffer-local-must-match-map | |
684 @code{completing-read} uses this value as the local keymap when an | |
685 exact match of one of the completions is required. Therefore, no keys | |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
686 are bound to @code{exit-minibuffer}, the command that exits the |
6555 | 687 minibuffer unconditionally. By default, this keymap makes the following |
688 bindings: | |
689 | |
690 @table @asis | |
691 @item @kbd{?} | |
692 @code{minibuffer-completion-help} | |
693 | |
694 @item @key{SPC} | |
695 @code{minibuffer-complete-word} | |
696 | |
697 @item @key{TAB} | |
698 @code{minibuffer-complete} | |
699 | |
700 @item @key{LFD} | |
701 @code{minibuffer-complete-and-exit} | |
702 | |
703 @item @key{RET} | |
704 @code{minibuffer-complete-and-exit} | |
705 @end table | |
706 | |
707 @noindent | |
708 with other characters bound as in @code{minibuffer-local-map}. | |
709 @end defvar | |
710 | |
711 @defvar minibuffer-completion-table | |
712 The value of this variable is the alist or obarray used for completion | |
713 in the minibuffer. This is the global variable that contains what | |
714 @code{completing-read} passes to @code{try-completion}. It is used by | |
715 minibuffer completion commands such as @code{minibuffer-complete-word}. | |
716 @end defvar | |
717 | |
718 @defvar minibuffer-completion-predicate | |
719 This variable's value is the predicate that @code{completing-read} | |
720 passes to @code{try-completion}. The variable is also used by the other | |
721 minibuffer completion functions. | |
722 @end defvar | |
723 | |
724 @deffn Command minibuffer-complete-word | |
725 This function completes the minibuffer contents by at most a single | |
726 word. Even if the minibuffer contents have only one completion, | |
727 @code{minibuffer-complete-word} does not add any characters beyond the | |
728 first character that is not a word constituent. @xref{Syntax Tables}. | |
729 @end deffn | |
730 | |
731 @deffn Command minibuffer-complete | |
732 This function completes the minibuffer contents as far as possible. | |
733 @end deffn | |
734 | |
735 @deffn Command minibuffer-complete-and-exit | |
736 This function completes the minibuffer contents, and exits if | |
737 confirmation is not required, i.e., if | |
13319
ce09d77f76a6
Minor fix in minibuffer-complete-and-exit.
Richard M. Stallman <rms@gnu.org>
parents:
12226
diff
changeset
|
738 @code{minibuffer-completion-confirm} is @code{nil}. If confirmation |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
739 @emph{is} required, it is given by repeating this command |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
740 immediately---the command is programmed to work without confirmation |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
741 when run twice in succession. |
6555 | 742 @end deffn |
743 | |
744 @defvar minibuffer-completion-confirm | |
745 When the value of this variable is non-@code{nil}, Emacs asks for | |
746 confirmation of a completion before exiting the minibuffer. The | |
747 function @code{minibuffer-complete-and-exit} checks the value of this | |
748 variable before it exits. | |
749 @end defvar | |
750 | |
751 @deffn Command minibuffer-completion-help | |
752 This function creates a list of the possible completions of the | |
753 current minibuffer contents. It works by calling @code{all-completions} | |
754 using the value of the variable @code{minibuffer-completion-table} as | |
755 the @var{collection} argument, and the value of | |
756 @code{minibuffer-completion-predicate} as the @var{predicate} argument. | |
757 The list of completions is displayed as text in a buffer named | |
758 @samp{*Completions*}. | |
759 @end deffn | |
760 | |
761 @defun display-completion-list completions | |
762 This function displays @var{completions} to the stream in | |
7337
cd57cd335fff
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7221
diff
changeset
|
763 @code{standard-output}, usually a buffer. (@xref{Read and Print}, for more |
6555 | 764 information about streams.) The argument @var{completions} is normally |
765 a list of completions just returned by @code{all-completions}, but it | |
766 does not have to be. Each element may be a symbol or a string, either | |
767 of which is simply printed, or a list of two strings, which is printed | |
768 as if the strings were concatenated. | |
769 | |
770 This function is called by @code{minibuffer-completion-help}. The | |
771 most common way to use it is together with | |
772 @code{with-output-to-temp-buffer}, like this: | |
773 | |
774 @example | |
775 (with-output-to-temp-buffer "*Completions*" | |
776 (display-completion-list | |
777 (all-completions (buffer-string) my-alist))) | |
778 @end example | |
779 @end defun | |
780 | |
781 @defopt completion-auto-help | |
782 If this variable is non-@code{nil}, the completion commands | |
783 automatically display a list of possible completions whenever nothing | |
784 can be completed because the next character is not uniquely determined. | |
785 @end defopt | |
786 | |
787 @node High-Level Completion | |
788 @subsection High-Level Completion Functions | |
789 | |
790 This section describes the higher-level convenient functions for | |
791 reading certain sorts of names with completion. | |
792 | |
12098 | 793 In most cases, you should not call these functions in the middle of a |
794 Lisp function. When possible, do all minibuffer input as part of | |
795 reading the arguments for a command, in the @code{interactive} spec. | |
796 @xref{Defining Commands}. | |
797 | |
6555 | 798 @defun read-buffer prompt &optional default existing |
799 This function reads the name of a buffer and returns it as a string. | |
800 The argument @var{default} is the default name to use, the value to | |
801 return if the user exits with an empty minibuffer. If non-@code{nil}, | |
802 it should be a string or a buffer. It is mentioned in the prompt, but | |
803 is not inserted in the minibuffer as initial input. | |
804 | |
805 If @var{existing} is non-@code{nil}, then the name specified must be | |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
806 that of an existing buffer. The usual commands to exit the minibuffer |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
807 do not exit if the text is not valid, and @key{RET} does completion to |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
808 attempt to find a valid name. (However, @var{default} is not checked |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
809 for validity; it is returned, whatever it is, if the user exits with the |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
810 minibuffer empty.) |
6555 | 811 |
812 In the following example, the user enters @samp{minibuffer.t}, and | |
813 then types @key{RET}. The argument @var{existing} is @code{t}, and the | |
814 only buffer name starting with the given input is | |
815 @samp{minibuffer.texi}, so that name is the value. | |
816 | |
817 @example | |
818 (read-buffer "Buffer name? " "foo" t) | |
819 @group | |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
820 ;; @r{After evaluation of the preceding expression,} |
6555 | 821 ;; @r{the following prompt appears,} |
822 ;; @r{with an empty minibuffer:} | |
823 @end group | |
824 | |
825 @group | |
826 ---------- Buffer: Minibuffer ---------- | |
827 Buffer name? (default foo) @point{} | |
828 ---------- Buffer: Minibuffer ---------- | |
829 @end group | |
830 | |
831 @group | |
832 ;; @r{The user types @kbd{minibuffer.t @key{RET}}.} | |
833 @result{} "minibuffer.texi" | |
834 @end group | |
835 @end example | |
836 @end defun | |
837 | |
838 @defun read-command prompt | |
839 This function reads the name of a command and returns it as a Lisp | |
840 symbol. The argument @var{prompt} is used as in | |
841 @code{read-from-minibuffer}. Recall that a command is anything for | |
842 which @code{commandp} returns @code{t}, and a command name is a symbol | |
843 for which @code{commandp} returns @code{t}. @xref{Interactive Call}. | |
844 | |
845 @example | |
846 (read-command "Command name? ") | |
847 | |
848 @group | |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
849 ;; @r{After evaluation of the preceding expression,} |
6555 | 850 ;; @r{the following prompt appears with an empty minibuffer:} |
851 @end group | |
852 | |
853 @group | |
854 ---------- Buffer: Minibuffer ---------- | |
855 Command name? | |
856 ---------- Buffer: Minibuffer ---------- | |
857 @end group | |
858 @end example | |
859 | |
860 @noindent | |
861 If the user types @kbd{forward-c @key{RET}}, then this function returns | |
862 @code{forward-char}. | |
863 | |
16736
981e116b4ac6
Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents:
16238
diff
changeset
|
864 The @code{read-command} function is a simplified interface to |
981e116b4ac6
Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents:
16238
diff
changeset
|
865 @code{completing-read}. It uses the variable @code{obarray} so as to |
981e116b4ac6
Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents:
16238
diff
changeset
|
866 complete in the set of extant Lisp symbols, and it uses the |
6555 | 867 @code{commandp} predicate so as to accept only command names: |
868 | |
869 @cindex @code{commandp} example | |
870 @example | |
871 @group | |
872 (read-command @var{prompt}) | |
873 @equiv{} | |
874 (intern (completing-read @var{prompt} obarray | |
875 'commandp t nil)) | |
876 @end group | |
877 @end example | |
878 @end defun | |
879 | |
880 @defun read-variable prompt | |
881 This function reads the name of a user variable and returns it as a | |
882 symbol. | |
883 | |
884 @example | |
885 @group | |
886 (read-variable "Variable name? ") | |
887 | |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
888 ;; @r{After evaluation of the preceding expression,} |
6555 | 889 ;; @r{the following prompt appears,} |
890 ;; @r{with an empty minibuffer:} | |
891 @end group | |
892 | |
893 @group | |
894 ---------- Buffer: Minibuffer ---------- | |
895 Variable name? @point{} | |
896 ---------- Buffer: Minibuffer ---------- | |
897 @end group | |
898 @end example | |
899 | |
900 @noindent | |
901 If the user then types @kbd{fill-p @key{RET}}, @code{read-variable} | |
902 returns @code{fill-prefix}. | |
903 | |
904 This function is similar to @code{read-command}, but uses the | |
905 predicate @code{user-variable-p} instead of @code{commandp}: | |
906 | |
907 @cindex @code{user-variable-p} example | |
908 @example | |
909 @group | |
910 (read-variable @var{prompt}) | |
911 @equiv{} | |
912 (intern | |
913 (completing-read @var{prompt} obarray | |
914 'user-variable-p t nil)) | |
915 @end group | |
916 @end example | |
917 @end defun | |
918 | |
919 @node Reading File Names | |
920 @subsection Reading File Names | |
921 | |
922 Here is another high-level completion function, designed for reading a | |
923 file name. It provides special features including automatic insertion | |
924 of the default directory. | |
925 | |
926 @defun read-file-name prompt &optional directory default existing initial | |
927 This function reads a file name in the minibuffer, prompting with | |
928 @var{prompt} and providing completion. If @var{default} is | |
929 non-@code{nil}, then the function returns @var{default} if the user just | |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
930 types @key{RET}. @var{default} is not checked for validity; it is |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
931 returned, whatever it is, if the user exits with the minibuffer empty. |
6555 | 932 |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
933 If @var{existing} is non-@code{nil}, then the user must specify the name |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
934 of an existing file; @key{RET} performs completion to make the name |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
935 valid if possible, and then refuses to exit if it is not valid. If the |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
936 value of @var{existing} is neither @code{nil} nor @code{t}, then |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
937 @key{RET} also requires confirmation after completion. If |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
938 @var{existing} is @code{nil}, then the name of a nonexistent file is |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
939 acceptable. |
6555 | 940 |
941 The argument @var{directory} specifies the directory to use for | |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
942 completion of relative file names. If @code{insert-default-directory} |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
943 is non-@code{nil}, @var{directory} is also inserted in the minibuffer as |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
944 initial input. It defaults to the current buffer's value of |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
945 @code{default-directory}. |
6555 | 946 |
947 @c Emacs 19 feature | |
948 If you specify @var{initial}, that is an initial file name to insert in | |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
949 the buffer (after with @var{directory}, if that is inserted). In this |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
950 case, point goes at the beginning of @var{initial}. The default for |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
951 @var{initial} is @code{nil}---don't insert any file name. To see what |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
952 @var{initial} does, try the command @kbd{C-x C-v}. |
6555 | 953 |
954 Here is an example: | |
955 | |
956 @example | |
957 @group | |
958 (read-file-name "The file is ") | |
959 | |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
960 ;; @r{After evaluation of the preceding expression,} |
6555 | 961 ;; @r{the following appears in the minibuffer:} |
962 @end group | |
963 | |
964 @group | |
965 ---------- Buffer: Minibuffer ---------- | |
966 The file is /gp/gnu/elisp/@point{} | |
967 ---------- Buffer: Minibuffer ---------- | |
968 @end group | |
969 @end example | |
970 | |
971 @noindent | |
972 Typing @kbd{manual @key{TAB}} results in the following: | |
973 | |
974 @example | |
975 @group | |
976 ---------- Buffer: Minibuffer ---------- | |
977 The file is /gp/gnu/elisp/manual.texi@point{} | |
978 ---------- Buffer: Minibuffer ---------- | |
979 @end group | |
980 @end example | |
981 | |
982 @c Wordy to avoid overfull hbox in smallbook mode. | |
983 @noindent | |
984 If the user types @key{RET}, @code{read-file-name} returns the file name | |
985 as the string @code{"/gp/gnu/elisp/manual.texi"}. | |
986 @end defun | |
987 | |
988 @defopt insert-default-directory | |
989 This variable is used by @code{read-file-name}. Its value controls | |
990 whether @code{read-file-name} starts by placing the name of the default | |
991 directory in the minibuffer, plus the initial file name if any. If the | |
992 value of this variable is @code{nil}, then @code{read-file-name} does | |
12098 | 993 not place any initial input in the minibuffer (unless you specify |
994 initial input with the @var{initial} argument). In that case, the | |
6555 | 995 default directory is still used for completion of relative file names, |
996 but is not displayed. | |
997 | |
998 For example: | |
999 | |
1000 @example | |
1001 @group | |
1002 ;; @r{Here the minibuffer starts out with the default directory.} | |
1003 (let ((insert-default-directory t)) | |
1004 (read-file-name "The file is ")) | |
1005 @end group | |
1006 | |
1007 @group | |
1008 ---------- Buffer: Minibuffer ---------- | |
1009 The file is ~lewis/manual/@point{} | |
1010 ---------- Buffer: Minibuffer ---------- | |
1011 @end group | |
1012 | |
1013 @group | |
1014 ;; @r{Here the minibuffer is empty and only the prompt} | |
1015 ;; @r{appears on its line.} | |
1016 (let ((insert-default-directory nil)) | |
1017 (read-file-name "The file is ")) | |
1018 @end group | |
1019 | |
1020 @group | |
1021 ---------- Buffer: Minibuffer ---------- | |
1022 The file is @point{} | |
1023 ---------- Buffer: Minibuffer ---------- | |
1024 @end group | |
1025 @end example | |
1026 @end defopt | |
1027 | |
1028 @node Programmed Completion | |
1029 @subsection Programmed Completion | |
1030 @cindex programmed completion | |
1031 | |
1032 Sometimes it is not possible to create an alist or an obarray | |
1033 containing all the intended possible completions. In such a case, you | |
1034 can supply your own function to compute the completion of a given string. | |
1035 This is called @dfn{programmed completion}. | |
1036 | |
1037 To use this feature, pass a symbol with a function definition as the | |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1038 @var{collection} argument to @code{completing-read}. The function |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1039 @code{completing-read} arranges to pass your completion function along |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1040 to @code{try-completion} and @code{all-completions}, which will then let |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1041 your function do all the work. |
6555 | 1042 |
1043 The completion function should accept three arguments: | |
1044 | |
1045 @itemize @bullet | |
1046 @item | |
1047 The string to be completed. | |
1048 | |
1049 @item | |
1050 The predicate function to filter possible matches, or @code{nil} if | |
1051 none. Your function should call the predicate for each possible match, | |
1052 and ignore the possible match if the predicate returns @code{nil}. | |
1053 | |
1054 @item | |
1055 A flag specifying the type of operation. | |
1056 @end itemize | |
1057 | |
1058 There are three flag values for three operations: | |
1059 | |
1060 @itemize @bullet | |
1061 @item | |
1062 @code{nil} specifies @code{try-completion}. The completion function | |
1063 should return the completion of the specified string, or @code{t} if the | |
16157
1713fe640e41
Clarify value returned by programmed completion function.
Richard M. Stallman <rms@gnu.org>
parents:
15768
diff
changeset
|
1064 string is a unique and exact match already, or @code{nil} if the string |
1713fe640e41
Clarify value returned by programmed completion function.
Richard M. Stallman <rms@gnu.org>
parents:
15768
diff
changeset
|
1065 matches no possibility. |
1713fe640e41
Clarify value returned by programmed completion function.
Richard M. Stallman <rms@gnu.org>
parents:
15768
diff
changeset
|
1066 |
1713fe640e41
Clarify value returned by programmed completion function.
Richard M. Stallman <rms@gnu.org>
parents:
15768
diff
changeset
|
1067 If the string is an exact match for one possibility, but also matches |
1713fe640e41
Clarify value returned by programmed completion function.
Richard M. Stallman <rms@gnu.org>
parents:
15768
diff
changeset
|
1068 other longer possibilities, the function shuold return the string, not |
1713fe640e41
Clarify value returned by programmed completion function.
Richard M. Stallman <rms@gnu.org>
parents:
15768
diff
changeset
|
1069 @code{t}. |
6555 | 1070 |
1071 @item | |
1072 @code{t} specifies @code{all-completions}. The completion function | |
1073 should return a list of all possible completions of the specified | |
1074 string. | |
1075 | |
1076 @item | |
1077 @code{lambda} specifies a test for an exact match. The completion | |
1078 function should return @code{t} if the specified string is an exact | |
1079 match for some possibility; @code{nil} otherwise. | |
1080 @end itemize | |
1081 | |
1082 It would be consistent and clean for completion functions to allow | |
12098 | 1083 lambda expressions (lists that are functions) as well as function |
6555 | 1084 symbols as @var{collection}, but this is impossible. Lists as |
1085 completion tables are already assigned another meaning---as alists. It | |
1086 would be unreliable to fail to handle an alist normally because it is | |
1087 also a possible function. So you must arrange for any function you wish | |
1088 to use for completion to be encapsulated in a symbol. | |
1089 | |
1090 Emacs uses programmed completion when completing file names. | |
1091 @xref{File Name Completion}. | |
1092 | |
1093 @node Yes-or-No Queries | |
1094 @section Yes-or-No Queries | |
1095 @cindex asking the user questions | |
1096 @cindex querying the user | |
1097 @cindex yes-or-no questions | |
1098 | |
1099 This section describes functions used to ask the user a yes-or-no | |
1100 question. The function @code{y-or-n-p} can be answered with a single | |
1101 character; it is useful for questions where an inadvertent wrong answer | |
1102 will not have serious consequences. @code{yes-or-no-p} is suitable for | |
1103 more momentous questions, since it requires three or four characters to | |
1104 answer. | |
1105 | |
7337
cd57cd335fff
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7221
diff
changeset
|
1106 If either of these functions is called in a command that was invoked |
cd57cd335fff
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7221
diff
changeset
|
1107 using the mouse---more precisely, if @code{last-nonmenu-event} |
cd57cd335fff
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7221
diff
changeset
|
1108 (@pxref{Command Loop Info}) is either @code{nil} or a list---then it |
cd57cd335fff
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7221
diff
changeset
|
1109 uses a dialog box or pop-up menu to ask the question. Otherwise, it |
cd57cd335fff
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7221
diff
changeset
|
1110 uses keyboard input. You can force use of the mouse or use of keyboard |
cd57cd335fff
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7221
diff
changeset
|
1111 input by binding @code{last-nonmenu-event} to a suitable value around |
cd57cd335fff
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7221
diff
changeset
|
1112 the call. |
cd57cd335fff
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7221
diff
changeset
|
1113 |
6555 | 1114 Strictly speaking, @code{yes-or-no-p} uses the minibuffer and |
1115 @code{y-or-n-p} does not; but it seems best to describe them together. | |
1116 | |
1117 @defun y-or-n-p prompt | |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1118 This function asks the user a question, expecting input in the echo |
6555 | 1119 area. It returns @code{t} if the user types @kbd{y}, @code{nil} if the |
1120 user types @kbd{n}. This function also accepts @key{SPC} to mean yes | |
1121 and @key{DEL} to mean no. It accepts @kbd{C-]} to mean ``quit'', like | |
1122 @kbd{C-g}, because the question might look like a minibuffer and for | |
1123 that reason the user might try to use @kbd{C-]} to get out. The answer | |
1124 is a single character, with no @key{RET} needed to terminate it. Upper | |
1125 and lower case are equivalent. | |
1126 | |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1127 ``Asking the question'' means printing @var{prompt} in the echo area, |
6555 | 1128 followed by the string @w{@samp{(y or n) }}. If the input is not one of |
1129 the expected answers (@kbd{y}, @kbd{n}, @kbd{@key{SPC}}, | |
1130 @kbd{@key{DEL}}, or something that quits), the function responds | |
1131 @samp{Please answer y or n.}, and repeats the request. | |
1132 | |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1133 This function does not actually use the minibuffer, since it does not |
6555 | 1134 allow editing of the answer. It actually uses the echo area (@pxref{The |
1135 Echo Area}), which uses the same screen space as the minibuffer. The | |
1136 cursor moves to the echo area while the question is being asked. | |
1137 | |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1138 The answers and their meanings, even @samp{y} and @samp{n}, are not |
6555 | 1139 hardwired. The keymap @code{query-replace-map} specifies them. |
1140 @xref{Search and Replace}. | |
1141 | |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1142 In the following example, the user first types @kbd{q}, which is |
6555 | 1143 invalid. At the next prompt the user types @kbd{y}. |
1144 | |
1145 @smallexample | |
1146 @group | |
1147 (y-or-n-p "Do you need a lift? ") | |
1148 | |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1149 ;; @r{After evaluation of the preceding expression,} |
6555 | 1150 ;; @r{the following prompt appears in the echo area:} |
1151 @end group | |
1152 | |
1153 @group | |
1154 ---------- Echo area ---------- | |
1155 Do you need a lift? (y or n) | |
1156 ---------- Echo area ---------- | |
1157 @end group | |
1158 | |
1159 ;; @r{If the user then types @kbd{q}, the following appears:} | |
1160 | |
1161 @group | |
1162 ---------- Echo area ---------- | |
1163 Please answer y or n. Do you need a lift? (y or n) | |
1164 ---------- Echo area ---------- | |
1165 @end group | |
1166 | |
1167 ;; @r{When the user types a valid answer,} | |
1168 ;; @r{it is displayed after the question:} | |
1169 | |
1170 @group | |
1171 ---------- Echo area ---------- | |
1172 Do you need a lift? (y or n) y | |
1173 ---------- Echo area ---------- | |
1174 @end group | |
1175 @end smallexample | |
1176 | |
1177 @noindent | |
1178 We show successive lines of echo area messages, but only one actually | |
1179 appears on the screen at a time. | |
1180 @end defun | |
1181 | |
15768
b913a75fddee
Add y-or-n-p-with-timeout.
Richard M. Stallman <rms@gnu.org>
parents:
13319
diff
changeset
|
1182 @defun y-or-n-p-with-timeout prompt seconds default-value |
b913a75fddee
Add y-or-n-p-with-timeout.
Richard M. Stallman <rms@gnu.org>
parents:
13319
diff
changeset
|
1183 Like @code{y-or-n-p}, except that if the user fails to answer within |
b913a75fddee
Add y-or-n-p-with-timeout.
Richard M. Stallman <rms@gnu.org>
parents:
13319
diff
changeset
|
1184 @var{seconds} seconds, this function stops waiting and returns |
b913a75fddee
Add y-or-n-p-with-timeout.
Richard M. Stallman <rms@gnu.org>
parents:
13319
diff
changeset
|
1185 @var{default-value}. It works by setting up a timer; see @ref{Timers}. |
b913a75fddee
Add y-or-n-p-with-timeout.
Richard M. Stallman <rms@gnu.org>
parents:
13319
diff
changeset
|
1186 The argument @var{seconds} may be an integer or a floating point number. |
b913a75fddee
Add y-or-n-p-with-timeout.
Richard M. Stallman <rms@gnu.org>
parents:
13319
diff
changeset
|
1187 @end defun |
b913a75fddee
Add y-or-n-p-with-timeout.
Richard M. Stallman <rms@gnu.org>
parents:
13319
diff
changeset
|
1188 |
6555 | 1189 @defun yes-or-no-p prompt |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1190 This function asks the user a question, expecting input in the |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1191 minibuffer. It returns @code{t} if the user enters @samp{yes}, |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1192 @code{nil} if the user types @samp{no}. The user must type @key{RET} to |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1193 finalize the response. Upper and lower case are equivalent. |
6555 | 1194 |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1195 @code{yes-or-no-p} starts by displaying @var{prompt} in the echo area, |
6555 | 1196 followed by @w{@samp{(yes or no) }}. The user must type one of the |
1197 expected responses; otherwise, the function responds @samp{Please answer | |
1198 yes or no.}, waits about two seconds and repeats the request. | |
1199 | |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1200 @code{yes-or-no-p} requires more work from the user than |
6555 | 1201 @code{y-or-n-p} and is appropriate for more crucial decisions. |
1202 | |
1203 Here is an example: | |
1204 | |
1205 @smallexample | |
1206 @group | |
1207 (yes-or-no-p "Do you really want to remove everything? ") | |
1208 | |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1209 ;; @r{After evaluation of the preceding expression,} |
6555 | 1210 ;; @r{the following prompt appears,} |
1211 ;; @r{with an empty minibuffer:} | |
1212 @end group | |
1213 | |
1214 @group | |
1215 ---------- Buffer: minibuffer ---------- | |
1216 Do you really want to remove everything? (yes or no) | |
1217 ---------- Buffer: minibuffer ---------- | |
1218 @end group | |
1219 @end smallexample | |
1220 | |
1221 @noindent | |
1222 If the user first types @kbd{y @key{RET}}, which is invalid because this | |
1223 function demands the entire word @samp{yes}, it responds by displaying | |
1224 these prompts, with a brief pause between them: | |
1225 | |
1226 @smallexample | |
1227 @group | |
1228 ---------- Buffer: minibuffer ---------- | |
1229 Please answer yes or no. | |
1230 Do you really want to remove everything? (yes or no) | |
1231 ---------- Buffer: minibuffer ---------- | |
1232 @end group | |
1233 @end smallexample | |
1234 @end defun | |
1235 | |
1236 @node Multiple Queries | |
1237 @section Asking Multiple Y-or-N Questions | |
1238 | |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1239 When you have a series of similar questions to ask, such as ``Do you |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1240 want to save this buffer'' for each buffer in turn, you should use |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1241 @code{map-y-or-n-p} to ask the collection of questions, rather than |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1242 asking each question individually. This gives the user certain |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1243 convenient facilities such as the ability to answer the whole series at |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1244 once. |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1245 |
6555 | 1246 @defun map-y-or-n-p prompter actor list &optional help action-alist |
1247 This function, new in Emacs 19, asks the user a series of questions, | |
1248 reading a single-character answer in the echo area for each one. | |
1249 | |
1250 The value of @var{list} specifies the objects to ask questions about. | |
1251 It should be either a list of objects or a generator function. If it is | |
1252 a function, it should expect no arguments, and should return either the | |
1253 next object to ask about, or @code{nil} meaning stop asking questions. | |
1254 | |
1255 The argument @var{prompter} specifies how to ask each question. If | |
1256 @var{prompter} is a string, the question text is computed like this: | |
1257 | |
1258 @example | |
1259 (format @var{prompter} @var{object}) | |
1260 @end example | |
1261 | |
1262 @noindent | |
1263 where @var{object} is the next object to ask about (as obtained from | |
1264 @var{list}). | |
1265 | |
1266 If not a string, @var{prompter} should be a function of one argument | |
12226 | 1267 (the next object to ask about) and should return the question text. If |
1268 the value is a string, that is the question to ask the user. The | |
1269 function can also return @code{t} meaning do act on this object (and | |
1270 don't ask the user), or @code{nil} meaning ignore this object (and don't | |
1271 ask the user). | |
6555 | 1272 |
1273 The argument @var{actor} says how to act on the answers that the user | |
1274 gives. It should be a function of one argument, and it is called with | |
1275 each object that the user says yes for. Its argument is always an | |
1276 object obtained from @var{list}. | |
1277 | |
1278 If the argument @var{help} is given, it should be a list of this form: | |
1279 | |
1280 @example | |
1281 (@var{singular} @var{plural} @var{action}) | |
1282 @end example | |
1283 | |
1284 @noindent | |
1285 where @var{singular} is a string containing a singular noun that | |
1286 describes the objects conceptually being acted on, @var{plural} is the | |
1287 corresponding plural noun, and @var{action} is a transitive verb | |
1288 describing what @var{actor} does. | |
1289 | |
1290 If you don't specify @var{help}, the default is @code{("object" | |
1291 "objects" "act on")}. | |
1292 | |
1293 Each time a question is asked, the user may enter @kbd{y}, @kbd{Y}, or | |
1294 @key{SPC} to act on that object; @kbd{n}, @kbd{N}, or @key{DEL} to skip | |
1295 that object; @kbd{!} to act on all following objects; @key{ESC} or | |
1296 @kbd{q} to exit (skip all following objects); @kbd{.} (period) to act on | |
1297 the current object and then exit; or @kbd{C-h} to get help. These are | |
1298 the same answers that @code{query-replace} accepts. The keymap | |
1299 @code{query-replace-map} defines their meaning for @code{map-y-or-n-p} | |
1300 as well as for @code{query-replace}; see @ref{Search and Replace}. | |
1301 | |
1302 You can use @var{action-alist} to specify additional possible answers | |
1303 and what they mean. It is an alist of elements of the form | |
1304 @code{(@var{char} @var{function} @var{help})}, each of which defines one | |
1305 additional answer. In this element, @var{char} is a character (the | |
1306 answer); @var{function} is a function of one argument (an object from | |
1307 @var{list}); @var{help} is a string. | |
1308 | |
1309 When the user responds with @var{char}, @code{map-y-or-n-p} calls | |
1310 @var{function}. If it returns non-@code{nil}, the object is considered | |
1311 ``acted upon'', and @code{map-y-or-n-p} advances to the next object in | |
1312 @var{list}. If it returns @code{nil}, the prompt is repeated for the | |
1313 same object. | |
1314 | |
7337
cd57cd335fff
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7221
diff
changeset
|
1315 If @code{map-y-or-n-p} is called in a command that was invoked using the |
cd57cd335fff
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7221
diff
changeset
|
1316 mouse---more precisely, if @code{last-nonmenu-event} (@pxref{Command |
cd57cd335fff
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7221
diff
changeset
|
1317 Loop Info}) is either @code{nil} or a list---then it uses a dialog box |
cd57cd335fff
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7221
diff
changeset
|
1318 or pop-up menu to ask the question. In this case, it does not use |
cd57cd335fff
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7221
diff
changeset
|
1319 keyboard input or the echo area. You can force use of the mouse or use |
cd57cd335fff
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7221
diff
changeset
|
1320 of keyboard input by binding @code{last-nonmenu-event} to a suitable |
cd57cd335fff
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7221
diff
changeset
|
1321 value around the call. |
cd57cd335fff
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7221
diff
changeset
|
1322 |
6555 | 1323 The return value of @code{map-y-or-n-p} is the number of objects acted on. |
1324 @end defun | |
1325 | |
1326 @node Minibuffer Misc | |
1327 @comment node-name, next, previous, up | |
1328 @section Minibuffer Miscellany | |
1329 | |
1330 This section describes some basic functions and variables related to | |
1331 minibuffers. | |
1332 | |
1333 @deffn Command exit-minibuffer | |
1334 This command exits the active minibuffer. It is normally bound to | |
1335 keys in minibuffer local keymaps. | |
1336 @end deffn | |
1337 | |
1338 @deffn Command self-insert-and-exit | |
1339 This command exits the active minibuffer after inserting the last | |
1340 character typed on the keyboard (found in @code{last-command-char}; | |
1341 @pxref{Command Loop Info}). | |
1342 @end deffn | |
1343 | |
1344 @deffn Command previous-history-element n | |
1345 This command replaces the minibuffer contents with the value of the | |
1346 @var{n}th previous (older) history element. | |
1347 @end deffn | |
1348 | |
1349 @deffn Command next-history-element n | |
1350 This command replaces the minibuffer contents with the value of the | |
1351 @var{n}th more recent history element. | |
1352 @end deffn | |
1353 | |
1354 @deffn Command previous-matching-history-element pattern | |
1355 This command replaces the minibuffer contents with the value of the | |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1356 previous (older) history element that matches @var{pattern} (a regular |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1357 expression). |
6555 | 1358 @end deffn |
1359 | |
1360 @deffn Command next-matching-history-element pattern | |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1361 This command replaces the minibuffer contents with the value of the next |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1362 (newer) history element that matches @var{pattern} (a regular |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1363 expression). |
6555 | 1364 @end deffn |
1365 | |
12098 | 1366 @defun minibuffer-prompt |
1367 This function returns the prompt string of the currently active | |
1368 minibuffer. If no minibuffer is active, it returns @code{nil}. | |
1369 @end defun | |
1370 | |
1371 @defun minibuffer-prompt-width | |
1372 This function returns the display width of the prompt string of the | |
1373 currently active minibuffer. If no minibuffer is active, it returns 0. | |
1374 @end defun | |
1375 | |
6555 | 1376 @defvar minibuffer-setup-hook |
1377 This is a normal hook that is run whenever the minibuffer is entered. | |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1378 @xref{Hooks}. |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1379 @end defvar |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1380 |
8529
464f7abd0b26
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
7337
diff
changeset
|
1381 @defvar minibuffer-exit-hook |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1382 This is a normal hook that is run whenever the minibuffer is exited. |
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1383 @xref{Hooks}. |
6555 | 1384 @end defvar |
1385 | |
1386 @defvar minibuffer-help-form | |
1387 The current value of this variable is used to rebind @code{help-form} | |
1388 locally inside the minibuffer (@pxref{Help Functions}). | |
1389 @end defvar | |
1390 | |
12067 | 1391 @defun active-minibuffer-window |
1392 This function returns the currently active minibuffer window, or | |
1393 @code{nil} if none is currently active. | |
1394 @end defun | |
1395 | |
6555 | 1396 @defun minibuffer-window &optional frame |
12067 | 1397 This function returns the minibuffer window used for frame @var{frame}. |
1398 If @var{frame} is @code{nil}, that stands for the current frame. Note | |
1399 that the minibuffer window used by a frame need not be part of that | |
1400 frame---a frame that has no minibuffer of its own necessarily uses some | |
1401 other frame's minibuffer window. | |
6555 | 1402 @end defun |
1403 | |
1404 @c Emacs 19 feature | |
1405 @defun window-minibuffer-p window | |
1406 This function returns non-@code{nil} if @var{window} is a minibuffer window. | |
1407 @end defun | |
1408 | |
1409 It is not correct to determine whether a given window is a minibuffer by | |
1410 comparing it with the result of @code{(minibuffer-window)}, because | |
1411 there can be more than one minibuffer window if there is more than one | |
1412 frame. | |
1413 | |
1414 @defun minibuffer-window-active-p window | |
1415 This function returns non-@code{nil} if @var{window}, assumed to be | |
1416 a minibuffer window, is currently active. | |
1417 @end defun | |
1418 | |
1419 @defvar minibuffer-scroll-window | |
1420 If the value of this variable is non-@code{nil}, it should be a window | |
1421 object. When the function @code{scroll-other-window} is called in the | |
1422 minibuffer, it scrolls this window. | |
1423 @end defvar | |
1424 | |
1425 Finally, some functions and variables deal with recursive minibuffers | |
1426 (@pxref{Recursive Editing}): | |
1427 | |
1428 @defun minibuffer-depth | |
1429 This function returns the current depth of activations of the | |
1430 minibuffer, a nonnegative integer. If no minibuffers are active, it | |
1431 returns zero. | |
1432 @end defun | |
1433 | |
1434 @defopt enable-recursive-minibuffers | |
1435 If this variable is non-@code{nil}, you can invoke commands (such as | |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1436 @code{find-file}) that use minibuffers even while in the minibuffer |
6555 | 1437 window. Such invocation produces a recursive editing level for a new |
1438 minibuffer. The outer-level minibuffer is invisible while you are | |
1439 editing the inner one. | |
1440 | |
1441 This variable only affects invoking the minibuffer while the | |
1442 minibuffer window is selected. If you switch windows while in the | |
1443 minibuffer, you can always invoke minibuffer commands while some other | |
1444 window is selected. | |
1445 @end defopt | |
1446 | |
1447 @c Emacs 19 feature | |
1448 If a command name has a property @code{enable-recursive-minibuffers} | |
7221
a2c7acc3be9c
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6555
diff
changeset
|
1449 that is non-@code{nil}, then the command can use the minibuffer to read |
6555 | 1450 arguments even if it is invoked from the minibuffer. The minibuffer |
12098 | 1451 command @code{next-matching-history-element} (normally @kbd{M-s} in the |
1452 minibuffer) uses this feature. |