Mercurial > vim
comparison runtime/doc/cmdline.txt @ 7:3fc0f57ecb91 v7.0001
updated for version 7.0001
author | vimboss |
---|---|
date | Sun, 13 Jun 2004 20:20:40 +0000 |
parents | |
children | bdeee1504ac1 |
comparison
equal
deleted
inserted
replaced
6:c2daee826b8f | 7:3fc0f57ecb91 |
---|---|
1 *cmdline.txt* For Vim version 7.0aa. Last change: 2004 Mar 31 | |
2 | |
3 | |
4 VIM REFERENCE MANUAL by Bram Moolenaar | |
5 | |
6 | |
7 *Cmdline-mode* *Command-line-mode* | |
8 Command-line mode *Cmdline* *Command-line* *mode-cmdline* *:* | |
9 | |
10 Command-line mode is used to enter Ex commands (":"), search patterns | |
11 ("/" and "?"), and filter commands ("!"). | |
12 | |
13 Basic command line editing is explained in chapter 20 of the user manual | |
14 |usr_20.txt|. | |
15 | |
16 1. Command-line editing |cmdline-editing| | |
17 2. Command-line completion |cmdline-completion| | |
18 3. Ex command-lines |cmdline-lines| | |
19 4. Ex command-line ranges |cmdline-ranges| | |
20 5. Ex special characters |cmdline-special| | |
21 6. Command-line window |cmdline-window| | |
22 | |
23 ============================================================================== | |
24 1. Command-line editing *cmdline-editing* | |
25 | |
26 Normally characters are inserted in front of the cursor position. You can | |
27 move around in the command-line with the left and right cursor keys. With the | |
28 <Insert> key, you can toggle between inserting and overstriking characters. | |
29 {Vi: can only alter the last character in the line} | |
30 | |
31 Note that if your keyboard does not have working cursor keys or any of the | |
32 other special keys, you can use ":cnoremap" to define another key for them. | |
33 For example, to define tcsh style editing keys: *tcsh-style* > | |
34 :cnoremap <C-A> <Home> | |
35 :cnoremap <C-F> <Right> | |
36 :cnoremap <C-B> <Left> | |
37 :cnoremap <Esc>b <S-Left> | |
38 :cnoremap <Esc>f <S-Right> | |
39 (<> notation |<>|; type all this literally) | |
40 | |
41 *cmdline-too-long* | |
42 When the command line is getting longer than what fits on the screen, only the | |
43 part that fits will be shown. The cursor can only move in this visible part, | |
44 thus you cannot edit beyond that. | |
45 | |
46 *cmdline-history* *history* | |
47 The command-lines that you enter are remembered in a history table. You can | |
48 recall them with the up and down cursor keys. There are actually four | |
49 history tables: | |
50 - one for ':' commands | |
51 - one for search strings | |
52 - one for expressions | |
53 - one for input lines, typed for the |input()| function. | |
54 These are completely separate. Each history can only be accessed when | |
55 entering the same type of line. | |
56 Use the 'history' option to set the number of lines that are remembered | |
57 (default: 20). | |
58 Notes: | |
59 - When you enter a command-line that is exactly the same as an older one, the | |
60 old one is removed (to avoid repeated commands moving older commands out of | |
61 the history). | |
62 - Only commands that are typed are remembered. Ones that completely come from | |
63 mappings are not put in the history | |
64 - All searches are put in the search history, including the ones that come | |
65 from commands like "*" and "#". But for a mapping, only the last search is | |
66 remembered (to avoid that long mappings trash the history). | |
67 {Vi: no history} | |
68 {not available when compiled without the |+cmdline_hist| feature} | |
69 | |
70 There is an automatic completion of names on the command-line; see | |
71 |cmdline-completion|. | |
72 | |
73 *c_CTRL-V* | |
74 CTRL-V Insert next non-digit literally. Up to three digits form the | |
75 decimal value of a single byte. The non-digit and the three | |
76 digits are not considered for mapping. This works the same | |
77 way as in Insert mode (see above, |i_CTRL-V|). | |
78 Note: Under Windows CTRL-V is often mapped to paste text. | |
79 Use CTRL-Q instead then. | |
80 *c_CTRL-Q* | |
81 CTRL-Q Same as CTRL-V. But with some terminals it is used for | |
82 control flow, it doesn't work then. | |
83 | |
84 *c_<Left>* | |
85 <Left> cursor left | |
86 *c_<Right>* | |
87 <Right> cursor right | |
88 *c_<S-Left>* | |
89 <S-Left> or <C-Left> *c_<C-Left>* | |
90 cursor one WORD left | |
91 *c_<S-Right>* | |
92 <S-Right> or <C-Right> *c_<C-Right>* | |
93 cursor one WORD right | |
94 CTRL-B or <Home> *c_CTRL-B* *c_<Home>* | |
95 cursor to beginning of command-line | |
96 CTRL-E or <End> *c_CTRL-E* *c_<End>* | |
97 cursor to end of command-line | |
98 | |
99 *c_<LeftMouse>* | |
100 <LeftMouse> cursor to position of mouse click. | |
101 | |
102 CTRL-H *c_<BS>* *c_CTRL-H* | |
103 <BS> delete the character in front of the cursor (see |:fixdel| if | |
104 your <BS> key does not do what you want). | |
105 *c_<Del>* | |
106 <Del> delete the character under the cursor (at end of line: | |
107 character before the cursor) (see |:fixdel| if your <Del> | |
108 key does not do what you want). | |
109 *c_CTRL-W* | |
110 CTRL-W delete the word before the cursor | |
111 *c_CTRL-U* | |
112 CTRL-U remove all characters between the cursor position and | |
113 the beginning of the line. Previous versions of vim | |
114 deleted all characters on the line. If that is the | |
115 preferred behavior, add the following to your .vimrc: > | |
116 :cnoremap <C-U> <C-E><C-U> | |
117 < | |
118 Note: if the command-line becomes empty with one of the | |
119 delete commands, Command-line mode is quit. | |
120 *c_<Insert>* | |
121 <Insert> Toggle between insert and overstrike. {not in Vi} | |
122 | |
123 {char1} <BS> {char2} or *c_digraph* | |
124 CTRL-K {char1} {char2} *c_CTRL-K* | |
125 enter digraph (see |digraphs|). When {char1} is a special | |
126 key, the code for that key is inserted in <> form. {not in Vi} | |
127 | |
128 CTRL-R {0-9a-z"%#:-=.} *c_CTRL-R* *c_<C-R>* | |
129 Insert the contents of a numbered or named register. Between | |
130 typing CTRL-R and the second character '"' will be displayed | |
131 to indicate that you are expected to enter the name of a | |
132 register. | |
133 The text is inserted as if you typed it, but mappings and | |
134 abbreviations are not used. Command-line completion through | |
135 'wildchar' is not triggered though. And characters that end | |
136 the command line are inserted literally (<Esc>, <CR>, <NL>, | |
137 <C-C>). A <BS> or CTRL-W could still end the command line | |
138 though, and remaining characters will then be interpreted in | |
139 another mode, which might not be what you intended. | |
140 Special registers: | |
141 '"' the unnamed register, containing the text of | |
142 the last delete or yank | |
143 '%' the current file name | |
144 '#' the alternate file name | |
145 '*' the clipboard contents (X11: primary selection) | |
146 '+' the clipboard contents | |
147 '/' the last search pattern | |
148 ':' the last command-line | |
149 '-' the last small (less than a line) delete | |
150 '.' the last inserted text | |
151 *c_CTRL-R_=* | |
152 '=' the expression register: you are prompted to | |
153 enter an expression (see |expression|) | |
154 See |registers| about registers. {not in Vi} | |
155 | |
156 CTRL-R CTRL-F *c_CTRL-R_CTRL-F* *c_<C-R>_<C-F>* | |
157 CTRL-R CTRL-P *c_CTRL-R_CTRL-P* *c_<C-R>_<C-P>* | |
158 CTRL-R CTRL-W *c_CTRL-R_CTRL-W* *c_<C-R>_<C-W>* | |
159 CTRL-R CTRL-A *c_CTRL-R_CTRL-A* *c_<C-R>_<C-A>* | |
160 Insert the object under the cursor: | |
161 CTRL-F the Filename under the cursor | |
162 CTRL-P the Filename under the cursor, expanded with | |
163 'path' as in |gf| | |
164 CTRL-W the Word under the cursor | |
165 CTRL-A the WORD under the cursor; see |WORD| | |
166 {not in Vi} | |
167 CTRL-F and CTRL-P: {only when +file_in_path feature is | |
168 included} | |
169 | |
170 *c_CTRL-R_CTRL-R* *c_<C-R>_<C-R>* | |
171 *c_CTRL-R_CTRL-O* *c_<C-R>_<C-O>* | |
172 CTRL-R CTRL-R {0-9a-z"%#:-=. CTRL-F CTRL-P CTRL-W CTRL-A} | |
173 CTRL-R CTRL-O {0-9a-z"%#:-=. CTRL-F CTRL-P CTRL-W CTRL-A} | |
174 Insert register or object under the cursor. Works like | |
175 |c_CTRL-R| but inserts the text literally. For example, if | |
176 register a contains "xy^Hz" (where ^H is a backspace), | |
177 "CTRL-R a" will insert "xz" while "CTRL-R CTRL-R a" will | |
178 insert "xy^Hz". | |
179 | |
180 CTRL-\ e {expr} *c_CTRL-\_e* | |
181 Evaluate {expr} and replace the whole command line with the | |
182 result. You will be prompted for the expression, type <Enter> | |
183 to finish it. It's most useful in mappings though. See | |
184 |expression|. | |
185 See |c_CTRL-R_=| for inserting the result of an expression. | |
186 Useful functions are |getcmdline()| and |getcmdpos()|. | |
187 The cursor position is unchanged, except when the cursor was | |
188 at the end of the line, then it stays at the end. | |
189 |setcmdpos()| can be used to set the cursor position. | |
190 Example: > | |
191 :cmap <F7> <C-\>eAppendSome()<CR> | |
192 :func AppendSome() | |
193 :let cmd = getcmdline() . " Some()" | |
194 :" place the cursor on the ) | |
195 :call setcmdpos(strlen(cmd)) | |
196 :return cmd | |
197 :endfunc | |
198 < | |
199 *c_CTRL-Y* | |
200 CTRL-Y When there is a modeless selection, copy the selection into | |
201 the clipboard. |modeless-selection| | |
202 If there is no selection CTRL-Y is inserted as a character. | |
203 | |
204 CTRL-J *c_CTRL-J* *c_<NL>* *c_<CR>* | |
205 <CR> or <NL> start entered command | |
206 *c_<Esc>* | |
207 <Esc> When typed and 'x' not present in 'cpoptions', quit | |
208 Command-line mode without executing. In macros or when 'x' | |
209 present in 'cpoptions', start entered command. | |
210 *c_CTRL-C* | |
211 CTRL-C quit command-line without executing | |
212 | |
213 *c_<Up>* | |
214 <Up> recall older command-line from history, whose beginning | |
215 matches the current command-line (see below). | |
216 {not available when compiled without the |+cmdline_hist| | |
217 feature} | |
218 *c_<Down>* | |
219 <Down> recall more recent command-line from history, whose beginning | |
220 matches the current command-line (see below). | |
221 {not available when compiled without the |+cmdline_hist| | |
222 feature} | |
223 | |
224 *c_<S-Up>* *c_<PageUp>* | |
225 <S-Up> or <PageUp> | |
226 recall older command-line from history | |
227 {not available when compiled without the |+cmdline_hist| | |
228 feature} | |
229 *c_<S-Down>* *c_<PageDown>* | |
230 <S-Down> or <PageDown> | |
231 recall more recent command-line from history | |
232 {not available when compiled without the |+cmdline_hist| | |
233 feature} | |
234 | |
235 CTRL-D command-line completion (see |cmdline-completion|) | |
236 'wildchar' option | |
237 command-line completion (see |cmdline-completion|) | |
238 CTRL-N command-line completion (see |cmdline-completion|) | |
239 CTRL-P command-line completion (see |cmdline-completion|) | |
240 CTRL-A command-line completion (see |cmdline-completion|) | |
241 CTRL-L command-line completion (see |cmdline-completion|) | |
242 | |
243 *c_CTRL-_* | |
244 CTRL-_ a - switch between Hebrew and English keyboard mode, which is | |
245 private to the command-line and not related to hkmap. | |
246 This is useful when Hebrew text entry is required in the | |
247 command-line, searches, abbreviations, etc. Applies only if | |
248 Vim is compiled with the |+rightleft| feature and the | |
249 'allowrevins' option is set. | |
250 See |rileft.txt|. | |
251 | |
252 b - switch between Farsi and English keyboard mode, which is | |
253 private to the command-line and not related to fkmap. In | |
254 Farsi keyboard mode the characters are inserted in reverse | |
255 insert manner. This is useful when Farsi text entry is | |
256 required in the command-line, searches, abbreviations, etc. | |
257 Applies only if Vim is compiled with the |+farsi| feature. | |
258 See |farsi.txt|. | |
259 | |
260 *c_CTRL-^* | |
261 CTRL-^ Toggle the use of language |:lmap| mappings and/or Input | |
262 Method. | |
263 When typing a pattern for a search command and 'imsearch' is | |
264 not -1, VAL is the value of 'imsearch', otherwise VAL is the | |
265 value of 'iminsert'. | |
266 When language mappings are defined: | |
267 - If VAL is 1 (langmap mappings used) it becomes 0 (no langmap | |
268 mappings used). | |
269 - If VAL was not 1 it becomes 1, thus langmap mappings are | |
270 enabled. | |
271 When no language mappings are defined: | |
272 - If VAL is 2 (Input Method is used) it becomes 0 (no input | |
273 method used) | |
274 - If VAL has another value it becomes 2, thus the Input Method | |
275 is enabled. | |
276 These language mappings are normally used to type characters | |
277 that are different from what the keyboard produces. The | |
278 'keymap' option can be used to install a whole number of them. | |
279 When entering a command line, langmap mappings are switched | |
280 off, since you are expected to type a command. After | |
281 switching it on with CTRL-^, the new state is not used again | |
282 for the next command or Search pattern. | |
283 {not in Vi} | |
284 | |
285 For Emacs-style editing on the command-line see |emacs-keys|. | |
286 | |
287 The <Up> and <Down> keys take the current command-line as a search string. | |
288 The beginning of the next/previous command-lines are compared with this | |
289 string. The first line that matches is the new command-line. When typing | |
290 these two keys repeatedly, the same string is used again. For example, this | |
291 can be used to find the previous substitute command: Type ":s" and then <Up>. | |
292 The same could be done by typing <S-Up> a number of times until the desired | |
293 command-line is shown. (Note: the shifted arrow keys do not work on all | |
294 terminals) | |
295 | |
296 *his* *:history* | |
297 :his[tory] Print the history of last entered commands. | |
298 {not in Vi} | |
299 {not available when compiled without the |+cmdline_hist| | |
300 feature} | |
301 | |
302 :his[tory] [{name}] [{first}][, [{last}]] | |
303 List the contents of history {name} which can be: | |
304 c[md] or : command-line history | |
305 s[earch] or / search string history | |
306 e[xpr] or = expression register history | |
307 i[nput] or @ input line history | |
308 a[ll] all of the above | |
309 {not in Vi} | |
310 | |
311 If the numbers {first} and/or {last} are given, the respective | |
312 range of entries from a history is listed. These numbers can | |
313 be specified in the following form: | |
314 *:history-indexing* | |
315 A positive number represents the absolute index of an entry | |
316 as it is given in the first column of a :history listing. | |
317 This number remains fixed even if other entries are deleted. | |
318 | |
319 A negative number means the relative position of an entry, | |
320 counted from the newest entry (which has index -1) backwards. | |
321 | |
322 Examples: | |
323 List entries 6 to 12 from the search history: > | |
324 :history / 6,12 | |
325 < | |
326 List the recent five entries from all histories: > | |
327 :history all -5, | |
328 | |
329 ============================================================================== | |
330 2. Command-line completion *cmdline-completion* | |
331 | |
332 When editing the command-line, a few commands can be used to complete the | |
333 word before the cursor. This is available for: | |
334 | |
335 - Command names: At the start of the command-line. | |
336 - Tags: Only after the ":tag" command. | |
337 - File names: Only after a command that accepts a file name or a setting for | |
338 an option that can be set to a file name. This is called file name | |
339 completion. | |
340 - Options: Only after the ":set" command. | |
341 - Mappings: Only after a ":map" or similar command. | |
342 - Variable and function names: Only after a ":if", ":call" or similar command. | |
343 | |
344 When Vim was compiled with the |+cmdline_compl| feature disabled, only file | |
345 names, directories and help items can be completed. | |
346 | |
347 These are the commands that can be used: | |
348 | |
349 *c_CTRL-D* | |
350 CTRL-D List names that match the pattern in front of the cursor. | |
351 When showing file names, directories are highlighted (see | |
352 'highlight' option). Names where 'suffixes' matches are moved | |
353 to the end. | |
354 *c_CTRL-I* *c_wildchar* *c_<Tab>* | |
355 'wildchar' option | |
356 A match is done on the pattern in front of the cursor. The | |
357 match (if there are several, the first match) is inserted | |
358 in place of the pattern. (Note: does not work inside a | |
359 macro, because <Tab> or <Esc> are mostly used as 'wildchar', | |
360 and these have a special meaning in some macros.) When typed | |
361 again and there were multiple matches, the next | |
362 match is inserted. After the last match, the first is used | |
363 again (wrap around). | |
364 The behavior can be changed with the 'wildmode' option. | |
365 *c_CTRL-N* | |
366 CTRL-N After using 'wildchar' which got multiple matches, go to next | |
367 match. Otherwise recall more recent command-line from history. | |
368 <S-Tab> *c_CTRL-P* *c_<S-Tab>* | |
369 CTRL-P After using 'wildchar' which got multiple matches, go to | |
370 previous match. Otherwise recall older command-line from | |
371 history. <S-Tab> only works with the GUI, on the Amiga and | |
372 with MS-DOS. | |
373 *c_CTRL-A* | |
374 CTRL-A All names that match the pattern in front of the cursor are | |
375 inserted. | |
376 *c_CTRL-L* | |
377 CTRL-L A match is done on the pattern in front of the cursor. If | |
378 there is one match, it is inserted in place of the pattern. | |
379 If there are multiple matches the longest common part is | |
380 inserted in place of the pattern. If the result is shorter | |
381 than the pattern, no completion is done. | |
382 | |
383 The 'wildchar' option defaults to <Tab> (CTRL-E when in Vi compatible mode; in | |
384 a previous version <Esc> was used). In the pattern standard wildcards '*' and | |
385 '?' are accepted. '*' matches any string, '?' matches exactly one character. | |
386 | |
387 If you like tcsh's autolist completion, you can use this mapping: | |
388 :cnoremap X <C-L><C-D> | |
389 (Where X is the command key to use, <C-L> is CTRL-L and <C-D> is CTRL-D) | |
390 This will find the longest match and then list all matching files. | |
391 | |
392 If you like tcsh's autolist completion, you can use the 'wildmode' option to | |
393 emulate it. For example, this mimics autolist=ambiguous: | |
394 :set wildmode=longest,list | |
395 This will find the longest match with the first 'wildchar', then list all | |
396 matching files with the next. | |
397 | |
398 *suffixes* | |
399 For file name completion you can use the 'suffixes' option to set a priority | |
400 between files with almost the same name. If there are multiple matches, | |
401 those files with an extension that is in the 'suffixes' option are ignored. | |
402 The default is ".bak,~,.o,.h,.info,.swp,.obj", which means that files ending | |
403 in ".bak", "~", ".o", ".h", ".info", ".swp" and ".obj" are sometimes ignored. | |
404 It is impossible to ignore suffixes with two dots. Examples: | |
405 | |
406 pattern: files: match: ~ | |
407 test* test.c test.h test.o test.c | |
408 test* test.h test.o test.h and test.o | |
409 test* test.i test.h test.c test.i and test.c | |
410 | |
411 If there is more than one matching file (after ignoring the ones matching | |
412 the 'suffixes' option) the first file name is inserted. You can see that | |
413 there is only one match when you type 'wildchar' twice and the completed | |
414 match stays the same. You can get to the other matches by entering | |
415 'wildchar', CTRL-N or CTRL-P. All files are included, also the ones with | |
416 extensions matching the 'suffixes' option. | |
417 | |
418 To completely ignore files with some extension use 'wildignore'. | |
419 | |
420 The old value of an option can be obtained by hitting 'wildchar' just after | |
421 the '='. For example, typing 'wildchar' after ":set dir=" will insert the | |
422 current value of 'dir'. This overrules file name completion for the options | |
423 that take a file name. | |
424 | |
425 If you would like using <S-Tab> for CTRL-P in an xterm, put this command in | |
426 your .cshrc: > | |
427 xmodmap -e "keysym Tab = Tab Find" | |
428 And this in your .vimrc: > | |
429 :cmap <Esc>[1~ <C-P> | |
430 | |
431 ============================================================================== | |
432 3. Ex command-lines *cmdline-lines* | |
433 | |
434 The Ex commands have a few specialties: | |
435 | |
436 *:quote* | |
437 '"' at the start of a line causes the whole line to be ignored. '"' | |
438 after a command causes the rest of the line to be ignored. This can be used | |
439 to add comments. Example: > | |
440 :set ai "set 'autoindent' option | |
441 It is not possible to add a comment to a shell command ":!cmd" or to the | |
442 ":map" command and friends, because they see the '"' as part of their | |
443 argument. | |
444 | |
445 *:bar* *:\bar* | |
446 '|' can be used to separate commands, so you can give multiple commands in one | |
447 line. If you want to use '|' in an argument, precede it with '\'. | |
448 | |
449 These commands see the '|' as their argument, and can therefore not be | |
450 followed by another command: | |
451 :argdo | |
452 :autocmd | |
453 :bufdo | |
454 :command | |
455 :cscope | |
456 :debug | |
457 :folddoopen | |
458 :folddoclosed | |
459 :function | |
460 :global | |
461 :help | |
462 :helpfind | |
463 :make | |
464 :normal | |
465 :perl | |
466 :perldo | |
467 :promptfind | |
468 :promptrepl | |
469 :pyfile | |
470 :python | |
471 :registers | |
472 :read ! | |
473 :scscope | |
474 :tcl | |
475 :tcldo | |
476 :tclfile | |
477 :vglobal | |
478 :windo | |
479 :write ! | |
480 :[range]! | |
481 a user defined command without the "-bar" argument |:command| | |
482 | |
483 Note that this is confusing (inherited from Vi): With ":g" the '|' is included | |
484 in the command, with ":s" it is not. | |
485 | |
486 To be able to use another command anyway, use the ":execute" command. | |
487 Example (append the output of "ls" and jump to the first line): > | |
488 :execute 'r !ls' | '[ | |
489 | |
490 There is one exception: When the 'b' flag is present in 'cpoptions', with the | |
491 ":map" and ":abbr" commands and friends CTRL-V needs to be used instead of | |
492 '\'. You can also use "<Bar>" instead. See also |map_bar|. | |
493 | |
494 Examples: > | |
495 :!ls | wc view the output of two commands | |
496 :r !ls | wc insert the same output in the text | |
497 :%g/foo/p|> moves all matching lines one shiftwidth | |
498 :%s/foo/bar/|> moves one line one shiftwidth | |
499 :map q 10^V| map "q" to "10|" | |
500 :map q 10\| map \ l map "q" to "10\" and map "\" to "l" | |
501 (when 'b' is present in 'cpoptions') | |
502 | |
503 You can also use <NL> to separate commands in the same way as with '|'. To | |
504 insert a <NL> use CTRL-V CTRL-J. "^@" will be shown. Using '|' is the | |
505 preferred method. But for external commands a <NL> must be used, because a | |
506 '|' is included in the external command. To avoid the special meaning of <NL> | |
507 it must be preceded with a backslash. Example: > | |
508 :r !date<NL>-join | |
509 This reads the current date into the file and joins it with the previous line. | |
510 | |
511 Note that when the command before the '|' generates an error, the following | |
512 commands will not be executed. | |
513 | |
514 | |
515 Because of Vi compatibility the following strange commands are supported: > | |
516 :| print current line (like ":p") | |
517 :3| print line 3 (like ":3p") | |
518 :3 goto line 3 | |
519 | |
520 A colon is allowed between the range and the command name. It is ignored | |
521 (this is Vi compatible). For example: > | |
522 :1,$:s/pat/string | |
523 | |
524 When the character '%' or '#' is used where a file name is expected, they are | |
525 expanded to the current and alternate file name (see the chapter "editing | |
526 files" |:_%| |:_#|). | |
527 | |
528 Embedded spaces in file names are allowed on the Amiga if one file name is | |
529 expected as argument. Trailing spaces will be ignored, unless escaped with a | |
530 backslash or CTRL-V. Note that the ":next" command uses spaces to separate | |
531 file names. Escape the spaces to include them in a file name. Example: > | |
532 :next foo\ bar goes\ to school\ | |
533 starts editing the three files "foo bar", "goes to" and "school ". | |
534 | |
535 When you want to use the special characters '"' or '|' in a command, or want | |
536 to use '%' or '#' in a file name, precede them with a backslash. The | |
537 backslash is not required in a range and in the ":substitute" command. | |
538 | |
539 *:_!* | |
540 The '!' (bang) character after an Ex command makes the command behave in a | |
541 different way. The '!' should be placed immediately after the command, without | |
542 any blanks in between. If you insert blanks the '!' will be seen as an | |
543 argument for the command, which has a different meaning. For example: | |
544 :w! name write the current buffer to file "name", overwriting | |
545 any existing file | |
546 :w !name send the current buffer as standard input to command | |
547 "name" | |
548 | |
549 ============================================================================== | |
550 4. Ex command-line ranges *cmdline-ranges* *[range]* *E16* *E493* | |
551 | |
552 Some Ex commands accept a line range in front of them. This is noted as | |
553 [range]. It consists of one or more line specifiers, separated with ',' or | |
554 ';'. | |
555 | |
556 The basics are explained in section |10.3| of the user manual. | |
557 | |
558 *:,* *:;* | |
559 When separated with ';' the cursor position will be set to that line | |
560 before interpreting the next line specifier. This doesn't happen for ','. | |
561 Examples: > | |
562 4,/this line/ | |
563 < from line 4 till match with "this line" after the cursor line. > | |
564 5;/that line/ | |
565 < from line 5 till match with "that line" after line 5. | |
566 | |
567 The default line specifier for most commands is the cursor position, but the | |
568 commands ":write" and ":global" have the whole file (1,$) as default. | |
569 | |
570 If more line specifiers are given than required for the command, the first | |
571 one(s) will be ignored. | |
572 | |
573 Line numbers may be specified with: *:range* *E14* *{address}* | |
574 {number} an absolute line number | |
575 . the current line *:.* | |
576 $ the last line in the file *:$* | |
577 % equal to 1,$ (the entire file) *:%* | |
578 't position of mark t (lowercase) *:'* | |
579 'T position of mark T (uppercase); when the mark is in | |
580 another file it cannot be used in a range | |
581 /{pattern}[/] the next line where {pattern} matches *:/* | |
582 ?{pattern}[?] the previous line where {pattern} matches *:?* | |
583 \/ the next line where the previously used search | |
584 pattern matches | |
585 \? the previous line where the previously used search | |
586 pattern matches | |
587 \& the next line where the previously used substitute | |
588 pattern matches | |
589 | |
590 Each may be followed (several times) by '+' or '-' and an optional number. | |
591 This number is added or subtracted from the preceding line number. If the | |
592 number is omitted, 1 is used. | |
593 | |
594 The "/" and "?" after {pattern} are required to separate the pattern from | |
595 anything that follows. | |
596 | |
597 The "/" and "?" may be preceded with another address. The search starts from | |
598 there. The difference from using ';' is that the cursor isn't moved. | |
599 Examples: > | |
600 /pat1//pat2/ Find line containing "pat2" after line containing | |
601 "pat1", without moving the cursor. | |
602 7;/pat2/ Find line containing "pat2", after line 7, leaving | |
603 the cursor in line 7. | |
604 | |
605 The {number} must be between 0 and the number of lines in the file. When | |
606 using a 0 (zero) this is interpreted as a 1 by most commands. Commands that | |
607 use it as a count do use it as a zero (|:tag|, |:pop|, etc). Some commands | |
608 interpret the zero as "before the first line" (|:read|, search pattern, etc). | |
609 | |
610 Examples: > | |
611 .+3 three lines below the cursor | |
612 /that/+1 the line below the next line containing "that" | |
613 .,$ from current line until end of file | |
614 0;/that the first line containing "that", also matches in the | |
615 first line. | |
616 1;/that the first line after line 1 containing "that" | |
617 | |
618 Some commands allow for a count after the command. This count is used as the | |
619 number of lines to be used, starting with the line given in the last line | |
620 specifier (the default is the cursor line). The commands that accept a count | |
621 are the ones that use a range but do not have a file name argument (because | |
622 a file name can also be a number). | |
623 | |
624 Examples: > | |
625 :s/x/X/g 5 substitute 'x' by 'X' in the current line and four | |
626 following lines | |
627 :23d 4 delete lines 23, 24, 25 and 26 | |
628 | |
629 | |
630 Folds and Range | |
631 | |
632 When folds are active the line numbers are rounded off to include the whole | |
633 closed fold. See |fold-behavior|. | |
634 | |
635 | |
636 Reverse Range | |
637 | |
638 A range should have the lower line number first. If this is not the case, Vim | |
639 will ask you if it should swap the line numbers. This is not done within the | |
640 global command ":g". | |
641 | |
642 | |
643 Count and Range *N:* | |
644 | |
645 When giving a count before entering ":", this is translated into: | |
646 :.,.+(count - 1) | |
647 In words: The 'count' lines at and after the cursor. Example: To delete | |
648 three lines: > | |
649 3:d<CR> is translated into: .,.+2d<CR> | |
650 < | |
651 | |
652 Visual Mode and Range *v_:* | |
653 | |
654 {Visual}: Starts a command-line with the Visual selected lines as a | |
655 range. The code ":'<,'>" is used for this range, which makes | |
656 it possible to select a similar line from the command-line | |
657 history for repeating a command on different Visually selected | |
658 lines. | |
659 | |
660 ============================================================================== | |
661 5. Ex special characters *cmdline-special* | |
662 | |
663 In Ex commands, at places where a file name can be used, the following | |
664 characters have a special meaning. These can also be used in the expression | |
665 function expand() |expand()|. | |
666 % is replaced with the current file name *:_%* | |
667 # is replaced with the alternate file name *:_#* | |
668 #n (where n is a number) is replaced with the file name of | |
669 buffer n. "#0" is the same as "#" | |
670 ## is replaced with all names in the argument list *:_##* | |
671 concatenated, separated by spaces. Each space in a name | |
672 is preceded with a backslash. | |
673 Note that these give the file name as it was typed. If an absolute path is | |
674 needed (when using the file name from a different directory), you need to add | |
675 ":p". See |filename-modifiers|. | |
676 Note that backslashes are inserted before spaces, so that the command will | |
677 correctly interpret the file name. But this doesn't happen for shell | |
678 commands. For those you probably have to use quotes: > | |
679 :!ls "%" | |
680 :r !spell "%" | |
681 | |
682 To avoid the special meaning of '%' and '#' insert a backslash before it. | |
683 Detail: The special meaning is always escaped when there is a backslash before | |
684 it, no matter how many backslashes. | |
685 you type: result ~ | |
686 # alternate.file | |
687 \# # | |
688 \\# \# | |
689 | |
690 *:<cword>* *:<cWORD>* *:<cfile>* *<cfile>* | |
691 *:<sfile>* *<sfile>* *:<afile>* *<afile>* | |
692 *:<abuf>* *<abuf>* *:<amatch>* *<amatch>* | |
693 *E495* *E496* *E497* *E498* *E499* *E500* | |
694 Note: these are typed literally, they are not special keys! | |
695 <cword> is replaced with the word under the cursor (like |star|) | |
696 <cWORD> is replaced with the WORD under the cursor (see |WORD|) | |
697 <cfile> is replaced with the path name under the cursor (like what | |
698 |gf| uses) | |
699 <afile> when executing autocommands, is replaced with the file name | |
700 for a file read or write | |
701 <abuf> when executing autocommands, is replaced with the currently | |
702 effective buffer number (for ":r file" it is the current | |
703 buffer, the file being read is not in a buffer). | |
704 <amatch> when executing autocommands, is replaced with the match for | |
705 which this autocommand was executed. It differs form | |
706 <afile> only when the file name isn't used to match with | |
707 (for FileType and Syntax events). | |
708 <sfile> when executing a ":source" command, is replaced with the | |
709 file name of the sourced file; | |
710 when executing a function, is replaced with | |
711 "function {function-name}"; function call nesting is | |
712 indicated like this: | |
713 "function {function-name1}..{function-name2}". Note that | |
714 filename-modifiers are useless when <sfile> is used inside | |
715 a function. | |
716 | |
717 *filename-modifiers* | |
718 *:_%:* *::8* *::p* *::.* *::~* *::h* *::t* *::r* *::e* *::s* *::gs* | |
719 The file name modifiers can be used after "%", "#", "#n", "<cfile>", "<sfile>", | |
720 "<afile>" or "<abuf>". They are also used with the |fnamemodify()| function. | |
721 These are not available when Vim has been compiled without the |+modify_fname| | |
722 feature. | |
723 These modifiers can be given, in this order: | |
724 :p Make file name a full path. Must be the first modifier. Also | |
725 changes "~/" (and "~user/" for Unix and VMS) to the path for | |
726 the home directory. If the name is a directory a path | |
727 separator is added at the end. For a file name that does not | |
728 exist and does not have an absolute path the result is | |
729 unpredictable. | |
730 :8 Converts the path to 8.3 short format (currently only on | |
731 win32). Will act on as much of a path that is an existing | |
732 path. | |
733 :~ Reduce file name to be relative to the home directory, if | |
734 possible. File name is unmodified if it is not below the home | |
735 directory. | |
736 :. Reduce file name to be relative to current directory, if | |
737 possible. File name is unmodified if it is not below the | |
738 current directory. | |
739 For maximum shortness, use ":~:.". | |
740 :h Head of the file name (the last component and any separators | |
741 removed). Cannot be used with :e, :r or :t. | |
742 Can be repeated to remove several components at the end. | |
743 When the file name ends in a path separator, only the path | |
744 separator is removed. Thus ":p:h" on a directory name results | |
745 on the directory name itself (without trailing slash). | |
746 When the file name is an absolute path (starts with "/" for | |
747 Unix; "x:\" for MS-DOS, WIN32, OS/2; "drive:" for Amiga), that | |
748 part is not removed. When there is no head (path is relative | |
749 to current directory) the result is empty. | |
750 :t Tail of the file name (last component of the name). Must | |
751 precede any :r or :e. | |
752 :r Root of the file name (the last extension removed). When | |
753 there is only an extension (file name that starts with '.', | |
754 e.g., ".vimrc"), it is not removed. Can be repeated to remove | |
755 several extensions (last one first). | |
756 :e Extension of the file name. Only makes sense when used alone. | |
757 When there is no extension the result is empty. | |
758 When there is only an extension (file name that starts with | |
759 '.'), the result is empty. Can be repeated to include more | |
760 extensions. If there are not enough extensions (but at least | |
761 one) as much as possible are included. | |
762 :s?pat?sub? | |
763 Substitute the first occurrence of "pat" with "sub". This | |
764 works like the |:s| command. "pat" is a regular expression. | |
765 Any character can be used for '?', but it must not occur in | |
766 "pat" or "sub". | |
767 After this, the previous modifiers can be used again. For | |
768 example ":p", to make a full path after the substitution. | |
769 :gs?pat?sub? | |
770 Substitute all occurrences of "path" with "sub". Otherwise | |
771 this works like ":s". | |
772 | |
773 Examples, when the file name is "src/version.c", current dir | |
774 "/home/mool/vim": > | |
775 :p /home/mool/vim/src/version.c | |
776 :p:. src/version.c | |
777 :p:~ ~/vim/src/version.c | |
778 :h src | |
779 :p:h /home/mool/vim/src | |
780 :p:h:h /home/mool/vim | |
781 :t version.c | |
782 :p:t version.c | |
783 :r src/version | |
784 :p:r /home/mool/vim/src/version | |
785 :t:r version | |
786 :e c | |
787 :s?version?main? src/main.c | |
788 :s?version?main?:p /home/mool/vim/src/main.c | |
789 :p:gs?/?\\? \home\mool\vim\src\version.c | |
790 | |
791 Examples, when the file name is "src/version.c.gz": > | |
792 :p /home/mool/vim/src/version.c.gz | |
793 :e gz | |
794 :e:e c.gz | |
795 :e:e:e c.gz | |
796 :e:e:r c | |
797 :r src/version.c | |
798 :r:e c | |
799 :r:r src/version | |
800 :r:r:r src/version | |
801 < | |
802 *extension-removal* *:_%<* | |
803 If a "<" is appended to "%", "#", "#n" or "CTRL-V p" the extension of the file | |
804 name is removed (everything after and including the last '.' in the file | |
805 name). This is included for backwards compatibility with version 3.0, the | |
806 ":r" form is preferred. Examples: > | |
807 | |
808 % current file name | |
809 %< current file name without extension | |
810 # alternate file name for current window | |
811 #< idem, without extension | |
812 #31 alternate file number 31 | |
813 #31< idem, without extension | |
814 <cword> word under the cursor | |
815 <cWORD> WORD under the cursor (see |WORD|) | |
816 <cfile> path name under the cursor | |
817 <cfile>< idem, without extension | |
818 | |
819 Note: Where a file name is expected wildcards expansion is done. On Unix the | |
820 shell is used for this, unless it can be done internally (for speed). | |
821 Backticks also work, like in > | |
822 :n `echo *.c` | |
823 (backtick expansion is not possible in |restricted-mode|) | |
824 But expansion is only done if there are any wildcards before expanding the | |
825 '%', '#', etc.. This avoids expanding wildcards inside a file name. If you | |
826 want to expand the result of <cfile>, add a wildcard character to it. | |
827 Examples: (alternate file name is "?readme?") | |
828 command expands to ~ | |
829 :e # :e ?readme? | |
830 :e `ls #` :e {files matching "?readme?"} | |
831 :e #.* :e {files matching "?readme?.*"} | |
832 :cd <cfile> :cd {file name under cursor} | |
833 :cd <cfile>* :cd {file name under cursor plus "*" and then expanded} | |
834 | |
835 When the expanded argument contains a "!" and it is used for a shell command | |
836 (":!cmd", ":r !cmd" or ":w !cmd"), it is escaped with a backslash to avoid it | |
837 being expanded into a previously used command. When the 'shell' option | |
838 contains "sh", this is done twice, to avoid the shell trying to expand the | |
839 "!". | |
840 | |
841 *filename-backslash* | |
842 For filesystems that use a backslash as directory separator (MS-DOS, Windows, | |
843 OS/2), it's a bit difficult to recognize a backslash that is used to escape | |
844 the special meaning of the next character. The general rule is: If the | |
845 backslash is followed by a normal file name character, it does not have a | |
846 special meaning. Therefore "\file\foo" is a valid file name, you don't have | |
847 to type the backslash twice. | |
848 | |
849 An exception is the '$' sign. It is a valid character in a file name. But | |
850 to avoid a file name like "$home" to be interpreted as an environment variable, | |
851 it needs to be preceded by a backslash. Therefore you need to use "/\$home" | |
852 for the file "$home" in the root directory. A few examples: | |
853 | |
854 FILE NAME INTERPRETED AS ~ | |
855 $home expanded to value of environment var $home | |
856 \$home file "$home" in current directory | |
857 /\$home file "$home" in root directory | |
858 \\$home file "\\", followed by expanded $home | |
859 | |
860 ============================================================================== | |
861 6. Command-line window *cmdline-window* *cmdwin* | |
862 | |
863 In the command-line window the command line can be edited just like editing | |
864 text in any window. It is a special kind of window, because you cannot leave | |
865 it in a normal way. | |
866 {not available when compiled without the |+cmdline_hist| or |+vertsplit| | |
867 feature} | |
868 | |
869 | |
870 OPEN | |
871 | |
872 There are two ways to open the command-line window: | |
873 1. From Command-line mode, use the key specified with the 'cedit' option. | |
874 The default is CTRL-F when 'compatible' is not set. | |
875 2. From Normal mode, use the "q:", "q/" or "q?" command. *q:* *q/* *q?* | |
876 This starts editing an Ex command-line ("q:") or search string ("q/" or | |
877 "q?"). Note that this is not possible while recording is in progress (the | |
878 "q" stops recording then). | |
879 | |
880 When the window opens it is filled with the command-line history. The last | |
881 line contains the command as typed so far. The left column will show a | |
882 character that indicates the type of command-line being edited, see | |
883 |cmdwin-char|. | |
884 | |
885 Vim will be in Normal mode when the editor is opened, except when 'insertmode' | |
886 is set. | |
887 | |
888 The height of the window is specified with 'cmdwinheight' (or smaller if there | |
889 is no room). The window is always full width and is positioned just above the | |
890 command-line. | |
891 | |
892 | |
893 EDIT | |
894 | |
895 You can now use commands to move around and edit the text in the window. Both | |
896 in Normal mode and Insert mode. | |
897 | |
898 It is possible to use ":", "/" and other commands that use the command-line, | |
899 but it's not possible to open another command-line window then. There is no | |
900 nesting. | |
901 *E11* | |
902 The command-line window is not a normal window. It is not possible to move to | |
903 another window or edit another buffer. All commands that would do this are | |
904 disabled in the command-line window. Of course it _is_ possible to execute | |
905 any command that you entered in the command-line window. | |
906 | |
907 | |
908 CLOSE *E199* | |
909 | |
910 There are several ways to leave the command-line window: | |
911 | |
912 <CR> Execute the command-line under the cursor. Works both in | |
913 Insert and in Normal mode. | |
914 CTRL-C Continue in Command-line mode. The command-line under the | |
915 cursor is used as the command-line. Works both in Insert and | |
916 in Normal mode. ":close" also works. There is no redraw, | |
917 thus the window will remain visible. | |
918 :quit Discard the command line and go back to Normal mode. | |
919 ":exit", ":xit" and CTRL-\ CTRL-N also work. | |
920 :qall Quit Vim, unless there are changes in some buffer. | |
921 :qall! Quit Vim, discarding changes to any buffer. | |
922 | |
923 Once the command-line window is closed the old window sizes are restored. The | |
924 executed command applies to the window and buffer where the command-line was | |
925 started from. This works as if the command-line window was not there, except | |
926 that there will be an extra screen redraw. | |
927 The buffer used for the command-line window is deleted. Any changes to lines | |
928 other than the one that is executed with <CR> are lost. | |
929 | |
930 | |
931 VARIOUS | |
932 | |
933 The command-line window cannot be used: | |
934 - when there already is a command-line window (no nesting) | |
935 - for entering a encryption key or when using inputsecret() | |
936 - when Vim was not compiled with the +vertsplit feature | |
937 | |
938 Some options are set when the command-line window is opened: | |
939 'filetype' "vim", when editing an Ex command-line; this starts Vim syntax | |
940 highlighting if it was enabled | |
941 'rightleft' off | |
942 'modifiable' on | |
943 'buftype' "nofile" | |
944 'swapfile' off | |
945 | |
946 It is allowed to write the buffer contents to a file. This is an easy way to | |
947 save the command-line history and read it back later. | |
948 | |
949 If the 'wildchar' option is set to <Tab>, and the command-line window is used | |
950 for an Ex command, then two mappings will be added to use <Tab> for completion | |
951 in the command-line window, like this: > | |
952 :imap <buffer> <Tab> <C-X><C-V> | |
953 :nmap <buffer> <Tab> a<C-X><C-V> | |
954 Note that hitting <Tab> in Normal mode will do completion on the next | |
955 character. That way it works at the end of the line. | |
956 If you don't want these mappings, disable them with: > | |
957 au CmdwinEnter [:>] iunmap <Tab> | |
958 au CmdwinEnter [:>] nunmap <Tab> | |
959 You could put these lines in your vimrc file. | |
960 | |
961 While in the command-line window you cannot use the mouse to put the cursor in | |
962 another window, or drag statuslines of other windows. You can drag the | |
963 statusline of the command-line window itself and the statusline above it. | |
964 Thus you can resize the command-line window, but not others. | |
965 | |
966 | |
967 AUTOCOMMANDS | |
968 | |
969 Two autocommand events are used: |CmdwinEnter| and |CmdwinLeave|. Since this | |
970 window is of a special type, the WinEnter, WinLeave, BufEnter and BufLeave | |
971 events are not triggered. You can use the Cmdwin events to do settings | |
972 specifically for the command-line window. Be careful not to cause side | |
973 effects! | |
974 Example: > | |
975 :au CmdwinEnter : let b:cpt_save = &cpt | set cpt=v | |
976 :au CmdwinLeave : let &cpt = b:cpt_save | |
977 This sets 'complete' to use command-line completion in Insert mode for CTRL-N. | |
978 Another example: > | |
979 :au CmdwinEnter [/?] startinsert | |
980 This will make Vim start in Insert mode in the command-line window. | |
981 | |
982 *cmdwin-char* | |
983 The character used for the pattern indicates the type of command-line: | |
984 : normal Ex command | |
985 > debug mode command |debug-mode| | |
986 / forward search string | |
987 ? backward search string | |
988 = expression for "= |expr-register| | |
989 @ string for |input()| | |
990 - text for |:insert| or |:append| | |
991 | |
992 vim:tw=78:ts=8:ft=help:norl: |