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