INSERT

*insert.txt*    For IdeaVIM version 0.12.0.  Last change: 2006 Nov 12


                  VIM REFERENCE MANUAL    by Rick Maddy


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

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.

                                                *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.
                                                *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.
                                                *i_CTRL-W*
CTRL-W          Delete the word before the cursor. 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.

                                                *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-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
                        '='     the expression register: you are prompted to
                                enter an expression (see |expression|)
                See |registers| about registers.

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

                                                *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_<Insert>*
<Insert>        Toggle between Insert and Replace mode.

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



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>*
<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>*
<MouseDown>     scroll three lines down                      *i_<MouseDown>*
<S-MouseDown>   scroll a full page down                      *i_<S-MouseDown>*
<MouseUp>       scroll three lines up                        *i_<MouseUp>*
<S-MouseUp>     scroll a full page up                        *i_<S-MouseUp>*
CTRL-O          execute one command, return to Insert mode   *i_CTRL-O*

The CTRL-O command sometimes has one side effect: If the cursor was beyond the
end of the line, it will be put on the last character in the line.
The shifted cursor keys are not available on all terminals.


3. 'textwidth' and 'wrapmargin' options                 *ins-textwidth*

This information does not apply to IdeaVIM.


4. 'expandtab', 'smarttab' and 'softtabstop' options    *ins-expandtab*

This information does not apply to IdeaVIM.


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.


6. Virtual Replace mode         *vreplace-mode* *Virtual-Replace-mode*



7. Insert mode completion                               *ins-completion*

This information does not apply to IdeaVIM.

Use IDEA's built in code completion while in Insert or Replace mode.


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.

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

                                                        *gI*
gI                      Insert text in column 1 [count] times.

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

                                                        *o*
o                       Begin a new line below the cursor and insert text,
                        repeat [count] times.

                                                        *O*
O                       Begin a new line above the cursor and insert text,
                        repeat [count] times.

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.



9. Ex insert commands                                   *inserting-ex*

This information does not apply to IdeaVIM.


10. Inserting a file                                    *inserting-file*