1*insert.txt* For Vim version 8.1. Last change: 2019 Jan 29 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 using |.| 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. If the returned value is 1055larger than the cursor column, the cursor column is used. 1056 1057Negative return values: 1058 -2 To cancel silently and stay in completion mode. 1059 -3 To cancel silently and leave completion mode. 1060 Another negative value: completion starts at the cursor column 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. 1079 1080If you want to suppress the warning message for an empty result, return 1081|v:none|. This is useful to implement asynchronous completion with 1082|complete()|. 1083 1084Other items are ignored. 1085 1086For acting upon end of completion, see the |CompleteDone| autocommand event. 1087 1088For example, the function can contain this: > 1089 let matches = ... list of words ... 1090 return {'words': matches, 'refresh': 'always'} 1091< 1092 *complete-items* 1093Each list item can either be a string or a Dictionary. When it is a string it 1094is used as the completion. When it is a Dictionary it can contain these 1095items: 1096 word the text that will be inserted, mandatory 1097 abbr abbreviation of "word"; when not empty it is used in 1098 the menu instead of "word" 1099 menu extra text for the popup menu, displayed after "word" 1100 or "abbr" 1101 info more information about the item, can be displayed in a 1102 preview window 1103 kind single letter indicating the type of completion 1104 icase when non-zero case is to be ignored when comparing 1105 items to be equal; when omitted zero is used, thus 1106 items that only differ in case are added 1107 dup when non-zero this match will be added even when an 1108 item with the same word is already present. 1109 empty when non-zero this match will be added even when it is 1110 an empty string 1111 user_data custom data which is associated with the item and 1112 available in |v:completed_item| 1113 1114All of these except "icase", "dup" and "empty" must be a string. If an item 1115does not meet these requirements then an error message is given and further 1116items in the list are not used. You can mix string and Dictionary items in 1117the returned list. 1118 1119The "menu" item is used in the popup menu and may be truncated, thus it should 1120be relatively short. The "info" item can be longer, it will be displayed in 1121the preview window when "preview" appears in 'completeopt'. The "info" item 1122will also remain displayed after the popup menu has been removed. This is 1123useful for function arguments. Use a single space for "info" to remove 1124existing text in the preview window. The size of the preview window is three 1125lines, but 'previewheight' is used when it has a value of 1 or 2. 1126 1127The "kind" item uses a single letter to indicate the kind of completion. This 1128may be used to show the completion differently (different color or icon). 1129Currently these types can be used: 1130 v variable 1131 f function or method 1132 m member of a struct or class 1133 t typedef 1134 d #define or macro 1135 1136When searching for matches takes some time call |complete_add()| to add each 1137match to the total list. These matches should then not appear in the returned 1138list! Call |complete_check()| now and then to allow the user to press a key 1139while still searching for matches. Stop searching when it returns non-zero. 1140 1141 *E839* *E840* 1142The function is allowed to move the cursor, it is restored afterwards. 1143The function is not allowed to move to another window or delete text. 1144 1145An example that completes the names of the months: > 1146 fun! CompleteMonths(findstart, base) 1147 if a:findstart 1148 " locate the start of the word 1149 let line = getline('.') 1150 let start = col('.') - 1 1151 while start > 0 && line[start - 1] =~ '\a' 1152 let start -= 1 1153 endwhile 1154 return start 1155 else 1156 " find months matching with "a:base" 1157 let res = [] 1158 for m in split("Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec") 1159 if m =~ '^' . a:base 1160 call add(res, m) 1161 endif 1162 endfor 1163 return res 1164 endif 1165 endfun 1166 set completefunc=CompleteMonths 1167< 1168The same, but now pretending searching for matches is slow: > 1169 fun! CompleteMonths(findstart, base) 1170 if a:findstart 1171 " locate the start of the word 1172 let line = getline('.') 1173 let start = col('.') - 1 1174 while start > 0 && line[start - 1] =~ '\a' 1175 let start -= 1 1176 endwhile 1177 return start 1178 else 1179 " find months matching with "a:base" 1180 for m in split("Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec") 1181 if m =~ '^' . a:base 1182 call complete_add(m) 1183 endif 1184 sleep 300m " simulate searching for next match 1185 if complete_check() 1186 break 1187 endif 1188 endfor 1189 return [] 1190 endif 1191 endfun 1192 set completefunc=CompleteMonths 1193< 1194 1195INSERT COMPLETION POPUP MENU *ins-completion-menu* 1196 *popupmenu-completion* 1197Vim can display the matches in a simplistic popup menu. 1198 1199The menu is used when: 1200- The 'completeopt' option contains "menu" or "menuone". 1201- The terminal supports at least 8 colors. 1202- There are at least two matches. One if "menuone" is used. 1203 1204The 'pumheight' option can be used to set a maximum height. The default is to 1205use all space available. 1206The 'pumwidth' option can be used to set a minimum width. The default is 15 1207characters. 1208 1209There are three states: 12101. A complete match has been inserted, e.g., after using CTRL-N or CTRL-P. 12112. A cursor key has been used to select another match. The match was not 1212 inserted then, only the entry in the popup menu is highlighted. 12133. Only part of a match has been inserted and characters were typed or the 1214 backspace key was used. The list of matches was then adjusted for what is 1215 in front of the cursor. 1216 1217You normally start in the first state, with the first match being inserted. 1218When "longest" is in 'completeopt' and there is more than one match you start 1219in the third state. 1220 1221If you select another match, e.g., with CTRL-N or CTRL-P, you go to the first 1222state. This doesn't change the list of matches. 1223 1224When you are back at the original text then you are in the third state. To 1225get there right away you can use a mapping that uses CTRL-P right after 1226starting the completion: > 1227 :imap <F7> <C-N><C-P> 1228< 1229 *popupmenu-keys* 1230In the first state these keys have a special meaning: 1231<BS> and CTRL-H Delete one character, find the matches for the word before 1232 the cursor. This reduces the list of matches, often to one 1233 entry, and switches to the second state. 1234Any non-special character: 1235 Stop completion without changing the match and insert the 1236 typed character. 1237 1238In the second and third state these keys have a special meaning: 1239<BS> and CTRL-H Delete one character, find the matches for the shorter word 1240 before the cursor. This may find more matches. 1241CTRL-L Add one character from the current match, may reduce the 1242 number of matches. 1243any printable, non-white character: 1244 Add this character and reduce the number of matches. 1245 1246In all three states these can be used: 1247CTRL-Y Yes: Accept the currently selected match and stop completion. 1248CTRL-E End completion, go back to what was there before selecting a 1249 match (what was typed or longest common string). 1250<PageUp> Select a match several entries back, but don't insert it. 1251<PageDown> Select a match several entries further, but don't insert it. 1252<Up> Select the previous match, as if CTRL-P was used, but don't 1253 insert it. 1254<Down> Select the next match, as if CTRL-N was used, but don't 1255 insert it. 1256<Space> or <Tab> Stop completion without changing the match and insert the 1257 typed character. 1258 1259The behavior of the <Enter> key depends on the state you are in: 1260first state: Use the text as it is and insert a line break. 1261second state: Insert the currently selected match. 1262third state: Use the text as it is and insert a line break. 1263 1264In other words: If you used the cursor keys to select another entry in the 1265list of matches then the <Enter> key inserts that match. If you typed 1266something else then <Enter> inserts a line break. 1267 1268 1269The colors of the menu can be changed with these highlight groups: 1270Pmenu normal item |hl-Pmenu| 1271PmenuSel selected item |hl-PmenuSel| 1272PmenuSbar scrollbar |hl-PmenuSbar| 1273PmenuThumb thumb of the scrollbar |hl-PmenuThumb| 1274 1275There are no special mappings for when the popup menu is visible. However, 1276you can use an Insert mode mapping that checks the |pumvisible()| function to 1277do something different. Example: > 1278 :inoremap <Down> <C-R>=pumvisible() ? "\<lt>C-N>" : "\<lt>Down>"<CR> 1279 1280You can use of <expr> in mapping to have the popup menu used when typing a 1281character and some condition is met. For example, for typing a dot: > 1282 inoremap <expr> . MayComplete() 1283 func MayComplete() 1284 if (can complete) 1285 return ".\<C-X>\<C-O>" 1286 endif 1287 return '.' 1288 endfunc 1289 1290See |:map-<expr>| for more info. 1291 1292 1293FILETYPE-SPECIFIC REMARKS FOR OMNI COMPLETION *compl-omni-filetypes* 1294 1295The file used for {filetype} should be autoload/{filetype}complete.vim 1296in 'runtimepath'. Thus for "java" it is autoload/javacomplete.vim. 1297 1298 1299C *ft-c-omni* 1300 1301Completion of C code requires a tags file. You should use Exuberant ctags, 1302because it adds extra information that is needed for completion. You can find 1303it here: http://ctags.sourceforge.net/ Version 5.6 or later is recommended. 1304 1305For version 5.5.4 you should add a patch that adds the "typename:" field: 1306 ftp://ftp.vim.org/pub/vim/unstable/patches/ctags-5.5.4.patch 1307A compiled .exe for MS-Windows can be found at: 1308 http://ctags.sourceforge.net/ 1309 https://github.com/universal-ctags/ctags-win32 1310 1311If you want to complete system functions you can do something like this. Use 1312ctags to generate a tags file for all the system header files: > 1313 % ctags -R -f ~/.vim/systags /usr/include /usr/local/include 1314In your vimrc file add this tags file to the 'tags' option: > 1315 set tags+=~/.vim/systags 1316 1317When using CTRL-X CTRL-O after a name without any "." or "->" it is completed 1318from the tags file directly. This works for any identifier, also function 1319names. If you want to complete a local variable name, which does not appear 1320in the tags file, use CTRL-P instead. 1321 1322When using CTRL-X CTRL-O after something that has "." or "->" Vim will attempt 1323to recognize the type of the variable and figure out what members it has. 1324This means only members valid for the variable will be listed. 1325 1326When a member name already was complete, CTRL-X CTRL-O will add a "." or 1327"->" for composite types. 1328 1329Vim doesn't include a C compiler, only the most obviously formatted 1330declarations are recognized. Preprocessor stuff may cause confusion. 1331When the same structure name appears in multiple places all possible members 1332are included. 1333 1334 1335CSS *ft-css-omni* 1336 1337Complete properties and their appropriate values according to CSS 2.1 1338specification. 1339 1340 1341HTML *ft-html-omni* 1342XHTML *ft-xhtml-omni* 1343 1344CTRL-X CTRL-O provides completion of various elements of (X)HTML files. It is 1345designed to support writing of XHTML 1.0 Strict files but will also work for 1346other versions of HTML. Features: 1347 1348- after "<" complete tag name depending on context (no div suggestion inside 1349 of an a tag); '/>' indicates empty tags 1350- inside of tag complete proper attributes (no width attribute for an a tag); 1351 show also type of attribute; '*' indicates required attributes 1352- when attribute has limited number of possible values help to complete them 1353- complete names of entities 1354- complete values of "class" and "id" attributes with data obtained from 1355 <style> tag and included CSS files 1356- when completing value of "style" attribute or working inside of "style" tag 1357 switch to |ft-css-omni| completion 1358- when completing values of events attributes or working inside of "script" 1359 tag switch to |ft-javascript-omni| completion 1360- when used after "</" CTRL-X CTRL-O will close the last opened tag 1361 1362Note: When used first time completion menu will be shown with little delay 1363- this is time needed for loading of data file. 1364Note: Completion may fail in badly formatted documents. In such case try to 1365run |:make| command to detect formatting problems. 1366 1367 1368HTML flavor *html-flavor* 1369 1370The default HTML completion depends on the filetype. For HTML files it is 1371HTML 4.01 Transitional ('filetype' is "html"), for XHTML it is XHTML 1.0 1372Strict ('filetype' is "xhtml"). 1373 1374When doing completion outside of any other tag you will have possibility to 1375choose DOCTYPE and the appropriate data file will be loaded and used for all 1376next completions. 1377 1378More about format of data file in |xml-omni-datafile|. Some of the data files 1379may be found on the Vim website (|www|). 1380 1381Note that b:html_omni_flavor may point to a file with any XML data. This 1382makes possible to mix PHP (|ft-php-omni|) completion with any XML dialect 1383(assuming you have data file for it). Without setting that variable XHTML 1.0 1384Strict will be used. 1385 1386 1387JAVASCRIPT *ft-javascript-omni* 1388 1389Completion of most elements of JavaScript language and DOM elements. 1390 1391Complete: 1392 1393- variables 1394- function name; show function arguments 1395- function arguments 1396- properties of variables trying to detect type of variable 1397- complete DOM objects and properties depending on context 1398- keywords of language 1399 1400Completion works in separate JavaScript files (&ft==javascript), inside of 1401<script> tag of (X)HTML and in values of event attributes (including scanning 1402of external files). 1403 1404DOM compatibility 1405 1406At the moment (beginning of 2006) there are two main browsers - MS Internet 1407Explorer and Mozilla Firefox. These two applications are covering over 90% of 1408market. Theoretically standards are created by W3C organisation 1409(http://www.w3c.org) but they are not always followed/implemented. 1410 1411 IE FF W3C Omni completion ~ 1412 +/- +/- + + ~ 1413 + + - + ~ 1414 + - - - ~ 1415 - + - - ~ 1416 1417Regardless from state of implementation in browsers but if element is defined 1418in standards, completion plugin will place element in suggestion list. When 1419both major engines implemented element, even if this is not in standards it 1420will be suggested. All other elements are not placed in suggestion list. 1421 1422 1423PHP *ft-php-omni* 1424 1425Completion of PHP code requires a tags file for completion of data from 1426external files and for class aware completion. You should use Exuberant ctags 1427version 5.5.4 or newer. You can find it here: http://ctags.sourceforge.net/ 1428 1429Script completes: 1430 1431- after $ variables name 1432 - if variable was declared as object add "->", if tags file is available show 1433 name of class 1434 - after "->" complete only function and variable names specific for given 1435 class. To find class location and contents tags file is required. Because 1436 PHP isn't strongly typed language user can use @var tag to declare class: > 1437 1438 /* @var $myVar myClass */ 1439 $myVar-> 1440< 1441 Still, to find myClass contents tags file is required. 1442 1443- function names with additional info: 1444 - in case of built-in functions list of possible arguments and after | type 1445 data returned by function 1446 - in case of user function arguments and name of file where function was 1447 defined (if it is not current file) 1448 1449- constants names 1450- class names after "new" declaration 1451 1452 1453Note: when doing completion first time Vim will load all necessary data into 1454memory. It may take several seconds. After next use of completion delay 1455should not be noticeable. 1456 1457Script detects if cursor is inside <?php ?> tags. If it is outside it will 1458automatically switch to HTML/CSS/JavaScript completion. Note: contrary to 1459original HTML files completion of tags (and only tags) isn't context aware. 1460 1461 1462RUBY *ft-ruby-omni* 1463 1464Completion of Ruby code requires that vim be built with |+ruby|. 1465 1466Ruby completion will parse your buffer on demand in order to provide a list of 1467completions. These completions will be drawn from modules loaded by 'require' 1468and modules defined in the current buffer. 1469 1470The completions provided by CTRL-X CTRL-O are sensitive to the context: 1471 1472 CONTEXT COMPLETIONS PROVIDED ~ 1473 1474 1. Not inside a class definition Classes, constants and globals 1475 1476 2. Inside a class definition Methods or constants defined in the class 1477 1478 3. After '.', '::' or ':' Methods applicable to the object being 1479 dereferenced 1480 1481 4. After ':' or ':foo' Symbol name (beginning with 'foo') 1482 1483Notes: 1484 - Vim will load/evaluate code in order to provide completions. This may 1485 cause some code execution, which may be a concern. This is no longer 1486 enabled by default, to enable this feature add > 1487 let g:rubycomplete_buffer_loading = 1 1488<- In context 1 above, Vim can parse the entire buffer to add a list of 1489 classes to the completion results. This feature is turned off by default, 1490 to enable it add > 1491 let g:rubycomplete_classes_in_global = 1 1492< to your vimrc 1493 - In context 2 above, anonymous classes are not supported. 1494 - In context 3 above, Vim will attempt to determine the methods supported by 1495 the object. 1496 - Vim can detect and load the Rails environment for files within a rails 1497 project. The feature is disabled by default, to enable it add > 1498 let g:rubycomplete_rails = 1 1499< to your vimrc 1500 1501 1502SYNTAX *ft-syntax-omni* 1503 1504Vim has the ability to color syntax highlight nearly 500 languages. Part of 1505this highlighting includes knowing what keywords are part of a language. Many 1506filetypes already have custom completion scripts written for them, the 1507syntaxcomplete plugin provides basic completion for all other filetypes. It 1508does this by populating the omni completion list with the text Vim already 1509knows how to color highlight. It can be used for any filetype and provides a 1510minimal language-sensitive completion. 1511 1512To enable syntax code completion you can run: > 1513 setlocal omnifunc=syntaxcomplete#Complete 1514 1515You can automate this by placing the following in your |.vimrc| (after any 1516":filetype" command): > 1517 if has("autocmd") && exists("+omnifunc") 1518 autocmd Filetype * 1519 \ if &omnifunc == "" | 1520 \ setlocal omnifunc=syntaxcomplete#Complete | 1521 \ endif 1522 endif 1523 1524The above will set completion to this script only if a specific plugin does 1525not already exist for that filetype. 1526 1527Each filetype can have a wide range of syntax items. The plugin allows you to 1528customize which syntax groups to include or exclude from the list. Let's have 1529a look at the PHP filetype to see how this works. 1530 1531If you edit a file called, index.php, run the following command: > 1532 syntax list 1533 1534The first thing you will notice is that there are many different syntax groups. 1535The PHP language can include elements from different languages like HTML, 1536JavaScript and many more. The syntax plugin will only include syntax groups 1537that begin with the filetype, "php", in this case. For example these syntax 1538groups are included by default with the PHP: phpEnvVar, phpIntVar, 1539phpFunctions. 1540 1541If you wish non-filetype syntax items to also be included, you can use a 1542regular expression syntax (added in version 13.0 of 1543autoload/syntaxcomplete.vim) to add items. Looking at the output from 1544":syntax list" while editing a PHP file I can see some of these entries: > 1545 htmlArg,htmlTag,htmlTagName,javaScriptStatement,javaScriptGlobalObjects 1546 1547To pick up any JavaScript and HTML keyword syntax groups while editing a PHP 1548file, you can use 3 different regexs, one for each language. Or you can 1549simply restrict the include groups to a particular value, without using 1550a regex string: > 1551 let g:omni_syntax_group_include_php = 'php\w\+,javaScript\w\+,html\w\+' 1552 let g:omni_syntax_group_include_php = 'phpFunctions,phpMethods' 1553< 1554The basic form of this variable is: > 1555 let g:omni_syntax_group_include_{filetype} = 'regex,comma,separated' 1556 1557The PHP language has an enormous number of items which it knows how to syntax 1558highlight. These items will be available within the omni completion list. 1559 1560Some people may find this list unwieldy or are only interested in certain 1561items. There are two ways to prune this list (if necessary). If you find 1562certain syntax groups you do not wish displayed you can use two different 1563methods to identify these groups. The first specifically lists the syntax 1564groups by name. The second uses a regular expression to identify both 1565syntax groups. Simply add one the following to your vimrc: > 1566 let g:omni_syntax_group_exclude_php = 'phpCoreConstant,phpConstant' 1567 let g:omni_syntax_group_exclude_php = 'php\w*Constant' 1568 1569Add as many syntax groups to this list by comma separating them. The basic 1570form of this variable is: > 1571 let g:omni_syntax_group_exclude_{filetype} = 'regex,comma,separated' 1572 1573You can create as many of these variables as you need, varying only the 1574filetype at the end of the variable name. 1575 1576The plugin uses the isKeyword option to determine where word boundaries are 1577for the syntax items. For example, in the Scheme language completion should 1578include the "-", call-with-output-file. Depending on your filetype, this may 1579not provide the words you are expecting. Setting the 1580g:omni_syntax_use_iskeyword option to 0 will force the syntax plugin to break 1581on word characters. This can be controlled adding the following to your 1582vimrc: > 1583 let g:omni_syntax_use_iskeyword = 0 1584 1585For plugin developers, the plugin exposes a public function OmniSyntaxList. 1586This function can be used to request a List of syntax items. When editing a 1587SQL file (:e syntax.sql) you can use the ":syntax list" command to see the 1588various groups and syntax items. For example: > 1589 syntax list 1590 1591Yields data similar to this: 1592 sqlOperator xxx some prior all like and any escape exists in is not ~ 1593 or intersect minus between distinct ~ 1594 links to Operator ~ 1595 sqlType xxx varbit varchar nvarchar bigint int uniqueidentifier ~ 1596 date money long tinyint unsigned xml text smalldate ~ 1597 double datetime nchar smallint numeric time bit char ~ 1598 varbinary binary smallmoney ~ 1599 image float integer timestamp real decimal ~ 1600 1601There are two syntax groups listed here: sqlOperator and sqlType. To retrieve 1602a List of syntax items you can call OmniSyntaxList a number of different 1603ways. To retrieve all syntax items regardless of syntax group: > 1604 echo OmniSyntaxList( [] ) 1605 1606To retrieve only the syntax items for the sqlOperator syntax group: > 1607 echo OmniSyntaxList( ['sqlOperator'] ) 1608 1609To retrieve all syntax items for both the sqlOperator and sqlType groups: > 1610 echo OmniSyntaxList( ['sqlOperator', 'sqlType'] ) 1611 1612A regular expression can also be used: > 1613 echo OmniSyntaxList( ['sql\w\+'] ) 1614 1615From within a plugin, you would typically assign the output to a List: > 1616 let myKeywords = [] 1617 let myKeywords = OmniSyntaxList( ['sqlKeyword'] ) 1618 1619 1620SQL *ft-sql-omni* 1621 1622Completion for the SQL language includes statements, functions, keywords. 1623It will also dynamically complete tables, procedures, views and column lists 1624with data pulled directly from within a database. For detailed instructions 1625and a tutorial see |omni-sql-completion|. 1626 1627The SQL completion plugin can be used in conjunction with other completion 1628plugins. For example, the PHP filetype has its own completion plugin. 1629Since PHP is often used to generate dynamic website by accessing a database, 1630the SQL completion plugin can also be enabled. This allows you to complete 1631PHP code and SQL code at the same time. 1632 1633 1634XML *ft-xml-omni* 1635 1636Vim 7 provides a mechanism for context aware completion of XML files. It 1637depends on a special |xml-omni-datafile| and two commands: |:XMLns| and 1638|:XMLent|. Features are: 1639 1640- after "<" complete the tag name, depending on context 1641- inside of a tag complete proper attributes 1642- when an attribute has a limited number of possible values help to complete 1643 them 1644- complete names of entities (defined in |xml-omni-datafile| and in the 1645 current file with "<!ENTITY" declarations) 1646- when used after "</" CTRL-X CTRL-O will close the last opened tag 1647 1648Format of XML data file *xml-omni-datafile* 1649 1650XML data files are stored in the "autoload/xml" directory in 'runtimepath'. 1651Vim distribution provides examples of data files in the 1652"$VIMRUNTIME/autoload/xml" directory. They have a meaningful name which will 1653be used in commands. It should be a unique name which will not create 1654conflicts. For example, the name xhtml10s.vim means it is the data file for 1655XHTML 1.0 Strict. 1656 1657Each file contains a variable with a name like g:xmldata_xhtml10s . It is 1658a compound from two parts: 1659 16601. "g:xmldata_" general prefix, constant for all data files 16612. "xhtml10s" the name of the file and the name of the described XML 1662 dialect; it will be used as an argument for the |:XMLns| 1663 command 1664 1665Part two must be exactly the same as name of file. 1666 1667The variable is a |Dictionary|. Keys are tag names and each value is a two 1668element |List|. The first element of the List is also a List with the names 1669of possible children. The second element is a |Dictionary| with the names of 1670attributes as keys and the possible values of attributes as values. Example: > 1671 1672 let g:xmldata_crippled = { 1673 \ "vimxmlentities": ["amp", "lt", "gt", "apos", "quot"], 1674 \ 'vimxmlroot': ['tag1'], 1675 \ 'tag1': 1676 \ [ ['childoftag1a', 'childoftag1b'], {'attroftag1a': [], 1677 \ 'attroftag1b': ['valueofattr1', 'valueofattr2']}], 1678 \ 'childoftag1a': 1679 \ [ [], {'attrofchild': ['attrofchild']}], 1680 \ 'childoftag1b': 1681 \ [ ['childoftag1a'], {'attrofchild': []}], 1682 \ "vimxmltaginfo": { 1683 \ 'tag1': ['Menu info', 'Long information visible in preview window']}, 1684 \ 'vimxmlattrinfo': { 1685 \ 'attrofchild': ['Menu info', 'Long information visible in preview window']}} 1686 1687This example would be put in the "autoload/xml/crippled.vim" file and could 1688help to write this file: > 1689 1690 <tag1 attroftag1b="valueofattr1"> 1691 <childoftag1a attrofchild> 1692 & < 1693 </childoftag1a> 1694 <childoftag1b attrofchild="5"> 1695 <childoftag1a> 1696 > ' " 1697 </childoftag1a> 1698 </childoftag1b> 1699 </tag1> 1700 1701In the example four special elements are visible: 1702 17031. "vimxmlentities" - a special key with List containing entities of this XML 1704 dialect. 17052. If the list containing possible values of attributes has one element and 1706 this element is equal to the name of the attribute this attribute will be 1707 treated as boolean and inserted as 'attrname' and not as 'attrname="' 17083. "vimxmltaginfo" - a special key with a Dictionary containing tag 1709 names as keys and two element List as values, for additional menu info and 1710 the long description. 17114. "vimxmlattrinfo" - special key with Dictionary containing attribute names 1712 as keys and two element List as values, for additional menu info and long 1713 description. 1714 1715Note: Tag names in the data file MUST not contain a namespace description. 1716Check xsl.vim for an example. 1717Note: All data and functions are publicly available as global 1718variables/functions and can be used for personal editing functions. 1719 1720 1721DTD -> Vim *dtd2vim* 1722 1723On |www| is the script |dtd2vim| which parses DTD and creates an XML data file 1724for Vim XML omni completion. 1725 1726 dtd2vim: http://www.vim.org/scripts/script.php?script_id=1462 1727 1728Check the beginning of that file for usage details. 1729The script requires perl and: 1730 1731 perlSGML: http://savannah.nongnu.org/projects/perlsgml 1732 1733 1734Commands 1735 1736:XMLns {name} [{namespace}] *:XMLns* 1737 1738Vim has to know which data file should be used and with which namespace. For 1739loading of the data file and connecting data with the proper namespace use 1740|:XMLns| command. The first (obligatory) argument is the name of the data 1741(xhtml10s, xsl). The second argument is the code of namespace (h, xsl). When 1742used without a second argument the dialect will be used as default - without 1743namespace declaration. For example to use XML completion in .xsl files: > 1744 1745 :XMLns xhtml10s 1746 :XMLns xsl xsl 1747 1748 1749:XMLent {name} *:XMLent* 1750 1751By default entities will be completed from the data file of the default 1752namespace. The XMLent command should be used in case when there is no default 1753namespace: > 1754 1755 :XMLent xhtml10s 1756 1757Usage 1758 1759While used in this situation (after declarations from previous part, | is 1760cursor position): > 1761 1762 <| 1763 1764Will complete to an appropriate XHTML tag, and in this situation: > 1765 1766 <xsl:| 1767 1768Will complete to an appropriate XSL tag. 1769 1770 1771The script xmlcomplete.vim, provided through the |autoload| mechanism, 1772has the xmlcomplete#GetLastOpenTag() function which can be used in XML files 1773to get the name of the last open tag (b:unaryTagsStack has to be defined): > 1774 1775 :echo xmlcomplete#GetLastOpenTag("b:unaryTagsStack") 1776 1777 1778 1779============================================================================== 17808. Insert mode commands *inserting* 1781 1782The following commands can be used to insert new text into the buffer. They 1783can all be undone and repeated with the "." command. 1784 1785 *a* 1786a Append text after the cursor [count] times. If the 1787 cursor is in the first column of an empty line Insert 1788 starts there. But not when 'virtualedit' is set! 1789 1790 *A* 1791A Append text at the end of the line [count] times. 1792 1793<insert> or *i* *insert* *<Insert>* 1794i Insert text before the cursor [count] times. 1795 When using CTRL-O in Insert mode |i_CTRL-O| the count 1796 is not supported. 1797 1798 *I* 1799I Insert text before the first non-blank in the line 1800 [count] times. 1801 When the 'H' flag is present in 'cpoptions' and the 1802 line only contains blanks, insert start just before 1803 the last blank. 1804 1805 *gI* 1806gI Insert text in column 1 [count] times. {not in Vi} 1807 1808 *gi* 1809gi Insert text in the same position as where Insert mode 1810 was stopped last time in the current buffer. 1811 This uses the |'^| mark. It's different from "`^i" 1812 when the mark is past the end of the line. 1813 The position is corrected for inserted/deleted lines, 1814 but NOT for inserted/deleted characters. 1815 When the |:keepjumps| command modifier is used the |'^| 1816 mark won't be changed. 1817 {not in Vi} 1818 1819 *o* 1820o Begin a new line below the cursor and insert text, 1821 repeat [count] times. {Vi: blank [count] screen 1822 lines} 1823 When the '#' flag is in 'cpoptions' the count is 1824 ignored. 1825 1826 *O* 1827O Begin a new line above the cursor and insert text, 1828 repeat [count] times. {Vi: blank [count] screen 1829 lines} 1830 When the '#' flag is in 'cpoptions' the count is 1831 ignored. 1832 1833These commands are used to start inserting text. You can end insert mode with 1834<Esc>. See |mode-ins-repl| for the other special characters in Insert mode. 1835The effect of [count] takes place after Insert mode is exited. 1836 1837When 'autoindent' is on, the indent for a new line is obtained from the 1838previous line. When 'smartindent' or 'cindent' is on, the indent for a line 1839is automatically adjusted for C programs. 1840 1841'textwidth' can be set to the maximum width for a line. When a line becomes 1842too long when appending characters a line break is automatically inserted. 1843 1844 1845============================================================================== 18469. Ex insert commands *inserting-ex* 1847 1848 *:a* *:append* 1849:{range}a[ppend][!] Insert several lines of text below the specified 1850 line. If the {range} is missing, the text will be 1851 inserted after the current line. 1852 Adding [!] toggles 'autoindent' for the time this 1853 command is executed. 1854 1855 *:i* *:in* *:insert* 1856:{range}i[nsert][!] Insert several lines of text above the specified 1857 line. If the {range} is missing, the text will be 1858 inserted before the current line. 1859 Adding [!] toggles 'autoindent' for the time this 1860 command is executed. 1861 1862These two commands will keep on asking for lines, until you type a line 1863containing only a ".". Watch out for lines starting with a backslash, see 1864|line-continuation|. 1865 1866When in Ex mode (see |-e|) a backslash at the end of the line can be used to 1867insert a NUL character. To be able to have a line ending in a backslash use 1868two backslashes. This means that the number of backslashes is halved, but 1869only at the end of the line. 1870 1871NOTE: These commands cannot be used with |:global| or |:vglobal|. 1872":append" and ":insert" don't work properly in between ":if" and 1873":endif", ":for" and ":endfor", ":while" and ":endwhile". 1874 1875 *:start* *:startinsert* 1876:star[tinsert][!] Start Insert mode just after executing this command. 1877 Works like typing "i" in Normal mode. When the ! is 1878 included it works like "A", append to the line. 1879 Otherwise insertion starts at the cursor position. 1880 Note that when using this command in a function or 1881 script, the insertion only starts after the function 1882 or script is finished. 1883 This command does not work from |:normal|. 1884 {not in Vi} 1885 1886 *:stopi* *:stopinsert* 1887:stopi[nsert] Stop Insert mode as soon as possible. Works like 1888 typing <Esc> in Insert mode. 1889 Can be used in an autocommand, example: > 1890 :au BufEnter scratch stopinsert 1891< 1892 *replacing-ex* *:startreplace* 1893:startr[eplace][!] Start Replace mode just after executing this command. 1894 Works just like typing "R" in Normal mode. When the 1895 ! is included it acts just like "$R" had been typed 1896 (ie. begin replace mode at the end-of-line). Other- 1897 wise replacement begins at the cursor position. 1898 Note that when using this command in a function or 1899 script that the replacement will only start after 1900 the function or script is finished. 1901 {not in Vi} 1902 1903 *:startgreplace* 1904:startg[replace][!] Just like |:startreplace|, but use Virtual Replace 1905 mode, like with |gR|. 1906 {not in Vi} 1907 1908============================================================================== 190910. Inserting a file *inserting-file* 1910 1911 *:r* *:re* *:read* 1912:r[ead] [++opt] [name] 1913 Insert the file [name] (default: current file) below 1914 the cursor. 1915 See |++opt| for the possible values of [++opt]. 1916 1917:{range}r[ead] [++opt] [name] 1918 Insert the file [name] (default: current file) below 1919 the specified line. 1920 See |++opt| for the possible values of [++opt]. 1921 1922 *:r!* *:read!* 1923:[range]r[ead] [++opt] !{cmd} 1924 Execute {cmd} and insert its standard output below 1925 the cursor or the specified line. A temporary file is 1926 used to store the output of the command which is then 1927 read into the buffer. 'shellredir' is used to save 1928 the output of the command, which can be set to include 1929 stderr or not. {cmd} is executed like with ":!{cmd}", 1930 any '!' is replaced with the previous command |:!|. 1931 See |++opt| for the possible values of [++opt]. 1932 1933These commands insert the contents of a file, or the output of a command, 1934into the buffer. They can be undone. They cannot be repeated with the "." 1935command. They work on a line basis, insertion starts below the line in which 1936the cursor is, or below the specified line. To insert text above the first 1937line use the command ":0r {name}". 1938 1939After the ":read" command, the cursor is left on the first non-blank in the 1940first new line. Unless in Ex mode, then the cursor is left on the last new 1941line (sorry, this is Vi compatible). 1942 1943If a file name is given with ":r", it becomes the alternate file. This can be 1944used, for example, when you want to edit that file instead: ":e! #". This can 1945be switched off by removing the 'a' flag from the 'cpoptions' option. 1946 1947Of the [++opt] arguments one is specifically for ":read", the ++edit argument. 1948This is useful when the ":read" command is actually used to read a file into 1949the buffer as if editing that file. Use this command in an empty buffer: > 1950 :read ++edit filename 1951The effect is that the 'fileformat', 'fileencoding', 'bomb', etc. options are 1952set to what has been detected for "filename". Note that a single empty line 1953remains, you may want to delete it. 1954 1955 *file-read* 1956The 'fileformat' option sets the <EOL> style for a file: 1957'fileformat' characters name ~ 1958 "dos" <CR><NL> or <NL> DOS format 1959 "unix" <NL> Unix format 1960 "mac" <CR> Mac format 1961Previously 'textmode' was used. It is obsolete now. 1962 1963If 'fileformat' is "dos", a <CR> in front of an <NL> is ignored and a CTRL-Z 1964at the end of the file is ignored. 1965 1966If 'fileformat' is "mac", a <NL> in the file is internally represented by a 1967<CR>. This is to avoid confusion with a <NL> which is used to represent a 1968<NUL>. See |CR-used-for-NL|. 1969 1970If the 'fileformats' option is not empty Vim tries to recognize the type of 1971<EOL> (see |file-formats|). However, the 'fileformat' option will not be 1972changed, the detected format is only used while reading the file. 1973A similar thing happens with 'fileencodings'. 1974 1975On non-MS-DOS, Win32, and OS/2 systems the message "[dos format]" is shown if 1976a file is read in DOS format, to remind you that something unusual is done. 1977On Macintosh, MS-DOS, Win32, and OS/2 the message "[unix format]" is shown if 1978a file is read in Unix format. 1979On non-Macintosh systems, the message "[Mac format]" is shown if a file is 1980read in Mac format. 1981 1982An example on how to use ":r !": > 1983 :r !uuencode binfile binfile 1984This command reads "binfile", uuencodes it and reads it into the current 1985buffer. Useful when you are editing e-mail and want to include a binary 1986file. 1987 1988 *read-messages* 1989When reading a file Vim will display a message with information about the read 1990file. In the table is an explanation for some of the items. The others are 1991self explanatory. Using the long or the short version depends on the 1992'shortmess' option. 1993 1994 long short meaning ~ 1995 [readonly] {RO} the file is write protected 1996 [fifo/socket] using a stream 1997 [fifo] using a fifo stream 1998 [socket] using a socket stream 1999 [CR missing] reading with "dos" 'fileformat' and a 2000 NL without a preceding CR was found. 2001 [NL found] reading with "mac" 'fileformat' and a 2002 NL was found (could be "unix" format) 2003 [long lines split] at least one line was split in two 2004 [NOT converted] conversion from 'fileencoding' to 2005 'encoding' was desired but not 2006 possible 2007 [converted] conversion from 'fileencoding' to 2008 'encoding' done 2009 [crypted] file was decrypted 2010 [READ ERRORS] not all of the file could be read 2011 2012 2013 vim:tw=78:ts=8:noet:ft=help:norl: 2014