Mercurial > vim
annotate runtime/doc/change.txt @ 2833:c869ff170ddc
Updated runtime files.
author | Bram Moolenaar <bram@vim.org> |
---|---|
date | Thu, 19 May 2011 12:22:51 +0200 |
parents | 3c7da93eb7f9 |
children | fd09a9c8468e |
rev | line source |
---|---|
2833 | 1 *change.txt* For Vim version 7.3. Last change: 2011 May 17 |
7 | 2 |
3 | |
4 VIM REFERENCE MANUAL by Bram Moolenaar | |
5 | |
6 | |
7 This file describes commands that delete or change text. In this context, | |
8 changing text means deleting the text and replacing it with other text using | |
9 one command. You can undo all of these commands. You can repeat the non-Ex | |
10 commands with the "." command. | |
11 | |
12 1. Deleting text |deleting| | |
13 2. Delete and insert |delete-insert| | |
14 3. Simple changes |simple-change| *changing* | |
15 4. Complex changes |complex-change| | |
32 | 16 4.1 Filter commands |filter| |
17 4.2 Substitute |:substitute| | |
18 4.3 Search and replace |search-replace| | |
19 4.4 Changing tabs |change-tabs| | |
7 | 20 5. Copying and moving text |copy-move| |
21 6. Formatting text |formatting| | |
282 | 22 7. Sorting text |sorting| |
7 | 23 |
24 For inserting text see |insert.txt|. | |
25 | |
26 ============================================================================== | |
27 1. Deleting text *deleting* *E470* | |
28 | |
29 ["x]<Del> or *<Del>* *x* *dl* | |
30 ["x]x Delete [count] characters under and after the cursor | |
31 [into register x] (not |linewise|). Does the same as | |
32 "dl". | |
33 The <Del> key does not take a [count]. Instead, it | |
34 deletes the last character of the count. | |
35 See |:fixdel| if the <Del> key does not do what you | |
36 want. See |'whichwrap'| for deleting a line break | |
37 (join lines). {Vi does not support <Del>} | |
38 | |
39 *X* *dh* | |
40 ["x]X Delete [count] characters before the cursor [into | |
41 register x] (not |linewise|). Does the same as "dh". | |
42 Also see |'whichwrap'|. | |
43 | |
44 *d* | |
45 ["x]d{motion} Delete text that {motion} moves over [into register | |
46 x]. See below for exceptions. | |
47 | |
48 *dd* | |
49 ["x]dd Delete [count] lines [into register x] |linewise|. | |
50 | |
51 *D* | |
52 ["x]D Delete the characters under the cursor until the end | |
53 of the line and [count]-1 more lines [into register | |
54 x]; synonym for "d$". | |
55 (not |linewise|) | |
164 | 56 When the '#' flag is in 'cpoptions' the count is |
57 ignored. | |
7 | 58 |
59 {Visual}["x]x or *v_x* *v_d* *v_<Del>* | |
60 {Visual}["x]d or | |
61 {Visual}["x]<Del> Delete the highlighted text [into register x] (for | |
62 {Visual} see |Visual-mode|). {not in Vi} | |
63 | |
64 {Visual}["x]CTRL-H or *v_CTRL-H* *v_<BS>* | |
65 {Visual}["x]<BS> When in Select mode: Delete the highlighted text [into | |
66 register x]. | |
67 | |
68 {Visual}["x]X or *v_X* *v_D* *v_b_D* | |
69 {Visual}["x]D Delete the highlighted lines [into register x] (for | |
70 {Visual} see |Visual-mode|). In Visual block mode, | |
71 "D" deletes the highlighted text plus all text until | |
72 the end of the line. {not in Vi} | |
73 | |
74 *:d* *:de* *:del* *:delete* | |
75 :[range]d[elete] [x] Delete [range] lines (default: current line) [into | |
76 register x]. | |
77 | |
78 :[range]d[elete] [x] {count} | |
79 Delete {count} lines, starting with [range] | |
80 (default: current line |cmdline-ranges|) [into | |
81 register x]. | |
82 | |
83 These commands delete text. You can repeat them with the "." command | |
84 (except ":d") and undo them. Use Visual mode to delete blocks of text. See | |
85 |registers| for an explanation of registers. | |
86 | |
87 An exception for the d{motion} command: If the motion is not linewise, the | |
88 start and end of the motion are not in the same line, and there are only | |
89 blanks before the start and after the end of the motion, the delete becomes | |
90 linewise. This means that the delete also removes the line of blanks that you | |
91 might expect to remain. | |
92 | |
93 Trying to delete an empty region of text (e.g., "d0" in the first column) | |
94 is an error when 'cpoptions' includes the 'E' flag. | |
95 | |
96 *J* | |
97 J Join [count] lines, with a minimum of two lines. | |
98 Remove the indent and insert up to two spaces (see | |
99 below). | |
100 | |
101 *v_J* | |
102 {Visual}J Join the highlighted lines, with a minimum of two | |
103 lines. Remove the indent and insert up to two spaces | |
104 (see below). {not in Vi} | |
105 | |
106 *gJ* | |
107 gJ Join [count] lines, with a minimum of two lines. | |
108 Don't insert or remove any spaces. {not in Vi} | |
109 | |
110 *v_gJ* | |
111 {Visual}gJ Join the highlighted lines, with a minimum of two | |
112 lines. Don't insert or remove any spaces. {not in | |
113 Vi} | |
114 | |
115 *:j* *:join* | |
168 | 116 :[range]j[oin][!] [flags] |
117 Join [range] lines. Same as "J", except with [!] | |
7 | 118 the join does not insert or delete any spaces. |
119 If a [range] has equal start and end values, this | |
120 command does nothing. The default behavior is to | |
121 join the current line with the line below it. | |
122 {not in Vi: !} | |
168 | 123 See |ex-flags| for [flags]. |
7 | 124 |
168 | 125 :[range]j[oin][!] {count} [flags] |
7 | 126 Join {count} lines, starting with [range] (default: |
127 current line |cmdline-ranges|). Same as "J", except | |
128 with [!] the join does not insert or delete any | |
129 spaces. | |
130 {not in Vi: !} | |
168 | 131 See |ex-flags| for [flags]. |
7 | 132 |
133 These commands delete the <EOL> between lines. This has the effect of joining | |
134 multiple lines into one line. You can repeat these commands (except ":j") and | |
135 undo them. | |
136 | |
137 These commands, except "gJ", insert one space in place of the <EOL> unless | |
138 there is trailing white space or the next line starts with a ')'. These | |
139 commands, except "gJ", delete any leading white space on the next line. If | |
140 the 'joinspaces' option is on, these commands insert two spaces after a '.', | |
141 '!' or '?' (but if 'cpoptions' includes the 'j' flag, they insert two spaces | |
142 only after a '.'). | |
143 The 'B' and 'M' flags in 'formatoptions' change the behavior for inserting | |
144 spaces before and after a multi-byte character |fo-table|. | |
145 | |
146 | |
147 ============================================================================== | |
148 2. Delete and insert *delete-insert* *replacing* | |
149 | |
150 *R* | |
151 R Enter Replace mode: Each character you type replaces | |
152 an existing character, starting with the character | |
153 under the cursor. Repeat the entered text [count]-1 | |
154 times. See |Replace-mode| for more details. | |
155 | |
156 *gR* | |
157 gR Enter Virtual Replace mode: Each character you type | |
158 replaces existing characters in screen space. So a | |
159 <Tab> may replace several characters at once. | |
160 Repeat the entered text [count]-1 times. See | |
161 |Virtual-Replace-mode| for more details. | |
2570
71b56b4e7785
Make the references to features in the help more consistent. (Sylvain Hitier)
Bram Moolenaar <bram@vim.org>
parents:
2561
diff
changeset
|
162 {not available when compiled without the |+vreplace| |
7 | 163 feature} |
164 | |
165 *c* | |
166 ["x]c{motion} Delete {motion} text [into register x] and start | |
167 insert. When 'cpoptions' includes the 'E' flag and | |
168 there is no text to delete (e.g., with "cTx" when the | |
169 cursor is just after an 'x'), an error occurs and | |
170 insert mode does not start (this is Vi compatible). | |
171 When 'cpoptions' does not include the 'E' flag, the | |
172 "c" command always starts insert mode, even if there | |
173 is no text to delete. | |
174 | |
175 *cc* | |
176 ["x]cc Delete [count] lines [into register x] and start | |
177 insert |linewise|. If 'autoindent' is on, preserve | |
178 the indent of the first line. | |
179 | |
180 *C* | |
181 ["x]C Delete from the cursor position to the end of the | |
182 line and [count]-1 more lines [into register x], and | |
183 start insert. Synonym for c$ (not |linewise|). | |
184 | |
185 *s* | |
186 ["x]s Delete [count] characters [into register x] and start | |
187 insert (s stands for Substitute). Synonym for "cl" | |
188 (not |linewise|). | |
189 | |
190 *S* | |
191 ["x]S Delete [count] lines [into register x] and start | |
192 insert. Synonym for "cc" |linewise|. | |
193 | |
194 {Visual}["x]c or *v_c* *v_s* | |
195 {Visual}["x]s Delete the highlighted text [into register x] and | |
196 start insert (for {Visual} see |Visual-mode|). {not | |
197 in Vi} | |
198 | |
199 *v_r* | |
200 {Visual}["x]r{char} Replace all selected characters by {char}. | |
201 | |
202 *v_C* | |
203 {Visual}["x]C Delete the highlighted lines [into register x] and | |
204 start insert. In Visual block mode it works | |
205 differently |v_b_C|. {not in Vi} | |
206 *v_S* | |
207 {Visual}["x]S Delete the highlighted lines [into register x] and | |
208 start insert (for {Visual} see |Visual-mode|). {not | |
209 in Vi} | |
210 *v_R* | |
211 {Visual}["x]R Currently just like {Visual}["x]S. In a next version | |
212 it might work differently. {not in Vi} | |
213 | |
214 Notes: | |
215 - You can end Insert and Replace mode with <Esc>. | |
216 - See the section "Insert and Replace mode" |mode-ins-repl| for the other | |
217 special characters in these modes. | |
218 - The effect of [count] takes place after Vim exits Insert or Replace mode. | |
219 - When the 'cpoptions' option contains '$' and the change is within one line, | |
220 Vim continues to show the text to be deleted and puts a '$' at the last | |
221 deleted character. | |
222 | |
223 See |registers| for an explanation of registers. | |
224 | |
225 Replace mode is just like Insert mode, except that every character you enter | |
226 deletes one character. If you reach the end of a line, Vim appends any | |
227 further characters (just like Insert mode). In Replace mode, the backspace | |
228 key restores the original text (if there was any). (See section "Insert and | |
229 Replace mode" |mode-ins-repl|). | |
230 | |
231 *cw* *cW* | |
1621 | 232 Special case: When the cursor is in a word, "cw" and "cW" do not include the |
233 white space after a word, they only change up to the end of the word. This is | |
234 because Vim interprets "cw" as change-word, and a word does not include the | |
235 following white space. | |
236 {Vi: "cw" when on a blank followed by other blanks changes only the first | |
237 blank; this is probably a bug, because "dw" deletes all the blanks; use the | |
238 'w' flag in 'cpoptions' to make it work like Vi anyway} | |
7 | 239 |
240 If you prefer "cw" to include the space after a word, use this mapping: > | |
241 :map cw dwi | |
1621 | 242 Or use "caw" (see |aw|). |
243 | |
7 | 244 *:c* *:ch* *:change* |
168 | 245 :{range}c[hange][!] Replace lines of text with some different text. |
7 | 246 Type a line containing only "." to stop replacing. |
247 Without {range}, this command changes only the current | |
248 line. | |
168 | 249 Adding [!] toggles 'autoindent' for the time this |
250 command is executed. | |
7 | 251 |
252 ============================================================================== | |
253 3. Simple changes *simple-change* | |
254 | |
255 *r* | |
256 r{char} Replace the character under the cursor with {char}. | |
257 If {char} is a <CR> or <NL>, a line break replaces the | |
258 character. To replace with a real <CR>, use CTRL-V | |
259 <CR>. CTRL-V <NL> replaces with a <Nul>. | |
260 {Vi: CTRL-V <CR> still replaces with a line break, | |
261 cannot replace something with a <CR>} | |
262 If you give a [count], Vim replaces [count] characters | |
263 with [count] {char}s. When {char} is a <CR> or <NL>, | |
264 however, Vim inserts only one <CR>: "5r<CR>" replaces | |
265 five characters with a single line break. | |
266 When {char} is a <CR> or <NL>, Vim performs | |
267 autoindenting. This works just like deleting the | |
268 characters that are replaced and then doing | |
269 "i<CR><Esc>". | |
270 {char} can be entered as a digraph |digraph-arg|. | |
271 |:lmap| mappings apply to {char}. The CTRL-^ command | |
272 in Insert mode can be used to switch this on/off | |
273 |i_CTRL-^|. See |utf-8-char-arg| about using | |
274 composing characters when 'encoding' is Unicode. | |
275 | |
276 *gr* | |
277 gr{char} Replace the virtual characters under the cursor with | |
278 {char}. This replaces in screen space, not file | |
279 space. See |gR| and |Virtual-Replace-mode| for more | |
280 details. As with |r| a count may be given. | |
281 {char} can be entered like with |r|. | |
2570
71b56b4e7785
Make the references to features in the help more consistent. (Sylvain Hitier)
Bram Moolenaar <bram@vim.org>
parents:
2561
diff
changeset
|
282 {not available when compiled without the |+vreplace| |
7 | 283 feature} |
284 | |
285 *digraph-arg* | |
286 The argument for Normal mode commands like |r| and |t| is a single character. | |
287 When 'cpo' doesn't contain the 'D' flag, this character can also be entered | |
288 like |digraphs|. First type CTRL-K and then the two digraph characters. | |
289 {not available when compiled without the |+digraphs| feature} | |
290 | |
291 *case* | |
292 The following commands change the case of letters. The currently active | |
293 |locale| is used. See |:language|. The LC_CTYPE value matters here. | |
294 | |
295 *~* | |
296 ~ 'notildeop' option: Switch case of the character | |
297 under the cursor and move the cursor to the right. | |
298 If a [count] is given, do that many characters. {Vi: | |
299 no count} | |
300 | |
301 ~{motion} 'tildeop' option: switch case of {motion} text. {Vi: | |
302 tilde cannot be used as an operator} | |
303 | |
304 *g~* | |
305 g~{motion} Switch case of {motion} text. {not in Vi} | |
306 | |
307 g~g~ *g~g~* *g~~* | |
308 g~~ Switch case of current line. {not in Vi}. | |
309 | |
310 *v_~* | |
311 {Visual}~ Switch case of highlighted text (for {Visual} see | |
312 |Visual-mode|). {not in Vi} | |
313 | |
314 *v_U* | |
315 {Visual}U Make highlighted text uppercase (for {Visual} see | |
316 |Visual-mode|). {not in Vi} | |
317 | |
318 *gU* *uppercase* | |
319 gU{motion} Make {motion} text uppercase. {not in Vi} | |
320 Example: > | |
321 :map! <C-F> <Esc>gUiw`]a | |
322 < This works in Insert mode: press CTRL-F to make the | |
323 word before the cursor uppercase. Handy to type | |
324 words in lowercase and then make them uppercase. | |
325 | |
326 | |
327 gUgU *gUgU* *gUU* | |
328 gUU Make current line uppercase. {not in Vi}. | |
329 | |
330 *v_u* | |
331 {Visual}u Make highlighted text lowercase (for {Visual} see | |
332 |Visual-mode|). {not in Vi} | |
333 | |
334 *gu* *lowercase* | |
335 gu{motion} Make {motion} text lowercase. {not in Vi} | |
336 | |
337 gugu *gugu* *guu* | |
338 guu Make current line lowercase. {not in Vi}. | |
339 | |
340 *g?* *rot13* | |
341 g?{motion} Rot13 encode {motion} text. {not in Vi} | |
342 | |
343 *v_g?* | |
344 {Visual}g? Rot13 encode the highlighted text (for {Visual} see | |
345 |Visual-mode|). {not in Vi} | |
346 | |
347 g?g? *g?g?* *g??* | |
348 g?? Rot13 encode current line. {not in Vi}. | |
349 | |
1621 | 350 To turn one line into title caps, make every first letter of a word |
351 uppercase: > | |
352 :s/\v<(.)(\w*)/\u\1\L\2/g | |
353 | |
7 | 354 |
355 Adding and subtracting ~ | |
356 *CTRL-A* | |
357 CTRL-A Add [count] to the number or alphabetic character at | |
358 or after the cursor. {not in Vi} | |
359 | |
360 *CTRL-X* | |
361 CTRL-X Subtract [count] from the number or alphabetic | |
362 character at or after the cursor. {not in Vi} | |
363 | |
364 The CTRL-A and CTRL-X commands work for (signed) decimal numbers, unsigned | |
365 octal and hexadecimal numbers and alphabetic characters. This depends on the | |
366 'nrformats' option. | |
36 | 367 - When 'nrformats' includes "octal", Vim considers numbers starting with a '0' |
39 | 368 to be octal, unless the number includes a '8' or '9'. Other numbers are |
369 decimal and may have a preceding minus sign. | |
36 | 370 If the cursor is on a number, the commands apply to that number; otherwise |
371 Vim uses the number to the right of the cursor. | |
7 | 372 - When 'nrformats' includes "hex", Vim assumes numbers starting with '0x' or |
373 '0X' are hexadecimal. The case of the rightmost letter in the number | |
374 determines the case of the resulting hexadecimal number. If there is no | |
375 letter in the current number, Vim uses the previously detected case. | |
36 | 376 - When 'nrformats' includes "alpha", Vim will change the alphabetic character |
377 under or after the cursor. This is useful to make lists with an alphabetic | |
378 index. | |
7 | 379 |
380 For numbers with leading zeros (including all octal and hexadecimal numbers), | |
381 Vim preserves the number of characters in the number when possible. CTRL-A on | |
36 | 382 "0077" results in "0100", CTRL-X on "0x100" results in "0x0ff". |
39 | 383 There is one exception: When a number that starts with a zero is found not to |
384 be octal (it contains a '8' or '9'), but 'nrformats' does include "octal", | |
385 leading zeros are removed to avoid that the result may be recognized as an | |
386 octal number. | |
36 | 387 |
388 Note that when 'nrformats' includes "octal", decimal numbers with leading | |
39 | 389 zeros cause mistakes, because they can be confused with octal numbers. |
7 | 390 |
391 The CTRL-A command is very useful in a macro. Example: Use the following | |
392 steps to make a numbered list. | |
393 | |
394 1. Create the first list entry, make sure it starts with a number. | |
99 | 395 2. qa - start recording into register 'a' |
7 | 396 3. Y - yank the entry |
397 4. p - put a copy of the entry below the first one | |
398 5. CTRL-A - increment the number | |
399 6. q - stop recording | |
400 7. <count>@a - repeat the yank, put and increment <count> times | |
401 | |
402 | |
403 SHIFTING LINES LEFT OR RIGHT *shift-left-right* | |
404 | |
405 *<* | |
406 <{motion} Shift {motion} lines one 'shiftwidth' leftwards. | |
407 | |
408 *<<* | |
409 << Shift [count] lines one 'shiftwidth' leftwards. | |
410 | |
411 *v_<* | |
412 {Visual}[count]< Shift the highlighted lines [count] 'shiftwidth' | |
413 leftwards (for {Visual} see |Visual-mode|). {not in | |
414 Vi} | |
415 | |
416 *>* | |
417 >{motion} Shift {motion} lines one 'shiftwidth' rightwards. | |
418 | |
419 *>>* | |
420 >> Shift [count] lines one 'shiftwidth' rightwards. | |
421 | |
422 *v_>* | |
423 {Visual}[count]> Shift the highlighted lines [count] 'shiftwidth' | |
424 rightwards (for {Visual} see |Visual-mode|). {not in | |
425 Vi} | |
426 | |
427 *:<* | |
428 :[range]< Shift [range] lines one 'shiftwidth' left. Repeat '<' | |
429 for shifting multiple 'shiftwidth's. | |
430 | |
431 :[range]< {count} Shift {count} lines one 'shiftwidth' left, starting | |
432 with [range] (default current line |cmdline-ranges|). | |
433 Repeat '<' for shifting multiple 'shiftwidth's. | |
434 | |
435 :[range]le[ft] [indent] left align lines in [range]. Sets the indent in the | |
436 lines to [indent] (default 0). {not in Vi} | |
437 | |
438 *:>* | |
168 | 439 :[range]> [flags] Shift {count} [range] lines one 'shiftwidth' right. |
7 | 440 Repeat '>' for shifting multiple 'shiftwidth's. |
168 | 441 See |ex-flags| for [flags]. |
7 | 442 |
168 | 443 :[range]> {count} [flags] |
444 Shift {count} lines one 'shiftwidth' right, starting | |
7 | 445 with [range] (default current line |cmdline-ranges|). |
446 Repeat '>' for shifting multiple 'shiftwidth's. | |
168 | 447 See |ex-flags| for [flags]. |
7 | 448 |
449 The ">" and "<" commands are handy for changing the indentation within | |
450 programs. Use the 'shiftwidth' option to set the size of the white space | |
451 which these commands insert or delete. Normally the 'shiftwidth' option is 8, | |
452 but you can set it to, say, 3 to make smaller indents. The shift leftwards | |
453 stops when there is no indent. The shift right does not affect empty lines. | |
454 | |
455 If the 'shiftround' option is on, the indent is rounded to a multiple of | |
456 'shiftwidth'. | |
457 | |
458 If the 'smartindent' option is on, or 'cindent' is on and 'cinkeys' contains | |
459 '#', shift right does not affect lines starting with '#' (these are supposed | |
460 to be C preprocessor lines that must stay in column 1). | |
461 | |
462 When the 'expandtab' option is off (this is the default) Vim uses <Tab>s as | |
463 much as possible to make the indent. You can use ">><<" to replace an indent | |
464 made out of spaces with the same indent made out of <Tab>s (and a few spaces | |
465 if necessary). If the 'expandtab' option is on, Vim uses only spaces. Then | |
466 you can use ">><<" to replace <Tab>s in the indent by spaces (or use | |
467 ":retab!"). | |
468 | |
469 To move a line several 'shiftwidth's, use Visual mode or the ":" commands. | |
470 For example: > | |
471 Vjj4> move three lines 4 indents to the right | |
472 :<<< move current line 3 indents to the left | |
473 :>> 5 move 5 lines 2 indents to the right | |
474 :5>> move line 5 2 indents to the right | |
475 | |
476 ============================================================================== | |
477 4. Complex changes *complex-change* | |
478 | |
856 | 479 4.1 Filter commands *filter* |
32 | 480 |
481 A filter is a program that accepts text at standard input, changes it in some | |
482 way, and sends it to standard output. You can use the commands below to send | |
1621 | 483 some text through a filter, so that it is replaced by the filter output. |
32 | 484 Examples of filters are "sort", which sorts lines alphabetically, and |
485 "indent", which formats C program files (you need a version of indent that | |
486 works like a filter; not all versions do). The 'shell' option specifies the | |
487 shell Vim uses to execute the filter command (See also the 'shelltype' | |
488 option). You can repeat filter commands with ".". Vim does not recognize a | |
489 comment (starting with '"') after the ":!" command. | |
490 | |
491 *!* | |
7 | 492 !{motion}{filter} Filter {motion} text lines through the external |
493 program {filter}. | |
494 | |
495 *!!* | |
496 !!{filter} Filter [count] lines through the external program | |
497 {filter}. | |
498 | |
499 *v_!* | |
500 {Visual}!{filter} Filter the highlighted lines through the external | |
501 program {filter} (for {Visual} see |Visual-mode|). | |
502 {not in Vi} | |
503 | |
504 :{range}![!]{filter} [!][arg] *:range!* | |
505 Filter {range} lines through the external program | |
506 {filter}. Vim replaces the optional bangs with the | |
507 latest given command and appends the optional [arg]. | |
508 Vim saves the output of the filter command in a | |
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
509 temporary file and then reads the file into the buffer |
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
510 |tempfile|. Vim uses the 'shellredir' option to |
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
511 redirect the filter output to the temporary file. |
603 | 512 However, if the 'shelltemp' option is off then pipes |
513 are used when possible (on Unix). | |
7 | 514 When the 'R' flag is included in 'cpoptions' marks in |
515 the filtered lines are deleted, unless the | |
516 |:keepmarks| command is used. Example: > | |
517 :keepmarks '<,'>!sort | |
518 < When the number of lines after filtering is less than | |
519 before, marks in the missing lines are deleted anyway. | |
520 | |
521 *=* | |
522 ={motion} Filter {motion} lines through the external program | |
523 given with the 'equalprg' option. When the 'equalprg' | |
524 option is empty (this is the default), use the | |
2833 | 525 internal formatting function |C-indenting| and |
526 |'lisp'|. But when 'indentexpr' is not empty, it will | |
527 be used instead |indent-expression|. When Vim was | |
528 compiled without internal formatting then the "indent" | |
529 program is used as a last resort. | |
7 | 530 |
531 *==* | |
532 == Filter [count] lines like with ={motion}. | |
533 | |
534 *v_=* | |
535 {Visual}= Filter the highlighted lines like with ={motion}. | |
536 {not in Vi} | |
537 | |
538 | |
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
539 *tempfile* *setuid* |
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
540 Vim uses temporary files for filtering, generating diffs and also for |
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
541 tempname(). For Unix, the file will be in a private directory (only |
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
542 accessible by the current user) to avoid security problems (e.g., a symlink |
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
543 attack or other people reading your file). When Vim exits the directory and |
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
544 all files in it are deleted. When Vim has the setuid bit set this may cause |
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
545 problems, the temp file is owned by the setuid user but the filter command |
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
546 probably runs as the original user. |
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
547 On MS-DOS and OS/2 the first of these directories that works is used: $TMP, |
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
548 $TEMP, c:\TMP, c:\TEMP. |
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
549 For Unix the list of directories is: $TMPDIR, /tmp, current-dir, $HOME. |
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
550 For MS-Windows the GetTempFileName() system function is used. |
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
551 For other systems the tmpnam() library function is used. |
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
552 |
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
553 |
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
554 |
32 | 555 4.2 Substitute *:substitute* |
556 *:s* *:su* | |
170 | 557 :[range]s[ubstitute]/{pattern}/{string}/[flags] [count] |
7 | 558 For each line in [range] replace a match of {pattern} |
559 with {string}. | |
560 For the {pattern} see |pattern|. | |
561 {string} can be a literal string, or something | |
562 special; see |sub-replace-special|. | |
563 When [range] and [count] are omitted, replace in the | |
564 current line only. | |
565 When [count] is given, replace in [count] lines, | |
566 starting with the last line in [range]. When [range] | |
567 is omitted start in the current line. | |
568 Also see |cmdline-ranges|. | |
170 | 569 See |:s_flags| for [flags]. |
7 | 570 |
170 | 571 :[range]s[ubstitute] [flags] [count] |
572 :[range]&[&][flags] [count] *:&* | |
7 | 573 Repeat last :substitute with same search pattern and |
574 substitute string, but without the same flags. You | |
170 | 575 may add [flags], see |:s_flags|. |
7 | 576 Note that after ":substitute" the '&' flag can't be |
577 used, it's recognized as a pattern separator. | |
578 The space between ":substitute" and the 'c', 'g' and | |
579 'r' flags isn't required, but in scripts it's a good | |
580 idea to keep it to avoid confusion. | |
581 | |
170 | 582 :[range]~[&][flags] [count] *:~* |
7 | 583 Repeat last substitute with same substitute string |
584 but with last used search pattern. This is like | |
170 | 585 ":&r". See |:s_flags| for [flags]. |
7 | 586 |
170 | 587 *&* |
2152 | 588 & Synonym for ":s" (repeat last substitute). Note |
7 | 589 that the flags are not remembered, thus it might |
590 actually work differently. You can use ":&&" to keep | |
591 the flags. | |
592 | |
170 | 593 *g&* |
7 | 594 g& Synonym for ":%s//~/&" (repeat last substitute on all |
595 lines with the same flags). | |
596 Mnemonic: global substitute. {not in Vi} | |
597 | |
598 *:snomagic* *:sno* | |
599 :[range]sno[magic] ... Same as ":substitute", but always use 'nomagic'. | |
600 {not in Vi} | |
601 | |
602 *:smagic* *:sm* | |
603 :[range]sm[agic] ... Same as ":substitute", but always use 'magic'. | |
604 {not in Vi} | |
605 | |
606 *:s_flags* | |
607 The flags that you can use for the substitute commands: | |
608 | |
609 [&] Must be the first one: Keep the flags from the previous substitute | |
610 command. Examples: > | |
611 :&& | |
612 :s/this/that/& | |
613 < Note that ":s" and ":&" don't keep the flags. | |
614 {not in Vi} | |
615 | |
616 [c] Confirm each substitution. Vim highlights the matching string (with | |
617 |hl-IncSearch|). You can type: *:s_c* | |
618 'y' to substitute this match | |
619 'l' to substitute this match and then quit ("last") | |
620 'n' to skip this match | |
621 <Esc> to quit substituting | |
622 'a' to substitute this and all remaining matches {not in Vi} | |
623 'q' to quit substituting {not in Vi} | |
624 CTRL-E to scroll the screen up {not in Vi, not available when | |
2570
71b56b4e7785
Make the references to features in the help more consistent. (Sylvain Hitier)
Bram Moolenaar <bram@vim.org>
parents:
2561
diff
changeset
|
625 compiled without the |+insert_expand| feature} |
7 | 626 CTRL-Y to scroll the screen down {not in Vi, not available when |
2570
71b56b4e7785
Make the references to features in the help more consistent. (Sylvain Hitier)
Bram Moolenaar <bram@vim.org>
parents:
2561
diff
changeset
|
627 compiled without the |+insert_expand| feature} |
7 | 628 If the 'edcompatible' option is on, Vim remembers the [c] flag and |
629 toggles it each time you use it, but resets it when you give a new | |
630 search pattern. | |
631 {not in Vi: highlighting of the match, other responses than 'y' or 'n'} | |
632 | |
633 [e] When the search pattern fails, do not issue an error message and, in | |
634 particular, continue in maps as if no error occurred. This is most | |
635 useful to prevent the "No match" error from breaking a mapping. Vim | |
636 does not suppress the following error messages, however: | |
637 Regular expressions can't be delimited by letters | |
638 \ should be followed by /, ? or & | |
639 No previous substitute regular expression | |
640 Trailing characters | |
641 Interrupted | |
642 {not in Vi} | |
643 | |
644 [g] Replace all occurrences in the line. Without this argument, | |
645 replacement occurs only for the first occurrence in each line. If | |
646 the 'edcompatible' option is on, Vim remembers this flag and toggles | |
647 it each time you use it, but resets it when you give a new search | |
648 pattern. If the 'gdefault' option is on, this flag is on by default | |
649 and the [g] argument switches it off. | |
650 | |
651 [i] Ignore case for the pattern. The 'ignorecase' and 'smartcase' options | |
652 are not used. | |
653 {not in Vi} | |
654 | |
655 [I] Don't ignore case for the pattern. The 'ignorecase' and 'smartcase' | |
656 options are not used. | |
657 {not in Vi} | |
658 | |
170 | 659 [n] Report the number of matches, do not actually substitute. The [c] |
660 flag is ignored. The matches are reported as if 'report' is zero. | |
661 Useful to |count-items|. | |
662 | |
7 | 663 [p] Print the line containing the last substitute. |
168 | 664 |
665 [#] Like [p] and prepend the line number. | |
666 | |
1121 | 667 [l] Like [p] but print the text like |:list|. |
7 | 668 |
669 [r] Only useful in combination with ":&" or ":s" without arguments. ":&r" | |
670 works the same way as ":~": When the search pattern is empty, use the | |
671 previously used search pattern instead of the search pattern from the | |
672 last substitute or ":global". If the last command that did a search | |
673 was a substitute or ":global", there is no effect. If the last | |
674 command was a search command such as "/", use the pattern from that | |
675 command. | |
676 For ":s" with an argument this already happens: > | |
677 :s/blue/red/ | |
678 /green | |
679 :s//red/ or :~ or :&r | |
680 < The last commands will replace "green" with "red". > | |
681 :s/blue/red/ | |
682 /green | |
683 :& | |
684 < The last command will replace "blue" with "red". | |
685 {not in Vi} | |
686 | |
687 Note that there is no flag to change the "magicness" of the pattern. A | |
1621 | 688 different command is used instead, or you can use |/\v| and friends. The |
689 reason is that the flags can only be found by skipping the pattern, and in | |
690 order to skip the pattern the "magicness" must be known. Catch 22! | |
7 | 691 |
692 If the {pattern} for the substitute command is empty, the command uses the | |
2725 | 693 pattern from the last substitute or ":global" command. If there is none, but |
694 there is a previous search pattern, that one is used. With the [r] flag, the | |
7 | 695 command uses the pattern from the last substitute, ":global", or search |
696 command. | |
697 | |
1121 | 698 If the {string} is omitted the substitute is done as if it's empty. Thus the |
699 matched pattern is deleted. The separator after {pattern} can also be left | |
700 out then. Example: > | |
701 :%s/TESTING | |
702 This deletes "TESTING" from all lines, but only one per line. | |
703 | |
7 | 704 For compatibility with Vi these two exceptions are allowed: |
705 "\/{string}/" and "\?{string}?" do the same as "//{string}/r". | |
706 "\&{string}&" does the same as "//{string}/". | |
707 *E146* | |
708 Instead of the '/' which surrounds the pattern and replacement string, you | |
1121 | 709 can use any other single-byte character, but not an alphanumeric character, |
710 '\', '"' or '|'. This is useful if you want to include a '/' in the search | |
711 pattern or replacement string. Example: > | |
7 | 712 :s+/+//+ |
713 | |
1621 | 714 For the definition of a pattern, see |pattern|. In Visual block mode, use |
715 |/\%V| in the pattern to have the substitute work in the block only. | |
716 Otherwise it works on whole lines anyway. | |
7 | 717 |
718 *sub-replace-special* *:s\=* | |
719 When the {string} starts with "\=" it is evaluated as an expression, see | |
452 | 720 |sub-replace-expression|. You can use that for any special characters. |
721 Otherwise these characters in {string} have a special meaning: | |
168 | 722 *:s%* |
843 | 723 When {string} is equal to "%" and '/' is included with the 'cpoptions' option, |
168 | 724 then the {string} of the previous substitute command is used. |cpo-/| |
7 | 725 |
726 magic nomagic action ~ | |
727 & \& replaced with the whole matched pattern *s/\&* | |
728 \& & replaced with & | |
729 \0 replaced with the whole matched pattern *\0* *s/\0* | |
730 \1 replaced with the matched pattern in the first | |
731 pair of () *s/\1* | |
26 | 732 \2 replaced with the matched pattern in the second |
7 | 733 pair of () *s/\2* |
734 .. .. *s/\3* | |
735 \9 replaced with the matched pattern in the ninth | |
736 pair of () *s/\9* | |
737 ~ \~ replaced with the {string} of the previous | |
738 substitute *s~* | |
739 \~ ~ replaced with ~ *s/\~* | |
740 \u next character made uppercase *s/\u* | |
741 \U following characters made uppercase, until \E *s/\U* | |
742 \l next character made lowercase *s/\l* | |
743 \L following characters made lowercase, until \E *s/\L* | |
744 \e end of \u, \U, \l and \L (NOTE: not <Esc>!) *s/\e* | |
745 \E end of \u, \U, \l and \L *s/\E* | |
746 <CR> split line in two at this point | |
747 (Type the <CR> as CTRL-V <Enter>) *s<CR>* | |
748 \r idem *s/\r* | |
749 \<CR> insert a carriage-return (CTRL-M) | |
750 (Type the <CR> as CTRL-V <Enter>) *s/\<CR>* | |
751 \n insert a <NL> (<NUL> in the file) | |
752 (does NOT break the line) *s/\n* | |
753 \b insert a <BS> *s/\b* | |
754 \t insert a <Tab> *s/\t* | |
755 \\ insert a single backslash *s/\\* | |
756 \x where x is any character not mentioned above: | |
757 Reserved for future expansion | |
758 | |
759 Examples: > | |
760 :s/a\|b/xxx\0xxx/g modifies "a b" to "xxxaxxx xxxbxxx" | |
761 :s/\([abc]\)\([efg]\)/\2\1/g modifies "af fa bg" to "fa fa gb" | |
762 :s/abcde/abc^Mde/ modifies "abcde" to "abc", "de" (two lines) | |
763 :s/$/\^M/ modifies "abcde" to "abcde^M" | |
772 | 764 :s/\w\+/\u\0/g modifies "bla bla" to "Bla Bla" |
7 | 765 |
766 Note: In previous versions CTRL-V was handled in a special way. Since this is | |
767 not Vi compatible, this was removed. Use a backslash instead. | |
768 | |
769 command text result ~ | |
770 :s/aa/a^Ma/ aa a<line-break>a | |
771 :s/aa/a\^Ma/ aa a^Ma | |
772 :s/aa/a\\^Ma/ aa a\<line-break>a | |
773 | |
774 (you need to type CTRL-V <CR> to get a ^M here) | |
775 | |
776 The numbering of "\1", "\2" etc. is done based on which "\(" comes first in | |
777 the pattern (going left to right). When a parentheses group matches several | |
778 times, the last one will be used for "\1", "\2", etc. Example: > | |
779 :s/\(\(a[a-d] \)*\)/\2/ modifies "aa ab x" to "ab x" | |
780 | |
781 When using parentheses in combination with '|', like in \([ab]\)\|\([cd]\), | |
782 either the first or second pattern in parentheses did not match, so either | |
783 \1 or \2 is empty. Example: > | |
784 :s/\([ab]\)\|\([cd]\)/\1x/g modifies "a b c d" to "ax bx x x" | |
785 < | |
786 | |
787 Substitute with an expression *sub-replace-expression* | |
270 | 788 *sub-replace-\=* |
789 When the substitute string starts with "\=" the remainder is interpreted as an | |
7 | 790 expression. This does not work recursively: a substitute() function inside |
791 the expression cannot use "\=" for the substitute string. | |
792 | |
793 The special meaning for characters as mentioned at |sub-replace-special| does | |
1668 | 794 not apply except for "<CR>", "\<CR>" and "\\". Thus in the result of the |
795 expression you need to use two backslashes to get one, put a backslash before a | |
796 <CR> you want to insert, and use a <CR> without a backslash where you want to | |
7 | 797 break the line. |
798 | |
799 For convenience a <NL> character is also used as a line break. Prepend a | |
800 backslash to get a real <NL> character (which will be a NUL in the file). | |
801 | |
714 | 802 When the result is a |List| then the items are joined with separating line |
803 breaks. Thus each item becomes a line, except that they can contain line | |
804 breaks themselves. | |
805 | |
7 | 806 The whole matched text can be accessed with "submatch(0)". The text matched |
807 with the first pair of () with "submatch(1)". Likewise for further | |
808 sub-matches in (). | |
809 | |
810 Be careful: The separation character must not appear in the expression! | |
811 Consider using a character like "@" or ":". There is no problem if the result | |
812 of the expression contains the separation character. | |
813 | |
452 | 814 Examples: > |
7 | 815 :s@\n@\="\r" . expand("$HOME") . "\r"@ |
452 | 816 This replaces an end-of-line with a new line containing the value of $HOME. > |
817 | |
818 s/E/\="\<Char-0x20ac>"/g | |
1668 | 819 This replaces each 'E' character with a euro sign. Read more in |<Char->|. |
7 | 820 |
821 | |
32 | 822 4.3 Search and replace *search-replace* |
823 | |
824 *:pro* *:promptfind* | |
7 | 825 :promptf[ind] [string] |
826 Put up a Search dialog. When [string] is given, it is | |
827 used as the initial search string. | |
828 {only for Win32, Motif and GTK GUI} | |
829 | |
830 *:promptr* *:promptrepl* | |
831 :promptr[epl] [string] | |
832 Put up a Search/Replace dialog. When [string] is | |
833 given, it is used as the initial search string. | |
834 {only for Win32, Motif and GTK GUI} | |
835 | |
32 | 836 |
837 4.4 Changing tabs *change-tabs* | |
7 | 838 *:ret* *:retab* |
839 :[range]ret[ab][!] [new_tabstop] | |
840 Replace all sequences of white-space containing a | |
841 <Tab> with new strings of white-space using the new | |
842 tabstop value given. If you do not specify a new | |
843 tabstop size or it is zero, Vim uses the current value | |
844 of 'tabstop'. | |
845 The current value of 'tabstop' is always used to | |
846 compute the width of existing tabs. | |
847 With !, Vim also replaces strings of only normal | |
848 spaces with tabs where appropriate. | |
849 With 'expandtab' on, Vim replaces all tabs with the | |
850 appropriate number of spaces. | |
851 This command sets 'tabstop' to the new value given, | |
852 and if performed on the whole file, which is default, | |
853 should not make any visible change. | |
854 Careful: This command modifies any <Tab> characters | |
855 inside of strings in a C program. Use "\t" to avoid | |
856 this (that's a good habit anyway). | |
857 ":retab!" may also change a sequence of spaces by | |
858 <Tab> characters, which can mess up a printf(). | |
859 {not in Vi} | |
860 Not available when |+ex_extra| feature was disabled at | |
861 compile time. | |
862 | |
863 *retab-example* | |
864 Example for using autocommands and ":retab" to edit a file which is stored | |
865 with tabstops at 8 but edited with tabstops set at 4. Warning: white space | |
866 inside of strings can change! Also see 'softtabstop' option. > | |
867 | |
868 :auto BufReadPost *.xx retab! 4 | |
869 :auto BufWritePre *.xx retab! 8 | |
870 :auto BufWritePost *.xx retab! 4 | |
871 :auto BufNewFile *.xx set ts=4 | |
872 | |
873 ============================================================================== | |
874 5. Copying and moving text *copy-move* | |
875 | |
876 *quote* | |
877 "{a-zA-Z0-9.%#:-"} Use register {a-zA-Z0-9.%#:-"} for next delete, yank | |
878 or put (use uppercase character to append with | |
879 delete and yank) ({.%#:} only work with put). | |
880 | |
881 *:reg* *:registers* | |
882 :reg[isters] Display the contents of all numbered and named | |
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
883 registers. If a register is written to for |:redir| |
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
884 it will not be listed. |
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
885 {not in Vi} |
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
886 |
7 | 887 |
888 :reg[isters] {arg} Display the contents of the numbered and named | |
889 registers that are mentioned in {arg}. For example: > | |
890 :dis 1a | |
891 < to display registers '1' and 'a'. Spaces are allowed | |
892 in {arg}. {not in Vi} | |
893 | |
894 *:di* *:display* | |
895 :di[splay] [arg] Same as :registers. {not in Vi} | |
896 | |
897 *y* *yank* | |
898 ["x]y{motion} Yank {motion} text [into register x]. When no | |
899 characters are to be yanked (e.g., "y0" in column 1), | |
900 this is an error when 'cpoptions' includes the 'E' | |
901 flag. | |
902 | |
903 *yy* | |
904 ["x]yy Yank [count] lines [into register x] |linewise|. | |
905 | |
906 *Y* | |
907 ["x]Y yank [count] lines [into register x] (synonym for | |
908 yy, |linewise|). If you like "Y" to work from the | |
909 cursor to the end of line (which is more logical, | |
910 but not Vi-compatible) use ":map Y y$". | |
911 | |
912 *v_y* | |
913 {Visual}["x]y Yank the highlighted text [into register x] (for | |
914 {Visual} see |Visual-mode|). {not in Vi} | |
915 | |
916 *v_Y* | |
917 {Visual}["x]Y Yank the highlighted lines [into register x] (for | |
918 {Visual} see |Visual-mode|). {not in Vi} | |
919 | |
2791 | 920 *:y* *:yank* *E850* |
921 :[range]y[ank] [x] Yank [range] lines [into register x]. Yanking to the | |
2826 | 922 "* or "+ registers is possible only when the |
923 |+clipboard| feature is included. | |
7 | 924 |
925 :[range]y[ank] [x] {count} | |
926 Yank {count} lines, starting with last line number | |
927 in [range] (default: current line |cmdline-ranges|), | |
928 [into register x]. | |
929 | |
930 *p* *put* *E353* | |
931 ["x]p Put the text [from register x] after the cursor | |
932 [count] times. {Vi: no count} | |
933 | |
934 *P* | |
935 ["x]P Put the text [from register x] before the cursor | |
936 [count] times. {Vi: no count} | |
937 | |
938 *<MiddleMouse>* | |
939 ["x]<MiddleMouse> Put the text from a register before the cursor [count] | |
940 times. Uses the "* register, unless another is | |
856 | 941 specified. |
36 | 942 Leaves the cursor at the end of the new text. |
943 Using the mouse only works when 'mouse' contains 'n' | |
944 or 'a'. | |
7 | 945 {not in Vi} |
946 If you have a scrollwheel and often accidentally paste | |
947 text, you can use these mappings to disable the | |
948 pasting with the middle mouse button: > | |
949 :map <MiddleMouse> <Nop> | |
950 :imap <MiddleMouse> <Nop> | |
951 < You might want to disable the multi-click versions | |
952 too, see |double-click|. | |
953 | |
954 *gp* | |
955 ["x]gp Just like "p", but leave the cursor just after the new | |
956 text. {not in Vi} | |
957 | |
958 *gP* | |
959 ["x]gP Just like "P", but leave the cursor just after the new | |
960 text. {not in Vi} | |
961 | |
962 *:pu* *:put* | |
963 :[line]pu[t] [x] Put the text [from register x] after [line] (default | |
964 current line). This always works |linewise|, thus | |
965 this command can be used to put a yanked block as new | |
966 lines. | |
236 | 967 The cursor is left on the first non-blank in the last |
968 new line. | |
7 | 969 The register can also be '=' followed by an optional |
970 expression. The expression continues until the end of | |
971 the command. You need to escape the '|' and '"' | |
972 characters to prevent them from terminating the | |
973 command. Example: > | |
974 :put ='path' . \",/test\" | |
975 < If there is no expression after '=', Vim uses the | |
976 previous expression. You can see it with ":dis =". | |
977 | |
978 :[line]pu[t]! [x] Put the text [from register x] before [line] (default | |
979 current line). | |
980 | |
981 ["x]]p or *]p* *]<MiddleMouse>* | |
982 ["x]]<MiddleMouse> Like "p", but adjust the indent to the current line. | |
983 Using the mouse only works when 'mouse' contains 'n' | |
984 or 'a'. {not in Vi} | |
985 | |
986 ["x][P or *[P* | |
987 ["x]]P or *]P* | |
988 ["x][p or *[p* *[<MiddleMouse>* | |
989 ["x][<MiddleMouse> Like "P", but adjust the indent to the current line. | |
990 Using the mouse only works when 'mouse' contains 'n' | |
991 or 'a'. {not in Vi} | |
992 | |
993 You can use these commands to copy text from one place to another. Do this | |
994 by first getting the text into a register with a yank, delete or change | |
995 command, then inserting the register contents with a put command. You can | |
996 also use these commands to move text from one file to another, because Vim | |
997 preserves all registers when changing buffers (the CTRL-^ command is a quick | |
998 way to toggle between two files). | |
999 | |
1000 *linewise-register* *characterwise-register* | |
1001 You can repeat the put commands with "." (except for :put) and undo them. If | |
1002 the command that was used to get the text into the register was |linewise|, | |
1003 Vim inserts the text below ("p") or above ("P") the line where the cursor is. | |
1004 Otherwise Vim inserts the text after ("p") or before ("P") the cursor. With | |
1005 the ":put" command, Vim always inserts the text in the next line. You can | |
1006 exchange two characters with the command sequence "xp". You can exchange two | |
1007 lines with the command sequence "ddp". You can exchange two words with the | |
1008 command sequence "deep" (start with the cursor in the blank space before the | |
1009 first word). You can use the "']" or "`]" command after the put command to | |
1010 move the cursor to the end of the inserted text, or use "'[" or "`[" to move | |
1011 the cursor to the start. | |
1012 | |
1013 *put-Visual-mode* *v_p* *v_P* | |
1014 When using a put command like |p| or |P| in Visual mode, Vim will try to | |
1015 replace the selected text with the contents of the register. Whether this | |
1016 works well depends on the type of selection and the type of the text in the | |
1017 register. With blockwise selection it also depends on the size of the block | |
236 | 1018 and whether the corners are on an existing character. (Implementation detail: |
7 | 1019 it actually works by first putting the register after the selection and then |
236 | 1020 deleting the selection.) |
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
1021 The previously selected text is put in the unnamed register. If you want to |
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
1022 put the same text into a Visual selection several times you need to use |
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
1023 another register. E.g., yank the text to copy, Visually select the text to |
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
1024 replace and use "0p . You can repeat this as many times as you like, the |
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
1025 unnamed register will be changed each time. |
7 | 1026 |
1027 *blockwise-register* | |
1028 If you use a blockwise Visual mode command to get the text into the register, | |
1029 the block of text will be inserted before ("P") or after ("p") the cursor | |
1030 column in the current and next lines. Vim makes the whole block of text start | |
1031 in the same column. Thus the inserted text looks the same as when it was | |
1032 yanked or deleted. Vim may replace some <Tab> characters with spaces to make | |
1033 this happen. However, if the width of the block is not a multiple of a <Tab> | |
1034 width and the text after the inserted block contains <Tab>s, that text may be | |
1035 misaligned. | |
1036 | |
1037 Note that after a characterwise yank command, Vim leaves the cursor on the | |
1038 first yanked character that is closest to the start of the buffer. This means | |
1039 that "yl" doesn't move the cursor, but "yh" moves the cursor one character | |
1040 left. | |
1041 Rationale: In Vi the "y" command followed by a backwards motion would | |
1042 sometimes not move the cursor to the first yanked character, | |
1043 because redisplaying was skipped. In Vim it always moves to | |
1044 the first character, as specified by Posix. | |
1045 With a linewise yank command the cursor is put in the first line, but the | |
1046 column is unmodified, thus it may not be on the first yanked character. | |
1047 | |
1048 There are nine types of registers: *registers* *E354* | |
1049 1. The unnamed register "" | |
1050 2. 10 numbered registers "0 to "9 | |
1051 3. The small delete register "- | |
1052 4. 26 named registers "a to "z or "A to "Z | |
1053 5. four read-only registers ":, "., "% and "# | |
1054 6. the expression register "= | |
1055 7. The selection and drop registers "*, "+ and "~ | |
1056 8. The black hole register "_ | |
1057 9. Last search pattern register "/ | |
1058 | |
1059 1. Unnamed register "" *quote_quote* *quotequote* | |
1060 Vim fills this register with text deleted with the "d", "c", "s", "x" commands | |
1061 or copied with the yank "y" command, regardless of whether or not a specific | |
8 | 1062 register was used (e.g. "xdd). This is like the unnamed register is pointing |
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
1063 to the last used register. Thus when appending using an uppercase register |
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
1064 name, the unnamed register contains the same text as the named register. |
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
1065 An exception is the '_' register: "_dd does not store the deleted text in any |
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
1066 register. |
42 | 1067 Vim uses the contents of the unnamed register for any put command (p or P) |
1068 which does not specify a register. Additionally you can access it with the | |
1069 name '"'. This means you have to type two double quotes. Writing to the "" | |
1070 register writes to register "0. | |
7 | 1071 {Vi: register contents are lost when changing files, no '"'} |
1072 | |
1073 2. Numbered registers "0 to "9 *quote_number* *quote0* *quote1* | |
1074 *quote2* *quote3* *quote4* *quote9* | |
1075 Vim fills these registers with text from yank and delete commands. | |
1076 Numbered register 0 contains the text from the most recent yank command, | |
1077 unless the command specified another register with ["x]. | |
1078 Numbered register 1 contains the text deleted by the most recent delete or | |
1079 change command, unless the command specified another register or the text is | |
1080 less than one line (the small delete register is used then). An exception is | |
42 | 1081 made for the delete operator with these movement commands: |%|, |(|, |)|, |`|, |
1082 |/|, |?|, |n|, |N|, |{| and |}|. Register "1 is always used then (this is Vi | |
1083 compatible). The "- register is used as well if the delete is within a line. | |
7 | 1084 With each successive deletion or change, Vim shifts the previous contents |
1085 of register 1 into register 2, 2 into 3, and so forth, losing the previous | |
1086 contents of register 9. | |
1087 {Vi: numbered register contents are lost when changing files; register 0 does | |
1088 not exist} | |
1089 | |
1090 3. Small delete register "- *quote_-* *quote-* | |
1091 This register contains text from commands that delete less than one line, | |
1092 except when the command specifies a register with ["x]. | |
1093 {not in Vi} | |
1094 | |
1095 4. Named registers "a to "z or "A to "Z *quote_alpha* *quotea* | |
1096 Vim fills these registers only when you say so. Specify them as lowercase | |
1097 letters to replace their previous contents or as uppercase letters to append | |
164 | 1098 to their previous contents. When the '>' flag is present in 'cpoptions' then |
1099 a line break is inserted before the appended text. | |
7 | 1100 |
1101 5. Read-only registers ":, "., "% and "# | |
1102 These are '%', '#', ':' and '.'. You can use them only with the "p", "P", | |
1103 and ":put" commands and with CTRL-R. {not in Vi} | |
1104 *quote_.* *quote.* *E29* | |
1105 ". Contains the last inserted text (the same as what is inserted | |
1106 with the insert mode commands CTRL-A and CTRL-@). Note: this | |
1107 doesn't work with CTRL-R on the command-line. It works a bit | |
1108 differently, like inserting the text instead of putting it | |
1109 ('textwidth' and other options affect what is inserted). | |
1110 *quote_%* *quote%* | |
1111 "% Contains the name of the current file. | |
1112 *quote_#* *quote#* | |
1113 "# Contains the name of the alternate file. | |
1114 *quote_:* *quote:* *E30* | |
1115 ": Contains the most recent executed command-line. Example: Use | |
1116 "@:" to repeat the previous command-line command. | |
1117 The command-line is only stored in this register when at least | |
1118 one character of it was typed. Thus it remains unchanged if | |
1119 the command was completely from a mapping. | |
1120 {not available when compiled without the |+cmdline_hist| | |
1121 feature} | |
1122 | |
1121 | 1123 6. Expression register "= *quote_=* *quote=* *@=* |
7 | 1124 This is not really a register that stores text, but is a way to use an |
1125 expression in commands which use a register. The expression register is | |
1126 read-only; you cannot put text into it. After the '=', the cursor moves to | |
1127 the command-line, where you can enter any expression (see |expression|). All | |
1128 normal command-line editing commands are available, including a special | |
1129 history for expressions. When you end the command-line by typing <CR>, Vim | |
1130 computes the result of the expression. If you end it with <Esc>, Vim abandons | |
1131 the expression. If you do not enter an expression, Vim uses the previous | |
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
1132 expression (like with the "/" command). |
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
1133 |
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
1134 The expression must evaluate to a String. A Number is always automatically |
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
1135 converted to a String. For the "p" and ":put" command, if the result is a |
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
1136 Float it's converted into a String. If the result is a List each element is |
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
1137 turned into a String and used as a line. A Dictionary or FuncRef results in |
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
1138 an error message (use string() to convert). |
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
1139 |
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
1140 If the "= register is used for the "p" command, the String is split up at <NL> |
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
1141 characters. If the String ends in a <NL>, it is regarded as a linewise |
332 | 1142 register. {not in Vi} |
7 | 1143 |
1144 7. Selection and drop registers "*, "+ and "~ | |
2207
b17bbfa96fa0
Add the settabvar() and gettabvar() functions.
Bram Moolenaar <bram@vim.org>
parents:
2154
diff
changeset
|
1145 Use these registers for storing and retrieving the selected text for the GUI. |
7 | 1146 See |quotestar| and |quoteplus|. When the clipboard is not available or not |
571 | 1147 working, the unnamed register is used instead. For Unix systems the clipboard |
1148 is only available when the |+xterm_clipboard| feature is present. {not in Vi} | |
7 | 1149 |
1150 Note that there is only a distinction between "* and "+ for X11 systems. For | |
1151 an explanation of the difference, see |x11-selection|. Under MS-Windows, use | |
1152 of "* and "+ is actually synonymous and refers to the |gui-clipboard|. | |
1153 | |
1154 *quote_~* *quote~* *<Drop>* | |
1155 The read-only "~ register stores the dropped text from the last drag'n'drop | |
1156 operation. When something has been dropped onto Vim, the "~ register is | |
1157 filled in and the <Drop> pseudo key is sent for notification. You can remap | |
1158 this key if you want; the default action (for all modes) is to insert the | |
1159 contents of the "~ register at the cursor position. {not in Vi} | |
9 | 1160 {only available when compiled with the |+dnd| feature, currently only with the |
7 | 1161 GTK GUI} |
1162 | |
1163 Note: The "~ register is only used when dropping plain text onto Vim. | |
1164 Drag'n'drop of URI lists is handled internally. | |
1165 | |
1166 8. Black hole register "_ *quote_* | |
1167 When writing to this register, nothing happens. This can be used to delete | |
1168 text without affecting the normal registers. When reading from this register, | |
1169 nothing is returned. {not in Vi} | |
1170 | |
1171 9. Last search pattern register "/ *quote_/* *quote/* | |
1172 Contains the most recent search-pattern. This is used for "n" and 'hlsearch'. | |
1173 It is writable with ":let", you can change it to have 'hlsearch' highlight | |
1174 other matches without actually searching. You can't yank or delete into this | |
1621 | 1175 register. The search direction is available in |v:searchforward|. |
1176 Note that the valued is restored when returning from a function | |
1177 |function-search-undo|. | |
1178 {not in Vi} | |
7 | 1179 |
1180 *@/* | |
1181 You can write to a register with a ":let" command |:let-@|. Example: > | |
1182 :let @/ = "the" | |
1183 | |
1184 If you use a put command without specifying a register, Vim uses the register | |
1185 that was last filled (this is also the contents of the unnamed register). If | |
1186 you are confused, use the ":dis" command to find out what Vim will put (this | |
1187 command displays all named and numbered registers; the unnamed register is | |
1188 labelled '"'). | |
1189 | |
1190 The next three commands always work on whole lines. | |
1191 | |
1192 :[range]co[py] {address} *:co* *:copy* | |
1193 Copy the lines given by [range] to below the line | |
1194 given by {address}. | |
1195 | |
1196 *:t* | |
1197 :t Synonym for copy. | |
1198 | |
1199 :[range]m[ove] {address} *:m* *:mo* *:move* *E134* | |
1200 Move the lines given by [range] to below the line | |
1201 given by {address}. | |
1202 | |
1203 ============================================================================== | |
1204 6. Formatting text *formatting* | |
1205 | |
1206 :[range]ce[nter] [width] *:ce* *:center* | |
1207 Center lines in [range] between [width] columns | |
1208 (default 'textwidth' or 80 when 'textwidth' is 0). | |
1209 {not in Vi} | |
1210 Not available when |+ex_extra| feature was disabled at | |
1211 compile time. | |
1212 | |
1213 :[range]ri[ght] [width] *:ri* *:right* | |
1214 Right-align lines in [range] at [width] columns | |
1215 (default 'textwidth' or 80 when 'textwidth' is 0). | |
1216 {not in Vi} | |
1217 Not available when |+ex_extra| feature was disabled at | |
1218 compile time. | |
1219 | |
1220 *:le* *:left* | |
1221 :[range]le[ft] [indent] | |
1222 Left-align lines in [range]. Sets the indent in the | |
1223 lines to [indent] (default 0). {not in Vi} | |
1224 Not available when |+ex_extra| feature was disabled at | |
1225 compile time. | |
1226 | |
1227 *gq* | |
216 | 1228 gq{motion} Format the lines that {motion} moves over. |
667 | 1229 Formatting is done with one of three methods: |
1230 1. If 'formatexpr' is not empty the expression is | |
1231 evaluated. This can differ for each buffer. | |
670 | 1232 2. If 'formatprg' is not empty an external program |
667 | 1233 is used. |
843 | 1234 3. Otherwise formatting is done internally. |
667 | 1235 |
1236 In the third case the 'textwidth' option controls the | |
1237 length of each formatted line (see below). | |
216 | 1238 If the 'textwidth' option is 0, the formatted line |
1239 length is the screen width (with a maximum width of | |
667 | 1240 79). |
7 | 1241 The 'formatoptions' option controls the type of |
1242 formatting |fo-table|. | |
216 | 1243 The cursor is left on the first non-blank of the last |
1244 formatted line. | |
7 | 1245 NOTE: The "Q" command formerly performed this |
1246 function. If you still want to use "Q" for | |
1247 formatting, use this mapping: > | |
1248 :nnoremap Q gq | |
1249 | |
1250 gqgq *gqgq* *gqq* | |
2434
86532ee3ea41
Updated runtime files. Add logcheck filetype plugin. (James Vega)
Bram Moolenaar <bram@vim.org>
parents:
2413
diff
changeset
|
1251 gqq Format the current line. With a count format that |
86532ee3ea41
Updated runtime files. Add logcheck filetype plugin. (James Vega)
Bram Moolenaar <bram@vim.org>
parents:
2413
diff
changeset
|
1252 many lines. {not in Vi} |
7 | 1253 |
1254 *v_gq* | |
1255 {Visual}gq Format the highlighted text. (for {Visual} see | |
1256 |Visual-mode|). {not in Vi} | |
1257 | |
1258 *gw* | |
1259 gw{motion} Format the lines that {motion} moves over. Similar to | |
1260 |gq| but puts the cursor back at the same position in | |
667 | 1261 the text. However, 'formatprg' and 'formatexpr' are |
1262 not used. {not in Vi} | |
7 | 1263 |
9 | 1264 gwgw *gwgw* *gww* |
1265 gww Format the current line as with "gw". {not in Vi} | |
1266 | |
1267 *v_gw* | |
1268 {Visual}gw Format the highlighted text as with "gw". (for | |
1269 {Visual} see |Visual-mode|). {not in Vi} | |
1270 | |
7 | 1271 Example: To format the current paragraph use: *gqap* > |
1272 gqap | |
1273 | |
1274 The "gq" command leaves the cursor in the line where the motion command takes | |
1275 the cursor. This allows you to repeat formatting repeated with ".". This | |
1276 works well with "gqj" (format current and next line) and "gq}" (format until | |
1277 end of paragraph). Note: When 'formatprg' is set, "gq" leaves the cursor on | |
1278 the first formatted line (as with using a filter command). | |
1279 | |
1280 If you want to format the current paragraph and continue where you were, use: > | |
1281 gwap | |
1282 If you always want to keep paragraphs formatted you may want to add the 'a' | |
1283 flag to 'formatoptions'. See |auto-format|. | |
1284 | |
1285 If the 'autoindent' option is on, Vim uses the indent of the first line for | |
1286 the following lines. | |
1287 | |
1288 Formatting does not change empty lines (but it does change lines with only | |
1289 white space!). | |
1290 | |
1291 The 'joinspaces' option is used when lines are joined together. | |
1292 | |
667 | 1293 You can set the 'formatexpr' option to an expression or the 'formatprg' option |
1294 to the name of an external program for Vim to use for text formatting. The | |
1295 'textwidth' and other options have no effect on formatting by an external | |
1296 program. | |
7 | 1297 |
1298 *right-justify* | |
1299 There is no command in Vim to right justify text. You can do it with | |
1300 an external command, like "par" (e.g.: "!}par" to format until the end of the | |
1301 paragraph) or set 'formatprg' to "par". | |
1302 | |
1303 *format-comments* | |
1621 | 1304 An overview of comment formatting is in section |30.6| of the user manual. |
1305 | |
1306 Vim can automatically insert and format comments in a special way. Vim | |
1307 recognizes a comment by a specific string at the start of the line (ignoring | |
1308 white space). Three types of comments can be used: | |
7 | 1309 |
1310 - A comment string that repeats at the start of each line. An example is the | |
1311 type of comment used in shell scripts, starting with "#". | |
1312 - A comment string that occurs only in the first line, not in the following | |
1313 lines. An example is this list with dashes. | |
1314 - Three-piece comments that have a start string, an end string, and optional | |
1315 lines in between. The strings for the start, middle and end are different. | |
1621 | 1316 An example is the C style comment: |
7 | 1317 /* |
1318 * this is a C comment | |
1319 */ | |
1320 | |
1321 The 'comments' option is a comma-separated list of parts. Each part defines a | |
1322 type of comment string. A part consists of: | |
1323 {flags}:{string} | |
1324 | |
1325 {string} is the literal text that must appear. | |
1326 | |
1327 {flags}: | |
1328 n Nested comment. Nesting with mixed parts is allowed. If 'comments' | |
1329 is "n:),n:>" a line starting with "> ) >" is a comment. | |
1330 | |
1331 b Blank (<Space>, <Tab> or <EOL>) required after {string}. | |
1332 | |
1333 f Only the first line has the comment string. Do not repeat comment on | |
1334 the next line, but preserve indentation (e.g., a bullet-list). | |
1335 | |
1336 s Start of three-piece comment | |
1337 | |
1338 m Middle of a three-piece comment | |
1339 | |
1340 e End of a three-piece comment | |
1341 | |
1621 | 1342 l Left align. Used together with 's' or 'e', the leftmost character of |
1343 start or end will line up with the leftmost character from the middle. | |
1344 This is the default and can be omitted. See below for more details. | |
7 | 1345 |
1621 | 1346 r Right align. Same as above but rightmost instead of leftmost. See |
1347 below for more details. | |
7 | 1348 |
1621 | 1349 O Don't consider this comment for the "O" command. |
7 | 1350 |
1351 x Allows three-piece comments to be ended by just typing the last | |
1621 | 1352 character of the end-comment string as the first action on a new |
1353 line when the middle-comment string has been inserted automatically. | |
1354 See below for more details. | |
7 | 1355 |
1356 {digits} | |
1621 | 1357 When together with 's' or 'e': add {digit} amount of offset to an |
1358 automatically inserted middle or end comment leader. The offset begins | |
1359 from a left alignment. See below for more details. | |
7 | 1360 |
1361 -{digits} | |
1362 Like {digits} but reduce the indent. This only works when there is | |
1363 some indent for the start or end part that can be removed. | |
1364 | |
1365 When a string has none of the 'f', 's', 'm' or 'e' flags, Vim assumes the | |
1366 comment string repeats at the start of each line. The flags field may be | |
1367 empty. | |
1368 | |
1369 Any blank space in the text before and after the {string} is part of the | |
1370 {string}, so do not include leading or trailing blanks unless the blanks are a | |
1371 required part of the comment string. | |
1372 | |
1373 When one comment leader is part of another, specify the part after the whole. | |
1374 For example, to include both "-" and "->", use > | |
1375 :set comments=f:->,f:- | |
1376 | |
1377 A three-piece comment must always be given as start,middle,end, with no other | |
1378 parts in between. An example of a three-piece comment is > | |
1379 sr:/*,mb:*,ex:*/ | |
1380 for C-comments. To avoid recognizing "*ptr" as a comment, the middle string | |
1381 includes the 'b' flag. For three-piece comments, Vim checks the text after | |
1382 the start and middle strings for the end string. If Vim finds the end string, | |
1383 the comment does not continue on the next line. Three-piece comments must | |
1384 have a middle string because otherwise Vim can't recognize the middle lines. | |
1385 | |
1386 Notice the use of the "x" flag in the above three-piece comment definition. | |
1387 When you hit Return in a C-comment, Vim will insert the middle comment leader | |
1621 | 1388 for the new line: " * ". To close this comment you just have to type "/" |
7 | 1389 before typing anything else on the new line. This will replace the |
1621 | 1390 middle-comment leader with the end-comment leader and apply any specified |
1391 alignment, leaving just " */". There is no need to hit BackSpace first. | |
1392 | |
2826 | 1393 When there is a match with a middle part, but there also is a maching end part |
1394 which is longer, the end part is used. This makes a C style comment work | |
1395 without requiring the middle part to end with a space. | |
1621 | 1396 |
1397 Here is an example of alignment flags at work to make a comment stand out | |
2826 | 1398 (kind of looks like a 1 too). Consider comment string: > |
1399 :set comments=sr:/***,m:**,ex-2:******/ | |
1400 < | |
1401 /*** ~ | |
1402 **<--right aligned from "r" flag ~ | |
1403 ** ~ | |
1404 offset 2 spaces for the "-2" flag--->** ~ | |
1405 ******/ ~ | |
1621 | 1406 In this case, the first comment was typed, then return was pressed 4 times, |
1407 then "/" was pressed to end the comment. | |
7 | 1408 |
1621 | 1409 Here are some finer points of three part comments. There are three times when |
1410 alignment and offset flags are taken into consideration: opening a new line | |
1411 after a start-comment, opening a new line before an end-comment, and | |
1412 automatically ending a three-piece comment. The end alignment flag has a | |
1413 backwards perspective; the result is that the same alignment flag used with | |
1414 "s" and "e" will result in the same indent for the starting and ending pieces. | |
1415 Only one alignment per comment part is meant to be used, but an offset number | |
1416 will override the "r" and "l" flag. | |
1417 | |
1418 Enabling 'cindent' will override the alignment flags in many cases. | |
1419 Reindenting using a different method like |gq| or |=| will not consult | |
1420 alignment flags either. The same behaviour can be defined in those other | |
1421 formatting options. One consideration is that 'cindent' has additional options | |
1422 for context based indenting of comments but cannot replicate many three piece | |
2826 | 1423 indent alignments. However, 'indentexpr' has the ability to work better with |
1424 three piece comments. | |
1621 | 1425 |
1426 Other examples: > | |
7 | 1427 "b:*" Includes lines starting with "*", but not if the "*" is |
1428 followed by a non-blank. This avoids a pointer dereference | |
1429 like "*str" to be recognized as a comment. | |
1430 "n:>" Includes a line starting with ">", ">>", ">>>", etc. | |
1431 "fb:-" Format a list that starts with "- ". | |
1432 | |
1433 By default, "b:#" is included. This means that a line that starts with | |
1434 "#include" is not recognized as a comment line. But a line that starts with | |
1435 "# define" is recognized. This is a compromise. | |
1436 | |
1437 {not available when compiled without the |+comments| feature} | |
1438 | |
1439 *fo-table* | |
1440 You can use the 'formatoptions' option to influence how Vim formats text. | |
1441 'formatoptions' is a string that can contain any of the letters below. The | |
1442 default setting is "tcq". You can separate the option letters with commas for | |
1443 readability. | |
1444 | |
1445 letter meaning when present in 'formatoptions' ~ | |
1446 | |
1121 | 1447 t Auto-wrap text using textwidth |
7 | 1448 c Auto-wrap comments using textwidth, inserting the current comment |
1449 leader automatically. | |
1450 r Automatically insert the current comment leader after hitting | |
1451 <Enter> in Insert mode. | |
1452 o Automatically insert the current comment leader after hitting 'o' or | |
1453 'O' in Normal mode. | |
1454 q Allow formatting of comments with "gq". | |
1455 Note that formatting will not change blank lines or lines containing | |
1456 only the comment leader. A new paragraph starts after such a line, | |
1457 or when the comment leader changes. | |
1458 w Trailing white space indicates a paragraph continues in the next line. | |
1459 A line that ends in a non-white character ends a paragraph. | |
1460 a Automatic formatting of paragraphs. Every time text is inserted or | |
1461 deleted the paragraph will be reformatted. See |auto-format|. | |
1462 When the 'c' flag is present this only happens for recognized | |
1463 comments. | |
41 | 1464 n When formatting text, recognize numbered lists. This actually uses |
1465 the 'formatlistpat' option, thus any kind of list can be used. The | |
1466 indent of the text after the number is used for the next line. The | |
1621 | 1467 default is to find a number, optionally followed by '.', ':', ')', |
41 | 1468 ']' or '}'. Note that 'autoindent' must be set too. Doesn't work |
1469 well together with "2". | |
7 | 1470 Example: > |
1471 1. the first item | |
1472 wraps | |
1473 2. the second item | |
1474 2 When formatting text, use the indent of the second line of a paragraph | |
1475 for the rest of the paragraph, instead of the indent of the first | |
1476 line. This supports paragraphs in which the first line has a | |
1477 different indent than the rest. Note that 'autoindent' must be set | |
1478 too. Example: > | |
1479 first line of a paragraph | |
1480 second line of the same paragraph | |
1481 third line. | |
1482 v Vi-compatible auto-wrapping in insert mode: Only break a line at a | |
1483 blank that you have entered during the current insert command. (Note: | |
1484 this is not 100% Vi compatible. Vi has some "unexpected features" or | |
1485 bugs in this area. It uses the screen column instead of the line | |
1486 column.) | |
1487 b Like 'v', but only auto-wrap if you enter a blank at or before | |
1488 the wrap margin. If the line was longer than 'textwidth' when you | |
1489 started the insert, or you do not enter a blank in the insert before | |
1490 reaching 'textwidth', Vim does not perform auto-wrapping. | |
1491 l Long lines are not broken in insert mode: When a line was longer than | |
1492 'textwidth' when the insert command started, Vim does not | |
1493 automatically format it. | |
1494 m Also break at a multi-byte character above 255. This is useful for | |
1495 Asian text where every character is a word on its own. | |
1496 M When joining lines, don't insert a space before or after a multi-byte | |
1497 character. Overrules the 'B' flag. | |
1498 B When joining lines, don't insert a space between two multi-byte | |
1499 characters. Overruled by the 'M' flag. | |
1500 1 Don't break a line after a one-letter word. It's broken before it | |
1501 instead (if possible). | |
1502 | |
1503 | |
1504 With 't' and 'c' you can specify when Vim performs auto-wrapping: | |
1505 value action ~ | |
1506 "" no automatic formatting (you can use "gq" for manual formatting) | |
1507 "t" automatic formatting of text, but not comments | |
1508 "c" automatic formatting for comments, but not text (good for C code) | |
1509 "tc" automatic formatting for text and comments | |
1510 | |
867 | 1511 Note that when 'textwidth' is 0, Vim does no automatic formatting anyway (but |
1512 does insert comment leaders according to the 'comments' option). An exception | |
1513 is when the 'a' flag is present. |auto-format| | |
7 | 1514 |
1515 Note that when 'paste' is on, Vim does no formatting at all. | |
1516 | |
1517 Note that 'textwidth' can be non-zero even if Vim never performs auto-wrapping; | |
1518 'textwidth' is still useful for formatting with "gq". | |
1519 | |
1520 If the 'comments' option includes "/*", "*" and/or "*/", then Vim has some | |
1521 built in stuff to treat these types of comments a bit more cleverly. | |
1522 Opening a new line before or after "/*" or "*/" (with 'r' or 'o' present in | |
1523 'formatoptions') gives the correct start of the line automatically. The same | |
236 | 1524 happens with formatting and auto-wrapping. Opening a line after a line |
7 | 1525 starting with "/*" or "*" and containing "*/", will cause no comment leader to |
1526 be inserted, and the indent of the new line is taken from the line containing | |
1527 the start of the comment. | |
1528 E.g.: | |
1529 /* ~ | |
1530 * Your typical comment. ~ | |
1531 */ ~ | |
1532 The indent on this line is the same as the start of the above | |
1533 comment. | |
1534 | |
1535 All of this should be really cool, especially in conjunction with the new | |
1536 :autocmd command to prepare different settings for different types of file. | |
1537 | |
1538 Some examples: | |
1539 for C code (only format comments): > | |
1540 :set fo=croq | |
1541 < for Mail/news (format all, don't start comment with "o" command): > | |
1542 :set fo=tcrq | |
1543 < | |
1544 | |
1545 Automatic formatting *auto-format* | |
1546 | |
1547 When the 'a' flag is present in 'formatoptions' text is formatted | |
1548 automatically when inserting text or deleting text. This works nice for | |
1549 editing text paragraphs. A few hints on how to use this: | |
1550 | |
1551 - You need to properly define paragraphs. The simplest is paragraphs that are | |
1552 separated by a blank line. When there is no separating blank line, consider | |
1553 using the 'w' flag and adding a space at the end of each line in the | |
1554 paragraphs except the last one. | |
1555 | |
1556 - You can set the 'formatoptions' based on the type of file |filetype| or | |
1557 specifically for one file with a |modeline|. | |
1558 | |
1559 - Set 'formatoptions' to "aw2tq" to make text with indents like this: | |
1560 | |
1561 bla bla foobar bla | |
1562 bla foobar bla foobar bla | |
1563 bla bla foobar bla | |
1564 bla foobar bla bla foobar | |
1565 | |
1566 - Add the 'c' flag to only auto-format comments. Useful in source code. | |
1567 | |
867 | 1568 - Set 'textwidth' to the desired width. If it is zero then 79 is used, or the |
1569 width of the screen if this is smaller. | |
1570 | |
7 | 1571 And a few warnings: |
1572 | |
1573 - When part of the text is not properly separated in paragraphs, making | |
1574 changes in this text will cause it to be formatted anyway. Consider doing > | |
1575 | |
1576 :set fo-=a | |
1577 | |
1578 - When using the 'w' flag (trailing space means paragraph continues) and | |
1579 deleting the last line of a paragraph with |dd|, the paragraph will be | |
1580 joined with the next one. | |
1581 | |
1582 - Changed text is saved for undo. Formatting is also a change. Thus each | |
1583 format action saves text for undo. This may consume quite a lot of memory. | |
1584 | |
1585 - Formatting a long paragraph and/or with complicated indenting may be slow. | |
1586 | |
282 | 1587 ============================================================================== |
1588 7. Sorting text *sorting* | |
1589 | |
1590 Vim has a sorting function and a sorting command. The sorting function can be | |
1591 found here: |sort()|. | |
1592 | |
1593 *:sor* *:sort* | |
826 | 1594 :[range]sor[t][!] [i][u][r][n][x][o] [/{pattern}/] |
586 | 1595 Sort lines in [range]. When no range is given all |
1596 lines are sorted. | |
282 | 1597 |
1598 With [!] the order is reversed. | |
1599 | |
1600 With [i] case is ignored. | |
1601 | |
293 | 1602 With [n] sorting is done on the first decimal number |
826 | 1603 in the line (after or inside a {pattern} match). |
1698 | 1604 One leading '-' is included in the number. |
293 | 1605 |
1606 With [x] sorting is done on the first hexadecimal | |
826 | 1607 number in the line (after or inside a {pattern} |
1608 match). A leading "0x" or "0X" is ignored. | |
1698 | 1609 One leading '-' is included in the number. |
293 | 1610 |
1611 With [o] sorting is done on the first octal number in | |
826 | 1612 the line (after or inside a {pattern} match). |
293 | 1613 |
282 | 1614 With [u] only keep the first of a sequence of |
1615 identical lines (ignoring case when [i] is used). | |
826 | 1616 Without this flag, a sequence of identical lines |
1617 will be kept in their original order. | |
293 | 1618 Note that leading and trailing white space may cause |
1619 lines to be different. | |
282 | 1620 |
826 | 1621 When /{pattern}/ is specified and there is no [r] flag |
1622 the text matched with {pattern} is skipped, so that | |
1623 you sort on what comes after the match. | |
282 | 1624 Instead of the slash any non-letter can be used. |
1625 For example, to sort on the second comma-separated | |
1626 field: > | |
1627 :sort /[^,]*,/ | |
1628 < To sort on the text at virtual column 10 (thus | |
1629 ignoring the difference between tabs and spaces): > | |
1630 :sort /.*\%10v/ | |
824 | 1631 < To sort on the first number in the line, no matter |
1632 what is in front of it: > | |
1621 | 1633 :sort /.\{-}\ze\d/ |
1634 < (Explanation: ".\{-}" matches any text, "\ze" sets the | |
1635 end of the match and \d matches a digit.) | |
1636 With [r] sorting is done on the matching {pattern} | |
826 | 1637 instead of skipping past it as described above. |
1638 For example, to sort on only the first three letters | |
1639 of each line: > | |
1640 :sort /\a\a\a/ r | |
1641 | |
1642 < If a {pattern} is used, any lines which don't have a | |
1643 match for {pattern} are kept in their current order, | |
1644 but separate from the lines which do match {pattern}. | |
1645 If you sorted in reverse, they will be in reverse | |
1646 order after the sorted lines, otherwise they will be | |
1647 in their original order, right before the sorted | |
1648 lines. | |
1649 | |
1314 | 1650 If {pattern} is empty (e.g. // is specified), the |
1651 last search pattern is used. This allows trying out | |
1652 a pattern first. | |
1653 | |
293 | 1654 Note that using ":sort" with ":global" doesn't sort the matching lines, it's |
1655 quite useless. | |
7 | 1656 |
359 | 1657 The details about sorting depend on the library function used. There is no |
1658 guarantee that sorting is "stable" or obeys the current locale. You will have | |
1659 to try it out. | |
1660 | |
826 | 1661 The sorting can be interrupted, but if you interrupt it too late in the |
1662 process you may end up with duplicated lines. This also depends on the system | |
1663 library function used. | |
481 | 1664 |
7 | 1665 vim:tw=78:ts=8:ft=help:norl: |