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