1 @node Minibuffer, M-x, Undo, Top
2 @chapter The Minibuffer
5 The @dfn{minibuffer} is the facility used by SXEmacs commands to read
6 arguments more complicated than a single number. Minibuffer arguments
7 can be file names, buffer names, Lisp function names, SXEmacs command
8 names, Lisp expressions, and many other things, depending on the command
9 reading the argument. You can use the usual SXEmacs editing commands in
10 the minibuffer to edit the argument text.
13 When the minibuffer is in use, it appears in the echo area, and the
14 cursor moves there. The beginning of the minibuffer line displays a
15 @dfn{prompt} which says what kind of input you should supply and how it
16 will be used. Often this prompt is derived from the name of the command
17 that the argument is for. The prompt normally ends with a colon.
19 @cindex default argument
20 Sometimes a @dfn{default argument} appears in parentheses after the
21 colon; it, too, is part of the prompt. The default is used as the
22 argument value if you enter an empty argument (e.g., by just typing @key{RET}).
23 For example, commands that read buffer names always show a default, which
24 is the name of the buffer that will be used if you type just @key{RET}.
27 The simplest way to enter a minibuffer argument is to type the text
28 you want, terminated by @key{RET} which exits the minibuffer. You can
29 cancel the command that wants the argument, and get out of the
30 minibuffer, by typing @kbd{C-g}.
32 Since the minibuffer uses the screen space of the echo area, it can
33 conflict with other ways SXEmacs customarily uses the echo area. Here is
34 how SXEmacs handles such conflicts:
38 If a command gets an error while you are in the minibuffer, this does
39 not cancel the minibuffer. However, the echo area is needed for the
40 error message and therefore the minibuffer itself is hidden for a
41 while. It comes back after a few seconds, or as soon as you type
45 If in the minibuffer you use a command whose purpose is to print a
46 message in the echo area, such as @kbd{C-x =}, the message is printed
47 normally, and the minibuffer is hidden for a while. It comes back
48 after a few seconds, or as soon as you type anything.
51 Echoing of keystrokes does not take place while the minibuffer is in
56 * File: Minibuffer File. Entering file names with the minibuffer.
57 * Edit: Minibuffer Edit. How to edit in the minibuffer.
58 * Completion:: An abbreviation facility for minibuffer input.
59 * Minibuffer History:: Reusing recent minibuffer arguments.
60 * Repetition:: Re-executing commands that used the minibuffer.
63 @node Minibuffer File, Minibuffer Edit, Minibuffer, Minibuffer
64 @section Minibuffers for File Names
66 Sometimes the minibuffer starts out with text in it. For example, when
67 you are supposed to give a file name, the minibuffer starts out containing
68 the @dfn{default directory}, which ends with a slash. This is to inform
69 you which directory the file will be found in if you do not specify a
72 For example, the minibuffer might start out with these contents:
75 Find File: /u2/emacs/src/
79 where @samp{Find File:@: } is the prompt. Typing @kbd{buffer.c}
80 specifies the file @file{/u2/emacs/src/buffer.c}. To find files in
81 nearby directories, use @kbd{..}; thus, if you type
82 @kbd{../lisp/simple.el}, you will get the file named
83 @file{/u2/emacs/lisp/simple.el}. Alternatively, you can kill with
84 @kbd{M-@key{DEL}} the directory names you don't want (@pxref{Words}).
86 If you don't want any of the default, you can kill it with @kbd{C-a
87 C-k}. But you don't need to kill the default; you can simply ignore it.
88 Insert an absolute file name, one starting with a slash or a tilde,
89 after the default directory. For example, to specify the file
90 @file{/etc/termcap}, just insert that name, giving these minibuffer
94 Find File: /u2/emacs/src//etc/termcap
98 @cindex // in file name
99 @cindex double slash in file name
100 @cindex slashes repeated in file name
101 SXEmacs gives a special meaning to a double slash (which is not normally
102 a useful thing to write): it means, ``ignore everything before the
103 second slash in the pair.'' Thus, @samp{/u2/emacs/src/} is ignored in
104 the example above, and you get the file @file{/etc/termcap}.
106 @vindex insert-default-directory
107 If you set @code{insert-default-directory} to @code{nil}, the default
108 directory is not inserted in the minibuffer. This way, the minibuffer
109 starts out empty. But the name you type, if relative, is still
110 interpreted with respect to the same default directory.
112 @node Minibuffer Edit, Completion, Minibuffer File, Minibuffer
113 @section Editing in the Minibuffer
115 The minibuffer is an SXEmacs buffer (albeit a peculiar one), and the
116 usual SXEmacs commands are available for editing the text of an argument
119 Since @key{RET} in the minibuffer is defined to exit the minibuffer,
120 you can't use it to insert a newline in the minibuffer. To do that,
121 type @kbd{C-o} or @kbd{C-q C-j}. (Recall that a newline is really the
122 character control-J.)
124 The minibuffer has its own window which always has space on the screen
125 but acts as if it were not there when the minibuffer is not in use.
126 When the minibuffer is in use, its window is just like the others; you
127 can switch to another window with @kbd{C-x o}, edit text in other
128 windows and perhaps even visit more files, before returning to the
129 minibuffer to submit the argument. You can kill text in another window,
130 return to the minibuffer window, and then yank the text to use it in the
131 argument. @xref{Windows}.
133 There are some restrictions on the use of the minibuffer window,
134 however. You cannot switch buffers in it---the minibuffer and its
135 window are permanently attached. Also, you cannot split or kill the
136 minibuffer window. But you can make it taller in the normal fashion with
137 @kbd{C-x ^}. If you enable Resize-Minibuffer mode, then the
138 minibuffer window expands vertically as necessary to hold the text that
139 you put in the minibuffer. Use @kbd{M-x resize-minibuffer-mode} to
140 enable or disable this minor mode (@pxref{Minor Modes}).
143 If while in the minibuffer you issue a command that displays help text
144 of any sort in another window, you can use the @kbd{C-M-v} command while
145 in the minibuffer to scroll the help text. This lasts until you exit
146 the minibuffer. This feature is especially useful if a completing
147 minibuffer gives you a list of possible completions. @xref{Other Window}.
149 @vindex minibuffer-confirm-incomplete
150 If the variable @code{minibuffer-confirm-incomplete} is @code{t}, you
151 are asked for confirmation if there is no known completion for the text
152 you typed. For example, if you attempted to visit a non-existent file,
153 the minibuffer might read:
155 Find File: chocolate_bar.c [no completions, confirm]
157 If you press @kbd{Return} again, that confirms the filename. Otherwise,
158 you can continue editing it.
160 SXEmacs supports recursive use of the minibuffer. However, it is easy
161 to do this by accident (because of autorepeating keyboards, for example)
162 and get confused. Therefore, most SXEmacs commands that use the
163 minibuffer refuse to operate if the minibuffer window is selected. If
164 the minibuffer is active but you have switched to a different window,
165 recursive use of the minibuffer is allowed---if you know enough to try
166 to do this, you probably will not get confused.
168 @vindex enable-recursive-minibuffers
169 If you set the variable @code{enable-recursive-minibuffers} to a
170 non-@code{nil}, recursive use of the minibuffer is always allowed.
172 @node Completion, Minibuffer History, Minibuffer Edit, Minibuffer
176 For certain kinds of arguments, you can use @dfn{completion} to enter
177 the argument value. Completion means that you type part of the
178 argument, then SXEmacs visibly fills in the rest, or as much as
179 can be determined from the part you have typed.
181 When completion is available, certain keys---@key{TAB}, @key{RET}, and
182 @key{SPC}---are rebound to complete the text present in the
183 minibuffer into a longer string that it stands for, by matching it
184 against a set of @dfn{completion alternatives} provided by the command
185 reading the argument. @kbd{?} is defined to display a list of possible
186 completions of what you have inserted.
188 For example, when @kbd{M-x} uses the minibuffer to read the name of a
189 command, it provides a list of all available SXEmacs command names to
190 complete against. The completion keys match the text in the minibuffer
191 against all the command names, find any additional name characters
192 implied by the ones already present in the minibuffer, and add those
193 characters to the ones you have given. This is what makes it possible
194 to type @kbd{M-x inse @key{SPC} b @key{RET}} instead of @kbd{M-x
195 insert-buffer @key{RET}} (for example).
197 Case is normally significant in completion because it is significant
198 in most of the names that you can complete (buffer names, file names and
199 command names). Thus, @samp{fo} does not complete to @samp{Foo}. When
200 you are completing a name in which case does not matter, case may be
201 ignored for completion's sake if specified by program.
203 When a completion list is displayed, the completions will highlight as
204 you move the mouse over them. Clicking the middle mouse button on any
205 highlighted completion will ``select'' it just as if you had typed it in
209 * Example: Completion Example.
210 * Commands: Completion Commands.
211 * Strict Completion::
212 * Options: Completion Options.
215 @node Completion Example, Completion Commands, Completion, Completion
216 @subsection Completion Example
219 @findex minibuffer-complete
220 A concrete example may help here. If you type @kbd{M-x au @key{TAB}},
221 the @key{TAB} looks for alternatives (in this case, command names) that
222 start with @samp{au}. There are several, including
223 @code{auto-fill-mode} and @code{auto-save-mode}---but they are all the
224 same as far as @code{auto}, so the @samp{au} in the minibuffer changes
227 If you type @key{TAB} again immediately, there are multiple
228 possibilities for the very next character---it could be any of
229 @samp{c-}---so no more characters are added; instead, @key{TAB}
230 displays a list of all possible completions in another window.
232 If you go on to type @kbd{-f @key{TAB}}, this @key{TAB} sees
233 @samp{auto-f}. The only command name starting this way is
234 @code{auto-fill-mode}, so completion fills in the rest of that. You now
235 have @samp{auto-fill-mode} in the minibuffer after typing just @kbd{au
236 @key{TAB} f @key{TAB}}. Note that @key{TAB} has this effect because in
237 the minibuffer it is bound to the command @code{minibuffer-complete}
238 when completion is available.
240 @node Completion Commands, Strict Completion, Completion Example, Completion
241 @subsection Completion Commands
243 Here is a list of the completion commands defined in the minibuffer
244 when completion is available.
248 Complete the text in the minibuffer as much as possible
249 (@code{minibuffer-complete}).
251 Complete the minibuffer text, but don't go beyond one word
252 (@code{minibuffer-complete-word}).
254 Submit the text in the minibuffer as the argument, possibly completing
255 first as described below (@code{minibuffer-complete-and-exit}).
257 Print a list of all possible completions of the text in the minibuffer
258 (@code{minibuffer-list-completions}).
260 Select the highlighted text under the mouse as a minibuffer response.
261 When the minibuffer is being used to prompt the user for a completion,
262 any valid completions which are visible on the screen will be highlighted
263 when the mouse moves over them. Clicking @key{button2} will select the
264 highlighted completion and exit the minibuffer.
265 (@code{minibuf-select-highlighted-completion}).
269 @findex minibuffer-complete-word
270 @key{SPC} completes much like @key{TAB}, but never goes beyond the
271 next hyphen or space. If you have @samp{auto-f} in the minibuffer and
272 type @key{SPC}, it finds that the completion is @samp{auto-fill-mode},
273 but it stops completing after @samp{fill-}. This gives
274 @samp{auto-fill-}. Another @key{SPC} at this point completes all the
275 way to @samp{auto-fill-mode}. @key{SPC} in the minibuffer when
276 completion is available runs the command
277 @code{minibuffer-complete-word}.
279 Here are some commands you can use to choose a completion from a
280 window that displays a list of completions:
283 @findex mouse-choose-completion
285 Clicking mouse button 2 on a completion in the list of possible
286 completions chooses that completion (@code{mouse-choose-completion}).
287 You normally use this command while point is in the minibuffer; but you
288 must click in the list of completions, not in the minibuffer itself.
290 @findex switch-to-completions
293 Typing @key{PRIOR} or @kbd{M-v}, while in the minibuffer, selects the
294 window showing the completion list buffer
295 (@code{switch-to-completions}). This paves the way for using the
296 commands below. (Selecting that window in the usual ways has the same
297 effect, but this way is more convenient.)
299 @findex choose-completion
301 Typing @key{RET} @emph{in the completion list buffer} chooses the
302 completion that point is in or next to (@code{choose-completion}). To
303 use this command, you must first switch windows to the window that shows
304 the list of completions.
306 @findex next-list-mode-item
310 Typing the right-arrow key @key{RIGHT}, @key{TAB} or @kbd{C-f} @emph{in
311 the completion list buffer} moves point to the following completion
312 (@code{next-list-mode-item}).
314 @findex previous-list-mode-item
317 Typing the left-arrow key @key{LEFT} or @kbd{C-b} @emph{in the
318 completion list buffer} moves point toward the beginning of the buffer,
319 to the previous completion (@code{previous-list-mode-item}).
322 @node Strict Completion, Completion Options, Completion Commands, Completion
323 @subsection Strict Completion
325 There are three different ways that @key{RET} can work in completing
326 minibuffers, depending on how the argument will be used.
330 @dfn{Strict} completion is used when it is meaningless to give any
331 argument except one of the known alternatives. For example, when
332 @kbd{C-x k} reads the name of a buffer to kill, it is meaningless to
333 give anything but the name of an existing buffer. In strict
334 completion, @key{RET} refuses to exit if the text in the minibuffer
335 does not complete to an exact match.
338 @dfn{Cautious} completion is similar to strict completion, except that
339 @key{RET} exits only if the text was an exact match already, not
340 needing completion. If the text is not an exact match, @key{RET} does
341 not exit, but it does complete the text. If it completes to an exact
342 match, a second @key{RET} will exit.
344 Cautious completion is used for reading file names for files that must
348 @dfn{Permissive} completion is used when any string whatever is
349 meaningful, and the list of completion alternatives is just a guide.
350 For example, when @kbd{C-x C-f} reads the name of a file to visit, any
351 file name is allowed, in case you want to create a file. In
352 permissive completion, @key{RET} takes the text in the minibuffer
353 exactly as given, without completing it.
356 The completion commands display a list of all possible completions in
357 a window whenever there is more than one possibility for the very next
358 character. Also, typing @kbd{?} explicitly requests such a list. If
359 the list of completions is long, you can scroll it with @kbd{C-M-v}
360 (@pxref{Other Window}).
362 @node Completion Options, , Strict Completion, Completion
363 @subsection Completion Options
365 @vindex completion-ignored-extensions
366 When completion is done on file names, certain file names are usually
367 ignored. The variable @code{completion-ignored-extensions} contains a
368 list of strings; a file whose name ends in any of those strings is
369 ignored as a possible completion. The standard value of this variable
370 has several elements including @code{".o"}, @code{".elc"}, @code{".dvi"}
371 and @code{"~"}. The effect is that, for example, @samp{foo} can
372 complete to @samp{foo.c} even though @samp{foo.o} exists as well.
373 However, if @emph{all} the possible completions end in ``ignored''
374 strings, then they are not ignored. Ignored extensions do not apply to
375 lists of completions---those always mention all possible completions.
377 @vindex completion-auto-help
378 If a completion command finds the next character is undetermined, it
379 automatically displays a list of all possible completions. If the variable
380 @code{completion-auto-help} is set to @code{nil}, this does not happen,
381 and you must type @kbd{?} to display the possible completions.
383 @vindex minibuffer-confirm-incomplete
384 If the variable @code{minibuffer-confirm-incomplete} is set to @code{t},
385 then in contexts where @code{completing-read} allows answers that are
386 not valid completions, an extra @key{RET} must be typed to confirm the
387 response. This is helpful for catching typos.
389 @cindex Icomplete mode
390 Icomplete mode presents a constantly-updated display that tells you
391 what completions are available for the text you've entered so far. The
392 command to enable or disable this minor mode is @kbd{M-x
395 @node Minibuffer History, Repetition, Completion, Minibuffer
396 @section Minibuffer History
397 @cindex minibuffer history
398 @cindex history of minibuffer input
400 Every argument that you enter with the minibuffer is saved on a
401 @dfn{minibuffer history list} so that you can use it again later in
402 another argument. Special commands load the text of an earlier argument
403 in the minibuffer. They discard the old minibuffer contents, so you can
404 think of them as moving through the history of previous arguments.
409 Move to the next earlier argument string saved in the minibuffer history
410 (@code{previous-history-element}).
413 Move to the next later argument string saved in the minibuffer history
414 (@code{next-history-element}).
415 @item M-r @var{regexp} @key{RET}
416 Move to an earlier saved argument in the minibuffer history that has a
417 match for @var{regexp} (@code{previous-matching-history-element}).
418 @item M-s @var{regexp} @key{RET}
419 Move to a later saved argument in the minibuffer history that has a
420 match for @var{regexp} (@code{next-matching-history-element}).
423 @kindex M-p @r{(minibuffer history)}
424 @kindex M-n @r{(minibuffer history)}
425 @findex next-history-element
426 @findex previous-history-element
427 The simplest way to reuse the saved arguments in the history list is
428 to move through the history list one element at a time. While in the
429 minibuffer, use @kbd{M-p} or up-arrow (@code{previous-history-element})
430 to ``move to'' the next earlier minibuffer input, and use @kbd{M-n} or
431 down-arrow (@code{next-history-element}) to ``move to'' the next later
434 The previous input that you fetch from the history entirely replaces
435 the contents of the minibuffer. To use it as the argument, exit the
436 minibuffer as usual with @key{RET}. You can also edit the text before
437 you reuse it; this does not change the history element that you
438 ``moved'' to, but your new argument does go at the end of the history
439 list in its own right.
441 For many minibuffer arguments there is a ``default'' value. In some
442 cases, the minibuffer history commands know the default value. Then you
443 can insert the default value into the minibuffer as text by using
444 @kbd{M-n} to move ``into the future'' in the history.
446 @findex previous-matching-history-element
447 @findex next-matching-history-element
448 @kindex M-r @r{(minibuffer history)}
449 @kindex M-s @r{(minibuffer history)}
450 There are also commands to search forward or backward through the
451 history; they search for history elements that match a regular
452 expression that you specify with the minibuffer. @kbd{M-r}
453 (@code{previous-matching-history-element}) searches older elements in
454 the history, while @kbd{M-s} (@code{next-matching-history-element})
455 searches newer elements. By special dispensation, these commands can
456 use the minibuffer to read their arguments even though you are already
457 in the minibuffer when you issue them. As with incremental searching,
458 an uppercase letter in the regular expression makes the search
459 case-sensitive (@pxref{Search Case}).
461 All uses of the minibuffer record your input on a history list, but
462 there are separate history lists for different kinds of arguments. For
463 example, there is a list for file names, used by all the commands that
466 There are several other very specific history lists, including one for
467 command names read by @kbd{M-x}, one for buffer names, one for arguments
468 of commands like @code{query-replace}, and one for compilation commands
469 read by @code{compile}. Finally, there is one ``miscellaneous'' history
470 list that most minibuffer arguments use.
474 @vindex history-length
475 The variable @code{history-length} specifies the maximum length of a
476 minibuffer history list; once a list gets that long, the oldest element
477 is deleted each time an element is added. If the value of
478 @code{history-length} is @code{t}, though, there is no maximum length
479 and elements are never deleted.
482 @node Repetition, , Minibuffer History, Minibuffer
483 @section Repeating Minibuffer Commands
484 @cindex command history
485 @cindex history of commands
487 Every command that uses the minibuffer at least once is recorded on a
488 special history list, together with the values of its arguments, so that
489 you can repeat the entire command. In particular, every use of
490 @kbd{M-x} is recorded there, since @kbd{M-x} uses the minibuffer to read
493 @findex list-command-history
496 @item C-x @key{ESC} @key{ESC}
497 Re-execute a recent minibuffer command (@code{repeat-complex-command}).
499 Within @kbd{C-x @key{ESC} @key{ESC}}, move to previous recorded command
500 (@code{previous-history-element}).
502 Within @kbd{C-x @key{ESC} @key{ESC}}, move to the next (more recent)
503 recorded command (@code{next-history-element}).
504 @item M-x list-command-history
505 Display the entire command history, showing all the commands
506 @kbd{C-x @key{ESC} @key{ESC}} can repeat, most recent first.
510 @findex repeat-complex-command
511 @kbd{C-x @key{ESC} @key{ESC}} is used to re-execute a recent
512 minibuffer-using command. With no argument, it repeats the last such
513 command. A numeric argument specifies which command to repeat; one
514 means the last one, and larger numbers specify earlier ones.
516 @kbd{C-x @key{ESC} @key{ESC}} works by turning the previous command
517 into a Lisp expression and then entering a minibuffer initialized with
518 the text for that expression. If you type just @key{RET}, the command
519 is repeated as before. You can also change the command by editing the
520 Lisp expression. Whatever expression you finally submit is what will be
521 executed. The repeated command is added to the front of the command
522 history unless it is identical to the most recently executed command
525 Even if you don't understand Lisp syntax, it will probably be obvious
526 which command is displayed for repetition. If you do not change the text,
527 you can be sure the command will repeat exactly as before.
531 @findex next-complex-command
532 @findex previous-complex-command
533 If you are in the minibuffer for @kbd{C-x @key{ESC} @key{ESC}} and the
534 command shown to you is not the one you want to repeat, you can move
535 around the list of previous commands using @kbd{M-n} and @kbd{M-p}.
536 @kbd{M-p} replaces the contents of the minibuffer with the next earlier
537 recorded command, and @kbd{M-n} replaces it with the next later command.
538 After finding the desired previous command, you can edit its expression
539 and then resubmit it by typing @key{RET}. Any editing you have done on
540 the command to be repeated is lost if you use @kbd{M-n} or @kbd{M-p}.
542 @kbd{M-n} and @kbd{M-p} are specially defined within @kbd{C-x @key{ESC}
543 @key{ESC}} to run the commands @code{previous-history-element} and
544 @code{next-history-element}.
546 @vindex command-history
547 The list of previous commands using the minibuffer is stored as a Lisp
548 list in the variable @code{command-history}. Each element of the list
549 is a Lisp expression which describes one command and its arguments.
550 Lisp programs can reexecute a command by feeding the corresponding
551 @code{command-history} element to @code{eval}.