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