|
0
|
1
|
|
|
2 @node Minibuffer, M-x, Undo, Top
|
|
|
3 @chapter The Minibuffer
|
|
|
4 @cindex minibuffer
|
|
|
5
|
|
|
6 Emacs commands use the @dfn{minibuffer} to read arguments more
|
|
|
7 complicated than a single number. Minibuffer arguments can be file
|
|
|
8 names, buffer names, Lisp function names, Emacs command names, Lisp
|
|
|
9 expressions, and many other things, depending on the command reading the
|
|
|
10 argument. To edit the argument in the minibuffer, you can use Emacs
|
|
|
11 editing commands.
|
|
|
12
|
|
|
13
|
|
|
14 @cindex prompt
|
|
|
15 When the minibuffer is in use, it appears in the echo area, and the
|
|
|
16 cursor moves there. The beginning of the minibuffer line displays a
|
|
|
17 @dfn{prompt} indicating what kind of input you should supply and how it
|
|
|
18 will be used. The prompt is often derived from the name of the command
|
|
|
19 the argument is for. The prompt normally ends with a colon.
|
|
|
20
|
|
|
21 @cindex default argument
|
|
|
22 Sometimes a @dfn{default argument} appears in parentheses after the
|
|
|
23 colon; it, too, is part of the prompt. The default is used as the
|
|
|
24 argument value if you enter an empty argument (e.g., by just typing @key{RET}).
|
|
|
25 For example, commands that read buffer names always show a default, which
|
|
|
26 is the name of the buffer that will be used if you type just @key{RET}.
|
|
|
27
|
|
|
28 @kindex C-g
|
|
|
29 The simplest way to give a minibuffer argument is to type the text you
|
|
|
30 want, terminated by @key{RET} to exit the minibuffer. To get out
|
|
|
31 of the minibuffer and cancel the command that it was for, type
|
|
|
32 @kbd{C-g}.
|
|
|
33
|
|
|
34 Since the minibuffer uses the screen space of the echo area, it can
|
|
|
35 conflict with other ways Emacs customarily uses the echo area. Here is how
|
|
|
36 Emacs handles such conflicts:
|
|
|
37
|
|
|
38 @itemize @bullet
|
|
|
39 @item
|
|
|
40 If a command gets an error while you are in the minibuffer, this does
|
|
|
41 not cancel the minibuffer. However, the echo area is needed for the
|
|
|
42 error message and therefore the minibuffer itself is hidden for a
|
|
|
43 while. It comes back after a few seconds, or as soon as you type
|
|
|
44 anything.
|
|
|
45
|
|
|
46 @item
|
|
|
47 If you use a command in the minibuffer whose purpose is to print a
|
|
|
48 message in the echo area (for example @kbd{C-x =}) the message is
|
|
|
49 displayed normally, and the minibuffer is hidden for a while. It comes back
|
|
|
50 after a few seconds, or as soon as you type anything.
|
|
|
51
|
|
|
52 @item
|
|
|
53 Echoing of keystrokes does not take place while the minibuffer is in
|
|
|
54 use.
|
|
|
55 @end itemize
|
|
|
56
|
|
|
57 @menu
|
|
|
58 * File: Minibuffer File. Entering file names with the minibuffer.
|
|
|
59 * Edit: Minibuffer Edit. How to edit in the minibuffer.
|
|
|
60 * Completion:: An abbreviation facility for minibuffer input.
|
|
|
61 * Repetition:: Re-executing commands that used the minibuffer.
|
|
|
62 @end menu
|
|
|
63
|
|
|
64 @node Minibuffer File, Minibuffer Edit, Minibuffer, Minibuffer
|
|
|
65 @section Minibuffers for File Names
|
|
|
66
|
|
|
67 Sometimes the minibuffer starts out with text in it. For example, when
|
|
|
68 you are supposed to give a file name, the minibuffer starts out containing
|
|
|
69 the @dfn{default directory}, which ends with a slash. This informs
|
|
|
70 you in which directory the file will be looked for if you do not specify
|
|
|
71 a different one. For example, the minibuffer might start out with:
|
|
|
72
|
|
|
73 @example
|
|
|
74 Find File: /u2/emacs/src/
|
|
|
75 @end example
|
|
|
76
|
|
|
77 @noindent
|
|
|
78 where @samp{Find File:@: } is the prompt. Typing @kbd{buffer.c} specifies
|
|
|
79 the file
|
|
|
80 @*@file{/u2/emacs/src/buffer.c}. To find files in nearby
|
|
|
81 directories, use @samp{..}; thus, if you type @kbd{../lisp/simple.el}, the
|
|
|
82 file that you visit will be the one named
|
|
|
83 @*@file{/u2/emacs/lisp/simple.el}.
|
|
|
84 Alternatively, you can use @kbd{M-@key{DEL}} to kill directory names you
|
|
|
85 don't want (@pxref{Words}).@refill
|
|
|
86
|
|
|
87 You can also type an absolute file name, one starting with a slash or a
|
|
|
88 tilde, ignoring the default directory. For example, to find the file
|
|
|
89 @file{/etc/termcap}, just type the name, giving:
|
|
|
90
|
|
|
91 @example
|
|
|
92 Find File: /u2/emacs/src//etc/termcap
|
|
|
93 @end example
|
|
|
94
|
|
|
95 @noindent
|
|
|
96 Two slashes in a row are not normally meaningful in Unix file names, but
|
|
|
97 they are allowed in XEmacs. They mean, ``ignore everything before the
|
|
|
98 second slash in the pair.'' Thus, @samp{/u2/emacs/src/} is ignored, and
|
|
|
99 you get the file @file{/etc/termcap}.
|
|
|
100
|
|
|
101 @vindex insert-default-directory
|
|
|
102 If you set @code{insert-default-directory} to @code{nil}, the default
|
|
|
103 directory is not inserted in the minibuffer. This way, the minibuffer
|
|
|
104 starts out empty. But the name you type, if relative, is still
|
|
|
105 interpreted with respect to the same default directory.
|
|
|
106
|
|
|
107 @node Minibuffer Edit, Completion, Minibuffer File, Minibuffer
|
|
|
108 @section Editing in the Minibuffer
|
|
|
109
|
|
|
110 The minibuffer is an Emacs buffer (albeit a peculiar one), and the usual
|
|
|
111 Emacs commands are available for editing the text of an argument you are
|
|
|
112 entering.
|
|
|
113
|
|
|
114 Since @key{RET} in the minibuffer is defined to exit the minibuffer,
|
|
|
115 you must use @kbd{C-o} or @kbd{C-q @key{LFD}} to insert a newline into
|
|
|
116 the minibuffer. (Recall that a newline is really the @key{LFD}
|
|
|
117 character.)
|
|
|
118
|
|
|
119 The minibuffer has its own window, which always has space on the screen
|
|
|
120 but acts as if it were not there when the minibuffer is not in use. The
|
|
|
121 minibuffer window is just like the others; you can switch to another
|
|
|
122 window with @kbd{C-x o}, edit text in other windows, and perhaps even
|
|
|
123 visit more files before returning to the minibuffer to submit the
|
|
|
124 argument. You can kill text in another window, return to the minibuffer
|
|
|
125 window, and then yank the text to use it in the argument. @xref{Windows}.
|
|
|
126
|
|
|
127 There are, however, some restrictions on the use of the minibuffer window.
|
|
|
128 You cannot switch buffers in it---the minibuffer and its window are
|
|
|
129 permanently attached. You also cannot split or kill the minibuffer
|
|
|
130 window, but you can make it taller with @kbd{C-x ^}.
|
|
|
131
|
|
|
132 @kindex C-M-v
|
|
|
133 If you are in the minibuffer and issue a command that displays help
|
|
|
134 text in another window, that window will be scrolled if you type
|
|
|
135 @kbd{M-C-v} while in the minibuffer until you exit the minibuffer. This
|
|
|
136 feature is helpful if a completing minibuffer gives you a long list of
|
|
|
137 possible completions.
|
|
|
138
|
|
|
139 If the variable @code{minibuffer-confirm-incomplete} is @code{t}, you
|
|
|
140 are asked for confirmation if there is no known completion for the text
|
|
|
141 you typed. For example, if you attempted to visit a non-existent file,
|
|
|
142 the minibuffer might read:
|
|
|
143 @example
|
|
|
144 Find File:chocolate_bar.c [no completions, confirm]
|
|
|
145 @end example
|
|
|
146 If you press @kbd{Return} again, that confirms the filename. Otherwise,
|
|
|
147 you can continue editing it.
|
|
|
148
|
|
|
149 Emacs supports recursive use of the minibuffer. However, it is
|
|
|
150 easy to do this by accident (because of autorepeating keyboards, for
|
|
|
151 example) and get confused. Therefore, most Emacs commands that use the
|
|
|
152 minibuffer refuse to operate if the minibuffer window is selected. If the
|
|
|
153 minibuffer is active but you have switched to a different window, recursive
|
|
|
154 use of the minibuffer is allowed---if you know enough to try to do this,
|
|
|
155 you probably will not get confused.
|
|
|
156
|
|
|
157 @vindex enable-recursive-minibuffers
|
|
|
158 If you set the variable @code{enable-recursive-minibuffers} to be
|
|
|
159 non-@code{nil}, recursive use of the minibuffer is always allowed.
|
|
|
160
|
|
|
161 @node Completion, Repetition, Minibuffer Edit, Minibuffer
|
|
|
162 @section Completion
|
|
|
163 @cindex completion
|
|
|
164
|
|
|
165 When appropriate, the minibuffer provides a @dfn{completion} facility.
|
|
|
166 You type the beginning of an argument and one of the completion keys,
|
|
|
167 and Emacs visibly fills in the rest, depending on what you have already
|
|
|
168 typed.
|
|
|
169
|
|
|
170 When completion is available, certain keys---@key{TAB}, @key{RET}, and
|
|
|
171 @key{SPC}---are redefined to complete an abbreviation present in the
|
|
|
172 minibuffer into a longer string that it stands for, by matching it
|
|
|
173 against a set of @dfn{completion alternatives} provided by the command
|
|
|
174 reading the argument. @kbd{?} is defined to display a list of possible
|
|
|
175 completions of what you have inserted.
|
|
|
176
|
|
|
177 For example, when the minibuffer is being used by @kbd{Meta-x} to read
|
|
|
178 the name of a command, it is given a list of all available Emacs command
|
|
|
179 names to complete against. The completion keys match the text in the
|
|
|
180 minibuffer against all the command names, find any additional characters of
|
|
|
181 the name that are implied by the ones already present in the minibuffer,
|
|
|
182 and add those characters to the ones you have given.
|
|
|
183
|
|
|
184 Case is normally significant in completion because it is significant in
|
|
|
185 most of the names that you can complete (buffer names, file names, and
|
|
|
186 command names). Thus, @samp{fo} will not complete to @samp{Foo}. When you
|
|
|
187 are completing a name in which case does not matter, case may be ignored
|
|
|
188 for completion's sake if specified by program.
|
|
|
189
|
|
|
190 When a completion list is displayed, the completions will highlight as
|
|
|
191 you move the mouse over them. Clicking the middle mouse button on any
|
|
|
192 highlighted completion will ``select'' it just as if you had typed it in
|
|
|
193 and hit @key{RET}.
|
|
|
194
|
|
|
195 @subsection A Completion Example
|
|
|
196
|
|
|
197 @kindex TAB
|
|
|
198 @findex minibuffer-complete
|
|
|
199 Consider the following example. If you type @kbd{Meta-x au @key{TAB}},
|
|
|
200 @key{TAB} looks for alternatives (in this case, command names) that
|
|
|
201 start with @samp{au}. There are only two commands: @code{auto-fill-mode} and
|
|
|
202 @code{auto-save-mode}. They are the same as far as @code{auto-}, so the
|
|
|
203 @samp{au} in the minibuffer changes to @samp{auto-}.@refill
|
|
|
204
|
|
|
205 If you type @key{TAB} again immediately, there are multiple possibilities
|
|
|
206 for the very next character---it could be @samp{s} or @samp{f}---so no more
|
|
|
207 characters are added; but a list of all possible completions is displayed
|
|
|
208 in another window.
|
|
|
209
|
|
|
210 If you go on to type @kbd{f @key{TAB}}, this @key{TAB} sees
|
|
|
211 @samp{auto-f}. The only command name starting this way is
|
|
|
212 @code{auto-fill-mode}, so completion inserts the rest of that command. You
|
|
|
213 now have @samp{auto-fill-mode} in the minibuffer after typing just @kbd{au
|
|
|
214 @key{TAB} f @key{TAB}}. Note that @key{TAB} has this effect because in the
|
|
|
215 minibuffer it is bound to the function @code{minibuffer-complete} when
|
|
|
216 completion is supposed to be done.@refill
|
|
|
217
|
|
|
218 @subsection Completion Commands
|
|
|
219
|
|
|
220 Here is a list of all the completion commands defined in the minibuffer
|
|
|
221 when completion is available.
|
|
|
222
|
|
|
223 @table @kbd
|
|
|
224 @item @key{TAB}
|
|
|
225 Complete the text in the minibuffer as much as possible @*
|
|
|
226 (@code{minibuffer-complete}).
|
|
|
227 @item @key{SPC}
|
|
|
228 Complete the text in the minibuffer but don't add or fill out more
|
|
|
229 than one word (@code{minibuffer-complete-word}).
|
|
|
230 @item @key{RET}
|
|
|
231 Submit the text in the minibuffer as the argument, possibly completing
|
|
|
232 first as described below (@code{minibuffer-complete-and-exit}).
|
|
|
233 @item ?
|
|
|
234 Print a list of all possible completions of the text in the minibuffer
|
|
|
235 (@code{minibuffer-list-completions}).
|
|
|
236 @item @key{button2}
|
|
|
237 Select the highlighted text under the mouse as a minibuffer response.
|
|
|
238 When the minibuffer is being used to prompt the user for a completion,
|
|
|
239 any valid completions which are visible on the screen will be highlighted
|
|
|
240 when the mouse moves over them. Clicking @key{button2} will select the
|
|
|
241 highlighted completion and exit the minibuffer.
|
|
|
242 (@code{minibuf-select-highlighted-completion}).
|
|
|
243 @end table
|
|
|
244
|
|
|
245 @kindex SPC
|
|
|
246 @findex minibuffer-complete-word
|
|
|
247 @key{SPC} completes in a way that is similar to @key{TAB}, but it never
|
|
|
248 goes beyond the next hyphen or space. If you have @samp{auto-f} in the
|
|
|
249 minibuffer and type @key{SPC}, it finds that the completion is
|
|
|
250 @samp{auto-fill-mode}, but it stops completing after @samp{fill-}.
|
|
|
251 The result is @samp{auto-fill-}. Another @key{SPC} at this point
|
|
|
252 completes all the way to @samp{auto-fill-mode}. @key{SPC} in the
|
|
|
253 minibuffer runs the function @code{minibuffer-complete-word} when
|
|
|
254 completion is available.@refill
|
|
|
255
|
|
|
256 There are three different ways that @key{RET} can work in completing
|
|
|
257 minibuffers, depending on how the argument will be used.
|
|
|
258
|
|
|
259 @itemize @bullet
|
|
|
260 @item
|
|
|
261 @dfn{Strict} completion is used when it is meaningless to give any
|
|
|
262 argument except one of the known alternatives. For example, when
|
|
|
263 @kbd{C-x k} reads the name of a buffer to kill, it is meaningless to
|
|
|
264 give anything but the name of an existing buffer. In strict
|
|
|
265 completion, @key{RET} refuses to exit if the text in the minibuffer
|
|
|
266 does not complete to an exact match.
|
|
|
267
|
|
|
268 @item
|
|
|
269 @dfn{Cautious} completion is similar to strict completion, except that
|
|
|
270 @key{RET} exits only if the text was an exact match already, not
|
|
|
271 needing completion. If the text is not an exact match, @key{RET} does
|
|
|
272 not exit, but it does complete the text. If it completes to an exact
|
|
|
273 match, a second @key{RET} will exit.
|
|
|
274
|
|
|
275 Cautious completion is used for reading file names for files that must
|
|
|
276 already exist.
|
|
|
277
|
|
|
278 @item
|
|
|
279 @dfn{Permissive} completion is used when any string is
|
|
|
280 meaningful, and the list of completion alternatives is just a guide.
|
|
|
281 For example, when @kbd{C-x C-f} reads the name of a file to visit, any
|
|
|
282 file name is allowed, in case you want to create a file. In
|
|
|
283 permissive completion, @key{RET} takes the text in the minibuffer
|
|
|
284 exactly as given, without completing it.
|
|
|
285 @end itemize
|
|
|
286
|
|
|
287 The completion commands display a list of all possible completions in a
|
|
|
288 window whenever there is more than one possibility for the very next
|
|
|
289 character. Typing @kbd{?} explicitly requests such a list. The
|
|
|
290 list of completions counts as help text, so @kbd{C-M-v} typed in the
|
|
|
291 minibuffer scrolls the list.
|
|
|
292
|
|
|
293 @vindex completion-ignored-extensions
|
|
|
294 When completion is done on file names, certain file names are usually
|
|
|
295 ignored. The variable @code{completion-ignored-extensions} contains a list
|
|
|
296 of strings; a file whose name ends in any of those strings is ignored as a
|
|
|
297 possible completion. The standard value of this variable has several
|
|
|
298 elements including @code{".o"}, @code{".elc"}, @code{".dvi"} and @code{"~"}.
|
|
|
299 The effect is that, for example, @samp{foo} completes to @samp{foo.c}
|
|
|
300 even though @samp{foo.o} exists as well. If the only possible completions
|
|
|
301 are files that end in ``ignored'' strings, they are not ignored.@refill
|
|
|
302
|
|
|
303 @vindex completion-auto-help
|
|
|
304 If a completion command finds the next character is undetermined, it
|
|
|
305 automatically displays a list of all possible completions. If the variable
|
|
|
306 @code{completion-auto-help} is set to @code{nil}, this does not happen,
|
|
|
307 and you must type @kbd{?} to display the possible completions.
|
|
|
308
|
|
|
309 @vindex minibuffer-confirm-incomplete
|
|
|
310 If the variable @code{minibuffer-confirm-incomplete} is set to @code{t},
|
|
|
311 then in contexts where @code{completing-read} allows answers that are
|
|
|
312 not valid completions, an extra @key{RET} must be typed to confirm the
|
|
|
313 response. This is helpful for catching typos.
|
|
|
314
|
|
|
315 @node Repetition,, Completion, Minibuffer
|
|
|
316 @section Repeating Minibuffer Commands
|
|
|
317 @cindex command history
|
|
|
318 @cindex history of commands
|
|
|
319
|
|
|
320 Every command that uses the minibuffer at least once is recorded on a
|
|
|
321 special history list, together with the values of the minibuffer arguments,
|
|
|
322 so that you can repeat the command easily. In particular, every
|
|
|
323 use of @kbd{Meta-x} is recorded, since @kbd{M-x} uses the minibuffer to
|
|
|
324 read the command name.
|
|
|
325
|
|
|
326 @findex list-command-history
|
|
|
327 @c widecommands
|
|
|
328 @table @kbd
|
|
|
329 @item C-x @key{ESC}
|
|
|
330 Re-execute a recent minibuffer command @*(@code{repeat-complex-command}).
|
|
|
331 @item M-p
|
|
|
332 Within @kbd{C-x @key{ESC}}, move to previous recorded command
|
|
|
333 (@code{previous-history-element}).
|
|
|
334 @item M-n
|
|
|
335 Within @kbd{C-x @key{ESC}}, move to the next (more recent) recorded
|
|
|
336 command (@code{next-history-element}).@refill
|
|
|
337 @item M-x list-command-history
|
|
|
338 Display the entire command history, showing all the commands
|
|
|
339 @kbd{C-x @key{ESC}} can repeat, most recent first.@refill
|
|
|
340 @end table
|
|
|
341
|
|
|
342 @kindex C-x ESC
|
|
|
343 @findex repeat-complex-command
|
|
|
344 @kbd{C-x @key{ESC}} is used to re-execute a recent command that used
|
|
|
345 the minibuffer. With no argument, it repeats the last command. A numeric
|
|
|
346 argument specifies which command to repeat; 1 means the last one, and
|
|
|
347 larger numbers specify earlier commands.
|
|
|
348
|
|
|
349 @kbd{C-x @key{ESC}} works by turning the previous command into a Lisp
|
|
|
350 expression and then entering a minibuffer initialized with the text for
|
|
|
351 that expression. If you type just @key{RET}, the command is repeated as
|
|
|
352 before. You can also change the command by editing the Lisp expression.
|
|
|
353 The expression you finally submit will be executed. The repeated
|
|
|
354 command is added to the front of the command history unless it is
|
|
|
355 identical to the most recently executed command already there.
|
|
|
356
|
|
|
357 Even if you don't understand Lisp syntax, it will probably be obvious
|
|
|
358 which command is displayed for repetition. If you do not change the text,
|
|
|
359 you can be sure the command will repeat exactly as before.
|
|
|
360
|
|
|
361 @kindex M-n
|
|
|
362 @kindex M-p
|
|
|
363 @findex next-complex-command
|
|
|
364 @findex previous-complex-command
|
|
|
365 If you are in the minibuffer for @kbd{C-x @key{ESC}} and the command shown
|
|
|
366 to you is not the one you want to repeat, you can move around the list of
|
|
|
367 previous commands using @kbd{M-n} and @kbd{M-p}. @kbd{M-p} replaces the
|
|
|
368 contents of the minibuffer with the next earlier recorded command, and
|
|
|
369 @kbd{M-n} replaces it with the next later command. After finding the
|
|
|
370 desired previous command, you can edit its expression and then
|
|
|
371 resubmit it by typing @key{RET}. Any editing you have done on the
|
|
|
372 command to be repeated is lost if you use @kbd{M-n} or @kbd{M-p}.
|
|
|
373
|
|
|
374 @kbd{M-n} and @kbd{M-p} are specially defined within @kbd{C-x @key{ESC}}
|
|
|
375 to run the commands @code{previous-history-element} and
|
|
|
376 @code{next-history-element}.
|
|
|
377
|
|
|
378 @vindex command-history
|
|
|
379 The list of previous commands using the minibuffer is stored as a Lisp
|
|
|
380 list in the variable @code{command-history}. Each element of the list
|
|
|
381 is a Lisp expression which describes one command and its arguments.
|
|
|
382 Lisp programs can reexecute a command by feeding the corresponding
|
|
|
383 @code{command-history} element to @code{eval}.
|
