| *insert.txt* For Vim version 7.3. Last change: 2012 Jul 10 |
| |
| |
| VIM REFERENCE MANUAL by Bram Moolenaar |
| |
| |
| *Insert* *Insert-mode* |
| Inserting and replacing text *mode-ins-repl* |
| |
| Most of this file is about Insert and Replace mode. At the end are a few |
| commands for inserting text in other ways. |
| |
| An overview of the most often used commands can be found in chapter 24 of the |
| user manual |usr_24.txt|. |
| |
| 1. Special keys |ins-special-keys| |
| 2. Special special keys |ins-special-special| |
| 3. 'textwidth' and 'wrapmargin' options |ins-textwidth| |
| 4. 'expandtab', 'smarttab' and 'softtabstop' options |ins-expandtab| |
| 5. Replace mode |Replace-mode| |
| 6. Virtual Replace mode |Virtual-Replace-mode| |
| 7. Insert mode completion |ins-completion| |
| 8. Insert mode commands |inserting| |
| 9. Ex insert commands |inserting-ex| |
| 10. Inserting a file |inserting-file| |
| |
| Also see 'virtualedit', for moving the cursor to positions where there is no |
| character. Useful for editing a table. |
| |
| ============================================================================== |
| 1. Special keys *ins-special-keys* |
| |
| In Insert and Replace mode, the following characters have a special meaning; |
| other characters are inserted directly. To insert one of these special |
| characters into the buffer, precede it with CTRL-V. To insert a <Nul> |
| character use "CTRL-V CTRL-@" or "CTRL-V 000". On some systems, you have to |
| use "CTRL-V 003" to insert a CTRL-C. Note: When CTRL-V is mapped you can |
| often use CTRL-Q instead |i_CTRL-Q|. |
| |
| If you are working in a special language mode when inserting text, see the |
| 'langmap' option, |'langmap'|, on how to avoid switching this mode on and off |
| all the time. |
| |
| If you have 'insertmode' set, <Esc> and a few other keys get another meaning. |
| See |'insertmode'|. |
| |
| char action ~ |
| ----------------------------------------------------------------------- |
| *i_CTRL-[* *i_<Esc>* |
| <Esc> or CTRL-[ End insert or Replace mode, go back to Normal mode. Finish |
| abbreviation. |
| Note: If your <Esc> key is hard to hit on your keyboard, train |
| yourself to use CTRL-[. |
| *i_CTRL-C* |
| CTRL-C Quit insert mode, go back to Normal mode. Do not check for |
| abbreviations. Does not trigger the |InsertLeave| autocommand |
| event. |
| |
| *i_CTRL-@* |
| CTRL-@ Insert previously inserted text and stop insert. {Vi: only |
| when typed as first char, only up to 128 chars} |
| *i_CTRL-A* |
| CTRL-A Insert previously inserted text. {not in Vi} |
| |
| *i_CTRL-H* *i_<BS>* *i_BS* |
| <BS> or CTRL-H Delete the character before the cursor (see |i_backspacing| |
| about joining lines). |
| See |:fixdel| if your <BS> key does not do what you want. |
| {Vi: does not delete autoindents} |
| *i_<Del>* *i_DEL* |
| <Del> Delete the character under the cursor. If the cursor is at |
| the end of the line, and the 'backspace' option includes |
| "eol", delete the <EOL>; the next line is appended after the |
| current one. |
| See |:fixdel| if your <Del> key does not do what you want. |
| {not in Vi} |
| *i_CTRL-W* |
| CTRL-W Delete the word before the cursor (see |i_backspacing| about |
| joining lines). See the section "word motions", |
| |word-motions|, for the definition of a word. |
| *i_CTRL-U* |
| CTRL-U Delete all entered characters in the current line (see |
| |i_backspacing| about joining lines). |
| |
| *i_CTRL-I* *i_<Tab>* *i_Tab* |
| <Tab> or CTRL-I Insert a tab. If the 'expandtab' option is on, the |
| equivalent number of spaces is inserted (use CTRL-V <Tab> to |
| avoid the expansion; use CTRL-Q <Tab> if CTRL-V is mapped |
| |i_CTRL-Q|). See also the 'smarttab' option and |
| |ins-expandtab|. |
| *i_CTRL-J* *i_<NL>* |
| <NL> or CTRL-J Begin new line. |
| *i_CTRL-M* *i_<CR>* |
| <CR> or CTRL-M Begin new line. |
| *i_CTRL-K* |
| CTRL-K {char1} [char2] |
| Enter digraph (see |digraphs|). When {char1} is a special |
| key, the code for that key is inserted in <> form. For |
| example, the string "<S-Space>" can be entered by typing |
| <C-K><S-Space> (two keys). Neither char is considered for |
| mapping. {not in Vi} |
| |
| CTRL-N Find next keyword (see |i_CTRL-N|). {not in Vi} |
| CTRL-P Find previous keyword (see |i_CTRL-P|). {not in Vi} |
| |
| CTRL-R {0-9a-z"%#*+:.-=} *i_CTRL-R* |
| Insert the contents of a register. Between typing CTRL-R and |
| the second character, '"' will be displayed to indicate that |
| you are expected to enter the name of a register. |
| The text is inserted as if you typed it, but mappings and |
| abbreviations are not used. If you have options like |
| 'textwidth', 'formatoptions', or 'autoindent' set, this will |
| influence what will be inserted. This is different from what |
| happens with the "p" command and pasting with the mouse. |
| Special registers: |
| '"' the unnamed register, containing the text of |
| the last delete or yank |
| '%' the current file name |
| '#' the alternate file name |
| '*' the clipboard contents (X11: primary selection) |
| '+' the clipboard contents |
| '/' the last search pattern |
| ':' the last command-line |
| '.' the last inserted text |
| '-' the last small (less than a line) delete |
| *i_CTRL-R_=* |
| '=' the expression register: you are prompted to |
| enter an expression (see |expression|) |
| Note that 0x80 (128 decimal) is used for |
| special keys. E.g., you can use this to move |
| the cursor up: |
| CTRL-R ="\<Up>" |
| Use CTRL-R CTRL-R to insert text literally. |
| When the result is a |List| the items are used |
| as lines. They can have line breaks inside |
| too. |
| When the result is a Float it's automatically |
| converted to a String. |
| See |registers| about registers. {not in Vi} |
| |
| CTRL-R CTRL-R {0-9a-z"%#*+/:.-=} *i_CTRL-R_CTRL-R* |
| Insert the contents of a register. Works like using a single |
| CTRL-R, but the text is inserted literally, not as if typed. |
| This differs when the register contains characters like <BS>. |
| Example, where register a contains "ab^Hc": > |
| CTRL-R a results in "ac". |
| CTRL-R CTRL-R a results in "ab^Hc". |
| < Options 'textwidth', 'formatoptions', etc. still apply. If |
| you also want to avoid these, use "<C-R><C-O>r", see below. |
| The '.' register (last inserted text) is still inserted as |
| typed. {not in Vi} |
| |
| CTRL-R CTRL-O {0-9a-z"%#*+/:.-=} *i_CTRL-R_CTRL-O* |
| Insert the contents of a register literally and don't |
| auto-indent. Does the same as pasting with the mouse |
| |<MiddleMouse>|. |
| Does not replace characters! |
| The '.' register (last inserted text) is still inserted as |
| typed. {not in Vi} |
| |
| CTRL-R CTRL-P {0-9a-z"%#*+/:.-=} *i_CTRL-R_CTRL-P* |
| Insert the contents of a register literally and fix the |
| indent, like |[<MiddleMouse>|. |
| Does not replace characters! |
| The '.' register (last inserted text) is still inserted as |
| typed. {not in Vi} |
| |
| *i_CTRL-T* |
| CTRL-T Insert one shiftwidth of indent at the start of the current |
| line. The indent is always rounded to a 'shiftwidth' (this is |
| vi compatible). {Vi: only when in indent} |
| *i_CTRL-D* |
| CTRL-D Delete one shiftwidth of indent at the start of the current |
| line. The indent is always rounded to a 'shiftwidth' (this is |
| vi compatible). {Vi: CTRL-D works only when used after |
| autoindent} |
| *i_0_CTRL-D* |
| 0 CTRL-D Delete all indent in the current line. {Vi: CTRL-D works |
| only when used after autoindent} |
| *i_^_CTRL-D* |
| ^ CTRL-D Delete all indent in the current line. The indent is |
| restored in the next line. This is useful when inserting a |
| label. {Vi: CTRL-D works only when used after autoindent} |
| |
| *i_CTRL-V* |
| CTRL-V Insert next non-digit literally. For special keys, the |
| terminal code is inserted. It's also possible to enter the |
| decimal, octal or hexadecimal value of a character |
| |i_CTRL-V_digit|. |
| The characters typed right after CTRL-V are not considered for |
| mapping. {Vi: no decimal byte entry} |
| Note: When CTRL-V is mapped (e.g., to paste text) you can |
| often use CTRL-Q instead |i_CTRL-Q|. |
| |
| *i_CTRL-Q* |
| CTRL-Q Same as CTRL-V. |
| Note: Some terminal connections may eat CTRL-Q, it doesn't |
| work then. It does work in the GUI. |
| |
| CTRL-X Enter CTRL-X mode. This is a sub-mode where commands can |
| be given to complete words or scroll the window. See |
| |i_CTRL-X| and |ins-completion|. {not in Vi} |
| |
| *i_CTRL-E* |
| CTRL-E Insert the character which is below the cursor. {not in Vi} |
| *i_CTRL-Y* |
| CTRL-Y Insert the character which is above the cursor. {not in Vi} |
| Note that for CTRL-E and CTRL-Y 'textwidth' is not used, to be |
| able to copy characters from a long line. |
| |
| *i_CTRL-_* |
| CTRL-_ Switch between languages, as follows: |
| - When in a rightleft window, revins and nohkmap are toggled, |
| since English will likely be inserted in this case. |
| - When in a norightleft window, revins and hkmap are toggled, |
| since Hebrew will likely be inserted in this case. |
| |
| CTRL-_ moves the cursor to the end of the typed text. |
| |
| This command is only available when the 'allowrevins' option |
| is set. |
| Please refer to |rileft.txt| for more information about |
| right-to-left mode. |
| {not in Vi} |
| Only if compiled with the |+rightleft| feature. |
| |
| *i_CTRL-^* |
| CTRL-^ Toggle the use of typing language characters. |
| When language |:lmap| mappings are defined: |
| - If 'iminsert' is 1 (langmap mappings used) it becomes 0 (no |
| langmap mappings used). |
| - If 'iminsert' has another value it becomes 1, thus langmap |
| mappings are enabled. |
| When no language mappings are defined: |
| - If 'iminsert' is 2 (Input Method used) it becomes 0 (no |
| Input Method used). |
| - If 'iminsert' has another value it becomes 2, thus the Input |
| Method is enabled. |
| When set to 1, the value of the "b:keymap_name" variable, the |
| 'keymap' option or "<lang>" appears in the status line. |
| The language mappings are normally used to type characters |
| that are different from what the keyboard produces. The |
| 'keymap' option can be used to install a whole number of them. |
| {not in Vi} |
| |
| *i_CTRL-]* |
| CTRL-] Trigger abbreviation, without inserting a character. {not in |
| Vi} |
| |
| *i_<Insert>* |
| <Insert> Toggle between Insert and Replace mode. {not in Vi} |
| ----------------------------------------------------------------------- |
| |
| *i_backspacing* |
| The effect of the <BS>, CTRL-W, and CTRL-U depend on the 'backspace' option |
| (unless 'revins' is set). This is a comma separated list of items: |
| |
| item action ~ |
| indent allow backspacing over autoindent |
| eol allow backspacing over end-of-line (join lines) |
| start allow backspacing over the start position of insert; CTRL-W and |
| CTRL-U stop once at the start position |
| |
| When 'backspace' is empty, Vi compatible backspacing is used. You cannot |
| backspace over autoindent, before column 1 or before where insert started. |
| |
| For backwards compatibility the values "0", "1" and "2" are also allowed, see |
| |'backspace'|. |
| |
| If the 'backspace' option does contain "eol" and the cursor is in column 1 |
| when one of the three keys is used, the current line is joined with the |
| previous line. This effectively deletes the <EOL> in front of the cursor. |
| {Vi: does not cross lines, does not delete past start position of insert} |
| |
| *i_CTRL-V_digit* |
| With CTRL-V the decimal, octal or hexadecimal value of a character can be |
| entered directly. This way you can enter any character, except a line break |
| (<NL>, value 10). There are five ways to enter the character value: |
| |
| first char mode max nr of chars max value ~ |
| (none) decimal 3 255 |
| o or O octal 3 377 (255) |
| x or X hexadecimal 2 ff (255) |
| u hexadecimal 4 ffff (65535) |
| U hexadecimal 8 7fffffff (2147483647) |
| |
| Normally you would type the maximum number of characters. Thus to enter a |
| space (value 32) you would type <C-V>032. You can omit the leading zero, in |
| which case the character typed after the number must be a non-digit. This |
| happens for the other modes as well: As soon as you type a character that is |
| invalid for the mode, the value before it will be used and the "invalid" |
| character is dealt with in the normal way. |
| |
| If you enter a value of 10, it will end up in the file as a 0. The 10 is a |
| <NL>, which is used internally to represent the <Nul> character. When writing |
| the buffer to a file, the <NL> character is translated into <Nul>. The <NL> |
| character is written at the end of each line. Thus if you want to insert a |
| <NL> character in a file you will have to make a line break. |
| |
| *i_CTRL-X* *insert_expand* |
| CTRL-X enters a sub-mode where several commands can be used. Most of these |
| commands do keyword completion; see |ins-completion|. These are not available |
| when Vim was compiled without the |+insert_expand| feature. |
| |
| Two commands can be used to scroll the window up or down, without exiting |
| insert mode: |
| |
| *i_CTRL-X_CTRL-E* |
| CTRL-X CTRL-E scroll window one line up. |
| When doing completion look here: |complete_CTRL-E| |
| |
| *i_CTRL-X_CTRL-Y* |
| CTRL-X CTRL-Y scroll window one line down. |
| When doing completion look here: |complete_CTRL-Y| |
| |
| After CTRL-X is pressed, each CTRL-E (CTRL-Y) scrolls the window up (down) by |
| one line unless that would cause the cursor to move from its current position |
| in the file. As soon as another key is pressed, CTRL-X mode is exited and |
| that key is interpreted as in Insert mode. |
| |
| |
| ============================================================================== |
| 2. Special special keys *ins-special-special* |
| |
| The following keys are special. They stop the current insert, do something, |
| and then restart insertion. This means you can do something without getting |
| out of Insert mode. This is very handy if you prefer to use the Insert mode |
| all the time, just like editors that don't have a separate Normal mode. You |
| may also want to set the 'backspace' option to "indent,eol,start" and set the |
| 'insertmode' option. You can use CTRL-O if you want to map a function key to |
| a command. |
| |
| The changes (inserted or deleted characters) before and after these keys can |
| be undone separately. Only the last change can be redone and always behaves |
| like an "i" command. |
| |
| char action ~ |
| ----------------------------------------------------------------------- |
| <Up> cursor one line up *i_<Up>* |
| <Down> cursor one line down *i_<Down>* |
| CTRL-G <Up> cursor one line up, insert start column *i_CTRL-G_<Up>* |
| CTRL-G k cursor one line up, insert start column *i_CTRL-G_k* |
| CTRL-G CTRL-K cursor one line up, insert start column *i_CTRL-G_CTRL-K* |
| CTRL-G <Down> cursor one line down, insert start column *i_CTRL-G_<Down>* |
| CTRL-G j cursor one line down, insert start column *i_CTRL-G_j* |
| CTRL-G CTRL-J cursor one line down, insert start column *i_CTRL-G_CTRL-J* |
| <Left> cursor one character left *i_<Left>* |
| <Right> cursor one character right *i_<Right>* |
| <S-Left> cursor one word back (like "b" command) *i_<S-Left>* |
| <C-Left> cursor one word back (like "b" command) *i_<C-Left>* |
| <S-Right> cursor one word forward (like "w" command) *i_<S-Right>* |
| <C-Right> cursor one word forward (like "w" command) *i_<C-Right>* |
| <Home> cursor to first char in the line *i_<Home>* |
| <End> cursor to after last char in the line *i_<End>* |
| <C-Home> cursor to first char in the file *i_<C-Home>* |
| <C-End> cursor to after last char in the file *i_<C-End>* |
| <LeftMouse> cursor to position of mouse click *i_<LeftMouse>* |
| <S-Up> move window one page up *i_<S-Up>* |
| <PageUp> move window one page up *i_<PageUp>* |
| <S-Down> move window one page down *i_<S-Down>* |
| <PageDown> move window one page down *i_<PageDown>* |
| <ScrollWheelDown> move window three lines down *i_<ScrollWheelDown>* |
| <S-ScrollWheelDown> move window one page down *i_<S-ScrollWheelDown>* |
| <ScrollWheelUp> move window three lines up *i_<ScrollWheelUp>* |
| <S-ScrollWheelUp> move window one page up *i_<S-ScrollWheelUp>* |
| <ScrollWheelLeft> move window six columns left *i_<ScrollWheelLeft>* |
| <S-ScrollWheelLeft> move window one page left *i_<S-ScrollWheelLeft>* |
| <ScrollWheelRight> move window six columns right *i_<ScrollWheelRight>* |
| <S-ScrollWheelRight> move window one page right *i_<S-ScrollWheelRight>* |
| CTRL-O execute one command, return to Insert mode *i_CTRL-O* |
| CTRL-\ CTRL-O like CTRL-O but don't move the cursor *i_CTRL-\_CTRL-O* |
| CTRL-L when 'insertmode' is set: go to Normal mode *i_CTRL-L* |
| CTRL-G u break undo sequence, start new change *i_CTRL-G_u* |
| ----------------------------------------------------------------------- |
| |
| Note: If the cursor keys take you out of Insert mode, check the 'noesckeys' |
| option. |
| |
| The CTRL-O command sometimes has a side effect: If the cursor was beyond the |
| end of the line, it will be put on the last character in the line. In |
| mappings it's often better to use <Esc> (first put an "x" in the text, <Esc> |
| will then always put the cursor on it). Or use CTRL-\ CTRL-O, but then |
| beware of the cursor possibly being beyond the end of the line. |
| |
| The CTRL-O command takes you to Normal mode. If you then use a command enter |
| Insert mode again it normally doesn't nest. Thus when typing "a<C-O>a" and |
| then <Esc> takes you back to Normal mode, you do not need to type <Esc> twice. |
| An exception is when not typing the command, e.g. when executing a mapping or |
| sourcing a script. This makes mappings work that briefly switch to Insert |
| mode. |
| |
| The shifted cursor keys are not available on all terminals. |
| |
| Another side effect is that a count specified before the "i" or "a" command is |
| ignored. That is because repeating the effect of the command after CTRL-O is |
| too complicated. |
| |
| An example for using CTRL-G u: > |
| |
| :inoremap <C-H> <C-G>u<C-H> |
| |
| This redefines the backspace key to start a new undo sequence. You can now |
| undo the effect of the backspace key, without changing what you typed before |
| that, with CTRL-O u. Another example: > |
| |
| :inoremap <CR> <C-]><C-G>u<CR> |
| |
| This breaks undo at each line break. It also expands abbreviations before |
| this. |
| |
| Using CTRL-O splits undo: the text typed before and after it is undone |
| separately. If you want to avoid this (e.g., in a mapping) you might be able |
| to use CTRL-R = |i_CTRL-R|. E.g., to call a function: > |
| :imap <F2> <C-R>=MyFunc()<CR> |
| |
| When the 'whichwrap' option is set appropriately, the <Left> and <Right> |
| keys on the first/last character in the line make the cursor wrap to the |
| previous/next line. |
| |
| The CTRL-G j and CTRL-G k commands can be used to insert text in front of a |
| column. Example: > |
| int i; |
| int j; |
| Position the cursor on the first "int", type "istatic <C-G>j ". The |
| result is: > |
| static int i; |
| int j; |
| When inserting the same text in front of the column in every line, use the |
| Visual blockwise command "I" |v_b_I|. |
| |
| ============================================================================== |
| 3. 'textwidth' and 'wrapmargin' options *ins-textwidth* |
| |
| The 'textwidth' option can be used to automatically break a line before it |
| gets too long. Set the 'textwidth' option to the desired maximum line |
| length. If you then type more characters (not spaces or tabs), the |
| last word will be put on a new line (unless it is the only word on the |
| line). If you set 'textwidth' to 0, this feature is disabled. |
| |
| The 'wrapmargin' option does almost the same. The difference is that |
| 'textwidth' has a fixed width while 'wrapmargin' depends on the width of the |
| screen. When using 'wrapmargin' this is equal to using 'textwidth' with a |
| value equal to (columns - 'wrapmargin'), where columns is the width of the |
| screen. |
| |
| When 'textwidth' and 'wrapmargin' are both set, 'textwidth' is used. |
| |
| If you don't really want to break the line, but view the line wrapped at a |
| convenient place, see the 'linebreak' option. |
| |
| The line is only broken automatically when using Insert mode, or when |
| appending to a line. When in replace mode and the line length is not |
| changed, the line will not be broken. |
| |
| Long lines are broken if you enter a non-white character after the margin. |
| The situations where a line will be broken can be restricted by adding |
| characters to the 'formatoptions' option: |
| "l" Only break a line if it was not longer than 'textwidth' when the insert |
| started. |
| "v" Only break at a white character that has been entered during the |
| current insert command. This is mostly Vi-compatible. |
| "lv" Only break if the line was not longer than 'textwidth' when the insert |
| started and only at a white character that has been entered during the |
| current insert command. Only differs from "l" when entering non-white |
| characters while crossing the 'textwidth' boundary. |
| |
| Normally an internal function will be used to decide where to break the line. |
| If you want to do it in a different way set the 'formatexpr' option to an |
| expression that will take care of the line break. |
| |
| If you want to format a block of text, you can use the "gq" operator. Type |
| "gq" and a movement command to move the cursor to the end of the block. In |
| many cases, the command "gq}" will do what you want (format until the end of |
| paragraph). Alternatively, you can use "gqap", which will format the whole |
| paragraph, no matter where the cursor currently is. Or you can use Visual |
| mode: hit "v", move to the end of the block, and type "gq". See also |gq|. |
| |
| ============================================================================== |
| 4. 'expandtab', 'smarttab' and 'softtabstop' options *ins-expandtab* |
| |
| If the 'expandtab' option is on, spaces will be used to fill the amount of |
| whitespace of the tab. If you want to enter a real <Tab>, type CTRL-V first |
| (use CTRL-Q when CTRL-V is mapped |i_CTRL-Q|). |
| The 'expandtab' option is off by default. Note that in Replace mode, a single |
| character is replaced with several spaces. The result of this is that the |
| number of characters in the line increases. Backspacing will delete one |
| space at a time. The original character will be put back for only one space |
| that you backspace over (the last one). {Vi does not have the 'expandtab' |
| option} |
| |
| *ins-smarttab* |
| When the 'smarttab' option is on, a <Tab> inserts 'shiftwidth' positions at |
| the beginning of a line and 'tabstop' positions in other places. This means |
| that often spaces instead of a <Tab> character are inserted. When 'smarttab' |
| is off, a <Tab> always inserts 'tabstop' positions, and 'shiftwidth' is only |
| used for ">>" and the like. {not in Vi} |
| |
| *ins-softtabstop* |
| When the 'softtabstop' option is non-zero, a <Tab> inserts 'softtabstop' |
| positions, and a <BS> used to delete white space, will delete 'softtabstop' |
| positions. This feels like 'tabstop' was set to 'softtabstop', but a real |
| <Tab> character still takes 'tabstop' positions, so your file will still look |
| correct when used by other applications. |
| |
| If 'softtabstop' is non-zero, a <BS> will try to delete as much white space to |
| move to the previous 'softtabstop' position, except when the previously |
| inserted character is a space, then it will only delete the character before |
| the cursor. Otherwise you cannot always delete a single character before the |
| cursor. You will have to delete 'softtabstop' characters first, and then type |
| extra spaces to get where you want to be. |
| |
| ============================================================================== |
| 5. Replace mode *Replace* *Replace-mode* *mode-replace* |
| |
| Enter Replace mode with the "R" command in normal mode. |
| |
| In Replace mode, one character in the line is deleted for every character you |
| type. If there is no character to delete (at the end of the line), the |
| typed character is appended (as in Insert mode). Thus the number of |
| characters in a line stays the same until you get to the end of the line. |
| If a <NL> is typed, a line break is inserted and no character is deleted. |
| |
| Be careful with <Tab> characters. If you type a normal printing character in |
| its place, the number of characters is still the same, but the number of |
| columns will become smaller. |
| |
| If you delete characters in Replace mode (with <BS>, CTRL-W, or CTRL-U), what |
| happens is that you delete the changes. The characters that were replaced |
| are restored. If you had typed past the existing text, the characters you |
| added are deleted. This is effectively a character-at-a-time undo. |
| |
| If the 'expandtab' option is on, a <Tab> will replace one character with |
| several spaces. The result of this is that the number of characters in the |
| line increases. Backspacing will delete one space at a time. The original |
| character will be put back for only one space that you backspace over (the |
| last one). {Vi does not have the 'expandtab' option} |
| |
| ============================================================================== |
| 6. Virtual Replace mode *vreplace-mode* *Virtual-Replace-mode* |
| |
| Enter Virtual Replace mode with the "gR" command in normal mode. |
| {not available when compiled without the |+vreplace| feature} |
| {Vi does not have Virtual Replace mode} |
| |
| Virtual Replace mode is similar to Replace mode, but instead of replacing |
| actual characters in the file, you are replacing screen real estate, so that |
| characters further on in the file never appear to move. |
| |
| So if you type a <Tab> it may replace several normal characters, and if you |
| type a letter on top of a <Tab> it may not replace anything at all, since the |
| <Tab> will still line up to the same place as before. |
| |
| Typing a <NL> still doesn't cause characters later in the file to appear to |
| move. The rest of the current line will be replaced by the <NL> (that is, |
| they are deleted), and replacing continues on the next line. A new line is |
| NOT inserted unless you go past the end of the file. |
| |
| Interesting effects are seen when using CTRL-T and CTRL-D. The characters |
| before the cursor are shifted sideways as normal, but characters later in the |
| line still remain still. CTRL-T will hide some of the old line under the |
| shifted characters, but CTRL-D will reveal them again. |
| |
| As with Replace mode, using <BS> etc will bring back the characters that were |
| replaced. This still works in conjunction with 'smartindent', CTRL-T and |
| CTRL-D, 'expandtab', 'smarttab', 'softtabstop', etc. |
| |
| In 'list' mode, Virtual Replace mode acts as if it was not in 'list' mode, |
| unless "L" is in 'cpoptions'. |
| |
| Note that the only situations for which characters beyond the cursor should |
| appear to move are in List mode |'list'|, and occasionally when 'wrap' is set |
| (and the line changes length to become shorter or wider than the width of the |
| screen). In other cases spaces may be inserted to avoid following characters |
| to move. |
| |
| This mode is very useful for editing <Tab> separated columns in tables, for |
| entering new data while keeping all the columns aligned. |
| |
| ============================================================================== |
| 7. Insert mode completion *ins-completion* |
| |
| In Insert and Replace mode, there are several commands to complete part of a |
| keyword or line that has been typed. This is useful if you are using |
| complicated keywords (e.g., function names with capitals and underscores). |
| |
| These commands are not available when the |+insert_expand| feature was |
| disabled at compile time. |
| |
| Completion can be done for: |
| |
| 1. Whole lines |i_CTRL-X_CTRL-L| |
| 2. keywords in the current file |i_CTRL-X_CTRL-N| |
| 3. keywords in 'dictionary' |i_CTRL-X_CTRL-K| |
| 4. keywords in 'thesaurus', thesaurus-style |i_CTRL-X_CTRL-T| |
| 5. keywords in the current and included files |i_CTRL-X_CTRL-I| |
| 6. tags |i_CTRL-X_CTRL-]| |
| 7. file names |i_CTRL-X_CTRL-F| |
| 8. definitions or macros |i_CTRL-X_CTRL-D| |
| 9. Vim command-line |i_CTRL-X_CTRL-V| |
| 10. User defined completion |i_CTRL-X_CTRL-U| |
| 11. omni completion |i_CTRL-X_CTRL-O| |
| 12. Spelling suggestions |i_CTRL-X_s| |
| 13. keywords in 'complete' |i_CTRL-N| |
| |
| All these (except 2) are done in CTRL-X mode. This is a sub-mode of Insert |
| and Replace modes. You enter CTRL-X mode by typing CTRL-X and one of the |
| CTRL-X commands. You exit CTRL-X mode by typing a key that is not a valid |
| CTRL-X mode command. Valid keys are the CTRL-X command itself, CTRL-N (next), |
| and CTRL-P (previous). |
| |
| Also see the 'infercase' option if you want to adjust the case of the match. |
| |
| *complete_CTRL-E* |
| When completion is active you can use CTRL-E to stop it and go back to the |
| originally typed text. The CTRL-E will not be inserted. |
| |
| *complete_CTRL-Y* |
| When the popup menu is displayed you can use CTRL-Y to stop completion and |
| accept the currently selected entry. The CTRL-Y is not inserted. Typing a |
| space, Enter, or some other unprintable character will leave completion mode |
| and insert that typed character. |
| |
| When the popup menu is displayed there are a few more special keys, see |
| |popupmenu-keys|. |
| |
| Note: The keys that are valid in CTRL-X mode are not mapped. This allows for |
| ":map ^F ^X^F" to work (where ^F is CTRL-F and ^X is CTRL-X). The key that |
| ends CTRL-X mode (any key that is not a valid CTRL-X mode command) is mapped. |
| Also, when doing completion with 'complete' mappings apply as usual. |
| |
| Note: While completion is active Insert mode can't be used recursively. |
| Mappings that somehow invoke ":normal i.." will generate an E523 error. |
| |
| The following mappings are suggested to make typing the completion commands |
| a bit easier (although they will hide other commands): > |
| :inoremap ^] ^X^] |
| :inoremap ^F ^X^F |
| :inoremap ^D ^X^D |
| :inoremap ^L ^X^L |
| |
| As a special case, typing CTRL-R to perform register insertion (see |
| |i_CTRL-R|) will not exit CTRL-X mode. This is primarily to allow the use of |
| the '=' register to call some function to determine the next operation. If |
| the contents of the register (or result of the '=' register evaluation) are |
| not valid CTRL-X mode keys, then CTRL-X mode will be exited as if those keys |
| had been typed. |
| |
| For example, the following will map <Tab> to either actually insert a <Tab> if |
| the current line is currently only whitespace, or start/continue a CTRL-N |
| completion operation: > |
| |
| function! CleverTab() |
| if strpart( getline('.'), 0, col('.')-1 ) =~ '^\s*$' |
| return "\<Tab>" |
| else |
| return "\<C-N>" |
| endif |
| endfunction |
| inoremap <Tab> <C-R>=CleverTab()<CR> |
| |
| |
| |
| Completing whole lines *compl-whole-line* |
| |
| *i_CTRL-X_CTRL-L* |
| CTRL-X CTRL-L Search backwards for a line that starts with the |
| same characters as those in the current line before |
| the cursor. Indent is ignored. The matching line is |
| inserted in front of the cursor. |
| The 'complete' option is used to decide which buffers |
| are searched for a match. Both loaded and unloaded |
| buffers are used. |
| CTRL-L or |
| CTRL-P Search backwards for next matching line. This line |
| replaces the previous matching line. |
| |
| CTRL-N Search forward for next matching line. This line |
| replaces the previous matching line. |
| |
| CTRL-X CTRL-L After expanding a line you can additionally get the |
| line next to it by typing CTRL-X CTRL-L again, unless |
| a double CTRL-X is used. Only works for loaded |
| buffers. |
| |
| Completing keywords in current file *compl-current* |
| |
| *i_CTRL-X_CTRL-P* |
| *i_CTRL-X_CTRL-N* |
| CTRL-X CTRL-N Search forwards for words that start with the keyword |
| in front of the cursor. The found keyword is inserted |
| in front of the cursor. |
| |
| CTRL-X CTRL-P Search backwards for words that start with the keyword |
| in front of the cursor. The found keyword is inserted |
| in front of the cursor. |
| |
| CTRL-N Search forward for next matching keyword. This |
| keyword replaces the previous matching keyword. |
| |
| CTRL-P Search backwards for next matching keyword. This |
| keyword replaces the previous matching keyword. |
| |
| CTRL-X CTRL-N or |
| CTRL-X CTRL-P Further use of CTRL-X CTRL-N or CTRL-X CTRL-P will |
| copy the words following the previous expansion in |
| other contexts unless a double CTRL-X is used. |
| |
| If there is a keyword in front of the cursor (a name made out of alphabetic |
| characters and characters in 'iskeyword'), it is used as the search pattern, |
| with "\<" prepended (meaning: start of a word). Otherwise "\<\k\k" is used |
| as search pattern (start of any keyword of at least two characters). |
| |
| In Replace mode, the number of characters that are replaced depends on the |
| length of the matched string. This works like typing the characters of the |
| matched string in Replace mode. |
| |
| If there is not a valid keyword character before the cursor, any keyword of |
| at least two characters is matched. |
| e.g., to get: |
| printf("(%g, %g, %g)", vector[0], vector[1], vector[2]); |
| just type: |
| printf("(%g, %g, %g)", vector[0], ^P[1], ^P[2]); |
| |
| The search wraps around the end of the file, the value of 'wrapscan' is not |
| used here. |
| |
| Multiple repeats of the same completion are skipped; thus a different match |
| will be inserted at each CTRL-N and CTRL-P (unless there is only one |
| matching keyword). |
| |
| Single character matches are never included, as they usually just get in |
| the way of what you were really after. |
| e.g., to get: |
| printf("name = %s\n", name); |
| just type: |
| printf("name = %s\n", n^P); |
| or even: |
| printf("name = %s\n", ^P); |
| The 'n' in '\n' is skipped. |
| |
| After expanding a word, you can use CTRL-X CTRL-P or CTRL-X CTRL-N to get the |
| word following the expansion in other contexts. These sequences search for |
| the text just expanded and further expand by getting an extra word. This is |
| useful if you need to repeat a sequence of complicated words. Although CTRL-P |
| and CTRL-N look just for strings of at least two characters, CTRL-X CTRL-P and |
| CTRL-X CTRL-N can be used to expand words of just one character. |
| e.g., to get: |
| México |
| you can type: |
| M^N^P^X^P^X^P |
| CTRL-N starts the expansion and then CTRL-P takes back the single character |
| "M", the next two CTRL-X CTRL-P's get the words "é" and ";xico". |
| |
| If the previous expansion was split, because it got longer than 'textwidth', |
| then just the text in the current line will be used. |
| |
| If the match found is at the end of a line, then the first word in the next |
| line will be inserted and the message "word from next line" displayed, if |
| this word is accepted the next CTRL-X CTRL-P or CTRL-X CTRL-N will search |
| for those lines starting with this word. |
| |
| |
| Completing keywords in 'dictionary' *compl-dictionary* |
| |
| *i_CTRL-X_CTRL-K* |
| CTRL-X CTRL-K Search the files given with the 'dictionary' option |
| for words that start with the keyword in front of the |
| cursor. This is like CTRL-N, but only the dictionary |
| files are searched, not the current file. The found |
| keyword is inserted in front of the cursor. This |
| could potentially be pretty slow, since all matches |
| are found before the first match is used. By default, |
| the 'dictionary' option is empty. |
| For suggestions where to find a list of words, see the |
| 'dictionary' option. |
| |
| CTRL-K or |
| CTRL-N Search forward for next matching keyword. This |
| keyword replaces the previous matching keyword. |
| |
| CTRL-P Search backwards for next matching keyword. This |
| keyword replaces the previous matching keyword. |
| |
| *i_CTRL-X_CTRL-T* |
| CTRL-X CTRL-T Works as CTRL-X CTRL-K, but in a special way. It uses |
| the 'thesaurus' option instead of 'dictionary'. If a |
| match is found in the thesaurus file, all the |
| remaining words on the same line are included as |
| matches, even though they don't complete the word. |
| Thus a word can be completely replaced. |
| |
| For an example, imagine the 'thesaurus' file has a |
| line like this: > |
| angry furious mad enraged |
| < Placing the cursor after the letters "ang" and typing |
| CTRL-X CTRL-T would complete the word "angry"; |
| subsequent presses would change the word to "furious", |
| "mad" etc. |
| Other uses include translation between two languages, |
| or grouping API functions by keyword. |
| |
| CTRL-T or |
| CTRL-N Search forward for next matching keyword. This |
| keyword replaces the previous matching keyword. |
| |
| CTRL-P Search backwards for next matching keyword. This |
| keyword replaces the previous matching keyword. |
| |
| |
| Completing keywords in the current and included files *compl-keyword* |
| |
| The 'include' option is used to specify a line that contains an include file |
| name. The 'path' option is used to search for include files. |
| |
| *i_CTRL-X_CTRL-I* |
| CTRL-X CTRL-I Search for the first keyword in the current and |
| included files that starts with the same characters |
| as those before the cursor. The matched keyword is |
| inserted in front of the cursor. |
| |
| CTRL-N Search forwards for next matching keyword. This |
| keyword replaces the previous matching keyword. |
| Note: CTRL-I is the same as <Tab>, which is likely to |
| be typed after a successful completion, therefore |
| CTRL-I is not used for searching for the next match. |
| |
| CTRL-P Search backward for previous matching keyword. This |
| keyword replaces the previous matching keyword. |
| |
| CTRL-X CTRL-I Further use of CTRL-X CTRL-I will copy the words |
| following the previous expansion in other contexts |
| unless a double CTRL-X is used. |
| |
| Completing tags *compl-tag* |
| *i_CTRL-X_CTRL-]* |
| CTRL-X CTRL-] Search for the first tag that starts with the same |
| characters as before the cursor. The matching tag is |
| inserted in front of the cursor. Alphabetic |
| characters and characters in 'iskeyword' are used |
| to decide which characters are included in the tag |
| name (same as for a keyword). See also |CTRL-]|. |
| The 'showfulltag' option can be used to add context |
| from around the tag definition. |
| CTRL-] or |
| CTRL-N Search forwards for next matching tag. This tag |
| replaces the previous matching tag. |
| |
| CTRL-P Search backward for previous matching tag. This tag |
| replaces the previous matching tag. |
| |
| |
| Completing file names *compl-filename* |
| *i_CTRL-X_CTRL-F* |
| CTRL-X CTRL-F Search for the first file name that starts with the |
| same characters as before the cursor. The matching |
| file name is inserted in front of the cursor. |
| Alphabetic characters and characters in 'isfname' |
| are used to decide which characters are included in |
| the file name. Note: the 'path' option is not used |
| here (yet). |
| CTRL-F or |
| CTRL-N Search forwards for next matching file name. This |
| file name replaces the previous matching file name. |
| |
| CTRL-P Search backward for previous matching file name. |
| This file name replaces the previous matching file |
| name. |
| |
| |
| Completing definitions or macros *compl-define* |
| |
| The 'define' option is used to specify a line that contains a definition. |
| The 'include' option is used to specify a line that contains an include file |
| name. The 'path' option is used to search for include files. |
| |
| *i_CTRL-X_CTRL-D* |
| CTRL-X CTRL-D Search in the current and included files for the |
| first definition (or macro) name that starts with |
| the same characters as before the cursor. The found |
| definition name is inserted in front of the cursor. |
| CTRL-D or |
| CTRL-N Search forwards for next matching macro name. This |
| macro name replaces the previous matching macro |
| name. |
| |
| CTRL-P Search backward for previous matching macro name. |
| This macro name replaces the previous matching macro |
| name. |
| |
| CTRL-X CTRL-D Further use of CTRL-X CTRL-D will copy the words |
| following the previous expansion in other contexts |
| unless a double CTRL-X is used. |
| |
| |
| Completing Vim commands *compl-vim* |
| |
| Completion is context-sensitive. It works like on the Command-line. It |
| completes an Ex command as well as its arguments. This is useful when writing |
| a Vim script. |
| |
| *i_CTRL-X_CTRL-V* |
| CTRL-X CTRL-V Guess what kind of item is in front of the cursor and |
| find the first match for it. |
| Note: When CTRL-V is mapped you can often use CTRL-Q |
| instead of |i_CTRL-Q|. |
| CTRL-V or |
| CTRL-N Search forwards for next match. This match replaces |
| the previous one. |
| |
| CTRL-P Search backwards for previous match. This match |
| replaces the previous one. |
| |
| CTRL-X CTRL-V Further use of CTRL-X CTRL-V will do the same as |
| CTRL-V. This allows mapping a key to do Vim command |
| completion, for example: > |
| :imap <Tab> <C-X><C-V> |
| |
| User defined completion *compl-function* |
| |
| Completion is done by a function that can be defined by the user with the |
| 'completefunc' option. See below for how the function is called and an |
| example |complete-functions|. |
| |
| *i_CTRL-X_CTRL-U* |
| CTRL-X CTRL-U Guess what kind of item is in front of the cursor and |
| find the first match for it. |
| CTRL-U or |
| CTRL-N Use the next match. This match replaces the previous |
| one. |
| |
| CTRL-P Use the previous match. This match replaces the |
| previous one. |
| |
| |
| Omni completion *compl-omni* |
| |
| Completion is done by a function that can be defined by the user with the |
| 'omnifunc' option. This is to be used for filetype-specific completion. |
| |
| See below for how the function is called and an example |complete-functions|. |
| For remarks about specific filetypes see |compl-omni-filetypes|. |
| More completion scripts will appear, check www.vim.org. Currently there is a |
| first version for C++. |
| |
| *i_CTRL-X_CTRL-O* |
| CTRL-X CTRL-O Guess what kind of item is in front of the cursor and |
| find the first match for it. |
| CTRL-O or |
| CTRL-N Use the next match. This match replaces the previous |
| one. |
| |
| CTRL-P Use the previous match. This match replaces the |
| previous one. |
| |
| |
| Spelling suggestions *compl-spelling* |
| |
| A word before or at the cursor is located and correctly spelled words are |
| suggested to replace it. If there is a badly spelled word in the line, before |
| or under the cursor, the cursor is moved to after it. Otherwise the word just |
| before the cursor is used for suggestions, even though it isn't badly spelled. |
| |
| NOTE: CTRL-S suspends display in many Unix terminals. Use 's' instead. Type |
| CTRL-Q to resume displaying. |
| |
| *i_CTRL-X_CTRL-S* *i_CTRL-X_s* |
| CTRL-X CTRL-S or |
| CTRL-X s Locate the word in front of the cursor and find the |
| first spell suggestion for it. |
| CTRL-S or |
| CTRL-N Use the next suggestion. This replaces the previous |
| one. Note that you can't use 's' here. |
| |
| CTRL-P Use the previous suggestion. This replaces the |
| previous one. |
| |
| |
| Completing keywords from different sources *compl-generic* |
| |
| *i_CTRL-N* |
| CTRL-N Find next match for words that start with the |
| keyword in front of the cursor, looking in places |
| specified with the 'complete' option. The found |
| keyword is inserted in front of the cursor. |
| |
| *i_CTRL-P* |
| CTRL-P Find previous match for words that start with the |
| keyword in front of the cursor, looking in places |
| specified with the 'complete' option. The found |
| keyword is inserted in front of the cursor. |
| |
| CTRL-N Search forward for next matching keyword. This |
| keyword replaces the previous matching keyword. |
| |
| CTRL-P Search backwards for next matching keyword. This |
| keyword replaces the previous matching keyword. |
| |
| CTRL-X CTRL-N or |
| CTRL-X CTRL-P Further use of CTRL-X CTRL-N or CTRL-X CTRL-P will |
| copy the words following the previous expansion in |
| other contexts unless a double CTRL-X is used. |
| |
| |
| FUNCTIONS FOR FINDING COMPLETIONS *complete-functions* |
| |
| This applies to 'completefunc' and 'omnifunc'. |
| |
| The function is called in two different ways: |
| - First the function is called to find the start of the text to be completed. |
| - Later the function is called to actually find the matches. |
| |
| On the first invocation the arguments are: |
| a:findstart 1 |
| a:base empty |
| |
| The function must return the column where the completion starts. It must be a |
| number between zero and the cursor column "col('.')". This involves looking |
| at the characters just before the cursor and including those characters that |
| could be part of the completed item. The text between this column and the |
| cursor column will be replaced with the matches. |
| |
| Special return values: |
| -1 If no completion can be done, the completion will be cancelled with an |
| error message. |
| -2 To cancel silently and stay in completion mode. |
| -3 To cancel silently and leave completion mode. |
| |
| On the second invocation the arguments are: |
| a:findstart 0 |
| a:base the text with which matches should match; the text that was |
| located in the first call (can be empty) |
| |
| The function must return a List with the matching words. These matches |
| usually include the "a:base" text. When there are no matches return an empty |
| List. |
| |
| In order to return more information than the matching words, return a Dict |
| that contains the List. The Dict can have these items: |
| words The List of matching words (mandatory). |
| refresh A string to control re-invocation of the function |
| (optional). |
| The only value currently recognized is "always", the |
| effect is that the function is called whenever the |
| leading text is changed. |
| Other items are ignored. |
| |
| For acting upon end of completion, see the |CompleteDone| autocommand event. |
| |
| For example, the function can contain this: > |
| let matches = ... list of words ... |
| return {'words': matches, 'refresh': 'always'} |
| < |
| *complete-items* |
| Each list item can either be a string or a Dictionary. When it is a string it |
| is used as the completion. When it is a Dictionary it can contain these |
| items: |
| word the text that will be inserted, mandatory |
| abbr abbreviation of "word"; when not empty it is used in |
| the menu instead of "word" |
| menu extra text for the popup menu, displayed after "word" |
| or "abbr" |
| info more information about the item, can be displayed in a |
| preview window |
| kind single letter indicating the type of completion |
| icase when non-zero case is to be ignored when comparing |
| items to be equal; when omitted zero is used, thus |
| items that only differ in case are added |
| dup when non-zero this match will be added even when an |
| item with the same word is already present. |
| empty when non-zero this match will be added even when it is |
| an empty string |
| |
| All of these except 'icase', 'dup' and 'empty' must be a string. If an item |
| does not meet these requirements then an error message is given and further |
| items in the list are not used. You can mix string and Dictionary items in |
| the returned list. |
| |
| The "menu" item is used in the popup menu and may be truncated, thus it should |
| be relatively short. The "info" item can be longer, it will be displayed in |
| the preview window when "preview" appears in 'completeopt'. The "info" item |
| will also remain displayed after the popup menu has been removed. This is |
| useful for function arguments. Use a single space for "info" to remove |
| existing text in the preview window. The size of the preview window is three |
| lines, but 'previewheight' is used when it has a value of 1 or 2. |
| |
| The "kind" item uses a single letter to indicate the kind of completion. This |
| may be used to show the completion differently (different color or icon). |
| Currently these types can be used: |
| v variable |
| f function or method |
| m member of a struct or class |
| t typedef |
| d #define or macro |
| |
| When searching for matches takes some time call |complete_add()| to add each |
| match to the total list. These matches should then not appear in the returned |
| list! Call |complete_check()| now and then to allow the user to press a key |
| while still searching for matches. Stop searching when it returns non-zero. |
| |
| *E839* *E840* |
| The function is allowed to move the cursor, it is restored afterwards. |
| The function is not allowed to move to another window or delete text. |
| |
| An example that completes the names of the months: > |
| fun! CompleteMonths(findstart, base) |
| if a:findstart |
| " locate the start of the word |
| let line = getline('.') |
| let start = col('.') - 1 |
| while start > 0 && line[start - 1] =~ '\a' |
| let start -= 1 |
| endwhile |
| return start |
| else |
| " find months matching with "a:base" |
| let res = [] |
| for m in split("Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec") |
| if m =~ '^' . a:base |
| call add(res, m) |
| endif |
| endfor |
| return res |
| endif |
| endfun |
| set completefunc=CompleteMonths |
| < |
| The same, but now pretending searching for matches is slow: > |
| fun! CompleteMonths(findstart, base) |
| if a:findstart |
| " locate the start of the word |
| let line = getline('.') |
| let start = col('.') - 1 |
| while start > 0 && line[start - 1] =~ '\a' |
| let start -= 1 |
| endwhile |
| return start |
| else |
| " find months matching with "a:base" |
| for m in split("Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec") |
| if m =~ '^' . a:base |
| call complete_add(m) |
| endif |
| sleep 300m " simulate searching for next match |
| if complete_check() |
| break |
| endif |
| endfor |
| return [] |
| endif |
| endfun |
| set completefunc=CompleteMonths |
| < |
| |
| INSERT COMPLETION POPUP MENU *ins-completion-menu* |
| *popupmenu-completion* |
| Vim can display the matches in a simplistic popup menu. |
| |
| The menu is used when: |
| - The 'completeopt' option contains "menu" or "menuone". |
| - The terminal supports at least 8 colors. |
| - There are at least two matches. One if "menuone" is used. |
| |
| The 'pumheight' option can be used to set a maximum height. The default is to |
| use all space available. |
| |
| There are three states: |
| 1. A complete match has been inserted, e.g., after using CTRL-N or CTRL-P. |
| 2. A cursor key has been used to select another match. The match was not |
| inserted then, only the entry in the popup menu is highlighted. |
| 3. Only part of a match has been inserted and characters were typed or the |
| backspace key was used. The list of matches was then adjusted for what is |
| in front of the cursor. |
| |
| You normally start in the first state, with the first match being inserted. |
| When "longest" is in 'completeopt' and there is more than one match you start |
| in the third state. |
| |
| If you select another match, e.g., with CTRL-N or CTRL-P, you go to the first |
| state. This doesn't change the list of matches. |
| |
| When you are back at the original text then you are in the third state. To |
| get there right away you can use a mapping that uses CTRL-P right after |
| starting the completion: > |
| :imap <F7> <C-N><C-P> |
| < |
| *popupmenu-keys* |
| In the first state these keys have a special meaning: |
| <BS> and CTRL-H Delete one character, find the matches for the word before |
| the cursor. This reduces the list of matches, often to one |
| entry, and switches to the second state. |
| Any non-special character: |
| Stop completion without changing the match and insert the |
| typed character. |
| |
| In the second and third state these keys have a special meaning: |
| <BS> and CTRL-H Delete one character, find the matches for the shorter word |
| before the cursor. This may find more matches. |
| CTRL-L Add one character from the current match, may reduce the |
| number of matches. |
| any printable, non-white character: |
| Add this character and reduce the number of matches. |
| |
| In all three states these can be used: |
| CTRL-Y Yes: Accept the currently selected match and stop completion. |
| CTRL-E End completion, go back to what was there before selecting a |
| match (what was typed or longest common string). |
| <PageUp> Select a match several entries back, but don't insert it. |
| <PageDown> Select a match several entries further, but don't insert it. |
| <Up> Select the previous match, as if CTRL-P was used, but don't |
| insert it. |
| <Down> Select the next match, as if CTRL-N was used, but don't |
| insert it. |
| <Space> or <Tab> Stop completion without changing the match and insert the |
| typed character. |
| |
| The behavior of the <Enter> key depends on the state you are in: |
| first state: Use the text as it is and insert a line break. |
| second state: Insert the currently selected match. |
| third state: Use the text as it is and insert a line break. |
| |
| In other words: If you used the cursor keys to select another entry in the |
| list of matches then the <Enter> key inserts that match. If you typed |
| something else then <Enter> inserts a line break. |
| |
| |
| The colors of the menu can be changed with these highlight groups: |
| Pmenu normal item |hl-Pmenu| |
| PmenuSel selected item |hl-PmenuSel| |
| PmenuSbar scrollbar |hl-PmenuSbar| |
| PmenuThumb thumb of the scrollbar |hl-PmenuThumb| |
| |
| There are no special mappings for when the popup menu is visible. However, |
| you can use an Insert mode mapping that checks the |pumvisible()| function to |
| do something different. Example: > |
| :inoremap <Down> <C-R>=pumvisible() ? "\<lt>C-N>" : "\<lt>Down>"<CR> |
| |
| You can use of <expr> in mapping to have the popup menu used when typing a |
| character and some condition is met. For example, for typing a dot: > |
| inoremap <expr> . MayComplete() |
| func MayComplete() |
| if (can complete) |
| return ".\<C-X>\<C-O>" |
| endif |
| return '.' |
| endfunc |
| |
| See |:map-<expr>| for more info. |
| |
| |
| FILETYPE-SPECIFIC REMARKS FOR OMNI COMPLETION *compl-omni-filetypes* |
| |
| The file used for {filetype} should be autoload/{filetype}complete.vim |
| in 'runtimepath'. Thus for "java" it is autoload/javacomplete.vim. |
| |
| |
| C *ft-c-omni* |
| |
| Completion of C code requires a tags file. You should use Exuberant ctags, |
| because it adds extra information that is needed for completion. You can find |
| it here: http://ctags.sourceforge.net/ Version 5.6 or later is recommended. |
| |
| For version 5.5.4 you should add a patch that adds the "typename:" field: |
| ftp://ftp.vim.org/pub/vim/unstable/patches/ctags-5.5.4.patch |
| A compiled .exe for MS-Windows can be found at: |
| http://georgevreilly.com/vim/ctags.html |
| |
| If you want to complete system functions you can do something like this. Use |
| ctags to generate a tags file for all the system header files: > |
| % ctags -R -f ~/.vim/systags /usr/include /usr/local/include |
| In your vimrc file add this tags file to the 'tags' option: > |
| set tags+=~/.vim/systags |
| |
| When using CTRL-X CTRL-O after a name without any "." or "->" it is completed |
| from the tags file directly. This works for any identifier, also function |
| names. If you want to complete a local variable name, which does not appear |
| in the tags file, use CTRL-P instead. |
| |
| When using CTRL-X CTRL-O after something that has "." or "->" Vim will attempt |
| to recognize the type of the variable and figure out what members it has. |
| This means only members valid for the variable will be listed. |
| |
| When a member name already was complete, CTRL-X CTRL-O will add a "." or |
| "->" for composite types. |
| |
| Vim doesn't include a C compiler, only the most obviously formatted |
| declarations are recognized. Preprocessor stuff may cause confusion. |
| When the same structure name appears in multiple places all possible members |
| are included. |
| |
| |
| CSS *ft-css-omni* |
| |
| Complete properties and their appropriate values according to CSS 2.1 |
| specification. |
| |
| |
| HTML *ft-html-omni* |
| XHTML *ft-xhtml-omni* |
| |
| CTRL-X CTRL-O provides completion of various elements of (X)HTML files. It is |
| designed to support writing of XHTML 1.0 Strict files but will also works for |
| other versions of HTML. Features: |
| |
| - after "<" complete tag name depending on context (no div suggestion inside |
| of an a tag); '/>' indicates empty tags |
| - inside of tag complete proper attributes (no width attribute for an a tag); |
| show also type of attribute; '*' indicates required attributes |
| - when attribute has limited number of possible values help to complete them |
| - complete names of entities |
| - complete values of "class" and "id" attributes with data obtained from |
| <style> tag and included CSS files |
| - when completing value of "style" attribute or working inside of "style" tag |
| switch to |ft-css-omni| completion |
| - when completing values of events attributes or working inside of "script" |
| tag switch to |ft-javascript-omni| completion |
| - when used after "</" CTRL-X CTRL-O will close the last opened tag |
| |
| Note: When used first time completion menu will be shown with little delay |
| - this is time needed for loading of data file. |
| Note: Completion may fail in badly formatted documents. In such case try to |
| run |:make| command to detect formatting problems. |
| |
| |
| HTML flavor *html-flavor* |
| |
| The default HTML completion depends on the filetype. For HTML files it is |
| HTML 4.01 Transitional ('filetype' is "html"), for XHTML it is XHTML 1.0 |
| Strict ('filetype' is "xhtml"). |
| |
| When doing completion outside of any other tag you will have possibility to |
| choose DOCTYPE and the appropriate data file will be loaded and used for all |
| next completions. |
| |
| More about format of data file in |xml-omni-datafile|. Some of the data files |
| may be found on the Vim website (|www|). |
| |
| Note that b:html_omni_flavor may point to a file with any XML data. This |
| makes possible to mix PHP (|ft-php-omni|) completion with any XML dialect |
| (assuming you have data file for it). Without setting that variable XHTML 1.0 |
| Strict will be used. |
| |
| |
| JAVASCRIPT *ft-javascript-omni* |
| |
| Completion of most elements of JavaScript language and DOM elements. |
| |
| Complete: |
| |
| - variables |
| - function name; show function arguments |
| - function arguments |
| - properties of variables trying to detect type of variable |
| - complete DOM objects and properties depending on context |
| - keywords of language |
| |
| Completion works in separate JavaScript files (&ft==javascript), inside of |
| <script> tag of (X)HTML and in values of event attributes (including scanning |
| of external files. |
| |
| DOM compatibility |
| |
| At the moment (beginning of 2006) there are two main browsers - MS Internet |
| Explorer and Mozilla Firefox. These two applications are covering over 90% of |
| market. Theoretically standards are created by W3C organisation |
| (http://www.w3c.org) but they are not always followed/implemented. |
| |
| IE FF W3C Omni completion ~ |
| +/- +/- + + ~ |
| + + - + ~ |
| + - - - ~ |
| - + - - ~ |
| |
| Regardless from state of implementation in browsers but if element is defined |
| in standards, completion plugin will place element in suggestion list. When |
| both major engines implemented element, even if this is not in standards it |
| will be suggested. All other elements are not placed in suggestion list. |
| |
| |
| PHP *ft-php-omni* |
| |
| Completion of PHP code requires a tags file for completion of data from |
| external files and for class aware completion. You should use Exuberant ctags |
| version 5.5.4 or newer. You can find it here: http://ctags.sourceforge.net/ |
| |
| Script completes: |
| |
| - after $ variables name |
| - if variable was declared as object add "->", if tags file is available show |
| name of class |
| - after "->" complete only function and variable names specific for given |
| class. To find class location and contents tags file is required. Because |
| PHP isn't strongly typed language user can use @var tag to declare class: > |
| |
| /* @var $myVar myClass */ |
| $myVar-> |
| < |
| Still, to find myClass contents tags file is required. |
| |
| - function names with additional info: |
| - in case of built-in functions list of possible arguments and after | type |
| data returned by function |
| - in case of user function arguments and name of file where function was |
| defined (if it is not current file) |
| |
| - constants names |
| - class names after "new" declaration |
| |
| |
| Note: when doing completion first time Vim will load all necessary data into |
| memory. It may take several seconds. After next use of completion delay |
| should not be noticeable. |
| |
| Script detects if cursor is inside <?php ?> tags. If it is outside it will |
| automatically switch to HTML/CSS/JavaScript completion. Note: contrary to |
| original HTML files completion of tags (and only tags) isn't context aware. |
| |
| |
| RUBY *ft-ruby-omni* |
| |
| Completion of Ruby code requires that vim be built with |+ruby|. |
| |
| Ruby completion will parse your buffer on demand in order to provide a list of |
| completions. These completions will be drawn from modules loaded by 'require' |
| and modules defined in the current buffer. |
| |
| The completions provided by CTRL-X CTRL-O are sensitive to the context: |
| |
| CONTEXT COMPLETIONS PROVIDED ~ |
| |
| 1. Not inside a class definition Classes, constants and globals |
| |
| 2. Inside a class definition Methods or constants defined in the class |
| |
| 3. After '.', '::' or ':' Methods applicable to the object being |
| dereferenced |
| |
| 4. After ':' or ':foo' Symbol name (beginning with 'foo') |
| |
| Notes: |
| - Vim will load/evaluate code in order to provide completions. This may |
| cause some code execution, which may be a concern. This is no longer |
| enabled by default, to enable this feature add > |
| let g:rubycomplete_buffer_loading = 1 |
| <- In context 1 above, Vim can parse the entire buffer to add a list of |
| classes to the completion results. This feature is turned off by default, |
| to enable it add > |
| let g:rubycomplete_classes_in_global = 1 |
| < to your vimrc |
| - In context 2 above, anonymous classes are not supported. |
| - In context 3 above, Vim will attempt to determine the methods supported by |
| the object. |
| - Vim can detect and load the Rails environment for files within a rails |
| project. The feature is disabled by default, to enable it add > |
| let g:rubycomplete_rails = 1 |
| < to your vimrc |
| |
| |
| SYNTAX *ft-syntax-omni* |
| |
| Vim has the ability to color syntax highlight nearly 500 languages. Part of |
| this highlighting includes knowing what keywords are part of a language. Many |
| filetypes already have custom completion scripts written for them, the |
| syntaxcomplete plugin provides basic completion for all other filetypes. It |
| does this by populating the omni completion list with the text Vim already |
| knows how to color highlight. It can be used for any filetype and provides a |
| minimal language-sensitive completion. |
| |
| To enable syntax code completion you can run: > |
| setlocal omnifunc=syntaxcomplete#Complete |
| |
| You can automate this by placing the following in your vimrc (after any |
| ":filetype" command): > |
| if has("autocmd") && exists("+omnifunc") |
| autocmd Filetype * |
| \ if &omnifunc == "" | |
| \ setlocal omnifunc=syntaxcomplete#Complete | |
| \ endif |
| endif |
| |
| The above will set completion to this script only if a specific plugin does |
| not already exist for that filetype. |
| |
| Each filetype can have a wide range of syntax items. The plugin allows you to |
| customize which syntax groups to include or exclude from the list. Let's have |
| a look at the PHP filetype to see how this works. |
| |
| If you edit a file called, index.php, run the following command: > |
| :syntax list |
| |
| The first thing you will notice is that there are many different syntax groups. |
| The PHP language can include elements from different languages like HTML, |
| JavaScript and many more. The syntax plugin will only include syntax groups |
| that begin with the filetype, "php", in this case. For example these syntax |
| groups are included by default with the PHP: phpEnvVar, phpIntVar, |
| phpFunctions. |
| |
| The PHP language has an enormous number of items which it knows how to syntax |
| highlight. This means these items will be available within the omni |
| completion list. Some people may find this list unwieldy or are only |
| interested in certain items. |
| |
| There are two ways to prune this list (if necessary). If you find certain |
| syntax groups you do not wish displayed you can add the following to your |
| vimrc: > |
| let g:omni_syntax_group_exclude_php = 'phpCoreConstant,phpConstant' |
| |
| Add as many syntax groups to this list by comma separating them. The basic |
| form of this variable is: > |
| let g:omni_syntax_group_exclude_{filetype} = 'comma,separated,list' |
| |
| For completeness the opposite is also true. Creating this variable in your |
| vimrc will only include the items in the phpFunctions and phpMethods syntax |
| groups: > |
| let g:omni_syntax_group_include_php = 'phpFunctions,phpMethods' |
| |
| You can create as many of these variables as you need, varying only the |
| filetype at the end of the variable name. |
| |
| The plugin uses the isKeyword option to determine where word boundaries are |
| for the syntax items. For example, in the Scheme language completion should |
| include the "-", call-with-output-file. Depending on your filetype, this may |
| not provide the words you are expecting. Setting the |
| g:omni_syntax_use_iskeyword option to 0 will force the syntax plugin to break |
| on word characters. This can be controlled adding the following to your |
| vimrc: > |
| let g:omni_syntax_use_iskeyword = 0 |
| |
| For plugin developers, the plugin exposes a public function OmniSyntaxList. |
| This function can be used to request a List of syntax items. When editing a |
| SQL file (:e syntax.sql) you can use the ":syntax list" command to see the |
| various groups and syntax items. For example: > |
| syntax list |
| |
| Yields data similar to this: > |
| sqlOperator xxx some prior all like and any escape exists in is not |
| or intersect minus between distinct |
| links to Operator |
| sqlType xxx varbit varchar nvarchar bigint int uniqueidentifier |
| date money long tinyint unsigned xml text smalldate |
| double datetime nchar smallint numeric time bit char |
| varbinary binary smallmoney |
| image float integer timestamp real decimal |
| |
| There are two syntax groups listed here: sqlOperator and sqlType. To retrieve |
| a List of syntax items you can call OmniSyntaxList a number of different |
| ways. To retrieve all syntax items regardless of syntax group: > |
| echo OmniSyntaxList( [] ) |
| |
| To retrieve only the syntax items for the sqlOperator syntax group: > |
| echo OmniSyntaxList( ['sqlOperator'] ) |
| |
| To retrieve all syntax items for both the sqlOperator and sqlType groups: > |
| echo OmniSyntaxList( ['sqlOperator', 'sqlType'] ) |
| |
| From within a plugin, you would typically assign the output to a List: > |
| let myKeywords = [] |
| let myKeywords = OmniSyntaxList( ['sqlKeyword'] ) |
| |
| |
| |
| SQL *ft-sql-omni* |
| |
| Completion for the SQL language includes statements, functions, keywords. |
| It will also dynamically complete tables, procedures, views and column lists |
| with data pulled directly from within a database. For detailed instructions |
| and a tutorial see |omni-sql-completion|. |
| |
| The SQL completion plugin can be used in conjunction with other completion |
| plugins. For example, the PHP filetype has its own completion plugin. |
| Since PHP is often used to generate dynamic website by accessing a database, |
| the SQL completion plugin can also be enabled. This allows you to complete |
| PHP code and SQL code at the same time. |
| |
| |
| XML *ft-xml-omni* |
| |
| Vim 7 provides a mechanism for context aware completion of XML files. It |
| depends on a special |xml-omni-datafile| and two commands: |:XMLns| and |
| |:XMLent|. Features are: |
| |
| - after "<" complete the tag name, depending on context |
| - inside of a tag complete proper attributes |
| - when an attribute has a limited number of possible values help to complete |
| them |
| - complete names of entities (defined in |xml-omni-datafile| and in the |
| current file with "<!ENTITY" declarations) |
| - when used after "</" CTRL-X CTRL-O will close the last opened tag |
| |
| Format of XML data file *xml-omni-datafile* |
| |
| XML data files are stored in the "autoload/xml" directory in 'runtimepath'. |
| Vim distribution provides examples of data files in the |
| "$VIMRUNTIME/autoload/xml" directory. They have a meaningful name which will |
| be used in commands. It should be a unique name which will not create |
| conflicts. For example, the name xhtml10s.vim means it is the data file for |
| XHTML 1.0 Strict. |
| |
| Each file contains a variable with a name like g:xmldata_xhtml10s . It is |
| a compound from two parts: |
| |
| 1. "g:xmldata_" general prefix, constant for all data files |
| 2. "xhtml10s" the name of the file and the name of the described XML |
| dialect; it will be used as an argument for the |:XMLns| |
| command |
| |
| Part two must be exactly the same as name of file. |
| |
| The variable is a |Dictionary|. Keys are tag names and each value is a two |
| element |List|. The first element of the List is also a List with the names |
| of possible children. The second element is a |Dictionary| with the names of |
| attributes as keys and the possible values of attributes as values. Example: > |
| |
| let g:xmldata_crippled = { |
| \ "vimxmlentities": ["amp", "lt", "gt", "apos", "quot"], |
| \ 'vimxmlroot': ['tag1'], |
| \ 'tag1': |
| \ [ ['childoftag1a', 'childoftag1b'], {'attroftag1a': [], |
| \ 'attroftag1b': ['valueofattr1', 'valueofattr2']}], |
| \ 'childoftag1a': |
| \ [ [], {'attrofchild': ['attrofchild']}], |
| \ 'childoftag1b': |
| \ [ ['childoftag1a'], {'attrofchild': []}], |
| \ "vimxmltaginfo": { |
| \ 'tag1': ['Menu info', 'Long information visible in preview window']}, |
| \ 'vimxmlattrinfo': { |
| \ 'attrofchild': ['Menu info', 'Long information visible in preview window']}} |
| |
| This example would be put in the "autoload/xml/crippled.vim" file and could |
| help to write this file: > |
| |
| <tag1 attroftag1b="valueofattr1"> |
| <childoftag1a attrofchild> |
| & < |
| </childoftag1a> |
| <childoftag1b attrofchild="5"> |
| <childoftag1a> |
| > ' " |
| </childoftag1a> |
| </childoftag1b> |
| </tag1> |
| |
| In the example four special elements are visible: |
| |
| 1. "vimxmlentities" - a special key with List containing entities of this XML |
| dialect. |
| 2. If the list containing possible values of attributes has one element and |
| this element is equal to the name of the attribute this attribute will be |
| treated as boolean and inserted as 'attrname' and not as 'attrname="' |
| 3. "vimxmltaginfo" - a special key with a Dictionary containing tag |
| names as keys and two element List as values, for additional menu info and |
| the long description. |
| 4. "vimxmlattrinfo" - special key with Dictionary containing attribute names |
| as keys and two element List as values, for additional menu info and long |
| description. |
| |
| Note: Tag names in the data file MUST not contain a namespace description. |
| Check xsl.vim for an example. |
| Note: All data and functions are publicly available as global |
| variables/functions and can be used for personal editing functions. |
| |
| |
| DTD -> Vim *dtd2vim* |
| |
| On |www| is the script |dtd2vim| which parses DTD and creates an XML data file |
| for Vim XML omni completion. |
| |
| dtd2vim: http://www.vim.org/scripts/script.php?script_id=1462 |
| |
| Check the beginning of that file for usage details. |
| The script requires perl and: |
| |
| perlSGML: http://savannah.nongnu.org/projects/perlsgml |
| |
| |
| Commands |
| |
| :XMLns {name} [{namespace}] *:XMLns* |
| |
| Vim has to know which data file should be used and with which namespace. For |
| loading of the data file and connecting data with the proper namespace use |
| |:XMLns| command. The first (obligatory) argument is the name of the data |
| (xhtml10s, xsl). The second argument is the code of namespace (h, xsl). When |
| used without a second argument the dialect will be used as default - without |
| namespace declaration. For example to use XML completion in .xsl files: > |
| |
| :XMLns xhtml10s |
| :XMLns xsl xsl |
| |
| |
| :XMLent {name} *:XMLent* |
| |
| By default entities will be completed from the data file of the default |
| namespace. The XMLent command should be used in case when there is no default |
| namespace: > |
| |
| :XMLent xhtml10s |
| |
| Usage |
| |
| While used in this situation (after declarations from previous part, | is |
| cursor position): > |
| |
| <| |
| |
| Will complete to an appropriate XHTML tag, and in this situation: > |
| |
| <xsl:| |
| |
| Will complete to an appropriate XSL tag. |
| |
| |
| The script xmlcomplete.vim, provided through the |autoload| mechanism, |
| has the xmlcomplete#GetLastOpenTag() function which can be used in XML files |
| to get the name of the last open tag (b:unaryTagsStack has to be defined): > |
| |
| :echo xmlcomplete#GetLastOpenTag("b:unaryTagsStack") |
| |
| |
| |
| ============================================================================== |
| 8. Insert mode commands *inserting* |
| |
| The following commands can be used to insert new text into the buffer. They |
| can all be undone and repeated with the "." command. |
| |
| *a* |
| a Append text after the cursor [count] times. If the |
| cursor is in the first column of an empty line Insert |
| starts there. But not when 'virtualedit' is set! |
| |
| *A* |
| A Append text at the end of the line [count] times. |
| |
| <insert> or *i* *insert* *<Insert>* |
| i Insert text before the cursor [count] times. |
| When using CTRL-O in Insert mode |i_CTRL-O| the count |
| is not supported. |
| |
| *I* |
| I Insert text before the first non-blank in the line |
| [count] times. |
| When the 'H' flag is present in 'cpoptions' and the |
| line only contains blanks, insert start just before |
| the last blank. |
| |
| *gI* |
| gI Insert text in column 1 [count] times. {not in Vi} |
| |
| *gi* |
| gi Insert text in the same position as where Insert mode |
| was stopped last time in the current buffer. |
| This uses the |'^| mark. It's different from "`^i" |
| when the mark is past the end of the line. |
| The position is corrected for inserted/deleted lines, |
| but NOT for inserted/deleted characters. |
| When the |:keepjumps| command modifier is used the |'^| |
| mark won't be changed. |
| {not in Vi} |
| |
| *o* |
| o Begin a new line below the cursor and insert text, |
| repeat [count] times. {Vi: blank [count] screen |
| lines} |
| When the '#' flag is in 'cpoptions' the count is |
| ignored. |
| |
| *O* |
| O Begin a new line above the cursor and insert text, |
| repeat [count] times. {Vi: blank [count] screen |
| lines} |
| When the '#' flag is in 'cpoptions' the count is |
| ignored. |
| |
| These commands are used to start inserting text. You can end insert mode with |
| <Esc>. See |mode-ins-repl| for the other special characters in Insert mode. |
| The effect of [count] takes place after Insert mode is exited. |
| |
| When 'autoindent' is on, the indent for a new line is obtained from the |
| previous line. When 'smartindent' or 'cindent' is on, the indent for a line |
| is automatically adjusted for C programs. |
| |
| 'textwidth' can be set to the maximum width for a line. When a line becomes |
| too long when appending characters a line break is automatically inserted. |
| |
| |
| ============================================================================== |
| 9. Ex insert commands *inserting-ex* |
| |
| *:a* *:append* |
| :{range}a[ppend][!] Insert several lines of text below the specified |
| line. If the {range} is missing, the text will be |
| inserted after the current line. |
| Adding [!] toggles 'autoindent' for the time this |
| command is executed. |
| |
| *:i* *:in* *:insert* |
| :{range}i[nsert][!] Insert several lines of text above the specified |
| line. If the {range} is missing, the text will be |
| inserted before the current line. |
| Adding [!] toggles 'autoindent' for the time this |
| command is executed. |
| |
| These two commands will keep on asking for lines, until you type a line |
| containing only a ".". Watch out for lines starting with a backslash, see |
| |line-continuation|. |
| |
| When in Ex mode (see |-e|) a backslash at the end of the line can be used to |
| insert a NUL character. To be able to have a line ending in a backslash use |
| two backslashes. This means that the number of backslashes is halved, but |
| only at the end of the line. |
| |
| NOTE: These commands cannot be used with |:global| or |:vglobal|. |
| ":append" and ":insert" don't work properly in between ":if" and |
| ":endif", ":for" and ":endfor", ":while" and ":endwhile". |
| |
| *:start* *:startinsert* |
| :star[tinsert][!] Start Insert mode just after executing this command. |
| Works like typing "i" in Normal mode. When the ! is |
| included it works like "A", append to the line. |
| Otherwise insertion starts at the cursor position. |
| Note that when using this command in a function or |
| script, the insertion only starts after the function |
| or script is finished. |
| This command does not work from |:normal|. |
| {not in Vi} |
| {not available when compiled without the |+ex_extra| |
| feature} |
| |
| *:stopi* *:stopinsert* |
| :stopi[nsert] Stop Insert mode as soon as possible. Works like |
| typing <Esc> in Insert mode. |
| Can be used in an autocommand, example: > |
| :au BufEnter scratch stopinsert |
| < |
| *replacing-ex* *:startreplace* |
| :startr[eplace][!] Start Replace mode just after executing this command. |
| Works just like typing "R" in Normal mode. When the |
| ! is included it acts just like "$R" had been typed |
| (ie. begin replace mode at the end-of-line). Other- |
| wise replacement begins at the cursor position. |
| Note that when using this command in a function or |
| script that the replacement will only start after |
| the function or script is finished. |
| {not in Vi} |
| {not available when compiled without the |+ex_extra| |
| feature} |
| |
| *:startgreplace* |
| :startg[replace][!] Just like |:startreplace|, but use Virtual Replace |
| mode, like with |gR|. |
| {not in Vi} |
| {not available when compiled without the |+ex_extra| |
| feature} |
| |
| ============================================================================== |
| 10. Inserting a file *inserting-file* |
| |
| *:r* *:re* *:read* |
| :r[ead] [++opt] [name] |
| Insert the file [name] (default: current file) below |
| the cursor. |
| See |++opt| for the possible values of [++opt]. |
| |
| :{range}r[ead] [++opt] [name] |
| Insert the file [name] (default: current file) below |
| the specified line. |
| See |++opt| for the possible values of [++opt]. |
| |
| *:r!* *:read!* |
| :[range]r[ead] !{cmd} Execute {cmd} and insert its standard output below |
| the cursor or the specified line. A temporary file is |
| used to store the output of the command which is then |
| read into the buffer. 'shellredir' is used to save |
| the output of the command, which can be set to include |
| stderr or not. {cmd} is executed like with ":!{cmd}", |
| any '!' is replaced with the previous command |:!|. |
| |
| These commands insert the contents of a file, or the output of a command, |
| into the buffer. They can be undone. They cannot be repeated with the "." |
| command. They work on a line basis, insertion starts below the line in which |
| the cursor is, or below the specified line. To insert text above the first |
| line use the command ":0r {name}". |
| |
| After the ":read" command, the cursor is left on the first non-blank in the |
| first new line. Unless in Ex mode, then the cursor is left on the last new |
| line (sorry, this is Vi compatible). |
| |
| If a file name is given with ":r", it becomes the alternate file. This can be |
| used, for example, when you want to edit that file instead: ":e! #". This can |
| be switched off by removing the 'a' flag from the 'cpoptions' option. |
| |
| Of the [++opt] arguments one is specifically for ":read", the ++edit argument. |
| This is useful when the ":read" command is actually used to read a file into |
| the buffer as if editing that file. Use this command in an empty buffer: > |
| :read ++edit filename |
| The effect is that the 'fileformat', 'fileencoding', 'bomb', etc. options are |
| set to what has been detected for "filename". Note that a single empty line |
| remains, you may want to delete it. |
| |
| *file-read* |
| The 'fileformat' option sets the <EOL> style for a file: |
| 'fileformat' characters name ~ |
| "dos" <CR><NL> or <NL> DOS format |
| "unix" <NL> Unix format |
| "mac" <CR> Mac format |
| Previously 'textmode' was used. It is obsolete now. |
| |
| If 'fileformat' is "dos", a <CR> in front of an <NL> is ignored and a CTRL-Z |
| at the end of the file is ignored. |
| |
| If 'fileformat' is "mac", a <NL> in the file is internally represented by a |
| <CR>. This is to avoid confusion with a <NL> which is used to represent a |
| <NUL>. See |CR-used-for-NL|. |
| |
| If the 'fileformats' option is not empty Vim tries to recognize the type of |
| <EOL> (see |file-formats|). However, the 'fileformat' option will not be |
| changed, the detected format is only used while reading the file. |
| A similar thing happens with 'fileencodings'. |
| |
| On non-MS-DOS, Win32, and OS/2 systems the message "[dos format]" is shown if |
| a file is read in DOS format, to remind you that something unusual is done. |
| On Macintosh, MS-DOS, Win32, and OS/2 the message "[unix format]" is shown if |
| a file is read in Unix format. |
| On non-Macintosh systems, the message "[Mac format]" is shown if a file is |
| read in Mac format. |
| |
| An example on how to use ":r !": > |
| :r !uuencode binfile binfile |
| This command reads "binfile", uuencodes it and reads it into the current |
| buffer. Useful when you are editing e-mail and want to include a binary |
| file. |
| |
| *read-messages* |
| When reading a file Vim will display a message with information about the read |
| file. In the table is an explanation for some of the items. The others are |
| self explanatory. Using the long or the short version depends on the |
| 'shortmess' option. |
| |
| long short meaning ~ |
| [readonly] {RO} the file is write protected |
| [fifo/socket] using a stream |
| [fifo] using a fifo stream |
| [socket] using a socket stream |
| [CR missing] reading with "dos" 'fileformat' and a |
| NL without a preceding CR was found. |
| [NL found] reading with "mac" 'fileformat' and a |
| NL was found (could be "unix" format) |
| [long lines split] at least one line was split in two |
| [NOT converted] conversion from 'fileencoding' to |
| 'encoding' was desired but not |
| possible |
| [converted] conversion from 'fileencoding' to |
| 'encoding' done |
| [crypted] file was decrypted |
| [READ ERRORS] not all of the file could be read |
| |
| |
| vim:tw=78:ts=8:ft=help:norl: |