1*insert.txt* For Vim version 7.4. Last change: 2016 Jan 31 2 3 4 VIM REFERENCE MANUAL by Bram Moolenaar 5 6 7 *Insert* *Insert-mode* 8Inserting and replacing text *mode-ins-repl* 9 10Most of this file is about Insert and Replace mode. At the end are a few 11commands for inserting text in other ways. 12 13An overview of the most often used commands can be found in chapter 24 of the 14user manual |usr_24.txt|. 15 161. Special keys |ins-special-keys| 172. Special special keys |ins-special-special| 183. 'textwidth' and 'wrapmargin' options |ins-textwidth| 194. 'expandtab', 'smarttab' and 'softtabstop' options |ins-expandtab| 205. Replace mode |Replace-mode| 216. Virtual Replace mode |Virtual-Replace-mode| 227. Insert mode completion |ins-completion| 238. Insert mode commands |inserting| 249. Ex insert commands |inserting-ex| 2510. Inserting a file |inserting-file| 26 27Also see 'virtualedit', for moving the cursor to positions where there is no 28character. Useful for editing a table. 29 30============================================================================== 311. Special keys *ins-special-keys* 32 33In Insert and Replace mode, the following characters have a special meaning; 34other characters are inserted directly. To insert one of these special 35characters into the buffer, precede it with CTRL-V. To insert a <Nul> 36character use "CTRL-V CTRL-@" or "CTRL-V 000". On some systems, you have to 37use "CTRL-V 003" to insert a CTRL-C. Note: When CTRL-V is mapped you can 38often use CTRL-Q instead |i_CTRL-Q|. 39 40If you are working in a special language mode when inserting text, see the 41'langmap' option, |'langmap'|, on how to avoid switching this mode on and off 42all the time. 43 44If you have 'insertmode' set, <Esc> and a few other keys get another meaning. 45See |'insertmode'|. 46 47char action ~ 48----------------------------------------------------------------------- 49 *i_CTRL-[* *i_<Esc>* 50<Esc> or CTRL-[ End insert or Replace mode, go back to Normal mode. Finish 51 abbreviation. 52 Note: If your <Esc> key is hard to hit on your keyboard, train 53 yourself to use CTRL-[. 54 If Esc doesn't work and you are using a Mac, try CTRL-Esc. 55 Or disable Listening under Accessibility preferences. 56 *i_CTRL-C* 57CTRL-C Quit insert mode, go back to Normal mode. Do not check for 58 abbreviations. Does not trigger the |InsertLeave| autocommand 59 event. 60 61 *i_CTRL-@* 62CTRL-@ Insert previously inserted text and stop insert. {Vi: only 63 when typed as first char, only up to 128 chars} 64 *i_CTRL-A* 65CTRL-A Insert previously inserted text. {not in Vi} 66 67 *i_CTRL-H* *i_<BS>* *i_BS* 68<BS> or CTRL-H Delete the character before the cursor (see |i_backspacing| 69 about joining lines). 70 See |:fixdel| if your <BS> key does not do what you want. 71 {Vi: does not delete autoindents} 72 *i_<Del>* *i_DEL* 73<Del> Delete the character under the cursor. If the cursor is at 74 the end of the line, and the 'backspace' option includes 75 "eol", delete the <EOL>; the next line is appended after the 76 current one. 77 See |:fixdel| if your <Del> key does not do what you want. 78 {not in Vi} 79 *i_CTRL-W* 80CTRL-W Delete the word before the cursor (see |i_backspacing| about 81 joining lines). See the section "word motions", 82 |word-motions|, for the definition of a word. 83 *i_CTRL-U* 84CTRL-U Delete all entered characters before the cursor in the current 85 line. If there are no newly entered characters and 86 'backspace' is not empty, delete all characters before the 87 cursor in the current line. 88 See |i_backspacing| about joining lines. 89 *i_CTRL-I* *i_<Tab>* *i_Tab* 90<Tab> or CTRL-I Insert a tab. If the 'expandtab' option is on, the 91 equivalent number of spaces is inserted (use CTRL-V <Tab> to 92 avoid the expansion; use CTRL-Q <Tab> if CTRL-V is mapped 93 |i_CTRL-Q|). See also the 'smarttab' option and 94 |ins-expandtab|. 95 *i_CTRL-J* *i_<NL>* 96<NL> or CTRL-J Begin new line. 97 *i_CTRL-M* *i_<CR>* 98<CR> or CTRL-M Begin new line. 99 *i_CTRL-K* 100CTRL-K {char1} [char2] 101 Enter digraph (see |digraphs|). When {char1} is a special 102 key, the code for that key is inserted in <> form. For 103 example, the string "<S-Space>" can be entered by typing 104 <C-K><S-Space> (two keys). Neither char is considered for 105 mapping. {not in Vi} 106 107CTRL-N Find next keyword (see |i_CTRL-N|). {not in Vi} 108CTRL-P Find previous keyword (see |i_CTRL-P|). {not in Vi} 109 110CTRL-R {0-9a-z"%#*+:.-=} *i_CTRL-R* 111 Insert the contents of a register. Between typing CTRL-R and 112 the second character, '"' will be displayed to indicate that 113 you are expected to enter the name of a register. 114 The text is inserted as if you typed it, but mappings and 115 abbreviations are not used. If you have options like 116 'textwidth', 'formatoptions', or 'autoindent' set, this will 117 influence what will be inserted. This is different from what 118 happens with the "p" command and pasting with the mouse. 119 Special registers: 120 '"' the unnamed register, containing the text of 121 the last delete or yank 122 '%' the current file name 123 '#' the alternate file name 124 '*' the clipboard contents (X11: primary selection) 125 '+' the clipboard contents 126 '/' the last search pattern 127 ':' the last command-line 128 '.' the last inserted text 129 '-' the last small (less than a line) delete 130 *i_CTRL-R_=* 131 '=' the expression register: you are prompted to 132 enter an expression (see |expression|) 133 Note that 0x80 (128 decimal) is used for 134 special keys. E.g., you can use this to move 135 the cursor up: 136 CTRL-R ="\<Up>" 137 Use CTRL-R CTRL-R to insert text literally. 138 When the result is a |List| the items are used 139 as lines. They can have line breaks inside 140 too. 141 When the result is a Float it's automatically 142 converted to a String. 143 When append() or setline() is invoked the undo 144 sequence will be broken. 145 See |registers| about registers. {not in Vi} 146 147CTRL-R CTRL-R {0-9a-z"%#*+/:.-=} *i_CTRL-R_CTRL-R* 148 Insert the contents of a register. Works like using a single 149 CTRL-R, but the text is inserted literally, not as if typed. 150 This differs when the register contains characters like <BS>. 151 Example, where register a contains "ab^Hc": > 152 CTRL-R a results in "ac". 153 CTRL-R CTRL-R a results in "ab^Hc". 154< Options 'textwidth', 'formatoptions', etc. still apply. If 155 you also want to avoid these, use CTRL-R CTRL-O, see below. 156 The '.' register (last inserted text) is still inserted as 157 typed. {not in Vi} 158 159CTRL-R CTRL-O {0-9a-z"%#*+/:.-=} *i_CTRL-R_CTRL-O* 160 Insert the contents of a register literally and don't 161 auto-indent. Does the same as pasting with the mouse 162 |<MiddleMouse>|. 163 Does not replace characters! 164 The '.' register (last inserted text) is still inserted as 165 typed. {not in Vi} 166 167CTRL-R CTRL-P {0-9a-z"%#*+/:.-=} *i_CTRL-R_CTRL-P* 168 Insert the contents of a register literally and fix the 169 indent, like |[<MiddleMouse>|. 170 Does not replace characters! 171 The '.' register (last inserted text) is still inserted as 172 typed. {not in Vi} 173 174 *i_CTRL-T* 175CTRL-T Insert one shiftwidth of indent at the start of the current 176 line. The indent is always rounded to a 'shiftwidth' (this is 177 vi compatible). {Vi: only when in indent} 178 *i_CTRL-D* 179CTRL-D Delete one shiftwidth of indent at the start of the current 180 line. The indent is always rounded to a 'shiftwidth' (this is 181 vi compatible). {Vi: CTRL-D works only when used after 182 autoindent} 183 *i_0_CTRL-D* 1840 CTRL-D Delete all indent in the current line. {Vi: CTRL-D works 185 only when used after autoindent} 186 *i_^_CTRL-D* 187^ CTRL-D Delete all indent in the current line. The indent is 188 restored in the next line. This is useful when inserting a 189 label. {Vi: CTRL-D works only when used after autoindent} 190 191 *i_CTRL-V* 192CTRL-V Insert next non-digit literally. For special keys, the 193 terminal code is inserted. It's also possible to enter the 194 decimal, octal or hexadecimal value of a character 195 |i_CTRL-V_digit|. 196 The characters typed right after CTRL-V are not considered for 197 mapping. {Vi: no decimal byte entry} 198 Note: When CTRL-V is mapped (e.g., to paste text) you can 199 often use CTRL-Q instead |i_CTRL-Q|. 200 201 *i_CTRL-Q* 202CTRL-Q Same as CTRL-V. 203 Note: Some terminal connections may eat CTRL-Q, it doesn't 204 work then. It does work in the GUI. 205 206CTRL-X Enter CTRL-X mode. This is a sub-mode where commands can 207 be given to complete words or scroll the window. See 208 |i_CTRL-X| and |ins-completion|. {not in Vi} 209 210 *i_CTRL-E* 211CTRL-E Insert the character which is below the cursor. {not in Vi} 212 *i_CTRL-Y* 213CTRL-Y Insert the character which is above the cursor. {not in Vi} 214 Note that for CTRL-E and CTRL-Y 'textwidth' is not used, to be 215 able to copy characters from a long line. 216 217 *i_CTRL-_* 218CTRL-_ Switch between languages, as follows: 219 - When in a rightleft window, revins and nohkmap are toggled, 220 since English will likely be inserted in this case. 221 - When in a norightleft window, revins and hkmap are toggled, 222 since Hebrew will likely be inserted in this case. 223 224 CTRL-_ moves the cursor to the end of the typed text. 225 226 This command is only available when the 'allowrevins' option 227 is set. 228 Please refer to |rileft.txt| for more information about 229 right-to-left mode. 230 {not in Vi} 231 Only if compiled with the |+rightleft| feature. 232 233 *i_CTRL-^* 234CTRL-^ Toggle the use of typing language characters. 235 When language |:lmap| mappings are defined: 236 - If 'iminsert' is 1 (langmap mappings used) it becomes 0 (no 237 langmap mappings used). 238 - If 'iminsert' has another value it becomes 1, thus langmap 239 mappings are enabled. 240 When no language mappings are defined: 241 - If 'iminsert' is 2 (Input Method used) it becomes 0 (no 242 Input Method used). 243 - If 'iminsert' has another value it becomes 2, thus the Input 244 Method is enabled. 245 When set to 1, the value of the "b:keymap_name" variable, the 246 'keymap' option or "<lang>" appears in the status line. 247 The language mappings are normally used to type characters 248 that are different from what the keyboard produces. The 249 'keymap' option can be used to install a whole number of them. 250 {not in Vi} 251 252 *i_CTRL-]* 253CTRL-] Trigger abbreviation, without inserting a character. {not in 254 Vi} 255 256 *i_<Insert>* 257<Insert> Toggle between Insert and Replace mode. {not in Vi} 258----------------------------------------------------------------------- 259 260 *i_backspacing* 261The effect of the <BS>, CTRL-W, and CTRL-U depend on the 'backspace' option 262(unless 'revins' is set). This is a comma separated list of items: 263 264item action ~ 265indent allow backspacing over autoindent 266eol allow backspacing over end-of-line (join lines) 267start allow backspacing over the start position of insert; CTRL-W and 268 CTRL-U stop once at the start position 269 270When 'backspace' is empty, Vi compatible backspacing is used. You cannot 271backspace over autoindent, before column 1 or before where insert started. 272 273For backwards compatibility the values "0", "1" and "2" are also allowed, see 274|'backspace'|. 275 276If the 'backspace' option does contain "eol" and the cursor is in column 1 277when one of the three keys is used, the current line is joined with the 278previous line. This effectively deletes the <EOL> in front of the cursor. 279{Vi: does not cross lines, does not delete past start position of insert} 280 281 *i_CTRL-V_digit* 282With CTRL-V the decimal, octal or hexadecimal value of a character can be 283entered directly. This way you can enter any character, except a line break 284(<NL>, value 10). There are five ways to enter the character value: 285 286first char mode max nr of chars max value ~ 287(none) decimal 3 255 288o or O octal 3 377 (255) 289x or X hexadecimal 2 ff (255) 290u hexadecimal 4 ffff (65535) 291U hexadecimal 8 7fffffff (2147483647) 292 293Normally you would type the maximum number of characters. Thus to enter a 294space (value 32) you would type <C-V>032. You can omit the leading zero, in 295which case the character typed after the number must be a non-digit. This 296happens for the other modes as well: As soon as you type a character that is 297invalid for the mode, the value before it will be used and the "invalid" 298character is dealt with in the normal way. 299 300If you enter a value of 10, it will end up in the file as a 0. The 10 is a 301<NL>, which is used internally to represent the <Nul> character. When writing 302the buffer to a file, the <NL> character is translated into <Nul>. The <NL> 303character is written at the end of each line. Thus if you want to insert a 304<NL> character in a file you will have to make a line break. 305 306 *i_CTRL-X* *insert_expand* 307CTRL-X enters a sub-mode where several commands can be used. Most of these 308commands do keyword completion; see |ins-completion|. These are not available 309when Vim was compiled without the |+insert_expand| feature. 310 311Two commands can be used to scroll the window up or down, without exiting 312insert mode: 313 314 *i_CTRL-X_CTRL-E* 315CTRL-X CTRL-E scroll window one line up. 316 When doing completion look here: |complete_CTRL-E| 317 318 *i_CTRL-X_CTRL-Y* 319CTRL-X CTRL-Y scroll window one line down. 320 When doing completion look here: |complete_CTRL-Y| 321 322After CTRL-X is pressed, each CTRL-E (CTRL-Y) scrolls the window up (down) by 323one line unless that would cause the cursor to move from its current position 324in the file. As soon as another key is pressed, CTRL-X mode is exited and 325that key is interpreted as in Insert mode. 326 327 328============================================================================== 3292. Special special keys *ins-special-special* 330 331The following keys are special. They stop the current insert, do something, 332and then restart insertion. This means you can do something without getting 333out of Insert mode. This is very handy if you prefer to use the Insert mode 334all the time, just like editors that don't have a separate Normal mode. You 335may also want to set the 'backspace' option to "indent,eol,start" and set the 336'insertmode' option. You can use CTRL-O if you want to map a function key to 337a command. 338 339The changes (inserted or deleted characters) before and after these keys can 340be undone separately. Only the last change can be redone and always behaves 341like an "i" command. 342 343char action ~ 344----------------------------------------------------------------------- 345<Up> cursor one line up *i_<Up>* 346<Down> cursor one line down *i_<Down>* 347CTRL-G <Up> cursor one line up, insert start column *i_CTRL-G_<Up>* 348CTRL-G k cursor one line up, insert start column *i_CTRL-G_k* 349CTRL-G CTRL-K cursor one line up, insert start column *i_CTRL-G_CTRL-K* 350CTRL-G <Down> cursor one line down, insert start column *i_CTRL-G_<Down>* 351CTRL-G j cursor one line down, insert start column *i_CTRL-G_j* 352CTRL-G CTRL-J cursor one line down, insert start column *i_CTRL-G_CTRL-J* 353<Left> cursor one character left *i_<Left>* 354<Right> cursor one character right *i_<Right>* 355<S-Left> cursor one word back (like "b" command) *i_<S-Left>* 356<C-Left> cursor one word back (like "b" command) *i_<C-Left>* 357<S-Right> cursor one word forward (like "w" command) *i_<S-Right>* 358<C-Right> cursor one word forward (like "w" command) *i_<C-Right>* 359<Home> cursor to first char in the line *i_<Home>* 360<End> cursor to after last char in the line *i_<End>* 361<C-Home> cursor to first char in the file *i_<C-Home>* 362<C-End> cursor to after last char in the file *i_<C-End>* 363<LeftMouse> cursor to position of mouse click *i_<LeftMouse>* 364<S-Up> move window one page up *i_<S-Up>* 365<PageUp> move window one page up *i_<PageUp>* 366<S-Down> move window one page down *i_<S-Down>* 367<PageDown> move window one page down *i_<PageDown>* 368<ScrollWheelDown> move window three lines down *i_<ScrollWheelDown>* 369<S-ScrollWheelDown> move window one page down *i_<S-ScrollWheelDown>* 370<ScrollWheelUp> move window three lines up *i_<ScrollWheelUp>* 371<S-ScrollWheelUp> move window one page up *i_<S-ScrollWheelUp>* 372<ScrollWheelLeft> move window six columns left *i_<ScrollWheelLeft>* 373<S-ScrollWheelLeft> move window one page left *i_<S-ScrollWheelLeft>* 374<ScrollWheelRight> move window six columns right *i_<ScrollWheelRight>* 375<S-ScrollWheelRight> move window one page right *i_<S-ScrollWheelRight>* 376CTRL-O execute one command, return to Insert mode *i_CTRL-O* 377CTRL-\ CTRL-O like CTRL-O but don't move the cursor *i_CTRL-\_CTRL-O* 378CTRL-L when 'insertmode' is set: go to Normal mode *i_CTRL-L* 379CTRL-G u break undo sequence, start new change *i_CTRL-G_u* 380CTRL-G U don't break undo with next left/right cursor *i_CTRL-G_U* 381 movement (but only if the cursor stays 382 within same the line) 383----------------------------------------------------------------------- 384 385Note: If the cursor keys take you out of Insert mode, check the 'noesckeys' 386option. 387 388The CTRL-O command sometimes has a side effect: If the cursor was beyond the 389end of the line, it will be put on the last character in the line. In 390mappings it's often better to use <Esc> (first put an "x" in the text, <Esc> 391will then always put the cursor on it). Or use CTRL-\ CTRL-O, but then 392beware of the cursor possibly being beyond the end of the line. Note that the 393command following CTRL-\ CTRL-O can still move the cursor, it is not restored 394to its original position. 395 396The CTRL-O command takes you to Normal mode. If you then use a command enter 397Insert mode again it normally doesn't nest. Thus when typing "a<C-O>a" and 398then <Esc> takes you back to Normal mode, you do not need to type <Esc> twice. 399An exception is when not typing the command, e.g. when executing a mapping or 400sourcing a script. This makes mappings work that briefly switch to Insert 401mode. 402 403The shifted cursor keys are not available on all terminals. 404 405Another side effect is that a count specified before the "i" or "a" command is 406ignored. That is because repeating the effect of the command after CTRL-O is 407too complicated. 408 409An example for using CTRL-G u: > 410 411 :inoremap <C-H> <C-G>u<C-H> 412 413This redefines the backspace key to start a new undo sequence. You can now 414undo the effect of the backspace key, without changing what you typed before 415that, with CTRL-O u. Another example: > 416 417 :inoremap <CR> <C-]><C-G>u<CR> 418 419This breaks undo at each line break. It also expands abbreviations before 420this. 421 422An example for using CTRL-G U: > 423 424 inoremap <Left> <C-G>U<Left> 425 inoremap <Right> <C-G>U<Right> 426 inoremap <expr> <Home> col('.') == match(getline('.'), '\S') + 1 ? 427 \ repeat('<C-G>U<Left>', col('.') - 1) : 428 \ (col('.') < match(getline('.'), '\S') ? 429 \ repeat('<C-G>U<Right>', match(getline('.'), '\S') + 0) : 430 \ repeat('<C-G>U<Left>', col('.') - 1 - match(getline('.'), '\S'))) 431 inoremap <expr> <End> repeat('<C-G>U<Right>', col('$') - col('.')) 432 inoremap ( ()<C-G>U<Left> 433 434This makes it possible to use the cursor keys in Insert mode, without breaking 435the undo sequence and therefore using |.| (redo) will work as expected. 436Also entering a text like (with the "(" mapping from above): > 437 438 Lorem ipsum (dolor 439 440will be repeatable by the |.|to the expected 441 442 Lorem ipsum (dolor) 443 444Using CTRL-O splits undo: the text typed before and after it is undone 445separately. If you want to avoid this (e.g., in a mapping) you might be able 446to use CTRL-R = |i_CTRL-R|. E.g., to call a function: > 447 :imap <F2> <C-R>=MyFunc()<CR> 448 449When the 'whichwrap' option is set appropriately, the <Left> and <Right> 450keys on the first/last character in the line make the cursor wrap to the 451previous/next line. 452 453The CTRL-G j and CTRL-G k commands can be used to insert text in front of a 454column. Example: > 455 int i; 456 int j; 457Position the cursor on the first "int", type "istatic <C-G>j ". The 458result is: > 459 static int i; 460 int j; 461When inserting the same text in front of the column in every line, use the 462Visual blockwise command "I" |v_b_I|. 463 464============================================================================== 4653. 'textwidth' and 'wrapmargin' options *ins-textwidth* 466 467The 'textwidth' option can be used to automatically break a line before it 468gets too long. Set the 'textwidth' option to the desired maximum line 469length. If you then type more characters (not spaces or tabs), the 470last word will be put on a new line (unless it is the only word on the 471line). If you set 'textwidth' to 0, this feature is disabled. 472 473The 'wrapmargin' option does almost the same. The difference is that 474'textwidth' has a fixed width while 'wrapmargin' depends on the width of the 475screen. When using 'wrapmargin' this is equal to using 'textwidth' with a 476value equal to (columns - 'wrapmargin'), where columns is the width of the 477screen. 478 479When 'textwidth' and 'wrapmargin' are both set, 'textwidth' is used. 480 481If you don't really want to break the line, but view the line wrapped at a 482convenient place, see the 'linebreak' option. 483 484The line is only broken automatically when using Insert mode, or when 485appending to a line. When in replace mode and the line length is not 486changed, the line will not be broken. 487 488Long lines are broken if you enter a non-white character after the margin. 489The situations where a line will be broken can be restricted by adding 490characters to the 'formatoptions' option: 491"l" Only break a line if it was not longer than 'textwidth' when the insert 492 started. 493"v" Only break at a white character that has been entered during the 494 current insert command. This is mostly Vi-compatible. 495"lv" Only break if the line was not longer than 'textwidth' when the insert 496 started and only at a white character that has been entered during the 497 current insert command. Only differs from "l" when entering non-white 498 characters while crossing the 'textwidth' boundary. 499 500Normally an internal function will be used to decide where to break the line. 501If you want to do it in a different way set the 'formatexpr' option to an 502expression that will take care of the line break. 503 504If you want to format a block of text, you can use the "gq" operator. Type 505"gq" and a movement command to move the cursor to the end of the block. In 506many cases, the command "gq}" will do what you want (format until the end of 507paragraph). Alternatively, you can use "gqap", which will format the whole 508paragraph, no matter where the cursor currently is. Or you can use Visual 509mode: hit "v", move to the end of the block, and type "gq". See also |gq|. 510 511============================================================================== 5124. 'expandtab', 'smarttab' and 'softtabstop' options *ins-expandtab* 513 514If the 'expandtab' option is on, spaces will be used to fill the amount of 515whitespace of the tab. If you want to enter a real <Tab>, type CTRL-V first 516(use CTRL-Q when CTRL-V is mapped |i_CTRL-Q|). 517The 'expandtab' option is off by default. Note that in Replace mode, a single 518character is replaced with several spaces. The result of this is that the 519number of characters in the line increases. Backspacing will delete one 520space at a time. The original character will be put back for only one space 521that you backspace over (the last one). {Vi does not have the 'expandtab' 522option} 523 524 *ins-smarttab* 525When the 'smarttab' option is on, a <Tab> inserts 'shiftwidth' positions at 526the beginning of a line and 'tabstop' positions in other places. This means 527that often spaces instead of a <Tab> character are inserted. When 'smarttab' 528is off, a <Tab> always inserts 'tabstop' positions, and 'shiftwidth' is only 529used for ">>" and the like. {not in Vi} 530 531 *ins-softtabstop* 532When the 'softtabstop' option is non-zero, a <Tab> inserts 'softtabstop' 533positions, and a <BS> used to delete white space, will delete 'softtabstop' 534positions. This feels like 'tabstop' was set to 'softtabstop', but a real 535<Tab> character still takes 'tabstop' positions, so your file will still look 536correct when used by other applications. 537 538If 'softtabstop' is non-zero, a <BS> will try to delete as much white space to 539move to the previous 'softtabstop' position, except when the previously 540inserted character is a space, then it will only delete the character before 541the cursor. Otherwise you cannot always delete a single character before the 542cursor. You will have to delete 'softtabstop' characters first, and then type 543extra spaces to get where you want to be. 544 545============================================================================== 5465. Replace mode *Replace* *Replace-mode* *mode-replace* 547 548Enter Replace mode with the "R" command in normal mode. 549 550In Replace mode, one character in the line is deleted for every character you 551type. If there is no character to delete (at the end of the line), the 552typed character is appended (as in Insert mode). Thus the number of 553characters in a line stays the same until you get to the end of the line. 554If a <NL> is typed, a line break is inserted and no character is deleted. 555 556Be careful with <Tab> characters. If you type a normal printing character in 557its place, the number of characters is still the same, but the number of 558columns will become smaller. 559 560If you delete characters in Replace mode (with <BS>, CTRL-W, or CTRL-U), what 561happens is that you delete the changes. The characters that were replaced 562are restored. If you had typed past the existing text, the characters you 563added are deleted. This is effectively a character-at-a-time undo. 564 565If the 'expandtab' option is on, a <Tab> will replace one character with 566several spaces. The result of this is that the number of characters in the 567line increases. Backspacing will delete one space at a time. The original 568character will be put back for only one space that you backspace over (the 569last one). {Vi does not have the 'expandtab' option} 570 571============================================================================== 5726. Virtual Replace mode *vreplace-mode* *Virtual-Replace-mode* 573 574Enter Virtual Replace mode with the "gR" command in normal mode. 575{not available when compiled without the |+vreplace| feature} 576{Vi does not have Virtual Replace mode} 577 578Virtual Replace mode is similar to Replace mode, but instead of replacing 579actual characters in the file, you are replacing screen real estate, so that 580characters further on in the file never appear to move. 581 582So if you type a <Tab> it may replace several normal characters, and if you 583type a letter on top of a <Tab> it may not replace anything at all, since the 584<Tab> will still line up to the same place as before. 585 586Typing a <NL> still doesn't cause characters later in the file to appear to 587move. The rest of the current line will be replaced by the <NL> (that is, 588they are deleted), and replacing continues on the next line. A new line is 589NOT inserted unless you go past the end of the file. 590 591Interesting effects are seen when using CTRL-T and CTRL-D. The characters 592before the cursor are shifted sideways as normal, but characters later in the 593line still remain still. CTRL-T will hide some of the old line under the 594shifted characters, but CTRL-D will reveal them again. 595 596As with Replace mode, using <BS> etc will bring back the characters that were 597replaced. This still works in conjunction with 'smartindent', CTRL-T and 598CTRL-D, 'expandtab', 'smarttab', 'softtabstop', etc. 599 600In 'list' mode, Virtual Replace mode acts as if it was not in 'list' mode, 601unless "L" is in 'cpoptions'. 602 603Note that the only situations for which characters beyond the cursor should 604appear to move are in List mode |'list'|, and occasionally when 'wrap' is set 605(and the line changes length to become shorter or wider than the width of the 606screen). In other cases spaces may be inserted to avoid following characters 607to move. 608 609This mode is very useful for editing <Tab> separated columns in tables, for 610entering new data while keeping all the columns aligned. 611 612============================================================================== 6137. Insert mode completion *ins-completion* 614 615In Insert and Replace mode, there are several commands to complete part of a 616keyword or line that has been typed. This is useful if you are using 617complicated keywords (e.g., function names with capitals and underscores). 618 619These commands are not available when the |+insert_expand| feature was 620disabled at compile time. 621 622Completion can be done for: 623 6241. Whole lines |i_CTRL-X_CTRL-L| 6252. keywords in the current file |i_CTRL-X_CTRL-N| 6263. keywords in 'dictionary' |i_CTRL-X_CTRL-K| 6274. keywords in 'thesaurus', thesaurus-style |i_CTRL-X_CTRL-T| 6285. keywords in the current and included files |i_CTRL-X_CTRL-I| 6296. tags |i_CTRL-X_CTRL-]| 6307. file names |i_CTRL-X_CTRL-F| 6318. definitions or macros |i_CTRL-X_CTRL-D| 6329. Vim command-line |i_CTRL-X_CTRL-V| 63310. User defined completion |i_CTRL-X_CTRL-U| 63411. omni completion |i_CTRL-X_CTRL-O| 63512. Spelling suggestions |i_CTRL-X_s| 63613. keywords in 'complete' |i_CTRL-N| 637 638All these (except 2) are done in CTRL-X mode. This is a sub-mode of Insert 639and Replace modes. You enter CTRL-X mode by typing CTRL-X and one of the 640CTRL-X commands. You exit CTRL-X mode by typing a key that is not a valid 641CTRL-X mode command. Valid keys are the CTRL-X command itself, CTRL-N (next), 642and CTRL-P (previous). 643 644Also see the 'infercase' option if you want to adjust the case of the match. 645 646 *complete_CTRL-E* 647When completion is active you can use CTRL-E to stop it and go back to the 648originally typed text. The CTRL-E will not be inserted. 649 650 *complete_CTRL-Y* 651When the popup menu is displayed you can use CTRL-Y to stop completion and 652accept the currently selected entry. The CTRL-Y is not inserted. Typing a 653space, Enter, or some other unprintable character will leave completion mode 654and insert that typed character. 655 656When the popup menu is displayed there are a few more special keys, see 657|popupmenu-keys|. 658 659Note: The keys that are valid in CTRL-X mode are not mapped. This allows for 660":map ^F ^X^F" to work (where ^F is CTRL-F and ^X is CTRL-X). The key that 661ends CTRL-X mode (any key that is not a valid CTRL-X mode command) is mapped. 662Also, when doing completion with 'complete' mappings apply as usual. 663 664Note: While completion is active Insert mode can't be used recursively. 665Mappings that somehow invoke ":normal i.." will generate an E523 error. 666 667The following mappings are suggested to make typing the completion commands 668a bit easier (although they will hide other commands): > 669 :inoremap ^] ^X^] 670 :inoremap ^F ^X^F 671 :inoremap ^D ^X^D 672 :inoremap ^L ^X^L 673 674As a special case, typing CTRL-R to perform register insertion (see 675|i_CTRL-R|) will not exit CTRL-X mode. This is primarily to allow the use of 676the '=' register to call some function to determine the next operation. If 677the contents of the register (or result of the '=' register evaluation) are 678not valid CTRL-X mode keys, then CTRL-X mode will be exited as if those keys 679had been typed. 680 681For example, the following will map <Tab> to either actually insert a <Tab> if 682the current line is currently only whitespace, or start/continue a CTRL-N 683completion operation: > 684 685 function! CleverTab() 686 if strpart( getline('.'), 0, col('.')-1 ) =~ '^\s*$' 687 return "\<Tab>" 688 else 689 return "\<C-N>" 690 endif 691 endfunction 692 inoremap <Tab> <C-R>=CleverTab()<CR> 693 694 695 696Completing whole lines *compl-whole-line* 697 698 *i_CTRL-X_CTRL-L* 699CTRL-X CTRL-L Search backwards for a line that starts with the 700 same characters as those in the current line before 701 the cursor. Indent is ignored. The matching line is 702 inserted in front of the cursor. 703 The 'complete' option is used to decide which buffers 704 are searched for a match. Both loaded and unloaded 705 buffers are used. 706 CTRL-L or 707 CTRL-P Search backwards for next matching line. This line 708 replaces the previous matching line. 709 710 CTRL-N Search forward for next matching line. This line 711 replaces the previous matching line. 712 713 CTRL-X CTRL-L After expanding a line you can additionally get the 714 line next to it by typing CTRL-X CTRL-L again, unless 715 a double CTRL-X is used. Only works for loaded 716 buffers. 717 718Completing keywords in current file *compl-current* 719 720 *i_CTRL-X_CTRL-P* 721 *i_CTRL-X_CTRL-N* 722CTRL-X CTRL-N Search forwards for words that start with the keyword 723 in front of the cursor. The found keyword is inserted 724 in front of the cursor. 725 726CTRL-X CTRL-P Search backwards for words that start with the keyword 727 in front of the cursor. The found keyword is inserted 728 in front of the cursor. 729 730 CTRL-N Search forward for next matching keyword. This 731 keyword replaces the previous matching keyword. 732 733 CTRL-P Search backwards for next matching keyword. This 734 keyword replaces the previous matching keyword. 735 736 CTRL-X CTRL-N or 737 CTRL-X CTRL-P Further use of CTRL-X CTRL-N or CTRL-X CTRL-P will 738 copy the words following the previous expansion in 739 other contexts unless a double CTRL-X is used. 740 741If there is a keyword in front of the cursor (a name made out of alphabetic 742characters and characters in 'iskeyword'), it is used as the search pattern, 743with "\<" prepended (meaning: start of a word). Otherwise "\<\k\k" is used 744as search pattern (start of any keyword of at least two characters). 745 746In Replace mode, the number of characters that are replaced depends on the 747length of the matched string. This works like typing the characters of the 748matched string in Replace mode. 749 750If there is not a valid keyword character before the cursor, any keyword of 751at least two characters is matched. 752 e.g., to get: 753 printf("(%g, %g, %g)", vector[0], vector[1], vector[2]); 754 just type: 755 printf("(%g, %g, %g)", vector[0], ^P[1], ^P[2]); 756 757The search wraps around the end of the file, the value of 'wrapscan' is not 758used here. 759 760Multiple repeats of the same completion are skipped; thus a different match 761will be inserted at each CTRL-N and CTRL-P (unless there is only one 762matching keyword). 763 764Single character matches are never included, as they usually just get in 765the way of what you were really after. 766 e.g., to get: 767 printf("name = %s\n", name); 768 just type: 769 printf("name = %s\n", n^P); 770 or even: 771 printf("name = %s\n", ^P); 772The 'n' in '\n' is skipped. 773 774After expanding a word, you can use CTRL-X CTRL-P or CTRL-X CTRL-N to get the 775word following the expansion in other contexts. These sequences search for 776the text just expanded and further expand by getting an extra word. This is 777useful if you need to repeat a sequence of complicated words. Although CTRL-P 778and CTRL-N look just for strings of at least two characters, CTRL-X CTRL-P and 779CTRL-X CTRL-N can be used to expand words of just one character. 780 e.g., to get: 781 México 782 you can type: 783 M^N^P^X^P^X^P 784CTRL-N starts the expansion and then CTRL-P takes back the single character 785"M", the next two CTRL-X CTRL-P's get the words "é" and ";xico". 786 787If the previous expansion was split, because it got longer than 'textwidth', 788then just the text in the current line will be used. 789 790If the match found is at the end of a line, then the first word in the next 791line will be inserted and the message "word from next line" displayed, if 792this word is accepted the next CTRL-X CTRL-P or CTRL-X CTRL-N will search 793for those lines starting with this word. 794 795 796Completing keywords in 'dictionary' *compl-dictionary* 797 798 *i_CTRL-X_CTRL-K* 799CTRL-X CTRL-K Search the files given with the 'dictionary' option 800 for words that start with the keyword in front of the 801 cursor. This is like CTRL-N, but only the dictionary 802 files are searched, not the current file. The found 803 keyword is inserted in front of the cursor. This 804 could potentially be pretty slow, since all matches 805 are found before the first match is used. By default, 806 the 'dictionary' option is empty. 807 For suggestions where to find a list of words, see the 808 'dictionary' option. 809 810 CTRL-K or 811 CTRL-N Search forward for next matching keyword. This 812 keyword replaces the previous matching keyword. 813 814 CTRL-P Search backwards for next matching keyword. This 815 keyword replaces the previous matching keyword. 816 817 *i_CTRL-X_CTRL-T* 818CTRL-X CTRL-T Works as CTRL-X CTRL-K, but in a special way. It uses 819 the 'thesaurus' option instead of 'dictionary'. If a 820 match is found in the thesaurus file, all the 821 remaining words on the same line are included as 822 matches, even though they don't complete the word. 823 Thus a word can be completely replaced. 824 825 For an example, imagine the 'thesaurus' file has a 826 line like this: > 827 angry furious mad enraged 828< Placing the cursor after the letters "ang" and typing 829 CTRL-X CTRL-T would complete the word "angry"; 830 subsequent presses would change the word to "furious", 831 "mad" etc. 832 Other uses include translation between two languages, 833 or grouping API functions by keyword. 834 835 CTRL-T or 836 CTRL-N Search forward for next matching keyword. This 837 keyword replaces the previous matching keyword. 838 839 CTRL-P Search backwards for next matching keyword. This 840 keyword replaces the previous matching keyword. 841 842 843Completing keywords in the current and included files *compl-keyword* 844 845The 'include' option is used to specify a line that contains an include file 846name. The 'path' option is used to search for include files. 847 848 *i_CTRL-X_CTRL-I* 849CTRL-X CTRL-I Search for the first keyword in the current and 850 included files that starts with the same characters 851 as those before the cursor. The matched keyword is 852 inserted in front of the cursor. 853 854 CTRL-N Search forwards for next matching keyword. This 855 keyword replaces the previous matching keyword. 856 Note: CTRL-I is the same as <Tab>, which is likely to 857 be typed after a successful completion, therefore 858 CTRL-I is not used for searching for the next match. 859 860 CTRL-P Search backward for previous matching keyword. This 861 keyword replaces the previous matching keyword. 862 863 CTRL-X CTRL-I Further use of CTRL-X CTRL-I will copy the words 864 following the previous expansion in other contexts 865 unless a double CTRL-X is used. 866 867Completing tags *compl-tag* 868 *i_CTRL-X_CTRL-]* 869CTRL-X CTRL-] Search for the first tag that starts with the same 870 characters as before the cursor. The matching tag is 871 inserted in front of the cursor. Alphabetic 872 characters and characters in 'iskeyword' are used 873 to decide which characters are included in the tag 874 name (same as for a keyword). See also |CTRL-]|. 875 The 'showfulltag' option can be used to add context 876 from around the tag definition. 877 CTRL-] or 878 CTRL-N Search forwards for next matching tag. This tag 879 replaces the previous matching tag. 880 881 CTRL-P Search backward for previous matching tag. This tag 882 replaces the previous matching tag. 883 884 885Completing file names *compl-filename* 886 *i_CTRL-X_CTRL-F* 887CTRL-X CTRL-F Search for the first file name that starts with the 888 same characters as before the cursor. The matching 889 file name is inserted in front of the cursor. 890 Alphabetic characters and characters in 'isfname' 891 are used to decide which characters are included in 892 the file name. Note: the 'path' option is not used 893 here (yet). 894 CTRL-F or 895 CTRL-N Search forwards for next matching file name. This 896 file name replaces the previous matching file name. 897 898 CTRL-P Search backward for previous matching file name. 899 This file name replaces the previous matching file 900 name. 901 902 903Completing definitions or macros *compl-define* 904 905The 'define' option is used to specify a line that contains a definition. 906The 'include' option is used to specify a line that contains an include file 907name. The 'path' option is used to search for include files. 908 909 *i_CTRL-X_CTRL-D* 910CTRL-X CTRL-D Search in the current and included files for the 911 first definition (or macro) name that starts with 912 the same characters as before the cursor. The found 913 definition name is inserted in front of the cursor. 914 CTRL-D or 915 CTRL-N Search forwards for next matching macro name. This 916 macro name replaces the previous matching macro 917 name. 918 919 CTRL-P Search backward for previous matching macro name. 920 This macro name replaces the previous matching macro 921 name. 922 923 CTRL-X CTRL-D Further use of CTRL-X CTRL-D will copy the words 924 following the previous expansion in other contexts 925 unless a double CTRL-X is used. 926 927 928Completing Vim commands *compl-vim* 929 930Completion is context-sensitive. It works like on the Command-line. It 931completes an Ex command as well as its arguments. This is useful when writing 932a Vim script. 933 934 *i_CTRL-X_CTRL-V* 935CTRL-X CTRL-V Guess what kind of item is in front of the cursor and 936 find the first match for it. 937 Note: When CTRL-V is mapped you can often use CTRL-Q 938 instead of |i_CTRL-Q|. 939 CTRL-V or 940 CTRL-N Search forwards for next match. This match replaces 941 the previous one. 942 943 CTRL-P Search backwards for previous match. This match 944 replaces the previous one. 945 946 CTRL-X CTRL-V Further use of CTRL-X CTRL-V will do the same as 947 CTRL-V. This allows mapping a key to do Vim command 948 completion, for example: > 949 :imap <Tab> <C-X><C-V> 950 951User defined completion *compl-function* 952 953Completion is done by a function that can be defined by the user with the 954'completefunc' option. See below for how the function is called and an 955example |complete-functions|. 956 957 *i_CTRL-X_CTRL-U* 958CTRL-X CTRL-U Guess what kind of item is in front of the cursor and 959 find the first match for it. 960 CTRL-U or 961 CTRL-N Use the next match. This match replaces the previous 962 one. 963 964 CTRL-P Use the previous match. This match replaces the 965 previous one. 966 967 968Omni completion *compl-omni* 969 970Completion is done by a function that can be defined by the user with the 971'omnifunc' option. This is to be used for filetype-specific completion. 972 973See below for how the function is called and an example |complete-functions|. 974For remarks about specific filetypes see |compl-omni-filetypes|. 975More completion scripts will appear, check www.vim.org. Currently there is a 976first version for C++. 977 978 *i_CTRL-X_CTRL-O* 979CTRL-X CTRL-O Guess what kind of item is in front of the cursor and 980 find the first match for it. 981 CTRL-O or 982 CTRL-N Use the next match. This match replaces the previous 983 one. 984 985 CTRL-P Use the previous match. This match replaces the 986 previous one. 987 988 989Spelling suggestions *compl-spelling* 990 991A word before or at the cursor is located and correctly spelled words are 992suggested to replace it. If there is a badly spelled word in the line, before 993or under the cursor, the cursor is moved to after it. Otherwise the word just 994before the cursor is used for suggestions, even though it isn't badly spelled. 995 996NOTE: CTRL-S suspends display in many Unix terminals. Use 's' instead. Type 997CTRL-Q to resume displaying. 998 999 *i_CTRL-X_CTRL-S* *i_CTRL-X_s* 1000CTRL-X CTRL-S or 1001CTRL-X s Locate the word in front of the cursor and find the 1002 first spell suggestion for it. 1003 CTRL-S or 1004 CTRL-N Use the next suggestion. This replaces the previous 1005 one. Note that you can't use 's' here. 1006 1007 CTRL-P Use the previous suggestion. This replaces the 1008 previous one. 1009 1010 1011Completing keywords from different sources *compl-generic* 1012 1013 *i_CTRL-N* 1014CTRL-N Find next match for words that start with the 1015 keyword in front of the cursor, looking in places 1016 specified with the 'complete' option. The found 1017 keyword is inserted in front of the cursor. 1018 1019 *i_CTRL-P* 1020CTRL-P Find previous match for words that start with the 1021 keyword in front of the cursor, looking in places 1022 specified with the 'complete' option. The found 1023 keyword is inserted in front of the cursor. 1024 1025 CTRL-N Search forward for next matching keyword. This 1026 keyword replaces the previous matching keyword. 1027 1028 CTRL-P Search backwards for next matching keyword. This 1029 keyword replaces the previous matching keyword. 1030 1031 CTRL-X CTRL-N or 1032 CTRL-X CTRL-P Further use of CTRL-X CTRL-N or CTRL-X CTRL-P will 1033 copy the words following the previous expansion in 1034 other contexts unless a double CTRL-X is used. 1035 1036 1037FUNCTIONS FOR FINDING COMPLETIONS *complete-functions* 1038 1039This applies to 'completefunc' and 'omnifunc'. 1040 1041The function is called in two different ways: 1042- First the function is called to find the start of the text to be completed. 1043- Later the function is called to actually find the matches. 1044 1045On the first invocation the arguments are: 1046 a:findstart 1 1047 a:base empty 1048 1049The function must return the column where the completion starts. It must be a 1050number between zero and the cursor column "col('.')". This involves looking 1051at the characters just before the cursor and including those characters that 1052could be part of the completed item. The text between this column and the 1053cursor column will be replaced with the matches. 1054 1055Special return values: 1056 -1 If no completion can be done, the completion will be cancelled with an 1057 error message. 1058 -2 To cancel silently and stay in completion mode. 1059 -3 To cancel silently and leave completion mode. 1060 1061On the second invocation the arguments are: 1062 a:findstart 0 1063 a:base the text with which matches should match; the text that was 1064 located in the first call (can be empty) 1065 1066The function must return a List with the matching words. These matches 1067usually include the "a:base" text. When there are no matches return an empty 1068List. 1069 1070In order to return more information than the matching words, return a Dict 1071that contains the List. The Dict can have these items: 1072 words The List of matching words (mandatory). 1073 refresh A string to control re-invocation of the function 1074 (optional). 1075 The only value currently recognized is "always", the 1076 effect is that the function is called whenever the 1077 leading text is changed. 1078Other items are ignored. 1079 1080For acting upon end of completion, see the |CompleteDone| autocommand event. 1081 1082For example, the function can contain this: > 1083 let matches = ... list of words ... 1084 return {'words': matches, 'refresh': 'always'} 1085< 1086 *complete-items* 1087Each list item can either be a string or a Dictionary. When it is a string it 1088is used as the completion. When it is a Dictionary it can contain these 1089items: 1090 word the text that will be inserted, mandatory 1091 abbr abbreviation of "word"; when not empty it is used in 1092 the menu instead of "word" 1093 menu extra text for the popup menu, displayed after "word" 1094 or "abbr" 1095 info more information about the item, can be displayed in a 1096 preview window 1097 kind single letter indicating the type of completion 1098 icase when non-zero case is to be ignored when comparing 1099 items to be equal; when omitted zero is used, thus 1100 items that only differ in case are added 1101 dup when non-zero this match will be added even when an 1102 item with the same word is already present. 1103 empty when non-zero this match will be added even when it is 1104 an empty string 1105 1106All of these except 'icase', 'dup' and 'empty' must be a string. If an item 1107does not meet these requirements then an error message is given and further 1108items in the list are not used. You can mix string and Dictionary items in 1109the returned list. 1110 1111The "menu" item is used in the popup menu and may be truncated, thus it should 1112be relatively short. The "info" item can be longer, it will be displayed in 1113the preview window when "preview" appears in 'completeopt'. The "info" item 1114will also remain displayed after the popup menu has been removed. This is 1115useful for function arguments. Use a single space for "info" to remove 1116existing text in the preview window. The size of the preview window is three 1117lines, but 'previewheight' is used when it has a value of 1 or 2. 1118 1119The "kind" item uses a single letter to indicate the kind of completion. This 1120may be used to show the completion differently (different color or icon). 1121Currently these types can be used: 1122 v variable 1123 f function or method 1124 m member of a struct or class 1125 t typedef 1126 d #define or macro 1127 1128When searching for matches takes some time call |complete_add()| to add each 1129match to the total list. These matches should then not appear in the returned 1130list! Call |complete_check()| now and then to allow the user to press a key 1131while still searching for matches. Stop searching when it returns non-zero. 1132 1133 *E839* *E840* 1134The function is allowed to move the cursor, it is restored afterwards. 1135The function is not allowed to move to another window or delete text. 1136 1137An example that completes the names of the months: > 1138 fun! CompleteMonths(findstart, base) 1139 if a:findstart 1140 " locate the start of the word 1141 let line = getline('.') 1142 let start = col('.') - 1 1143 while start > 0 && line[start - 1] =~ '\a' 1144 let start -= 1 1145 endwhile 1146 return start 1147 else 1148 " find months matching with "a:base" 1149 let res = [] 1150 for m in split("Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec") 1151 if m =~ '^' . a:base 1152 call add(res, m) 1153 endif 1154 endfor 1155 return res 1156 endif 1157 endfun 1158 set completefunc=CompleteMonths 1159< 1160The same, but now pretending searching for matches is slow: > 1161 fun! CompleteMonths(findstart, base) 1162 if a:findstart 1163 " locate the start of the word 1164 let line = getline('.') 1165 let start = col('.') - 1 1166 while start > 0 && line[start - 1] =~ '\a' 1167 let start -= 1 1168 endwhile 1169 return start 1170 else 1171 " find months matching with "a:base" 1172 for m in split("Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec") 1173 if m =~ '^' . a:base 1174 call complete_add(m) 1175 endif 1176 sleep 300m " simulate searching for next match 1177 if complete_check() 1178 break 1179 endif 1180 endfor 1181 return [] 1182 endif 1183 endfun 1184 set completefunc=CompleteMonths 1185< 1186 1187INSERT COMPLETION POPUP MENU *ins-completion-menu* 1188 *popupmenu-completion* 1189Vim can display the matches in a simplistic popup menu. 1190 1191The menu is used when: 1192- The 'completeopt' option contains "menu" or "menuone". 1193- The terminal supports at least 8 colors. 1194- There are at least two matches. One if "menuone" is used. 1195 1196The 'pumheight' option can be used to set a maximum height. The default is to 1197use all space available. 1198 1199There are three states: 12001. A complete match has been inserted, e.g., after using CTRL-N or CTRL-P. 12012. A cursor key has been used to select another match. The match was not 1202 inserted then, only the entry in the popup menu is highlighted. 12033. Only part of a match has been inserted and characters were typed or the 1204 backspace key was used. The list of matches was then adjusted for what is 1205 in front of the cursor. 1206 1207You normally start in the first state, with the first match being inserted. 1208When "longest" is in 'completeopt' and there is more than one match you start 1209in the third state. 1210 1211If you select another match, e.g., with CTRL-N or CTRL-P, you go to the first 1212state. This doesn't change the list of matches. 1213 1214When you are back at the original text then you are in the third state. To 1215get there right away you can use a mapping that uses CTRL-P right after 1216starting the completion: > 1217 :imap <F7> <C-N><C-P> 1218< 1219 *popupmenu-keys* 1220In the first state these keys have a special meaning: 1221<BS> and CTRL-H Delete one character, find the matches for the word before 1222 the cursor. This reduces the list of matches, often to one 1223 entry, and switches to the second state. 1224Any non-special character: 1225 Stop completion without changing the match and insert the 1226 typed character. 1227 1228In the second and third state these keys have a special meaning: 1229<BS> and CTRL-H Delete one character, find the matches for the shorter word 1230 before the cursor. This may find more matches. 1231CTRL-L Add one character from the current match, may reduce the 1232 number of matches. 1233any printable, non-white character: 1234 Add this character and reduce the number of matches. 1235 1236In all three states these can be used: 1237CTRL-Y Yes: Accept the currently selected match and stop completion. 1238CTRL-E End completion, go back to what was there before selecting a 1239 match (what was typed or longest common string). 1240<PageUp> Select a match several entries back, but don't insert it. 1241<PageDown> Select a match several entries further, but don't insert it. 1242<Up> Select the previous match, as if CTRL-P was used, but don't 1243 insert it. 1244<Down> Select the next match, as if CTRL-N was used, but don't 1245 insert it. 1246<Space> or <Tab> Stop completion without changing the match and insert the 1247 typed character. 1248 1249The behavior of the <Enter> key depends on the state you are in: 1250first state: Use the text as it is and insert a line break. 1251second state: Insert the currently selected match. 1252third state: Use the text as it is and insert a line break. 1253 1254In other words: If you used the cursor keys to select another entry in the 1255list of matches then the <Enter> key inserts that match. If you typed 1256something else then <Enter> inserts a line break. 1257 1258 1259The colors of the menu can be changed with these highlight groups: 1260Pmenu normal item |hl-Pmenu| 1261PmenuSel selected item |hl-PmenuSel| 1262PmenuSbar scrollbar |hl-PmenuSbar| 1263PmenuThumb thumb of the scrollbar |hl-PmenuThumb| 1264 1265There are no special mappings for when the popup menu is visible. However, 1266you can use an Insert mode mapping that checks the |pumvisible()| function to 1267do something different. Example: > 1268 :inoremap <Down> <C-R>=pumvisible() ? "\<lt>C-N>" : "\<lt>Down>"<CR> 1269 1270You can use of <expr> in mapping to have the popup menu used when typing a 1271character and some condition is met. For example, for typing a dot: > 1272 inoremap <expr> . MayComplete() 1273 func MayComplete() 1274 if (can complete) 1275 return ".\<C-X>\<C-O>" 1276 endif 1277 return '.' 1278 endfunc 1279 1280See |:map-<expr>| for more info. 1281 1282 1283FILETYPE-SPECIFIC REMARKS FOR OMNI COMPLETION *compl-omni-filetypes* 1284 1285The file used for {filetype} should be autoload/{filetype}complete.vim 1286in 'runtimepath'. Thus for "java" it is autoload/javacomplete.vim. 1287 1288 1289C *ft-c-omni* 1290 1291Completion of C code requires a tags file. You should use Exuberant ctags, 1292because it adds extra information that is needed for completion. You can find 1293it here: http://ctags.sourceforge.net/ Version 5.6 or later is recommended. 1294 1295For version 5.5.4 you should add a patch that adds the "typename:" field: 1296 ftp://ftp.vim.org/pub/vim/unstable/patches/ctags-5.5.4.patch 1297A compiled .exe for MS-Windows can be found at: 1298 http://georgevreilly.com/vim/ctags.html 1299 1300If you want to complete system functions you can do something like this. Use 1301ctags to generate a tags file for all the system header files: > 1302 % ctags -R -f ~/.vim/systags /usr/include /usr/local/include 1303In your vimrc file add this tags file to the 'tags' option: > 1304 set tags+=~/.vim/systags 1305 1306When using CTRL-X CTRL-O after a name without any "." or "->" it is completed 1307from the tags file directly. This works for any identifier, also function 1308names. If you want to complete a local variable name, which does not appear 1309in the tags file, use CTRL-P instead. 1310 1311When using CTRL-X CTRL-O after something that has "." or "->" Vim will attempt 1312to recognize the type of the variable and figure out what members it has. 1313This means only members valid for the variable will be listed. 1314 1315When a member name already was complete, CTRL-X CTRL-O will add a "." or 1316"->" for composite types. 1317 1318Vim doesn't include a C compiler, only the most obviously formatted 1319declarations are recognized. Preprocessor stuff may cause confusion. 1320When the same structure name appears in multiple places all possible members 1321are included. 1322 1323 1324CSS *ft-css-omni* 1325 1326Complete properties and their appropriate values according to CSS 2.1 1327specification. 1328 1329 1330HTML *ft-html-omni* 1331XHTML *ft-xhtml-omni* 1332 1333CTRL-X CTRL-O provides completion of various elements of (X)HTML files. It is 1334designed to support writing of XHTML 1.0 Strict files but will also work for 1335other versions of HTML. Features: 1336 1337- after "<" complete tag name depending on context (no div suggestion inside 1338 of an a tag); '/>' indicates empty tags 1339- inside of tag complete proper attributes (no width attribute for an a tag); 1340 show also type of attribute; '*' indicates required attributes 1341- when attribute has limited number of possible values help to complete them 1342- complete names of entities 1343- complete values of "class" and "id" attributes with data obtained from 1344 <style> tag and included CSS files 1345- when completing value of "style" attribute or working inside of "style" tag 1346 switch to |ft-css-omni| completion 1347- when completing values of events attributes or working inside of "script" 1348 tag switch to |ft-javascript-omni| completion 1349- when used after "</" CTRL-X CTRL-O will close the last opened tag 1350 1351Note: When used first time completion menu will be shown with little delay 1352- this is time needed for loading of data file. 1353Note: Completion may fail in badly formatted documents. In such case try to 1354run |:make| command to detect formatting problems. 1355 1356 1357HTML flavor *html-flavor* 1358 1359The default HTML completion depends on the filetype. For HTML files it is 1360HTML 4.01 Transitional ('filetype' is "html"), for XHTML it is XHTML 1.0 1361Strict ('filetype' is "xhtml"). 1362 1363When doing completion outside of any other tag you will have possibility to 1364choose DOCTYPE and the appropriate data file will be loaded and used for all 1365next completions. 1366 1367More about format of data file in |xml-omni-datafile|. Some of the data files 1368may be found on the Vim website (|www|). 1369 1370Note that b:html_omni_flavor may point to a file with any XML data. This 1371makes possible to mix PHP (|ft-php-omni|) completion with any XML dialect 1372(assuming you have data file for it). Without setting that variable XHTML 1.0 1373Strict will be used. 1374 1375 1376JAVASCRIPT *ft-javascript-omni* 1377 1378Completion of most elements of JavaScript language and DOM elements. 1379 1380Complete: 1381 1382- variables 1383- function name; show function arguments 1384- function arguments 1385- properties of variables trying to detect type of variable 1386- complete DOM objects and properties depending on context 1387- keywords of language 1388 1389Completion works in separate JavaScript files (&ft==javascript), inside of 1390<script> tag of (X)HTML and in values of event attributes (including scanning 1391of external files). 1392 1393DOM compatibility 1394 1395At the moment (beginning of 2006) there are two main browsers - MS Internet 1396Explorer and Mozilla Firefox. These two applications are covering over 90% of 1397market. Theoretically standards are created by W3C organisation 1398(http://www.w3c.org) but they are not always followed/implemented. 1399 1400 IE FF W3C Omni completion ~ 1401 +/- +/- + + ~ 1402 + + - + ~ 1403 + - - - ~ 1404 - + - - ~ 1405 1406Regardless from state of implementation in browsers but if element is defined 1407in standards, completion plugin will place element in suggestion list. When 1408both major engines implemented element, even if this is not in standards it 1409will be suggested. All other elements are not placed in suggestion list. 1410 1411 1412PHP *ft-php-omni* 1413 1414Completion of PHP code requires a tags file for completion of data from 1415external files and for class aware completion. You should use Exuberant ctags 1416version 5.5.4 or newer. You can find it here: http://ctags.sourceforge.net/ 1417 1418Script completes: 1419 1420- after $ variables name 1421 - if variable was declared as object add "->", if tags file is available show 1422 name of class 1423 - after "->" complete only function and variable names specific for given 1424 class. To find class location and contents tags file is required. Because 1425 PHP isn't strongly typed language user can use @var tag to declare class: > 1426 1427 /* @var $myVar myClass */ 1428 $myVar-> 1429< 1430 Still, to find myClass contents tags file is required. 1431 1432- function names with additional info: 1433 - in case of built-in functions list of possible arguments and after | type 1434 data returned by function 1435 - in case of user function arguments and name of file where function was 1436 defined (if it is not current file) 1437 1438- constants names 1439- class names after "new" declaration 1440 1441 1442Note: when doing completion first time Vim will load all necessary data into 1443memory. It may take several seconds. After next use of completion delay 1444should not be noticeable. 1445 1446Script detects if cursor is inside <?php ?> tags. If it is outside it will 1447automatically switch to HTML/CSS/JavaScript completion. Note: contrary to 1448original HTML files completion of tags (and only tags) isn't context aware. 1449 1450 1451RUBY *ft-ruby-omni* 1452 1453Completion of Ruby code requires that vim be built with |+ruby|. 1454 1455Ruby completion will parse your buffer on demand in order to provide a list of 1456completions. These completions will be drawn from modules loaded by 'require' 1457and modules defined in the current buffer. 1458 1459The completions provided by CTRL-X CTRL-O are sensitive to the context: 1460 1461 CONTEXT COMPLETIONS PROVIDED ~ 1462 1463 1. Not inside a class definition Classes, constants and globals 1464 1465 2. Inside a class definition Methods or constants defined in the class 1466 1467 3. After '.', '::' or ':' Methods applicable to the object being 1468 dereferenced 1469 1470 4. After ':' or ':foo' Symbol name (beginning with 'foo') 1471 1472Notes: 1473 - Vim will load/evaluate code in order to provide completions. This may 1474 cause some code execution, which may be a concern. This is no longer 1475 enabled by default, to enable this feature add > 1476 let g:rubycomplete_buffer_loading = 1 1477<- In context 1 above, Vim can parse the entire buffer to add a list of 1478 classes to the completion results. This feature is turned off by default, 1479 to enable it add > 1480 let g:rubycomplete_classes_in_global = 1 1481< to your vimrc 1482 - In context 2 above, anonymous classes are not supported. 1483 - In context 3 above, Vim will attempt to determine the methods supported by 1484 the object. 1485 - Vim can detect and load the Rails environment for files within a rails 1486 project. The feature is disabled by default, to enable it add > 1487 let g:rubycomplete_rails = 1 1488< to your vimrc 1489 1490 1491SYNTAX *ft-syntax-omni* 1492 1493Vim has the ability to color syntax highlight nearly 500 languages. Part of 1494this highlighting includes knowing what keywords are part of a language. Many 1495filetypes already have custom completion scripts written for them, the 1496syntaxcomplete plugin provides basic completion for all other filetypes. It 1497does this by populating the omni completion list with the text Vim already 1498knows how to color highlight. It can be used for any filetype and provides a 1499minimal language-sensitive completion. 1500 1501To enable syntax code completion you can run: > 1502 setlocal omnifunc=syntaxcomplete#Complete 1503 1504You can automate this by placing the following in your |.vimrc| (after any 1505":filetype" command): > 1506 if has("autocmd") && exists("+omnifunc") 1507 autocmd Filetype * 1508 \ if &omnifunc == "" | 1509 \ setlocal omnifunc=syntaxcomplete#Complete | 1510 \ endif 1511 endif 1512 1513The above will set completion to this script only if a specific plugin does 1514not already exist for that filetype. 1515 1516Each filetype can have a wide range of syntax items. The plugin allows you to 1517customize which syntax groups to include or exclude from the list. Let's have 1518a look at the PHP filetype to see how this works. 1519 1520If you edit a file called, index.php, run the following command: > 1521 syntax list 1522 1523The first thing you will notice is that there are many different syntax groups. 1524The PHP language can include elements from different languages like HTML, 1525JavaScript and many more. The syntax plugin will only include syntax groups 1526that begin with the filetype, "php", in this case. For example these syntax 1527groups are included by default with the PHP: phpEnvVar, phpIntVar, 1528phpFunctions. 1529 1530If you wish non-filetype syntax items to also be included, you can use a 1531regular expression syntax (added in version 13.0 of autoload\syntaxcomplete.vim) 1532to add items. Looking at the output from ":syntax list" while editing a PHP file 1533I can see some of these entries: > 1534 htmlArg,htmlTag,htmlTagName,javaScriptStatement,javaScriptGlobalObjects 1535 1536To pick up any JavaScript and HTML keyword syntax groups while editing a PHP 1537file, you can use 3 different regexs, one for each language. Or you can 1538simply restrict the include groups to a particular value, without using 1539a regex string: > 1540 let g:omni_syntax_group_include_php = 'php\w\+,javaScript\w\+,html\w\+' 1541 let g:omni_syntax_group_include_php = 'phpFunctions,phpMethods' 1542< 1543The basic form of this variable is: > 1544 let g:omni_syntax_group_include_{filetype} = 'regex,comma,separated' 1545 1546The PHP language has an enormous number of items which it knows how to syntax 1547highlight. These items will be available within the omni completion list. 1548 1549Some people may find this list unwieldy or are only interested in certain 1550items. There are two ways to prune this list (if necessary). If you find 1551certain syntax groups you do not wish displayed you can use two different 1552methods to identify these groups. The first specifically lists the syntax 1553groups by name. The second uses a regular expression to identify both 1554syntax groups. Simply add one the following to your vimrc: > 1555 let g:omni_syntax_group_exclude_php = 'phpCoreConstant,phpConstant' 1556 let g:omni_syntax_group_exclude_php = 'php\w*Constant' 1557 1558Add as many syntax groups to this list by comma separating them. The basic 1559form of this variable is: > 1560 let g:omni_syntax_group_exclude_{filetype} = 'regex,comma,separated' 1561 1562You can create as many of these variables as you need, varying only the 1563filetype at the end of the variable name. 1564 1565The plugin uses the isKeyword option to determine where word boundaries are 1566for the syntax items. For example, in the Scheme language completion should 1567include the "-", call-with-output-file. Depending on your filetype, this may 1568not provide the words you are expecting. Setting the 1569g:omni_syntax_use_iskeyword option to 0 will force the syntax plugin to break 1570on word characters. This can be controlled adding the following to your 1571vimrc: > 1572 let g:omni_syntax_use_iskeyword = 0 1573 1574For plugin developers, the plugin exposes a public function OmniSyntaxList. 1575This function can be used to request a List of syntax items. When editing a 1576SQL file (:e syntax.sql) you can use the ":syntax list" command to see the 1577various groups and syntax items. For example: > 1578 syntax list 1579 1580Yields data similar to this: > 1581 sqlOperator xxx some prior all like and any escape exists in is not 1582 or intersect minus between distinct 1583 links to Operator 1584 sqlType xxx varbit varchar nvarchar bigint int uniqueidentifier 1585 date money long tinyint unsigned xml text smalldate 1586 double datetime nchar smallint numeric time bit char 1587 varbinary binary smallmoney 1588 image float integer timestamp real decimal 1589 1590There are two syntax groups listed here: sqlOperator and sqlType. To retrieve 1591a List of syntax items you can call OmniSyntaxList a number of different 1592ways. To retrieve all syntax items regardless of syntax group: > 1593 echo OmniSyntaxList( [] ) 1594 1595To retrieve only the syntax items for the sqlOperator syntax group: > 1596 echo OmniSyntaxList( ['sqlOperator'] ) 1597 1598To retrieve all syntax items for both the sqlOperator and sqlType groups: > 1599 echo OmniSyntaxList( ['sqlOperator', 'sqlType'] ) 1600 1601A regular expression can also be used: > 1602 echo OmniSyntaxList( ['sql\w\+'] ) 1603 1604From within a plugin, you would typically assign the output to a List: > 1605 let myKeywords = [] 1606 let myKeywords = OmniSyntaxList( ['sqlKeyword'] ) 1607 1608 1609 1610SQL *ft-sql-omni* 1611 1612Completion for the SQL language includes statements, functions, keywords. 1613It will also dynamically complete tables, procedures, views and column lists 1614with data pulled directly from within a database. For detailed instructions 1615and a tutorial see |omni-sql-completion|. 1616 1617The SQL completion plugin can be used in conjunction with other completion 1618plugins. For example, the PHP filetype has its own completion plugin. 1619Since PHP is often used to generate dynamic website by accessing a database, 1620the SQL completion plugin can also be enabled. This allows you to complete 1621PHP code and SQL code at the same time. 1622 1623 1624XML *ft-xml-omni* 1625 1626Vim 7 provides a mechanism for context aware completion of XML files. It 1627depends on a special |xml-omni-datafile| and two commands: |:XMLns| and 1628|:XMLent|. Features are: 1629 1630- after "<" complete the tag name, depending on context 1631- inside of a tag complete proper attributes 1632- when an attribute has a limited number of possible values help to complete 1633 them 1634- complete names of entities (defined in |xml-omni-datafile| and in the 1635 current file with "<!ENTITY" declarations) 1636- when used after "</" CTRL-X CTRL-O will close the last opened tag 1637 1638Format of XML data file *xml-omni-datafile* 1639 1640XML data files are stored in the "autoload/xml" directory in 'runtimepath'. 1641Vim distribution provides examples of data files in the 1642"$VIMRUNTIME/autoload/xml" directory. They have a meaningful name which will 1643be used in commands. It should be a unique name which will not create 1644conflicts. For example, the name xhtml10s.vim means it is the data file for 1645XHTML 1.0 Strict. 1646 1647Each file contains a variable with a name like g:xmldata_xhtml10s . It is 1648a compound from two parts: 1649 16501. "g:xmldata_" general prefix, constant for all data files 16512. "xhtml10s" the name of the file and the name of the described XML 1652 dialect; it will be used as an argument for the |:XMLns| 1653 command 1654 1655Part two must be exactly the same as name of file. 1656 1657The variable is a |Dictionary|. Keys are tag names and each value is a two 1658element |List|. The first element of the List is also a List with the names 1659of possible children. The second element is a |Dictionary| with the names of 1660attributes as keys and the possible values of attributes as values. Example: > 1661 1662 let g:xmldata_crippled = { 1663 \ "vimxmlentities": ["amp", "lt", "gt", "apos", "quot"], 1664 \ 'vimxmlroot': ['tag1'], 1665 \ 'tag1': 1666 \ [ ['childoftag1a', 'childoftag1b'], {'attroftag1a': [], 1667 \ 'attroftag1b': ['valueofattr1', 'valueofattr2']}], 1668 \ 'childoftag1a': 1669 \ [ [], {'attrofchild': ['attrofchild']}], 1670 \ 'childoftag1b': 1671 \ [ ['childoftag1a'], {'attrofchild': []}], 1672 \ "vimxmltaginfo": { 1673 \ 'tag1': ['Menu info', 'Long information visible in preview window']}, 1674 \ 'vimxmlattrinfo': { 1675 \ 'attrofchild': ['Menu info', 'Long information visible in preview window']}} 1676 1677This example would be put in the "autoload/xml/crippled.vim" file and could 1678help to write this file: > 1679 1680 <tag1 attroftag1b="valueofattr1"> 1681 <childoftag1a attrofchild> 1682 & < 1683 </childoftag1a> 1684 <childoftag1b attrofchild="5"> 1685 <childoftag1a> 1686 > ' " 1687 </childoftag1a> 1688 </childoftag1b> 1689 </tag1> 1690 1691In the example four special elements are visible: 1692 16931. "vimxmlentities" - a special key with List containing entities of this XML 1694 dialect. 16952. If the list containing possible values of attributes has one element and 1696 this element is equal to the name of the attribute this attribute will be 1697 treated as boolean and inserted as 'attrname' and not as 'attrname="' 16983. "vimxmltaginfo" - a special key with a Dictionary containing tag 1699 names as keys and two element List as values, for additional menu info and 1700 the long description. 17014. "vimxmlattrinfo" - special key with Dictionary containing attribute names 1702 as keys and two element List as values, for additional menu info and long 1703 description. 1704 1705Note: Tag names in the data file MUST not contain a namespace description. 1706Check xsl.vim for an example. 1707Note: All data and functions are publicly available as global 1708variables/functions and can be used for personal editing functions. 1709 1710 1711DTD -> Vim *dtd2vim* 1712 1713On |www| is the script |dtd2vim| which parses DTD and creates an XML data file 1714for Vim XML omni completion. 1715 1716 dtd2vim: http://www.vim.org/scripts/script.php?script_id=1462 1717 1718Check the beginning of that file for usage details. 1719The script requires perl and: 1720 1721 perlSGML: http://savannah.nongnu.org/projects/perlsgml 1722 1723 1724Commands 1725 1726:XMLns {name} [{namespace}] *:XMLns* 1727 1728Vim has to know which data file should be used and with which namespace. For 1729loading of the data file and connecting data with the proper namespace use 1730|:XMLns| command. The first (obligatory) argument is the name of the data 1731(xhtml10s, xsl). The second argument is the code of namespace (h, xsl). When 1732used without a second argument the dialect will be used as default - without 1733namespace declaration. For example to use XML completion in .xsl files: > 1734 1735 :XMLns xhtml10s 1736 :XMLns xsl xsl 1737 1738 1739:XMLent {name} *:XMLent* 1740 1741By default entities will be completed from the data file of the default 1742namespace. The XMLent command should be used in case when there is no default 1743namespace: > 1744 1745 :XMLent xhtml10s 1746 1747Usage 1748 1749While used in this situation (after declarations from previous part, | is 1750cursor position): > 1751 1752 <| 1753 1754Will complete to an appropriate XHTML tag, and in this situation: > 1755 1756 <xsl:| 1757 1758Will complete to an appropriate XSL tag. 1759 1760 1761The script xmlcomplete.vim, provided through the |autoload| mechanism, 1762has the xmlcomplete#GetLastOpenTag() function which can be used in XML files 1763to get the name of the last open tag (b:unaryTagsStack has to be defined): > 1764 1765 :echo xmlcomplete#GetLastOpenTag("b:unaryTagsStack") 1766 1767 1768 1769============================================================================== 17708. Insert mode commands *inserting* 1771 1772The following commands can be used to insert new text into the buffer. They 1773can all be undone and repeated with the "." command. 1774 1775 *a* 1776a Append text after the cursor [count] times. If the 1777 cursor is in the first column of an empty line Insert 1778 starts there. But not when 'virtualedit' is set! 1779 1780 *A* 1781A Append text at the end of the line [count] times. 1782 1783<insert> or *i* *insert* *<Insert>* 1784i Insert text before the cursor [count] times. 1785 When using CTRL-O in Insert mode |i_CTRL-O| the count 1786 is not supported. 1787 1788 *I* 1789I Insert text before the first non-blank in the line 1790 [count] times. 1791 When the 'H' flag is present in 'cpoptions' and the 1792 line only contains blanks, insert start just before 1793 the last blank. 1794 1795 *gI* 1796gI Insert text in column 1 [count] times. {not in Vi} 1797 1798 *gi* 1799gi Insert text in the same position as where Insert mode 1800 was stopped last time in the current buffer. 1801 This uses the |'^| mark. It's different from "`^i" 1802 when the mark is past the end of the line. 1803 The position is corrected for inserted/deleted lines, 1804 but NOT for inserted/deleted characters. 1805 When the |:keepjumps| command modifier is used the |'^| 1806 mark won't be changed. 1807 {not in Vi} 1808 1809 *o* 1810o Begin a new line below the cursor and insert text, 1811 repeat [count] times. {Vi: blank [count] screen 1812 lines} 1813 When the '#' flag is in 'cpoptions' the count is 1814 ignored. 1815 1816 *O* 1817O Begin a new line above the cursor and insert text, 1818 repeat [count] times. {Vi: blank [count] screen 1819 lines} 1820 When the '#' flag is in 'cpoptions' the count is 1821 ignored. 1822 1823These commands are used to start inserting text. You can end insert mode with 1824<Esc>. See |mode-ins-repl| for the other special characters in Insert mode. 1825The effect of [count] takes place after Insert mode is exited. 1826 1827When 'autoindent' is on, the indent for a new line is obtained from the 1828previous line. When 'smartindent' or 'cindent' is on, the indent for a line 1829is automatically adjusted for C programs. 1830 1831'textwidth' can be set to the maximum width for a line. When a line becomes 1832too long when appending characters a line break is automatically inserted. 1833 1834 1835============================================================================== 18369. Ex insert commands *inserting-ex* 1837 1838 *:a* *:append* 1839:{range}a[ppend][!] Insert several lines of text below the specified 1840 line. If the {range} is missing, the text will be 1841 inserted after the current line. 1842 Adding [!] toggles 'autoindent' for the time this 1843 command is executed. 1844 1845 *:i* *:in* *:insert* 1846:{range}i[nsert][!] Insert several lines of text above the specified 1847 line. If the {range} is missing, the text will be 1848 inserted before the current line. 1849 Adding [!] toggles 'autoindent' for the time this 1850 command is executed. 1851 1852These two commands will keep on asking for lines, until you type a line 1853containing only a ".". Watch out for lines starting with a backslash, see 1854|line-continuation|. 1855 1856When in Ex mode (see |-e|) a backslash at the end of the line can be used to 1857insert a NUL character. To be able to have a line ending in a backslash use 1858two backslashes. This means that the number of backslashes is halved, but 1859only at the end of the line. 1860 1861NOTE: These commands cannot be used with |:global| or |:vglobal|. 1862":append" and ":insert" don't work properly in between ":if" and 1863":endif", ":for" and ":endfor", ":while" and ":endwhile". 1864 1865 *:start* *:startinsert* 1866:star[tinsert][!] Start Insert mode just after executing this command. 1867 Works like typing "i" in Normal mode. When the ! is 1868 included it works like "A", append to the line. 1869 Otherwise insertion starts at the cursor position. 1870 Note that when using this command in a function or 1871 script, the insertion only starts after the function 1872 or script is finished. 1873 This command does not work from |:normal|. 1874 {not in Vi} 1875 1876 *:stopi* *:stopinsert* 1877:stopi[nsert] Stop Insert mode as soon as possible. Works like 1878 typing <Esc> in Insert mode. 1879 Can be used in an autocommand, example: > 1880 :au BufEnter scratch stopinsert 1881< 1882 *replacing-ex* *:startreplace* 1883:startr[eplace][!] Start Replace mode just after executing this command. 1884 Works just like typing "R" in Normal mode. When the 1885 ! is included it acts just like "$R" had been typed 1886 (ie. begin replace mode at the end-of-line). Other- 1887 wise replacement begins at the cursor position. 1888 Note that when using this command in a function or 1889 script that the replacement will only start after 1890 the function or script is finished. 1891 {not in Vi} 1892 1893 *:startgreplace* 1894:startg[replace][!] Just like |:startreplace|, but use Virtual Replace 1895 mode, like with |gR|. 1896 {not in Vi} 1897 1898============================================================================== 189910. Inserting a file *inserting-file* 1900 1901 *:r* *:re* *:read* 1902:r[ead] [++opt] [name] 1903 Insert the file [name] (default: current file) below 1904 the cursor. 1905 See |++opt| for the possible values of [++opt]. 1906 1907:{range}r[ead] [++opt] [name] 1908 Insert the file [name] (default: current file) below 1909 the specified line. 1910 See |++opt| for the possible values of [++opt]. 1911 1912 *:r!* *:read!* 1913:[range]r[ead] [++opt] !{cmd} 1914 Execute {cmd} and insert its standard output below 1915 the cursor or the specified line. A temporary file is 1916 used to store the output of the command which is then 1917 read into the buffer. 'shellredir' is used to save 1918 the output of the command, which can be set to include 1919 stderr or not. {cmd} is executed like with ":!{cmd}", 1920 any '!' is replaced with the previous command |:!|. 1921 See |++opt| for the possible values of [++opt]. 1922 1923These commands insert the contents of a file, or the output of a command, 1924into the buffer. They can be undone. They cannot be repeated with the "." 1925command. They work on a line basis, insertion starts below the line in which 1926the cursor is, or below the specified line. To insert text above the first 1927line use the command ":0r {name}". 1928 1929After the ":read" command, the cursor is left on the first non-blank in the 1930first new line. Unless in Ex mode, then the cursor is left on the last new 1931line (sorry, this is Vi compatible). 1932 1933If a file name is given with ":r", it becomes the alternate file. This can be 1934used, for example, when you want to edit that file instead: ":e! #". This can 1935be switched off by removing the 'a' flag from the 'cpoptions' option. 1936 1937Of the [++opt] arguments one is specifically for ":read", the ++edit argument. 1938This is useful when the ":read" command is actually used to read a file into 1939the buffer as if editing that file. Use this command in an empty buffer: > 1940 :read ++edit filename 1941The effect is that the 'fileformat', 'fileencoding', 'bomb', etc. options are 1942set to what has been detected for "filename". Note that a single empty line 1943remains, you may want to delete it. 1944 1945 *file-read* 1946The 'fileformat' option sets the <EOL> style for a file: 1947'fileformat' characters name ~ 1948 "dos" <CR><NL> or <NL> DOS format 1949 "unix" <NL> Unix format 1950 "mac" <CR> Mac format 1951Previously 'textmode' was used. It is obsolete now. 1952 1953If 'fileformat' is "dos", a <CR> in front of an <NL> is ignored and a CTRL-Z 1954at the end of the file is ignored. 1955 1956If 'fileformat' is "mac", a <NL> in the file is internally represented by a 1957<CR>. This is to avoid confusion with a <NL> which is used to represent a 1958<NUL>. See |CR-used-for-NL|. 1959 1960If the 'fileformats' option is not empty Vim tries to recognize the type of 1961<EOL> (see |file-formats|). However, the 'fileformat' option will not be 1962changed, the detected format is only used while reading the file. 1963A similar thing happens with 'fileencodings'. 1964 1965On non-MS-DOS, Win32, and OS/2 systems the message "[dos format]" is shown if 1966a file is read in DOS format, to remind you that something unusual is done. 1967On Macintosh, MS-DOS, Win32, and OS/2 the message "[unix format]" is shown if 1968a file is read in Unix format. 1969On non-Macintosh systems, the message "[Mac format]" is shown if a file is 1970read in Mac format. 1971 1972An example on how to use ":r !": > 1973 :r !uuencode binfile binfile 1974This command reads "binfile", uuencodes it and reads it into the current 1975buffer. Useful when you are editing e-mail and want to include a binary 1976file. 1977 1978 *read-messages* 1979When reading a file Vim will display a message with information about the read 1980file. In the table is an explanation for some of the items. The others are 1981self explanatory. Using the long or the short version depends on the 1982'shortmess' option. 1983 1984 long short meaning ~ 1985 [readonly] {RO} the file is write protected 1986 [fifo/socket] using a stream 1987 [fifo] using a fifo stream 1988 [socket] using a socket stream 1989 [CR missing] reading with "dos" 'fileformat' and a 1990 NL without a preceding CR was found. 1991 [NL found] reading with "mac" 'fileformat' and a 1992 NL was found (could be "unix" format) 1993 [long lines split] at least one line was split in two 1994 [NOT converted] conversion from 'fileencoding' to 1995 'encoding' was desired but not 1996 possible 1997 [converted] conversion from 'fileencoding' to 1998 'encoding' done 1999 [crypted] file was decrypted 2000 [READ ERRORS] not all of the file could be read 2001 2002 2003 vim:tw=78:ts=8:ft=help:norl: 2004