blob: 9ec46825e4c1fa46bc0c1f7f08dd5a5f6f1a8807 [file] [log] [blame]
glepnird5fdfa52025-06-02 19:45:41 +02001*insert.txt* For Vim version 9.1. Last change: 2025 Jun 02
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-[.
Christian Brabandtd3b55d72024-10-08 20:20:23 +020054 If Esc doesn't work and you are using a Mac, try CTRL-<Esc>.
Bram Moolenaarfb539272014-08-22 19:21:47 +020055 Or disable Listening under Accessibility preferences.
Bram Moolenaar071d4272004-06-13 20:20:40 +000056 *i_CTRL-C*
57CTRL-C Quit insert mode, go back to Normal mode. Do not check for
Bram Moolenaar677ee682005-01-27 14:41:15 +000058 abbreviations. Does not trigger the |InsertLeave| autocommand
59 event.
Bram Moolenaar071d4272004-06-13 20:20:40 +000060
61 *i_CTRL-@*
Bram Moolenaara6c27c42019-05-09 19:16:22 +020062CTRL-@ Insert previously inserted text and stop insert.
63
Bram Moolenaar071d4272004-06-13 20:20:40 +000064 *i_CTRL-A*
Bram Moolenaar25c9c682019-05-05 18:13:34 +020065CTRL-A Insert previously inserted text.
Bram Moolenaar071d4272004-06-13 20:20:40 +000066
67 *i_CTRL-H* *i_<BS>* *i_BS*
68<BS> or CTRL-H Delete the character before the cursor (see |i_backspacing|
69 about joining lines).
70 See |:fixdel| if your <BS> key does not do what you want.
Bram Moolenaara6c27c42019-05-09 19:16:22 +020071
Bram Moolenaar071d4272004-06-13 20:20:40 +000072 *i_<Del>* *i_DEL*
73<Del> Delete the character under the cursor. If the cursor is at
74 the end of the line, and the 'backspace' option includes
75 "eol", delete the <EOL>; the next line is appended after the
76 current one.
77 See |:fixdel| if your <Del> key does not do what you want.
Bram Moolenaar071d4272004-06-13 20:20:40 +000078 *i_CTRL-W*
79CTRL-W Delete the word before the cursor (see |i_backspacing| about
80 joining lines). See the section "word motions",
81 |word-motions|, for the definition of a word.
82 *i_CTRL-U*
Bram Moolenaarf2571c62015-06-09 19:44:55 +020083CTRL-U Delete all entered characters before the cursor in the current
Bram Moolenaar979243b2015-06-26 19:35:49 +020084 line. If there are no newly entered characters and
85 'backspace' is not empty, delete all characters before the
Bram Moolenaarf2571c62015-06-09 19:44:55 +020086 cursor in the current line.
Bram Moolenaar04fb9162021-12-30 20:24:12 +000087 If C-indenting is enabled the indent will be adjusted if the
88 line becomes blank.
Bram Moolenaarf2571c62015-06-09 19:44:55 +020089 See |i_backspacing| about joining lines.
Bram Moolenaar071d4272004-06-13 20:20:40 +000090 *i_CTRL-I* *i_<Tab>* *i_Tab*
91<Tab> or CTRL-I Insert a tab. If the 'expandtab' option is on, the
92 equivalent number of spaces is inserted (use CTRL-V <Tab> to
93 avoid the expansion; use CTRL-Q <Tab> if CTRL-V is mapped
94 |i_CTRL-Q|). See also the 'smarttab' option and
95 |ins-expandtab|.
96 *i_CTRL-J* *i_<NL>*
97<NL> or CTRL-J Begin new line.
98 *i_CTRL-M* *i_<CR>*
99<CR> or CTRL-M Begin new line.
100 *i_CTRL-K*
101CTRL-K {char1} [char2]
102 Enter digraph (see |digraphs|). When {char1} is a special
103 key, the code for that key is inserted in <> form. For
104 example, the string "<S-Space>" can be entered by typing
105 <C-K><S-Space> (two keys). Neither char is considered for
Bram Moolenaar25c9c682019-05-05 18:13:34 +0200106 mapping.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000107
Bram Moolenaar25c9c682019-05-05 18:13:34 +0200108CTRL-N Find next keyword (see |i_CTRL-N|).
109CTRL-P Find previous keyword (see |i_CTRL-P|).
Bram Moolenaar071d4272004-06-13 20:20:40 +0000110
Bram Moolenaar5be4cee2019-09-27 19:34:08 +0200111CTRL-R {register} *i_CTRL-R*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000112 Insert the contents of a register. Between typing CTRL-R and
113 the second character, '"' will be displayed to indicate that
114 you are expected to enter the name of a register.
115 The text is inserted as if you typed it, but mappings and
116 abbreviations are not used. If you have options like
117 'textwidth', 'formatoptions', or 'autoindent' set, this will
118 influence what will be inserted. This is different from what
119 happens with the "p" command and pasting with the mouse.
120 Special registers:
121 '"' the unnamed register, containing the text of
122 the last delete or yank
123 '%' the current file name
124 '#' the alternate file name
125 '*' the clipboard contents (X11: primary selection)
126 '+' the clipboard contents
127 '/' the last search pattern
128 ':' the last command-line
129 '.' the last inserted text
Christian Brabandtee17b6f2023-09-09 11:23:50 +0200130 *i_CTRL-R_-*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000131 '-' the last small (less than a line) delete
Christian Brabandta5eb6782023-08-29 16:22:38 +0200132 register. This is repeatable using |.| since
133 it remembers the register to put instead of
134 the literal text to insert.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100135 *i_CTRL-R_=*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000136 '=' the expression register: you are prompted to
137 enter an expression (see |expression|)
Bram Moolenaar293ee4d2004-12-09 21:34:53 +0000138 Note that 0x80 (128 decimal) is used for
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +0000139 special keys. E.g., you can use this to move
140 the cursor up:
141 CTRL-R ="\<Up>"
142 Use CTRL-R CTRL-R to insert text literally.
Bram Moolenaar362e1a32006-03-06 23:29:24 +0000143 When the result is a |List| the items are used
144 as lines. They can have line breaks inside
145 too.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100146 When the result is a Float it's automatically
147 converted to a String.
Bram Moolenaar94f76b72013-07-04 22:50:40 +0200148 When append() or setline() is invoked the undo
149 sequence will be broken.
Bram Moolenaar25c9c682019-05-05 18:13:34 +0200150 See |registers| about registers.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000151
Bram Moolenaar5be4cee2019-09-27 19:34:08 +0200152CTRL-R CTRL-R {register} *i_CTRL-R_CTRL-R*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000153 Insert the contents of a register. Works like using a single
154 CTRL-R, but the text is inserted literally, not as if typed.
155 This differs when the register contains characters like <BS>.
156 Example, where register a contains "ab^Hc": >
157 CTRL-R a results in "ac".
158 CTRL-R CTRL-R a results in "ab^Hc".
159< Options 'textwidth', 'formatoptions', etc. still apply. If
Bram Moolenaarca635012015-09-25 20:34:21 +0200160 you also want to avoid these, use CTRL-R CTRL-O, see below.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000161 The '.' register (last inserted text) is still inserted as
Bram Moolenaar25c9c682019-05-05 18:13:34 +0200162 typed.
Bram Moolenaard1caa942020-04-10 22:10:56 +0200163 After this command, the '.' register contains the text from
164 the register as if it was inserted by typing it.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000165
Bram Moolenaar5be4cee2019-09-27 19:34:08 +0200166CTRL-R CTRL-O {register} *i_CTRL-R_CTRL-O*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000167 Insert the contents of a register literally and don't
168 auto-indent. Does the same as pasting with the mouse
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +0200169 |<MiddleMouse>|. When the register is linewise this will
170 insert the text above the current line, like with `P`.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000171 The '.' register (last inserted text) is still inserted as
Bram Moolenaar25c9c682019-05-05 18:13:34 +0200172 typed.
Bram Moolenaard1caa942020-04-10 22:10:56 +0200173 After this command, the '.' register contains the command
174 typed and not the text. I.e., the literals "^R^O" and not the
175 text from the register.
Christian Brabandt5d5cbb22024-01-05 18:19:52 +0100176 Does not replace characters in |Replace-mode|!
Bram Moolenaar071d4272004-06-13 20:20:40 +0000177
Bram Moolenaar5be4cee2019-09-27 19:34:08 +0200178CTRL-R CTRL-P {register} *i_CTRL-R_CTRL-P*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000179 Insert the contents of a register literally and fix the
180 indent, like |[<MiddleMouse>|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000181 The '.' register (last inserted text) is still inserted as
Bram Moolenaar25c9c682019-05-05 18:13:34 +0200182 typed.
Bram Moolenaard1caa942020-04-10 22:10:56 +0200183 After this command, the '.' register contains the command
184 typed and not the text. I.e., the literals "^R^P" and not the
185 text from the register.
Christian Brabandt5d5cbb22024-01-05 18:19:52 +0100186 Does not replace characters in |Replace-mode|!
Bram Moolenaar071d4272004-06-13 20:20:40 +0000187
188 *i_CTRL-T*
189CTRL-T Insert one shiftwidth of indent at the start of the current
190 line. The indent is always rounded to a 'shiftwidth' (this is
Bram Moolenaara6c27c42019-05-09 19:16:22 +0200191 vi compatible).
Bram Moolenaar071d4272004-06-13 20:20:40 +0000192 *i_CTRL-D*
193CTRL-D Delete one shiftwidth of indent at the start of the current
194 line. The indent is always rounded to a 'shiftwidth' (this is
Bram Moolenaara6c27c42019-05-09 19:16:22 +0200195 vi compatible).
Bram Moolenaar071d4272004-06-13 20:20:40 +0000196 *i_0_CTRL-D*
Bram Moolenaara6c27c42019-05-09 19:16:22 +02001970 CTRL-D Delete all indent in the current line.
198
Bram Moolenaar071d4272004-06-13 20:20:40 +0000199 *i_^_CTRL-D*
200^ CTRL-D Delete all indent in the current line. The indent is
201 restored in the next line. This is useful when inserting a
Bram Moolenaara6c27c42019-05-09 19:16:22 +0200202 label.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000203
204 *i_CTRL-V*
205CTRL-V Insert next non-digit literally. For special keys, the
206 terminal code is inserted. It's also possible to enter the
207 decimal, octal or hexadecimal value of a character
208 |i_CTRL-V_digit|.
209 The characters typed right after CTRL-V are not considered for
Bram Moolenaara6c27c42019-05-09 19:16:22 +0200210 mapping.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000211 Note: When CTRL-V is mapped (e.g., to paste text) you can
212 often use CTRL-Q instead |i_CTRL-Q|.
Bram Moolenaarfc4ea2a2019-11-26 19:33:22 +0100213 When |modifyOtherKeys| is enabled then special Escape sequence
214 is converted back to what it was without |modifyOtherKeys|,
215 unless the Shift key is also pressed.
216
Bram Moolenaar071d4272004-06-13 20:20:40 +0000217 *i_CTRL-Q*
218CTRL-Q Same as CTRL-V.
219 Note: Some terminal connections may eat CTRL-Q, it doesn't
220 work then. It does work in the GUI.
221
Bram Moolenaar8024f932020-01-14 19:29:13 +0100222CTRL-SHIFT-V *i_CTRL-SHIFT-V* *i_CTRL-SHIFT-Q*
223CTRL-SHIFT-Q Works just like CTRL-V, unless |modifyOtherKeys| is active,
224 then it inserts the Escape sequence for a key with modifiers.
David Mandelberg3d1a4372025-03-08 17:06:50 +0100225 Note: When CTRL-SHIFT-V is intercepted by your system (e.g.,
226 to paste text) you can often use CTRL-SHIFT-Q instead.
zeertzjqd89770e2025-03-09 08:38:35 +0100227 However, in some terminals (e.g. GNOME Terminal), CTRL-SHIFT-Q
David Mandelberg3d1a4372025-03-08 17:06:50 +0100228 quits the terminal without confirmation.
Bram Moolenaar8024f932020-01-14 19:29:13 +0100229
Bram Moolenaar071d4272004-06-13 20:20:40 +0000230CTRL-X Enter CTRL-X mode. This is a sub-mode where commands can
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000231 be given to complete words or scroll the window. See
Bram Moolenaar25c9c682019-05-05 18:13:34 +0200232 |i_CTRL-X| and |ins-completion|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000233
234 *i_CTRL-E*
Bram Moolenaar25c9c682019-05-05 18:13:34 +0200235CTRL-E Insert the character which is below the cursor.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000236 *i_CTRL-Y*
Bram Moolenaar25c9c682019-05-05 18:13:34 +0200237CTRL-Y Insert the character which is above the cursor.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000238 Note that for CTRL-E and CTRL-Y 'textwidth' is not used, to be
239 able to copy characters from a long line.
240
241 *i_CTRL-_*
242CTRL-_ Switch between languages, as follows:
243 - When in a rightleft window, revins and nohkmap are toggled,
244 since English will likely be inserted in this case.
245 - When in a norightleft window, revins and hkmap are toggled,
246 since Hebrew will likely be inserted in this case.
247
248 CTRL-_ moves the cursor to the end of the typed text.
249
250 This command is only available when the 'allowrevins' option
251 is set.
252 Please refer to |rileft.txt| for more information about
253 right-to-left mode.
Bram Moolenaar9964e462007-05-05 17:54:07 +0000254 Only if compiled with the |+rightleft| feature.
255
Bram Moolenaar071d4272004-06-13 20:20:40 +0000256 *i_CTRL-^*
257CTRL-^ Toggle the use of typing language characters.
258 When language |:lmap| mappings are defined:
259 - If 'iminsert' is 1 (langmap mappings used) it becomes 0 (no
260 langmap mappings used).
261 - If 'iminsert' has another value it becomes 1, thus langmap
262 mappings are enabled.
263 When no language mappings are defined:
264 - If 'iminsert' is 2 (Input Method used) it becomes 0 (no
265 Input Method used).
266 - If 'iminsert' has another value it becomes 2, thus the Input
267 Method is enabled.
268 When set to 1, the value of the "b:keymap_name" variable, the
269 'keymap' option or "<lang>" appears in the status line.
270 The language mappings are normally used to type characters
271 that are different from what the keyboard produces. The
272 'keymap' option can be used to install a whole number of them.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000273
274 *i_CTRL-]*
Bram Moolenaar25c9c682019-05-05 18:13:34 +0200275CTRL-] Trigger abbreviation, without inserting a character.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000276
277 *i_<Insert>*
Bram Moolenaar25c9c682019-05-05 18:13:34 +0200278<Insert> Toggle between Insert and Replace mode.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000279-----------------------------------------------------------------------
280
281 *i_backspacing*
282The effect of the <BS>, CTRL-W, and CTRL-U depend on the 'backspace' option
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +0100283(unless 'revins' is set). This is a comma-separated list of items:
Bram Moolenaar071d4272004-06-13 20:20:40 +0000284
285item action ~
286indent allow backspacing over autoindent
287eol allow backspacing over end-of-line (join lines)
288start allow backspacing over the start position of insert; CTRL-W and
289 CTRL-U stop once at the start position
290
291When 'backspace' is empty, Vi compatible backspacing is used. You cannot
292backspace over autoindent, before column 1 or before where insert started.
293
Bram Moolenaar1588bc82022-03-08 21:35:07 +0000294For backwards compatibility the values "0", "1", "2" and "3" are also allowed,
295see |'backspace'|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000296
297If the 'backspace' option does contain "eol" and the cursor is in column 1
298when one of the three keys is used, the current line is joined with the
299previous line. This effectively deletes the <EOL> in front of the cursor.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000300
301 *i_CTRL-V_digit*
302With CTRL-V the decimal, octal or hexadecimal value of a character can be
303entered directly. This way you can enter any character, except a line break
304(<NL>, value 10). There are five ways to enter the character value:
305
306first char mode max nr of chars max value ~
307(none) decimal 3 255
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000308o or O octal 3 377 (255)
Bram Moolenaar071d4272004-06-13 20:20:40 +0000309x or X hexadecimal 2 ff (255)
310u hexadecimal 4 ffff (65535)
311U hexadecimal 8 7fffffff (2147483647)
312
313Normally you would type the maximum number of characters. Thus to enter a
314space (value 32) you would type <C-V>032. You can omit the leading zero, in
315which case the character typed after the number must be a non-digit. This
316happens for the other modes as well: As soon as you type a character that is
317invalid for the mode, the value before it will be used and the "invalid"
318character is dealt with in the normal way.
319
320If you enter a value of 10, it will end up in the file as a 0. The 10 is a
321<NL>, which is used internally to represent the <Nul> character. When writing
322the buffer to a file, the <NL> character is translated into <Nul>. The <NL>
323character is written at the end of each line. Thus if you want to insert a
324<NL> character in a file you will have to make a line break.
Bram Moolenaarcb80aa22020-10-26 21:12:46 +0100325Also see 'fileformat'.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000326
327 *i_CTRL-X* *insert_expand*
328CTRL-X enters a sub-mode where several commands can be used. Most of these
Bram Moolenaare2c453d2019-08-21 14:37:09 +0200329commands do keyword completion; see |ins-completion|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000330
331Two commands can be used to scroll the window up or down, without exiting
332insert mode:
333
334 *i_CTRL-X_CTRL-E*
335CTRL-X CTRL-E scroll window one line up.
Bram Moolenaard2cec5b2006-03-28 21:08:56 +0000336 When doing completion look here: |complete_CTRL-E|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000337
338 *i_CTRL-X_CTRL-Y*
339CTRL-X CTRL-Y scroll window one line down.
Bram Moolenaard2cec5b2006-03-28 21:08:56 +0000340 When doing completion look here: |complete_CTRL-Y|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000341
342After CTRL-X is pressed, each CTRL-E (CTRL-Y) scrolls the window up (down) by
343one line unless that would cause the cursor to move from its current position
344in the file. As soon as another key is pressed, CTRL-X mode is exited and
345that key is interpreted as in Insert mode.
346
347
348==============================================================================
3492. Special special keys *ins-special-special*
350
351The following keys are special. They stop the current insert, do something,
352and then restart insertion. This means you can do something without getting
353out of Insert mode. This is very handy if you prefer to use the Insert mode
354all the time, just like editors that don't have a separate Normal mode. You
355may also want to set the 'backspace' option to "indent,eol,start" and set the
356'insertmode' option. You can use CTRL-O if you want to map a function key to
357a command.
358
359The changes (inserted or deleted characters) before and after these keys can
360be undone separately. Only the last change can be redone and always behaves
361like an "i" command.
362
363char action ~
364-----------------------------------------------------------------------
365<Up> cursor one line up *i_<Up>*
366<Down> cursor one line down *i_<Down>*
367CTRL-G <Up> cursor one line up, insert start column *i_CTRL-G_<Up>*
368CTRL-G k cursor one line up, insert start column *i_CTRL-G_k*
369CTRL-G CTRL-K cursor one line up, insert start column *i_CTRL-G_CTRL-K*
370CTRL-G <Down> cursor one line down, insert start column *i_CTRL-G_<Down>*
371CTRL-G j cursor one line down, insert start column *i_CTRL-G_j*
372CTRL-G CTRL-J cursor one line down, insert start column *i_CTRL-G_CTRL-J*
373<Left> cursor one character left *i_<Left>*
374<Right> cursor one character right *i_<Right>*
375<S-Left> cursor one word back (like "b" command) *i_<S-Left>*
376<C-Left> cursor one word back (like "b" command) *i_<C-Left>*
377<S-Right> cursor one word forward (like "w" command) *i_<S-Right>*
378<C-Right> cursor one word forward (like "w" command) *i_<C-Right>*
379<Home> cursor to first char in the line *i_<Home>*
380<End> cursor to after last char in the line *i_<End>*
381<C-Home> cursor to first char in the file *i_<C-Home>*
382<C-End> cursor to after last char in the file *i_<C-End>*
383<LeftMouse> cursor to position of mouse click *i_<LeftMouse>*
384<S-Up> move window one page up *i_<S-Up>*
385<PageUp> move window one page up *i_<PageUp>*
386<S-Down> move window one page down *i_<S-Down>*
387<PageDown> move window one page down *i_<PageDown>*
Bram Moolenaar8d9b40e2010-07-25 15:49:07 +0200388<ScrollWheelDown> move window three lines down *i_<ScrollWheelDown>*
389<S-ScrollWheelDown> move window one page down *i_<S-ScrollWheelDown>*
390<ScrollWheelUp> move window three lines up *i_<ScrollWheelUp>*
391<S-ScrollWheelUp> move window one page up *i_<S-ScrollWheelUp>*
392<ScrollWheelLeft> move window six columns left *i_<ScrollWheelLeft>*
393<S-ScrollWheelLeft> move window one page left *i_<S-ScrollWheelLeft>*
394<ScrollWheelRight> move window six columns right *i_<ScrollWheelRight>*
395<S-ScrollWheelRight> move window one page right *i_<S-ScrollWheelRight>*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000396CTRL-O execute one command, return to Insert mode *i_CTRL-O*
Bram Moolenaar4770d092006-01-12 23:22:24 +0000397CTRL-\ CTRL-O like CTRL-O but don't move the cursor *i_CTRL-\_CTRL-O*
Bram Moolenaar488c6512005-08-11 20:09:58 +0000398CTRL-L when 'insertmode' is set: go to Normal mode *i_CTRL-L*
Bram Moolenaarb529cfb2022-07-25 15:42:07 +0100399CTRL-G u close undo sequence, start new change *i_CTRL-G_u*
400CTRL-G U don't start a new undo block with the next *i_CTRL-G_U*
401 left/right cursor movement, if the cursor
402 stays within the same line
Bram Moolenaar071d4272004-06-13 20:20:40 +0000403-----------------------------------------------------------------------
404
405Note: If the cursor keys take you out of Insert mode, check the 'noesckeys'
406option.
407
408The CTRL-O command sometimes has a side effect: If the cursor was beyond the
409end of the line, it will be put on the last character in the line. In
410mappings it's often better to use <Esc> (first put an "x" in the text, <Esc>
Bram Moolenaar488c6512005-08-11 20:09:58 +0000411will then always put the cursor on it). Or use CTRL-\ CTRL-O, but then
Bram Moolenaara3e6bc92013-01-30 14:18:00 +0100412beware of the cursor possibly being beyond the end of the line. Note that the
413command following CTRL-\ CTRL-O can still move the cursor, it is not restored
414to its original position.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000415
Bram Moolenaar05365702010-10-27 18:34:44 +0200416The CTRL-O command takes you to Normal mode. If you then use a command enter
Bram Moolenaard38b0552012-04-25 19:07:41 +0200417Insert mode again it normally doesn't nest. Thus when typing "a<C-O>a" and
418then <Esc> takes you back to Normal mode, you do not need to type <Esc> twice.
419An exception is when not typing the command, e.g. when executing a mapping or
420sourcing a script. This makes mappings work that briefly switch to Insert
421mode.
Bram Moolenaar05365702010-10-27 18:34:44 +0200422
Bram Moolenaar071d4272004-06-13 20:20:40 +0000423The shifted cursor keys are not available on all terminals.
424
425Another side effect is that a count specified before the "i" or "a" command is
426ignored. That is because repeating the effect of the command after CTRL-O is
427too complicated.
428
429An example for using CTRL-G u: >
430
431 :inoremap <C-H> <C-G>u<C-H>
432
433This redefines the backspace key to start a new undo sequence. You can now
434undo the effect of the backspace key, without changing what you typed before
Bram Moolenaar5b435d62012-04-05 17:33:26 +0200435that, with CTRL-O u. Another example: >
436
437 :inoremap <CR> <C-]><C-G>u<CR>
438
Bram Moolenaarb529cfb2022-07-25 15:42:07 +0100439This starts a new undo block at each line break. It also expands
440abbreviations before this.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000441
Bram Moolenaar8b5f65a2015-09-01 19:26:12 +0200442An example for using CTRL-G U: >
443
444 inoremap <Left> <C-G>U<Left>
445 inoremap <Right> <C-G>U<Right>
446 inoremap <expr> <Home> col('.') == match(getline('.'), '\S') + 1 ?
447 \ repeat('<C-G>U<Left>', col('.') - 1) :
448 \ (col('.') < match(getline('.'), '\S') ?
449 \ repeat('<C-G>U<Right>', match(getline('.'), '\S') + 0) :
450 \ repeat('<C-G>U<Left>', col('.') - 1 - match(getline('.'), '\S')))
451 inoremap <expr> <End> repeat('<C-G>U<Right>', col('$') - col('.'))
452 inoremap ( ()<C-G>U<Left>
453
Bram Moolenaarb529cfb2022-07-25 15:42:07 +0100454This makes it possible to use the cursor keys in Insert mode, without starting
455a new undo block and therefore using |.| (redo) will work as expected. Also
456entering a text like (with the "(" mapping from above):
Bram Moolenaar8b5f65a2015-09-01 19:26:12 +0200457
458 Lorem ipsum (dolor
459
Bram Moolenaard2f3a8b2018-06-19 14:35:59 +0200460will be repeatable by using |.| to the expected
Bram Moolenaar8b5f65a2015-09-01 19:26:12 +0200461
462 Lorem ipsum (dolor)
463
Bram Moolenaarf4b8e572004-06-24 15:53:16 +0000464Using CTRL-O splits undo: the text typed before and after it is undone
465separately. If you want to avoid this (e.g., in a mapping) you might be able
466to use CTRL-R = |i_CTRL-R|. E.g., to call a function: >
467 :imap <F2> <C-R>=MyFunc()<CR>
468
Bram Moolenaar071d4272004-06-13 20:20:40 +0000469When the 'whichwrap' option is set appropriately, the <Left> and <Right>
470keys on the first/last character in the line make the cursor wrap to the
471previous/next line.
472
473The CTRL-G j and CTRL-G k commands can be used to insert text in front of a
474column. Example: >
475 int i;
476 int j;
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000477Position the cursor on the first "int", type "istatic <C-G>j ". The
Bram Moolenaar071d4272004-06-13 20:20:40 +0000478result is: >
479 static int i;
480 int j;
481When inserting the same text in front of the column in every line, use the
482Visual blockwise command "I" |v_b_I|.
483
484==============================================================================
4853. 'textwidth' and 'wrapmargin' options *ins-textwidth*
486
487The 'textwidth' option can be used to automatically break a line before it
488gets too long. Set the 'textwidth' option to the desired maximum line
489length. If you then type more characters (not spaces or tabs), the
490last word will be put on a new line (unless it is the only word on the
491line). If you set 'textwidth' to 0, this feature is disabled.
492
493The 'wrapmargin' option does almost the same. The difference is that
494'textwidth' has a fixed width while 'wrapmargin' depends on the width of the
495screen. When using 'wrapmargin' this is equal to using 'textwidth' with a
496value equal to (columns - 'wrapmargin'), where columns is the width of the
497screen.
498
499When 'textwidth' and 'wrapmargin' are both set, 'textwidth' is used.
500
501If you don't really want to break the line, but view the line wrapped at a
502convenient place, see the 'linebreak' option.
503
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +0000504The line is only broken automatically when using Insert mode, or when
Bram Moolenaar071d4272004-06-13 20:20:40 +0000505appending to a line. When in replace mode and the line length is not
506changed, the line will not be broken.
507
508Long lines are broken if you enter a non-white character after the margin.
509The situations where a line will be broken can be restricted by adding
510characters to the 'formatoptions' option:
511"l" Only break a line if it was not longer than 'textwidth' when the insert
512 started.
513"v" Only break at a white character that has been entered during the
514 current insert command. This is mostly Vi-compatible.
515"lv" Only break if the line was not longer than 'textwidth' when the insert
516 started and only at a white character that has been entered during the
517 current insert command. Only differs from "l" when entering non-white
518 characters while crossing the 'textwidth' boundary.
519
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +0000520Normally an internal function will be used to decide where to break the line.
521If you want to do it in a different way set the 'formatexpr' option to an
522expression that will take care of the line break.
523
Bram Moolenaar071d4272004-06-13 20:20:40 +0000524If you want to format a block of text, you can use the "gq" operator. Type
525"gq" and a movement command to move the cursor to the end of the block. In
526many cases, the command "gq}" will do what you want (format until the end of
527paragraph). Alternatively, you can use "gqap", which will format the whole
528paragraph, no matter where the cursor currently is. Or you can use Visual
529mode: hit "v", move to the end of the block, and type "gq". See also |gq|.
530
531==============================================================================
5324. 'expandtab', 'smarttab' and 'softtabstop' options *ins-expandtab*
533
534If the 'expandtab' option is on, spaces will be used to fill the amount of
535whitespace of the tab. If you want to enter a real <Tab>, type CTRL-V first
536(use CTRL-Q when CTRL-V is mapped |i_CTRL-Q|).
537The 'expandtab' option is off by default. Note that in Replace mode, a single
538character is replaced with several spaces. The result of this is that the
539number of characters in the line increases. Backspacing will delete one
540space at a time. The original character will be put back for only one space
Bram Moolenaar25c9c682019-05-05 18:13:34 +0200541that you backspace over (the last one).
Bram Moolenaar071d4272004-06-13 20:20:40 +0000542
543 *ins-smarttab*
544When the 'smarttab' option is on, a <Tab> inserts 'shiftwidth' positions at
545the beginning of a line and 'tabstop' positions in other places. This means
Bram Moolenaar30b65812012-07-12 22:01:11 +0200546that often spaces instead of a <Tab> character are inserted. When 'smarttab'
Bram Moolenaar071d4272004-06-13 20:20:40 +0000547is off, a <Tab> always inserts 'tabstop' positions, and 'shiftwidth' is only
Bram Moolenaar25c9c682019-05-05 18:13:34 +0200548used for ">>" and the like.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000549
550 *ins-softtabstop*
551When the 'softtabstop' option is non-zero, a <Tab> inserts 'softtabstop'
552positions, and a <BS> used to delete white space, will delete 'softtabstop'
553positions. This feels like 'tabstop' was set to 'softtabstop', but a real
554<Tab> character still takes 'tabstop' positions, so your file will still look
555correct when used by other applications.
556
557If 'softtabstop' is non-zero, a <BS> will try to delete as much white space to
558move to the previous 'softtabstop' position, except when the previously
559inserted character is a space, then it will only delete the character before
560the cursor. Otherwise you cannot always delete a single character before the
561cursor. You will have to delete 'softtabstop' characters first, and then type
562extra spaces to get where you want to be.
563
564==============================================================================
5655. Replace mode *Replace* *Replace-mode* *mode-replace*
566
567Enter Replace mode with the "R" command in normal mode.
568
569In Replace mode, one character in the line is deleted for every character you
570type. If there is no character to delete (at the end of the line), the
571typed character is appended (as in Insert mode). Thus the number of
572characters in a line stays the same until you get to the end of the line.
573If a <NL> is typed, a line break is inserted and no character is deleted.
574
575Be careful with <Tab> characters. If you type a normal printing character in
576its place, the number of characters is still the same, but the number of
577columns will become smaller.
578
579If you delete characters in Replace mode (with <BS>, CTRL-W, or CTRL-U), what
580happens is that you delete the changes. The characters that were replaced
581are restored. If you had typed past the existing text, the characters you
582added are deleted. This is effectively a character-at-a-time undo.
583
584If the 'expandtab' option is on, a <Tab> will replace one character with
585several spaces. The result of this is that the number of characters in the
586line increases. Backspacing will delete one space at a time. The original
587character will be put back for only one space that you backspace over (the
Bram Moolenaar25c9c682019-05-05 18:13:34 +0200588last one).
Bram Moolenaar071d4272004-06-13 20:20:40 +0000589
590==============================================================================
5916. Virtual Replace mode *vreplace-mode* *Virtual-Replace-mode*
592
593Enter Virtual Replace mode with the "gR" command in normal mode.
Bram Moolenaardb84e452010-08-15 13:50:43 +0200594{not available when compiled without the |+vreplace| feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +0000595
596Virtual Replace mode is similar to Replace mode, but instead of replacing
597actual characters in the file, you are replacing screen real estate, so that
598characters further on in the file never appear to move.
599
600So if you type a <Tab> it may replace several normal characters, and if you
601type a letter on top of a <Tab> it may not replace anything at all, since the
602<Tab> will still line up to the same place as before.
603
604Typing a <NL> still doesn't cause characters later in the file to appear to
605move. The rest of the current line will be replaced by the <NL> (that is,
606they are deleted), and replacing continues on the next line. A new line is
607NOT inserted unless you go past the end of the file.
608
609Interesting effects are seen when using CTRL-T and CTRL-D. The characters
610before the cursor are shifted sideways as normal, but characters later in the
611line still remain still. CTRL-T will hide some of the old line under the
612shifted characters, but CTRL-D will reveal them again.
613
614As with Replace mode, using <BS> etc will bring back the characters that were
615replaced. This still works in conjunction with 'smartindent', CTRL-T and
616CTRL-D, 'expandtab', 'smarttab', 'softtabstop', etc.
617
618In 'list' mode, Virtual Replace mode acts as if it was not in 'list' mode,
619unless "L" is in 'cpoptions'.
620
Bram Moolenaar24ea3ba2010-09-19 19:01:21 +0200621Note that the only situations for which characters beyond the cursor should
622appear to move are in List mode |'list'|, and occasionally when 'wrap' is set
623(and the line changes length to become shorter or wider than the width of the
624screen). In other cases spaces may be inserted to avoid following characters
625to move.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000626
627This mode is very useful for editing <Tab> separated columns in tables, for
628entering new data while keeping all the columns aligned.
629
630==============================================================================
6317. Insert mode completion *ins-completion*
632
Bram Moolenaar4be06f92005-07-29 22:36:03 +0000633In Insert and Replace mode, there are several commands to complete part of a
Bram Moolenaar071d4272004-06-13 20:20:40 +0000634keyword or line that has been typed. This is useful if you are using
635complicated keywords (e.g., function names with capitals and underscores).
636
Bram Moolenaar071d4272004-06-13 20:20:40 +0000637Completion can be done for:
638
6391. Whole lines |i_CTRL-X_CTRL-L|
6402. keywords in the current file |i_CTRL-X_CTRL-N|
6413. keywords in 'dictionary' |i_CTRL-X_CTRL-K|
6424. keywords in 'thesaurus', thesaurus-style |i_CTRL-X_CTRL-T|
6435. keywords in the current and included files |i_CTRL-X_CTRL-I|
6446. tags |i_CTRL-X_CTRL-]|
6457. file names |i_CTRL-X_CTRL-F|
6468. definitions or macros |i_CTRL-X_CTRL-D|
6479. Vim command-line |i_CTRL-X_CTRL-V|
Bram Moolenaar4be06f92005-07-29 22:36:03 +000064810. User defined completion |i_CTRL-X_CTRL-U|
Bram Moolenaarf75a9632005-09-13 21:20:47 +000064911. omni completion |i_CTRL-X_CTRL-O|
Bram Moolenaar488c6512005-08-11 20:09:58 +000065012. Spelling suggestions |i_CTRL-X_s|
Bram Moolenaar6aa8cea2017-06-05 14:44:35 +020065113. keywords in 'complete' |i_CTRL-N| |i_CTRL-P|
glepnird5fdfa52025-06-02 19:45:41 +020065214. contents from registers |i_CTRL-X_CTRL-R|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000653
zeertzjqdca29d92021-08-31 19:12:51 +0200654Additionally, |i_CTRL-X_CTRL-Z| stops completion without changing the text.
655
Bram Moolenaar6aa8cea2017-06-05 14:44:35 +0200656All these, except CTRL-N and CTRL-P, are done in CTRL-X mode. This is a
657sub-mode of Insert and Replace modes. You enter CTRL-X mode by typing CTRL-X
658and one of the CTRL-X commands. You exit CTRL-X mode by typing a key that is
659not a valid CTRL-X mode command. Valid keys are the CTRL-X command itself,
660CTRL-N (next), and CTRL-P (previous).
Bram Moolenaar071d4272004-06-13 20:20:40 +0000661
Bram Moolenaarfd133322019-03-29 12:20:27 +0100662To get the current completion information, |complete_info()| can be used.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000663Also see the 'infercase' option if you want to adjust the case of the match.
664
glepnirfaf41122025-02-14 17:57:52 +0100665When inserting a selected candidate word from the |popup-menu|, the part of
666the candidate word that does not match the query is highlighted using
zeertzjqd6c79132025-03-09 16:14:45 +0100667|hl-ComplMatchIns|. If fuzzy is enabled in 'completeopt', highlighting will
668not be applied.
glepnirfaf41122025-02-14 17:57:52 +0100669
Bram Moolenaard2cec5b2006-03-28 21:08:56 +0000670 *complete_CTRL-E*
671When completion is active you can use CTRL-E to stop it and go back to the
Bram Moolenaar551dbcc2006-04-25 22:13:59 +0000672originally typed text. The CTRL-E will not be inserted.
Bram Moolenaard2cec5b2006-03-28 21:08:56 +0000673
674 *complete_CTRL-Y*
675When the popup menu is displayed you can use CTRL-Y to stop completion and
676accept the currently selected entry. The CTRL-Y is not inserted. Typing a
677space, Enter, or some other unprintable character will leave completion mode
678and insert that typed character.
679
Bram Moolenaar9e54a0e2006-04-14 20:42:25 +0000680When the popup menu is displayed there are a few more special keys, see
681|popupmenu-keys|.
682
Bram Moolenaar071d4272004-06-13 20:20:40 +0000683Note: The keys that are valid in CTRL-X mode are not mapped. This allows for
Bram Moolenaarf269eab2022-10-03 18:04:35 +0100684`:map <C-F> <C-X><C-F>` to work (assuming "<" is not in 'cpo'). The key that
Bram Moolenaar071d4272004-06-13 20:20:40 +0000685ends CTRL-X mode (any key that is not a valid CTRL-X mode command) is mapped.
686Also, when doing completion with 'complete' mappings apply as usual.
687
zeertzjqcfe45652022-05-27 17:26:55 +0100688 *E565*
Bram Moolenaarff06f282020-04-21 22:01:14 +0200689Note: While completion is active Insert mode can't be used recursively and
690buffer text cannot be changed. Mappings that somehow invoke ":normal i.."
691will generate an E565 error.
Bram Moolenaarf193fff2006-04-27 00:02:13 +0000692
Bram Moolenaar071d4272004-06-13 20:20:40 +0000693The following mappings are suggested to make typing the completion commands
Bram Moolenaarf269eab2022-10-03 18:04:35 +0100694a bit easier (although they will hide other commands; this requires "<" is not
695in 'cpo'): >
696 :inoremap <C-]> <C-X><C-]>
697 :inoremap <C-F> <C-X><C-F>
698 :inoremap <C-D> <C-X><C-D>
699 :inoremap <C-L> <C-X><C-L>
Bram Moolenaar071d4272004-06-13 20:20:40 +0000700
701As a special case, typing CTRL-R to perform register insertion (see
702|i_CTRL-R|) will not exit CTRL-X mode. This is primarily to allow the use of
703the '=' register to call some function to determine the next operation. If
704the contents of the register (or result of the '=' register evaluation) are
705not valid CTRL-X mode keys, then CTRL-X mode will be exited as if those keys
706had been typed.
707
708For example, the following will map <Tab> to either actually insert a <Tab> if
709the current line is currently only whitespace, or start/continue a CTRL-N
710completion operation: >
711
712 function! CleverTab()
713 if strpart( getline('.'), 0, col('.')-1 ) =~ '^\s*$'
714 return "\<Tab>"
715 else
716 return "\<C-N>"
Bram Moolenaarb52073a2010-03-17 20:02:06 +0100717 endif
Bram Moolenaar071d4272004-06-13 20:20:40 +0000718 endfunction
719 inoremap <Tab> <C-R>=CleverTab()<CR>
720
721
722
723Completing whole lines *compl-whole-line*
724
725 *i_CTRL-X_CTRL-L*
726CTRL-X CTRL-L Search backwards for a line that starts with the
Bram Moolenaar83bab712005-08-01 21:58:57 +0000727 same characters as those in the current line before
728 the cursor. Indent is ignored. The matching line is
Bram Moolenaar071d4272004-06-13 20:20:40 +0000729 inserted in front of the cursor.
Bram Moolenaar83bab712005-08-01 21:58:57 +0000730 The 'complete' option is used to decide which buffers
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +0000731 are searched for a match. Both loaded and unloaded
732 buffers are used.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000733 CTRL-L or
734 CTRL-P Search backwards for next matching line. This line
735 replaces the previous matching line.
736
737 CTRL-N Search forward for next matching line. This line
738 replaces the previous matching line.
739
740 CTRL-X CTRL-L After expanding a line you can additionally get the
741 line next to it by typing CTRL-X CTRL-L again, unless
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100742 a double CTRL-X is used. Only works for loaded
743 buffers.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000744
745Completing keywords in current file *compl-current*
746
747 *i_CTRL-X_CTRL-P*
748 *i_CTRL-X_CTRL-N*
749CTRL-X CTRL-N Search forwards for words that start with the keyword
750 in front of the cursor. The found keyword is inserted
751 in front of the cursor.
752
753CTRL-X CTRL-P Search backwards for words that start with the keyword
754 in front of the cursor. The found keyword is inserted
755 in front of the cursor.
756
757 CTRL-N Search forward for next matching keyword. This
758 keyword replaces the previous matching keyword.
759
760 CTRL-P Search backwards for next matching keyword. This
761 keyword replaces the previous matching keyword.
762
763 CTRL-X CTRL-N or
764 CTRL-X CTRL-P Further use of CTRL-X CTRL-N or CTRL-X CTRL-P will
765 copy the words following the previous expansion in
766 other contexts unless a double CTRL-X is used.
767
768If there is a keyword in front of the cursor (a name made out of alphabetic
769characters and characters in 'iskeyword'), it is used as the search pattern,
770with "\<" prepended (meaning: start of a word). Otherwise "\<\k\k" is used
771as search pattern (start of any keyword of at least two characters).
772
773In Replace mode, the number of characters that are replaced depends on the
774length of the matched string. This works like typing the characters of the
775matched string in Replace mode.
776
777If there is not a valid keyword character before the cursor, any keyword of
778at least two characters is matched.
779 e.g., to get:
780 printf("(%g, %g, %g)", vector[0], vector[1], vector[2]);
781 just type:
782 printf("(%g, %g, %g)", vector[0], ^P[1], ^P[2]);
783
Bram Moolenaarf75a9632005-09-13 21:20:47 +0000784The search wraps around the end of the file, the value of 'wrapscan' is not
785used here.
786
Bram Moolenaar071d4272004-06-13 20:20:40 +0000787Multiple repeats of the same completion are skipped; thus a different match
788will be inserted at each CTRL-N and CTRL-P (unless there is only one
789matching keyword).
790
791Single character matches are never included, as they usually just get in
792the way of what you were really after.
793 e.g., to get:
794 printf("name = %s\n", name);
795 just type:
796 printf("name = %s\n", n^P);
797 or even:
798 printf("name = %s\n", ^P);
799The 'n' in '\n' is skipped.
800
801After expanding a word, you can use CTRL-X CTRL-P or CTRL-X CTRL-N to get the
802word following the expansion in other contexts. These sequences search for
803the text just expanded and further expand by getting an extra word. This is
804useful if you need to repeat a sequence of complicated words. Although CTRL-P
805and CTRL-N look just for strings of at least two characters, CTRL-X CTRL-P and
806CTRL-X CTRL-N can be used to expand words of just one character.
807 e.g., to get:
808 M&eacute;xico
809 you can type:
810 M^N^P^X^P^X^P
811CTRL-N starts the expansion and then CTRL-P takes back the single character
812"M", the next two CTRL-X CTRL-P's get the words "&eacute" and ";xico".
813
814If the previous expansion was split, because it got longer than 'textwidth',
815then just the text in the current line will be used.
816
817If the match found is at the end of a line, then the first word in the next
Bram Moolenaar46eea442022-03-30 10:51:39 +0100818line will be inserted and the message "Word from other line" displayed, if
Bram Moolenaar071d4272004-06-13 20:20:40 +0000819this word is accepted the next CTRL-X CTRL-P or CTRL-X CTRL-N will search
820for those lines starting with this word.
821
822
823Completing keywords in 'dictionary' *compl-dictionary*
824
825 *i_CTRL-X_CTRL-K*
826CTRL-X CTRL-K Search the files given with the 'dictionary' option
827 for words that start with the keyword in front of the
828 cursor. This is like CTRL-N, but only the dictionary
829 files are searched, not the current file. The found
830 keyword is inserted in front of the cursor. This
831 could potentially be pretty slow, since all matches
832 are found before the first match is used. By default,
833 the 'dictionary' option is empty.
834 For suggestions where to find a list of words, see the
835 'dictionary' option.
Bram Moolenaar1588bc82022-03-08 21:35:07 +0000836 'ignorecase', 'smartcase' and 'infercase' apply.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000837
838 CTRL-K or
839 CTRL-N Search forward for next matching keyword. This
840 keyword replaces the previous matching keyword.
841
842 CTRL-P Search backwards for next matching keyword. This
843 keyword replaces the previous matching keyword.
844
Bram Moolenaarf4d8b762021-10-17 14:13:09 +0100845
846Completing words in 'thesaurus' *compl-thesaurus*
847
Bram Moolenaar071d4272004-06-13 20:20:40 +0000848 *i_CTRL-X_CTRL-T*
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000849CTRL-X CTRL-T Works as CTRL-X CTRL-K, but in a special way. It uses
Bram Moolenaar071d4272004-06-13 20:20:40 +0000850 the 'thesaurus' option instead of 'dictionary'. If a
851 match is found in the thesaurus file, all the
852 remaining words on the same line are included as
853 matches, even though they don't complete the word.
854 Thus a word can be completely replaced.
855
Bram Moolenaar071d4272004-06-13 20:20:40 +0000856 CTRL-T or
857 CTRL-N Search forward for next matching keyword. This
858 keyword replaces the previous matching keyword.
859
860 CTRL-P Search backwards for next matching keyword. This
861 keyword replaces the previous matching keyword.
862
Bram Moolenaarf4d8b762021-10-17 14:13:09 +0100863In the file used by the 'thesaurus' option each line in the file should
864contain words with similar meaning, separated by non-keyword characters (white
865space is preferred). Maximum line length is 510 bytes.
866
867For an example, imagine the 'thesaurus' file has a line like this: >
868 angry furious mad enraged
Bram Moolenaar2f0936c2022-01-08 21:51:59 +0000869Placing the cursor after the letters "ang" and typing CTRL-X CTRL-T would
Bram Moolenaarf4d8b762021-10-17 14:13:09 +0100870complete the word "angry"; subsequent presses would change the word to
871"furious", "mad" etc.
872
873Other uses include translation between two languages, or grouping API
874functions by keyword.
875
876An English word list was added to this github issue:
877https://github.com/vim/vim/issues/629#issuecomment-443293282
878Unpack thesaurus_pkg.zip, put the thesaurus.txt file somewhere, e.g.
879~/.vim/thesaurus/english.txt, and the 'thesaurus' option to this file name.
880
Bram Moolenaar2f0936c2022-01-08 21:51:59 +0000881
Bram Moolenaarf4d8b762021-10-17 14:13:09 +0100882Completing keywords with 'thesaurusfunc' *compl-thesaurusfunc*
883
884If the 'thesaurusfunc' option is set, then the user specified function is
885invoked to get the list of completion matches and the 'thesaurus' option is
886not used. See |complete-functions| for an explanation of how the function is
887invoked and what it should return.
888
889Here is an example that uses the "aiksaurus" command (provided by Magnus
890Groß): >
891
Bram Moolenaar113cb512021-11-07 20:27:04 +0000892 func Thesaur(findstart, base)
893 if a:findstart
Bram Moolenaar938ae282023-02-20 20:44:55 +0000894 return searchpos('\<', 'bnW', line('.'))[1] - 1
Bram Moolenaar113cb512021-11-07 20:27:04 +0000895 endif
896 let res = []
897 let h = ''
Bram Moolenaarc51cf032022-02-26 12:25:45 +0000898 for l in systemlist('aiksaurus ' .. shellescape(a:base))
Bram Moolenaar113cb512021-11-07 20:27:04 +0000899 if l[:3] == '=== '
Bram Moolenaarc51cf032022-02-26 12:25:45 +0000900 let h = '(' .. substitute(l[4:], ' =*$', ')', '')
Bram Moolenaar113cb512021-11-07 20:27:04 +0000901 elseif l ==# 'Alphabetically similar known words are: '
902 let h = "\U0001f52e"
903 elseif l[0] =~ '\a' || (h ==# "\U0001f52e" && l[0] ==# "\t")
904 call extend(res, map(split(substitute(l, '^\t', '', ''), ', '), {_, val -> {'word': val, 'menu': h}}))
Bram Moolenaarf4d8b762021-10-17 14:13:09 +0100905 endif
Bram Moolenaar113cb512021-11-07 20:27:04 +0000906 endfor
907 return res
908 endfunc
Bram Moolenaarb59ae592022-11-23 23:46:31 +0000909
Bram Moolenaar113cb512021-11-07 20:27:04 +0000910 if exists('+thesaurusfunc')
911 set thesaurusfunc=Thesaur
912 endif
Bram Moolenaarf4d8b762021-10-17 14:13:09 +0100913
Bram Moolenaar071d4272004-06-13 20:20:40 +0000914
915Completing keywords in the current and included files *compl-keyword*
916
917The 'include' option is used to specify a line that contains an include file
918name. The 'path' option is used to search for include files.
919
920 *i_CTRL-X_CTRL-I*
921CTRL-X CTRL-I Search for the first keyword in the current and
922 included files that starts with the same characters
923 as those before the cursor. The matched keyword is
924 inserted in front of the cursor.
925
926 CTRL-N Search forwards for next matching keyword. This
927 keyword replaces the previous matching keyword.
928 Note: CTRL-I is the same as <Tab>, which is likely to
929 be typed after a successful completion, therefore
930 CTRL-I is not used for searching for the next match.
931
932 CTRL-P Search backward for previous matching keyword. This
933 keyword replaces the previous matching keyword.
934
935 CTRL-X CTRL-I Further use of CTRL-X CTRL-I will copy the words
936 following the previous expansion in other contexts
937 unless a double CTRL-X is used.
938
939Completing tags *compl-tag*
940 *i_CTRL-X_CTRL-]*
941CTRL-X CTRL-] Search for the first tag that starts with the same
942 characters as before the cursor. The matching tag is
943 inserted in front of the cursor. Alphabetic
944 characters and characters in 'iskeyword' are used
945 to decide which characters are included in the tag
946 name (same as for a keyword). See also |CTRL-]|.
947 The 'showfulltag' option can be used to add context
948 from around the tag definition.
949 CTRL-] or
950 CTRL-N Search forwards for next matching tag. This tag
951 replaces the previous matching tag.
952
953 CTRL-P Search backward for previous matching tag. This tag
954 replaces the previous matching tag.
955
956
957Completing file names *compl-filename*
958 *i_CTRL-X_CTRL-F*
959CTRL-X CTRL-F Search for the first file name that starts with the
960 same characters as before the cursor. The matching
961 file name is inserted in front of the cursor.
962 Alphabetic characters and characters in 'isfname'
963 are used to decide which characters are included in
964 the file name. Note: the 'path' option is not used
965 here (yet).
966 CTRL-F or
967 CTRL-N Search forwards for next matching file name. This
968 file name replaces the previous matching file name.
969
970 CTRL-P Search backward for previous matching file name.
971 This file name replaces the previous matching file
972 name.
973
974
975Completing definitions or macros *compl-define*
976
977The 'define' option is used to specify a line that contains a definition.
978The 'include' option is used to specify a line that contains an include file
979name. The 'path' option is used to search for include files.
980
981 *i_CTRL-X_CTRL-D*
982CTRL-X CTRL-D Search in the current and included files for the
983 first definition (or macro) name that starts with
984 the same characters as before the cursor. The found
985 definition name is inserted in front of the cursor.
986 CTRL-D or
987 CTRL-N Search forwards for next matching macro name. This
988 macro name replaces the previous matching macro
989 name.
990
991 CTRL-P Search backward for previous matching macro name.
992 This macro name replaces the previous matching macro
993 name.
994
995 CTRL-X CTRL-D Further use of CTRL-X CTRL-D will copy the words
996 following the previous expansion in other contexts
997 unless a double CTRL-X is used.
998
999
1000Completing Vim commands *compl-vim*
1001
1002Completion is context-sensitive. It works like on the Command-line. It
Bram Moolenaar4be06f92005-07-29 22:36:03 +00001003completes an Ex command as well as its arguments. This is useful when writing
1004a Vim script.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001005
1006 *i_CTRL-X_CTRL-V*
1007CTRL-X CTRL-V Guess what kind of item is in front of the cursor and
1008 find the first match for it.
1009 Note: When CTRL-V is mapped you can often use CTRL-Q
Bram Moolenaar3577c6f2008-06-24 21:16:56 +00001010 instead of |i_CTRL-Q|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001011 CTRL-V or
1012 CTRL-N Search forwards for next match. This match replaces
1013 the previous one.
1014
Bram Moolenaar3577c6f2008-06-24 21:16:56 +00001015 CTRL-P Search backwards for previous match. This match
Bram Moolenaar071d4272004-06-13 20:20:40 +00001016 replaces the previous one.
1017
1018 CTRL-X CTRL-V Further use of CTRL-X CTRL-V will do the same as
1019 CTRL-V. This allows mapping a key to do Vim command
1020 completion, for example: >
1021 :imap <Tab> <C-X><C-V>
1022
glepnir05460682025-05-26 18:23:27 +02001023
glepnird5fdfa52025-06-02 19:45:41 +02001024Completing contents from registers *compl-register-words*
glepnir05460682025-05-26 18:23:27 +02001025 *i_CTRL-X_CTRL-R*
1026CTRL-X CTRL-R Guess what kind of item is in front of the cursor from
1027 all registers and find the first match for it.
1028 Further use of CTRL-R (without CTRL-X) will insert the
1029 register content, see |i_CTRL-R|.
1030 'ignorecase' applies to the matching.
1031
1032 CTRL-N Search forwards for next match. This match replaces
1033 the previous one.
1034
1035 CTRL-P Search backwards for previous match. This match
1036 replaces the previous one.
1037
glepnird5fdfa52025-06-02 19:45:41 +02001038 CTRL-X CTRL-R Further use of CTRL-X CTRL-R will copy the line
1039 following the previous expansion in other contexts
1040 unless a double CTRL-X is used (e.g. this switches
1041 from completing register words to register contents).
1042
Bram Moolenaar4be06f92005-07-29 22:36:03 +00001043User defined completion *compl-function*
Bram Moolenaarcfbc5ee2004-07-02 15:38:35 +00001044
1045Completion is done by a function that can be defined by the user with the
Bram Moolenaar280f1262006-01-30 00:14:18 +00001046'completefunc' option. See below for how the function is called and an
1047example |complete-functions|.
Bram Moolenaarcfbc5ee2004-07-02 15:38:35 +00001048
1049 *i_CTRL-X_CTRL-U*
1050CTRL-X CTRL-U Guess what kind of item is in front of the cursor and
1051 find the first match for it.
1052 CTRL-U or
1053 CTRL-N Use the next match. This match replaces the previous
1054 one.
1055
1056 CTRL-P Use the previous match. This match replaces the
1057 previous one.
1058
1059
Bram Moolenaarf75a9632005-09-13 21:20:47 +00001060Omni completion *compl-omni*
Bram Moolenaar4be06f92005-07-29 22:36:03 +00001061
Bram Moolenaare344bea2005-09-01 20:46:49 +00001062Completion is done by a function that can be defined by the user with the
Bram Moolenaarf75a9632005-09-13 21:20:47 +00001063'omnifunc' option. This is to be used for filetype-specific completion.
Bram Moolenaare344bea2005-09-01 20:46:49 +00001064
Bram Moolenaar280f1262006-01-30 00:14:18 +00001065See below for how the function is called and an example |complete-functions|.
Bram Moolenaarf75a9632005-09-13 21:20:47 +00001066For remarks about specific filetypes see |compl-omni-filetypes|.
Bram Moolenaar9c102382006-05-03 21:26:49 +00001067More completion scripts will appear, check www.vim.org. Currently there is a
1068first version for C++.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00001069
1070 *i_CTRL-X_CTRL-O*
1071CTRL-X CTRL-O Guess what kind of item is in front of the cursor and
1072 find the first match for it.
1073 CTRL-O or
1074 CTRL-N Use the next match. This match replaces the previous
1075 one.
1076
1077 CTRL-P Use the previous match. This match replaces the
1078 previous one.
1079
1080
Bram Moolenaar488c6512005-08-11 20:09:58 +00001081Spelling suggestions *compl-spelling*
1082
Bram Moolenaar5195e452005-08-19 20:32:47 +00001083A word before or at the cursor is located and correctly spelled words are
1084suggested to replace it. If there is a badly spelled word in the line, before
1085or under the cursor, the cursor is moved to after it. Otherwise the word just
1086before the cursor is used for suggestions, even though it isn't badly spelled.
1087
Bram Moolenaar488c6512005-08-11 20:09:58 +00001088NOTE: CTRL-S suspends display in many Unix terminals. Use 's' instead. Type
1089CTRL-Q to resume displaying.
1090
1091 *i_CTRL-X_CTRL-S* *i_CTRL-X_s*
1092CTRL-X CTRL-S or
1093CTRL-X s Locate the word in front of the cursor and find the
1094 first spell suggestion for it.
1095 CTRL-S or
1096 CTRL-N Use the next suggestion. This replaces the previous
1097 one. Note that you can't use 's' here.
1098
1099 CTRL-P Use the previous suggestion. This replaces the
1100 previous one.
1101
1102
Bram Moolenaar071d4272004-06-13 20:20:40 +00001103Completing keywords from different sources *compl-generic*
1104
1105 *i_CTRL-N*
1106CTRL-N Find next match for words that start with the
1107 keyword in front of the cursor, looking in places
1108 specified with the 'complete' option. The found
1109 keyword is inserted in front of the cursor.
1110
1111 *i_CTRL-P*
1112CTRL-P Find previous match for words that start with the
1113 keyword in front of the cursor, looking in places
1114 specified with the 'complete' option. The found
1115 keyword is inserted in front of the cursor.
1116
1117 CTRL-N Search forward for next matching keyword. This
1118 keyword replaces the previous matching keyword.
1119
1120 CTRL-P Search backwards for next matching keyword. This
1121 keyword replaces the previous matching keyword.
1122
1123 CTRL-X CTRL-N or
1124 CTRL-X CTRL-P Further use of CTRL-X CTRL-N or CTRL-X CTRL-P will
1125 copy the words following the previous expansion in
1126 other contexts unless a double CTRL-X is used.
1127
Bram Moolenaar578b49e2005-09-10 19:22:57 +00001128
zeertzjqdca29d92021-08-31 19:12:51 +02001129Stop completion *compl-stop*
1130
1131 *i_CTRL-X_CTRL-Z*
1132CTRL-X CTRL-Z Stop completion without changing the text.
1133
1134
Bram Moolenaar280f1262006-01-30 00:14:18 +00001135FUNCTIONS FOR FINDING COMPLETIONS *complete-functions*
1136
Yegappan Lakshmanan160e9942021-10-16 15:41:29 +01001137This applies to 'completefunc', 'thesaurusfunc' and 'omnifunc'.
Bram Moolenaar280f1262006-01-30 00:14:18 +00001138
Bram Moolenaar8b6144b2006-02-08 09:20:24 +00001139The function is called in two different ways:
1140- First the function is called to find the start of the text to be completed.
1141- Later the function is called to actually find the matches.
Bram Moolenaar280f1262006-01-30 00:14:18 +00001142
1143On the first invocation the arguments are:
1144 a:findstart 1
1145 a:base empty
1146
Bram Moolenaar8b6144b2006-02-08 09:20:24 +00001147The function must return the column where the completion starts. It must be a
1148number between zero and the cursor column "col('.')". This involves looking
1149at the characters just before the cursor and including those characters that
1150could be part of the completed item. The text between this column and the
Bram Moolenaarfc65cab2018-08-28 22:58:02 +02001151cursor column will be replaced with the matches. If the returned value is
1152larger than the cursor column, the cursor column is used.
Bram Moolenaar8e52a592012-05-18 21:49:28 +02001153
Bram Moolenaarfc65cab2018-08-28 22:58:02 +02001154Negative return values:
Bram Moolenaar938ae282023-02-20 20:44:55 +00001155 -2 To cancel silently and stay in completion mode.
1156 -3 To cancel silently and leave completion mode.
Bram Moolenaarfc65cab2018-08-28 22:58:02 +02001157 Another negative value: completion starts at the cursor column
Bram Moolenaar280f1262006-01-30 00:14:18 +00001158
1159On the second invocation the arguments are:
1160 a:findstart 0
Bram Moolenaar8b6144b2006-02-08 09:20:24 +00001161 a:base the text with which matches should match; the text that was
Bram Moolenaar280f1262006-01-30 00:14:18 +00001162 located in the first call (can be empty)
1163
1164The function must return a List with the matching words. These matches
1165usually include the "a:base" text. When there are no matches return an empty
Bram Moolenaar90df4b92021-07-07 20:26:08 +02001166List. Note that the cursor may have moved since the first invocation, the
1167text may have been changed.
Bram Moolenaar5302d9e2011-09-14 17:55:08 +02001168
1169In order to return more information than the matching words, return a Dict
1170that contains the List. The Dict can have these items:
1171 words The List of matching words (mandatory).
1172 refresh A string to control re-invocation of the function
1173 (optional).
1174 The only value currently recognized is "always", the
1175 effect is that the function is called whenever the
1176 leading text is changed.
Bram Moolenaarcee9bc22019-01-11 13:02:23 +01001177
1178If you want to suppress the warning message for an empty result, return
Bram Moolenaar314dd792019-02-03 15:27:20 +01001179|v:none|. This is useful to implement asynchronous completion with
1180|complete()|.
Bram Moolenaarcee9bc22019-01-11 13:02:23 +01001181
Bram Moolenaar5302d9e2011-09-14 17:55:08 +02001182Other items are ignored.
1183
Bram Moolenaar560979e2020-02-04 22:53:05 +01001184For acting upon end of completion, see the |CompleteDonePre| and
1185|CompleteDone| autocommand event.
Bram Moolenaar30b65812012-07-12 22:01:11 +02001186
Bram Moolenaar5302d9e2011-09-14 17:55:08 +02001187For example, the function can contain this: >
1188 let matches = ... list of words ...
1189 return {'words': matches, 'refresh': 'always'}
1190<
Girish Palyacbe53192025-04-14 22:13:15 +02001191If looking for matches is time-consuming, |complete_check()| may be used to
1192maintain responsiveness.
1193
Bram Moolenaar5c4bab02006-03-10 21:37:46 +00001194 *complete-items*
Bram Moolenaar8b6144b2006-02-08 09:20:24 +00001195Each list item can either be a string or a Dictionary. When it is a string it
1196is used as the completion. When it is a Dictionary it can contain these
1197items:
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001198 word the text that will be inserted, mandatory
1199 abbr abbreviation of "word"; when not empty it is used in
1200 the menu instead of "word"
Bram Moolenaar8dff8182006-04-06 20:18:50 +00001201 menu extra text for the popup menu, displayed after "word"
1202 or "abbr"
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001203 info more information about the item, can be displayed in a
Bram Moolenaar62a0cb42019-08-18 16:35:23 +02001204 preview or popup window
Bram Moolenaar8b6144b2006-02-08 09:20:24 +00001205 kind single letter indicating the type of completion
Bram Moolenaar91170f82006-05-05 21:15:17 +00001206 icase when non-zero case is to be ignored when comparing
1207 items to be equal; when omitted zero is used, thus
1208 items that only differ in case are added
Bram Moolenaar73655cf2019-04-06 13:45:55 +02001209 equal when non-zero, always treat this item to be equal when
1210 comparing. Which means, "equal=1" disables filtering
1211 of this item.
Bram Moolenaar4a85b412006-04-23 22:40:29 +00001212 dup when non-zero this match will be added even when an
1213 item with the same word is already present.
Bram Moolenaar166af9b2010-11-16 20:34:40 +01001214 empty when non-zero this match will be added even when it is
1215 an empty string
Bram Moolenaar938ae282023-02-20 20:44:55 +00001216 user_data custom data which is associated with the item and
Bram Moolenaar08928322020-01-04 14:32:48 +01001217 available in |v:completed_item|; it can be any type;
1218 defaults to an empty string
glepnir0fe17f82024-10-08 22:26:44 +02001219 abbr_hlgroup an additional highlight group whose attributes are
zeertzjq41008522024-07-27 13:21:49 +02001220 combined with |hl-PmenuSel| and |hl-Pmenu| or
1221 |hl-PmenuMatchSel| and |hl-PmenuMatch| highlight
1222 attributes in the popup menu to apply cterm and gui
1223 properties (with higher priority) like strikethrough
glepnir0fe17f82024-10-08 22:26:44 +02001224 to the completion items abbreviation
glepnir38f99a12024-08-23 18:31:06 +02001225 kind_hlgroup an additional highlight group specifically for setting
1226 the highlight attributes of the completion kind. When
glepnir88a6dd02024-08-25 15:49:54 +02001227 this field is present, it will override the
1228 |hl-PmenuKind| highlight group, allowing for the
1229 customization of ctermfg and guifg properties for the
1230 completion kind
glepnird4088ed2024-12-31 10:55:22 +01001231 match See "matches" in |complete_info()|.
Bram Moolenaar8b6144b2006-02-08 09:20:24 +00001232
Bram Moolenaar73655cf2019-04-06 13:45:55 +02001233All of these except "icase", "equal", "dup" and "empty" must be a string. If
1234an item does not meet these requirements then an error message is given and
1235further items in the list are not used. You can mix string and Dictionary
1236items in the returned list.
Bram Moolenaar8b6144b2006-02-08 09:20:24 +00001237
1238The "menu" item is used in the popup menu and may be truncated, thus it should
Bram Moolenaar0b598c22006-03-11 21:22:53 +00001239be relatively short. The "info" item can be longer, it will be displayed in
Bram Moolenaar62a0cb42019-08-18 16:35:23 +02001240the preview window when "preview" appears in 'completeopt' or in a popup
1241window when "popup" appears in 'completeopt'. In the preview window the
1242"info" item will also remain displayed after the popup menu has been removed.
1243This is useful for function arguments. Use a single space for "info" to
1244remove existing text in the preview window. The size of the preview window is
1245three lines, but 'previewheight' is used when it has a value of 1 or 2.
1246
1247 *complete-popup*
1248When "popup" is in 'completeopt' a popup window is used to display the "info".
Bram Moolenaar06fe74a2019-08-31 16:20:32 +02001249Then the 'completepopup' option specifies the properties of the popup. This
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +01001250is used when the info popup is created. The option is a comma-separated list
Bram Moolenaar06fe74a2019-08-31 16:20:32 +02001251of values:
Bram Moolenaar62a0cb42019-08-18 16:35:23 +02001252 height maximum height of the popup
1253 width maximum width of the popup
Bram Moolenaar8fe10002019-09-11 22:56:44 +02001254 highlight highlight group of the popup (default is PmenuSel)
Bram Moolenaar258cef52019-08-21 17:29:29 +02001255 align "item" (default) or "menu"
1256 border "on" (default) or "off"
Bram Moolenaar62a0cb42019-08-18 16:35:23 +02001257Example: >
1258 :set completepopup=height:10,width:60,highlight:InfoPopup
Bram Moolenaar8b6144b2006-02-08 09:20:24 +00001259
Bram Moolenaar06fe74a2019-08-31 16:20:32 +02001260When the "align" value is "item" then the popup is positioned close to the
Bram Moolenaar258cef52019-08-21 17:29:29 +02001261selected item. Changing the selection will also move the popup. When "align"
1262is "menu" then the popup is aligned with the top of the menu if the menu is
1263below the text, and the bottom of the menu otherwise.
1264
Bram Moolenaar06fe74a2019-08-31 16:20:32 +02001265After the info popup is created it can be found with |popup_findinfo()| and
1266properties can be changed with |popup_setoptions()|.
1267
Bram Moolenaardca7abe2019-10-20 18:17:57 +02001268 *complete-popuphidden*
1269If the information for the popup is obtained asynchronously, use "popuphidden"
Bram Moolenaar91359012019-11-30 17:57:03 +01001270in 'completeopt'. The info popup will then be initially hidden and
Bram Moolenaardca7abe2019-10-20 18:17:57 +02001271|popup_show()| must be called once it has been filled with the info. This can
1272be done with a |CompleteChanged| autocommand, something like this: >
1273 set completeopt+=popuphidden
1274 au CompleteChanged * call UpdateCompleteInfo()
1275 func UpdateCompleteInfo()
1276 " Cancel any pending info fetch
1277 let item = v:event.completed_item
1278 " Start fetching info for the item then call ShowCompleteInfo(info)
1279 endfunc
1280 func ShowCompleteInfo(info)
1281 let id = popup_findinfo()
1282 if id
1283 call popup_settext(id, 'async info: ' .. a:info)
1284 call popup_show(id)
1285 endif
1286 endfunc
1287
1288< *complete-item-kind*
Bram Moolenaar8b6144b2006-02-08 09:20:24 +00001289The "kind" item uses a single letter to indicate the kind of completion. This
1290may be used to show the completion differently (different color or icon).
1291Currently these types can be used:
1292 v variable
1293 f function or method
Bram Moolenaar0b598c22006-03-11 21:22:53 +00001294 m member of a struct or class
1295 t typedef
1296 d #define or macro
Bram Moolenaar280f1262006-01-30 00:14:18 +00001297
1298When searching for matches takes some time call |complete_add()| to add each
1299match to the total list. These matches should then not appear in the returned
1300list! Call |complete_check()| now and then to allow the user to press a key
1301while still searching for matches. Stop searching when it returns non-zero.
1302
Bram Moolenaar6aa57292021-08-14 21:25:52 +02001303 *E840*
Bram Moolenaar166af9b2010-11-16 20:34:40 +01001304The function is allowed to move the cursor, it is restored afterwards.
1305The function is not allowed to move to another window or delete text.
Bram Moolenaar280f1262006-01-30 00:14:18 +00001306
1307An example that completes the names of the months: >
1308 fun! CompleteMonths(findstart, base)
1309 if a:findstart
1310 " locate the start of the word
1311 let line = getline('.')
1312 let start = col('.') - 1
1313 while start > 0 && line[start - 1] =~ '\a'
1314 let start -= 1
1315 endwhile
1316 return start
1317 else
1318 " find months matching with "a:base"
1319 let res = []
1320 for m in split("Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec")
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001321 if m =~ '^' .. a:base
Bram Moolenaar280f1262006-01-30 00:14:18 +00001322 call add(res, m)
1323 endif
1324 endfor
1325 return res
1326 endif
1327 endfun
1328 set completefunc=CompleteMonths
1329<
1330The same, but now pretending searching for matches is slow: >
1331 fun! CompleteMonths(findstart, base)
1332 if a:findstart
1333 " locate the start of the word
1334 let line = getline('.')
1335 let start = col('.') - 1
1336 while start > 0 && line[start - 1] =~ '\a'
1337 let start -= 1
1338 endwhile
1339 return start
1340 else
1341 " find months matching with "a:base"
1342 for m in split("Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec")
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001343 if m =~ '^' .. a:base
Bram Moolenaar280f1262006-01-30 00:14:18 +00001344 call complete_add(m)
1345 endif
1346 sleep 300m " simulate searching for next match
1347 if complete_check()
1348 break
1349 endif
1350 endfor
1351 return []
1352 endif
1353 endfun
1354 set completefunc=CompleteMonths
1355<
1356
Bram Moolenaar1c7715d2005-10-03 22:02:18 +00001357INSERT COMPLETION POPUP MENU *ins-completion-menu*
Bram Moolenaarebefac62005-12-28 22:39:57 +00001358 *popupmenu-completion*
Bram Moolenaar1c7715d2005-10-03 22:02:18 +00001359Vim can display the matches in a simplistic popup menu.
1360
1361The menu is used when:
Bram Moolenaara2031822006-03-07 22:29:51 +00001362- The 'completeopt' option contains "menu" or "menuone".
Bram Moolenaar1c7715d2005-10-03 22:02:18 +00001363- The terminal supports at least 8 colors.
Bram Moolenaard68071d2006-05-02 22:08:30 +00001364- There are at least two matches. One if "menuone" is used.
Bram Moolenaar1c7715d2005-10-03 22:02:18 +00001365
Bram Moolenaar56718732006-03-15 22:53:57 +00001366The 'pumheight' option can be used to set a maximum height. The default is to
1367use all space available.
Bram Moolenaar9b56a572018-02-10 16:19:32 +01001368The 'pumwidth' option can be used to set a minimum width. The default is 15
1369characters.
Bram Moolenaar56718732006-03-15 22:53:57 +00001370
Girish Palyadc314052025-05-08 23:28:52 +02001371 *compl-states*
Bram Moolenaar779b74b2006-04-10 14:55:34 +00001372There are three states:
13731. A complete match has been inserted, e.g., after using CTRL-N or CTRL-P.
13742. A cursor key has been used to select another match. The match was not
1375 inserted then, only the entry in the popup menu is highlighted.
13763. Only part of a match has been inserted and characters were typed or the
1377 backspace key was used. The list of matches was then adjusted for what is
1378 in front of the cursor.
Bram Moolenaarc7453f52006-02-10 23:20:28 +00001379
Bram Moolenaar80a94a52006-02-23 21:26:58 +00001380You normally start in the first state, with the first match being inserted.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001381When "longest" is in 'completeopt' and there is more than one match you start
Bram Moolenaar779b74b2006-04-10 14:55:34 +00001382in the third state.
Bram Moolenaarc7453f52006-02-10 23:20:28 +00001383
Bram Moolenaar779b74b2006-04-10 14:55:34 +00001384If you select another match, e.g., with CTRL-N or CTRL-P, you go to the first
1385state. This doesn't change the list of matches.
Bram Moolenaar80a94a52006-02-23 21:26:58 +00001386
Bram Moolenaar779b74b2006-04-10 14:55:34 +00001387When you are back at the original text then you are in the third state. To
Bram Moolenaara2031822006-03-07 22:29:51 +00001388get there right away you can use a mapping that uses CTRL-P right after
1389starting the completion: >
1390 :imap <F7> <C-N><C-P>
Bram Moolenaar76916e62006-03-21 21:23:25 +00001391<
1392 *popupmenu-keys*
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001393In the first state these keys have a special meaning:
1394<BS> and CTRL-H Delete one character, find the matches for the word before
1395 the cursor. This reduces the list of matches, often to one
Bram Moolenaar80a94a52006-02-23 21:26:58 +00001396 entry, and switches to the second state.
Bram Moolenaar779b74b2006-04-10 14:55:34 +00001397Any non-special character:
1398 Stop completion without changing the match and insert the
1399 typed character.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001400
Bram Moolenaar779b74b2006-04-10 14:55:34 +00001401In the second and third state these keys have a special meaning:
Bram Moolenaar8b6144b2006-02-08 09:20:24 +00001402<BS> and CTRL-H Delete one character, find the matches for the shorter word
1403 before the cursor. This may find more matches.
1404CTRL-L Add one character from the current match, may reduce the
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001405 number of matches.
Bram Moolenaar80a94a52006-02-23 21:26:58 +00001406any printable, non-white character:
1407 Add this character and reduce the number of matches.
Bram Moolenaarc7453f52006-02-10 23:20:28 +00001408
Bram Moolenaar779b74b2006-04-10 14:55:34 +00001409In all three states these can be used:
Bram Moolenaard2cec5b2006-03-28 21:08:56 +00001410CTRL-Y Yes: Accept the currently selected match and stop completion.
Bram Moolenaar9964e462007-05-05 17:54:07 +00001411CTRL-E End completion, go back to what was there before selecting a
1412 match (what was typed or longest common string).
Bram Moolenaar80a94a52006-02-23 21:26:58 +00001413<PageUp> Select a match several entries back, but don't insert it.
1414<PageDown> Select a match several entries further, but don't insert it.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001415<Up> Select the previous match, as if CTRL-P was used, but don't
Bram Moolenaar80a94a52006-02-23 21:26:58 +00001416 insert it.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001417<Down> Select the next match, as if CTRL-N was used, but don't
Bram Moolenaar80a94a52006-02-23 21:26:58 +00001418 insert it.
Bram Moolenaar9964e462007-05-05 17:54:07 +00001419<Space> or <Tab> Stop completion without changing the match and insert the
Bram Moolenaar779b74b2006-04-10 14:55:34 +00001420 typed character.
1421
Bram Moolenaar044b68f2007-05-10 17:39:52 +00001422The behavior of the <Enter> key depends on the state you are in:
Bram Moolenaar779b74b2006-04-10 14:55:34 +00001423first state: Use the text as it is and insert a line break.
1424second state: Insert the currently selected match.
1425third state: Use the text as it is and insert a line break.
1426
1427In other words: If you used the cursor keys to select another entry in the
Bram Moolenaar044b68f2007-05-10 17:39:52 +00001428list of matches then the <Enter> key inserts that match. If you typed
1429something else then <Enter> inserts a line break.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001430
Bram Moolenaar1c7715d2005-10-03 22:02:18 +00001431
1432The colors of the menu can be changed with these highlight groups:
1433Pmenu normal item |hl-Pmenu|
1434PmenuSel selected item |hl-PmenuSel|
1435PmenuSbar scrollbar |hl-PmenuSbar|
1436PmenuThumb thumb of the scrollbar |hl-PmenuThumb|
1437
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001438There are no special mappings for when the popup menu is visible. However,
1439you can use an Insert mode mapping that checks the |pumvisible()| function to
1440do something different. Example: >
1441 :inoremap <Down> <C-R>=pumvisible() ? "\<lt>C-N>" : "\<lt>Down>"<CR>
Bram Moolenaar1c7715d2005-10-03 22:02:18 +00001442
Bram Moolenaar5c4bab02006-03-10 21:37:46 +00001443You can use of <expr> in mapping to have the popup menu used when typing a
1444character and some condition is met. For example, for typing a dot: >
1445 inoremap <expr> . MayComplete()
1446 func MayComplete()
1447 if (can complete)
1448 return ".\<C-X>\<C-O>"
1449 endif
1450 return '.'
1451 endfunc
1452
1453See |:map-<expr>| for more info.
1454
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001455
1456FILETYPE-SPECIFIC REMARKS FOR OMNI COMPLETION *compl-omni-filetypes*
1457
1458The file used for {filetype} should be autoload/{filetype}complete.vim
1459in 'runtimepath'. Thus for "java" it is autoload/javacomplete.vim.
Bram Moolenaar578b49e2005-09-10 19:22:57 +00001460
Bram Moolenaara5792f52005-11-23 21:25:05 +00001461
Bram Moolenaarf75a9632005-09-13 21:20:47 +00001462C *ft-c-omni*
Bram Moolenaar578b49e2005-09-10 19:22:57 +00001463
Bram Moolenaar47c532e2022-03-19 15:18:53 +00001464Completion of C code requires a tags file. You should use Universal/
1465Exuberant ctags, because it adds extra information that is needed for
1466completion. You can find it here:
1467 Universal Ctags: https://ctags.io
1468 Exuberant Ctags: http://ctags.sourceforge.net
Bram Moolenaar9964e462007-05-05 17:54:07 +00001469
Bram Moolenaar47c532e2022-03-19 15:18:53 +00001470Universal Ctags is preferred, Exuberant Ctags is no longer being developed.
1471
1472For Exuberant ctags, version 5.6 or later is recommended. For version 5.5.4
1473you should add a patch that adds the "typename:" field:
Bram Moolenaar36fc5352006-03-04 21:49:37 +00001474 ftp://ftp.vim.org/pub/vim/unstable/patches/ctags-5.5.4.patch
Bram Moolenaar8b6144b2006-02-08 09:20:24 +00001475A compiled .exe for MS-Windows can be found at:
Bram Moolenaar2f058492017-11-30 20:27:52 +01001476 http://ctags.sourceforge.net/
1477 https://github.com/universal-ctags/ctags-win32
Bram Moolenaar578b49e2005-09-10 19:22:57 +00001478
1479If you want to complete system functions you can do something like this. Use
1480ctags to generate a tags file for all the system header files: >
1481 % ctags -R -f ~/.vim/systags /usr/include /usr/local/include
1482In your vimrc file add this tags file to the 'tags' option: >
1483 set tags+=~/.vim/systags
1484
1485When using CTRL-X CTRL-O after a name without any "." or "->" it is completed
1486from the tags file directly. This works for any identifier, also function
1487names. If you want to complete a local variable name, which does not appear
1488in the tags file, use CTRL-P instead.
1489
1490When using CTRL-X CTRL-O after something that has "." or "->" Vim will attempt
1491to recognize the type of the variable and figure out what members it has.
1492This means only members valid for the variable will be listed.
1493
Bram Moolenaarf75a9632005-09-13 21:20:47 +00001494When a member name already was complete, CTRL-X CTRL-O will add a "." or
1495"->" for composite types.
1496
Bram Moolenaar578b49e2005-09-10 19:22:57 +00001497Vim doesn't include a C compiler, only the most obviously formatted
1498declarations are recognized. Preprocessor stuff may cause confusion.
1499When the same structure name appears in multiple places all possible members
1500are included.
1501
Bram Moolenaar6b730e12005-09-16 21:47:57 +00001502
Bram Moolenaar4770d092006-01-12 23:22:24 +00001503CSS *ft-css-omni*
Bram Moolenaara5792f52005-11-23 21:25:05 +00001504
1505Complete properties and their appropriate values according to CSS 2.1
Bram Moolenaare2f98b92006-03-29 21:18:24 +00001506specification.
Bram Moolenaara5792f52005-11-23 21:25:05 +00001507
1508
Bram Moolenaare2f98b92006-03-29 21:18:24 +00001509HTML *ft-html-omni*
1510XHTML *ft-xhtml-omni*
Bram Moolenaar6b730e12005-09-16 21:47:57 +00001511
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001512CTRL-X CTRL-O provides completion of various elements of (X)HTML files. It is
Bram Moolenaardb6ea062014-07-10 22:01:47 +02001513designed to support writing of XHTML 1.0 Strict files but will also work for
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001514other versions of HTML. Features:
Bram Moolenaar6b730e12005-09-16 21:47:57 +00001515
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001516- after "<" complete tag name depending on context (no div suggestion inside
1517 of an a tag); '/>' indicates empty tags
1518- inside of tag complete proper attributes (no width attribute for an a tag);
1519 show also type of attribute; '*' indicates required attributes
1520- when attribute has limited number of possible values help to complete them
Bram Moolenaara5792f52005-11-23 21:25:05 +00001521- complete names of entities
Bram Moolenaar1e015462005-09-25 22:16:38 +00001522- complete values of "class" and "id" attributes with data obtained from
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001523 <style> tag and included CSS files
Bram Moolenaar8b6144b2006-02-08 09:20:24 +00001524- when completing value of "style" attribute or working inside of "style" tag
Bram Moolenaar1e015462005-09-25 22:16:38 +00001525 switch to |ft-css-omni| completion
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001526- when completing values of events attributes or working inside of "script"
1527 tag switch to |ft-javascript-omni| completion
Bram Moolenaar1e015462005-09-25 22:16:38 +00001528- when used after "</" CTRL-X CTRL-O will close the last opened tag
Bram Moolenaar6b730e12005-09-16 21:47:57 +00001529
Bram Moolenaara5792f52005-11-23 21:25:05 +00001530Note: When used first time completion menu will be shown with little delay
Bram Moolenaare2f98b92006-03-29 21:18:24 +00001531- this is time needed for loading of data file.
Bram Moolenaar8b6144b2006-02-08 09:20:24 +00001532Note: Completion may fail in badly formatted documents. In such case try to
1533run |:make| command to detect formatting problems.
Bram Moolenaara5792f52005-11-23 21:25:05 +00001534
1535
Bram Moolenaarc1e37902006-04-18 21:55:01 +00001536HTML flavor *html-flavor*
1537
Bram Moolenaar9c102382006-05-03 21:26:49 +00001538The default HTML completion depends on the filetype. For HTML files it is
1539HTML 4.01 Transitional ('filetype' is "html"), for XHTML it is XHTML 1.0
1540Strict ('filetype' is "xhtml").
Bram Moolenaarc1e37902006-04-18 21:55:01 +00001541
Bram Moolenaar9c102382006-05-03 21:26:49 +00001542When doing completion outside of any other tag you will have possibility to
1543choose DOCTYPE and the appropriate data file will be loaded and used for all
1544next completions.
Bram Moolenaarc1e37902006-04-18 21:55:01 +00001545
Bram Moolenaar9c102382006-05-03 21:26:49 +00001546More about format of data file in |xml-omni-datafile|. Some of the data files
1547may be found on the Vim website (|www|).
Bram Moolenaarc1e37902006-04-18 21:55:01 +00001548
Bram Moolenaar9c102382006-05-03 21:26:49 +00001549Note that b:html_omni_flavor may point to a file with any XML data. This
1550makes possible to mix PHP (|ft-php-omni|) completion with any XML dialect
1551(assuming you have data file for it). Without setting that variable XHTML 1.0
1552Strict will be used.
Bram Moolenaarc1e37902006-04-18 21:55:01 +00001553
1554
Bram Moolenaare2f98b92006-03-29 21:18:24 +00001555JAVASCRIPT *ft-javascript-omni*
Bram Moolenaarb8a7b562006-02-01 21:47:16 +00001556
Bram Moolenaar8b6144b2006-02-08 09:20:24 +00001557Completion of most elements of JavaScript language and DOM elements.
Bram Moolenaarb8a7b562006-02-01 21:47:16 +00001558
1559Complete:
1560
1561- variables
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001562- function name; show function arguments
Bram Moolenaarb8a7b562006-02-01 21:47:16 +00001563- function arguments
1564- properties of variables trying to detect type of variable
Bram Moolenaar8b6144b2006-02-08 09:20:24 +00001565- complete DOM objects and properties depending on context
Bram Moolenaarb8a7b562006-02-01 21:47:16 +00001566- keywords of language
1567
Bram Moolenaar8b6144b2006-02-08 09:20:24 +00001568Completion works in separate JavaScript files (&ft==javascript), inside of
1569<script> tag of (X)HTML and in values of event attributes (including scanning
Bram Moolenaar9ba7e172013-07-17 22:37:26 +02001570of external files).
Bram Moolenaare2f98b92006-03-29 21:18:24 +00001571
Bram Moolenaarb8a7b562006-02-01 21:47:16 +00001572DOM compatibility
1573
1574At the moment (beginning of 2006) there are two main browsers - MS Internet
1575Explorer and Mozilla Firefox. These two applications are covering over 90% of
1576market. Theoretically standards are created by W3C organisation
1577(http://www.w3c.org) but they are not always followed/implemented.
1578
Bram Moolenaare2f98b92006-03-29 21:18:24 +00001579 IE FF W3C Omni completion ~
1580 +/- +/- + + ~
1581 + + - + ~
1582 + - - - ~
1583 - + - - ~
Bram Moolenaarb8a7b562006-02-01 21:47:16 +00001584
1585Regardless from state of implementation in browsers but if element is defined
1586in standards, completion plugin will place element in suggestion list. When
1587both major engines implemented element, even if this is not in standards it
1588will be suggested. All other elements are not placed in suggestion list.
1589
1590
Bram Moolenaare2f98b92006-03-29 21:18:24 +00001591PHP *ft-php-omni*
Bram Moolenaar362e1a32006-03-06 23:29:24 +00001592
Bram Moolenaar9964e462007-05-05 17:54:07 +00001593Completion of PHP code requires a tags file for completion of data from
Bram Moolenaar47c532e2022-03-19 15:18:53 +00001594external files and for class aware completion. You should use Universal/
1595Exuberant ctags version 5.5.4 or newer. You can find it here:
1596
1597 Universal Ctags: https://ctags.io
1598 Exuberant Ctags: http://ctags.sourceforge.net
Bram Moolenaar362e1a32006-03-06 23:29:24 +00001599
1600Script completes:
1601
1602- after $ variables name
Bram Moolenaar0b598c22006-03-11 21:22:53 +00001603 - if variable was declared as object add "->", if tags file is available show
1604 name of class
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001605 - after "->" complete only function and variable names specific for given
1606 class. To find class location and contents tags file is required. Because
1607 PHP isn't strongly typed language user can use @var tag to declare class: >
1608
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001609 /* @var $myVar myClass */
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001610 $myVar->
1611<
1612 Still, to find myClass contents tags file is required.
Bram Moolenaar0b598c22006-03-11 21:22:53 +00001613
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00001614- function names with additional info:
Bram Moolenaar0b598c22006-03-11 21:22:53 +00001615 - in case of built-in functions list of possible arguments and after | type
1616 data returned by function
Bram Moolenaar06b5d512010-05-22 15:37:44 +02001617 - in case of user function arguments and name of file where function was
Bram Moolenaar0b598c22006-03-11 21:22:53 +00001618 defined (if it is not current file)
1619
1620- constants names
1621- class names after "new" declaration
1622
Bram Moolenaar362e1a32006-03-06 23:29:24 +00001623
1624Note: when doing completion first time Vim will load all necessary data into
1625memory. It may take several seconds. After next use of completion delay
Bram Moolenaar0b598c22006-03-11 21:22:53 +00001626should not be noticeable.
Bram Moolenaar362e1a32006-03-06 23:29:24 +00001627
1628Script detects if cursor is inside <?php ?> tags. If it is outside it will
1629automatically switch to HTML/CSS/JavaScript completion. Note: contrary to
1630original HTML files completion of tags (and only tags) isn't context aware.
1631
1632
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001633RUBY *ft-ruby-omni*
Bram Moolenaarfc1421e2006-04-20 22:17:20 +00001634
1635Completion of Ruby code requires that vim be built with |+ruby|.
1636
1637Ruby completion will parse your buffer on demand in order to provide a list of
1638completions. These completions will be drawn from modules loaded by 'require'
1639and modules defined in the current buffer.
1640
1641The completions provided by CTRL-X CTRL-O are sensitive to the context:
1642
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001643 CONTEXT COMPLETIONS PROVIDED ~
Bram Moolenaarfc1421e2006-04-20 22:17:20 +00001644
1645 1. Not inside a class definition Classes, constants and globals
1646
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001647 2. Inside a class definition Methods or constants defined in the class
Bram Moolenaarfc1421e2006-04-20 22:17:20 +00001648
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001649 3. After '.', '::' or ':' Methods applicable to the object being
1650 dereferenced
Bram Moolenaarfc1421e2006-04-20 22:17:20 +00001651
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001652 4. After ':' or ':foo' Symbol name (beginning with 'foo')
Bram Moolenaarfc1421e2006-04-20 22:17:20 +00001653
1654Notes:
1655 - Vim will load/evaluate code in order to provide completions. This may
Bram Moolenaar40962ec2018-01-28 22:47:25 +01001656 cause some code execution, which may be a concern. This is no longer
Bram Moolenaar9964e462007-05-05 17:54:07 +00001657 enabled by default, to enable this feature add >
1658 let g:rubycomplete_buffer_loading = 1
1659<- In context 1 above, Vim can parse the entire buffer to add a list of
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00001660 classes to the completion results. This feature is turned off by default,
1661 to enable it add >
1662 let g:rubycomplete_classes_in_global = 1
1663< to your vimrc
Bram Moolenaarfc1421e2006-04-20 22:17:20 +00001664 - In context 2 above, anonymous classes are not supported.
1665 - In context 3 above, Vim will attempt to determine the methods supported by
1666 the object.
1667 - Vim can detect and load the Rails environment for files within a rails
1668 project. The feature is disabled by default, to enable it add >
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00001669 let g:rubycomplete_rails = 1
1670< to your vimrc
Bram Moolenaarfc1421e2006-04-20 22:17:20 +00001671
1672
Bram Moolenaar4770d092006-01-12 23:22:24 +00001673SYNTAX *ft-syntax-omni*
1674
Bram Moolenaar9964e462007-05-05 17:54:07 +00001675Vim has the ability to color syntax highlight nearly 500 languages. Part of
1676this highlighting includes knowing what keywords are part of a language. Many
1677filetypes already have custom completion scripts written for them, the
1678syntaxcomplete plugin provides basic completion for all other filetypes. It
1679does this by populating the omni completion list with the text Vim already
1680knows how to color highlight. It can be used for any filetype and provides a
1681minimal language-sensitive completion.
Bram Moolenaar4770d092006-01-12 23:22:24 +00001682
Bram Moolenaarc06ac342006-03-02 22:43:39 +00001683To enable syntax code completion you can run: >
Bram Moolenaarec7944a2013-06-12 21:29:15 +02001684 setlocal omnifunc=syntaxcomplete#Complete
Bram Moolenaar4770d092006-01-12 23:22:24 +00001685
Bram Moolenaarec7944a2013-06-12 21:29:15 +02001686You can automate this by placing the following in your |.vimrc| (after any
Bram Moolenaarc06ac342006-03-02 22:43:39 +00001687":filetype" command): >
1688 if has("autocmd") && exists("+omnifunc")
Bram Moolenaare2f98b92006-03-29 21:18:24 +00001689 autocmd Filetype *
1690 \ if &omnifunc == "" |
1691 \ setlocal omnifunc=syntaxcomplete#Complete |
1692 \ endif
Bram Moolenaarc06ac342006-03-02 22:43:39 +00001693 endif
Bram Moolenaar4770d092006-01-12 23:22:24 +00001694
Bram Moolenaarc06ac342006-03-02 22:43:39 +00001695The above will set completion to this script only if a specific plugin does
1696not already exist for that filetype.
1697
1698Each filetype can have a wide range of syntax items. The plugin allows you to
1699customize which syntax groups to include or exclude from the list. Let's have
1700a look at the PHP filetype to see how this works.
1701
1702If you edit a file called, index.php, run the following command: >
Bram Moolenaarec7944a2013-06-12 21:29:15 +02001703 syntax list
Bram Moolenaarc06ac342006-03-02 22:43:39 +00001704
Bram Moolenaar06b5d512010-05-22 15:37:44 +02001705The first thing you will notice is that there are many different syntax groups.
1706The PHP language can include elements from different languages like HTML,
Bram Moolenaarc06ac342006-03-02 22:43:39 +00001707JavaScript and many more. The syntax plugin will only include syntax groups
1708that begin with the filetype, "php", in this case. For example these syntax
1709groups are included by default with the PHP: phpEnvVar, phpIntVar,
1710phpFunctions.
1711
Bram Moolenaar40962ec2018-01-28 22:47:25 +01001712If you wish non-filetype syntax items to also be included, you can use a
1713regular expression syntax (added in version 13.0 of
Bram Moolenaar6dc819b2018-07-03 16:42:19 +02001714autoload/syntaxcomplete.vim) to add items. Looking at the output from
Bram Moolenaar40962ec2018-01-28 22:47:25 +01001715":syntax list" while editing a PHP file I can see some of these entries: >
Bram Moolenaarec7944a2013-06-12 21:29:15 +02001716 htmlArg,htmlTag,htmlTagName,javaScriptStatement,javaScriptGlobalObjects
Bram Moolenaarc06ac342006-03-02 22:43:39 +00001717
Bram Moolenaarec7944a2013-06-12 21:29:15 +02001718To pick up any JavaScript and HTML keyword syntax groups while editing a PHP
Bram Moolenaar40962ec2018-01-28 22:47:25 +01001719file, you can use 3 different regexs, one for each language. Or you can
1720simply restrict the include groups to a particular value, without using
Bram Moolenaarec7944a2013-06-12 21:29:15 +02001721a regex string: >
1722 let g:omni_syntax_group_include_php = 'php\w\+,javaScript\w\+,html\w\+'
1723 let g:omni_syntax_group_include_php = 'phpFunctions,phpMethods'
1724<
1725The basic form of this variable is: >
1726 let g:omni_syntax_group_include_{filetype} = 'regex,comma,separated'
1727
1728The PHP language has an enormous number of items which it knows how to syntax
Bram Moolenaar9ba7e172013-07-17 22:37:26 +02001729highlight. These items will be available within the omni completion list.
Bram Moolenaarec7944a2013-06-12 21:29:15 +02001730
1731Some people may find this list unwieldy or are only interested in certain
1732items. There are two ways to prune this list (if necessary). If you find
Bram Moolenaar40962ec2018-01-28 22:47:25 +01001733certain syntax groups you do not wish displayed you can use two different
1734methods to identify these groups. The first specifically lists the syntax
1735groups by name. The second uses a regular expression to identify both
Bram Moolenaarec7944a2013-06-12 21:29:15 +02001736syntax groups. Simply add one the following to your vimrc: >
1737 let g:omni_syntax_group_exclude_php = 'phpCoreConstant,phpConstant'
1738 let g:omni_syntax_group_exclude_php = 'php\w*Constant'
Bram Moolenaarc06ac342006-03-02 22:43:39 +00001739
1740Add as many syntax groups to this list by comma separating them. The basic
1741form of this variable is: >
Bram Moolenaarec7944a2013-06-12 21:29:15 +02001742 let g:omni_syntax_group_exclude_{filetype} = 'regex,comma,separated'
Bram Moolenaarc06ac342006-03-02 22:43:39 +00001743
1744You can create as many of these variables as you need, varying only the
1745filetype at the end of the variable name.
Bram Moolenaar4770d092006-01-12 23:22:24 +00001746
Bram Moolenaar9964e462007-05-05 17:54:07 +00001747The plugin uses the isKeyword option to determine where word boundaries are
1748for the syntax items. For example, in the Scheme language completion should
1749include the "-", call-with-output-file. Depending on your filetype, this may
1750not provide the words you are expecting. Setting the
1751g:omni_syntax_use_iskeyword option to 0 will force the syntax plugin to break
1752on word characters. This can be controlled adding the following to your
1753vimrc: >
1754 let g:omni_syntax_use_iskeyword = 0
1755
Bram Moolenaar8b682772010-07-30 21:49:40 +02001756For plugin developers, the plugin exposes a public function OmniSyntaxList.
1757This function can be used to request a List of syntax items. When editing a
Bram Moolenaar40962ec2018-01-28 22:47:25 +01001758SQL file (:e syntax.sql) you can use the ":syntax list" command to see the
Bram Moolenaar8b682772010-07-30 21:49:40 +02001759various groups and syntax items. For example: >
Bram Moolenaar40962ec2018-01-28 22:47:25 +01001760 syntax list
Bram Moolenaar8b682772010-07-30 21:49:40 +02001761
Bram Moolenaar40962ec2018-01-28 22:47:25 +01001762Yields data similar to this:
1763 sqlOperator xxx some prior all like and any escape exists in is not ~
1764 or intersect minus between distinct ~
1765 links to Operator ~
1766 sqlType xxx varbit varchar nvarchar bigint int uniqueidentifier ~
1767 date money long tinyint unsigned xml text smalldate ~
1768 double datetime nchar smallint numeric time bit char ~
1769 varbinary binary smallmoney ~
1770 image float integer timestamp real decimal ~
Bram Moolenaar8b682772010-07-30 21:49:40 +02001771
1772There are two syntax groups listed here: sqlOperator and sqlType. To retrieve
Bram Moolenaar40962ec2018-01-28 22:47:25 +01001773a List of syntax items you can call OmniSyntaxList a number of different
Bram Moolenaar8b682772010-07-30 21:49:40 +02001774ways. To retrieve all syntax items regardless of syntax group: >
1775 echo OmniSyntaxList( [] )
1776
1777To retrieve only the syntax items for the sqlOperator syntax group: >
1778 echo OmniSyntaxList( ['sqlOperator'] )
1779
1780To retrieve all syntax items for both the sqlOperator and sqlType groups: >
1781 echo OmniSyntaxList( ['sqlOperator', 'sqlType'] )
1782
Bram Moolenaarec7944a2013-06-12 21:29:15 +02001783A regular expression can also be used: >
1784 echo OmniSyntaxList( ['sql\w\+'] )
1785
Bram Moolenaar8b682772010-07-30 21:49:40 +02001786From within a plugin, you would typically assign the output to a List: >
1787 let myKeywords = []
1788 let myKeywords = OmniSyntaxList( ['sqlKeyword'] )
1789
Bram Moolenaar4770d092006-01-12 23:22:24 +00001790
Bram Moolenaare2f98b92006-03-29 21:18:24 +00001791SQL *ft-sql-omni*
1792
1793Completion for the SQL language includes statements, functions, keywords.
1794It will also dynamically complete tables, procedures, views and column lists
1795with data pulled directly from within a database. For detailed instructions
1796and a tutorial see |omni-sql-completion|.
1797
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001798The SQL completion plugin can be used in conjunction with other completion
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001799plugins. For example, the PHP filetype has its own completion plugin.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001800Since PHP is often used to generate dynamic website by accessing a database,
1801the SQL completion plugin can also be enabled. This allows you to complete
1802PHP code and SQL code at the same time.
1803
Bram Moolenaare2f98b92006-03-29 21:18:24 +00001804
Bram Moolenaar4770d092006-01-12 23:22:24 +00001805XML *ft-xml-omni*
Bram Moolenaara5792f52005-11-23 21:25:05 +00001806
Bram Moolenaar9c102382006-05-03 21:26:49 +00001807Vim 7 provides a mechanism for context aware completion of XML files. It
1808depends on a special |xml-omni-datafile| and two commands: |:XMLns| and
1809|:XMLent|. Features are:
Bram Moolenaara5792f52005-11-23 21:25:05 +00001810
Bram Moolenaar9c102382006-05-03 21:26:49 +00001811- after "<" complete the tag name, depending on context
1812- inside of a tag complete proper attributes
1813- when an attribute has a limited number of possible values help to complete
Bram Moolenaara5792f52005-11-23 21:25:05 +00001814 them
Bram Moolenaar9c102382006-05-03 21:26:49 +00001815- complete names of entities (defined in |xml-omni-datafile| and in the
1816 current file with "<!ENTITY" declarations)
Bram Moolenaara5792f52005-11-23 21:25:05 +00001817- when used after "</" CTRL-X CTRL-O will close the last opened tag
1818
Bram Moolenaar4770d092006-01-12 23:22:24 +00001819Format of XML data file *xml-omni-datafile*
Bram Moolenaara5792f52005-11-23 21:25:05 +00001820
Bram Moolenaar9c102382006-05-03 21:26:49 +00001821XML data files are stored in the "autoload/xml" directory in 'runtimepath'.
1822Vim distribution provides examples of data files in the
1823"$VIMRUNTIME/autoload/xml" directory. They have a meaningful name which will
1824be used in commands. It should be a unique name which will not create
1825conflicts. For example, the name xhtml10s.vim means it is the data file for
1826XHTML 1.0 Strict.
Bram Moolenaara5792f52005-11-23 21:25:05 +00001827
Bram Moolenaar9c102382006-05-03 21:26:49 +00001828Each file contains a variable with a name like g:xmldata_xhtml10s . It is
1829a compound from two parts:
Bram Moolenaara5792f52005-11-23 21:25:05 +00001830
Bram Moolenaar9c102382006-05-03 21:26:49 +000018311. "g:xmldata_" general prefix, constant for all data files
18322. "xhtml10s" the name of the file and the name of the described XML
1833 dialect; it will be used as an argument for the |:XMLns|
1834 command
Bram Moolenaara5792f52005-11-23 21:25:05 +00001835
1836Part two must be exactly the same as name of file.
1837
Bram Moolenaar9c102382006-05-03 21:26:49 +00001838The variable is a |Dictionary|. Keys are tag names and each value is a two
1839element |List|. The first element of the List is also a List with the names
1840of possible children. The second element is a |Dictionary| with the names of
1841attributes as keys and the possible values of attributes as values. Example: >
Bram Moolenaara5792f52005-11-23 21:25:05 +00001842
Bram Moolenaar9c102382006-05-03 21:26:49 +00001843 let g:xmldata_crippled = {
1844 \ "vimxmlentities": ["amp", "lt", "gt", "apos", "quot"],
1845 \ 'vimxmlroot': ['tag1'],
1846 \ 'tag1':
1847 \ [ ['childoftag1a', 'childoftag1b'], {'attroftag1a': [],
1848 \ 'attroftag1b': ['valueofattr1', 'valueofattr2']}],
1849 \ 'childoftag1a':
1850 \ [ [], {'attrofchild': ['attrofchild']}],
1851 \ 'childoftag1b':
1852 \ [ ['childoftag1a'], {'attrofchild': []}],
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001853 \ "vimxmltaginfo": {
Bram Moolenaar9c102382006-05-03 21:26:49 +00001854 \ 'tag1': ['Menu info', 'Long information visible in preview window']},
1855 \ 'vimxmlattrinfo': {
1856 \ 'attrofchild': ['Menu info', 'Long information visible in preview window']}}
Bram Moolenaara5792f52005-11-23 21:25:05 +00001857
Bram Moolenaar9c102382006-05-03 21:26:49 +00001858This example would be put in the "autoload/xml/crippled.vim" file and could
1859help to write this file: >
Bram Moolenaara5792f52005-11-23 21:25:05 +00001860
Bram Moolenaar9c102382006-05-03 21:26:49 +00001861 <tag1 attroftag1b="valueofattr1">
1862 <childoftag1a attrofchild>
1863 &amp; &lt;
1864 </childoftag1a>
1865 <childoftag1b attrofchild="5">
1866 <childoftag1a>
1867 &gt; &apos; &quot;
1868 </childoftag1a>
1869 </childoftag1b>
1870 </tag1>
Bram Moolenaara5792f52005-11-23 21:25:05 +00001871
Bram Moolenaar9c102382006-05-03 21:26:49 +00001872In the example four special elements are visible:
1873
18741. "vimxmlentities" - a special key with List containing entities of this XML
Bram Moolenaara5792f52005-11-23 21:25:05 +00001875 dialect.
Bram Moolenaar9c102382006-05-03 21:26:49 +000018762. If the list containing possible values of attributes has one element and
1877 this element is equal to the name of the attribute this attribute will be
1878 treated as boolean and inserted as 'attrname' and not as 'attrname="'
18793. "vimxmltaginfo" - a special key with a Dictionary containing tag
1880 names as keys and two element List as values, for additional menu info and
1881 the long description.
18824. "vimxmlattrinfo" - special key with Dictionary containing attribute names
1883 as keys and two element List as values, for additional menu info and long
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001884 description.
Bram Moolenaara5792f52005-11-23 21:25:05 +00001885
Bram Moolenaar9c102382006-05-03 21:26:49 +00001886Note: Tag names in the data file MUST not contain a namespace description.
1887Check xsl.vim for an example.
1888Note: All data and functions are publicly available as global
1889variables/functions and can be used for personal editing functions.
Bram Moolenaara5792f52005-11-23 21:25:05 +00001890
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001891
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001892DTD -> Vim *dtd2vim*
Bram Moolenaarc1e37902006-04-18 21:55:01 +00001893
Bram Moolenaar9c102382006-05-03 21:26:49 +00001894On |www| is the script |dtd2vim| which parses DTD and creates an XML data file
Bram Moolenaarc1e37902006-04-18 21:55:01 +00001895for Vim XML omni completion.
1896
1897 dtd2vim: http://www.vim.org/scripts/script.php?script_id=1462
1898
Bram Moolenaar9c102382006-05-03 21:26:49 +00001899Check the beginning of that file for usage details.
1900The script requires perl and:
Bram Moolenaarc1e37902006-04-18 21:55:01 +00001901
1902 perlSGML: http://savannah.nongnu.org/projects/perlsgml
1903
1904
Bram Moolenaara5792f52005-11-23 21:25:05 +00001905Commands
1906
Bram Moolenaar4770d092006-01-12 23:22:24 +00001907:XMLns {name} [{namespace}] *:XMLns*
Bram Moolenaara5792f52005-11-23 21:25:05 +00001908
Bram Moolenaar9c102382006-05-03 21:26:49 +00001909Vim has to know which data file should be used and with which namespace. For
1910loading of the data file and connecting data with the proper namespace use
1911|:XMLns| command. The first (obligatory) argument is the name of the data
1912(xhtml10s, xsl). The second argument is the code of namespace (h, xsl). When
1913used without a second argument the dialect will be used as default - without
1914namespace declaration. For example to use XML completion in .xsl files: >
Bram Moolenaara5792f52005-11-23 21:25:05 +00001915
1916 :XMLns xhtml10s
1917 :XMLns xsl xsl
1918
1919
Bram Moolenaar4770d092006-01-12 23:22:24 +00001920:XMLent {name} *:XMLent*
Bram Moolenaara5792f52005-11-23 21:25:05 +00001921
Bram Moolenaar9c102382006-05-03 21:26:49 +00001922By default entities will be completed from the data file of the default
1923namespace. The XMLent command should be used in case when there is no default
1924namespace: >
Bram Moolenaara5792f52005-11-23 21:25:05 +00001925
Bram Moolenaar4770d092006-01-12 23:22:24 +00001926 :XMLent xhtml10s
Bram Moolenaara5792f52005-11-23 21:25:05 +00001927
1928Usage
1929
Bram Moolenaar9c102382006-05-03 21:26:49 +00001930While used in this situation (after declarations from previous part, | is
Bram Moolenaara5792f52005-11-23 21:25:05 +00001931cursor position): >
1932
Bram Moolenaar4770d092006-01-12 23:22:24 +00001933 <|
Bram Moolenaara5792f52005-11-23 21:25:05 +00001934
Bram Moolenaar9c102382006-05-03 21:26:49 +00001935Will complete to an appropriate XHTML tag, and in this situation: >
Bram Moolenaara5792f52005-11-23 21:25:05 +00001936
Bram Moolenaar4770d092006-01-12 23:22:24 +00001937 <xsl:|
Bram Moolenaara5792f52005-11-23 21:25:05 +00001938
Bram Moolenaar9c102382006-05-03 21:26:49 +00001939Will complete to an appropriate XSL tag.
Bram Moolenaara5792f52005-11-23 21:25:05 +00001940
Bram Moolenaar9c102382006-05-03 21:26:49 +00001941
1942The script xmlcomplete.vim, provided through the |autoload| mechanism,
1943has the xmlcomplete#GetLastOpenTag() function which can be used in XML files
1944to get the name of the last open tag (b:unaryTagsStack has to be defined): >
Bram Moolenaar6b730e12005-09-16 21:47:57 +00001945
Bram Moolenaar4770d092006-01-12 23:22:24 +00001946 :echo xmlcomplete#GetLastOpenTag("b:unaryTagsStack")
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00001947
Bram Moolenaar6b730e12005-09-16 21:47:57 +00001948
Bram Moolenaar1e015462005-09-25 22:16:38 +00001949
Bram Moolenaar071d4272004-06-13 20:20:40 +00001950==============================================================================
19518. Insert mode commands *inserting*
1952
1953The following commands can be used to insert new text into the buffer. They
1954can all be undone and repeated with the "." command.
1955
1956 *a*
1957a Append text after the cursor [count] times. If the
1958 cursor is in the first column of an empty line Insert
1959 starts there. But not when 'virtualedit' is set!
1960
1961 *A*
1962A Append text at the end of the line [count] times.
Bram Moolenaar1d59aa12020-09-19 18:50:13 +02001963 For using "A" in Visual block mode see |v_b_A|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001964
1965<insert> or *i* *insert* *<Insert>*
1966i Insert text before the cursor [count] times.
1967 When using CTRL-O in Insert mode |i_CTRL-O| the count
1968 is not supported.
1969
1970 *I*
1971I Insert text before the first non-blank in the line
1972 [count] times.
Bram Moolenaar4399ef42005-02-12 14:29:27 +00001973 When the 'H' flag is present in 'cpoptions' and the
1974 line only contains blanks, insert start just before
1975 the last blank.
Bram Moolenaar1d59aa12020-09-19 18:50:13 +02001976 For using "I" in Visual block mode see |v_b_I|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001977
1978 *gI*
Bram Moolenaar25c9c682019-05-05 18:13:34 +02001979gI Insert text in column 1 [count] times.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001980
1981 *gi*
1982gi Insert text in the same position as where Insert mode
1983 was stopped last time in the current buffer.
1984 This uses the |'^| mark. It's different from "`^i"
1985 when the mark is past the end of the line.
1986 The position is corrected for inserted/deleted lines,
1987 but NOT for inserted/deleted characters.
1988 When the |:keepjumps| command modifier is used the |'^|
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001989 mark won't be changed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001990
1991 *o*
1992o Begin a new line below the cursor and insert text,
Bram Moolenaara6c27c42019-05-09 19:16:22 +02001993 repeat [count] times.
Bram Moolenaar4399ef42005-02-12 14:29:27 +00001994 When the '#' flag is in 'cpoptions' the count is
1995 ignored.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001996
1997 *O*
1998O Begin a new line above the cursor and insert text,
Bram Moolenaara6c27c42019-05-09 19:16:22 +02001999 repeat [count] times.
Bram Moolenaar4399ef42005-02-12 14:29:27 +00002000 When the '#' flag is in 'cpoptions' the count is
2001 ignored.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002002
2003These commands are used to start inserting text. You can end insert mode with
2004<Esc>. See |mode-ins-repl| for the other special characters in Insert mode.
2005The effect of [count] takes place after Insert mode is exited.
2006
2007When 'autoindent' is on, the indent for a new line is obtained from the
2008previous line. When 'smartindent' or 'cindent' is on, the indent for a line
2009is automatically adjusted for C programs.
2010
Bram Moolenaar04fb9162021-12-30 20:24:12 +00002011'formatoptions' can be set to copy the comment leader when opening a new
2012line.
2013
Bram Moolenaar071d4272004-06-13 20:20:40 +00002014'textwidth' can be set to the maximum width for a line. When a line becomes
2015too long when appending characters a line break is automatically inserted.
2016
2017
2018==============================================================================
20199. Ex insert commands *inserting-ex*
2020
2021 *:a* *:append*
Bram Moolenaardf177f62005-02-22 08:39:57 +00002022:{range}a[ppend][!] Insert several lines of text below the specified
Bram Moolenaar071d4272004-06-13 20:20:40 +00002023 line. If the {range} is missing, the text will be
2024 inserted after the current line.
Bram Moolenaardf177f62005-02-22 08:39:57 +00002025 Adding [!] toggles 'autoindent' for the time this
2026 command is executed.
Bram Moolenaara4d131d2021-12-27 21:33:07 +00002027 This command is not supported in |Vim9| script,
2028 because it is too easily confused with a variable
2029 name.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002030
2031 *:i* *:in* *:insert*
Bram Moolenaardf177f62005-02-22 08:39:57 +00002032:{range}i[nsert][!] Insert several lines of text above the specified
Bram Moolenaar071d4272004-06-13 20:20:40 +00002033 line. If the {range} is missing, the text will be
2034 inserted before the current line.
Bram Moolenaardf177f62005-02-22 08:39:57 +00002035 Adding [!] toggles 'autoindent' for the time this
2036 command is executed.
Bram Moolenaara4d131d2021-12-27 21:33:07 +00002037 This command is not supported in |Vim9| script,
2038 because it is too easily confused with a variable
2039 name.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002040
2041These two commands will keep on asking for lines, until you type a line
2042containing only a ".". Watch out for lines starting with a backslash, see
2043|line-continuation|.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01002044
Mohamed Akram8c446da2024-07-13 18:49:55 +02002045Text typed after a "|" command separator is used first. So the following
2046command in ex mode: >
2047 :a|one
2048 two
2049 .
2050 :visual
h-east52e7cc22024-07-28 17:03:29 +02002051appends the following text, after the cursor line: >
Mohamed Akram8c446da2024-07-13 18:49:55 +02002052 one
2053 two
2054<
Mohamed Akram6d6dffa2024-07-14 10:34:25 +02002055In |Ex-mode|, when these commands are used with |:global| or |:vglobal| then
2056the lines are obtained from the text following the command. Separate lines
2057with a NL escaped with a backslash: >
2058 :global/abc/insert\
2059 one line\
2060 another line
2061The final "." is not needed then.
2062
2063NOTE: ":append" and ":insert" don't work properly in between ":if" and
Bram Moolenaar06fb4352005-01-05 22:10:30 +00002064":endif", ":for" and ":endfor", ":while" and ":endwhile".
Bram Moolenaar071d4272004-06-13 20:20:40 +00002065
2066 *:start* *:startinsert*
2067:star[tinsert][!] Start Insert mode just after executing this command.
2068 Works like typing "i" in Normal mode. When the ! is
2069 included it works like "A", append to the line.
2070 Otherwise insertion starts at the cursor position.
2071 Note that when using this command in a function or
2072 script, the insertion only starts after the function
2073 or script is finished.
Bram Moolenaar87e25fd2005-07-27 21:13:01 +00002074 This command does not work from |:normal|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002075
2076 *:stopi* *:stopinsert*
2077:stopi[nsert] Stop Insert mode as soon as possible. Works like
2078 typing <Esc> in Insert mode.
2079 Can be used in an autocommand, example: >
2080 :au BufEnter scratch stopinsert
Bram Moolenaar325b7a22004-07-05 15:58:32 +00002081<
2082 *replacing-ex* *:startreplace*
2083:startr[eplace][!] Start Replace mode just after executing this command.
2084 Works just like typing "R" in Normal mode. When the
2085 ! is included it acts just like "$R" had been typed
2086 (ie. begin replace mode at the end-of-line). Other-
2087 wise replacement begins at the cursor position.
2088 Note that when using this command in a function or
2089 script that the replacement will only start after
2090 the function or script is finished.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002091
Bram Moolenaar61da4982005-12-14 22:02:18 +00002092 *:startgreplace*
2093:startg[replace][!] Just like |:startreplace|, but use Virtual Replace
2094 mode, like with |gR|.
Bram Moolenaar61da4982005-12-14 22:02:18 +00002095
Bram Moolenaar071d4272004-06-13 20:20:40 +00002096==============================================================================
209710. Inserting a file *inserting-file*
2098
2099 *:r* *:re* *:read*
Bram Moolenaar910f66f2006-04-05 20:41:53 +00002100:r[ead] [++opt] [name]
2101 Insert the file [name] (default: current file) below
Bram Moolenaar071d4272004-06-13 20:20:40 +00002102 the cursor.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00002103 See |++opt| for the possible values of [++opt].
Bram Moolenaar071d4272004-06-13 20:20:40 +00002104
Bram Moolenaar910f66f2006-04-05 20:41:53 +00002105:{range}r[ead] [++opt] [name]
2106 Insert the file [name] (default: current file) below
Bram Moolenaar071d4272004-06-13 20:20:40 +00002107 the specified line.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00002108 See |++opt| for the possible values of [++opt].
Bram Moolenaar071d4272004-06-13 20:20:40 +00002109
2110 *:r!* *:read!*
Bram Moolenaar0187ca02013-04-12 15:09:51 +02002111:[range]r[ead] [++opt] !{cmd}
2112 Execute {cmd} and insert its standard output below
Bram Moolenaar9964e462007-05-05 17:54:07 +00002113 the cursor or the specified line. A temporary file is
2114 used to store the output of the command which is then
2115 read into the buffer. 'shellredir' is used to save
2116 the output of the command, which can be set to include
2117 stderr or not. {cmd} is executed like with ":!{cmd}",
2118 any '!' is replaced with the previous command |:!|.
Bram Moolenaar0187ca02013-04-12 15:09:51 +02002119 See |++opt| for the possible values of [++opt].
Bram Moolenaar071d4272004-06-13 20:20:40 +00002120
2121These commands insert the contents of a file, or the output of a command,
2122into the buffer. They can be undone. They cannot be repeated with the "."
2123command. They work on a line basis, insertion starts below the line in which
2124the cursor is, or below the specified line. To insert text above the first
2125line use the command ":0r {name}".
2126
2127After the ":read" command, the cursor is left on the first non-blank in the
Martino Ischiae6ccb642024-12-28 10:19:26 +01002128first new line. If in Ex mode, then the cursor is left on the last new
Bram Moolenaar071d4272004-06-13 20:20:40 +00002129line (sorry, this is Vi compatible).
2130
2131If a file name is given with ":r", it becomes the alternate file. This can be
2132used, for example, when you want to edit that file instead: ":e! #". This can
2133be switched off by removing the 'a' flag from the 'cpoptions' option.
2134
Bram Moolenaar910f66f2006-04-05 20:41:53 +00002135Of the [++opt] arguments one is specifically for ":read", the ++edit argument.
2136This is useful when the ":read" command is actually used to read a file into
2137the buffer as if editing that file. Use this command in an empty buffer: >
2138 :read ++edit filename
2139The effect is that the 'fileformat', 'fileencoding', 'bomb', etc. options are
2140set to what has been detected for "filename". Note that a single empty line
2141remains, you may want to delete it.
2142
Bram Moolenaar071d4272004-06-13 20:20:40 +00002143 *file-read*
2144The 'fileformat' option sets the <EOL> style for a file:
2145'fileformat' characters name ~
2146 "dos" <CR><NL> or <NL> DOS format
2147 "unix" <NL> Unix format
2148 "mac" <CR> Mac format
2149Previously 'textmode' was used. It is obsolete now.
2150
2151If 'fileformat' is "dos", a <CR> in front of an <NL> is ignored and a CTRL-Z
2152at the end of the file is ignored.
2153
2154If 'fileformat' is "mac", a <NL> in the file is internally represented by a
2155<CR>. This is to avoid confusion with a <NL> which is used to represent a
2156<NUL>. See |CR-used-for-NL|.
2157
2158If the 'fileformats' option is not empty Vim tries to recognize the type of
2159<EOL> (see |file-formats|). However, the 'fileformat' option will not be
2160changed, the detected format is only used while reading the file.
2161A similar thing happens with 'fileencodings'.
2162
Bram Moolenaar8024f932020-01-14 19:29:13 +01002163On non-Win32 systems the message "[dos format]" is shown if a file is read in
2164DOS format, to remind you that something unusual is done.
Bram Moolenaar5666fcd2019-12-26 14:35:26 +01002165On Macintosh and Win32 the message "[unix format]" is shown if a file is read
2166in Unix format.
Bram Moolenaar8024f932020-01-14 19:29:13 +01002167On non-Macintosh systems, the message "[mac format]" is shown if a file is
Bram Moolenaar071d4272004-06-13 20:20:40 +00002168read in Mac format.
2169
2170An example on how to use ":r !": >
2171 :r !uuencode binfile binfile
2172This command reads "binfile", uuencodes it and reads it into the current
2173buffer. Useful when you are editing e-mail and want to include a binary
2174file.
2175
2176 *read-messages*
2177When reading a file Vim will display a message with information about the read
2178file. In the table is an explanation for some of the items. The others are
2179self explanatory. Using the long or the short version depends on the
2180'shortmess' option.
2181
2182 long short meaning ~
2183 [readonly] {RO} the file is write protected
2184 [fifo/socket] using a stream
2185 [fifo] using a fifo stream
2186 [socket] using a socket stream
2187 [CR missing] reading with "dos" 'fileformat' and a
2188 NL without a preceding CR was found.
2189 [NL found] reading with "mac" 'fileformat' and a
2190 NL was found (could be "unix" format)
2191 [long lines split] at least one line was split in two
2192 [NOT converted] conversion from 'fileencoding' to
2193 'encoding' was desired but not
2194 possible
2195 [converted] conversion from 'fileencoding' to
2196 'encoding' done
2197 [crypted] file was decrypted
2198 [READ ERRORS] not all of the file could be read
2199
2200
Bram Moolenaar91f84f62018-07-29 15:07:52 +02002201 vim:tw=78:ts=8:noet:ft=help:norl: