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