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