blob: 4ee1c79b86e8aca3e6926dfbd818653a28f41af6 [file] [log] [blame]
Bram Moolenaar166af9b2010-11-16 20:34:40 +01001*insert.txt* For Vim version 7.3. Last change: 2010 Nov 10
Bram Moolenaar071d4272004-06-13 20:20:40 +00002
3
4 VIM REFERENCE MANUAL by Bram Moolenaar
5
6
7 *Insert* *Insert-mode*
8Inserting and replacing text *mode-ins-repl*
9
10Most of this file is about Insert and Replace mode. At the end are a few
11commands for inserting text in other ways.
12
13An overview of the most often used commands can be found in chapter 24 of the
14user manual |usr_24.txt|.
15
161. Special keys |ins-special-keys|
172. Special special keys |ins-special-special|
183. 'textwidth' and 'wrapmargin' options |ins-textwidth|
194. 'expandtab', 'smarttab' and 'softtabstop' options |ins-expandtab|
205. Replace mode |Replace-mode|
216. Virtual Replace mode |Virtual-Replace-mode|
227. Insert mode completion |ins-completion|
238. Insert mode commands |inserting|
249. Ex insert commands |inserting-ex|
2510. Inserting a file |inserting-file|
26
27Also see 'virtualedit', for moving the cursor to positions where there is no
28character. Useful for editing a table.
29
30==============================================================================
311. Special keys *ins-special-keys*
32
33In Insert and Replace mode, the following characters have a special meaning;
34other characters are inserted directly. To insert one of these special
35characters into the buffer, precede it with CTRL-V. To insert a <Nul>
36character use "CTRL-V CTRL-@" or "CTRL-V 000". On some systems, you have to
37use "CTRL-V 003" to insert a CTRL-C. Note: When CTRL-V is mapped you can
38often use CTRL-Q instead |i_CTRL-Q|.
39
40If you are working in a special language mode when inserting text, see the
41'langmap' option, |'langmap'|, on how to avoid switching this mode on and off
42all the time.
43
44If you have 'insertmode' set, <Esc> and a few other keys get another meaning.
45See |'insertmode'|.
46
47char action ~
48-----------------------------------------------------------------------
49 *i_CTRL-[* *i_<Esc>*
50<Esc> or CTRL-[ End insert or Replace mode, go back to Normal mode. Finish
51 abbreviation.
52 Note: If your <Esc> key is hard to hit on your keyboard, train
53 yourself to use CTRL-[.
54 *i_CTRL-C*
55CTRL-C Quit insert mode, go back to Normal mode. Do not check for
Bram Moolenaar677ee682005-01-27 14:41:15 +000056 abbreviations. Does not trigger the |InsertLeave| autocommand
57 event.
Bram Moolenaar071d4272004-06-13 20:20:40 +000058
59 *i_CTRL-@*
60CTRL-@ Insert previously inserted text and stop insert. {Vi: only
61 when typed as first char, only up to 128 chars}
62 *i_CTRL-A*
63CTRL-A Insert previously inserted text. {not in Vi}
64
65 *i_CTRL-H* *i_<BS>* *i_BS*
66<BS> or CTRL-H Delete the character before the cursor (see |i_backspacing|
67 about joining lines).
68 See |:fixdel| if your <BS> key does not do what you want.
69 {Vi: does not delete autoindents}
70 *i_<Del>* *i_DEL*
71<Del> Delete the character under the cursor. If the cursor is at
72 the end of the line, and the 'backspace' option includes
73 "eol", delete the <EOL>; the next line is appended after the
74 current one.
75 See |:fixdel| if your <Del> key does not do what you want.
76 {not in Vi}
77 *i_CTRL-W*
78CTRL-W Delete the word before the cursor (see |i_backspacing| about
79 joining lines). See the section "word motions",
80 |word-motions|, for the definition of a word.
81 *i_CTRL-U*
82CTRL-U Delete all entered characters in the current line (see
83 |i_backspacing| about joining lines).
84
85 *i_CTRL-I* *i_<Tab>* *i_Tab*
86<Tab> or CTRL-I Insert a tab. If the 'expandtab' option is on, the
87 equivalent number of spaces is inserted (use CTRL-V <Tab> to
88 avoid the expansion; use CTRL-Q <Tab> if CTRL-V is mapped
89 |i_CTRL-Q|). See also the 'smarttab' option and
90 |ins-expandtab|.
91 *i_CTRL-J* *i_<NL>*
92<NL> or CTRL-J Begin new line.
93 *i_CTRL-M* *i_<CR>*
94<CR> or CTRL-M Begin new line.
95 *i_CTRL-K*
96CTRL-K {char1} [char2]
97 Enter digraph (see |digraphs|). When {char1} is a special
98 key, the code for that key is inserted in <> form. For
99 example, the string "<S-Space>" can be entered by typing
100 <C-K><S-Space> (two keys). Neither char is considered for
101 mapping. {not in Vi}
102
103CTRL-N Find next keyword (see |i_CTRL-N|). {not in Vi}
104CTRL-P Find previous keyword (see |i_CTRL-P|). {not in Vi}
105
106CTRL-R {0-9a-z"%#*+:.-=} *i_CTRL-R*
107 Insert the contents of a register. Between typing CTRL-R and
108 the second character, '"' will be displayed to indicate that
109 you are expected to enter the name of a register.
110 The text is inserted as if you typed it, but mappings and
111 abbreviations are not used. If you have options like
112 'textwidth', 'formatoptions', or 'autoindent' set, this will
113 influence what will be inserted. This is different from what
114 happens with the "p" command and pasting with the mouse.
115 Special registers:
116 '"' the unnamed register, containing the text of
117 the last delete or yank
118 '%' the current file name
119 '#' the alternate file name
120 '*' the clipboard contents (X11: primary selection)
121 '+' the clipboard contents
122 '/' the last search pattern
123 ':' the last command-line
124 '.' the last inserted text
125 '-' the last small (less than a line) delete
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100126 *i_CTRL-R_=*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000127 '=' the expression register: you are prompted to
128 enter an expression (see |expression|)
Bram Moolenaar293ee4d2004-12-09 21:34:53 +0000129 Note that 0x80 (128 decimal) is used for
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +0000130 special keys. E.g., you can use this to move
131 the cursor up:
132 CTRL-R ="\<Up>"
133 Use CTRL-R CTRL-R to insert text literally.
Bram Moolenaar362e1a32006-03-06 23:29:24 +0000134 When the result is a |List| the items are used
135 as lines. They can have line breaks inside
136 too.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100137 When the result is a Float it's automatically
138 converted to a String.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000139 See |registers| about registers. {not in Vi}
140
141CTRL-R CTRL-R {0-9a-z"%#*+/:.-=} *i_CTRL-R_CTRL-R*
142 Insert the contents of a register. Works like using a single
143 CTRL-R, but the text is inserted literally, not as if typed.
144 This differs when the register contains characters like <BS>.
145 Example, where register a contains "ab^Hc": >
146 CTRL-R a results in "ac".
147 CTRL-R CTRL-R a results in "ab^Hc".
148< Options 'textwidth', 'formatoptions', etc. still apply. If
149 you also want to avoid these, use "<C-R><C-O>r", see below.
150 The '.' register (last inserted text) is still inserted as
151 typed. {not in Vi}
152
153CTRL-R CTRL-O {0-9a-z"%#*+/:.-=} *i_CTRL-R_CTRL-O*
154 Insert the contents of a register literally and don't
155 auto-indent. Does the same as pasting with the mouse
156 |<MiddleMouse>|.
157 Does not replace characters!
158 The '.' register (last inserted text) is still inserted as
159 typed. {not in Vi}
160
161CTRL-R CTRL-P {0-9a-z"%#*+/:.-=} *i_CTRL-R_CTRL-P*
162 Insert the contents of a register literally and fix the
163 indent, like |[<MiddleMouse>|.
164 Does not replace characters!
165 The '.' register (last inserted text) is still inserted as
166 typed. {not in Vi}
167
168 *i_CTRL-T*
169CTRL-T Insert one shiftwidth of indent at the start of the current
170 line. The indent is always rounded to a 'shiftwidth' (this is
171 vi compatible). {Vi: only when in indent}
172 *i_CTRL-D*
173CTRL-D Delete one shiftwidth of indent at the start of the current
174 line. The indent is always rounded to a 'shiftwidth' (this is
175 vi compatible). {Vi: CTRL-D works only when used after
176 autoindent}
177 *i_0_CTRL-D*
1780 CTRL-D Delete all indent in the current line. {Vi: CTRL-D works
179 only when used after autoindent}
180 *i_^_CTRL-D*
181^ CTRL-D Delete all indent in the current line. The indent is
182 restored in the next line. This is useful when inserting a
183 label. {Vi: CTRL-D works only when used after autoindent}
184
185 *i_CTRL-V*
186CTRL-V Insert next non-digit literally. For special keys, the
187 terminal code is inserted. It's also possible to enter the
188 decimal, octal or hexadecimal value of a character
189 |i_CTRL-V_digit|.
190 The characters typed right after CTRL-V are not considered for
191 mapping. {Vi: no decimal byte entry}
192 Note: When CTRL-V is mapped (e.g., to paste text) you can
193 often use CTRL-Q instead |i_CTRL-Q|.
194
195 *i_CTRL-Q*
196CTRL-Q Same as CTRL-V.
197 Note: Some terminal connections may eat CTRL-Q, it doesn't
198 work then. It does work in the GUI.
199
200CTRL-X Enter CTRL-X mode. This is a sub-mode where commands can
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000201 be given to complete words or scroll the window. See
Bram Moolenaar071d4272004-06-13 20:20:40 +0000202 |i_CTRL-X| and |ins-completion|. {not in Vi}
203
204 *i_CTRL-E*
205CTRL-E Insert the character which is below the cursor. {not in Vi}
206 *i_CTRL-Y*
207CTRL-Y Insert the character which is above the cursor. {not in Vi}
208 Note that for CTRL-E and CTRL-Y 'textwidth' is not used, to be
209 able to copy characters from a long line.
210
211 *i_CTRL-_*
212CTRL-_ Switch between languages, as follows:
213 - When in a rightleft window, revins and nohkmap are toggled,
214 since English will likely be inserted in this case.
215 - When in a norightleft window, revins and hkmap are toggled,
216 since Hebrew will likely be inserted in this case.
217
218 CTRL-_ moves the cursor to the end of the typed text.
219
220 This command is only available when the 'allowrevins' option
221 is set.
222 Please refer to |rileft.txt| for more information about
223 right-to-left mode.
224 {not in Vi}
Bram Moolenaar9964e462007-05-05 17:54:07 +0000225 Only if compiled with the |+rightleft| feature.
226
Bram Moolenaar071d4272004-06-13 20:20:40 +0000227 *i_CTRL-^*
228CTRL-^ Toggle the use of typing language characters.
229 When language |:lmap| mappings are defined:
230 - If 'iminsert' is 1 (langmap mappings used) it becomes 0 (no
231 langmap mappings used).
232 - If 'iminsert' has another value it becomes 1, thus langmap
233 mappings are enabled.
234 When no language mappings are defined:
235 - If 'iminsert' is 2 (Input Method used) it becomes 0 (no
236 Input Method used).
237 - If 'iminsert' has another value it becomes 2, thus the Input
238 Method is enabled.
239 When set to 1, the value of the "b:keymap_name" variable, the
240 'keymap' option or "<lang>" appears in the status line.
241 The language mappings are normally used to type characters
242 that are different from what the keyboard produces. The
243 'keymap' option can be used to install a whole number of them.
244 {not in Vi}
245
246 *i_CTRL-]*
247CTRL-] Trigger abbreviation, without inserting a character. {not in
248 Vi}
249
250 *i_<Insert>*
251<Insert> Toggle between Insert and Replace mode. {not in Vi}
252-----------------------------------------------------------------------
253
254 *i_backspacing*
255The effect of the <BS>, CTRL-W, and CTRL-U depend on the 'backspace' option
256(unless 'revins' is set). This is a comma separated list of items:
257
258item action ~
259indent allow backspacing over autoindent
260eol allow backspacing over end-of-line (join lines)
261start allow backspacing over the start position of insert; CTRL-W and
262 CTRL-U stop once at the start position
263
264When 'backspace' is empty, Vi compatible backspacing is used. You cannot
265backspace over autoindent, before column 1 or before where insert started.
266
267For backwards compatibility the values "0", "1" and "2" are also allowed, see
268|'backspace'|.
269
270If the 'backspace' option does contain "eol" and the cursor is in column 1
271when one of the three keys is used, the current line is joined with the
272previous line. This effectively deletes the <EOL> in front of the cursor.
273{Vi: does not cross lines, does not delete past start position of insert}
274
275 *i_CTRL-V_digit*
276With CTRL-V the decimal, octal or hexadecimal value of a character can be
277entered directly. This way you can enter any character, except a line break
278(<NL>, value 10). There are five ways to enter the character value:
279
280first char mode max nr of chars max value ~
281(none) decimal 3 255
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000282o or O octal 3 377 (255)
Bram Moolenaar071d4272004-06-13 20:20:40 +0000283x or X hexadecimal 2 ff (255)
284u hexadecimal 4 ffff (65535)
285U hexadecimal 8 7fffffff (2147483647)
286
287Normally you would type the maximum number of characters. Thus to enter a
288space (value 32) you would type <C-V>032. You can omit the leading zero, in
289which case the character typed after the number must be a non-digit. This
290happens for the other modes as well: As soon as you type a character that is
291invalid for the mode, the value before it will be used and the "invalid"
292character is dealt with in the normal way.
293
294If you enter a value of 10, it will end up in the file as a 0. The 10 is a
295<NL>, which is used internally to represent the <Nul> character. When writing
296the buffer to a file, the <NL> character is translated into <Nul>. The <NL>
297character is written at the end of each line. Thus if you want to insert a
298<NL> character in a file you will have to make a line break.
299
300 *i_CTRL-X* *insert_expand*
301CTRL-X enters a sub-mode where several commands can be used. Most of these
302commands do keyword completion; see |ins-completion|. These are not available
303when Vim was compiled without the |+insert_expand| feature.
304
305Two commands can be used to scroll the window up or down, without exiting
306insert mode:
307
308 *i_CTRL-X_CTRL-E*
309CTRL-X CTRL-E scroll window one line up.
Bram Moolenaard2cec5b2006-03-28 21:08:56 +0000310 When doing completion look here: |complete_CTRL-E|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000311
312 *i_CTRL-X_CTRL-Y*
313CTRL-X CTRL-Y scroll window one line down.
Bram Moolenaard2cec5b2006-03-28 21:08:56 +0000314 When doing completion look here: |complete_CTRL-Y|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000315
316After CTRL-X is pressed, each CTRL-E (CTRL-Y) scrolls the window up (down) by
317one line unless that would cause the cursor to move from its current position
318in the file. As soon as another key is pressed, CTRL-X mode is exited and
319that key is interpreted as in Insert mode.
320
321
322==============================================================================
3232. Special special keys *ins-special-special*
324
325The following keys are special. They stop the current insert, do something,
326and then restart insertion. This means you can do something without getting
327out of Insert mode. This is very handy if you prefer to use the Insert mode
328all the time, just like editors that don't have a separate Normal mode. You
329may also want to set the 'backspace' option to "indent,eol,start" and set the
330'insertmode' option. You can use CTRL-O if you want to map a function key to
331a command.
332
333The changes (inserted or deleted characters) before and after these keys can
334be undone separately. Only the last change can be redone and always behaves
335like an "i" command.
336
337char action ~
338-----------------------------------------------------------------------
339<Up> cursor one line up *i_<Up>*
340<Down> cursor one line down *i_<Down>*
341CTRL-G <Up> cursor one line up, insert start column *i_CTRL-G_<Up>*
342CTRL-G k cursor one line up, insert start column *i_CTRL-G_k*
343CTRL-G CTRL-K cursor one line up, insert start column *i_CTRL-G_CTRL-K*
344CTRL-G <Down> cursor one line down, insert start column *i_CTRL-G_<Down>*
345CTRL-G j cursor one line down, insert start column *i_CTRL-G_j*
346CTRL-G CTRL-J cursor one line down, insert start column *i_CTRL-G_CTRL-J*
347<Left> cursor one character left *i_<Left>*
348<Right> cursor one character right *i_<Right>*
349<S-Left> cursor one word back (like "b" command) *i_<S-Left>*
350<C-Left> cursor one word back (like "b" command) *i_<C-Left>*
351<S-Right> cursor one word forward (like "w" command) *i_<S-Right>*
352<C-Right> cursor one word forward (like "w" command) *i_<C-Right>*
353<Home> cursor to first char in the line *i_<Home>*
354<End> cursor to after last char in the line *i_<End>*
355<C-Home> cursor to first char in the file *i_<C-Home>*
356<C-End> cursor to after last char in the file *i_<C-End>*
357<LeftMouse> cursor to position of mouse click *i_<LeftMouse>*
358<S-Up> move window one page up *i_<S-Up>*
359<PageUp> move window one page up *i_<PageUp>*
360<S-Down> move window one page down *i_<S-Down>*
361<PageDown> move window one page down *i_<PageDown>*
Bram Moolenaar8d9b40e2010-07-25 15:49:07 +0200362<ScrollWheelDown> move window three lines down *i_<ScrollWheelDown>*
363<S-ScrollWheelDown> move window one page down *i_<S-ScrollWheelDown>*
364<ScrollWheelUp> move window three lines up *i_<ScrollWheelUp>*
365<S-ScrollWheelUp> move window one page up *i_<S-ScrollWheelUp>*
366<ScrollWheelLeft> move window six columns left *i_<ScrollWheelLeft>*
367<S-ScrollWheelLeft> move window one page left *i_<S-ScrollWheelLeft>*
368<ScrollWheelRight> move window six columns right *i_<ScrollWheelRight>*
369<S-ScrollWheelRight> move window one page right *i_<S-ScrollWheelRight>*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000370CTRL-O execute one command, return to Insert mode *i_CTRL-O*
Bram Moolenaar4770d092006-01-12 23:22:24 +0000371CTRL-\ CTRL-O like CTRL-O but don't move the cursor *i_CTRL-\_CTRL-O*
Bram Moolenaar488c6512005-08-11 20:09:58 +0000372CTRL-L when 'insertmode' is set: go to Normal mode *i_CTRL-L*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000373CTRL-G u break undo sequence, start new change *i_CTRL-G_u*
374-----------------------------------------------------------------------
375
376Note: If the cursor keys take you out of Insert mode, check the 'noesckeys'
377option.
378
379The CTRL-O command sometimes has a side effect: If the cursor was beyond the
380end of the line, it will be put on the last character in the line. In
381mappings it's often better to use <Esc> (first put an "x" in the text, <Esc>
Bram Moolenaar488c6512005-08-11 20:09:58 +0000382will then always put the cursor on it). Or use CTRL-\ CTRL-O, but then
383beware of the cursor possibly being beyond the end of the line.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000384
Bram Moolenaar05365702010-10-27 18:34:44 +0200385The CTRL-O command takes you to Normal mode. If you then use a command enter
386Insert mode again it doesn't nest. Thus when typing "a<C-O>a" and then <Esc>
387takes you back to Normal mode, you do not need to type <Esc> twice.
388
Bram Moolenaar071d4272004-06-13 20:20:40 +0000389The shifted cursor keys are not available on all terminals.
390
391Another side effect is that a count specified before the "i" or "a" command is
392ignored. That is because repeating the effect of the command after CTRL-O is
393too complicated.
394
395An example for using CTRL-G u: >
396
397 :inoremap <C-H> <C-G>u<C-H>
398
399This redefines the backspace key to start a new undo sequence. You can now
400undo the effect of the backspace key, without changing what you typed before
401that, with CTRL-O u.
402
Bram Moolenaarf4b8e572004-06-24 15:53:16 +0000403Using CTRL-O splits undo: the text typed before and after it is undone
404separately. If you want to avoid this (e.g., in a mapping) you might be able
405to use CTRL-R = |i_CTRL-R|. E.g., to call a function: >
406 :imap <F2> <C-R>=MyFunc()<CR>
407
Bram Moolenaar071d4272004-06-13 20:20:40 +0000408When the 'whichwrap' option is set appropriately, the <Left> and <Right>
409keys on the first/last character in the line make the cursor wrap to the
410previous/next line.
411
412The CTRL-G j and CTRL-G k commands can be used to insert text in front of a
413column. Example: >
414 int i;
415 int j;
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000416Position the cursor on the first "int", type "istatic <C-G>j ". The
Bram Moolenaar071d4272004-06-13 20:20:40 +0000417result is: >
418 static int i;
419 int j;
420When inserting the same text in front of the column in every line, use the
421Visual blockwise command "I" |v_b_I|.
422
423==============================================================================
4243. 'textwidth' and 'wrapmargin' options *ins-textwidth*
425
426The 'textwidth' option can be used to automatically break a line before it
427gets too long. Set the 'textwidth' option to the desired maximum line
428length. If you then type more characters (not spaces or tabs), the
429last word will be put on a new line (unless it is the only word on the
430line). If you set 'textwidth' to 0, this feature is disabled.
431
432The 'wrapmargin' option does almost the same. The difference is that
433'textwidth' has a fixed width while 'wrapmargin' depends on the width of the
434screen. When using 'wrapmargin' this is equal to using 'textwidth' with a
435value equal to (columns - 'wrapmargin'), where columns is the width of the
436screen.
437
438When 'textwidth' and 'wrapmargin' are both set, 'textwidth' is used.
439
440If you don't really want to break the line, but view the line wrapped at a
441convenient place, see the 'linebreak' option.
442
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +0000443The line is only broken automatically when using Insert mode, or when
Bram Moolenaar071d4272004-06-13 20:20:40 +0000444appending to a line. When in replace mode and the line length is not
445changed, the line will not be broken.
446
447Long lines are broken if you enter a non-white character after the margin.
448The situations where a line will be broken can be restricted by adding
449characters to the 'formatoptions' option:
450"l" Only break a line if it was not longer than 'textwidth' when the insert
451 started.
452"v" Only break at a white character that has been entered during the
453 current insert command. This is mostly Vi-compatible.
454"lv" Only break if the line was not longer than 'textwidth' when the insert
455 started and only at a white character that has been entered during the
456 current insert command. Only differs from "l" when entering non-white
457 characters while crossing the 'textwidth' boundary.
458
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +0000459Normally an internal function will be used to decide where to break the line.
460If you want to do it in a different way set the 'formatexpr' option to an
461expression that will take care of the line break.
462
Bram Moolenaar071d4272004-06-13 20:20:40 +0000463If you want to format a block of text, you can use the "gq" operator. Type
464"gq" and a movement command to move the cursor to the end of the block. In
465many cases, the command "gq}" will do what you want (format until the end of
466paragraph). Alternatively, you can use "gqap", which will format the whole
467paragraph, no matter where the cursor currently is. Or you can use Visual
468mode: hit "v", move to the end of the block, and type "gq". See also |gq|.
469
470==============================================================================
4714. 'expandtab', 'smarttab' and 'softtabstop' options *ins-expandtab*
472
473If the 'expandtab' option is on, spaces will be used to fill the amount of
474whitespace of the tab. If you want to enter a real <Tab>, type CTRL-V first
475(use CTRL-Q when CTRL-V is mapped |i_CTRL-Q|).
476The 'expandtab' option is off by default. Note that in Replace mode, a single
477character is replaced with several spaces. The result of this is that the
478number of characters in the line increases. Backspacing will delete one
479space at a time. The original character will be put back for only one space
480that you backspace over (the last one). {Vi does not have the 'expandtab'
481option}
482
483 *ins-smarttab*
484When the 'smarttab' option is on, a <Tab> inserts 'shiftwidth' positions at
485the beginning of a line and 'tabstop' positions in other places. This means
486that often spaces instead of a <Tab> character are inserted. When 'smarttab
487is off, a <Tab> always inserts 'tabstop' positions, and 'shiftwidth' is only
488used for ">>" and the like. {not in Vi}
489
490 *ins-softtabstop*
491When the 'softtabstop' option is non-zero, a <Tab> inserts 'softtabstop'
492positions, and a <BS> used to delete white space, will delete 'softtabstop'
493positions. This feels like 'tabstop' was set to 'softtabstop', but a real
494<Tab> character still takes 'tabstop' positions, so your file will still look
495correct when used by other applications.
496
497If 'softtabstop' is non-zero, a <BS> will try to delete as much white space to
498move to the previous 'softtabstop' position, except when the previously
499inserted character is a space, then it will only delete the character before
500the cursor. Otherwise you cannot always delete a single character before the
501cursor. You will have to delete 'softtabstop' characters first, and then type
502extra spaces to get where you want to be.
503
504==============================================================================
5055. Replace mode *Replace* *Replace-mode* *mode-replace*
506
507Enter Replace mode with the "R" command in normal mode.
508
509In Replace mode, one character in the line is deleted for every character you
510type. If there is no character to delete (at the end of the line), the
511typed character is appended (as in Insert mode). Thus the number of
512characters in a line stays the same until you get to the end of the line.
513If a <NL> is typed, a line break is inserted and no character is deleted.
514
515Be careful with <Tab> characters. If you type a normal printing character in
516its place, the number of characters is still the same, but the number of
517columns will become smaller.
518
519If you delete characters in Replace mode (with <BS>, CTRL-W, or CTRL-U), what
520happens is that you delete the changes. The characters that were replaced
521are restored. If you had typed past the existing text, the characters you
522added are deleted. This is effectively a character-at-a-time undo.
523
524If the 'expandtab' option is on, a <Tab> will replace one character with
525several spaces. The result of this is that the number of characters in the
526line increases. Backspacing will delete one space at a time. The original
527character will be put back for only one space that you backspace over (the
528last one). {Vi does not have the 'expandtab' option}
529
530==============================================================================
5316. Virtual Replace mode *vreplace-mode* *Virtual-Replace-mode*
532
533Enter Virtual Replace mode with the "gR" command in normal mode.
Bram Moolenaardb84e452010-08-15 13:50:43 +0200534{not available when compiled without the |+vreplace| feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +0000535{Vi does not have Virtual Replace mode}
536
537Virtual Replace mode is similar to Replace mode, but instead of replacing
538actual characters in the file, you are replacing screen real estate, so that
539characters further on in the file never appear to move.
540
541So if you type a <Tab> it may replace several normal characters, and if you
542type a letter on top of a <Tab> it may not replace anything at all, since the
543<Tab> will still line up to the same place as before.
544
545Typing a <NL> still doesn't cause characters later in the file to appear to
546move. The rest of the current line will be replaced by the <NL> (that is,
547they are deleted), and replacing continues on the next line. A new line is
548NOT inserted unless you go past the end of the file.
549
550Interesting effects are seen when using CTRL-T and CTRL-D. The characters
551before the cursor are shifted sideways as normal, but characters later in the
552line still remain still. CTRL-T will hide some of the old line under the
553shifted characters, but CTRL-D will reveal them again.
554
555As with Replace mode, using <BS> etc will bring back the characters that were
556replaced. This still works in conjunction with 'smartindent', CTRL-T and
557CTRL-D, 'expandtab', 'smarttab', 'softtabstop', etc.
558
559In 'list' mode, Virtual Replace mode acts as if it was not in 'list' mode,
560unless "L" is in 'cpoptions'.
561
Bram Moolenaar24ea3ba2010-09-19 19:01:21 +0200562Note that the only situations for which characters beyond the cursor should
563appear to move are in List mode |'list'|, and occasionally when 'wrap' is set
564(and the line changes length to become shorter or wider than the width of the
565screen). In other cases spaces may be inserted to avoid following characters
566to move.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000567
568This mode is very useful for editing <Tab> separated columns in tables, for
569entering new data while keeping all the columns aligned.
570
571==============================================================================
5727. Insert mode completion *ins-completion*
573
Bram Moolenaar4be06f92005-07-29 22:36:03 +0000574In Insert and Replace mode, there are several commands to complete part of a
Bram Moolenaar071d4272004-06-13 20:20:40 +0000575keyword or line that has been typed. This is useful if you are using
576complicated keywords (e.g., function names with capitals and underscores).
577
578These commands are not available when the |+insert_expand| feature was
579disabled at compile time.
580
581Completion can be done for:
582
5831. Whole lines |i_CTRL-X_CTRL-L|
5842. keywords in the current file |i_CTRL-X_CTRL-N|
5853. keywords in 'dictionary' |i_CTRL-X_CTRL-K|
5864. keywords in 'thesaurus', thesaurus-style |i_CTRL-X_CTRL-T|
5875. keywords in the current and included files |i_CTRL-X_CTRL-I|
5886. tags |i_CTRL-X_CTRL-]|
5897. file names |i_CTRL-X_CTRL-F|
5908. definitions or macros |i_CTRL-X_CTRL-D|
5919. Vim command-line |i_CTRL-X_CTRL-V|
Bram Moolenaar4be06f92005-07-29 22:36:03 +000059210. User defined completion |i_CTRL-X_CTRL-U|
Bram Moolenaarf75a9632005-09-13 21:20:47 +000059311. omni completion |i_CTRL-X_CTRL-O|
Bram Moolenaar488c6512005-08-11 20:09:58 +000059412. Spelling suggestions |i_CTRL-X_s|
59513. keywords in 'complete' |i_CTRL-N|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000596
597All these (except 2) are done in CTRL-X mode. This is a sub-mode of Insert
598and Replace modes. You enter CTRL-X mode by typing CTRL-X and one of the
599CTRL-X commands. You exit CTRL-X mode by typing a key that is not a valid
600CTRL-X mode command. Valid keys are the CTRL-X command itself, CTRL-N (next),
601and CTRL-P (previous).
602
603Also see the 'infercase' option if you want to adjust the case of the match.
604
Bram Moolenaard2cec5b2006-03-28 21:08:56 +0000605 *complete_CTRL-E*
606When completion is active you can use CTRL-E to stop it and go back to the
Bram Moolenaar551dbcc2006-04-25 22:13:59 +0000607originally typed text. The CTRL-E will not be inserted.
Bram Moolenaard2cec5b2006-03-28 21:08:56 +0000608
609 *complete_CTRL-Y*
610When the popup menu is displayed you can use CTRL-Y to stop completion and
611accept the currently selected entry. The CTRL-Y is not inserted. Typing a
612space, Enter, or some other unprintable character will leave completion mode
613and insert that typed character.
614
Bram Moolenaar9e54a0e2006-04-14 20:42:25 +0000615When the popup menu is displayed there are a few more special keys, see
616|popupmenu-keys|.
617
Bram Moolenaar071d4272004-06-13 20:20:40 +0000618Note: The keys that are valid in CTRL-X mode are not mapped. This allows for
619":map ^F ^X^F" to work (where ^F is CTRL-F and ^X is CTRL-X). The key that
620ends CTRL-X mode (any key that is not a valid CTRL-X mode command) is mapped.
621Also, when doing completion with 'complete' mappings apply as usual.
622
Bram Moolenaarf193fff2006-04-27 00:02:13 +0000623Note: While completion is active Insert mode can't be used recursively.
624Mappings that somehow invoke ":normal i.." will generate an E523 error.
625
Bram Moolenaar071d4272004-06-13 20:20:40 +0000626The following mappings are suggested to make typing the completion commands
627a bit easier (although they will hide other commands): >
628 :inoremap ^] ^X^]
629 :inoremap ^F ^X^F
630 :inoremap ^D ^X^D
631 :inoremap ^L ^X^L
632
633As a special case, typing CTRL-R to perform register insertion (see
634|i_CTRL-R|) will not exit CTRL-X mode. This is primarily to allow the use of
635the '=' register to call some function to determine the next operation. If
636the contents of the register (or result of the '=' register evaluation) are
637not valid CTRL-X mode keys, then CTRL-X mode will be exited as if those keys
638had been typed.
639
640For example, the following will map <Tab> to either actually insert a <Tab> if
641the current line is currently only whitespace, or start/continue a CTRL-N
642completion operation: >
643
644 function! CleverTab()
645 if strpart( getline('.'), 0, col('.')-1 ) =~ '^\s*$'
646 return "\<Tab>"
647 else
648 return "\<C-N>"
Bram Moolenaarb52073a2010-03-17 20:02:06 +0100649 endif
Bram Moolenaar071d4272004-06-13 20:20:40 +0000650 endfunction
651 inoremap <Tab> <C-R>=CleverTab()<CR>
652
653
654
655Completing whole lines *compl-whole-line*
656
657 *i_CTRL-X_CTRL-L*
658CTRL-X CTRL-L Search backwards for a line that starts with the
Bram Moolenaar83bab712005-08-01 21:58:57 +0000659 same characters as those in the current line before
660 the cursor. Indent is ignored. The matching line is
Bram Moolenaar071d4272004-06-13 20:20:40 +0000661 inserted in front of the cursor.
Bram Moolenaar83bab712005-08-01 21:58:57 +0000662 The 'complete' option is used to decide which buffers
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +0000663 are searched for a match. Both loaded and unloaded
664 buffers are used.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000665 CTRL-L or
666 CTRL-P Search backwards for next matching line. This line
667 replaces the previous matching line.
668
669 CTRL-N Search forward for next matching line. This line
670 replaces the previous matching line.
671
672 CTRL-X CTRL-L After expanding a line you can additionally get the
673 line next to it by typing CTRL-X CTRL-L again, unless
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100674 a double CTRL-X is used. Only works for loaded
675 buffers.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000676
677Completing keywords in current file *compl-current*
678
679 *i_CTRL-X_CTRL-P*
680 *i_CTRL-X_CTRL-N*
681CTRL-X CTRL-N Search forwards for words that start with the keyword
682 in front of the cursor. The found keyword is inserted
683 in front of the cursor.
684
685CTRL-X CTRL-P Search backwards for words that start with the keyword
686 in front of the cursor. The found keyword is inserted
687 in front of the cursor.
688
689 CTRL-N Search forward for next matching keyword. This
690 keyword replaces the previous matching keyword.
691
692 CTRL-P Search backwards for next matching keyword. This
693 keyword replaces the previous matching keyword.
694
695 CTRL-X CTRL-N or
696 CTRL-X CTRL-P Further use of CTRL-X CTRL-N or CTRL-X CTRL-P will
697 copy the words following the previous expansion in
698 other contexts unless a double CTRL-X is used.
699
700If there is a keyword in front of the cursor (a name made out of alphabetic
701characters and characters in 'iskeyword'), it is used as the search pattern,
702with "\<" prepended (meaning: start of a word). Otherwise "\<\k\k" is used
703as search pattern (start of any keyword of at least two characters).
704
705In Replace mode, the number of characters that are replaced depends on the
706length of the matched string. This works like typing the characters of the
707matched string in Replace mode.
708
709If there is not a valid keyword character before the cursor, any keyword of
710at least two characters is matched.
711 e.g., to get:
712 printf("(%g, %g, %g)", vector[0], vector[1], vector[2]);
713 just type:
714 printf("(%g, %g, %g)", vector[0], ^P[1], ^P[2]);
715
Bram Moolenaarf75a9632005-09-13 21:20:47 +0000716The search wraps around the end of the file, the value of 'wrapscan' is not
717used here.
718
Bram Moolenaar071d4272004-06-13 20:20:40 +0000719Multiple repeats of the same completion are skipped; thus a different match
720will be inserted at each CTRL-N and CTRL-P (unless there is only one
721matching keyword).
722
723Single character matches are never included, as they usually just get in
724the way of what you were really after.
725 e.g., to get:
726 printf("name = %s\n", name);
727 just type:
728 printf("name = %s\n", n^P);
729 or even:
730 printf("name = %s\n", ^P);
731The 'n' in '\n' is skipped.
732
733After expanding a word, you can use CTRL-X CTRL-P or CTRL-X CTRL-N to get the
734word following the expansion in other contexts. These sequences search for
735the text just expanded and further expand by getting an extra word. This is
736useful if you need to repeat a sequence of complicated words. Although CTRL-P
737and CTRL-N look just for strings of at least two characters, CTRL-X CTRL-P and
738CTRL-X CTRL-N can be used to expand words of just one character.
739 e.g., to get:
740 M&eacute;xico
741 you can type:
742 M^N^P^X^P^X^P
743CTRL-N starts the expansion and then CTRL-P takes back the single character
744"M", the next two CTRL-X CTRL-P's get the words "&eacute" and ";xico".
745
746If the previous expansion was split, because it got longer than 'textwidth',
747then just the text in the current line will be used.
748
749If the match found is at the end of a line, then the first word in the next
750line will be inserted and the message "word from next line" displayed, if
751this word is accepted the next CTRL-X CTRL-P or CTRL-X CTRL-N will search
752for those lines starting with this word.
753
754
755Completing keywords in 'dictionary' *compl-dictionary*
756
757 *i_CTRL-X_CTRL-K*
758CTRL-X CTRL-K Search the files given with the 'dictionary' option
759 for words that start with the keyword in front of the
760 cursor. This is like CTRL-N, but only the dictionary
761 files are searched, not the current file. The found
762 keyword is inserted in front of the cursor. This
763 could potentially be pretty slow, since all matches
764 are found before the first match is used. By default,
765 the 'dictionary' option is empty.
766 For suggestions where to find a list of words, see the
767 'dictionary' option.
768
769 CTRL-K or
770 CTRL-N Search forward for next matching keyword. This
771 keyword replaces the previous matching keyword.
772
773 CTRL-P Search backwards for next matching keyword. This
774 keyword replaces the previous matching keyword.
775
776 *i_CTRL-X_CTRL-T*
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000777CTRL-X CTRL-T Works as CTRL-X CTRL-K, but in a special way. It uses
Bram Moolenaar071d4272004-06-13 20:20:40 +0000778 the 'thesaurus' option instead of 'dictionary'. If a
779 match is found in the thesaurus file, all the
780 remaining words on the same line are included as
781 matches, even though they don't complete the word.
782 Thus a word can be completely replaced.
783
784 For an example, imagine the 'thesaurus' file has a
785 line like this: >
786 angry furious mad enraged
787< Placing the cursor after the letters "ang" and typing
788 CTRL-X CTRL-T would complete the word "angry";
789 subsequent presses would change the word to "furious",
790 "mad" etc.
791 Other uses include translation between two languages,
792 or grouping API functions by keyword.
793
794 CTRL-T or
795 CTRL-N Search forward for next matching keyword. This
796 keyword replaces the previous matching keyword.
797
798 CTRL-P Search backwards for next matching keyword. This
799 keyword replaces the previous matching keyword.
800
801
802Completing keywords in the current and included files *compl-keyword*
803
804The 'include' option is used to specify a line that contains an include file
805name. The 'path' option is used to search for include files.
806
807 *i_CTRL-X_CTRL-I*
808CTRL-X CTRL-I Search for the first keyword in the current and
809 included files that starts with the same characters
810 as those before the cursor. The matched keyword is
811 inserted in front of the cursor.
812
813 CTRL-N Search forwards for next matching keyword. This
814 keyword replaces the previous matching keyword.
815 Note: CTRL-I is the same as <Tab>, which is likely to
816 be typed after a successful completion, therefore
817 CTRL-I is not used for searching for the next match.
818
819 CTRL-P Search backward for previous matching keyword. This
820 keyword replaces the previous matching keyword.
821
822 CTRL-X CTRL-I Further use of CTRL-X CTRL-I will copy the words
823 following the previous expansion in other contexts
824 unless a double CTRL-X is used.
825
826Completing tags *compl-tag*
827 *i_CTRL-X_CTRL-]*
828CTRL-X CTRL-] Search for the first tag that starts with the same
829 characters as before the cursor. The matching tag is
830 inserted in front of the cursor. Alphabetic
831 characters and characters in 'iskeyword' are used
832 to decide which characters are included in the tag
833 name (same as for a keyword). See also |CTRL-]|.
834 The 'showfulltag' option can be used to add context
835 from around the tag definition.
836 CTRL-] or
837 CTRL-N Search forwards for next matching tag. This tag
838 replaces the previous matching tag.
839
840 CTRL-P Search backward for previous matching tag. This tag
841 replaces the previous matching tag.
842
843
844Completing file names *compl-filename*
845 *i_CTRL-X_CTRL-F*
846CTRL-X CTRL-F Search for the first file name that starts with the
847 same characters as before the cursor. The matching
848 file name is inserted in front of the cursor.
849 Alphabetic characters and characters in 'isfname'
850 are used to decide which characters are included in
851 the file name. Note: the 'path' option is not used
852 here (yet).
853 CTRL-F or
854 CTRL-N Search forwards for next matching file name. This
855 file name replaces the previous matching file name.
856
857 CTRL-P Search backward for previous matching file name.
858 This file name replaces the previous matching file
859 name.
860
861
862Completing definitions or macros *compl-define*
863
864The 'define' option is used to specify a line that contains a definition.
865The 'include' option is used to specify a line that contains an include file
866name. The 'path' option is used to search for include files.
867
868 *i_CTRL-X_CTRL-D*
869CTRL-X CTRL-D Search in the current and included files for the
870 first definition (or macro) name that starts with
871 the same characters as before the cursor. The found
872 definition name is inserted in front of the cursor.
873 CTRL-D or
874 CTRL-N Search forwards for next matching macro name. This
875 macro name replaces the previous matching macro
876 name.
877
878 CTRL-P Search backward for previous matching macro name.
879 This macro name replaces the previous matching macro
880 name.
881
882 CTRL-X CTRL-D Further use of CTRL-X CTRL-D will copy the words
883 following the previous expansion in other contexts
884 unless a double CTRL-X is used.
885
886
887Completing Vim commands *compl-vim*
888
889Completion is context-sensitive. It works like on the Command-line. It
Bram Moolenaar4be06f92005-07-29 22:36:03 +0000890completes an Ex command as well as its arguments. This is useful when writing
891a Vim script.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000892
893 *i_CTRL-X_CTRL-V*
894CTRL-X CTRL-V Guess what kind of item is in front of the cursor and
895 find the first match for it.
896 Note: When CTRL-V is mapped you can often use CTRL-Q
Bram Moolenaar3577c6f2008-06-24 21:16:56 +0000897 instead of |i_CTRL-Q|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000898 CTRL-V or
899 CTRL-N Search forwards for next match. This match replaces
900 the previous one.
901
Bram Moolenaar3577c6f2008-06-24 21:16:56 +0000902 CTRL-P Search backwards for previous match. This match
Bram Moolenaar071d4272004-06-13 20:20:40 +0000903 replaces the previous one.
904
905 CTRL-X CTRL-V Further use of CTRL-X CTRL-V will do the same as
906 CTRL-V. This allows mapping a key to do Vim command
907 completion, for example: >
908 :imap <Tab> <C-X><C-V>
909
Bram Moolenaar4be06f92005-07-29 22:36:03 +0000910User defined completion *compl-function*
Bram Moolenaarcfbc5ee2004-07-02 15:38:35 +0000911
912Completion is done by a function that can be defined by the user with the
Bram Moolenaar280f1262006-01-30 00:14:18 +0000913'completefunc' option. See below for how the function is called and an
914example |complete-functions|.
Bram Moolenaarcfbc5ee2004-07-02 15:38:35 +0000915
916 *i_CTRL-X_CTRL-U*
917CTRL-X CTRL-U Guess what kind of item is in front of the cursor and
918 find the first match for it.
919 CTRL-U or
920 CTRL-N Use the next match. This match replaces the previous
921 one.
922
923 CTRL-P Use the previous match. This match replaces the
924 previous one.
925
926
Bram Moolenaarf75a9632005-09-13 21:20:47 +0000927Omni completion *compl-omni*
Bram Moolenaar4be06f92005-07-29 22:36:03 +0000928
Bram Moolenaare344bea2005-09-01 20:46:49 +0000929Completion is done by a function that can be defined by the user with the
Bram Moolenaarf75a9632005-09-13 21:20:47 +0000930'omnifunc' option. This is to be used for filetype-specific completion.
Bram Moolenaare344bea2005-09-01 20:46:49 +0000931
Bram Moolenaar280f1262006-01-30 00:14:18 +0000932See below for how the function is called and an example |complete-functions|.
Bram Moolenaarf75a9632005-09-13 21:20:47 +0000933For remarks about specific filetypes see |compl-omni-filetypes|.
Bram Moolenaar9c102382006-05-03 21:26:49 +0000934More completion scripts will appear, check www.vim.org. Currently there is a
935first version for C++.
Bram Moolenaar4be06f92005-07-29 22:36:03 +0000936
937 *i_CTRL-X_CTRL-O*
938CTRL-X CTRL-O Guess what kind of item is in front of the cursor and
939 find the first match for it.
940 CTRL-O or
941 CTRL-N Use the next match. This match replaces the previous
942 one.
943
944 CTRL-P Use the previous match. This match replaces the
945 previous one.
946
947
Bram Moolenaar488c6512005-08-11 20:09:58 +0000948Spelling suggestions *compl-spelling*
949
Bram Moolenaar5195e452005-08-19 20:32:47 +0000950A word before or at the cursor is located and correctly spelled words are
951suggested to replace it. If there is a badly spelled word in the line, before
952or under the cursor, the cursor is moved to after it. Otherwise the word just
953before the cursor is used for suggestions, even though it isn't badly spelled.
954
Bram Moolenaar488c6512005-08-11 20:09:58 +0000955NOTE: CTRL-S suspends display in many Unix terminals. Use 's' instead. Type
956CTRL-Q to resume displaying.
957
958 *i_CTRL-X_CTRL-S* *i_CTRL-X_s*
959CTRL-X CTRL-S or
960CTRL-X s Locate the word in front of the cursor and find the
961 first spell suggestion for it.
962 CTRL-S or
963 CTRL-N Use the next suggestion. This replaces the previous
964 one. Note that you can't use 's' here.
965
966 CTRL-P Use the previous suggestion. This replaces the
967 previous one.
968
969
Bram Moolenaar071d4272004-06-13 20:20:40 +0000970Completing keywords from different sources *compl-generic*
971
972 *i_CTRL-N*
973CTRL-N Find next match for words that start with the
974 keyword in front of the cursor, looking in places
975 specified with the 'complete' option. The found
976 keyword is inserted in front of the cursor.
977
978 *i_CTRL-P*
979CTRL-P Find previous match for words that start with the
980 keyword in front of the cursor, looking in places
981 specified with the 'complete' option. The found
982 keyword is inserted in front of the cursor.
983
984 CTRL-N Search forward for next matching keyword. This
985 keyword replaces the previous matching keyword.
986
987 CTRL-P Search backwards for next matching keyword. This
988 keyword replaces the previous matching keyword.
989
990 CTRL-X CTRL-N or
991 CTRL-X CTRL-P Further use of CTRL-X CTRL-N or CTRL-X CTRL-P will
992 copy the words following the previous expansion in
993 other contexts unless a double CTRL-X is used.
994
Bram Moolenaar578b49e2005-09-10 19:22:57 +0000995
Bram Moolenaar280f1262006-01-30 00:14:18 +0000996FUNCTIONS FOR FINDING COMPLETIONS *complete-functions*
997
998This applies to 'completefunc' and 'omnifunc'.
999
Bram Moolenaar8b6144b2006-02-08 09:20:24 +00001000The function is called in two different ways:
1001- First the function is called to find the start of the text to be completed.
1002- Later the function is called to actually find the matches.
Bram Moolenaar280f1262006-01-30 00:14:18 +00001003
1004On the first invocation the arguments are:
1005 a:findstart 1
1006 a:base empty
1007
Bram Moolenaar8b6144b2006-02-08 09:20:24 +00001008The function must return the column where the completion starts. It must be a
1009number between zero and the cursor column "col('.')". This involves looking
1010at the characters just before the cursor and including those characters that
1011could be part of the completed item. The text between this column and the
1012cursor column will be replaced with the matches. Return -1 if no completion
1013can be done.
Bram Moolenaar280f1262006-01-30 00:14:18 +00001014
1015On the second invocation the arguments are:
1016 a:findstart 0
Bram Moolenaar8b6144b2006-02-08 09:20:24 +00001017 a:base the text with which matches should match; the text that was
Bram Moolenaar280f1262006-01-30 00:14:18 +00001018 located in the first call (can be empty)
1019
1020The function must return a List with the matching words. These matches
1021usually include the "a:base" text. When there are no matches return an empty
Bram Moolenaar8b6144b2006-02-08 09:20:24 +00001022List.
Bram Moolenaar5c4bab02006-03-10 21:37:46 +00001023 *complete-items*
Bram Moolenaar8b6144b2006-02-08 09:20:24 +00001024Each list item can either be a string or a Dictionary. When it is a string it
1025is used as the completion. When it is a Dictionary it can contain these
1026items:
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001027 word the text that will be inserted, mandatory
1028 abbr abbreviation of "word"; when not empty it is used in
1029 the menu instead of "word"
Bram Moolenaar8dff8182006-04-06 20:18:50 +00001030 menu extra text for the popup menu, displayed after "word"
1031 or "abbr"
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001032 info more information about the item, can be displayed in a
1033 preview window
Bram Moolenaar8b6144b2006-02-08 09:20:24 +00001034 kind single letter indicating the type of completion
Bram Moolenaar91170f82006-05-05 21:15:17 +00001035 icase when non-zero case is to be ignored when comparing
1036 items to be equal; when omitted zero is used, thus
1037 items that only differ in case are added
Bram Moolenaar4a85b412006-04-23 22:40:29 +00001038 dup when non-zero this match will be added even when an
1039 item with the same word is already present.
Bram Moolenaar166af9b2010-11-16 20:34:40 +01001040 empty when non-zero this match will be added even when it is
1041 an empty string
Bram Moolenaar8b6144b2006-02-08 09:20:24 +00001042
Bram Moolenaard1f56e62006-02-22 21:25:37 +00001043All of these except 'icase' must be a string. If an item does not meet these
1044requirements then an error message is given and further items in the list are
1045not used. You can mix string and Dictionary items in the returned list.
Bram Moolenaar8b6144b2006-02-08 09:20:24 +00001046
1047The "menu" item is used in the popup menu and may be truncated, thus it should
Bram Moolenaar0b598c22006-03-11 21:22:53 +00001048be relatively short. The "info" item can be longer, it will be displayed in
1049the preview window when "preview" appears in 'completeopt'. The "info" item
1050will also remain displayed after the popup menu has been removed. This is
Bram Moolenaarfc1421e2006-04-20 22:17:20 +00001051useful for function arguments. Use a single space for "info" to remove
Bram Moolenaar05365702010-10-27 18:34:44 +02001052existing text in the preview window. The size of the preview window is three
1053lines, but 'previewheight' is used when it has a value of 1 or 2.
Bram Moolenaar8b6144b2006-02-08 09:20:24 +00001054
1055The "kind" item uses a single letter to indicate the kind of completion. This
1056may be used to show the completion differently (different color or icon).
1057Currently these types can be used:
1058 v variable
1059 f function or method
Bram Moolenaar0b598c22006-03-11 21:22:53 +00001060 m member of a struct or class
1061 t typedef
1062 d #define or macro
Bram Moolenaar280f1262006-01-30 00:14:18 +00001063
1064When searching for matches takes some time call |complete_add()| to add each
1065match to the total list. These matches should then not appear in the returned
1066list! Call |complete_check()| now and then to allow the user to press a key
1067while still searching for matches. Stop searching when it returns non-zero.
1068
Bram Moolenaar166af9b2010-11-16 20:34:40 +01001069 *E839* *E840*
1070The function is allowed to move the cursor, it is restored afterwards.
1071The function is not allowed to move to another window or delete text.
Bram Moolenaar280f1262006-01-30 00:14:18 +00001072
1073An example that completes the names of the months: >
1074 fun! CompleteMonths(findstart, base)
1075 if a:findstart
1076 " locate the start of the word
1077 let line = getline('.')
1078 let start = col('.') - 1
1079 while start > 0 && line[start - 1] =~ '\a'
1080 let start -= 1
1081 endwhile
1082 return start
1083 else
1084 " find months matching with "a:base"
1085 let res = []
1086 for m in split("Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec")
1087 if m =~ '^' . a:base
1088 call add(res, m)
1089 endif
1090 endfor
1091 return res
1092 endif
1093 endfun
1094 set completefunc=CompleteMonths
1095<
1096The same, but now pretending searching for matches is slow: >
1097 fun! CompleteMonths(findstart, base)
1098 if a:findstart
1099 " locate the start of the word
1100 let line = getline('.')
1101 let start = col('.') - 1
1102 while start > 0 && line[start - 1] =~ '\a'
1103 let start -= 1
1104 endwhile
1105 return start
1106 else
1107 " find months matching with "a:base"
1108 for m in split("Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec")
1109 if m =~ '^' . a:base
1110 call complete_add(m)
1111 endif
1112 sleep 300m " simulate searching for next match
1113 if complete_check()
1114 break
1115 endif
1116 endfor
1117 return []
1118 endif
1119 endfun
1120 set completefunc=CompleteMonths
1121<
1122
Bram Moolenaar1c7715d2005-10-03 22:02:18 +00001123INSERT COMPLETION POPUP MENU *ins-completion-menu*
Bram Moolenaarebefac62005-12-28 22:39:57 +00001124 *popupmenu-completion*
Bram Moolenaar1c7715d2005-10-03 22:02:18 +00001125Vim can display the matches in a simplistic popup menu.
1126
1127The menu is used when:
Bram Moolenaara2031822006-03-07 22:29:51 +00001128- The 'completeopt' option contains "menu" or "menuone".
Bram Moolenaar1c7715d2005-10-03 22:02:18 +00001129- The terminal supports at least 8 colors.
Bram Moolenaard68071d2006-05-02 22:08:30 +00001130- There are at least two matches. One if "menuone" is used.
Bram Moolenaar1c7715d2005-10-03 22:02:18 +00001131
Bram Moolenaar56718732006-03-15 22:53:57 +00001132The 'pumheight' option can be used to set a maximum height. The default is to
1133use all space available.
1134
Bram Moolenaar779b74b2006-04-10 14:55:34 +00001135There are three states:
11361. A complete match has been inserted, e.g., after using CTRL-N or CTRL-P.
11372. A cursor key has been used to select another match. The match was not
1138 inserted then, only the entry in the popup menu is highlighted.
11393. Only part of a match has been inserted and characters were typed or the
1140 backspace key was used. The list of matches was then adjusted for what is
1141 in front of the cursor.
Bram Moolenaarc7453f52006-02-10 23:20:28 +00001142
Bram Moolenaar80a94a52006-02-23 21:26:58 +00001143You normally start in the first state, with the first match being inserted.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001144When "longest" is in 'completeopt' and there is more than one match you start
Bram Moolenaar779b74b2006-04-10 14:55:34 +00001145in the third state.
Bram Moolenaarc7453f52006-02-10 23:20:28 +00001146
Bram Moolenaar779b74b2006-04-10 14:55:34 +00001147If you select another match, e.g., with CTRL-N or CTRL-P, you go to the first
1148state. This doesn't change the list of matches.
Bram Moolenaar80a94a52006-02-23 21:26:58 +00001149
Bram Moolenaar779b74b2006-04-10 14:55:34 +00001150When you are back at the original text then you are in the third state. To
Bram Moolenaara2031822006-03-07 22:29:51 +00001151get there right away you can use a mapping that uses CTRL-P right after
1152starting the completion: >
1153 :imap <F7> <C-N><C-P>
Bram Moolenaar76916e62006-03-21 21:23:25 +00001154<
1155 *popupmenu-keys*
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001156In the first state these keys have a special meaning:
1157<BS> and CTRL-H Delete one character, find the matches for the word before
1158 the cursor. This reduces the list of matches, often to one
Bram Moolenaar80a94a52006-02-23 21:26:58 +00001159 entry, and switches to the second state.
Bram Moolenaar779b74b2006-04-10 14:55:34 +00001160Any non-special character:
1161 Stop completion without changing the match and insert the
1162 typed character.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001163
Bram Moolenaar779b74b2006-04-10 14:55:34 +00001164In the second and third state these keys have a special meaning:
Bram Moolenaar8b6144b2006-02-08 09:20:24 +00001165<BS> and CTRL-H Delete one character, find the matches for the shorter word
1166 before the cursor. This may find more matches.
1167CTRL-L Add one character from the current match, may reduce the
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001168 number of matches.
Bram Moolenaar80a94a52006-02-23 21:26:58 +00001169any printable, non-white character:
1170 Add this character and reduce the number of matches.
Bram Moolenaarc7453f52006-02-10 23:20:28 +00001171
Bram Moolenaar779b74b2006-04-10 14:55:34 +00001172In all three states these can be used:
Bram Moolenaard2cec5b2006-03-28 21:08:56 +00001173CTRL-Y Yes: Accept the currently selected match and stop completion.
Bram Moolenaar9964e462007-05-05 17:54:07 +00001174CTRL-E End completion, go back to what was there before selecting a
1175 match (what was typed or longest common string).
Bram Moolenaar80a94a52006-02-23 21:26:58 +00001176<PageUp> Select a match several entries back, but don't insert it.
1177<PageDown> Select a match several entries further, but don't insert it.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001178<Up> Select the previous match, as if CTRL-P was used, but don't
Bram Moolenaar80a94a52006-02-23 21:26:58 +00001179 insert it.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001180<Down> Select the next match, as if CTRL-N was used, but don't
Bram Moolenaar80a94a52006-02-23 21:26:58 +00001181 insert it.
Bram Moolenaar9964e462007-05-05 17:54:07 +00001182<Space> or <Tab> Stop completion without changing the match and insert the
Bram Moolenaar779b74b2006-04-10 14:55:34 +00001183 typed character.
1184
Bram Moolenaar044b68f2007-05-10 17:39:52 +00001185The behavior of the <Enter> key depends on the state you are in:
Bram Moolenaar779b74b2006-04-10 14:55:34 +00001186first state: Use the text as it is and insert a line break.
1187second state: Insert the currently selected match.
1188third state: Use the text as it is and insert a line break.
1189
1190In other words: If you used the cursor keys to select another entry in the
Bram Moolenaar044b68f2007-05-10 17:39:52 +00001191list of matches then the <Enter> key inserts that match. If you typed
1192something else then <Enter> inserts a line break.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001193
Bram Moolenaar1c7715d2005-10-03 22:02:18 +00001194
1195The colors of the menu can be changed with these highlight groups:
1196Pmenu normal item |hl-Pmenu|
1197PmenuSel selected item |hl-PmenuSel|
1198PmenuSbar scrollbar |hl-PmenuSbar|
1199PmenuThumb thumb of the scrollbar |hl-PmenuThumb|
1200
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001201There are no special mappings for when the popup menu is visible. However,
1202you can use an Insert mode mapping that checks the |pumvisible()| function to
1203do something different. Example: >
1204 :inoremap <Down> <C-R>=pumvisible() ? "\<lt>C-N>" : "\<lt>Down>"<CR>
Bram Moolenaar1c7715d2005-10-03 22:02:18 +00001205
Bram Moolenaar5c4bab02006-03-10 21:37:46 +00001206You can use of <expr> in mapping to have the popup menu used when typing a
1207character and some condition is met. For example, for typing a dot: >
1208 inoremap <expr> . MayComplete()
1209 func MayComplete()
1210 if (can complete)
1211 return ".\<C-X>\<C-O>"
1212 endif
1213 return '.'
1214 endfunc
1215
1216See |:map-<expr>| for more info.
1217
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001218
1219FILETYPE-SPECIFIC REMARKS FOR OMNI COMPLETION *compl-omni-filetypes*
1220
1221The file used for {filetype} should be autoload/{filetype}complete.vim
1222in 'runtimepath'. Thus for "java" it is autoload/javacomplete.vim.
Bram Moolenaar578b49e2005-09-10 19:22:57 +00001223
Bram Moolenaara5792f52005-11-23 21:25:05 +00001224
Bram Moolenaarf75a9632005-09-13 21:20:47 +00001225C *ft-c-omni*
Bram Moolenaar578b49e2005-09-10 19:22:57 +00001226
Bram Moolenaarf75a9632005-09-13 21:20:47 +00001227Completion of C code requires a tags file. You should use Exuberant ctags,
1228because it adds extra information that is needed for completion. You can find
Bram Moolenaar9964e462007-05-05 17:54:07 +00001229it here: http://ctags.sourceforge.net/ Version 5.6 or later is recommended.
1230
Bram Moolenaarf75a9632005-09-13 21:20:47 +00001231For version 5.5.4 you should add a patch that adds the "typename:" field:
Bram Moolenaar36fc5352006-03-04 21:49:37 +00001232 ftp://ftp.vim.org/pub/vim/unstable/patches/ctags-5.5.4.patch
Bram Moolenaar8b6144b2006-02-08 09:20:24 +00001233A compiled .exe for MS-Windows can be found at:
Bram Moolenaar36fc5352006-03-04 21:49:37 +00001234 http://georgevreilly.com/vim/ctags.html
Bram Moolenaar578b49e2005-09-10 19:22:57 +00001235
1236If you want to complete system functions you can do something like this. Use
1237ctags to generate a tags file for all the system header files: >
1238 % ctags -R -f ~/.vim/systags /usr/include /usr/local/include
1239In your vimrc file add this tags file to the 'tags' option: >
1240 set tags+=~/.vim/systags
1241
1242When using CTRL-X CTRL-O after a name without any "." or "->" it is completed
1243from the tags file directly. This works for any identifier, also function
1244names. If you want to complete a local variable name, which does not appear
1245in the tags file, use CTRL-P instead.
1246
1247When using CTRL-X CTRL-O after something that has "." or "->" Vim will attempt
1248to recognize the type of the variable and figure out what members it has.
1249This means only members valid for the variable will be listed.
1250
Bram Moolenaarf75a9632005-09-13 21:20:47 +00001251When a member name already was complete, CTRL-X CTRL-O will add a "." or
1252"->" for composite types.
1253
Bram Moolenaar578b49e2005-09-10 19:22:57 +00001254Vim doesn't include a C compiler, only the most obviously formatted
1255declarations are recognized. Preprocessor stuff may cause confusion.
1256When the same structure name appears in multiple places all possible members
1257are included.
1258
Bram Moolenaar6b730e12005-09-16 21:47:57 +00001259
Bram Moolenaar4770d092006-01-12 23:22:24 +00001260CSS *ft-css-omni*
Bram Moolenaara5792f52005-11-23 21:25:05 +00001261
1262Complete properties and their appropriate values according to CSS 2.1
Bram Moolenaare2f98b92006-03-29 21:18:24 +00001263specification.
Bram Moolenaara5792f52005-11-23 21:25:05 +00001264
1265
Bram Moolenaare2f98b92006-03-29 21:18:24 +00001266HTML *ft-html-omni*
1267XHTML *ft-xhtml-omni*
Bram Moolenaar6b730e12005-09-16 21:47:57 +00001268
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001269CTRL-X CTRL-O provides completion of various elements of (X)HTML files. It is
1270designed to support writing of XHTML 1.0 Strict files but will also works for
1271other versions of HTML. Features:
Bram Moolenaar6b730e12005-09-16 21:47:57 +00001272
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001273- after "<" complete tag name depending on context (no div suggestion inside
1274 of an a tag); '/>' indicates empty tags
1275- inside of tag complete proper attributes (no width attribute for an a tag);
1276 show also type of attribute; '*' indicates required attributes
1277- when attribute has limited number of possible values help to complete them
Bram Moolenaara5792f52005-11-23 21:25:05 +00001278- complete names of entities
Bram Moolenaar1e015462005-09-25 22:16:38 +00001279- complete values of "class" and "id" attributes with data obtained from
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001280 <style> tag and included CSS files
Bram Moolenaar8b6144b2006-02-08 09:20:24 +00001281- when completing value of "style" attribute or working inside of "style" tag
Bram Moolenaar1e015462005-09-25 22:16:38 +00001282 switch to |ft-css-omni| completion
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001283- when completing values of events attributes or working inside of "script"
1284 tag switch to |ft-javascript-omni| completion
Bram Moolenaar1e015462005-09-25 22:16:38 +00001285- when used after "</" CTRL-X CTRL-O will close the last opened tag
Bram Moolenaar6b730e12005-09-16 21:47:57 +00001286
Bram Moolenaara5792f52005-11-23 21:25:05 +00001287Note: When used first time completion menu will be shown with little delay
Bram Moolenaare2f98b92006-03-29 21:18:24 +00001288- this is time needed for loading of data file.
Bram Moolenaar8b6144b2006-02-08 09:20:24 +00001289Note: Completion may fail in badly formatted documents. In such case try to
1290run |:make| command to detect formatting problems.
Bram Moolenaara5792f52005-11-23 21:25:05 +00001291
1292
Bram Moolenaarc1e37902006-04-18 21:55:01 +00001293HTML flavor *html-flavor*
1294
Bram Moolenaar9c102382006-05-03 21:26:49 +00001295The default HTML completion depends on the filetype. For HTML files it is
1296HTML 4.01 Transitional ('filetype' is "html"), for XHTML it is XHTML 1.0
1297Strict ('filetype' is "xhtml").
Bram Moolenaarc1e37902006-04-18 21:55:01 +00001298
Bram Moolenaar9c102382006-05-03 21:26:49 +00001299When doing completion outside of any other tag you will have possibility to
1300choose DOCTYPE and the appropriate data file will be loaded and used for all
1301next completions.
Bram Moolenaarc1e37902006-04-18 21:55:01 +00001302
Bram Moolenaar9c102382006-05-03 21:26:49 +00001303More about format of data file in |xml-omni-datafile|. Some of the data files
1304may be found on the Vim website (|www|).
Bram Moolenaarc1e37902006-04-18 21:55:01 +00001305
Bram Moolenaar9c102382006-05-03 21:26:49 +00001306Note that b:html_omni_flavor may point to a file with any XML data. This
1307makes possible to mix PHP (|ft-php-omni|) completion with any XML dialect
1308(assuming you have data file for it). Without setting that variable XHTML 1.0
1309Strict will be used.
Bram Moolenaarc1e37902006-04-18 21:55:01 +00001310
1311
Bram Moolenaare2f98b92006-03-29 21:18:24 +00001312JAVASCRIPT *ft-javascript-omni*
Bram Moolenaarb8a7b562006-02-01 21:47:16 +00001313
Bram Moolenaar8b6144b2006-02-08 09:20:24 +00001314Completion of most elements of JavaScript language and DOM elements.
Bram Moolenaarb8a7b562006-02-01 21:47:16 +00001315
1316Complete:
1317
1318- variables
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001319- function name; show function arguments
Bram Moolenaarb8a7b562006-02-01 21:47:16 +00001320- function arguments
1321- properties of variables trying to detect type of variable
Bram Moolenaar8b6144b2006-02-08 09:20:24 +00001322- complete DOM objects and properties depending on context
Bram Moolenaarb8a7b562006-02-01 21:47:16 +00001323- keywords of language
1324
Bram Moolenaar8b6144b2006-02-08 09:20:24 +00001325Completion works in separate JavaScript files (&ft==javascript), inside of
1326<script> tag of (X)HTML and in values of event attributes (including scanning
1327of external files.
Bram Moolenaare2f98b92006-03-29 21:18:24 +00001328
Bram Moolenaarb8a7b562006-02-01 21:47:16 +00001329DOM compatibility
1330
1331At the moment (beginning of 2006) there are two main browsers - MS Internet
1332Explorer and Mozilla Firefox. These two applications are covering over 90% of
1333market. Theoretically standards are created by W3C organisation
1334(http://www.w3c.org) but they are not always followed/implemented.
1335
Bram Moolenaare2f98b92006-03-29 21:18:24 +00001336 IE FF W3C Omni completion ~
1337 +/- +/- + + ~
1338 + + - + ~
1339 + - - - ~
1340 - + - - ~
Bram Moolenaarb8a7b562006-02-01 21:47:16 +00001341
1342Regardless from state of implementation in browsers but if element is defined
1343in standards, completion plugin will place element in suggestion list. When
1344both major engines implemented element, even if this is not in standards it
1345will be suggested. All other elements are not placed in suggestion list.
1346
1347
Bram Moolenaare2f98b92006-03-29 21:18:24 +00001348PHP *ft-php-omni*
Bram Moolenaar362e1a32006-03-06 23:29:24 +00001349
Bram Moolenaar9964e462007-05-05 17:54:07 +00001350Completion of PHP code requires a tags file for completion of data from
1351external files and for class aware completion. You should use Exuberant ctags
1352version 5.5.4 or newer. You can find it here: http://ctags.sourceforge.net/
Bram Moolenaar362e1a32006-03-06 23:29:24 +00001353
1354Script completes:
1355
1356- after $ variables name
Bram Moolenaar0b598c22006-03-11 21:22:53 +00001357 - if variable was declared as object add "->", if tags file is available show
1358 name of class
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001359 - after "->" complete only function and variable names specific for given
1360 class. To find class location and contents tags file is required. Because
1361 PHP isn't strongly typed language user can use @var tag to declare class: >
1362
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001363 /* @var $myVar myClass */
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001364 $myVar->
1365<
1366 Still, to find myClass contents tags file is required.
Bram Moolenaar0b598c22006-03-11 21:22:53 +00001367
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00001368- function names with additional info:
Bram Moolenaar0b598c22006-03-11 21:22:53 +00001369 - in case of built-in functions list of possible arguments and after | type
1370 data returned by function
Bram Moolenaar06b5d512010-05-22 15:37:44 +02001371 - in case of user function arguments and name of file where function was
Bram Moolenaar0b598c22006-03-11 21:22:53 +00001372 defined (if it is not current file)
1373
1374- constants names
1375- class names after "new" declaration
1376
Bram Moolenaar362e1a32006-03-06 23:29:24 +00001377
1378Note: when doing completion first time Vim will load all necessary data into
1379memory. It may take several seconds. After next use of completion delay
Bram Moolenaar0b598c22006-03-11 21:22:53 +00001380should not be noticeable.
Bram Moolenaar362e1a32006-03-06 23:29:24 +00001381
1382Script detects if cursor is inside <?php ?> tags. If it is outside it will
1383automatically switch to HTML/CSS/JavaScript completion. Note: contrary to
1384original HTML files completion of tags (and only tags) isn't context aware.
1385
1386
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001387RUBY *ft-ruby-omni*
Bram Moolenaarfc1421e2006-04-20 22:17:20 +00001388
1389Completion of Ruby code requires that vim be built with |+ruby|.
1390
1391Ruby completion will parse your buffer on demand in order to provide a list of
1392completions. These completions will be drawn from modules loaded by 'require'
1393and modules defined in the current buffer.
1394
1395The completions provided by CTRL-X CTRL-O are sensitive to the context:
1396
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001397 CONTEXT COMPLETIONS PROVIDED ~
Bram Moolenaarfc1421e2006-04-20 22:17:20 +00001398
1399 1. Not inside a class definition Classes, constants and globals
1400
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001401 2. Inside a class definition Methods or constants defined in the class
Bram Moolenaarfc1421e2006-04-20 22:17:20 +00001402
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001403 3. After '.', '::' or ':' Methods applicable to the object being
1404 dereferenced
Bram Moolenaarfc1421e2006-04-20 22:17:20 +00001405
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001406 4. After ':' or ':foo' Symbol name (beginning with 'foo')
Bram Moolenaarfc1421e2006-04-20 22:17:20 +00001407
1408Notes:
1409 - Vim will load/evaluate code in order to provide completions. This may
Bram Moolenaar9964e462007-05-05 17:54:07 +00001410 cause some code execution, which may be a concern. This is no longer
1411 enabled by default, to enable this feature add >
1412 let g:rubycomplete_buffer_loading = 1
1413<- In context 1 above, Vim can parse the entire buffer to add a list of
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00001414 classes to the completion results. This feature is turned off by default,
1415 to enable it add >
1416 let g:rubycomplete_classes_in_global = 1
1417< to your vimrc
Bram Moolenaarfc1421e2006-04-20 22:17:20 +00001418 - In context 2 above, anonymous classes are not supported.
1419 - In context 3 above, Vim will attempt to determine the methods supported by
1420 the object.
1421 - Vim can detect and load the Rails environment for files within a rails
1422 project. The feature is disabled by default, to enable it add >
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00001423 let g:rubycomplete_rails = 1
1424< to your vimrc
Bram Moolenaarfc1421e2006-04-20 22:17:20 +00001425
1426
Bram Moolenaar4770d092006-01-12 23:22:24 +00001427SYNTAX *ft-syntax-omni*
1428
Bram Moolenaar9964e462007-05-05 17:54:07 +00001429Vim has the ability to color syntax highlight nearly 500 languages. Part of
1430this highlighting includes knowing what keywords are part of a language. Many
1431filetypes already have custom completion scripts written for them, the
1432syntaxcomplete plugin provides basic completion for all other filetypes. It
1433does this by populating the omni completion list with the text Vim already
1434knows how to color highlight. It can be used for any filetype and provides a
1435minimal language-sensitive completion.
Bram Moolenaar4770d092006-01-12 23:22:24 +00001436
Bram Moolenaarc06ac342006-03-02 22:43:39 +00001437To enable syntax code completion you can run: >
Bram Moolenaare2f98b92006-03-29 21:18:24 +00001438 setlocal omnifunc=syntaxcomplete#Complete
Bram Moolenaar4770d092006-01-12 23:22:24 +00001439
Bram Moolenaarc06ac342006-03-02 22:43:39 +00001440You can automate this by placing the following in your vimrc (after any
1441":filetype" command): >
1442 if has("autocmd") && exists("+omnifunc")
Bram Moolenaare2f98b92006-03-29 21:18:24 +00001443 autocmd Filetype *
1444 \ if &omnifunc == "" |
1445 \ setlocal omnifunc=syntaxcomplete#Complete |
1446 \ endif
Bram Moolenaarc06ac342006-03-02 22:43:39 +00001447 endif
Bram Moolenaar4770d092006-01-12 23:22:24 +00001448
Bram Moolenaarc06ac342006-03-02 22:43:39 +00001449The above will set completion to this script only if a specific plugin does
1450not already exist for that filetype.
1451
1452Each filetype can have a wide range of syntax items. The plugin allows you to
1453customize which syntax groups to include or exclude from the list. Let's have
1454a look at the PHP filetype to see how this works.
1455
1456If you edit a file called, index.php, run the following command: >
1457 :syntax list
1458
Bram Moolenaar06b5d512010-05-22 15:37:44 +02001459The first thing you will notice is that there are many different syntax groups.
1460The PHP language can include elements from different languages like HTML,
Bram Moolenaarc06ac342006-03-02 22:43:39 +00001461JavaScript and many more. The syntax plugin will only include syntax groups
1462that begin with the filetype, "php", in this case. For example these syntax
1463groups are included by default with the PHP: phpEnvVar, phpIntVar,
1464phpFunctions.
1465
1466The PHP language has an enormous number of items which it knows how to syntax
1467highlight. This means these items will be available within the omni
1468completion list. Some people may find this list unwieldy or are only
1469interested in certain items.
1470
1471There are two ways to prune this list (if necessary). If you find certain
1472syntax groups you do not wish displayed you can add the following to your
1473vimrc: >
1474 let g:omni_syntax_group_exclude_php = 'phpCoreConstant,phpConstant'
1475
1476Add as many syntax groups to this list by comma separating them. The basic
1477form of this variable is: >
1478 let g:omni_syntax_group_exclude_{filetype} = 'comma,separated,list'
1479
1480For completeness the opposite is also true. Creating this variable in your
1481vimrc will only include the items in the phpFunctions and phpMethods syntax
1482groups: >
1483 let g:omni_syntax_group_include_php = 'phpFunctions,phpMethods'
1484
1485You can create as many of these variables as you need, varying only the
1486filetype at the end of the variable name.
Bram Moolenaar4770d092006-01-12 23:22:24 +00001487
Bram Moolenaar9964e462007-05-05 17:54:07 +00001488The plugin uses the isKeyword option to determine where word boundaries are
1489for the syntax items. For example, in the Scheme language completion should
1490include the "-", call-with-output-file. Depending on your filetype, this may
1491not provide the words you are expecting. Setting the
1492g:omni_syntax_use_iskeyword option to 0 will force the syntax plugin to break
1493on word characters. This can be controlled adding the following to your
1494vimrc: >
1495 let g:omni_syntax_use_iskeyword = 0
1496
Bram Moolenaar8b682772010-07-30 21:49:40 +02001497For plugin developers, the plugin exposes a public function OmniSyntaxList.
1498This function can be used to request a List of syntax items. When editing a
1499SQL file (:e syntax.sql) you can use the ":syntax list" command to see the
1500various groups and syntax items. For example: >
1501 syntax list
1502
1503Yields data similar to this: >
1504 sqlOperator xxx some prior all like and any escape exists in is not
1505 or intersect minus between distinct
1506 links to Operator
1507 sqlType xxx varbit varchar nvarchar bigint int uniqueidentifier
1508 date money long tinyint unsigned xml text smalldate
1509 double datetime nchar smallint numeric time bit char
1510 varbinary binary smallmoney
1511 image float integer timestamp real decimal
1512
1513There are two syntax groups listed here: sqlOperator and sqlType. To retrieve
1514a List of syntax items you can call OmniSyntaxList a number of different
1515ways. To retrieve all syntax items regardless of syntax group: >
1516 echo OmniSyntaxList( [] )
1517
1518To retrieve only the syntax items for the sqlOperator syntax group: >
1519 echo OmniSyntaxList( ['sqlOperator'] )
1520
1521To retrieve all syntax items for both the sqlOperator and sqlType groups: >
1522 echo OmniSyntaxList( ['sqlOperator', 'sqlType'] )
1523
1524From within a plugin, you would typically assign the output to a List: >
1525 let myKeywords = []
1526 let myKeywords = OmniSyntaxList( ['sqlKeyword'] )
1527
1528
Bram Moolenaar4770d092006-01-12 23:22:24 +00001529
Bram Moolenaare2f98b92006-03-29 21:18:24 +00001530SQL *ft-sql-omni*
1531
1532Completion for the SQL language includes statements, functions, keywords.
1533It will also dynamically complete tables, procedures, views and column lists
1534with data pulled directly from within a database. For detailed instructions
1535and a tutorial see |omni-sql-completion|.
1536
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001537The SQL completion plugin can be used in conjunction with other completion
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001538plugins. For example, the PHP filetype has its own completion plugin.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001539Since PHP is often used to generate dynamic website by accessing a database,
1540the SQL completion plugin can also be enabled. This allows you to complete
1541PHP code and SQL code at the same time.
1542
Bram Moolenaare2f98b92006-03-29 21:18:24 +00001543
Bram Moolenaar4770d092006-01-12 23:22:24 +00001544XML *ft-xml-omni*
Bram Moolenaara5792f52005-11-23 21:25:05 +00001545
Bram Moolenaar9c102382006-05-03 21:26:49 +00001546Vim 7 provides a mechanism for context aware completion of XML files. It
1547depends on a special |xml-omni-datafile| and two commands: |:XMLns| and
1548|:XMLent|. Features are:
Bram Moolenaara5792f52005-11-23 21:25:05 +00001549
Bram Moolenaar9c102382006-05-03 21:26:49 +00001550- after "<" complete the tag name, depending on context
1551- inside of a tag complete proper attributes
1552- when an attribute has a limited number of possible values help to complete
Bram Moolenaara5792f52005-11-23 21:25:05 +00001553 them
Bram Moolenaar9c102382006-05-03 21:26:49 +00001554- complete names of entities (defined in |xml-omni-datafile| and in the
1555 current file with "<!ENTITY" declarations)
Bram Moolenaara5792f52005-11-23 21:25:05 +00001556- when used after "</" CTRL-X CTRL-O will close the last opened tag
1557
Bram Moolenaar4770d092006-01-12 23:22:24 +00001558Format of XML data file *xml-omni-datafile*
Bram Moolenaara5792f52005-11-23 21:25:05 +00001559
Bram Moolenaar9c102382006-05-03 21:26:49 +00001560XML data files are stored in the "autoload/xml" directory in 'runtimepath'.
1561Vim distribution provides examples of data files in the
1562"$VIMRUNTIME/autoload/xml" directory. They have a meaningful name which will
1563be used in commands. It should be a unique name which will not create
1564conflicts. For example, the name xhtml10s.vim means it is the data file for
1565XHTML 1.0 Strict.
Bram Moolenaara5792f52005-11-23 21:25:05 +00001566
Bram Moolenaar9c102382006-05-03 21:26:49 +00001567Each file contains a variable with a name like g:xmldata_xhtml10s . It is
1568a compound from two parts:
Bram Moolenaara5792f52005-11-23 21:25:05 +00001569
Bram Moolenaar9c102382006-05-03 21:26:49 +000015701. "g:xmldata_" general prefix, constant for all data files
15712. "xhtml10s" the name of the file and the name of the described XML
1572 dialect; it will be used as an argument for the |:XMLns|
1573 command
Bram Moolenaara5792f52005-11-23 21:25:05 +00001574
1575Part two must be exactly the same as name of file.
1576
Bram Moolenaar9c102382006-05-03 21:26:49 +00001577The variable is a |Dictionary|. Keys are tag names and each value is a two
1578element |List|. The first element of the List is also a List with the names
1579of possible children. The second element is a |Dictionary| with the names of
1580attributes as keys and the possible values of attributes as values. Example: >
Bram Moolenaara5792f52005-11-23 21:25:05 +00001581
Bram Moolenaar9c102382006-05-03 21:26:49 +00001582 let g:xmldata_crippled = {
1583 \ "vimxmlentities": ["amp", "lt", "gt", "apos", "quot"],
1584 \ 'vimxmlroot': ['tag1'],
1585 \ 'tag1':
1586 \ [ ['childoftag1a', 'childoftag1b'], {'attroftag1a': [],
1587 \ 'attroftag1b': ['valueofattr1', 'valueofattr2']}],
1588 \ 'childoftag1a':
1589 \ [ [], {'attrofchild': ['attrofchild']}],
1590 \ 'childoftag1b':
1591 \ [ ['childoftag1a'], {'attrofchild': []}],
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001592 \ "vimxmltaginfo": {
Bram Moolenaar9c102382006-05-03 21:26:49 +00001593 \ 'tag1': ['Menu info', 'Long information visible in preview window']},
1594 \ 'vimxmlattrinfo': {
1595 \ 'attrofchild': ['Menu info', 'Long information visible in preview window']}}
Bram Moolenaara5792f52005-11-23 21:25:05 +00001596
Bram Moolenaar9c102382006-05-03 21:26:49 +00001597This example would be put in the "autoload/xml/crippled.vim" file and could
1598help to write this file: >
Bram Moolenaara5792f52005-11-23 21:25:05 +00001599
Bram Moolenaar9c102382006-05-03 21:26:49 +00001600 <tag1 attroftag1b="valueofattr1">
1601 <childoftag1a attrofchild>
1602 &amp; &lt;
1603 </childoftag1a>
1604 <childoftag1b attrofchild="5">
1605 <childoftag1a>
1606 &gt; &apos; &quot;
1607 </childoftag1a>
1608 </childoftag1b>
1609 </tag1>
Bram Moolenaara5792f52005-11-23 21:25:05 +00001610
Bram Moolenaar9c102382006-05-03 21:26:49 +00001611In the example four special elements are visible:
1612
16131. "vimxmlentities" - a special key with List containing entities of this XML
Bram Moolenaara5792f52005-11-23 21:25:05 +00001614 dialect.
Bram Moolenaar9c102382006-05-03 21:26:49 +000016152. If the list containing possible values of attributes has one element and
1616 this element is equal to the name of the attribute this attribute will be
1617 treated as boolean and inserted as 'attrname' and not as 'attrname="'
16183. "vimxmltaginfo" - a special key with a Dictionary containing tag
1619 names as keys and two element List as values, for additional menu info and
1620 the long description.
16214. "vimxmlattrinfo" - special key with Dictionary containing attribute names
1622 as keys and two element List as values, for additional menu info and long
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001623 description.
Bram Moolenaara5792f52005-11-23 21:25:05 +00001624
Bram Moolenaar9c102382006-05-03 21:26:49 +00001625Note: Tag names in the data file MUST not contain a namespace description.
1626Check xsl.vim for an example.
1627Note: All data and functions are publicly available as global
1628variables/functions and can be used for personal editing functions.
Bram Moolenaara5792f52005-11-23 21:25:05 +00001629
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001630
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001631DTD -> Vim *dtd2vim*
Bram Moolenaarc1e37902006-04-18 21:55:01 +00001632
Bram Moolenaar9c102382006-05-03 21:26:49 +00001633On |www| is the script |dtd2vim| which parses DTD and creates an XML data file
Bram Moolenaarc1e37902006-04-18 21:55:01 +00001634for Vim XML omni completion.
1635
1636 dtd2vim: http://www.vim.org/scripts/script.php?script_id=1462
1637
Bram Moolenaar9c102382006-05-03 21:26:49 +00001638Check the beginning of that file for usage details.
1639The script requires perl and:
Bram Moolenaarc1e37902006-04-18 21:55:01 +00001640
1641 perlSGML: http://savannah.nongnu.org/projects/perlsgml
1642
1643
Bram Moolenaara5792f52005-11-23 21:25:05 +00001644Commands
1645
Bram Moolenaar4770d092006-01-12 23:22:24 +00001646:XMLns {name} [{namespace}] *:XMLns*
Bram Moolenaara5792f52005-11-23 21:25:05 +00001647
Bram Moolenaar9c102382006-05-03 21:26:49 +00001648Vim has to know which data file should be used and with which namespace. For
1649loading of the data file and connecting data with the proper namespace use
1650|:XMLns| command. The first (obligatory) argument is the name of the data
1651(xhtml10s, xsl). The second argument is the code of namespace (h, xsl). When
1652used without a second argument the dialect will be used as default - without
1653namespace declaration. For example to use XML completion in .xsl files: >
Bram Moolenaara5792f52005-11-23 21:25:05 +00001654
1655 :XMLns xhtml10s
1656 :XMLns xsl xsl
1657
1658
Bram Moolenaar4770d092006-01-12 23:22:24 +00001659:XMLent {name} *:XMLent*
Bram Moolenaara5792f52005-11-23 21:25:05 +00001660
Bram Moolenaar9c102382006-05-03 21:26:49 +00001661By default entities will be completed from the data file of the default
1662namespace. The XMLent command should be used in case when there is no default
1663namespace: >
Bram Moolenaara5792f52005-11-23 21:25:05 +00001664
Bram Moolenaar4770d092006-01-12 23:22:24 +00001665 :XMLent xhtml10s
Bram Moolenaara5792f52005-11-23 21:25:05 +00001666
1667Usage
1668
Bram Moolenaar9c102382006-05-03 21:26:49 +00001669While used in this situation (after declarations from previous part, | is
Bram Moolenaara5792f52005-11-23 21:25:05 +00001670cursor position): >
1671
Bram Moolenaar4770d092006-01-12 23:22:24 +00001672 <|
Bram Moolenaara5792f52005-11-23 21:25:05 +00001673
Bram Moolenaar9c102382006-05-03 21:26:49 +00001674Will complete to an appropriate XHTML tag, and in this situation: >
Bram Moolenaara5792f52005-11-23 21:25:05 +00001675
Bram Moolenaar4770d092006-01-12 23:22:24 +00001676 <xsl:|
Bram Moolenaara5792f52005-11-23 21:25:05 +00001677
Bram Moolenaar9c102382006-05-03 21:26:49 +00001678Will complete to an appropriate XSL tag.
Bram Moolenaara5792f52005-11-23 21:25:05 +00001679
Bram Moolenaar9c102382006-05-03 21:26:49 +00001680
1681The script xmlcomplete.vim, provided through the |autoload| mechanism,
1682has the xmlcomplete#GetLastOpenTag() function which can be used in XML files
1683to get the name of the last open tag (b:unaryTagsStack has to be defined): >
Bram Moolenaar6b730e12005-09-16 21:47:57 +00001684
Bram Moolenaar4770d092006-01-12 23:22:24 +00001685 :echo xmlcomplete#GetLastOpenTag("b:unaryTagsStack")
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00001686
Bram Moolenaar6b730e12005-09-16 21:47:57 +00001687
Bram Moolenaar1e015462005-09-25 22:16:38 +00001688
Bram Moolenaar071d4272004-06-13 20:20:40 +00001689==============================================================================
16908. Insert mode commands *inserting*
1691
1692The following commands can be used to insert new text into the buffer. They
1693can all be undone and repeated with the "." command.
1694
1695 *a*
1696a Append text after the cursor [count] times. If the
1697 cursor is in the first column of an empty line Insert
1698 starts there. But not when 'virtualedit' is set!
1699
1700 *A*
1701A Append text at the end of the line [count] times.
1702
1703<insert> or *i* *insert* *<Insert>*
1704i Insert text before the cursor [count] times.
1705 When using CTRL-O in Insert mode |i_CTRL-O| the count
1706 is not supported.
1707
1708 *I*
1709I Insert text before the first non-blank in the line
1710 [count] times.
Bram Moolenaar4399ef42005-02-12 14:29:27 +00001711 When the 'H' flag is present in 'cpoptions' and the
1712 line only contains blanks, insert start just before
1713 the last blank.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001714
1715 *gI*
1716gI Insert text in column 1 [count] times. {not in Vi}
1717
1718 *gi*
1719gi Insert text in the same position as where Insert mode
1720 was stopped last time in the current buffer.
1721 This uses the |'^| mark. It's different from "`^i"
1722 when the mark is past the end of the line.
1723 The position is corrected for inserted/deleted lines,
1724 but NOT for inserted/deleted characters.
1725 When the |:keepjumps| command modifier is used the |'^|
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001726 mark won't be changed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001727 {not in Vi}
1728
1729 *o*
1730o Begin a new line below the cursor and insert text,
1731 repeat [count] times. {Vi: blank [count] screen
1732 lines}
Bram Moolenaar4399ef42005-02-12 14:29:27 +00001733 When the '#' flag is in 'cpoptions' the count is
1734 ignored.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001735
1736 *O*
1737O Begin a new line above the cursor and insert text,
1738 repeat [count] times. {Vi: blank [count] screen
1739 lines}
Bram Moolenaar4399ef42005-02-12 14:29:27 +00001740 When the '#' flag is in 'cpoptions' the count is
1741 ignored.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001742
1743These commands are used to start inserting text. You can end insert mode with
1744<Esc>. See |mode-ins-repl| for the other special characters in Insert mode.
1745The effect of [count] takes place after Insert mode is exited.
1746
1747When 'autoindent' is on, the indent for a new line is obtained from the
1748previous line. When 'smartindent' or 'cindent' is on, the indent for a line
1749is automatically adjusted for C programs.
1750
1751'textwidth' can be set to the maximum width for a line. When a line becomes
1752too long when appending characters a line break is automatically inserted.
1753
1754
1755==============================================================================
17569. Ex insert commands *inserting-ex*
1757
1758 *:a* *:append*
Bram Moolenaardf177f62005-02-22 08:39:57 +00001759:{range}a[ppend][!] Insert several lines of text below the specified
Bram Moolenaar071d4272004-06-13 20:20:40 +00001760 line. If the {range} is missing, the text will be
1761 inserted after the current line.
Bram Moolenaardf177f62005-02-22 08:39:57 +00001762 Adding [!] toggles 'autoindent' for the time this
1763 command is executed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001764
1765 *:i* *:in* *:insert*
Bram Moolenaardf177f62005-02-22 08:39:57 +00001766:{range}i[nsert][!] Insert several lines of text above the specified
Bram Moolenaar071d4272004-06-13 20:20:40 +00001767 line. If the {range} is missing, the text will be
1768 inserted before the current line.
Bram Moolenaardf177f62005-02-22 08:39:57 +00001769 Adding [!] toggles 'autoindent' for the time this
1770 command is executed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001771
1772These two commands will keep on asking for lines, until you type a line
1773containing only a ".". Watch out for lines starting with a backslash, see
1774|line-continuation|.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001775
Bram Moolenaar4a748032010-09-30 21:47:56 +02001776When in Ex mode (see |-e|) a backslash at the end of the line can be used to
1777insert a NUL character. To be able to have a line ending in a backslash use
1778two backslashes. This means that the number of backslashes is halved, but
1779only at the end of the line.
1780
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001781NOTE: These commands cannot be used with |:global| or |:vglobal|.
1782":append" and ":insert" don't work properly in between ":if" and
Bram Moolenaar06fb4352005-01-05 22:10:30 +00001783":endif", ":for" and ":endfor", ":while" and ":endwhile".
Bram Moolenaar071d4272004-06-13 20:20:40 +00001784
1785 *:start* *:startinsert*
1786:star[tinsert][!] Start Insert mode just after executing this command.
1787 Works like typing "i" in Normal mode. When the ! is
1788 included it works like "A", append to the line.
1789 Otherwise insertion starts at the cursor position.
1790 Note that when using this command in a function or
1791 script, the insertion only starts after the function
1792 or script is finished.
Bram Moolenaar87e25fd2005-07-27 21:13:01 +00001793 This command does not work from |:normal|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001794 {not in Vi}
Bram Moolenaardb84e452010-08-15 13:50:43 +02001795 {not available when compiled without the |+ex_extra|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001796 feature}
1797
1798 *:stopi* *:stopinsert*
1799:stopi[nsert] Stop Insert mode as soon as possible. Works like
1800 typing <Esc> in Insert mode.
1801 Can be used in an autocommand, example: >
1802 :au BufEnter scratch stopinsert
Bram Moolenaar325b7a22004-07-05 15:58:32 +00001803<
1804 *replacing-ex* *:startreplace*
1805:startr[eplace][!] Start Replace mode just after executing this command.
1806 Works just like typing "R" in Normal mode. When the
1807 ! is included it acts just like "$R" had been typed
1808 (ie. begin replace mode at the end-of-line). Other-
1809 wise replacement begins at the cursor position.
1810 Note that when using this command in a function or
1811 script that the replacement will only start after
1812 the function or script is finished.
1813 {not in Vi}
Bram Moolenaardb84e452010-08-15 13:50:43 +02001814 {not available when compiled without the |+ex_extra|
Bram Moolenaar325b7a22004-07-05 15:58:32 +00001815 feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001816
Bram Moolenaar61da4982005-12-14 22:02:18 +00001817 *:startgreplace*
1818:startg[replace][!] Just like |:startreplace|, but use Virtual Replace
1819 mode, like with |gR|.
1820 {not in Vi}
Bram Moolenaardb84e452010-08-15 13:50:43 +02001821 {not available when compiled without the |+ex_extra|
Bram Moolenaar61da4982005-12-14 22:02:18 +00001822 feature}
1823
Bram Moolenaar071d4272004-06-13 20:20:40 +00001824==============================================================================
182510. Inserting a file *inserting-file*
1826
1827 *:r* *:re* *:read*
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001828:r[ead] [++opt] [name]
1829 Insert the file [name] (default: current file) below
Bram Moolenaar071d4272004-06-13 20:20:40 +00001830 the cursor.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001831 See |++opt| for the possible values of [++opt].
Bram Moolenaar071d4272004-06-13 20:20:40 +00001832
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001833:{range}r[ead] [++opt] [name]
1834 Insert the file [name] (default: current file) below
Bram Moolenaar071d4272004-06-13 20:20:40 +00001835 the specified line.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001836 See |++opt| for the possible values of [++opt].
Bram Moolenaar071d4272004-06-13 20:20:40 +00001837
1838 *:r!* *:read!*
Bram Moolenaar9964e462007-05-05 17:54:07 +00001839:[range]r[ead] !{cmd} Execute {cmd} and insert its standard output below
1840 the cursor or the specified line. A temporary file is
1841 used to store the output of the command which is then
1842 read into the buffer. 'shellredir' is used to save
1843 the output of the command, which can be set to include
1844 stderr or not. {cmd} is executed like with ":!{cmd}",
1845 any '!' is replaced with the previous command |:!|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001846
1847These commands insert the contents of a file, or the output of a command,
1848into the buffer. They can be undone. They cannot be repeated with the "."
1849command. They work on a line basis, insertion starts below the line in which
1850the cursor is, or below the specified line. To insert text above the first
1851line use the command ":0r {name}".
1852
1853After the ":read" command, the cursor is left on the first non-blank in the
1854first new line. Unless in Ex mode, then the cursor is left on the last new
1855line (sorry, this is Vi compatible).
1856
1857If a file name is given with ":r", it becomes the alternate file. This can be
1858used, for example, when you want to edit that file instead: ":e! #". This can
1859be switched off by removing the 'a' flag from the 'cpoptions' option.
1860
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001861Of the [++opt] arguments one is specifically for ":read", the ++edit argument.
1862This is useful when the ":read" command is actually used to read a file into
1863the buffer as if editing that file. Use this command in an empty buffer: >
1864 :read ++edit filename
1865The effect is that the 'fileformat', 'fileencoding', 'bomb', etc. options are
1866set to what has been detected for "filename". Note that a single empty line
1867remains, you may want to delete it.
1868
Bram Moolenaar071d4272004-06-13 20:20:40 +00001869 *file-read*
1870The 'fileformat' option sets the <EOL> style for a file:
1871'fileformat' characters name ~
1872 "dos" <CR><NL> or <NL> DOS format
1873 "unix" <NL> Unix format
1874 "mac" <CR> Mac format
1875Previously 'textmode' was used. It is obsolete now.
1876
1877If 'fileformat' is "dos", a <CR> in front of an <NL> is ignored and a CTRL-Z
1878at the end of the file is ignored.
1879
1880If 'fileformat' is "mac", a <NL> in the file is internally represented by a
1881<CR>. This is to avoid confusion with a <NL> which is used to represent a
1882<NUL>. See |CR-used-for-NL|.
1883
1884If the 'fileformats' option is not empty Vim tries to recognize the type of
1885<EOL> (see |file-formats|). However, the 'fileformat' option will not be
1886changed, the detected format is only used while reading the file.
1887A similar thing happens with 'fileencodings'.
1888
1889On non-MS-DOS, Win32, and OS/2 systems the message "[dos format]" is shown if
1890a file is read in DOS format, to remind you that something unusual is done.
1891On Macintosh, MS-DOS, Win32, and OS/2 the message "[unix format]" is shown if
1892a file is read in Unix format.
1893On non-Macintosh systems, the message "[Mac format]" is shown if a file is
1894read in Mac format.
1895
1896An example on how to use ":r !": >
1897 :r !uuencode binfile binfile
1898This command reads "binfile", uuencodes it and reads it into the current
1899buffer. Useful when you are editing e-mail and want to include a binary
1900file.
1901
1902 *read-messages*
1903When reading a file Vim will display a message with information about the read
1904file. In the table is an explanation for some of the items. The others are
1905self explanatory. Using the long or the short version depends on the
1906'shortmess' option.
1907
1908 long short meaning ~
1909 [readonly] {RO} the file is write protected
1910 [fifo/socket] using a stream
1911 [fifo] using a fifo stream
1912 [socket] using a socket stream
1913 [CR missing] reading with "dos" 'fileformat' and a
1914 NL without a preceding CR was found.
1915 [NL found] reading with "mac" 'fileformat' and a
1916 NL was found (could be "unix" format)
1917 [long lines split] at least one line was split in two
1918 [NOT converted] conversion from 'fileencoding' to
1919 'encoding' was desired but not
1920 possible
1921 [converted] conversion from 'fileencoding' to
1922 'encoding' done
1923 [crypted] file was decrypted
1924 [READ ERRORS] not all of the file could be read
1925
1926
1927 vim:tw=78:ts=8:ft=help:norl: