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