Mercurial > hg > xemacs-beta

comparison man/xemacs/mini.texi @ 412:697ef44129c6 r21-2-14

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