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