Mercurial > hg > xemacs-beta

comparison man/xemacs/mini.texi @ 0:376386a54a3c r19-14

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import from CVS: tag r19-14
author cvs
date Mon, 13 Aug 2007 08:45:50 +0200
parents
children 74fd4e045ea6
comparison
equal deleted inserted replaced
-1:000000000000 0:376386a54a3c
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}.