blob: 7d218930d98ace6f801dffce70ad58ef1886b0c1 [file] [log] [blame]
Bram Moolenaar079ba762021-10-23 12:08:41 +01001*insert.txt* For Vim version 8.2. Last change: 2021 Oct 18
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-[.
Bram Moolenaarfb539272014-08-22 19:21:47 +020054 If Esc doesn't work and you are using a Mac, try CTRL-Esc.
55 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.
87 See |i_backspacing| about joining lines.
Bram Moolenaar071d4272004-06-13 20:20:40 +000088 *i_CTRL-I* *i_<Tab>* *i_Tab*
89<Tab> or CTRL-I Insert a tab. If the 'expandtab' option is on, the
90 equivalent number of spaces is inserted (use CTRL-V <Tab> to
91 avoid the expansion; use CTRL-Q <Tab> if CTRL-V is mapped
92 |i_CTRL-Q|). See also the 'smarttab' option and
93 |ins-expandtab|.
94 *i_CTRL-J* *i_<NL>*
95<NL> or CTRL-J Begin new line.
96 *i_CTRL-M* *i_<CR>*
97<CR> or CTRL-M Begin new line.
98 *i_CTRL-K*
99CTRL-K {char1} [char2]
100 Enter digraph (see |digraphs|). When {char1} is a special
101 key, the code for that key is inserted in <> form. For
102 example, the string "<S-Space>" can be entered by typing
103 <C-K><S-Space> (two keys). Neither char is considered for
Bram Moolenaar25c9c682019-05-05 18:13:34 +0200104 mapping.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000105
Bram Moolenaar25c9c682019-05-05 18:13:34 +0200106CTRL-N Find next keyword (see |i_CTRL-N|).
107CTRL-P Find previous keyword (see |i_CTRL-P|).
Bram Moolenaar071d4272004-06-13 20:20:40 +0000108
Bram Moolenaar5be4cee2019-09-27 19:34:08 +0200109CTRL-R {register} *i_CTRL-R*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000110 Insert the contents of a register. Between typing CTRL-R and
111 the second character, '"' will be displayed to indicate that
112 you are expected to enter the name of a register.
113 The text is inserted as if you typed it, but mappings and
114 abbreviations are not used. If you have options like
115 'textwidth', 'formatoptions', or 'autoindent' set, this will
116 influence what will be inserted. This is different from what
117 happens with the "p" command and pasting with the mouse.
118 Special registers:
119 '"' the unnamed register, containing the text of
120 the last delete or yank
121 '%' the current file name
122 '#' the alternate file name
123 '*' the clipboard contents (X11: primary selection)
124 '+' the clipboard contents
125 '/' the last search pattern
126 ':' the last command-line
127 '.' the last inserted text
128 '-' the last small (less than a line) delete
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100129 *i_CTRL-R_=*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000130 '=' the expression register: you are prompted to
131 enter an expression (see |expression|)
Bram Moolenaar293ee4d2004-12-09 21:34:53 +0000132 Note that 0x80 (128 decimal) is used for
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +0000133 special keys. E.g., you can use this to move
134 the cursor up:
135 CTRL-R ="\<Up>"
136 Use CTRL-R CTRL-R to insert text literally.
Bram Moolenaar362e1a32006-03-06 23:29:24 +0000137 When the result is a |List| the items are used
138 as lines. They can have line breaks inside
139 too.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100140 When the result is a Float it's automatically
141 converted to a String.
Bram Moolenaar94f76b72013-07-04 22:50:40 +0200142 When append() or setline() is invoked the undo
143 sequence will be broken.
Bram Moolenaar25c9c682019-05-05 18:13:34 +0200144 See |registers| about registers.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000145
Bram Moolenaar5be4cee2019-09-27 19:34:08 +0200146CTRL-R CTRL-R {register} *i_CTRL-R_CTRL-R*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000147 Insert the contents of a register. Works like using a single
148 CTRL-R, but the text is inserted literally, not as if typed.
149 This differs when the register contains characters like <BS>.
150 Example, where register a contains "ab^Hc": >
151 CTRL-R a results in "ac".
152 CTRL-R CTRL-R a results in "ab^Hc".
153< Options 'textwidth', 'formatoptions', etc. still apply. If
Bram Moolenaarca635012015-09-25 20:34:21 +0200154 you also want to avoid these, use CTRL-R CTRL-O, see below.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000155 The '.' register (last inserted text) is still inserted as
Bram Moolenaar25c9c682019-05-05 18:13:34 +0200156 typed.
Bram Moolenaard1caa942020-04-10 22:10:56 +0200157 After this command, the '.' register contains the text from
158 the register as if it was inserted by typing it.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000159
Bram Moolenaar5be4cee2019-09-27 19:34:08 +0200160CTRL-R CTRL-O {register} *i_CTRL-R_CTRL-O*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000161 Insert the contents of a register literally and don't
162 auto-indent. Does the same as pasting with the mouse
Bram Moolenaarcd5c8f82017-04-09 20:11:58 +0200163 |<MiddleMouse>|. When the register is linewise this will
164 insert the text above the current line, like with `P`.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000165 Does not replace characters!
166 The '.' register (last inserted text) is still inserted as
Bram Moolenaar25c9c682019-05-05 18:13:34 +0200167 typed.
Bram Moolenaard1caa942020-04-10 22:10:56 +0200168 After this command, the '.' register contains the command
169 typed and not the text. I.e., the literals "^R^O" and not the
170 text from the register.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000171
Bram Moolenaar5be4cee2019-09-27 19:34:08 +0200172CTRL-R CTRL-P {register} *i_CTRL-R_CTRL-P*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000173 Insert the contents of a register literally and fix the
174 indent, like |[<MiddleMouse>|.
175 Does not replace characters!
176 The '.' register (last inserted text) is still inserted as
Bram Moolenaar25c9c682019-05-05 18:13:34 +0200177 typed.
Bram Moolenaard1caa942020-04-10 22:10:56 +0200178 After this command, the '.' register contains the command
179 typed and not the text. I.e., the literals "^R^P" and not the
180 text from the register.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000181
182 *i_CTRL-T*
183CTRL-T Insert one shiftwidth of indent at the start of the current
184 line. The indent is always rounded to a 'shiftwidth' (this is
Bram Moolenaara6c27c42019-05-09 19:16:22 +0200185 vi compatible).
Bram Moolenaar071d4272004-06-13 20:20:40 +0000186 *i_CTRL-D*
187CTRL-D Delete one shiftwidth of indent at the start of the current
188 line. The indent is always rounded to a 'shiftwidth' (this is
Bram Moolenaara6c27c42019-05-09 19:16:22 +0200189 vi compatible).
Bram Moolenaar071d4272004-06-13 20:20:40 +0000190 *i_0_CTRL-D*
Bram Moolenaara6c27c42019-05-09 19:16:22 +02001910 CTRL-D Delete all indent in the current line.
192
Bram Moolenaar071d4272004-06-13 20:20:40 +0000193 *i_^_CTRL-D*
194^ CTRL-D Delete all indent in the current line. The indent is
195 restored in the next line. This is useful when inserting a
Bram Moolenaara6c27c42019-05-09 19:16:22 +0200196 label.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000197
198 *i_CTRL-V*
199CTRL-V Insert next non-digit literally. For special keys, the
200 terminal code is inserted. It's also possible to enter the
201 decimal, octal or hexadecimal value of a character
202 |i_CTRL-V_digit|.
203 The characters typed right after CTRL-V are not considered for
Bram Moolenaara6c27c42019-05-09 19:16:22 +0200204 mapping.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000205 Note: When CTRL-V is mapped (e.g., to paste text) you can
206 often use CTRL-Q instead |i_CTRL-Q|.
Bram Moolenaarfc4ea2a2019-11-26 19:33:22 +0100207 When |modifyOtherKeys| is enabled then special Escape sequence
208 is converted back to what it was without |modifyOtherKeys|,
209 unless the Shift key is also pressed.
210
Bram Moolenaar071d4272004-06-13 20:20:40 +0000211 *i_CTRL-Q*
212CTRL-Q Same as CTRL-V.
213 Note: Some terminal connections may eat CTRL-Q, it doesn't
214 work then. It does work in the GUI.
215
Bram Moolenaar8024f932020-01-14 19:29:13 +0100216CTRL-SHIFT-V *i_CTRL-SHIFT-V* *i_CTRL-SHIFT-Q*
217CTRL-SHIFT-Q Works just like CTRL-V, unless |modifyOtherKeys| is active,
218 then it inserts the Escape sequence for a key with modifiers.
219
Bram Moolenaar071d4272004-06-13 20:20:40 +0000220CTRL-X Enter CTRL-X mode. This is a sub-mode where commands can
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000221 be given to complete words or scroll the window. See
Bram Moolenaar25c9c682019-05-05 18:13:34 +0200222 |i_CTRL-X| and |ins-completion|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000223
224 *i_CTRL-E*
Bram Moolenaar25c9c682019-05-05 18:13:34 +0200225CTRL-E Insert the character which is below the cursor.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000226 *i_CTRL-Y*
Bram Moolenaar25c9c682019-05-05 18:13:34 +0200227CTRL-Y Insert the character which is above the cursor.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000228 Note that for CTRL-E and CTRL-Y 'textwidth' is not used, to be
229 able to copy characters from a long line.
230
231 *i_CTRL-_*
232CTRL-_ Switch between languages, as follows:
233 - When in a rightleft window, revins and nohkmap are toggled,
234 since English will likely be inserted in this case.
235 - When in a norightleft window, revins and hkmap are toggled,
236 since Hebrew will likely be inserted in this case.
237
238 CTRL-_ moves the cursor to the end of the typed text.
239
240 This command is only available when the 'allowrevins' option
241 is set.
242 Please refer to |rileft.txt| for more information about
243 right-to-left mode.
Bram Moolenaar9964e462007-05-05 17:54:07 +0000244 Only if compiled with the |+rightleft| feature.
245
Bram Moolenaar071d4272004-06-13 20:20:40 +0000246 *i_CTRL-^*
247CTRL-^ Toggle the use of typing language characters.
248 When language |:lmap| mappings are defined:
249 - If 'iminsert' is 1 (langmap mappings used) it becomes 0 (no
250 langmap mappings used).
251 - If 'iminsert' has another value it becomes 1, thus langmap
252 mappings are enabled.
253 When no language mappings are defined:
254 - If 'iminsert' is 2 (Input Method used) it becomes 0 (no
255 Input Method used).
256 - If 'iminsert' has another value it becomes 2, thus the Input
257 Method is enabled.
258 When set to 1, the value of the "b:keymap_name" variable, the
259 'keymap' option or "<lang>" appears in the status line.
260 The language mappings are normally used to type characters
261 that are different from what the keyboard produces. The
262 'keymap' option can be used to install a whole number of them.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000263
264 *i_CTRL-]*
Bram Moolenaar25c9c682019-05-05 18:13:34 +0200265CTRL-] Trigger abbreviation, without inserting a character.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000266
267 *i_<Insert>*
Bram Moolenaar25c9c682019-05-05 18:13:34 +0200268<Insert> Toggle between Insert and Replace mode.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000269-----------------------------------------------------------------------
270
271 *i_backspacing*
272The effect of the <BS>, CTRL-W, and CTRL-U depend on the 'backspace' option
273(unless 'revins' is set). This is a comma separated list of items:
274
275item action ~
276indent allow backspacing over autoindent
277eol allow backspacing over end-of-line (join lines)
278start allow backspacing over the start position of insert; CTRL-W and
279 CTRL-U stop once at the start position
280
281When 'backspace' is empty, Vi compatible backspacing is used. You cannot
282backspace over autoindent, before column 1 or before where insert started.
283
284For backwards compatibility the values "0", "1" and "2" are also allowed, see
285|'backspace'|.
286
287If the 'backspace' option does contain "eol" and the cursor is in column 1
288when one of the three keys is used, the current line is joined with the
289previous line. This effectively deletes the <EOL> in front of the cursor.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000290
291 *i_CTRL-V_digit*
292With CTRL-V the decimal, octal or hexadecimal value of a character can be
293entered directly. This way you can enter any character, except a line break
294(<NL>, value 10). There are five ways to enter the character value:
295
296first char mode max nr of chars max value ~
297(none) decimal 3 255
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000298o or O octal 3 377 (255)
Bram Moolenaar071d4272004-06-13 20:20:40 +0000299x or X hexadecimal 2 ff (255)
300u hexadecimal 4 ffff (65535)
301U hexadecimal 8 7fffffff (2147483647)
302
303Normally you would type the maximum number of characters. Thus to enter a
304space (value 32) you would type <C-V>032. You can omit the leading zero, in
305which case the character typed after the number must be a non-digit. This
306happens for the other modes as well: As soon as you type a character that is
307invalid for the mode, the value before it will be used and the "invalid"
308character is dealt with in the normal way.
309
310If you enter a value of 10, it will end up in the file as a 0. The 10 is a
311<NL>, which is used internally to represent the <Nul> character. When writing
312the buffer to a file, the <NL> character is translated into <Nul>. The <NL>
313character is written at the end of each line. Thus if you want to insert a
314<NL> character in a file you will have to make a line break.
Bram Moolenaarcb80aa22020-10-26 21:12:46 +0100315Also see 'fileformat'.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000316
317 *i_CTRL-X* *insert_expand*
318CTRL-X enters a sub-mode where several commands can be used. Most of these
Bram Moolenaare2c453d2019-08-21 14:37:09 +0200319commands do keyword completion; see |ins-completion|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000320
321Two commands can be used to scroll the window up or down, without exiting
322insert mode:
323
324 *i_CTRL-X_CTRL-E*
325CTRL-X CTRL-E scroll window one line up.
Bram Moolenaard2cec5b2006-03-28 21:08:56 +0000326 When doing completion look here: |complete_CTRL-E|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000327
328 *i_CTRL-X_CTRL-Y*
329CTRL-X CTRL-Y scroll window one line down.
Bram Moolenaard2cec5b2006-03-28 21:08:56 +0000330 When doing completion look here: |complete_CTRL-Y|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000331
332After CTRL-X is pressed, each CTRL-E (CTRL-Y) scrolls the window up (down) by
333one line unless that would cause the cursor to move from its current position
334in the file. As soon as another key is pressed, CTRL-X mode is exited and
335that key is interpreted as in Insert mode.
336
337
338==============================================================================
3392. Special special keys *ins-special-special*
340
341The following keys are special. They stop the current insert, do something,
342and then restart insertion. This means you can do something without getting
343out of Insert mode. This is very handy if you prefer to use the Insert mode
344all the time, just like editors that don't have a separate Normal mode. You
345may also want to set the 'backspace' option to "indent,eol,start" and set the
346'insertmode' option. You can use CTRL-O if you want to map a function key to
347a command.
348
349The changes (inserted or deleted characters) before and after these keys can
350be undone separately. Only the last change can be redone and always behaves
351like an "i" command.
352
353char action ~
354-----------------------------------------------------------------------
355<Up> cursor one line up *i_<Up>*
356<Down> cursor one line down *i_<Down>*
357CTRL-G <Up> cursor one line up, insert start column *i_CTRL-G_<Up>*
358CTRL-G k cursor one line up, insert start column *i_CTRL-G_k*
359CTRL-G CTRL-K cursor one line up, insert start column *i_CTRL-G_CTRL-K*
360CTRL-G <Down> cursor one line down, insert start column *i_CTRL-G_<Down>*
361CTRL-G j cursor one line down, insert start column *i_CTRL-G_j*
362CTRL-G CTRL-J cursor one line down, insert start column *i_CTRL-G_CTRL-J*
363<Left> cursor one character left *i_<Left>*
364<Right> cursor one character right *i_<Right>*
365<S-Left> cursor one word back (like "b" command) *i_<S-Left>*
366<C-Left> cursor one word back (like "b" command) *i_<C-Left>*
367<S-Right> cursor one word forward (like "w" command) *i_<S-Right>*
368<C-Right> cursor one word forward (like "w" command) *i_<C-Right>*
369<Home> cursor to first char in the line *i_<Home>*
370<End> cursor to after last char in the line *i_<End>*
371<C-Home> cursor to first char in the file *i_<C-Home>*
372<C-End> cursor to after last char in the file *i_<C-End>*
373<LeftMouse> cursor to position of mouse click *i_<LeftMouse>*
374<S-Up> move window one page up *i_<S-Up>*
375<PageUp> move window one page up *i_<PageUp>*
376<S-Down> move window one page down *i_<S-Down>*
377<PageDown> move window one page down *i_<PageDown>*
Bram Moolenaar8d9b40e2010-07-25 15:49:07 +0200378<ScrollWheelDown> move window three lines down *i_<ScrollWheelDown>*
379<S-ScrollWheelDown> move window one page down *i_<S-ScrollWheelDown>*
380<ScrollWheelUp> move window three lines up *i_<ScrollWheelUp>*
381<S-ScrollWheelUp> move window one page up *i_<S-ScrollWheelUp>*
382<ScrollWheelLeft> move window six columns left *i_<ScrollWheelLeft>*
383<S-ScrollWheelLeft> move window one page left *i_<S-ScrollWheelLeft>*
384<ScrollWheelRight> move window six columns right *i_<ScrollWheelRight>*
385<S-ScrollWheelRight> move window one page right *i_<S-ScrollWheelRight>*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000386CTRL-O execute one command, return to Insert mode *i_CTRL-O*
Bram Moolenaar4770d092006-01-12 23:22:24 +0000387CTRL-\ CTRL-O like CTRL-O but don't move the cursor *i_CTRL-\_CTRL-O*
Bram Moolenaar488c6512005-08-11 20:09:58 +0000388CTRL-L when 'insertmode' is set: go to Normal mode *i_CTRL-L*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000389CTRL-G u break undo sequence, start new change *i_CTRL-G_u*
Bram Moolenaar8b5f65a2015-09-01 19:26:12 +0200390CTRL-G U don't break undo with next left/right cursor *i_CTRL-G_U*
Bram Moolenaar191acfd2020-03-27 20:42:43 +0100391 movement, if the cursor stays within the
392 same line
Bram Moolenaar071d4272004-06-13 20:20:40 +0000393-----------------------------------------------------------------------
394
395Note: If the cursor keys take you out of Insert mode, check the 'noesckeys'
396option.
397
398The CTRL-O command sometimes has a side effect: If the cursor was beyond the
399end of the line, it will be put on the last character in the line. In
400mappings it's often better to use <Esc> (first put an "x" in the text, <Esc>
Bram Moolenaar488c6512005-08-11 20:09:58 +0000401will then always put the cursor on it). Or use CTRL-\ CTRL-O, but then
Bram Moolenaara3e6bc92013-01-30 14:18:00 +0100402beware of the cursor possibly being beyond the end of the line. Note that the
403command following CTRL-\ CTRL-O can still move the cursor, it is not restored
404to its original position.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000405
Bram Moolenaar05365702010-10-27 18:34:44 +0200406The CTRL-O command takes you to Normal mode. If you then use a command enter
Bram Moolenaard38b0552012-04-25 19:07:41 +0200407Insert mode again it normally doesn't nest. Thus when typing "a<C-O>a" and
408then <Esc> takes you back to Normal mode, you do not need to type <Esc> twice.
409An exception is when not typing the command, e.g. when executing a mapping or
410sourcing a script. This makes mappings work that briefly switch to Insert
411mode.
Bram Moolenaar05365702010-10-27 18:34:44 +0200412
Bram Moolenaar071d4272004-06-13 20:20:40 +0000413The shifted cursor keys are not available on all terminals.
414
415Another side effect is that a count specified before the "i" or "a" command is
416ignored. That is because repeating the effect of the command after CTRL-O is
417too complicated.
418
419An example for using CTRL-G u: >
420
421 :inoremap <C-H> <C-G>u<C-H>
422
423This redefines the backspace key to start a new undo sequence. You can now
424undo the effect of the backspace key, without changing what you typed before
Bram Moolenaar5b435d62012-04-05 17:33:26 +0200425that, with CTRL-O u. Another example: >
426
427 :inoremap <CR> <C-]><C-G>u<CR>
428
429This breaks undo at each line break. It also expands abbreviations before
430this.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000431
Bram Moolenaar8b5f65a2015-09-01 19:26:12 +0200432An example for using CTRL-G U: >
433
434 inoremap <Left> <C-G>U<Left>
435 inoremap <Right> <C-G>U<Right>
436 inoremap <expr> <Home> col('.') == match(getline('.'), '\S') + 1 ?
437 \ repeat('<C-G>U<Left>', col('.') - 1) :
438 \ (col('.') < match(getline('.'), '\S') ?
439 \ repeat('<C-G>U<Right>', match(getline('.'), '\S') + 0) :
440 \ repeat('<C-G>U<Left>', col('.') - 1 - match(getline('.'), '\S')))
441 inoremap <expr> <End> repeat('<C-G>U<Right>', col('$') - col('.'))
442 inoremap ( ()<C-G>U<Left>
443
444This makes it possible to use the cursor keys in Insert mode, without breaking
Bram Moolenaar40962ec2018-01-28 22:47:25 +0100445the undo sequence and therefore using |.| (redo) will work as expected.
Bram Moolenaard2f3a8b2018-06-19 14:35:59 +0200446Also entering a text like (with the "(" mapping from above):
Bram Moolenaar8b5f65a2015-09-01 19:26:12 +0200447
448 Lorem ipsum (dolor
449
Bram Moolenaard2f3a8b2018-06-19 14:35:59 +0200450will be repeatable by using |.| to the expected
Bram Moolenaar8b5f65a2015-09-01 19:26:12 +0200451
452 Lorem ipsum (dolor)
453
Bram Moolenaarf4b8e572004-06-24 15:53:16 +0000454Using CTRL-O splits undo: the text typed before and after it is undone
455separately. If you want to avoid this (e.g., in a mapping) you might be able
456to use CTRL-R = |i_CTRL-R|. E.g., to call a function: >
457 :imap <F2> <C-R>=MyFunc()<CR>
458
Bram Moolenaar071d4272004-06-13 20:20:40 +0000459When the 'whichwrap' option is set appropriately, the <Left> and <Right>
460keys on the first/last character in the line make the cursor wrap to the
461previous/next line.
462
463The CTRL-G j and CTRL-G k commands can be used to insert text in front of a
464column. Example: >
465 int i;
466 int j;
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000467Position the cursor on the first "int", type "istatic <C-G>j ". The
Bram Moolenaar071d4272004-06-13 20:20:40 +0000468result is: >
469 static int i;
470 int j;
471When inserting the same text in front of the column in every line, use the
472Visual blockwise command "I" |v_b_I|.
473
474==============================================================================
4753. 'textwidth' and 'wrapmargin' options *ins-textwidth*
476
477The 'textwidth' option can be used to automatically break a line before it
478gets too long. Set the 'textwidth' option to the desired maximum line
479length. If you then type more characters (not spaces or tabs), the
480last word will be put on a new line (unless it is the only word on the
481line). If you set 'textwidth' to 0, this feature is disabled.
482
483The 'wrapmargin' option does almost the same. The difference is that
484'textwidth' has a fixed width while 'wrapmargin' depends on the width of the
485screen. When using 'wrapmargin' this is equal to using 'textwidth' with a
486value equal to (columns - 'wrapmargin'), where columns is the width of the
487screen.
488
489When 'textwidth' and 'wrapmargin' are both set, 'textwidth' is used.
490
491If you don't really want to break the line, but view the line wrapped at a
492convenient place, see the 'linebreak' option.
493
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +0000494The line is only broken automatically when using Insert mode, or when
Bram Moolenaar071d4272004-06-13 20:20:40 +0000495appending to a line. When in replace mode and the line length is not
496changed, the line will not be broken.
497
498Long lines are broken if you enter a non-white character after the margin.
499The situations where a line will be broken can be restricted by adding
500characters to the 'formatoptions' option:
501"l" Only break a line if it was not longer than 'textwidth' when the insert
502 started.
503"v" Only break at a white character that has been entered during the
504 current insert command. This is mostly Vi-compatible.
505"lv" Only break if the line was not longer than 'textwidth' when the insert
506 started and only at a white character that has been entered during the
507 current insert command. Only differs from "l" when entering non-white
508 characters while crossing the 'textwidth' boundary.
509
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +0000510Normally an internal function will be used to decide where to break the line.
511If you want to do it in a different way set the 'formatexpr' option to an
512expression that will take care of the line break.
513
Bram Moolenaar071d4272004-06-13 20:20:40 +0000514If you want to format a block of text, you can use the "gq" operator. Type
515"gq" and a movement command to move the cursor to the end of the block. In
516many cases, the command "gq}" will do what you want (format until the end of
517paragraph). Alternatively, you can use "gqap", which will format the whole
518paragraph, no matter where the cursor currently is. Or you can use Visual
519mode: hit "v", move to the end of the block, and type "gq". See also |gq|.
520
521==============================================================================
5224. 'expandtab', 'smarttab' and 'softtabstop' options *ins-expandtab*
523
524If the 'expandtab' option is on, spaces will be used to fill the amount of
525whitespace of the tab. If you want to enter a real <Tab>, type CTRL-V first
526(use CTRL-Q when CTRL-V is mapped |i_CTRL-Q|).
527The 'expandtab' option is off by default. Note that in Replace mode, a single
528character is replaced with several spaces. The result of this is that the
529number of characters in the line increases. Backspacing will delete one
530space at a time. The original character will be put back for only one space
Bram Moolenaar25c9c682019-05-05 18:13:34 +0200531that you backspace over (the last one).
Bram Moolenaar071d4272004-06-13 20:20:40 +0000532
533 *ins-smarttab*
534When the 'smarttab' option is on, a <Tab> inserts 'shiftwidth' positions at
535the beginning of a line and 'tabstop' positions in other places. This means
Bram Moolenaar30b65812012-07-12 22:01:11 +0200536that often spaces instead of a <Tab> character are inserted. When 'smarttab'
Bram Moolenaar071d4272004-06-13 20:20:40 +0000537is off, a <Tab> always inserts 'tabstop' positions, and 'shiftwidth' is only
Bram Moolenaar25c9c682019-05-05 18:13:34 +0200538used for ">>" and the like.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000539
540 *ins-softtabstop*
541When the 'softtabstop' option is non-zero, a <Tab> inserts 'softtabstop'
542positions, and a <BS> used to delete white space, will delete 'softtabstop'
543positions. This feels like 'tabstop' was set to 'softtabstop', but a real
544<Tab> character still takes 'tabstop' positions, so your file will still look
545correct when used by other applications.
546
547If 'softtabstop' is non-zero, a <BS> will try to delete as much white space to
548move to the previous 'softtabstop' position, except when the previously
549inserted character is a space, then it will only delete the character before
550the cursor. Otherwise you cannot always delete a single character before the
551cursor. You will have to delete 'softtabstop' characters first, and then type
552extra spaces to get where you want to be.
553
554==============================================================================
5555. Replace mode *Replace* *Replace-mode* *mode-replace*
556
557Enter Replace mode with the "R" command in normal mode.
558
559In Replace mode, one character in the line is deleted for every character you
560type. If there is no character to delete (at the end of the line), the
561typed character is appended (as in Insert mode). Thus the number of
562characters in a line stays the same until you get to the end of the line.
563If a <NL> is typed, a line break is inserted and no character is deleted.
564
565Be careful with <Tab> characters. If you type a normal printing character in
566its place, the number of characters is still the same, but the number of
567columns will become smaller.
568
569If you delete characters in Replace mode (with <BS>, CTRL-W, or CTRL-U), what
570happens is that you delete the changes. The characters that were replaced
571are restored. If you had typed past the existing text, the characters you
572added are deleted. This is effectively a character-at-a-time undo.
573
574If the 'expandtab' option is on, a <Tab> will replace one character with
575several spaces. The result of this is that the number of characters in the
576line increases. Backspacing will delete one space at a time. The original
577character will be put back for only one space that you backspace over (the
Bram Moolenaar25c9c682019-05-05 18:13:34 +0200578last one).
Bram Moolenaar071d4272004-06-13 20:20:40 +0000579
580==============================================================================
5816. Virtual Replace mode *vreplace-mode* *Virtual-Replace-mode*
582
583Enter Virtual Replace mode with the "gR" command in normal mode.
Bram Moolenaardb84e452010-08-15 13:50:43 +0200584{not available when compiled without the |+vreplace| feature}
Bram Moolenaar071d4272004-06-13 20:20:40 +0000585
586Virtual Replace mode is similar to Replace mode, but instead of replacing
587actual characters in the file, you are replacing screen real estate, so that
588characters further on in the file never appear to move.
589
590So if you type a <Tab> it may replace several normal characters, and if you
591type a letter on top of a <Tab> it may not replace anything at all, since the
592<Tab> will still line up to the same place as before.
593
594Typing a <NL> still doesn't cause characters later in the file to appear to
595move. The rest of the current line will be replaced by the <NL> (that is,
596they are deleted), and replacing continues on the next line. A new line is
597NOT inserted unless you go past the end of the file.
598
599Interesting effects are seen when using CTRL-T and CTRL-D. The characters
600before the cursor are shifted sideways as normal, but characters later in the
601line still remain still. CTRL-T will hide some of the old line under the
602shifted characters, but CTRL-D will reveal them again.
603
604As with Replace mode, using <BS> etc will bring back the characters that were
605replaced. This still works in conjunction with 'smartindent', CTRL-T and
606CTRL-D, 'expandtab', 'smarttab', 'softtabstop', etc.
607
608In 'list' mode, Virtual Replace mode acts as if it was not in 'list' mode,
609unless "L" is in 'cpoptions'.
610
Bram Moolenaar24ea3ba2010-09-19 19:01:21 +0200611Note that the only situations for which characters beyond the cursor should
612appear to move are in List mode |'list'|, and occasionally when 'wrap' is set
613(and the line changes length to become shorter or wider than the width of the
614screen). In other cases spaces may be inserted to avoid following characters
615to move.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000616
617This mode is very useful for editing <Tab> separated columns in tables, for
618entering new data while keeping all the columns aligned.
619
620==============================================================================
6217. Insert mode completion *ins-completion*
622
Bram Moolenaar4be06f92005-07-29 22:36:03 +0000623In Insert and Replace mode, there are several commands to complete part of a
Bram Moolenaar071d4272004-06-13 20:20:40 +0000624keyword or line that has been typed. This is useful if you are using
625complicated keywords (e.g., function names with capitals and underscores).
626
Bram Moolenaar071d4272004-06-13 20:20:40 +0000627Completion can be done for:
628
6291. Whole lines |i_CTRL-X_CTRL-L|
6302. keywords in the current file |i_CTRL-X_CTRL-N|
6313. keywords in 'dictionary' |i_CTRL-X_CTRL-K|
6324. keywords in 'thesaurus', thesaurus-style |i_CTRL-X_CTRL-T|
6335. keywords in the current and included files |i_CTRL-X_CTRL-I|
6346. tags |i_CTRL-X_CTRL-]|
6357. file names |i_CTRL-X_CTRL-F|
6368. definitions or macros |i_CTRL-X_CTRL-D|
6379. Vim command-line |i_CTRL-X_CTRL-V|
Bram Moolenaar4be06f92005-07-29 22:36:03 +000063810. User defined completion |i_CTRL-X_CTRL-U|
Bram Moolenaarf75a9632005-09-13 21:20:47 +000063911. omni completion |i_CTRL-X_CTRL-O|
Bram Moolenaar488c6512005-08-11 20:09:58 +000064012. Spelling suggestions |i_CTRL-X_s|
Bram Moolenaar6aa8cea2017-06-05 14:44:35 +020064113. keywords in 'complete' |i_CTRL-N| |i_CTRL-P|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000642
zeertzjqdca29d92021-08-31 19:12:51 +0200643Additionally, |i_CTRL-X_CTRL-Z| stops completion without changing the text.
644
Bram Moolenaar6aa8cea2017-06-05 14:44:35 +0200645All these, except CTRL-N and CTRL-P, are done in CTRL-X mode. This is a
646sub-mode of Insert and Replace modes. You enter CTRL-X mode by typing CTRL-X
647and one of the CTRL-X commands. You exit CTRL-X mode by typing a key that is
648not a valid CTRL-X mode command. Valid keys are the CTRL-X command itself,
649CTRL-N (next), and CTRL-P (previous).
Bram Moolenaar071d4272004-06-13 20:20:40 +0000650
Bram Moolenaarfd133322019-03-29 12:20:27 +0100651To get the current completion information, |complete_info()| can be used.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000652Also see the 'infercase' option if you want to adjust the case of the match.
653
Bram Moolenaard2cec5b2006-03-28 21:08:56 +0000654 *complete_CTRL-E*
655When completion is active you can use CTRL-E to stop it and go back to the
Bram Moolenaar551dbcc2006-04-25 22:13:59 +0000656originally typed text. The CTRL-E will not be inserted.
Bram Moolenaard2cec5b2006-03-28 21:08:56 +0000657
658 *complete_CTRL-Y*
659When the popup menu is displayed you can use CTRL-Y to stop completion and
660accept the currently selected entry. The CTRL-Y is not inserted. Typing a
661space, Enter, or some other unprintable character will leave completion mode
662and insert that typed character.
663
Bram Moolenaar9e54a0e2006-04-14 20:42:25 +0000664When the popup menu is displayed there are a few more special keys, see
665|popupmenu-keys|.
666
Bram Moolenaar071d4272004-06-13 20:20:40 +0000667Note: The keys that are valid in CTRL-X mode are not mapped. This allows for
668":map ^F ^X^F" to work (where ^F is CTRL-F and ^X is CTRL-X). The key that
669ends CTRL-X mode (any key that is not a valid CTRL-X mode command) is mapped.
670Also, when doing completion with 'complete' mappings apply as usual.
671
Bram Moolenaar7ceefb32020-05-01 16:07:38 +0200672 *E578* *E565*
Bram Moolenaarff06f282020-04-21 22:01:14 +0200673Note: While completion is active Insert mode can't be used recursively and
674buffer text cannot be changed. Mappings that somehow invoke ":normal i.."
675will generate an E565 error.
Bram Moolenaarf193fff2006-04-27 00:02:13 +0000676
Bram Moolenaar071d4272004-06-13 20:20:40 +0000677The following mappings are suggested to make typing the completion commands
678a bit easier (although they will hide other commands): >
679 :inoremap ^] ^X^]
680 :inoremap ^F ^X^F
681 :inoremap ^D ^X^D
682 :inoremap ^L ^X^L
683
684As a special case, typing CTRL-R to perform register insertion (see
685|i_CTRL-R|) will not exit CTRL-X mode. This is primarily to allow the use of
686the '=' register to call some function to determine the next operation. If
687the contents of the register (or result of the '=' register evaluation) are
688not valid CTRL-X mode keys, then CTRL-X mode will be exited as if those keys
689had been typed.
690
691For example, the following will map <Tab> to either actually insert a <Tab> if
692the current line is currently only whitespace, or start/continue a CTRL-N
693completion operation: >
694
695 function! CleverTab()
696 if strpart( getline('.'), 0, col('.')-1 ) =~ '^\s*$'
697 return "\<Tab>"
698 else
699 return "\<C-N>"
Bram Moolenaarb52073a2010-03-17 20:02:06 +0100700 endif
Bram Moolenaar071d4272004-06-13 20:20:40 +0000701 endfunction
702 inoremap <Tab> <C-R>=CleverTab()<CR>
703
704
705
706Completing whole lines *compl-whole-line*
707
708 *i_CTRL-X_CTRL-L*
709CTRL-X CTRL-L Search backwards for a line that starts with the
Bram Moolenaar83bab712005-08-01 21:58:57 +0000710 same characters as those in the current line before
711 the cursor. Indent is ignored. The matching line is
Bram Moolenaar071d4272004-06-13 20:20:40 +0000712 inserted in front of the cursor.
Bram Moolenaar83bab712005-08-01 21:58:57 +0000713 The 'complete' option is used to decide which buffers
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +0000714 are searched for a match. Both loaded and unloaded
715 buffers are used.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000716 CTRL-L or
717 CTRL-P Search backwards for next matching line. This line
718 replaces the previous matching line.
719
720 CTRL-N Search forward for next matching line. This line
721 replaces the previous matching line.
722
723 CTRL-X CTRL-L After expanding a line you can additionally get the
724 line next to it by typing CTRL-X CTRL-L again, unless
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100725 a double CTRL-X is used. Only works for loaded
726 buffers.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000727
728Completing keywords in current file *compl-current*
729
730 *i_CTRL-X_CTRL-P*
731 *i_CTRL-X_CTRL-N*
732CTRL-X CTRL-N Search forwards for words that start with the keyword
733 in front of the cursor. The found keyword is inserted
734 in front of the cursor.
735
736CTRL-X CTRL-P Search backwards for words that start with the keyword
737 in front of the cursor. The found keyword is inserted
738 in front of the cursor.
739
740 CTRL-N Search forward for next matching keyword. This
741 keyword replaces the previous matching keyword.
742
743 CTRL-P Search backwards for next matching keyword. This
744 keyword replaces the previous matching keyword.
745
746 CTRL-X CTRL-N or
747 CTRL-X CTRL-P Further use of CTRL-X CTRL-N or CTRL-X CTRL-P will
748 copy the words following the previous expansion in
749 other contexts unless a double CTRL-X is used.
750
751If there is a keyword in front of the cursor (a name made out of alphabetic
752characters and characters in 'iskeyword'), it is used as the search pattern,
753with "\<" prepended (meaning: start of a word). Otherwise "\<\k\k" is used
754as search pattern (start of any keyword of at least two characters).
755
756In Replace mode, the number of characters that are replaced depends on the
757length of the matched string. This works like typing the characters of the
758matched string in Replace mode.
759
760If there is not a valid keyword character before the cursor, any keyword of
761at least two characters is matched.
762 e.g., to get:
763 printf("(%g, %g, %g)", vector[0], vector[1], vector[2]);
764 just type:
765 printf("(%g, %g, %g)", vector[0], ^P[1], ^P[2]);
766
Bram Moolenaarf75a9632005-09-13 21:20:47 +0000767The search wraps around the end of the file, the value of 'wrapscan' is not
768used here.
769
Bram Moolenaar071d4272004-06-13 20:20:40 +0000770Multiple repeats of the same completion are skipped; thus a different match
771will be inserted at each CTRL-N and CTRL-P (unless there is only one
772matching keyword).
773
774Single character matches are never included, as they usually just get in
775the way of what you were really after.
776 e.g., to get:
777 printf("name = %s\n", name);
778 just type:
779 printf("name = %s\n", n^P);
780 or even:
781 printf("name = %s\n", ^P);
782The 'n' in '\n' is skipped.
783
784After expanding a word, you can use CTRL-X CTRL-P or CTRL-X CTRL-N to get the
785word following the expansion in other contexts. These sequences search for
786the text just expanded and further expand by getting an extra word. This is
787useful if you need to repeat a sequence of complicated words. Although CTRL-P
788and CTRL-N look just for strings of at least two characters, CTRL-X CTRL-P and
789CTRL-X CTRL-N can be used to expand words of just one character.
790 e.g., to get:
791 M&eacute;xico
792 you can type:
793 M^N^P^X^P^X^P
794CTRL-N starts the expansion and then CTRL-P takes back the single character
795"M", the next two CTRL-X CTRL-P's get the words "&eacute" and ";xico".
796
797If the previous expansion was split, because it got longer than 'textwidth',
798then just the text in the current line will be used.
799
800If the match found is at the end of a line, then the first word in the next
801line will be inserted and the message "word from next line" displayed, if
802this word is accepted the next CTRL-X CTRL-P or CTRL-X CTRL-N will search
803for those lines starting with this word.
804
805
806Completing keywords in 'dictionary' *compl-dictionary*
807
808 *i_CTRL-X_CTRL-K*
809CTRL-X CTRL-K Search the files given with the 'dictionary' option
810 for words that start with the keyword in front of the
811 cursor. This is like CTRL-N, but only the dictionary
812 files are searched, not the current file. The found
813 keyword is inserted in front of the cursor. This
814 could potentially be pretty slow, since all matches
815 are found before the first match is used. By default,
816 the 'dictionary' option is empty.
817 For suggestions where to find a list of words, see the
818 'dictionary' option.
819
820 CTRL-K or
821 CTRL-N Search forward for next matching keyword. This
822 keyword replaces the previous matching keyword.
823
824 CTRL-P Search backwards for next matching keyword. This
825 keyword replaces the previous matching keyword.
826
Bram Moolenaarf4d8b762021-10-17 14:13:09 +0100827
828Completing words in 'thesaurus' *compl-thesaurus*
829
Bram Moolenaar071d4272004-06-13 20:20:40 +0000830 *i_CTRL-X_CTRL-T*
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000831CTRL-X CTRL-T Works as CTRL-X CTRL-K, but in a special way. It uses
Bram Moolenaar071d4272004-06-13 20:20:40 +0000832 the 'thesaurus' option instead of 'dictionary'. If a
833 match is found in the thesaurus file, all the
834 remaining words on the same line are included as
835 matches, even though they don't complete the word.
836 Thus a word can be completely replaced.
837
Bram Moolenaar071d4272004-06-13 20:20:40 +0000838 CTRL-T 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 +0100845In the file used by the 'thesaurus' option each line in the file should
846contain words with similar meaning, separated by non-keyword characters (white
847space is preferred). Maximum line length is 510 bytes.
848
849For an example, imagine the 'thesaurus' file has a line like this: >
850 angry furious mad enraged
851<Placing the cursor after the letters "ang" and typing CTRL-X CTRL-T would
852complete the word "angry"; subsequent presses would change the word to
853"furious", "mad" etc.
854
855Other uses include translation between two languages, or grouping API
856functions by keyword.
857
858An English word list was added to this github issue:
859https://github.com/vim/vim/issues/629#issuecomment-443293282
860Unpack thesaurus_pkg.zip, put the thesaurus.txt file somewhere, e.g.
861~/.vim/thesaurus/english.txt, and the 'thesaurus' option to this file name.
862
863
864Completing keywords with 'thesaurusfunc' *compl-thesaurusfunc*
865
866If the 'thesaurusfunc' option is set, then the user specified function is
867invoked to get the list of completion matches and the 'thesaurus' option is
868not used. See |complete-functions| for an explanation of how the function is
869invoked and what it should return.
870
871Here is an example that uses the "aiksaurus" command (provided by Magnus
872Groß): >
873
874 func Thesaur(findstart, base)
875 if a:findstart
876 let line = getline('.')
877 let start = col('.') - 1
878 while start > 0 && line[start - 1] =~ '\a'
879 let start -= 1
880 endwhile
881 return start
882 else
883 let res = []
884 let h = ''
885 for l in split(system('aiksaurus '.shellescape(a:base)), '\n')
886 if l[:3] == '=== '
887 let h = substitute(l[4:], ' =*$', '', '')
888 elseif l[0] =~ '\a'
889 call extend(res, map(split(l, ', '), {_, val -> {'word': val, 'menu': '('.h.')'}}))
890 endif
891 endfor
892 return res
893 endif
894 endfunc
895
Bram Moolenaar079ba762021-10-23 12:08:41 +0100896 if exists('+thesaurusfunc')
Bram Moolenaarf4d8b762021-10-17 14:13:09 +0100897 set thesaurusfunc=Thesaur
898 endif
899
Bram Moolenaar071d4272004-06-13 20:20:40 +0000900
901Completing keywords in the current and included files *compl-keyword*
902
903The 'include' option is used to specify a line that contains an include file
904name. The 'path' option is used to search for include files.
905
906 *i_CTRL-X_CTRL-I*
907CTRL-X CTRL-I Search for the first keyword in the current and
908 included files that starts with the same characters
909 as those before the cursor. The matched keyword is
910 inserted in front of the cursor.
911
912 CTRL-N Search forwards for next matching keyword. This
913 keyword replaces the previous matching keyword.
914 Note: CTRL-I is the same as <Tab>, which is likely to
915 be typed after a successful completion, therefore
916 CTRL-I is not used for searching for the next match.
917
918 CTRL-P Search backward for previous matching keyword. This
919 keyword replaces the previous matching keyword.
920
921 CTRL-X CTRL-I Further use of CTRL-X CTRL-I will copy the words
922 following the previous expansion in other contexts
923 unless a double CTRL-X is used.
924
925Completing tags *compl-tag*
926 *i_CTRL-X_CTRL-]*
927CTRL-X CTRL-] Search for the first tag that starts with the same
928 characters as before the cursor. The matching tag is
929 inserted in front of the cursor. Alphabetic
930 characters and characters in 'iskeyword' are used
931 to decide which characters are included in the tag
932 name (same as for a keyword). See also |CTRL-]|.
933 The 'showfulltag' option can be used to add context
934 from around the tag definition.
935 CTRL-] or
936 CTRL-N Search forwards for next matching tag. This tag
937 replaces the previous matching tag.
938
939 CTRL-P Search backward for previous matching tag. This tag
940 replaces the previous matching tag.
941
942
943Completing file names *compl-filename*
944 *i_CTRL-X_CTRL-F*
945CTRL-X CTRL-F Search for the first file name that starts with the
946 same characters as before the cursor. The matching
947 file name is inserted in front of the cursor.
948 Alphabetic characters and characters in 'isfname'
949 are used to decide which characters are included in
950 the file name. Note: the 'path' option is not used
951 here (yet).
952 CTRL-F or
953 CTRL-N Search forwards for next matching file name. This
954 file name replaces the previous matching file name.
955
956 CTRL-P Search backward for previous matching file name.
957 This file name replaces the previous matching file
958 name.
959
960
961Completing definitions or macros *compl-define*
962
963The 'define' option is used to specify a line that contains a definition.
964The 'include' option is used to specify a line that contains an include file
965name. The 'path' option is used to search for include files.
966
967 *i_CTRL-X_CTRL-D*
968CTRL-X CTRL-D Search in the current and included files for the
969 first definition (or macro) name that starts with
970 the same characters as before the cursor. The found
971 definition name is inserted in front of the cursor.
972 CTRL-D or
973 CTRL-N Search forwards for next matching macro name. This
974 macro name replaces the previous matching macro
975 name.
976
977 CTRL-P Search backward for previous matching macro name.
978 This macro name replaces the previous matching macro
979 name.
980
981 CTRL-X CTRL-D Further use of CTRL-X CTRL-D will copy the words
982 following the previous expansion in other contexts
983 unless a double CTRL-X is used.
984
985
986Completing Vim commands *compl-vim*
987
988Completion is context-sensitive. It works like on the Command-line. It
Bram Moolenaar4be06f92005-07-29 22:36:03 +0000989completes an Ex command as well as its arguments. This is useful when writing
990a Vim script.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000991
992 *i_CTRL-X_CTRL-V*
993CTRL-X CTRL-V Guess what kind of item is in front of the cursor and
994 find the first match for it.
995 Note: When CTRL-V is mapped you can often use CTRL-Q
Bram Moolenaar3577c6f2008-06-24 21:16:56 +0000996 instead of |i_CTRL-Q|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000997 CTRL-V or
998 CTRL-N Search forwards for next match. This match replaces
999 the previous one.
1000
Bram Moolenaar3577c6f2008-06-24 21:16:56 +00001001 CTRL-P Search backwards for previous match. This match
Bram Moolenaar071d4272004-06-13 20:20:40 +00001002 replaces the previous one.
1003
1004 CTRL-X CTRL-V Further use of CTRL-X CTRL-V will do the same as
1005 CTRL-V. This allows mapping a key to do Vim command
1006 completion, for example: >
1007 :imap <Tab> <C-X><C-V>
1008
Bram Moolenaar4be06f92005-07-29 22:36:03 +00001009User defined completion *compl-function*
Bram Moolenaarcfbc5ee2004-07-02 15:38:35 +00001010
1011Completion is done by a function that can be defined by the user with the
Bram Moolenaar280f1262006-01-30 00:14:18 +00001012'completefunc' option. See below for how the function is called and an
1013example |complete-functions|.
Bram Moolenaarcfbc5ee2004-07-02 15:38:35 +00001014
1015 *i_CTRL-X_CTRL-U*
1016CTRL-X CTRL-U Guess what kind of item is in front of the cursor and
1017 find the first match for it.
1018 CTRL-U or
1019 CTRL-N Use the next match. This match replaces the previous
1020 one.
1021
1022 CTRL-P Use the previous match. This match replaces the
1023 previous one.
1024
1025
Bram Moolenaarf75a9632005-09-13 21:20:47 +00001026Omni completion *compl-omni*
Bram Moolenaar4be06f92005-07-29 22:36:03 +00001027
Bram Moolenaare344bea2005-09-01 20:46:49 +00001028Completion is done by a function that can be defined by the user with the
Bram Moolenaarf75a9632005-09-13 21:20:47 +00001029'omnifunc' option. This is to be used for filetype-specific completion.
Bram Moolenaare344bea2005-09-01 20:46:49 +00001030
Bram Moolenaar280f1262006-01-30 00:14:18 +00001031See below for how the function is called and an example |complete-functions|.
Bram Moolenaarf75a9632005-09-13 21:20:47 +00001032For remarks about specific filetypes see |compl-omni-filetypes|.
Bram Moolenaar9c102382006-05-03 21:26:49 +00001033More completion scripts will appear, check www.vim.org. Currently there is a
1034first version for C++.
Bram Moolenaar4be06f92005-07-29 22:36:03 +00001035
1036 *i_CTRL-X_CTRL-O*
1037CTRL-X CTRL-O Guess what kind of item is in front of the cursor and
1038 find the first match for it.
1039 CTRL-O or
1040 CTRL-N Use the next match. This match replaces the previous
1041 one.
1042
1043 CTRL-P Use the previous match. This match replaces the
1044 previous one.
1045
1046
Bram Moolenaar488c6512005-08-11 20:09:58 +00001047Spelling suggestions *compl-spelling*
1048
Bram Moolenaar5195e452005-08-19 20:32:47 +00001049A word before or at the cursor is located and correctly spelled words are
1050suggested to replace it. If there is a badly spelled word in the line, before
1051or under the cursor, the cursor is moved to after it. Otherwise the word just
1052before the cursor is used for suggestions, even though it isn't badly spelled.
1053
Bram Moolenaar488c6512005-08-11 20:09:58 +00001054NOTE: CTRL-S suspends display in many Unix terminals. Use 's' instead. Type
1055CTRL-Q to resume displaying.
1056
1057 *i_CTRL-X_CTRL-S* *i_CTRL-X_s*
1058CTRL-X CTRL-S or
1059CTRL-X s Locate the word in front of the cursor and find the
1060 first spell suggestion for it.
1061 CTRL-S or
1062 CTRL-N Use the next suggestion. This replaces the previous
1063 one. Note that you can't use 's' here.
1064
1065 CTRL-P Use the previous suggestion. This replaces the
1066 previous one.
1067
1068
Bram Moolenaar071d4272004-06-13 20:20:40 +00001069Completing keywords from different sources *compl-generic*
1070
1071 *i_CTRL-N*
1072CTRL-N Find next match for words that start with the
1073 keyword in front of the cursor, looking in places
1074 specified with the 'complete' option. The found
1075 keyword is inserted in front of the cursor.
1076
1077 *i_CTRL-P*
1078CTRL-P Find previous match for words that start with the
1079 keyword in front of the cursor, looking in places
1080 specified with the 'complete' option. The found
1081 keyword is inserted in front of the cursor.
1082
1083 CTRL-N Search forward for next matching keyword. This
1084 keyword replaces the previous matching keyword.
1085
1086 CTRL-P Search backwards for next matching keyword. This
1087 keyword replaces the previous matching keyword.
1088
1089 CTRL-X CTRL-N or
1090 CTRL-X CTRL-P Further use of CTRL-X CTRL-N or CTRL-X CTRL-P will
1091 copy the words following the previous expansion in
1092 other contexts unless a double CTRL-X is used.
1093
Bram Moolenaar578b49e2005-09-10 19:22:57 +00001094
zeertzjqdca29d92021-08-31 19:12:51 +02001095Stop completion *compl-stop*
1096
1097 *i_CTRL-X_CTRL-Z*
1098CTRL-X CTRL-Z Stop completion without changing the text.
1099
1100
Bram Moolenaar280f1262006-01-30 00:14:18 +00001101FUNCTIONS FOR FINDING COMPLETIONS *complete-functions*
1102
Yegappan Lakshmanan160e9942021-10-16 15:41:29 +01001103This applies to 'completefunc', 'thesaurusfunc' and 'omnifunc'.
Bram Moolenaar280f1262006-01-30 00:14:18 +00001104
Bram Moolenaar8b6144b2006-02-08 09:20:24 +00001105The function is called in two different ways:
1106- First the function is called to find the start of the text to be completed.
1107- Later the function is called to actually find the matches.
Bram Moolenaar280f1262006-01-30 00:14:18 +00001108
1109On the first invocation the arguments are:
1110 a:findstart 1
1111 a:base empty
1112
Bram Moolenaar8b6144b2006-02-08 09:20:24 +00001113The function must return the column where the completion starts. It must be a
1114number between zero and the cursor column "col('.')". This involves looking
1115at the characters just before the cursor and including those characters that
1116could be part of the completed item. The text between this column and the
Bram Moolenaarfc65cab2018-08-28 22:58:02 +02001117cursor column will be replaced with the matches. If the returned value is
1118larger than the cursor column, the cursor column is used.
Bram Moolenaar8e52a592012-05-18 21:49:28 +02001119
Bram Moolenaarfc65cab2018-08-28 22:58:02 +02001120Negative return values:
1121 -2 To cancel silently and stay in completion mode.
1122 -3 To cancel silently and leave completion mode.
1123 Another negative value: completion starts at the cursor column
Bram Moolenaar280f1262006-01-30 00:14:18 +00001124
1125On the second invocation the arguments are:
1126 a:findstart 0
Bram Moolenaar8b6144b2006-02-08 09:20:24 +00001127 a:base the text with which matches should match; the text that was
Bram Moolenaar280f1262006-01-30 00:14:18 +00001128 located in the first call (can be empty)
1129
1130The function must return a List with the matching words. These matches
1131usually include the "a:base" text. When there are no matches return an empty
Bram Moolenaar90df4b92021-07-07 20:26:08 +02001132List. Note that the cursor may have moved since the first invocation, the
1133text may have been changed.
Bram Moolenaar5302d9e2011-09-14 17:55:08 +02001134
1135In order to return more information than the matching words, return a Dict
1136that contains the List. The Dict can have these items:
1137 words The List of matching words (mandatory).
1138 refresh A string to control re-invocation of the function
1139 (optional).
1140 The only value currently recognized is "always", the
1141 effect is that the function is called whenever the
1142 leading text is changed.
Bram Moolenaarcee9bc22019-01-11 13:02:23 +01001143
1144If you want to suppress the warning message for an empty result, return
Bram Moolenaar314dd792019-02-03 15:27:20 +01001145|v:none|. This is useful to implement asynchronous completion with
1146|complete()|.
Bram Moolenaarcee9bc22019-01-11 13:02:23 +01001147
Bram Moolenaar5302d9e2011-09-14 17:55:08 +02001148Other items are ignored.
1149
Bram Moolenaar560979e2020-02-04 22:53:05 +01001150For acting upon end of completion, see the |CompleteDonePre| and
1151|CompleteDone| autocommand event.
Bram Moolenaar30b65812012-07-12 22:01:11 +02001152
Bram Moolenaar5302d9e2011-09-14 17:55:08 +02001153For example, the function can contain this: >
1154 let matches = ... list of words ...
1155 return {'words': matches, 'refresh': 'always'}
1156<
Bram Moolenaar5c4bab02006-03-10 21:37:46 +00001157 *complete-items*
Bram Moolenaar8b6144b2006-02-08 09:20:24 +00001158Each list item can either be a string or a Dictionary. When it is a string it
1159is used as the completion. When it is a Dictionary it can contain these
1160items:
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001161 word the text that will be inserted, mandatory
1162 abbr abbreviation of "word"; when not empty it is used in
1163 the menu instead of "word"
Bram Moolenaar8dff8182006-04-06 20:18:50 +00001164 menu extra text for the popup menu, displayed after "word"
1165 or "abbr"
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001166 info more information about the item, can be displayed in a
Bram Moolenaar62a0cb42019-08-18 16:35:23 +02001167 preview or popup window
Bram Moolenaar8b6144b2006-02-08 09:20:24 +00001168 kind single letter indicating the type of completion
Bram Moolenaar91170f82006-05-05 21:15:17 +00001169 icase when non-zero case is to be ignored when comparing
1170 items to be equal; when omitted zero is used, thus
1171 items that only differ in case are added
Bram Moolenaar73655cf2019-04-06 13:45:55 +02001172 equal when non-zero, always treat this item to be equal when
1173 comparing. Which means, "equal=1" disables filtering
1174 of this item.
Bram Moolenaar4a85b412006-04-23 22:40:29 +00001175 dup when non-zero this match will be added even when an
1176 item with the same word is already present.
Bram Moolenaar166af9b2010-11-16 20:34:40 +01001177 empty when non-zero this match will be added even when it is
1178 an empty string
Bram Moolenaar9b56a572018-02-10 16:19:32 +01001179 user_data custom data which is associated with the item and
Bram Moolenaar08928322020-01-04 14:32:48 +01001180 available in |v:completed_item|; it can be any type;
1181 defaults to an empty string
Bram Moolenaar8b6144b2006-02-08 09:20:24 +00001182
Bram Moolenaar73655cf2019-04-06 13:45:55 +02001183All of these except "icase", "equal", "dup" and "empty" must be a string. If
1184an item does not meet these requirements then an error message is given and
1185further items in the list are not used. You can mix string and Dictionary
1186items in the returned list.
Bram Moolenaar8b6144b2006-02-08 09:20:24 +00001187
1188The "menu" item is used in the popup menu and may be truncated, thus it should
Bram Moolenaar0b598c22006-03-11 21:22:53 +00001189be relatively short. The "info" item can be longer, it will be displayed in
Bram Moolenaar62a0cb42019-08-18 16:35:23 +02001190the preview window when "preview" appears in 'completeopt' or in a popup
1191window when "popup" appears in 'completeopt'. In the preview window the
1192"info" item will also remain displayed after the popup menu has been removed.
1193This is useful for function arguments. Use a single space for "info" to
1194remove existing text in the preview window. The size of the preview window is
1195three lines, but 'previewheight' is used when it has a value of 1 or 2.
1196
1197 *complete-popup*
1198When "popup" is in 'completeopt' a popup window is used to display the "info".
Bram Moolenaar06fe74a2019-08-31 16:20:32 +02001199Then the 'completepopup' option specifies the properties of the popup. This
1200is used when the info popup is created. The option is a comma separated list
1201of values:
Bram Moolenaar62a0cb42019-08-18 16:35:23 +02001202 height maximum height of the popup
1203 width maximum width of the popup
Bram Moolenaar8fe10002019-09-11 22:56:44 +02001204 highlight highlight group of the popup (default is PmenuSel)
Bram Moolenaar258cef52019-08-21 17:29:29 +02001205 align "item" (default) or "menu"
1206 border "on" (default) or "off"
Bram Moolenaar62a0cb42019-08-18 16:35:23 +02001207Example: >
1208 :set completepopup=height:10,width:60,highlight:InfoPopup
Bram Moolenaar8b6144b2006-02-08 09:20:24 +00001209
Bram Moolenaar06fe74a2019-08-31 16:20:32 +02001210When the "align" value is "item" then the popup is positioned close to the
Bram Moolenaar258cef52019-08-21 17:29:29 +02001211selected item. Changing the selection will also move the popup. When "align"
1212is "menu" then the popup is aligned with the top of the menu if the menu is
1213below the text, and the bottom of the menu otherwise.
1214
Bram Moolenaar06fe74a2019-08-31 16:20:32 +02001215After the info popup is created it can be found with |popup_findinfo()| and
1216properties can be changed with |popup_setoptions()|.
1217
Bram Moolenaardca7abe2019-10-20 18:17:57 +02001218 *complete-popuphidden*
1219If the information for the popup is obtained asynchronously, use "popuphidden"
Bram Moolenaar91359012019-11-30 17:57:03 +01001220in 'completeopt'. The info popup will then be initially hidden and
Bram Moolenaardca7abe2019-10-20 18:17:57 +02001221|popup_show()| must be called once it has been filled with the info. This can
1222be done with a |CompleteChanged| autocommand, something like this: >
1223 set completeopt+=popuphidden
1224 au CompleteChanged * call UpdateCompleteInfo()
1225 func UpdateCompleteInfo()
1226 " Cancel any pending info fetch
1227 let item = v:event.completed_item
1228 " Start fetching info for the item then call ShowCompleteInfo(info)
1229 endfunc
1230 func ShowCompleteInfo(info)
1231 let id = popup_findinfo()
1232 if id
1233 call popup_settext(id, 'async info: ' .. a:info)
1234 call popup_show(id)
1235 endif
1236 endfunc
1237
1238< *complete-item-kind*
Bram Moolenaar8b6144b2006-02-08 09:20:24 +00001239The "kind" item uses a single letter to indicate the kind of completion. This
1240may be used to show the completion differently (different color or icon).
1241Currently these types can be used:
1242 v variable
1243 f function or method
Bram Moolenaar0b598c22006-03-11 21:22:53 +00001244 m member of a struct or class
1245 t typedef
1246 d #define or macro
Bram Moolenaar280f1262006-01-30 00:14:18 +00001247
1248When searching for matches takes some time call |complete_add()| to add each
1249match to the total list. These matches should then not appear in the returned
1250list! Call |complete_check()| now and then to allow the user to press a key
1251while still searching for matches. Stop searching when it returns non-zero.
1252
Bram Moolenaar6aa57292021-08-14 21:25:52 +02001253 *E840*
Bram Moolenaar166af9b2010-11-16 20:34:40 +01001254The function is allowed to move the cursor, it is restored afterwards.
1255The function is not allowed to move to another window or delete text.
Bram Moolenaar280f1262006-01-30 00:14:18 +00001256
1257An example that completes the names of the months: >
1258 fun! CompleteMonths(findstart, base)
1259 if a:findstart
1260 " locate the start of the word
1261 let line = getline('.')
1262 let start = col('.') - 1
1263 while start > 0 && line[start - 1] =~ '\a'
1264 let start -= 1
1265 endwhile
1266 return start
1267 else
1268 " find months matching with "a:base"
1269 let res = []
1270 for m in split("Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec")
1271 if m =~ '^' . a:base
1272 call add(res, m)
1273 endif
1274 endfor
1275 return res
1276 endif
1277 endfun
1278 set completefunc=CompleteMonths
1279<
1280The same, but now pretending searching for matches is slow: >
1281 fun! CompleteMonths(findstart, base)
1282 if a:findstart
1283 " locate the start of the word
1284 let line = getline('.')
1285 let start = col('.') - 1
1286 while start > 0 && line[start - 1] =~ '\a'
1287 let start -= 1
1288 endwhile
1289 return start
1290 else
1291 " find months matching with "a:base"
1292 for m in split("Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec")
1293 if m =~ '^' . a:base
1294 call complete_add(m)
1295 endif
1296 sleep 300m " simulate searching for next match
1297 if complete_check()
1298 break
1299 endif
1300 endfor
1301 return []
1302 endif
1303 endfun
1304 set completefunc=CompleteMonths
1305<
1306
Bram Moolenaar1c7715d2005-10-03 22:02:18 +00001307INSERT COMPLETION POPUP MENU *ins-completion-menu*
Bram Moolenaarebefac62005-12-28 22:39:57 +00001308 *popupmenu-completion*
Bram Moolenaar1c7715d2005-10-03 22:02:18 +00001309Vim can display the matches in a simplistic popup menu.
1310
1311The menu is used when:
Bram Moolenaara2031822006-03-07 22:29:51 +00001312- The 'completeopt' option contains "menu" or "menuone".
Bram Moolenaar1c7715d2005-10-03 22:02:18 +00001313- The terminal supports at least 8 colors.
Bram Moolenaard68071d2006-05-02 22:08:30 +00001314- There are at least two matches. One if "menuone" is used.
Bram Moolenaar1c7715d2005-10-03 22:02:18 +00001315
Bram Moolenaar56718732006-03-15 22:53:57 +00001316The 'pumheight' option can be used to set a maximum height. The default is to
1317use all space available.
Bram Moolenaar9b56a572018-02-10 16:19:32 +01001318The 'pumwidth' option can be used to set a minimum width. The default is 15
1319characters.
Bram Moolenaar56718732006-03-15 22:53:57 +00001320
Bram Moolenaar779b74b2006-04-10 14:55:34 +00001321There are three states:
13221. A complete match has been inserted, e.g., after using CTRL-N or CTRL-P.
13232. A cursor key has been used to select another match. The match was not
1324 inserted then, only the entry in the popup menu is highlighted.
13253. Only part of a match has been inserted and characters were typed or the
1326 backspace key was used. The list of matches was then adjusted for what is
1327 in front of the cursor.
Bram Moolenaarc7453f52006-02-10 23:20:28 +00001328
Bram Moolenaar80a94a52006-02-23 21:26:58 +00001329You normally start in the first state, with the first match being inserted.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001330When "longest" is in 'completeopt' and there is more than one match you start
Bram Moolenaar779b74b2006-04-10 14:55:34 +00001331in the third state.
Bram Moolenaarc7453f52006-02-10 23:20:28 +00001332
Bram Moolenaar779b74b2006-04-10 14:55:34 +00001333If you select another match, e.g., with CTRL-N or CTRL-P, you go to the first
1334state. This doesn't change the list of matches.
Bram Moolenaar80a94a52006-02-23 21:26:58 +00001335
Bram Moolenaar779b74b2006-04-10 14:55:34 +00001336When you are back at the original text then you are in the third state. To
Bram Moolenaara2031822006-03-07 22:29:51 +00001337get there right away you can use a mapping that uses CTRL-P right after
1338starting the completion: >
1339 :imap <F7> <C-N><C-P>
Bram Moolenaar76916e62006-03-21 21:23:25 +00001340<
1341 *popupmenu-keys*
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001342In the first state these keys have a special meaning:
1343<BS> and CTRL-H Delete one character, find the matches for the word before
1344 the cursor. This reduces the list of matches, often to one
Bram Moolenaar80a94a52006-02-23 21:26:58 +00001345 entry, and switches to the second state.
Bram Moolenaar779b74b2006-04-10 14:55:34 +00001346Any non-special character:
1347 Stop completion without changing the match and insert the
1348 typed character.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001349
Bram Moolenaar779b74b2006-04-10 14:55:34 +00001350In the second and third state these keys have a special meaning:
Bram Moolenaar8b6144b2006-02-08 09:20:24 +00001351<BS> and CTRL-H Delete one character, find the matches for the shorter word
1352 before the cursor. This may find more matches.
1353CTRL-L Add one character from the current match, may reduce the
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001354 number of matches.
Bram Moolenaar80a94a52006-02-23 21:26:58 +00001355any printable, non-white character:
1356 Add this character and reduce the number of matches.
Bram Moolenaarc7453f52006-02-10 23:20:28 +00001357
Bram Moolenaar779b74b2006-04-10 14:55:34 +00001358In all three states these can be used:
Bram Moolenaard2cec5b2006-03-28 21:08:56 +00001359CTRL-Y Yes: Accept the currently selected match and stop completion.
Bram Moolenaar9964e462007-05-05 17:54:07 +00001360CTRL-E End completion, go back to what was there before selecting a
1361 match (what was typed or longest common string).
Bram Moolenaar80a94a52006-02-23 21:26:58 +00001362<PageUp> Select a match several entries back, but don't insert it.
1363<PageDown> Select a match several entries further, but don't insert it.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001364<Up> Select the previous match, as if CTRL-P was used, but don't
Bram Moolenaar80a94a52006-02-23 21:26:58 +00001365 insert it.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001366<Down> Select the next match, as if CTRL-N was used, but don't
Bram Moolenaar80a94a52006-02-23 21:26:58 +00001367 insert it.
Bram Moolenaar9964e462007-05-05 17:54:07 +00001368<Space> or <Tab> Stop completion without changing the match and insert the
Bram Moolenaar779b74b2006-04-10 14:55:34 +00001369 typed character.
1370
Bram Moolenaar044b68f2007-05-10 17:39:52 +00001371The behavior of the <Enter> key depends on the state you are in:
Bram Moolenaar779b74b2006-04-10 14:55:34 +00001372first state: Use the text as it is and insert a line break.
1373second state: Insert the currently selected match.
1374third state: Use the text as it is and insert a line break.
1375
1376In other words: If you used the cursor keys to select another entry in the
Bram Moolenaar044b68f2007-05-10 17:39:52 +00001377list of matches then the <Enter> key inserts that match. If you typed
1378something else then <Enter> inserts a line break.
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001379
Bram Moolenaar1c7715d2005-10-03 22:02:18 +00001380
1381The colors of the menu can be changed with these highlight groups:
1382Pmenu normal item |hl-Pmenu|
1383PmenuSel selected item |hl-PmenuSel|
1384PmenuSbar scrollbar |hl-PmenuSbar|
1385PmenuThumb thumb of the scrollbar |hl-PmenuThumb|
1386
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001387There are no special mappings for when the popup menu is visible. However,
1388you can use an Insert mode mapping that checks the |pumvisible()| function to
1389do something different. Example: >
1390 :inoremap <Down> <C-R>=pumvisible() ? "\<lt>C-N>" : "\<lt>Down>"<CR>
Bram Moolenaar1c7715d2005-10-03 22:02:18 +00001391
Bram Moolenaar5c4bab02006-03-10 21:37:46 +00001392You can use of <expr> in mapping to have the popup menu used when typing a
1393character and some condition is met. For example, for typing a dot: >
1394 inoremap <expr> . MayComplete()
1395 func MayComplete()
1396 if (can complete)
1397 return ".\<C-X>\<C-O>"
1398 endif
1399 return '.'
1400 endfunc
1401
1402See |:map-<expr>| for more info.
1403
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001404
1405FILETYPE-SPECIFIC REMARKS FOR OMNI COMPLETION *compl-omni-filetypes*
1406
1407The file used for {filetype} should be autoload/{filetype}complete.vim
1408in 'runtimepath'. Thus for "java" it is autoload/javacomplete.vim.
Bram Moolenaar578b49e2005-09-10 19:22:57 +00001409
Bram Moolenaara5792f52005-11-23 21:25:05 +00001410
Bram Moolenaarf75a9632005-09-13 21:20:47 +00001411C *ft-c-omni*
Bram Moolenaar578b49e2005-09-10 19:22:57 +00001412
Bram Moolenaarf75a9632005-09-13 21:20:47 +00001413Completion of C code requires a tags file. You should use Exuberant ctags,
1414because it adds extra information that is needed for completion. You can find
Bram Moolenaar9964e462007-05-05 17:54:07 +00001415it here: http://ctags.sourceforge.net/ Version 5.6 or later is recommended.
1416
Bram Moolenaarf75a9632005-09-13 21:20:47 +00001417For version 5.5.4 you should add a patch that adds the "typename:" field:
Bram Moolenaar36fc5352006-03-04 21:49:37 +00001418 ftp://ftp.vim.org/pub/vim/unstable/patches/ctags-5.5.4.patch
Bram Moolenaar8b6144b2006-02-08 09:20:24 +00001419A compiled .exe for MS-Windows can be found at:
Bram Moolenaar2f058492017-11-30 20:27:52 +01001420 http://ctags.sourceforge.net/
1421 https://github.com/universal-ctags/ctags-win32
Bram Moolenaar578b49e2005-09-10 19:22:57 +00001422
1423If you want to complete system functions you can do something like this. Use
1424ctags to generate a tags file for all the system header files: >
1425 % ctags -R -f ~/.vim/systags /usr/include /usr/local/include
1426In your vimrc file add this tags file to the 'tags' option: >
1427 set tags+=~/.vim/systags
1428
1429When using CTRL-X CTRL-O after a name without any "." or "->" it is completed
1430from the tags file directly. This works for any identifier, also function
1431names. If you want to complete a local variable name, which does not appear
1432in the tags file, use CTRL-P instead.
1433
1434When using CTRL-X CTRL-O after something that has "." or "->" Vim will attempt
1435to recognize the type of the variable and figure out what members it has.
1436This means only members valid for the variable will be listed.
1437
Bram Moolenaarf75a9632005-09-13 21:20:47 +00001438When a member name already was complete, CTRL-X CTRL-O will add a "." or
1439"->" for composite types.
1440
Bram Moolenaar578b49e2005-09-10 19:22:57 +00001441Vim doesn't include a C compiler, only the most obviously formatted
1442declarations are recognized. Preprocessor stuff may cause confusion.
1443When the same structure name appears in multiple places all possible members
1444are included.
1445
Bram Moolenaar6b730e12005-09-16 21:47:57 +00001446
Bram Moolenaar4770d092006-01-12 23:22:24 +00001447CSS *ft-css-omni*
Bram Moolenaara5792f52005-11-23 21:25:05 +00001448
1449Complete properties and their appropriate values according to CSS 2.1
Bram Moolenaare2f98b92006-03-29 21:18:24 +00001450specification.
Bram Moolenaara5792f52005-11-23 21:25:05 +00001451
1452
Bram Moolenaare2f98b92006-03-29 21:18:24 +00001453HTML *ft-html-omni*
1454XHTML *ft-xhtml-omni*
Bram Moolenaar6b730e12005-09-16 21:47:57 +00001455
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001456CTRL-X CTRL-O provides completion of various elements of (X)HTML files. It is
Bram Moolenaardb6ea062014-07-10 22:01:47 +02001457designed to support writing of XHTML 1.0 Strict files but will also work for
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001458other versions of HTML. Features:
Bram Moolenaar6b730e12005-09-16 21:47:57 +00001459
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001460- after "<" complete tag name depending on context (no div suggestion inside
1461 of an a tag); '/>' indicates empty tags
1462- inside of tag complete proper attributes (no width attribute for an a tag);
1463 show also type of attribute; '*' indicates required attributes
1464- when attribute has limited number of possible values help to complete them
Bram Moolenaara5792f52005-11-23 21:25:05 +00001465- complete names of entities
Bram Moolenaar1e015462005-09-25 22:16:38 +00001466- complete values of "class" and "id" attributes with data obtained from
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001467 <style> tag and included CSS files
Bram Moolenaar8b6144b2006-02-08 09:20:24 +00001468- when completing value of "style" attribute or working inside of "style" tag
Bram Moolenaar1e015462005-09-25 22:16:38 +00001469 switch to |ft-css-omni| completion
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001470- when completing values of events attributes or working inside of "script"
1471 tag switch to |ft-javascript-omni| completion
Bram Moolenaar1e015462005-09-25 22:16:38 +00001472- when used after "</" CTRL-X CTRL-O will close the last opened tag
Bram Moolenaar6b730e12005-09-16 21:47:57 +00001473
Bram Moolenaara5792f52005-11-23 21:25:05 +00001474Note: When used first time completion menu will be shown with little delay
Bram Moolenaare2f98b92006-03-29 21:18:24 +00001475- this is time needed for loading of data file.
Bram Moolenaar8b6144b2006-02-08 09:20:24 +00001476Note: Completion may fail in badly formatted documents. In such case try to
1477run |:make| command to detect formatting problems.
Bram Moolenaara5792f52005-11-23 21:25:05 +00001478
1479
Bram Moolenaarc1e37902006-04-18 21:55:01 +00001480HTML flavor *html-flavor*
1481
Bram Moolenaar9c102382006-05-03 21:26:49 +00001482The default HTML completion depends on the filetype. For HTML files it is
1483HTML 4.01 Transitional ('filetype' is "html"), for XHTML it is XHTML 1.0
1484Strict ('filetype' is "xhtml").
Bram Moolenaarc1e37902006-04-18 21:55:01 +00001485
Bram Moolenaar9c102382006-05-03 21:26:49 +00001486When doing completion outside of any other tag you will have possibility to
1487choose DOCTYPE and the appropriate data file will be loaded and used for all
1488next completions.
Bram Moolenaarc1e37902006-04-18 21:55:01 +00001489
Bram Moolenaar9c102382006-05-03 21:26:49 +00001490More about format of data file in |xml-omni-datafile|. Some of the data files
1491may be found on the Vim website (|www|).
Bram Moolenaarc1e37902006-04-18 21:55:01 +00001492
Bram Moolenaar9c102382006-05-03 21:26:49 +00001493Note that b:html_omni_flavor may point to a file with any XML data. This
1494makes possible to mix PHP (|ft-php-omni|) completion with any XML dialect
1495(assuming you have data file for it). Without setting that variable XHTML 1.0
1496Strict will be used.
Bram Moolenaarc1e37902006-04-18 21:55:01 +00001497
1498
Bram Moolenaare2f98b92006-03-29 21:18:24 +00001499JAVASCRIPT *ft-javascript-omni*
Bram Moolenaarb8a7b562006-02-01 21:47:16 +00001500
Bram Moolenaar8b6144b2006-02-08 09:20:24 +00001501Completion of most elements of JavaScript language and DOM elements.
Bram Moolenaarb8a7b562006-02-01 21:47:16 +00001502
1503Complete:
1504
1505- variables
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001506- function name; show function arguments
Bram Moolenaarb8a7b562006-02-01 21:47:16 +00001507- function arguments
1508- properties of variables trying to detect type of variable
Bram Moolenaar8b6144b2006-02-08 09:20:24 +00001509- complete DOM objects and properties depending on context
Bram Moolenaarb8a7b562006-02-01 21:47:16 +00001510- keywords of language
1511
Bram Moolenaar8b6144b2006-02-08 09:20:24 +00001512Completion works in separate JavaScript files (&ft==javascript), inside of
1513<script> tag of (X)HTML and in values of event attributes (including scanning
Bram Moolenaar9ba7e172013-07-17 22:37:26 +02001514of external files).
Bram Moolenaare2f98b92006-03-29 21:18:24 +00001515
Bram Moolenaarb8a7b562006-02-01 21:47:16 +00001516DOM compatibility
1517
1518At the moment (beginning of 2006) there are two main browsers - MS Internet
1519Explorer and Mozilla Firefox. These two applications are covering over 90% of
1520market. Theoretically standards are created by W3C organisation
1521(http://www.w3c.org) but they are not always followed/implemented.
1522
Bram Moolenaare2f98b92006-03-29 21:18:24 +00001523 IE FF W3C Omni completion ~
1524 +/- +/- + + ~
1525 + + - + ~
1526 + - - - ~
1527 - + - - ~
Bram Moolenaarb8a7b562006-02-01 21:47:16 +00001528
1529Regardless from state of implementation in browsers but if element is defined
1530in standards, completion plugin will place element in suggestion list. When
1531both major engines implemented element, even if this is not in standards it
1532will be suggested. All other elements are not placed in suggestion list.
1533
1534
Bram Moolenaare2f98b92006-03-29 21:18:24 +00001535PHP *ft-php-omni*
Bram Moolenaar362e1a32006-03-06 23:29:24 +00001536
Bram Moolenaar9964e462007-05-05 17:54:07 +00001537Completion of PHP code requires a tags file for completion of data from
1538external files and for class aware completion. You should use Exuberant ctags
1539version 5.5.4 or newer. You can find it here: http://ctags.sourceforge.net/
Bram Moolenaar362e1a32006-03-06 23:29:24 +00001540
1541Script completes:
1542
1543- after $ variables name
Bram Moolenaar0b598c22006-03-11 21:22:53 +00001544 - if variable was declared as object add "->", if tags file is available show
1545 name of class
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001546 - after "->" complete only function and variable names specific for given
1547 class. To find class location and contents tags file is required. Because
1548 PHP isn't strongly typed language user can use @var tag to declare class: >
1549
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001550 /* @var $myVar myClass */
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001551 $myVar->
1552<
1553 Still, to find myClass contents tags file is required.
Bram Moolenaar0b598c22006-03-11 21:22:53 +00001554
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00001555- function names with additional info:
Bram Moolenaar0b598c22006-03-11 21:22:53 +00001556 - in case of built-in functions list of possible arguments and after | type
1557 data returned by function
Bram Moolenaar06b5d512010-05-22 15:37:44 +02001558 - in case of user function arguments and name of file where function was
Bram Moolenaar0b598c22006-03-11 21:22:53 +00001559 defined (if it is not current file)
1560
1561- constants names
1562- class names after "new" declaration
1563
Bram Moolenaar362e1a32006-03-06 23:29:24 +00001564
1565Note: when doing completion first time Vim will load all necessary data into
1566memory. It may take several seconds. After next use of completion delay
Bram Moolenaar0b598c22006-03-11 21:22:53 +00001567should not be noticeable.
Bram Moolenaar362e1a32006-03-06 23:29:24 +00001568
1569Script detects if cursor is inside <?php ?> tags. If it is outside it will
1570automatically switch to HTML/CSS/JavaScript completion. Note: contrary to
1571original HTML files completion of tags (and only tags) isn't context aware.
1572
1573
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001574RUBY *ft-ruby-omni*
Bram Moolenaarfc1421e2006-04-20 22:17:20 +00001575
1576Completion of Ruby code requires that vim be built with |+ruby|.
1577
1578Ruby completion will parse your buffer on demand in order to provide a list of
1579completions. These completions will be drawn from modules loaded by 'require'
1580and modules defined in the current buffer.
1581
1582The completions provided by CTRL-X CTRL-O are sensitive to the context:
1583
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001584 CONTEXT COMPLETIONS PROVIDED ~
Bram Moolenaarfc1421e2006-04-20 22:17:20 +00001585
1586 1. Not inside a class definition Classes, constants and globals
1587
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001588 2. Inside a class definition Methods or constants defined in the class
Bram Moolenaarfc1421e2006-04-20 22:17:20 +00001589
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001590 3. After '.', '::' or ':' Methods applicable to the object being
1591 dereferenced
Bram Moolenaarfc1421e2006-04-20 22:17:20 +00001592
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001593 4. After ':' or ':foo' Symbol name (beginning with 'foo')
Bram Moolenaarfc1421e2006-04-20 22:17:20 +00001594
1595Notes:
1596 - Vim will load/evaluate code in order to provide completions. This may
Bram Moolenaar40962ec2018-01-28 22:47:25 +01001597 cause some code execution, which may be a concern. This is no longer
Bram Moolenaar9964e462007-05-05 17:54:07 +00001598 enabled by default, to enable this feature add >
1599 let g:rubycomplete_buffer_loading = 1
1600<- In context 1 above, Vim can parse the entire buffer to add a list of
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00001601 classes to the completion results. This feature is turned off by default,
1602 to enable it add >
1603 let g:rubycomplete_classes_in_global = 1
1604< to your vimrc
Bram Moolenaarfc1421e2006-04-20 22:17:20 +00001605 - In context 2 above, anonymous classes are not supported.
1606 - In context 3 above, Vim will attempt to determine the methods supported by
1607 the object.
1608 - Vim can detect and load the Rails environment for files within a rails
1609 project. The feature is disabled by default, to enable it add >
Bram Moolenaar551dbcc2006-04-25 22:13:59 +00001610 let g:rubycomplete_rails = 1
1611< to your vimrc
Bram Moolenaarfc1421e2006-04-20 22:17:20 +00001612
1613
Bram Moolenaar4770d092006-01-12 23:22:24 +00001614SYNTAX *ft-syntax-omni*
1615
Bram Moolenaar9964e462007-05-05 17:54:07 +00001616Vim has the ability to color syntax highlight nearly 500 languages. Part of
1617this highlighting includes knowing what keywords are part of a language. Many
1618filetypes already have custom completion scripts written for them, the
1619syntaxcomplete plugin provides basic completion for all other filetypes. It
1620does this by populating the omni completion list with the text Vim already
1621knows how to color highlight. It can be used for any filetype and provides a
1622minimal language-sensitive completion.
Bram Moolenaar4770d092006-01-12 23:22:24 +00001623
Bram Moolenaarc06ac342006-03-02 22:43:39 +00001624To enable syntax code completion you can run: >
Bram Moolenaarec7944a2013-06-12 21:29:15 +02001625 setlocal omnifunc=syntaxcomplete#Complete
Bram Moolenaar4770d092006-01-12 23:22:24 +00001626
Bram Moolenaarec7944a2013-06-12 21:29:15 +02001627You can automate this by placing the following in your |.vimrc| (after any
Bram Moolenaarc06ac342006-03-02 22:43:39 +00001628":filetype" command): >
1629 if has("autocmd") && exists("+omnifunc")
Bram Moolenaare2f98b92006-03-29 21:18:24 +00001630 autocmd Filetype *
1631 \ if &omnifunc == "" |
1632 \ setlocal omnifunc=syntaxcomplete#Complete |
1633 \ endif
Bram Moolenaarc06ac342006-03-02 22:43:39 +00001634 endif
Bram Moolenaar4770d092006-01-12 23:22:24 +00001635
Bram Moolenaarc06ac342006-03-02 22:43:39 +00001636The above will set completion to this script only if a specific plugin does
1637not already exist for that filetype.
1638
1639Each filetype can have a wide range of syntax items. The plugin allows you to
1640customize which syntax groups to include or exclude from the list. Let's have
1641a look at the PHP filetype to see how this works.
1642
1643If you edit a file called, index.php, run the following command: >
Bram Moolenaarec7944a2013-06-12 21:29:15 +02001644 syntax list
Bram Moolenaarc06ac342006-03-02 22:43:39 +00001645
Bram Moolenaar06b5d512010-05-22 15:37:44 +02001646The first thing you will notice is that there are many different syntax groups.
1647The PHP language can include elements from different languages like HTML,
Bram Moolenaarc06ac342006-03-02 22:43:39 +00001648JavaScript and many more. The syntax plugin will only include syntax groups
1649that begin with the filetype, "php", in this case. For example these syntax
1650groups are included by default with the PHP: phpEnvVar, phpIntVar,
1651phpFunctions.
1652
Bram Moolenaar40962ec2018-01-28 22:47:25 +01001653If you wish non-filetype syntax items to also be included, you can use a
1654regular expression syntax (added in version 13.0 of
Bram Moolenaar6dc819b2018-07-03 16:42:19 +02001655autoload/syntaxcomplete.vim) to add items. Looking at the output from
Bram Moolenaar40962ec2018-01-28 22:47:25 +01001656":syntax list" while editing a PHP file I can see some of these entries: >
Bram Moolenaarec7944a2013-06-12 21:29:15 +02001657 htmlArg,htmlTag,htmlTagName,javaScriptStatement,javaScriptGlobalObjects
Bram Moolenaarc06ac342006-03-02 22:43:39 +00001658
Bram Moolenaarec7944a2013-06-12 21:29:15 +02001659To pick up any JavaScript and HTML keyword syntax groups while editing a PHP
Bram Moolenaar40962ec2018-01-28 22:47:25 +01001660file, you can use 3 different regexs, one for each language. Or you can
1661simply restrict the include groups to a particular value, without using
Bram Moolenaarec7944a2013-06-12 21:29:15 +02001662a regex string: >
1663 let g:omni_syntax_group_include_php = 'php\w\+,javaScript\w\+,html\w\+'
1664 let g:omni_syntax_group_include_php = 'phpFunctions,phpMethods'
1665<
1666The basic form of this variable is: >
1667 let g:omni_syntax_group_include_{filetype} = 'regex,comma,separated'
1668
1669The PHP language has an enormous number of items which it knows how to syntax
Bram Moolenaar9ba7e172013-07-17 22:37:26 +02001670highlight. These items will be available within the omni completion list.
Bram Moolenaarec7944a2013-06-12 21:29:15 +02001671
1672Some people may find this list unwieldy or are only interested in certain
1673items. There are two ways to prune this list (if necessary). If you find
Bram Moolenaar40962ec2018-01-28 22:47:25 +01001674certain syntax groups you do not wish displayed you can use two different
1675methods to identify these groups. The first specifically lists the syntax
1676groups by name. The second uses a regular expression to identify both
Bram Moolenaarec7944a2013-06-12 21:29:15 +02001677syntax groups. Simply add one the following to your vimrc: >
1678 let g:omni_syntax_group_exclude_php = 'phpCoreConstant,phpConstant'
1679 let g:omni_syntax_group_exclude_php = 'php\w*Constant'
Bram Moolenaarc06ac342006-03-02 22:43:39 +00001680
1681Add as many syntax groups to this list by comma separating them. The basic
1682form of this variable is: >
Bram Moolenaarec7944a2013-06-12 21:29:15 +02001683 let g:omni_syntax_group_exclude_{filetype} = 'regex,comma,separated'
Bram Moolenaarc06ac342006-03-02 22:43:39 +00001684
1685You can create as many of these variables as you need, varying only the
1686filetype at the end of the variable name.
Bram Moolenaar4770d092006-01-12 23:22:24 +00001687
Bram Moolenaar9964e462007-05-05 17:54:07 +00001688The plugin uses the isKeyword option to determine where word boundaries are
1689for the syntax items. For example, in the Scheme language completion should
1690include the "-", call-with-output-file. Depending on your filetype, this may
1691not provide the words you are expecting. Setting the
1692g:omni_syntax_use_iskeyword option to 0 will force the syntax plugin to break
1693on word characters. This can be controlled adding the following to your
1694vimrc: >
1695 let g:omni_syntax_use_iskeyword = 0
1696
Bram Moolenaar8b682772010-07-30 21:49:40 +02001697For plugin developers, the plugin exposes a public function OmniSyntaxList.
1698This function can be used to request a List of syntax items. When editing a
Bram Moolenaar40962ec2018-01-28 22:47:25 +01001699SQL file (:e syntax.sql) you can use the ":syntax list" command to see the
Bram Moolenaar8b682772010-07-30 21:49:40 +02001700various groups and syntax items. For example: >
Bram Moolenaar40962ec2018-01-28 22:47:25 +01001701 syntax list
Bram Moolenaar8b682772010-07-30 21:49:40 +02001702
Bram Moolenaar40962ec2018-01-28 22:47:25 +01001703Yields data similar to this:
1704 sqlOperator xxx some prior all like and any escape exists in is not ~
1705 or intersect minus between distinct ~
1706 links to Operator ~
1707 sqlType xxx varbit varchar nvarchar bigint int uniqueidentifier ~
1708 date money long tinyint unsigned xml text smalldate ~
1709 double datetime nchar smallint numeric time bit char ~
1710 varbinary binary smallmoney ~
1711 image float integer timestamp real decimal ~
Bram Moolenaar8b682772010-07-30 21:49:40 +02001712
1713There are two syntax groups listed here: sqlOperator and sqlType. To retrieve
Bram Moolenaar40962ec2018-01-28 22:47:25 +01001714a List of syntax items you can call OmniSyntaxList a number of different
Bram Moolenaar8b682772010-07-30 21:49:40 +02001715ways. To retrieve all syntax items regardless of syntax group: >
1716 echo OmniSyntaxList( [] )
1717
1718To retrieve only the syntax items for the sqlOperator syntax group: >
1719 echo OmniSyntaxList( ['sqlOperator'] )
1720
1721To retrieve all syntax items for both the sqlOperator and sqlType groups: >
1722 echo OmniSyntaxList( ['sqlOperator', 'sqlType'] )
1723
Bram Moolenaarec7944a2013-06-12 21:29:15 +02001724A regular expression can also be used: >
1725 echo OmniSyntaxList( ['sql\w\+'] )
1726
Bram Moolenaar8b682772010-07-30 21:49:40 +02001727From within a plugin, you would typically assign the output to a List: >
1728 let myKeywords = []
1729 let myKeywords = OmniSyntaxList( ['sqlKeyword'] )
1730
Bram Moolenaar4770d092006-01-12 23:22:24 +00001731
Bram Moolenaare2f98b92006-03-29 21:18:24 +00001732SQL *ft-sql-omni*
1733
1734Completion for the SQL language includes statements, functions, keywords.
1735It will also dynamically complete tables, procedures, views and column lists
1736with data pulled directly from within a database. For detailed instructions
1737and a tutorial see |omni-sql-completion|.
1738
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001739The SQL completion plugin can be used in conjunction with other completion
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001740plugins. For example, the PHP filetype has its own completion plugin.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00001741Since PHP is often used to generate dynamic website by accessing a database,
1742the SQL completion plugin can also be enabled. This allows you to complete
1743PHP code and SQL code at the same time.
1744
Bram Moolenaare2f98b92006-03-29 21:18:24 +00001745
Bram Moolenaar4770d092006-01-12 23:22:24 +00001746XML *ft-xml-omni*
Bram Moolenaara5792f52005-11-23 21:25:05 +00001747
Bram Moolenaar9c102382006-05-03 21:26:49 +00001748Vim 7 provides a mechanism for context aware completion of XML files. It
1749depends on a special |xml-omni-datafile| and two commands: |:XMLns| and
1750|:XMLent|. Features are:
Bram Moolenaara5792f52005-11-23 21:25:05 +00001751
Bram Moolenaar9c102382006-05-03 21:26:49 +00001752- after "<" complete the tag name, depending on context
1753- inside of a tag complete proper attributes
1754- when an attribute has a limited number of possible values help to complete
Bram Moolenaara5792f52005-11-23 21:25:05 +00001755 them
Bram Moolenaar9c102382006-05-03 21:26:49 +00001756- complete names of entities (defined in |xml-omni-datafile| and in the
1757 current file with "<!ENTITY" declarations)
Bram Moolenaara5792f52005-11-23 21:25:05 +00001758- when used after "</" CTRL-X CTRL-O will close the last opened tag
1759
Bram Moolenaar4770d092006-01-12 23:22:24 +00001760Format of XML data file *xml-omni-datafile*
Bram Moolenaara5792f52005-11-23 21:25:05 +00001761
Bram Moolenaar9c102382006-05-03 21:26:49 +00001762XML data files are stored in the "autoload/xml" directory in 'runtimepath'.
1763Vim distribution provides examples of data files in the
1764"$VIMRUNTIME/autoload/xml" directory. They have a meaningful name which will
1765be used in commands. It should be a unique name which will not create
1766conflicts. For example, the name xhtml10s.vim means it is the data file for
1767XHTML 1.0 Strict.
Bram Moolenaara5792f52005-11-23 21:25:05 +00001768
Bram Moolenaar9c102382006-05-03 21:26:49 +00001769Each file contains a variable with a name like g:xmldata_xhtml10s . It is
1770a compound from two parts:
Bram Moolenaara5792f52005-11-23 21:25:05 +00001771
Bram Moolenaar9c102382006-05-03 21:26:49 +000017721. "g:xmldata_" general prefix, constant for all data files
17732. "xhtml10s" the name of the file and the name of the described XML
1774 dialect; it will be used as an argument for the |:XMLns|
1775 command
Bram Moolenaara5792f52005-11-23 21:25:05 +00001776
1777Part two must be exactly the same as name of file.
1778
Bram Moolenaar9c102382006-05-03 21:26:49 +00001779The variable is a |Dictionary|. Keys are tag names and each value is a two
1780element |List|. The first element of the List is also a List with the names
1781of possible children. The second element is a |Dictionary| with the names of
1782attributes as keys and the possible values of attributes as values. Example: >
Bram Moolenaara5792f52005-11-23 21:25:05 +00001783
Bram Moolenaar9c102382006-05-03 21:26:49 +00001784 let g:xmldata_crippled = {
1785 \ "vimxmlentities": ["amp", "lt", "gt", "apos", "quot"],
1786 \ 'vimxmlroot': ['tag1'],
1787 \ 'tag1':
1788 \ [ ['childoftag1a', 'childoftag1b'], {'attroftag1a': [],
1789 \ 'attroftag1b': ['valueofattr1', 'valueofattr2']}],
1790 \ 'childoftag1a':
1791 \ [ [], {'attrofchild': ['attrofchild']}],
1792 \ 'childoftag1b':
1793 \ [ ['childoftag1a'], {'attrofchild': []}],
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001794 \ "vimxmltaginfo": {
Bram Moolenaar9c102382006-05-03 21:26:49 +00001795 \ 'tag1': ['Menu info', 'Long information visible in preview window']},
1796 \ 'vimxmlattrinfo': {
1797 \ 'attrofchild': ['Menu info', 'Long information visible in preview window']}}
Bram Moolenaara5792f52005-11-23 21:25:05 +00001798
Bram Moolenaar9c102382006-05-03 21:26:49 +00001799This example would be put in the "autoload/xml/crippled.vim" file and could
1800help to write this file: >
Bram Moolenaara5792f52005-11-23 21:25:05 +00001801
Bram Moolenaar9c102382006-05-03 21:26:49 +00001802 <tag1 attroftag1b="valueofattr1">
1803 <childoftag1a attrofchild>
1804 &amp; &lt;
1805 </childoftag1a>
1806 <childoftag1b attrofchild="5">
1807 <childoftag1a>
1808 &gt; &apos; &quot;
1809 </childoftag1a>
1810 </childoftag1b>
1811 </tag1>
Bram Moolenaara5792f52005-11-23 21:25:05 +00001812
Bram Moolenaar9c102382006-05-03 21:26:49 +00001813In the example four special elements are visible:
1814
18151. "vimxmlentities" - a special key with List containing entities of this XML
Bram Moolenaara5792f52005-11-23 21:25:05 +00001816 dialect.
Bram Moolenaar9c102382006-05-03 21:26:49 +000018172. If the list containing possible values of attributes has one element and
1818 this element is equal to the name of the attribute this attribute will be
1819 treated as boolean and inserted as 'attrname' and not as 'attrname="'
18203. "vimxmltaginfo" - a special key with a Dictionary containing tag
1821 names as keys and two element List as values, for additional menu info and
1822 the long description.
18234. "vimxmlattrinfo" - special key with Dictionary containing attribute names
1824 as keys and two element List as values, for additional menu info and long
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001825 description.
Bram Moolenaara5792f52005-11-23 21:25:05 +00001826
Bram Moolenaar9c102382006-05-03 21:26:49 +00001827Note: Tag names in the data file MUST not contain a namespace description.
1828Check xsl.vim for an example.
1829Note: All data and functions are publicly available as global
1830variables/functions and can be used for personal editing functions.
Bram Moolenaara5792f52005-11-23 21:25:05 +00001831
Bram Moolenaar1d2ba7f2006-02-14 22:29:30 +00001832
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001833DTD -> Vim *dtd2vim*
Bram Moolenaarc1e37902006-04-18 21:55:01 +00001834
Bram Moolenaar9c102382006-05-03 21:26:49 +00001835On |www| is the script |dtd2vim| which parses DTD and creates an XML data file
Bram Moolenaarc1e37902006-04-18 21:55:01 +00001836for Vim XML omni completion.
1837
1838 dtd2vim: http://www.vim.org/scripts/script.php?script_id=1462
1839
Bram Moolenaar9c102382006-05-03 21:26:49 +00001840Check the beginning of that file for usage details.
1841The script requires perl and:
Bram Moolenaarc1e37902006-04-18 21:55:01 +00001842
1843 perlSGML: http://savannah.nongnu.org/projects/perlsgml
1844
1845
Bram Moolenaara5792f52005-11-23 21:25:05 +00001846Commands
1847
Bram Moolenaar4770d092006-01-12 23:22:24 +00001848:XMLns {name} [{namespace}] *:XMLns*
Bram Moolenaara5792f52005-11-23 21:25:05 +00001849
Bram Moolenaar9c102382006-05-03 21:26:49 +00001850Vim has to know which data file should be used and with which namespace. For
1851loading of the data file and connecting data with the proper namespace use
1852|:XMLns| command. The first (obligatory) argument is the name of the data
1853(xhtml10s, xsl). The second argument is the code of namespace (h, xsl). When
1854used without a second argument the dialect will be used as default - without
1855namespace declaration. For example to use XML completion in .xsl files: >
Bram Moolenaara5792f52005-11-23 21:25:05 +00001856
1857 :XMLns xhtml10s
1858 :XMLns xsl xsl
1859
1860
Bram Moolenaar4770d092006-01-12 23:22:24 +00001861:XMLent {name} *:XMLent*
Bram Moolenaara5792f52005-11-23 21:25:05 +00001862
Bram Moolenaar9c102382006-05-03 21:26:49 +00001863By default entities will be completed from the data file of the default
1864namespace. The XMLent command should be used in case when there is no default
1865namespace: >
Bram Moolenaara5792f52005-11-23 21:25:05 +00001866
Bram Moolenaar4770d092006-01-12 23:22:24 +00001867 :XMLent xhtml10s
Bram Moolenaara5792f52005-11-23 21:25:05 +00001868
1869Usage
1870
Bram Moolenaar9c102382006-05-03 21:26:49 +00001871While used in this situation (after declarations from previous part, | is
Bram Moolenaara5792f52005-11-23 21:25:05 +00001872cursor position): >
1873
Bram Moolenaar4770d092006-01-12 23:22:24 +00001874 <|
Bram Moolenaara5792f52005-11-23 21:25:05 +00001875
Bram Moolenaar9c102382006-05-03 21:26:49 +00001876Will complete to an appropriate XHTML tag, and in this situation: >
Bram Moolenaara5792f52005-11-23 21:25:05 +00001877
Bram Moolenaar4770d092006-01-12 23:22:24 +00001878 <xsl:|
Bram Moolenaara5792f52005-11-23 21:25:05 +00001879
Bram Moolenaar9c102382006-05-03 21:26:49 +00001880Will complete to an appropriate XSL tag.
Bram Moolenaara5792f52005-11-23 21:25:05 +00001881
Bram Moolenaar9c102382006-05-03 21:26:49 +00001882
1883The script xmlcomplete.vim, provided through the |autoload| mechanism,
1884has the xmlcomplete#GetLastOpenTag() function which can be used in XML files
1885to get the name of the last open tag (b:unaryTagsStack has to be defined): >
Bram Moolenaar6b730e12005-09-16 21:47:57 +00001886
Bram Moolenaar4770d092006-01-12 23:22:24 +00001887 :echo xmlcomplete#GetLastOpenTag("b:unaryTagsStack")
Bram Moolenaarbfd8fc02005-09-20 23:22:24 +00001888
Bram Moolenaar6b730e12005-09-16 21:47:57 +00001889
Bram Moolenaar1e015462005-09-25 22:16:38 +00001890
Bram Moolenaar071d4272004-06-13 20:20:40 +00001891==============================================================================
18928. Insert mode commands *inserting*
1893
1894The following commands can be used to insert new text into the buffer. They
1895can all be undone and repeated with the "." command.
1896
1897 *a*
1898a Append text after the cursor [count] times. If the
1899 cursor is in the first column of an empty line Insert
1900 starts there. But not when 'virtualedit' is set!
1901
1902 *A*
1903A Append text at the end of the line [count] times.
Bram Moolenaar1d59aa12020-09-19 18:50:13 +02001904 For using "A" in Visual block mode see |v_b_A|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001905
1906<insert> or *i* *insert* *<Insert>*
1907i Insert text before the cursor [count] times.
1908 When using CTRL-O in Insert mode |i_CTRL-O| the count
1909 is not supported.
1910
1911 *I*
1912I Insert text before the first non-blank in the line
1913 [count] times.
Bram Moolenaar4399ef42005-02-12 14:29:27 +00001914 When the 'H' flag is present in 'cpoptions' and the
1915 line only contains blanks, insert start just before
1916 the last blank.
Bram Moolenaar1d59aa12020-09-19 18:50:13 +02001917 For using "I" in Visual block mode see |v_b_I|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001918
1919 *gI*
Bram Moolenaar25c9c682019-05-05 18:13:34 +02001920gI Insert text in column 1 [count] times.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001921
1922 *gi*
1923gi Insert text in the same position as where Insert mode
1924 was stopped last time in the current buffer.
1925 This uses the |'^| mark. It's different from "`^i"
1926 when the mark is past the end of the line.
1927 The position is corrected for inserted/deleted lines,
1928 but NOT for inserted/deleted characters.
1929 When the |:keepjumps| command modifier is used the |'^|
Bram Moolenaar69a7cb42004-06-20 12:51:53 +00001930 mark won't be changed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001931
1932 *o*
1933o Begin a new line below the cursor and insert text,
Bram Moolenaara6c27c42019-05-09 19:16:22 +02001934 repeat [count] times.
Bram Moolenaar4399ef42005-02-12 14:29:27 +00001935 When the '#' flag is in 'cpoptions' the count is
1936 ignored.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001937
1938 *O*
1939O Begin a new line above the cursor and insert text,
Bram Moolenaara6c27c42019-05-09 19:16:22 +02001940 repeat [count] times.
Bram Moolenaar4399ef42005-02-12 14:29:27 +00001941 When the '#' flag is in 'cpoptions' the count is
1942 ignored.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001943
1944These commands are used to start inserting text. You can end insert mode with
1945<Esc>. See |mode-ins-repl| for the other special characters in Insert mode.
1946The effect of [count] takes place after Insert mode is exited.
1947
1948When 'autoindent' is on, the indent for a new line is obtained from the
1949previous line. When 'smartindent' or 'cindent' is on, the indent for a line
1950is automatically adjusted for C programs.
1951
1952'textwidth' can be set to the maximum width for a line. When a line becomes
1953too long when appending characters a line break is automatically inserted.
1954
1955
1956==============================================================================
19579. Ex insert commands *inserting-ex*
1958
1959 *:a* *:append*
Bram Moolenaardf177f62005-02-22 08:39:57 +00001960:{range}a[ppend][!] Insert several lines of text below the specified
Bram Moolenaar071d4272004-06-13 20:20:40 +00001961 line. If the {range} is missing, the text will be
1962 inserted after the current line.
Bram Moolenaardf177f62005-02-22 08:39:57 +00001963 Adding [!] toggles 'autoindent' for the time this
1964 command is executed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001965
1966 *:i* *:in* *:insert*
Bram Moolenaardf177f62005-02-22 08:39:57 +00001967:{range}i[nsert][!] Insert several lines of text above the specified
Bram Moolenaar071d4272004-06-13 20:20:40 +00001968 line. If the {range} is missing, the text will be
1969 inserted before the current line.
Bram Moolenaardf177f62005-02-22 08:39:57 +00001970 Adding [!] toggles 'autoindent' for the time this
1971 command is executed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001972
1973These two commands will keep on asking for lines, until you type a line
1974containing only a ".". Watch out for lines starting with a backslash, see
1975|line-continuation|.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001976
Bram Moolenaar4a748032010-09-30 21:47:56 +02001977When in Ex mode (see |-e|) a backslash at the end of the line can be used to
1978insert a NUL character. To be able to have a line ending in a backslash use
1979two backslashes. This means that the number of backslashes is halved, but
1980only at the end of the line.
1981
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001982NOTE: These commands cannot be used with |:global| or |:vglobal|.
1983":append" and ":insert" don't work properly in between ":if" and
Bram Moolenaar06fb4352005-01-05 22:10:30 +00001984":endif", ":for" and ":endfor", ":while" and ":endwhile".
Bram Moolenaar071d4272004-06-13 20:20:40 +00001985
1986 *:start* *:startinsert*
1987:star[tinsert][!] Start Insert mode just after executing this command.
1988 Works like typing "i" in Normal mode. When the ! is
1989 included it works like "A", append to the line.
1990 Otherwise insertion starts at the cursor position.
1991 Note that when using this command in a function or
1992 script, the insertion only starts after the function
1993 or script is finished.
Bram Moolenaar87e25fd2005-07-27 21:13:01 +00001994 This command does not work from |:normal|.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001995
1996 *:stopi* *:stopinsert*
1997:stopi[nsert] Stop Insert mode as soon as possible. Works like
1998 typing <Esc> in Insert mode.
1999 Can be used in an autocommand, example: >
2000 :au BufEnter scratch stopinsert
Bram Moolenaar325b7a22004-07-05 15:58:32 +00002001<
2002 *replacing-ex* *:startreplace*
2003:startr[eplace][!] Start Replace mode just after executing this command.
2004 Works just like typing "R" in Normal mode. When the
2005 ! is included it acts just like "$R" had been typed
2006 (ie. begin replace mode at the end-of-line). Other-
2007 wise replacement begins at the cursor position.
2008 Note that when using this command in a function or
2009 script that the replacement will only start after
2010 the function or script is finished.
Bram Moolenaar071d4272004-06-13 20:20:40 +00002011
Bram Moolenaar61da4982005-12-14 22:02:18 +00002012 *:startgreplace*
2013:startg[replace][!] Just like |:startreplace|, but use Virtual Replace
2014 mode, like with |gR|.
Bram Moolenaar61da4982005-12-14 22:02:18 +00002015
Bram Moolenaar071d4272004-06-13 20:20:40 +00002016==============================================================================
201710. Inserting a file *inserting-file*
2018
2019 *:r* *:re* *:read*
Bram Moolenaar910f66f2006-04-05 20:41:53 +00002020:r[ead] [++opt] [name]
2021 Insert the file [name] (default: current file) below
Bram Moolenaar071d4272004-06-13 20:20:40 +00002022 the cursor.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00002023 See |++opt| for the possible values of [++opt].
Bram Moolenaar071d4272004-06-13 20:20:40 +00002024
Bram Moolenaar910f66f2006-04-05 20:41:53 +00002025:{range}r[ead] [++opt] [name]
2026 Insert the file [name] (default: current file) below
Bram Moolenaar071d4272004-06-13 20:20:40 +00002027 the specified line.
Bram Moolenaar910f66f2006-04-05 20:41:53 +00002028 See |++opt| for the possible values of [++opt].
Bram Moolenaar071d4272004-06-13 20:20:40 +00002029
2030 *:r!* *:read!*
Bram Moolenaar0187ca02013-04-12 15:09:51 +02002031:[range]r[ead] [++opt] !{cmd}
2032 Execute {cmd} and insert its standard output below
Bram Moolenaar9964e462007-05-05 17:54:07 +00002033 the cursor or the specified line. A temporary file is
2034 used to store the output of the command which is then
2035 read into the buffer. 'shellredir' is used to save
2036 the output of the command, which can be set to include
2037 stderr or not. {cmd} is executed like with ":!{cmd}",
2038 any '!' is replaced with the previous command |:!|.
Bram Moolenaar0187ca02013-04-12 15:09:51 +02002039 See |++opt| for the possible values of [++opt].
Bram Moolenaar071d4272004-06-13 20:20:40 +00002040
2041These commands insert the contents of a file, or the output of a command,
2042into the buffer. They can be undone. They cannot be repeated with the "."
2043command. They work on a line basis, insertion starts below the line in which
2044the cursor is, or below the specified line. To insert text above the first
2045line use the command ":0r {name}".
2046
2047After the ":read" command, the cursor is left on the first non-blank in the
2048first new line. Unless in Ex mode, then the cursor is left on the last new
2049line (sorry, this is Vi compatible).
2050
2051If a file name is given with ":r", it becomes the alternate file. This can be
2052used, for example, when you want to edit that file instead: ":e! #". This can
2053be switched off by removing the 'a' flag from the 'cpoptions' option.
2054
Bram Moolenaar910f66f2006-04-05 20:41:53 +00002055Of the [++opt] arguments one is specifically for ":read", the ++edit argument.
2056This is useful when the ":read" command is actually used to read a file into
2057the buffer as if editing that file. Use this command in an empty buffer: >
2058 :read ++edit filename
2059The effect is that the 'fileformat', 'fileencoding', 'bomb', etc. options are
2060set to what has been detected for "filename". Note that a single empty line
2061remains, you may want to delete it.
2062
Bram Moolenaar071d4272004-06-13 20:20:40 +00002063 *file-read*
2064The 'fileformat' option sets the <EOL> style for a file:
2065'fileformat' characters name ~
2066 "dos" <CR><NL> or <NL> DOS format
2067 "unix" <NL> Unix format
2068 "mac" <CR> Mac format
2069Previously 'textmode' was used. It is obsolete now.
2070
2071If 'fileformat' is "dos", a <CR> in front of an <NL> is ignored and a CTRL-Z
2072at the end of the file is ignored.
2073
2074If 'fileformat' is "mac", a <NL> in the file is internally represented by a
2075<CR>. This is to avoid confusion with a <NL> which is used to represent a
2076<NUL>. See |CR-used-for-NL|.
2077
2078If the 'fileformats' option is not empty Vim tries to recognize the type of
2079<EOL> (see |file-formats|). However, the 'fileformat' option will not be
2080changed, the detected format is only used while reading the file.
2081A similar thing happens with 'fileencodings'.
2082
Bram Moolenaar8024f932020-01-14 19:29:13 +01002083On non-Win32 systems the message "[dos format]" is shown if a file is read in
2084DOS format, to remind you that something unusual is done.
Bram Moolenaar5666fcd2019-12-26 14:35:26 +01002085On Macintosh and Win32 the message "[unix format]" is shown if a file is read
2086in Unix format.
Bram Moolenaar8024f932020-01-14 19:29:13 +01002087On non-Macintosh systems, the message "[mac format]" is shown if a file is
Bram Moolenaar071d4272004-06-13 20:20:40 +00002088read in Mac format.
2089
2090An example on how to use ":r !": >
2091 :r !uuencode binfile binfile
2092This command reads "binfile", uuencodes it and reads it into the current
2093buffer. Useful when you are editing e-mail and want to include a binary
2094file.
2095
2096 *read-messages*
2097When reading a file Vim will display a message with information about the read
2098file. In the table is an explanation for some of the items. The others are
2099self explanatory. Using the long or the short version depends on the
2100'shortmess' option.
2101
2102 long short meaning ~
2103 [readonly] {RO} the file is write protected
2104 [fifo/socket] using a stream
2105 [fifo] using a fifo stream
2106 [socket] using a socket stream
2107 [CR missing] reading with "dos" 'fileformat' and a
2108 NL without a preceding CR was found.
2109 [NL found] reading with "mac" 'fileformat' and a
2110 NL was found (could be "unix" format)
2111 [long lines split] at least one line was split in two
2112 [NOT converted] conversion from 'fileencoding' to
2113 'encoding' was desired but not
2114 possible
2115 [converted] conversion from 'fileencoding' to
2116 'encoding' done
2117 [crypted] file was decrypted
2118 [READ ERRORS] not all of the file could be read
2119
2120
Bram Moolenaar91f84f62018-07-29 15:07:52 +02002121 vim:tw=78:ts=8:noet:ft=help:norl: