*insert.txt* For Vim version 8.1. Last change: 2019 Oct 20

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-[.

If Esc doesn't work and you are using a Mac, try CTRL-Esc.

Or disable Listening under Accessibility preferences.

*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.

*i_CTRL-A*

CTRL-A Insert previously inserted text.

*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.

*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.

*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 before the cursor in the current

line. If there are no newly entered characters and

'backspace' is not empty, delete all characters before the

cursor 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.

CTRL-N Find next keyword (see |i_CTRL-N|).

CTRL-P Find previous keyword (see |i_CTRL-P|).

CTRL-R {register} *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.

When append() or setline() is invoked the undo

sequence will be broken.

See |registers| about registers.

CTRL-R CTRL-R {register} *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 CTRL-R CTRL-O, see below.

The '.' register (last inserted text) is still inserted as

typed.

CTRL-R CTRL-O {register} *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>|. When the register is linewise this will

insert the text above the current line, like with `P`.

Does not replace characters!

The '.' register (last inserted text) is still inserted as

typed.

CTRL-R CTRL-P {register} *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.

*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).

*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).

*i_0_CTRL-D*

0 CTRL-D Delete all indent in the current line.

*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.

*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.

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|.

*i_CTRL-E*

CTRL-E Insert the character which is below the cursor.

*i_CTRL-Y*

CTRL-Y Insert the character which is above the cursor.

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.

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.

*i_CTRL-]*

CTRL-] Trigger abbreviation, without inserting a character.

*i_<Insert>*

<Insert> Toggle between Insert and Replace mode.

-----------------------------------------------------------------------

*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.

*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|.

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*

CTRL-G U don't break undo with next left/right cursor *i_CTRL-G_U*

movement, if the cursor stays within

same the line

-----------------------------------------------------------------------

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. Note that the

command following CTRL-\ CTRL-O can still move the cursor, it is not restored

to its original position.

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.

An example for using CTRL-G U: >

inoremap <Left> <C-G>U<Left>

inoremap <Right> <C-G>U<Right>

inoremap <expr> <Home> col('.') == match(getline('.'), '\S') + 1 ?

\ repeat('<C-G>U<Left>', col('.') - 1) :

\ (col('.') < match(getline('.'), '\S') ?

\ repeat('<C-G>U<Right>', match(getline('.'), '\S') + 0) :

\ repeat('<C-G>U<Left>', col('.') - 1 - match(getline('.'), '\S')))

inoremap <expr> <End> repeat('<C-G>U<Right>', col('$') - col('.'))

inoremap ( ()<C-G>U<Left>

This makes it possible to use the cursor keys in Insert mode, without breaking

the undo sequence and therefore using |.| (redo) will work as expected.

Also entering a text like (with the "(" mapping from above):

Lorem ipsum (dolor

will be repeatable by using |.| to the expected

Lorem ipsum (dolor)

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).

*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.

*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).

==============================================================================

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}

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).

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| |i_CTRL-P|

All these, except CTRL-N and CTRL-P, 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).

To get the current completion information, |complete_info()| can be used.

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&eacute;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 "&eacute" 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.