|
1668
|
1 *map.txt* For Vim version 7.2b. Last change: 2008 Jul 09
|
|
7
|
2
|
|
|
3
|
|
|
4 VIM REFERENCE MANUAL by Bram Moolenaar
|
|
|
5
|
|
|
6
|
|
|
7 Key mapping, abbreviations and user-defined commands.
|
|
|
8
|
|
|
9 This subject is introduced in sections |05.3|, |24.7| and |40.1| of the user
|
|
|
10 manual.
|
|
|
11
|
|
|
12 1. Key mapping |key-mapping|
|
|
592
|
13 1.1 MAP COMMANDS |:map-commands|
|
|
|
14 1.2 Special arguments |:map-arguments|
|
|
|
15 1.3 Mapping and modes |:map-modes|
|
|
|
16 1.4 Listing mappings |map-listing|
|
|
|
17 1.5 Mapping special keys |:map-special-keys|
|
|
|
18 1.6 Special characters |:map-special-chars|
|
|
|
19 1.7 What keys to map |map-which-keys|
|
|
|
20 1.8 Examples |map-examples|
|
|
|
21 1.9 Using mappings |map-typing|
|
|
|
22 1.10 Mapping alt-keys |:map-alt-keys|
|
|
|
23 1.11 Mapping an operator |:map-operator|
|
|
7
|
24 2. Abbreviations |abbreviations|
|
|
|
25 3. Local mappings and functions |script-local|
|
|
|
26 4. User-defined commands |user-commands|
|
|
|
27
|
|
|
28 ==============================================================================
|
|
|
29 1. Key mapping *key-mapping* *mapping* *macro*
|
|
|
30
|
|
|
31 Key mapping is used to change the meaning of typed keys. The most common use
|
|
|
32 is to define a sequence commands for a function key. Example: >
|
|
|
33
|
|
|
34 :map <F2> a<C-R>=strftime("%c")<CR><Esc>
|
|
|
35
|
|
236
|
36 This appends the current date and time after the cursor (in <> notation |<>|).
|
|
7
|
37
|
|
592
|
38
|
|
|
39 1.1 MAP COMMANDS *:map-commands*
|
|
|
40
|
|
7
|
41 There are commands to enter new mappings, remove mappings and list mappings.
|
|
|
42 See |map-overview| for the various forms of "map" and their relationships with
|
|
|
43 modes.
|
|
|
44
|
|
|
45 {lhs} means left-hand-side *{lhs}*
|
|
|
46 {rhs} means right-hand-side *{rhs}*
|
|
|
47
|
|
663
|
48 :map {lhs} {rhs} |mapmode-nvo| *:map*
|
|
|
49 :nm[ap] {lhs} {rhs} |mapmode-n| *:nm* *:nmap*
|
|
|
50 :vm[ap] {lhs} {rhs} |mapmode-v| *:vm* *:vmap*
|
|
788
|
51 :xm[ap] {lhs} {rhs} |mapmode-x| *:xm* *:xmap*
|
|
|
52 :smap {lhs} {rhs} |mapmode-s| *:smap*
|
|
663
|
53 :om[ap] {lhs} {rhs} |mapmode-o| *:om* *:omap*
|
|
|
54 :map! {lhs} {rhs} |mapmode-ic| *:map!*
|
|
|
55 :im[ap] {lhs} {rhs} |mapmode-i| *:im* *:imap*
|
|
|
56 :lm[ap] {lhs} {rhs} |mapmode-l| *:lm* *:lmap*
|
|
|
57 :cm[ap] {lhs} {rhs} |mapmode-c| *:cm* *:cmap*
|
|
7
|
58 Map the key sequence {lhs} to {rhs} for the modes
|
|
|
59 where the map command applies. The result, including
|
|
|
60 {rhs}, is then further scanned for mappings. This
|
|
|
61 allows for nested and recursive use of mappings.
|
|
|
62
|
|
|
63
|
|
663
|
64 :no[remap] {lhs} {rhs} |mapmode-nvo| *:no* *:noremap*
|
|
|
65 :nn[oremap] {lhs} {rhs} |mapmode-n| *:nn* *:nnoremap*
|
|
|
66 :vn[oremap] {lhs} {rhs} |mapmode-v| *:vn* *:vnoremap*
|
|
788
|
67 :xn[oremap] {lhs} {rhs} |mapmode-x| *:xn* *:xnoremap*
|
|
|
68 :snor[emap] {lhs} {rhs} |mapmode-s| *:snor* *:snoremap*
|
|
663
|
69 :ono[remap] {lhs} {rhs} |mapmode-o| *:ono* *:onoremap*
|
|
|
70 :no[remap]! {lhs} {rhs} |mapmode-ic| *:no!* *:noremap!*
|
|
|
71 :ino[remap] {lhs} {rhs} |mapmode-i| *:ino* *:inoremap*
|
|
|
72 :ln[oremap] {lhs} {rhs} |mapmode-l| *:ln* *:lnoremap*
|
|
|
73 :cno[remap] {lhs} {rhs} |mapmode-c| *:cno* *:cnoremap*
|
|
7
|
74 Map the key sequence {lhs} to {rhs} for the modes
|
|
|
75 where the map command applies. Disallow mapping of
|
|
|
76 {rhs}, to avoid nested and recursive mappings. Often
|
|
|
77 used to redefine a command. {not in Vi}
|
|
|
78
|
|
|
79
|
|
663
|
80 :unm[ap] {lhs} |mapmode-nvo| *:unm* *:unmap*
|
|
|
81 :nun[map] {lhs} |mapmode-n| *:nun* *:nunmap*
|
|
|
82 :vu[nmap] {lhs} |mapmode-v| *:vu* *:vunmap*
|
|
788
|
83 :xu[nmap] {lhs} |mapmode-x| *:xu* *:xunmap*
|
|
|
84 :sunm[ap] {lhs} |mapmode-s| *:sunm* *:sunmap*
|
|
663
|
85 :ou[nmap] {lhs} |mapmode-o| *:ou* *:ounmap*
|
|
|
86 :unm[ap]! {lhs} |mapmode-ic| *:unm!* *:unmap!*
|
|
|
87 :iu[nmap] {lhs} |mapmode-i| *:iu* *:iunmap*
|
|
|
88 :lu[nmap] {lhs} |mapmode-l| *:lu* *:lunmap*
|
|
|
89 :cu[nmap] {lhs} |mapmode-c| *:cu* *:cunmap*
|
|
7
|
90 Remove the mapping of {lhs} for the modes where the
|
|
|
91 map command applies. The mapping may remain defined
|
|
|
92 for other modes where it applies.
|
|
|
93 Note: Trailing spaces are included in the {lhs}. This
|
|
|
94 unmap does NOT work: >
|
|
|
95 :map @@ foo
|
|
|
96 :unmap @@ | print
|
|
|
97
|
|
663
|
98 :mapc[lear] |mapmode-nvo| *:mapc* *:mapclear*
|
|
|
99 :nmapc[lear] |mapmode-n| *:nmapc* *:nmapclear*
|
|
|
100 :vmapc[lear] |mapmode-v| *:vmapc* *:vmapclear*
|
|
788
|
101 :xmapc[lear] |mapmode-x| *:xmapc* *:xmapclear*
|
|
|
102 :smapc[lear] |mapmode-s| *:smapc* *:smapclear*
|
|
663
|
103 :omapc[lear] |mapmode-o| *:omapc* *:omapclear*
|
|
|
104 :mapc[lear]! |mapmode-ic| *:mapc!* *:mapclear!*
|
|
|
105 :imapc[lear] |mapmode-i| *:imapc* *:imapclear*
|
|
|
106 :lmapc[lear] |mapmode-l| *:lmapc* *:lmapclear*
|
|
|
107 :cmapc[lear] |mapmode-c| *:cmapc* *:cmapclear*
|
|
7
|
108 Remove ALL mappings for the modes where the map
|
|
|
109 command applies. {not in Vi}
|
|
|
110 Warning: This also removes the default mappings.
|
|
|
111
|
|
663
|
112 :map |mapmode-nvo|
|
|
|
113 :nm[ap] |mapmode-n|
|
|
|
114 :vm[ap] |mapmode-v|
|
|
788
|
115 :xm[ap] |mapmode-x|
|
|
|
116 :sm[ap] |mapmode-s|
|
|
663
|
117 :om[ap] |mapmode-o|
|
|
|
118 :map! |mapmode-ic|
|
|
|
119 :im[ap] |mapmode-i|
|
|
|
120 :lm[ap] |mapmode-l|
|
|
|
121 :cm[ap] |mapmode-c|
|
|
7
|
122 List all key mappings for the modes where the map
|
|
|
123 command applies. Note that ":map" and ":map!" are
|
|
|
124 used most often, because they include the other modes.
|
|
|
125
|
|
663
|
126 :map {lhs} |mapmode-nvo| *:map_l*
|
|
|
127 :nm[ap] {lhs} |mapmode-n| *:nmap_l*
|
|
|
128 :vm[ap] {lhs} |mapmode-v| *:vmap_l*
|
|
788
|
129 :xm[ap] {lhs} |mapmode-x| *:xmap_l*
|
|
|
130 :sm[ap] {lhs} |mapmode-s| *:smap_l*
|
|
663
|
131 :om[ap] {lhs} |mapmode-o| *:omap_l*
|
|
|
132 :map! {lhs} |mapmode-ic| *:map_l!*
|
|
|
133 :im[ap] {lhs} |mapmode-i| *:imap_l*
|
|
|
134 :lm[ap] {lhs} |mapmode-l| *:lmap_l*
|
|
|
135 :cm[ap] {lhs} |mapmode-c| *:cmap_l*
|
|
7
|
136 List the key mappings for the key sequences starting
|
|
|
137 with {lhs} in the modes where the map command applies.
|
|
|
138 {not in Vi}
|
|
|
139
|
|
|
140 These commands are used to map a key or key sequence to a string of
|
|
|
141 characters. You can use this to put command sequences under function keys,
|
|
|
142 translate one key into another, etc. See |:mkexrc| for how to save and
|
|
|
143 restore the current mappings.
|
|
|
144
|
|
592
|
145 *map-ambiguous*
|
|
|
146 When two mappings start with the same sequence of characters, they are
|
|
|
147 ambiguous. Example: >
|
|
|
148 :imap aa foo
|
|
|
149 :imap aaa bar
|
|
|
150 When Vim has read "aa", it will need to get another character to be able to
|
|
|
151 decide if "aa" or "aaa" should be mapped. This means that after typing "aa"
|
|
|
152 that mapping won't get expanded yet, Vim is waiting for another character.
|
|
|
153 If you type a space, then "foo" will get inserted, plus the space. If you
|
|
|
154 type "a", then "bar" will get inserted.
|
|
|
155 {Vi does not allow ambiguous mappings}
|
|
|
156
|
|
|
157
|
|
|
158 1.2 SPECIAL ARGUMENTS *:map-arguments*
|
|
|
159
|
|
859
|
160 "<buffer>", "<silent>", "<special>", "<script>", "<expr>" and "<unique>" can
|
|
|
161 be used in any order. They must appear right after the command, before any
|
|
|
162 other arguments.
|
|
721
|
163
|
|
7
|
164 *:map-local* *:map-<buffer>* *E224* *E225*
|
|
1668
|
165 If the first argument to one of these commands is "<buffer>" the mapping will
|
|
|
166 be effective in the current buffer only. Example: >
|
|
7
|
167 :map <buffer> ,w /[.,;]<CR>
|
|
|
168 Then you can map ",w" to something else in another buffer: >
|
|
|
169 :map <buffer> ,w /[#&!]<CR>
|
|
|
170 The local buffer mappings are used before the global ones.
|
|
|
171 The "<buffer>" argument can also be used to clear mappings: >
|
|
|
172 :unmap <buffer> ,w
|
|
|
173 :mapclear <buffer>
|
|
|
174 Local mappings are also cleared when a buffer is deleted, but not when it is
|
|
|
175 unloaded. Just like local option values.
|
|
|
176
|
|
|
177 *:map-<silent>* *:map-silent*
|
|
|
178 To define a mapping which will not be echoed on the command line, add
|
|
|
179 "<silent>" as the first argument. Example: >
|
|
|
180 :map <silent> ,h /Header<CR>
|
|
|
181 The search string will not be echoed when using this mapping. Messages from
|
|
|
182 the executed command are still given though. To shut them up too, add a
|
|
|
183 ":silent" in the executed command: >
|
|
|
184 :map <silent> ,h :exe ":silent normal /Header\r"<CR>
|
|
|
185 Prompts will still be given, e.g., for inputdialog().
|
|
|
186 Using "<silent>" for an abbreviation is possible, but will cause redrawing of
|
|
|
187 the command line to fail.
|
|
|
188
|
|
859
|
189 *:map-<special>* *:map-special*
|
|
|
190 Define a mapping with <> notation for special keys, even though the "<" flag
|
|
|
191 may appear in 'cpoptions'. This is useful if the side effect of setting
|
|
|
192 'cpoptions' is not desired. Example: >
|
|
|
193 :map <special> <F12> /Header<CR>
|
|
|
194 <
|
|
7
|
195 *:map-<script>* *:map-script*
|
|
|
196 If the first argument to one of these commands is "<script>" and it is used to
|
|
|
197 define a new mapping or abbreviation, the mapping will only remap characters
|
|
|
198 in the {rhs} using mappings that were defined local to a script, starting with
|
|
|
199 "<SID>". This can be used to avoid that mappings from outside a script
|
|
|
200 interfere (e.g., when CTRL-V is remapped in mswin.vim), but do use other
|
|
|
201 mappings defined in the script.
|
|
|
202 Note: ":map <script>" and ":noremap <script>" do the same thing. The
|
|
|
203 "<script>" overrules the command name. Using ":noremap <script>" is
|
|
|
204 preferred, because it's clearer that remapping is (mostly) disabled.
|
|
|
205
|
|
|
206 *:map-<unique>* *E226* *E227*
|
|
|
207 If the first argument to one of these commands is "<unique>" and it is used to
|
|
|
208 define a new mapping or abbreviation, the command will fail if the mapping or
|
|
|
209 abbreviation already exists. Example: >
|
|
|
210 :map <unique> ,w /[#&!]<CR>
|
|
|
211 When defining a local mapping, there will also be a check if a global map
|
|
|
212 already exists which is equal.
|
|
|
213 Example of what will fail: >
|
|
|
214 :map ,w /[#&!]<CR>
|
|
|
215 :map <buffer> <unique> ,w /[.,;]<CR>
|
|
626
|
216 If you want to map a key and then have it do what it was originally mapped to,
|
|
|
217 have a look at |maparg()|.
|
|
7
|
218
|
|
721
|
219 *:map-<expr>* *:map-expression*
|
|
|
220 If the first argument to one of these commands is "<expr>" and it is used to
|
|
|
221 define a new mapping or abbreviation, the argument is an expression. The
|
|
|
222 expression is evaluated to obtain the {rhs} that is used. Example: >
|
|
|
223 :inoremap <expr> . InsertDot()
|
|
|
224 The result of the InsertDot() function will be inserted. It could check the
|
|
|
225 text before the cursor and start omni completion when some condition is met.
|
|
|
226
|
|
|
227 Be very careful about side effects! The expression is evaluated while
|
|
856
|
228 obtaining characters, you may very well make the command dysfunctional.
|
|
|
229 For this reason the following is blocked:
|
|
1132
|
230 - Changing the buffer text |textlock|.
|
|
|
231 - Editing another buffer.
|
|
|
232 - The |:normal| command.
|
|
|
233 - Moving the cursor is allowed, but it is restored afterwards.
|
|
|
234 - You can use getchar(), but the existing typeahead isn't seen and new
|
|
|
235 typeahead is discarded.
|
|
856
|
236 If you want the mapping to do any of these let the returned characters do
|
|
|
237 that.
|
|
721
|
238
|
|
|
239 Here is an example that inserts a list number that increases: >
|
|
|
240 let counter = 0
|
|
|
241 inoremap <expr> <C-L> ListItem()
|
|
|
242 inoremap <expr> <C-R> ListReset()
|
|
|
243
|
|
|
244 func ListItem()
|
|
|
245 let g:counter += 1
|
|
|
246 return g:counter . '. '
|
|
|
247 endfunc
|
|
|
248
|
|
|
249 func ListReset()
|
|
|
250 let g:counter = 0
|
|
|
251 return ''
|
|
|
252 endfunc
|
|
|
253
|
|
727
|
254 CTRL-L inserts the next number, CTRL-R resets the count. CTRL-R returns an
|
|
721
|
255 empty string, so that nothing is inserted.
|
|
7
|
256
|
|
837
|
257 Note that there are some tricks to make special keys work and escape CSI bytes
|
|
|
258 in the text. The |:map| command also does this, thus you must avoid that it
|
|
|
259 is done twice. This does not work: >
|
|
|
260 :imap <expr> <F3> "<Char-0x611B>"
|
|
|
261 Because the <Char- sequence is escaped for being a |:imap| argument and then
|
|
|
262 again for using <expr>. This does work: >
|
|
|
263 :imap <expr> <F3> "\u611B"
|
|
|
264 Using 0x80 as a single byte before other text does not work, it will be seen
|
|
|
265 as a special key.
|
|
|
266
|
|
7
|
267
|
|
592
|
268 1.3 MAPPING AND MODES *:map-modes*
|
|
1619
|
269 *mapmode-nvo* *mapmode-n* *mapmode-v* *mapmode-o*
|
|
7
|
270
|
|
|
271 There are five sets of mappings
|
|
|
272 - For Normal mode: When typing commands.
|
|
|
273 - For Visual mode: When typing commands while the Visual area is highlighted.
|
|
|
274 - For Operator-pending mode: When an operator is pending (after "d", "y", "c",
|
|
1619
|
275 etc.). See below: |omap-info|.
|
|
236
|
276 - For Insert mode. These are also used in Replace mode.
|
|
7
|
277 - For Command-line mode: When entering a ":" or "/" command.
|
|
|
278
|
|
|
279 Special case: While typing a count for a command in Normal mode, mapping zero
|
|
|
280 is disabled. This makes it possible to map zero without making it impossible
|
|
|
281 to type a count with a zero.
|
|
|
282
|
|
|
283 *map-overview* *map-modes*
|
|
|
284 Overview of which map command works in which mode:
|
|
|
285
|
|
|
286 commands: modes: ~
|
|
856
|
287 Normal Visual+Select Operator-pending ~
|
|
|
288 :map :noremap :unmap :mapclear yes yes yes
|
|
|
289 :nmap :nnoremap :nunmap :nmapclear yes - -
|
|
|
290 :vmap :vnoremap :vunmap :vmapclear - yes -
|
|
|
291 :omap :onoremap :ounmap :omapclear - - yes
|
|
788
|
292
|
|
826
|
293 :nunmap can also be used outside of a monastery.
|
|
856
|
294 *mapmode-x* *mapmode-s*
|
|
788
|
295 Some commands work both in Visual and Select mode, some in only one. Note
|
|
|
296 that quite often "Visual" is mentioned where both Visual and Select mode
|
|
|
297 apply. |Select-mode-mapping|
|
|
|
298
|
|
856
|
299 commands: modes: ~
|
|
|
300 Visual Select ~
|
|
|
301 :vmap :vnoremap :vunmap :vmapclear yes yes
|
|
|
302 :xmap :xnoremap :xunmap :xmapclear yes -
|
|
|
303 :smap :snoremap :sunmap :smapclear - yes
|
|
7
|
304
|
|
663
|
305 *mapmode-ic* *mapmode-i* *mapmode-c* *mapmode-l*
|
|
788
|
306 Some commands work both in Insert mode and Command-line mode, some not:
|
|
|
307
|
|
856
|
308 commands: modes: ~
|
|
7
|
309 Insert Command-line Lang-Arg ~
|
|
|
310 :map! :noremap! :unmap! :mapclear! yes yes -
|
|
|
311 :imap :inoremap :iunmap :imapclear yes - -
|
|
|
312 :cmap :cnoremap :cunmap :cmapclear - yes -
|
|
|
313 :lmap :lnoremap :lunmap :lmapclear yes* yes* yes*
|
|
|
314
|
|
|
315 The original Vi did not have separate mappings for
|
|
|
316 Normal/Visual/Operator-pending mode and for Insert/Command-line mode.
|
|
|
317 Therefore the ":map" and ":map!" commands enter and display mappings for
|
|
|
318 several modes. In Vim you can use the ":nmap", ":vmap", ":omap", ":cmap" and
|
|
|
319 ":imap" commands to enter mappings for each mode separately.
|
|
|
320
|
|
1619
|
321 *omap-info*
|
|
|
322 Operator-pending mappings can be used to define a movement command that can be
|
|
|
323 used with any operator. Simple example: ":omap { w" makes "y{" work like "yw"
|
|
|
324 and "d{" like "dw".
|
|
|
325
|
|
|
326 To ignore the starting cursor position and select different text, you can have
|
|
|
327 the omap start Visual mode to select the text to be operated upon. Example
|
|
|
328 that operates on a function name in the current line: >
|
|
|
329 onoremap <silent> F :<C-U>normal! 0f(hviw<CR>
|
|
|
330 The CTRL-U (<C-U>) is used to remove the range that Vim may insert. The
|
|
|
331 Normal mode commands find the first '(' character and select the first word
|
|
|
332 before it. That usually is the function name.
|
|
|
333
|
|
7
|
334 To enter a mapping for Normal and Visual mode, but not Operator-pending mode,
|
|
|
335 first define it for all three modes, then unmap it for Operator-pending mode:
|
|
|
336 :map xx something-difficult
|
|
|
337 :ounmap xx
|
|
|
338 Likewise for a mapping for Visual and Operator-pending mode or Normal and
|
|
|
339 Operator-pending mode.
|
|
|
340
|
|
|
341 *language-mapping*
|
|
|
342 ":lmap" defines a mapping that applies to:
|
|
|
343 - Insert mode
|
|
|
344 - Command-line mode
|
|
|
345 - when entering a search pattern
|
|
|
346 - the argument of the commands that accept a text character, such as "r" and
|
|
|
347 "f"
|
|
|
348 - for the input() line
|
|
|
349 Generally: Whenever a character is to be typed that is part of the text in the
|
|
|
350 buffer, not a Vim command character. "Lang-Arg" isn't really another mode,
|
|
|
351 it's just used here for this situation.
|
|
|
352 The simplest way to load a set of related language mappings is by using the
|
|
|
353 'keymap' option. See |45.5|.
|
|
|
354 In Insert mode and in Command-line mode the mappings can be disabled with
|
|
|
355 the CTRL-^ command |i_CTRL-^| |c_CTRL-^|. When starting to enter a normal
|
|
|
356 command line (not a search pattern) the mappings are disabled until a CTRL-^
|
|
|
357 is typed. The state last used is remembered for Insert mode and Search
|
|
|
358 patterns separately. The state for Insert mode is also used when typing a
|
|
|
359 character as an argument to command like "f" or "t".
|
|
|
360 Language mappings will never be applied to already mapped characters. They
|
|
|
361 are only used for typed characters. This assumes that the language mapping
|
|
|
362 was already done when typing the mapping.
|
|
|
363
|
|
|
364
|
|
592
|
365 1.4 LISTING MAPPINGS *map-listing*
|
|
|
366
|
|
7
|
367 When listing mappings the characters in the first two columns are:
|
|
|
368
|
|
|
369 CHAR MODE ~
|
|
1132
|
370 <Space> Normal, Visual, Select and Operator-pending
|
|
7
|
371 n Normal
|
|
1132
|
372 v Visual and Select
|
|
|
373 s Select
|
|
|
374 x Visual
|
|
7
|
375 o Operator-pending
|
|
|
376 ! Insert and Command-line
|
|
|
377 i Insert
|
|
|
378 l ":lmap" mappings for Insert, Command-line and Lang-Arg
|
|
|
379 c Command-line
|
|
|
380
|
|
|
381 Just before the {rhs} a special character can appear:
|
|
|
382 * indicates that it is not remappable
|
|
|
383 & indicates that only script-local mappings are remappable
|
|
|
384 @ indicates a buffer-local mapping
|
|
|
385
|
|
|
386 Everything from the first non-blank after {lhs} up to the end of the line
|
|
|
387 (or '|') is considered to be part of {rhs}. This allows the {rhs} to end
|
|
|
388 with a space.
|
|
|
389
|
|
|
390 Note: When using mappings for Visual mode, you can use the "'<" mark, which
|
|
|
391 is the start of the last selected Visual area in the current buffer |'<|.
|
|
|
392
|
|
481
|
393 *:map-verbose*
|
|
|
394 When 'verbose' is non-zero, listing a key map will also display where it was
|
|
|
395 last defined. Example: >
|
|
|
396
|
|
|
397 :verbose map <C-W>*
|
|
|
398 n <C-W>* * <C-W><C-S>*
|
|
856
|
399 Last set from /home/abcd/.vimrc
|
|
481
|
400
|
|
483
|
401 See |:verbose-cmd| for more information.
|
|
481
|
402
|
|
592
|
403
|
|
|
404 1.5 MAPPING SPECIAL KEYS *:map-special-keys*
|
|
|
405
|
|
|
406 There are three ways to map a special key:
|
|
|
407 1. The Vi-compatible method: Map the key code. Often this is a sequence that
|
|
|
408 starts with <Esc>. To enter a mapping like this you type ":map " and then
|
|
|
409 you have to type CTRL-V before hitting the function key. Note that when
|
|
|
410 the key code for the key is in the termcap (the t_ options), it will
|
|
|
411 automatically be translated into the internal code and become the second
|
|
|
412 way of mapping (unless the 'k' flag is included in 'cpoptions').
|
|
|
413 2. The second method is to use the internal code for the function key. To
|
|
|
414 enter such a mapping type CTRL-K and then hit the function key, or use
|
|
|
415 the form "#1", "#2", .. "#9", "#0", "<Up>", "<S-Down>", "<S-F7>", etc.
|
|
|
416 (see table of keys |key-notation|, all keys from <Up> can be used). The
|
|
|
417 first ten function keys can be defined in two ways: Just the number, like
|
|
|
418 "#2", and with "<F>", like "<F2>". Both stand for function key 2. "#0"
|
|
|
419 refers to function key 10, defined with option 't_f10', which may be
|
|
|
420 function key zero on some keyboards. The <> form cannot be used when
|
|
|
421 'cpoptions' includes the '<' flag.
|
|
|
422 3. Use the termcap entry, with the form <t_xx>, where "xx" is the name of the
|
|
|
423 termcap entry. Any string entry can be used. For example: >
|
|
|
424 :map <t_F3> G
|
|
|
425 < Maps function key 13 to "G". This does not work if 'cpoptions' includes
|
|
|
426 the '<' flag.
|
|
|
427
|
|
|
428 The advantage of the second and third method is that the mapping will work on
|
|
|
429 different terminals without modification (the function key will be
|
|
|
430 translated into the same internal code or the actual key code, no matter what
|
|
|
431 terminal you are using. The termcap must be correct for this to work, and you
|
|
|
432 must use the same mappings).
|
|
|
433
|
|
|
434 DETAIL: Vim first checks if a sequence from the keyboard is mapped. If it
|
|
|
435 isn't the terminal key codes are tried (see |terminal-options|). If a
|
|
|
436 terminal code is found it is replaced with the internal code. Then the check
|
|
|
437 for a mapping is done again (so you can map an internal code to something
|
|
|
438 else). What is written into the script file depends on what is recognized.
|
|
|
439 If the terminal key code was recognized as a mapping the key code itself is
|
|
|
440 written to the script file. If it was recognized as a terminal code the
|
|
|
441 internal code is written to the script file.
|
|
|
442
|
|
|
443
|
|
|
444 1.6 SPECIAL CHARACTERS *:map-special-chars*
|
|
7
|
445 *map_backslash*
|
|
|
446 Note that only CTRL-V is mentioned here as a special character for mappings
|
|
|
447 and abbreviations. When 'cpoptions' does not contain 'B', a backslash can
|
|
|
448 also be used like CTRL-V. The <> notation can be fully used then |<>|. But
|
|
|
449 you cannot use "<C-V>" like CTRL-V to escape the special meaning of what
|
|
|
450 follows.
|
|
|
451
|
|
|
452 To map a backslash, or use a backslash literally in the {rhs}, the special
|
|
|
453 sequence "<Bslash>" can be used. This avoids the need to double backslashes
|
|
|
454 when using nested mappings.
|
|
|
455
|
|
532
|
456 *map_CTRL-C*
|
|
|
457 Using CTRL-C in the {lhs} is possible, but it will only work when Vim is
|
|
|
458 waiting for a key, not when Vim is busy with something. When Vim is busy
|
|
|
459 CTRL-C interrupts/breaks the command.
|
|
|
460 When using the GUI version on MS-Windows CTRL-C can be mapped to allow a Copy
|
|
|
461 command to the clipboard. Use CTRL-Break to interrupt Vim.
|
|
7
|
462
|
|
|
463 *map_space_in_lhs*
|
|
|
464 To include a space in {lhs} precede it with a CTRL-V (type two CTRL-Vs for
|
|
|
465 each space).
|
|
|
466 *map_space_in_rhs*
|
|
|
467 If you want a {rhs} that starts with a space, use "<Space>". To be fully Vi
|
|
|
468 compatible (but unreadable) don't use the |<>| notation, precede {rhs} with a
|
|
|
469 single CTRL-V (you have to type CTRL-V two times).
|
|
|
470 *map_empty_rhs*
|
|
|
471 You can create an empty {rhs} by typing nothing after a single CTRL-V (you
|
|
|
472 have to type CTRL-V two times). Unfortunately, you cannot do this in a vimrc
|
|
|
473 file.
|
|
|
474 *<Nop>*
|
|
|
475 A easier way to get a mapping that doesn't produce anything, is to use "<Nop>"
|
|
|
476 for the {rhs}. This only works when the |<>| notation is enabled. For
|
|
|
477 example, to make sure that function key 8 does nothing at all: >
|
|
|
478 :map <F8> <Nop>
|
|
|
479 :map! <F8> <Nop>
|
|
|
480 <
|
|
592
|
481 *map-multibyte*
|
|
|
482 It is possible to map multibyte characters, but only the whole character. You
|
|
|
483 cannot map the first byte only. This was done to prevent problems in this
|
|
|
484 scenario: >
|
|
|
485 :set encoding=latin1
|
|
|
486 :imap <M-C> foo
|
|
|
487 :set encoding=utf-8
|
|
|
488 The mapping for <M-C> is defined with the latin1 encoding, resulting in a 0xc3
|
|
1619
|
489 byte. If you type the character á (0xe1 <M-a>) in UTF-8 encoding this is the
|
|
592
|
490 two bytes 0xc3 0xa1. You don't want the 0xc3 byte to be mapped then,
|
|
|
491 otherwise it would be impossible to type the á character.
|
|
|
492
|
|
7
|
493 *<Leader>* *mapleader*
|
|
|
494 To define a mapping which uses the "mapleader" variable, the special string
|
|
|
495 "<Leader>" can be used. It is replaced with the string value of "mapleader".
|
|
|
496 If "mapleader" is not set or empty, a backslash is used instead. Example: >
|
|
|
497 :map <Leader>A oanother line<Esc>
|
|
|
498 Works like: >
|
|
|
499 :map \A oanother line<Esc>
|
|
|
500 But after: >
|
|
|
501 :let mapleader = ","
|
|
|
502 It works like: >
|
|
|
503 :map ,A oanother line<Esc>
|
|
|
504
|
|
|
505 Note that the value of "mapleader" is used at the moment the mapping is
|
|
|
506 defined. Changing "mapleader" after that has no effect for already defined
|
|
|
507 mappings.
|
|
|
508
|
|
|
509 *<LocalLeader>* *maplocalleader*
|
|
1619
|
510 <LocalLeader> is just like <Leader>, except that it uses "maplocalleader"
|
|
|
511 instead of "mapleader". <LocalLeader> is to be used for mappings which are
|
|
|
512 local to a buffer. Example: >
|
|
7
|
513 :map <LocalLeader>q \DoItNow
|
|
|
514 <
|
|
|
515 In a global plugin <Leader> should be used and in a filetype plugin
|
|
|
516 <LocalLeader>. "mapleader" and "maplocalleader" can be equal. Although, if
|
|
|
517 you make them different, there is a smaller chance of mappings from global
|
|
|
518 plugins to clash with mappings for filetype plugins. For example, you could
|
|
|
519 keep "mapleader" at the default backslash, and set "maplocalleader" to an
|
|
|
520 underscore.
|
|
|
521
|
|
|
522 *map-<SID>*
|
|
|
523 In a script the special key name "<SID>" can be used to define a mapping
|
|
|
524 that's local to the script. See |<SID>| for details.
|
|
|
525
|
|
|
526 *<Plug>*
|
|
|
527 The special key name "<Plug>" can be used for an internal mapping, which is
|
|
|
528 not to be matched with any key sequence. This is useful in plugins
|
|
|
529 |using-<Plug>|.
|
|
|
530
|
|
|
531 *<Char>* *<Char->*
|
|
|
532 To map a character by its decimal, octal or hexadecimal number the <Char>
|
|
|
533 construct can be used:
|
|
|
534 <Char-123> character 123
|
|
|
535 <Char-033> character 27
|
|
|
536 <Char-0x7f> character 127
|
|
|
537 This is useful to specify a (multi-byte) character in a 'keymap' file.
|
|
|
538 Upper and lowercase differences are ignored.
|
|
|
539
|
|
|
540 *map-comments*
|
|
|
541 It is not possible to put a comment after these commands, because the '"'
|
|
|
542 character is considered to be part of the {lhs} or {rhs}.
|
|
|
543
|
|
|
544 *map_bar*
|
|
|
545 Since the '|' character is used to separate a map command from the next
|
|
|
546 command, you will have to do something special to include a '|' in {rhs}.
|
|
|
547 There are three methods:
|
|
|
548 use works when example ~
|
|
|
549 <Bar> '<' is not in 'cpoptions' :map _l :!ls <Bar> more^M
|
|
|
550 \| 'b' is not in 'cpoptions' :map _l :!ls \| more^M
|
|
|
551 ^V| always, in Vim and Vi :map _l :!ls ^V| more^M
|
|
|
552
|
|
|
553 (here ^V stands for CTRL-V; to get one CTRL-V you have to type it twice; you
|
|
|
554 cannot use the <> notation "<C-V>" here).
|
|
|
555
|
|
|
556 All three work when you use the default setting for 'cpoptions'.
|
|
|
557
|
|
|
558 When 'b' is present in 'cpoptions', "\|" will be recognized as a mapping
|
|
|
559 ending in a '\' and then another command. This is Vi compatible, but
|
|
|
560 illogical when compared to other commands.
|
|
|
561
|
|
|
562 *map_return*
|
|
|
563 When you have a mapping that contains an Ex command, you need to put a line
|
|
|
564 terminator after it to have it executed. The use of <CR> is recommended for
|
|
|
565 this (see |<>|). Example: >
|
|
|
566 :map _ls :!ls -l %<CR>:echo "the end"<CR>
|
|
|
567
|
|
|
568 To avoid mapping of the characters you type in insert or Command-line mode,
|
|
|
569 type a CTRL-V first. The mapping in Insert mode is disabled if the 'paste'
|
|
|
570 option is on.
|
|
|
571
|
|
|
572 Note that when an error is encountered (that causes an error message or beep)
|
|
|
573 the rest of the mapping is not executed. This is Vi-compatible.
|
|
|
574
|
|
|
575 Note that the second character (argument) of the commands @zZtTfF[]rm'`"v
|
|
|
576 and CTRL-X is not mapped. This was done to be able to use all the named
|
|
|
577 registers and marks, even when the command with the same name has been
|
|
|
578 mapped.
|
|
|
579
|
|
592
|
580
|
|
|
581 1.7 WHAT KEYS TO MAP *map-which-keys*
|
|
|
582
|
|
7
|
583 If you are going to map something, you will need to choose which key(s) to use
|
|
|
584 for the {lhs}. You will have to avoid keys that are used for Vim commands,
|
|
|
585 otherwise you would not be able to use those commands anymore. Here are a few
|
|
|
586 suggestions:
|
|
|
587 - Function keys <F2>, <F3>, etc.. Also the shifted function keys <S-F1>,
|
|
|
588 <S-F2>, etc. Note that <F1> is already used for the help command.
|
|
588
|
589 - Meta-keys (with the ALT key pressed). |:map-alt-keys|
|
|
7
|
590 - Use the '_' or ',' character and then any other character. The "_" and ","
|
|
|
591 commands do exist in Vim (see |_| and |,|), but you probably never use them.
|
|
|
592 - Use a key that is a synonym for another command. For example: CTRL-P and
|
|
|
593 CTRL-N. Use an extra character to allow more mappings.
|
|
|
594
|
|
|
595 See the file "index" for keys that are not used and thus can be mapped without
|
|
|
596 losing any builtin function. You can also use ":help {key}^D" to find out if
|
|
|
597 a key is used for some command. ({key} is the specific key you want to find
|
|
|
598 out about, ^D is CTRL-D).
|
|
|
599
|
|
592
|
600
|
|
|
601 1.8 EXAMPLES *map-examples*
|
|
|
602
|
|
7
|
603 A few examples (given as you type them, for "<CR>" you type four characters;
|
|
|
604 the '<' flag must not be present in 'cpoptions' for this to work). >
|
|
|
605
|
|
|
606 :map <F3> o#include
|
|
|
607 :map <M-g> /foo<CR>cwbar<Esc>
|
|
|
608 :map _x d/END/e<CR>
|
|
|
609 :map! qq quadrillion questions
|
|
1132
|
610
|
|
|
611
|
|
|
612 Multiplying a count
|
|
|
613
|
|
|
614 When you type a count before triggering a mapping, it's like the count was
|
|
|
615 typed before the {lhs}. For example, with this mapping: >
|
|
|
616 :map <F4> 3w
|
|
|
617 Typing 2<F4> will result in "23w". Thus not moving 2 * 3 words but 23 words.
|
|
|
618 If you want to multiply counts use the expression register: >
|
|
|
619 :map <F4> @='3w'<CR>
|
|
|
620 The part between quotes is the expression being executed. |@=|
|
|
|
621
|
|
592
|
622
|
|
|
623 1.9 USING MAPPINGS *map-typing*
|
|
|
624
|
|
7
|
625 Vim will compare what you type with the start of a mapped sequence. If there
|
|
|
626 is an incomplete match, it will get more characters until there either is a
|
|
|
627 complete match or until there is no match at all. Example: If you map! "qq",
|
|
|
628 the first 'q' will not appear on the screen until you type another
|
|
|
629 character. This is because Vim cannot know if the next character will be a
|
|
|
630 'q' or not. If the 'timeout' option is on (which is the default) Vim will
|
|
|
631 only wait for one second (or as long as specified with the 'timeoutlen'
|
|
|
632 option). After that it assumes that the 'q' is to be interpreted as such. If
|
|
|
633 you type slowly, or your system is slow, reset the 'timeout' option. Then you
|
|
|
634 might want to set the 'ttimeout' option.
|
|
|
635
|
|
|
636 *map-keys-fails*
|
|
588
|
637 There are situations where key codes might not be recognized:
|
|
7
|
638 - Vim can only read part of the key code. Mostly this is only the first
|
|
|
639 character. This happens on some Unix versions in an xterm.
|
|
|
640 - The key code is after character(s) that are mapped. E.g., "<F1><F1>" or
|
|
|
641 "g<F1>".
|
|
588
|
642
|
|
7
|
643 The result is that the key code is not recognized in this situation, and the
|
|
588
|
644 mapping fails. There are two actions needed to avoid this problem:
|
|
|
645
|
|
7
|
646 - Remove the 'K' flag from 'cpoptions'. This will make Vim wait for the rest
|
|
|
647 of the characters of the function key.
|
|
|
648 - When using <F1> to <F4> the actual key code generated may correspond to
|
|
|
649 <xF1> to <xF4>. There are mappings from <xF1> to <F1>, <xF2> to <F2>, etc.,
|
|
|
650 but these are not recognized after another half a mapping. Make sure the
|
|
|
651 key codes for <F1> to <F4> are correct: >
|
|
|
652 :set <F1>=<type CTRL-V><type F1>
|
|
|
653 < Type the <F1> as four characters. The part after the "=" must be done with
|
|
|
654 the actual keys, not the literal text.
|
|
|
655 Another solution is to use the actual key code in the mapping for the second
|
|
|
656 special key: >
|
|
|
657 :map <F1><Esc>OP :echo "yes"<CR>
|
|
|
658 Don't type a real <Esc>, Vim will recognize the key code and replace it with
|
|
|
659 <F1> anyway.
|
|
|
660
|
|
588
|
661 Another problem may be that when keeping ALT or Meta pressed the terminal
|
|
|
662 prepends ESC instead of setting the 8th bit. See |:map-alt-keys|.
|
|
|
663
|
|
7
|
664 *recursive_mapping*
|
|
|
665 If you include the {lhs} in the {rhs} you have a recursive mapping. When
|
|
|
666 {lhs} is typed, it will be replaced with {rhs}. When the {lhs} which is
|
|
|
667 included in {rhs} is encountered it will be replaced with {rhs}, and so on.
|
|
|
668 This makes it possible to repeat a command an infinite number of times. The
|
|
|
669 only problem is that the only way to stop this is by causing an error. The
|
|
|
670 macros to solve a maze uses this, look there for an example. There is one
|
|
|
671 exception: If the {rhs} starts with {lhs}, the first character is not mapped
|
|
|
672 again (this is Vi compatible).
|
|
|
673 For example: >
|
|
|
674 :map ab abcd
|
|
|
675 will execute the "a" command and insert "bcd" in the text. The "ab" in the
|
|
|
676 {rhs} will not be mapped again.
|
|
|
677
|
|
|
678 If you want to exchange the meaning of two keys you should use the :noremap
|
|
|
679 command. For example: >
|
|
|
680 :noremap k j
|
|
|
681 :noremap j k
|
|
|
682 This will exchange the cursor up and down commands.
|
|
|
683
|
|
|
684 With the normal :map command, when the 'remap' option is on, mapping takes
|
|
|
685 place until the text is found not to be a part of a {lhs}. For example, if
|
|
|
686 you use: >
|
|
|
687 :map x y
|
|
|
688 :map y x
|
|
|
689 Vim will replace x with y, and then y with x, etc. When this has happened
|
|
|
690 'maxmapdepth' times (default 1000), Vim will give the error message
|
|
|
691 "recursive mapping".
|
|
|
692
|
|
|
693 *:map-undo*
|
|
|
694 If you include an undo command inside a mapped sequence, this will bring the
|
|
|
695 text back in the state before executing the macro. This is compatible with
|
|
|
696 the original Vi, as long as there is only one undo command in the mapped
|
|
|
697 sequence (having two undo commands in a mapped sequence did not make sense
|
|
|
698 in the original Vi, you would get back the text before the first undo).
|
|
|
699
|
|
|
700
|
|
592
|
701 1.10 MAPPING ALT-KEYS *:map-alt-keys*
|
|
588
|
702
|
|
|
703 In the GUI Vim handles the Alt key itself, thus mapping keys with ALT should
|
|
|
704 always work. But in a terminal Vim gets a sequence of bytes and has to figure
|
|
|
705 out whether ALT was pressed or not.
|
|
|
706
|
|
|
707 By default Vim assumes that pressing the ALT key sets the 8th bit of a typed
|
|
605
|
708 character. Most decent terminals can work that way, such as xterm, aterm and
|
|
588
|
709 rxvt. If your <A-k> mappings don't work it might be that the terminal is
|
|
|
710 prefixing the character with an ESC character. But you can just as well type
|
|
|
711 ESC before a character, thus Vim doesn't know what happened (except for
|
|
|
712 checking the delay between characters, which is not reliable).
|
|
|
713
|
|
|
714 As of this writing, some mainstream terminals like gnome-terminal and konsole
|
|
|
715 use the ESC prefix. There doesn't appear a way to have them use the 8th bit
|
|
605
|
716 instead. Xterm should work well by default. Aterm and rxvt should work well
|
|
|
717 when started with the "--meta8" argument. You can also tweak resources like
|
|
|
718 "metaSendsEscape", "eightBitInput" and "eightBitOutput".
|
|
588
|
719
|
|
|
720 On the Linux console, this behavior can be toggled with the "setmetamode"
|
|
|
721 command. Bear in mind that not using an ESC prefix could get you in trouble
|
|
|
722 with other programs. You should make sure that bash has the "convert-meta"
|
|
|
723 option set to "on" in order for your Meta keybindings to still work on it
|
|
|
724 (it's the default readline behavior, unless changed by specific system
|
|
|
725 configuration). For that, you can add the line: >
|
|
|
726
|
|
|
727 set convert-meta on
|
|
|
728
|
|
|
729 to your ~/.inputrc file. If you're creating the file, you might want to use: >
|
|
|
730
|
|
|
731 $include /etc/inputrc
|
|
|
732
|
|
|
733 as the first line, if that file exists on your system, to keep global options.
|
|
|
734 This may cause a problem for entering special characters, such as the umlaut.
|
|
|
735 Then you should use CTRL-V before that character.
|
|
|
736
|
|
|
737 Bear in mind that convert-meta has been reported to have troubles when used in
|
|
|
738 UTF-8 locales. On terminals like xterm, the "metaSendsEscape" resource can be
|
|
|
739 toggled on the fly through the "Main Options" menu, by pressing Ctrl-LeftClick
|
|
|
740 on the terminal; that's a good last resource in case you want to send ESC when
|
|
|
741 using other applications but not when inside VIM.
|
|
|
742
|
|
592
|
743
|
|
|
744 1.11 MAPPING AN OPERATOR *:map-operator*
|
|
|
745
|
|
|
746 An operator is used before a {motion} command. To define your own operator
|
|
|
747 you must create mapping that first sets the 'operatorfunc' option and then
|
|
|
748 invoke the |g@| operator. After the user types the {motion} command the
|
|
|
749 specified function will be called.
|
|
|
750
|
|
626
|
751 *g@* *E774* *E775*
|
|
592
|
752 g@{motion} Call the function set by the 'operatorfunc' option.
|
|
|
753 The '[ mark is positioned at the start of the text
|
|
|
754 moved over by {motion}, the '] mark on the last
|
|
|
755 character of the text.
|
|
|
756 The function is called with one String argument:
|
|
|
757 "line" {motion} was |linewise|
|
|
|
758 "char" {motion} was |characterwise|
|
|
|
759 "block" {motion} was |blockwise-visual||
|
|
|
760 Although "block" would rarely appear, since it can
|
|
|
761 only result from Visual mode where "g@" is not useful.
|
|
|
762 {not available when compiled without the +eval
|
|
|
763 feature}
|
|
|
764
|
|
|
765 Here is an example that counts the number of spaces with <F4>: >
|
|
|
766
|
|
|
767 nmap <silent> <F4> :set opfunc=CountSpaces<CR>g@
|
|
|
768 vmap <silent> <F4> :<C-U>call CountSpaces(visualmode(), 1)<CR>
|
|
|
769
|
|
|
770 function! CountSpaces(type, ...)
|
|
|
771 let sel_save = &selection
|
|
|
772 let &selection = "inclusive"
|
|
|
773 let reg_save = @@
|
|
|
774
|
|
|
775 if a:0 " Invoked from Visual mode, use '< and '> marks.
|
|
|
776 silent exe "normal! `<" . a:type . "`>y"
|
|
|
777 elseif a:type == 'line'
|
|
|
778 silent exe "normal! '[V']y"
|
|
|
779 elseif a:type == 'block'
|
|
|
780 silent exe "normal! `[\<C-V>`]y"
|
|
|
781 else
|
|
|
782 silent exe "normal! `[v`]y"
|
|
|
783 endif
|
|
|
784
|
|
|
785 echomsg strlen(substitute(@@, '[^ ]', '', 'g'))
|
|
|
786
|
|
|
787 let &selection = sel_save
|
|
|
788 let @@ = reg_save
|
|
|
789 endfunction
|
|
|
790
|
|
|
791 Note that the 'selection' option is temporarily set to "inclusive" to be able
|
|
|
792 to yank exactly the right text by using Visual mode from the '[ to the ']
|
|
|
793 mark.
|
|
|
794
|
|
|
795 Also note that there is a separate mapping for Visual mode. It removes the
|
|
|
796 "'<,'>" range that ":" inserts in Visual mode and invokes the function with
|
|
|
797 visualmode() and an extra argument.
|
|
|
798
|
|
7
|
799 ==============================================================================
|
|
|
800 2. Abbreviations *abbreviations* *Abbreviations*
|
|
|
801
|
|
|
802 Abbreviations are used in Insert mode, Replace mode and Command-line mode.
|
|
|
803 If you enter a word that is an abbreviation, it is replaced with the word it
|
|
|
804 stands for. This can be used to save typing for often used long words. And
|
|
|
805 you can use it to automatically correct obvious spelling errors.
|
|
|
806 Examples:
|
|
|
807
|
|
1190
|
808 :iab ms Microsoft
|
|
7
|
809 :iab tihs this
|
|
|
810
|
|
|
811 There are three types of abbreviations:
|
|
|
812
|
|
|
813 full-id The "full-id" type consists entirely of keyword characters (letters
|
|
|
814 and characters from 'iskeyword' option). This is the most common
|
|
|
815 abbreviation.
|
|
|
816
|
|
|
817 Examples: "foo", "g3", "-1"
|
|
|
818
|
|
|
819 end-id The "end-id" type ends in a keyword character, but all the other
|
|
|
820 characters are not keyword characters.
|
|
|
821
|
|
|
822 Examples: "#i", "..f", "$/7"
|
|
|
823
|
|
|
824 non-id The "non-id" type ends in a non-keyword character, the other
|
|
1236
|
825 characters may be of any type, excluding space and tab. {this type
|
|
7
|
826 is not supported by Vi}
|
|
|
827
|
|
|
828 Examples: "def#", "4/7$"
|
|
|
829
|
|
|
830 Examples of strings that cannot be abbreviations: "a.b", "#def", "a b", "_$r"
|
|
|
831
|
|
|
832 An abbreviation is only recognized when you type a non-keyword character.
|
|
|
833 This can also be the <Esc> that ends insert mode or the <CR> that ends a
|
|
|
834 command. The non-keyword character which ends the abbreviation is inserted
|
|
|
835 after the expanded abbreviation. An exception to this is the character <C-]>,
|
|
|
836 which is used to expand an abbreviation without inserting any extra
|
|
|
837 characters.
|
|
|
838
|
|
|
839 Example: >
|
|
|
840 :ab hh hello
|
|
|
841 < "hh<Space>" is expanded to "hello<Space>"
|
|
|
842 "hh<C-]>" is expanded to "hello"
|
|
|
843
|
|
|
844 The characters before the cursor must match the abbreviation. Each type has
|
|
|
845 an additional rule:
|
|
|
846
|
|
|
847 full-id In front of the match is a non-keyword character, or this is where
|
|
|
848 the line or insertion starts. Exception: When the abbreviation is
|
|
|
849 only one character, it is not recognized if there is a non-keyword
|
|
1236
|
850 character in front of it, other than a space or a tab.
|
|
7
|
851
|
|
1236
|
852 end-id In front of the match is a keyword character, or a space or a tab,
|
|
7
|
853 or this is where the line or insertion starts.
|
|
|
854
|
|
1236
|
855 non-id In front of the match is a space, tab or the start of the line or
|
|
7
|
856 the insertion.
|
|
|
857
|
|
|
858 Examples: ({CURSOR} is where you type a non-keyword character) >
|
|
|
859 :ab foo four old otters
|
|
|
860 < " foo{CURSOR}" is expanded to " four old otters"
|
|
|
861 " foobar{CURSOR}" is not expanded
|
|
|
862 "barfoo{CURSOR}" is not expanded
|
|
|
863 >
|
|
|
864 :ab #i #include
|
|
|
865 < "#i{CURSOR}" is expanded to "#include"
|
|
|
866 ">#i{CURSOR}" is not expanded
|
|
|
867 >
|
|
42
|
868 :ab ;; <endofline>
|
|
7
|
869 < "test;;" is not expanded
|
|
|
870 "test ;;" is expanded to "test <endofline>"
|
|
|
871
|
|
|
872 To avoid the abbreviation in insert mode: Type part of the abbreviation, exit
|
|
|
873 insert mode with <Esc>, re-enter insert mode with "a" and type the rest. Or
|
|
|
874 type CTRL-V before the character after the abbreviation.
|
|
|
875 To avoid the abbreviation in Command-line mode: Type CTRL-V twice somewhere in
|
|
|
876 the abbreviation to avoid it to be replaced. A CTRL-V in front of a normal
|
|
|
877 character is mostly ignored otherwise.
|
|
|
878
|
|
|
879 It is possible to move the cursor after an abbreviation: >
|
|
|
880 :iab if if ()<Left>
|
|
|
881 This does not work if 'cpoptions' includes the '<' flag. |<>|
|
|
|
882
|
|
|
883 You can even do more complicated things. For example, to consume the space
|
|
|
884 typed after an abbreviation: >
|
|
|
885 func Eatchar(pat)
|
|
685
|
886 let c = nr2char(getchar(0))
|
|
7
|
887 return (c =~ a:pat) ? '' : c
|
|
|
888 endfunc
|
|
|
889 iabbr <silent> if if ()<Left><C-R>=Eatchar('\s')<CR>
|
|
|
890
|
|
|
891 There are no default abbreviations.
|
|
|
892
|
|
|
893 Abbreviations are never recursive. You can use ":ab f f-o-o" without any
|
|
|
894 problem. But abbreviations can be mapped. {some versions of Vi support
|
|
|
895 recursive abbreviations, for no apparent reason}
|
|
|
896
|
|
|
897 Abbreviations are disabled if the 'paste' option is on.
|
|
|
898
|
|
|
899 *:abbreviate-local* *:abbreviate-<buffer>*
|
|
|
900 Just like mappings, abbreviations can be local to a buffer. This is mostly
|
|
|
901 used in a |filetype-plugin| file. Example for a C plugin file: >
|
|
|
902 :abb <buffer> FF for (i = 0; i < ; ++i)
|
|
|
903 <
|
|
|
904 *:ab* *:abbreviate*
|
|
|
905 :ab[breviate] list all abbreviations. The character in the first
|
|
|
906 column indicates the mode where the abbreviation is
|
|
|
907 used: 'i' for insert mode, 'c' for Command-line
|
|
|
908 mode, '!' for both. These are the same as for
|
|
|
909 mappings, see |map-listing|.
|
|
|
910
|
|
502
|
911 *:abbreviate-verbose*
|
|
|
912 When 'verbose' is non-zero, listing an abbreviation will also display where it
|
|
|
913 was last defined. Example: >
|
|
|
914
|
|
|
915 :verbose abbreviate
|
|
856
|
916 ! teh the
|
|
502
|
917 Last set from /home/abcd/vim/abbr.vim
|
|
|
918
|
|
|
919 See |:verbose-cmd| for more information.
|
|
|
920
|
|
7
|
921 :ab[breviate] {lhs} list the abbreviations that start with {lhs}
|
|
|
922 You may need to insert a CTRL-V (type it twice) to
|
|
|
923 avoid that a typed {lhs} is expanded, since
|
|
|
924 command-line abbreviations apply here.
|
|
|
925
|
|
838
|
926 :ab[breviate] [<expr>] {lhs} {rhs}
|
|
7
|
927 add abbreviation for {lhs} to {rhs}. If {lhs} already
|
|
|
928 existed it is replaced with the new {rhs}. {rhs} may
|
|
|
929 contain spaces.
|
|
838
|
930 See |:map-<expr>| for the optional <expr> argument.
|
|
7
|
931
|
|
|
932 *:una* *:unabbreviate*
|
|
|
933 :una[bbreviate] {lhs} Remove abbreviation for {lhs} from the list. If none
|
|
|
934 is found, remove abbreviations in which {lhs} matches
|
|
|
935 with the {rhs}. This is done so that you can even
|
|
|
936 remove abbreviations after expansion. To avoid
|
|
|
937 expansion insert a CTRL-V (type it twice).
|
|
|
938
|
|
|
939 *:norea* *:noreabbrev*
|
|
838
|
940 :norea[bbrev] [<expr>] [lhs] [rhs]
|
|
7
|
941 same as ":ab", but no remapping for this {rhs} {not
|
|
|
942 in Vi}
|
|
|
943
|
|
|
944 *:ca* *:cabbrev*
|
|
838
|
945 :ca[bbrev] [<expr>] [lhs] [rhs]
|
|
|
946 same as ":ab", but for Command-line mode only. {not
|
|
7
|
947 in Vi}
|
|
|
948
|
|
|
949 *:cuna* *:cunabbrev*
|
|
|
950 :cuna[bbrev] {lhs} same as ":una", but for Command-line mode only. {not
|
|
|
951 in Vi}
|
|
|
952
|
|
|
953 *:cnorea* *:cnoreabbrev*
|
|
838
|
954 :cnorea[bbrev] [<expr>] [lhs] [rhs]
|
|
7
|
955 same as ":ab", but for Command-line mode only and no
|
|
|
956 remapping for this {rhs} {not in Vi}
|
|
|
957
|
|
|
958 *:ia* *:iabbrev*
|
|
838
|
959 :ia[bbrev] [<expr>] [lhs] [rhs]
|
|
|
960 same as ":ab", but for Insert mode only. {not in Vi}
|
|
7
|
961
|
|
|
962 *:iuna* *:iunabbrev*
|
|
|
963 :iuna[bbrev] {lhs} same as ":una", but for insert mode only. {not in
|
|
|
964 Vi}
|
|
|
965
|
|
|
966 *:inorea* *:inoreabbrev*
|
|
838
|
967 :inorea[bbrev] [<expr>] [lhs] [rhs]
|
|
7
|
968 same as ":ab", but for Insert mode only and no
|
|
|
969 remapping for this {rhs} {not in Vi}
|
|
|
970
|
|
|
971 *:abc* *:abclear*
|
|
|
972 :abc[lear] Remove all abbreviations. {not in Vi}
|
|
|
973
|
|
|
974 *:iabc* *:iabclear*
|
|
|
975 :iabc[lear] Remove all abbreviations for Insert mode. {not in Vi}
|
|
|
976
|
|
|
977 *:cabc* *:cabclear*
|
|
|
978 :cabc[lear] Remove all abbreviations for Command-line mode. {not
|
|
|
979 in Vi}
|
|
|
980
|
|
|
981 *using_CTRL-V*
|
|
|
982 It is possible to use special characters in the rhs of an abbreviation.
|
|
|
983 CTRL-V has to be used to avoid the special meaning of most non printable
|
|
|
984 characters. How many CTRL-Vs need to be typed depends on how you enter the
|
|
|
985 abbreviation. This also applies to mappings. Let's use an example here.
|
|
|
986
|
|
|
987 Suppose you want to abbreviate "esc" to enter an <Esc> character. When you
|
|
|
988 type the ":ab" command in Vim, you have to enter this: (here ^V is a CTRL-V
|
|
|
989 and ^[ is <Esc>)
|
|
|
990
|
|
|
991 You type: ab esc ^V^V^V^V^V^[
|
|
|
992
|
|
|
993 All keyboard input is subjected to ^V quote interpretation, so
|
|
|
994 the first, third, and fifth ^V characters simply allow the second,
|
|
|
995 and fourth ^Vs, and the ^[, to be entered into the command-line.
|
|
|
996
|
|
|
997 You see: ab esc ^V^V^[
|
|
|
998
|
|
|
999 The command-line contains two actual ^Vs before the ^[. This is
|
|
|
1000 how it should appear in your .exrc file, if you choose to go that
|
|
|
1001 route. The first ^V is there to quote the second ^V; the :ab
|
|
|
1002 command uses ^V as its own quote character, so you can include quoted
|
|
42
|
1003 whitespace or the | character in the abbreviation. The :ab command
|
|
7
|
1004 doesn't do anything special with the ^[ character, so it doesn't need
|
|
|
1005 to be quoted. (Although quoting isn't harmful; that's why typing 7
|
|
|
1006 [but not 8!] ^Vs works.)
|
|
|
1007
|
|
|
1008 Stored as: esc ^V^[
|
|
|
1009
|
|
|
1010 After parsing, the abbreviation's short form ("esc") and long form
|
|
|
1011 (the two characters "^V^[") are stored in the abbreviation table.
|
|
|
1012 If you give the :ab command with no arguments, this is how the
|
|
|
1013 abbreviation will be displayed.
|
|
|
1014
|
|
|
1015 Later, when the abbreviation is expanded because the user typed in
|
|
|
1016 the word "esc", the long form is subjected to the same type of
|
|
|
1017 ^V interpretation as keyboard input. So the ^V protects the ^[
|
|
42
|
1018 character from being interpreted as the "exit Insert mode" character.
|
|
7
|
1019 Instead, the ^[ is inserted into the text.
|
|
|
1020
|
|
|
1021 Expands to: ^[
|
|
|
1022
|
|
|
1023 [example given by Steve Kirkendall]
|
|
|
1024
|
|
|
1025 ==============================================================================
|
|
|
1026 3. Local mappings and functions *script-local*
|
|
|
1027
|
|
|
1028 When using several Vim script files, there is the danger that mappings and
|
|
|
1029 functions used in one script use the same name as in other scripts. To avoid
|
|
|
1030 this, they can be made local to the script.
|
|
|
1031
|
|
|
1032 *<SID>* *<SNR>* *E81*
|
|
|
1033 The string "<SID>" can be used in a mapping or menu. This requires that the
|
|
|
1034 '<' flag is not present in 'cpoptions'.
|
|
|
1035 When executing the map command, Vim will replace "<SID>" with the special
|
|
|
1036 key code <SNR>, followed by a number that's unique for the script, and an
|
|
|
1037 underscore. Example: >
|
|
|
1038 :map <SID>Add
|
|
|
1039 could define a mapping "<SNR>23_Add".
|
|
|
1040
|
|
|
1041 When defining a function in a script, "s:" can be prepended to the name to
|
|
|
1042 make it local to the script. But when a mapping is executed from outside of
|
|
|
1043 the script, it doesn't know in which script the function was defined. To
|
|
|
1044 avoid this problem, use "<SID>" instead of "s:". The same translation is done
|
|
|
1045 as for mappings. This makes it possible to define a call to the function in
|
|
42
|
1046 a mapping.
|
|
7
|
1047
|
|
|
1048 When a local function is executed, it runs in the context of the script it was
|
|
|
1049 defined in. This means that new functions and mappings it defines can also
|
|
|
1050 use "s:" or "<SID>" and it will use the same unique number as when the
|
|
|
1051 function itself was defined. Also, the "s:var" local script variables can be
|
|
|
1052 used.
|
|
|
1053
|
|
|
1054 When executing an autocommand or a user command, it will run in the context of
|
|
|
1055 the script it was defined in. This makes it possible that the command calls a
|
|
|
1056 local function or uses a local mapping.
|
|
|
1057
|
|
|
1058 Otherwise, using "<SID>" outside of a script context is an error.
|
|
|
1059
|
|
|
1060 If you need to get the script number to use in a complicated script, you can
|
|
625
|
1061 use this function: >
|
|
|
1062 function s:SID()
|
|
|
1063 return matchstr(expand('<sfile>'), '<SNR>\zs\d\+\ze_SID$')
|
|
|
1064 endfun
|
|
7
|
1065
|
|
|
1066 The "<SNR>" will be shown when listing functions and mappings. This is useful
|
|
|
1067 to find out what they are defined to.
|
|
|
1068
|
|
|
1069 The |:scriptnames| command can be used to see which scripts have been sourced
|
|
|
1070 and what their <SNR> number is.
|
|
|
1071
|
|
|
1072 This is all {not in Vi} and {not available when compiled without the +eval
|
|
|
1073 feature}.
|
|
|
1074
|
|
|
1075 ==============================================================================
|
|
|
1076 4. User-defined commands *user-commands*
|
|
|
1077
|
|
236
|
1078 It is possible to define your own Ex commands. A user-defined command can act
|
|
7
|
1079 just like a built-in command (it can have a range or arguments, arguments can
|
|
|
1080 be completed as filenames or buffer names, etc), except that when the command
|
|
|
1081 is executed, it is transformed into a normal ex command and then executed.
|
|
|
1082
|
|
|
1083 For starters: See section |40.2| in the user manual.
|
|
|
1084
|
|
|
1085 *E183* *user-cmd-ambiguous*
|
|
|
1086 All user defined commands must start with an uppercase letter, to avoid
|
|
236
|
1087 confusion with builtin commands. (There are a few builtin commands, notably
|
|
7
|
1088 :Next, :Print and :X, which do start with an uppercase letter. The builtin
|
|
|
1089 will always take precedence in these cases). The other characters of the user
|
|
|
1090 command can be uppercase letters, lowercase letters or digits. When using
|
|
|
1091 digits, note that other commands that take a numeric argument may become
|
|
|
1092 ambiguous. For example, the command ":Cc2" could be the user command ":Cc2"
|
|
|
1093 without an argument, or the command ":Cc" with argument "2". It is advised to
|
|
|
1094 put a space between the command name and the argument to avoid these problems.
|
|
|
1095
|
|
236
|
1096 When using a user-defined command, the command can be abbreviated. However, if
|
|
|
1097 an abbreviation is not unique, an error will be issued. Furthermore, a
|
|
7
|
1098 built-in command will always take precedence.
|
|
|
1099
|
|
|
1100 Example: >
|
|
|
1101 :command Rename ...
|
|
|
1102 :command Renumber ...
|
|
|
1103 :Rena " Means "Rename"
|
|
|
1104 :Renu " Means "Renumber"
|
|
|
1105 :Ren " Error - ambiguous
|
|
|
1106 :command Paste ...
|
|
|
1107 :P " The built-in :Print
|
|
|
1108
|
|
|
1109 It is recommended that full names for user-defined commands are used in
|
|
|
1110 scripts.
|
|
|
1111
|
|
|
1112 :com[mand] *:com* *:command*
|
|
236
|
1113 List all user-defined commands. When listing commands,
|
|
7
|
1114 the characters in the first two columns are
|
|
|
1115 ! Command has the -bang attribute
|
|
|
1116 " Command has the -register attribute
|
|
|
1117 b Command is local to current buffer
|
|
|
1118 (see below for details on attributes)
|
|
|
1119
|
|
|
1120 :com[mand] {cmd} List the user-defined commands that start with {cmd}
|
|
|
1121
|
|
482
|
1122 *:command-verbose*
|
|
|
1123 When 'verbose' is non-zero, listing a command will also display where it was
|
|
|
1124 last defined. Example: >
|
|
|
1125
|
|
|
1126 :verbose command TOhtml
|
|
856
|
1127 < Name Args Range Complete Definition ~
|
|
|
1128 TOhtml 0 % :call Convert2HTML(<line1>, <line2>) ~
|
|
|
1129 Last set from /usr/share/vim/vim-7.0/plugin/tohtml.vim ~
|
|
|
1130
|
|
483
|
1131 See |:verbose-cmd| for more information.
|
|
482
|
1132
|
|
7
|
1133 *E174* *E182*
|
|
|
1134 :com[mand][!] [{attr}...] {cmd} {rep}
|
|
|
1135 Define a user command. The name of the command is
|
|
236
|
1136 {cmd} and its replacement text is {rep}. The command's
|
|
|
1137 attributes (see below) are {attr}. If the command
|
|
7
|
1138 already exists, an error is reported, unless a ! is
|
|
|
1139 specified, in which case the command is redefined.
|
|
|
1140
|
|
|
1141 :delc[ommand] {cmd} *:delc* *:delcommand* *E184*
|
|
|
1142 Delete the user-defined command {cmd}.
|
|
|
1143
|
|
|
1144 :comc[lear] *:comc* *:comclear*
|
|
|
1145 Delete all user-defined commands.
|
|
|
1146
|
|
|
1147 Command attributes
|
|
|
1148
|
|
236
|
1149 User-defined commands are treated by Vim just like any other ex commands. They
|
|
|
1150 can have arguments, or have a range specified. Arguments are subject to
|
|
|
1151 completion as filenames, buffers, etc. Exactly how this works depends upon the
|
|
7
|
1152 command's attributes, which are specified when the command is defined.
|
|
|
1153
|
|
|
1154 There are a number of attributes, split into four categories: argument
|
|
236
|
1155 handling, completion behavior, range handling, and special cases. The
|
|
7
|
1156 attributes are described below, by category.
|
|
|
1157
|
|
1132
|
1158 Argument handling *E175* *E176* *:command-nargs*
|
|
7
|
1159
|
|
|
1160 By default, a user defined command will take no arguments (and an error is
|
|
236
|
1161 reported if any are supplied). However, it is possible to specify that the
|
|
|
1162 command can take arguments, using the -nargs attribute. Valid cases are:
|
|
7
|
1163
|
|
|
1164 -nargs=0 No arguments are allowed (the default)
|
|
|
1165 -nargs=1 Exactly one argument is required
|
|
|
1166 -nargs=* Any number of arguments are allowed (0, 1, or many)
|
|
|
1167 -nargs=? 0 or 1 arguments are allowed
|
|
|
1168 -nargs=+ Arguments must be supplied, but any number are allowed
|
|
|
1169
|
|
1236
|
1170 Arguments are considered to be separated by (unescaped) spaces or tabs in this
|
|
7
|
1171 context.
|
|
|
1172
|
|
|
1173 Note that arguments are used as text, not as expressions. Specifically,
|
|
|
1174 "s:var" will use the script-local variable in the script where the command was
|
|
|
1175 defined, not where it is invoked! Example:
|
|
|
1176 script1.vim: >
|
|
|
1177 :let s:error = "None"
|
|
|
1178 :command -nargs=1 Error echoerr <args>
|
|
|
1179 < script2.vim: >
|
|
|
1180 :source script1.vim
|
|
|
1181 :let s:error = "Wrong!"
|
|
|
1182 :Error s:error
|
|
1619
|
1183 Executing script2.vim will result in "None" being echoed. Not what you
|
|
7
|
1184 intended! Calling a function may be an alternative.
|
|
|
1185
|
|
1132
|
1186 Completion behavior *:command-completion* *E179*
|
|
|
1187 *E180* *E181* *:command-complete*
|
|
7
|
1188 By default, the arguments of user defined commands do not undergo completion.
|
|
|
1189 However, by specifying one or the other of the following attributes, argument
|
|
|
1190 completion can be enabled:
|
|
|
1191
|
|
|
1192 -complete=augroup autocmd groups
|
|
|
1193 -complete=buffer buffer names
|
|
|
1194 -complete=command Ex command (and arguments)
|
|
|
1195 -complete=dir directory names
|
|
|
1196 -complete=environment environment variable names
|
|
|
1197 -complete=event autocommand events
|
|
|
1198 -complete=expression Vim expression
|
|
|
1199 -complete=file file and directory names
|
|
714
|
1200 -complete=shellcmd Shell command
|
|
7
|
1201 -complete=function function name
|
|
|
1202 -complete=help help subjects
|
|
|
1203 -complete=highlight highlight groups
|
|
|
1204 -complete=mapping mapping name
|
|
|
1205 -complete=menu menus
|
|
|
1206 -complete=option options
|
|
|
1207 -complete=tag tags
|
|
|
1208 -complete=tag_listfiles tags, file names are shown when CTRL-D is hit
|
|
|
1209 -complete=var user variables
|
|
|
1210 -complete=custom,{func} custom completion, defined via {func}
|
|
406
|
1211 -complete=customlist,{func} custom completion, defined via {func}
|
|
7
|
1212
|
|
557
|
1213
|
|
|
1214 Custom completion *:command-completion-custom*
|
|
|
1215 *:command-completion-customlist*
|
|
|
1216 *E467* *E468*
|
|
7
|
1217 It is possible to define customized completion schemes via the "custom,{func}"
|
|
406
|
1218 or the "customlist,{func}" completion argument. The {func} part should be a
|
|
1619
|
1219 function with the following signature: >
|
|
7
|
1220
|
|
|
1221 :function {func}(ArgLead, CmdLine, CursorPos)
|
|
|
1222
|
|
406
|
1223 The function need not use all these arguments. The function should provide the
|
|
|
1224 completion candidates as the return value.
|
|
|
1225
|
|
|
1226 For the "custom" argument, the function should return the completion
|
|
|
1227 candidates one per line in a newline separated string.
|
|
|
1228
|
|
|
1229 For the "customlist" argument, the function should return the completion
|
|
557
|
1230 candidates as a Vim List. Non-string items in the list are ignored.
|
|
406
|
1231
|
|
|
1232 The function arguments are:
|
|
7
|
1233 ArgLead the leading portion of the argument currently being
|
|
|
1234 completed on
|
|
|
1235 CmdLine the entire command line
|
|
557
|
1236 CursorPos the cursor position in it (byte index)
|
|
406
|
1237 The function may use these for determining context. For the "custom"
|
|
|
1238 argument, it is not necessary to filter candidates against the (implicit
|
|
|
1239 pattern in) ArgLead. Vim will do filter the candidates with its regexp engine
|
|
|
1240 after function return, and this is probably more efficient in most cases. For
|
|
|
1241 the "customlist" argument, Vim will not filter the returned completion
|
|
|
1242 candidates and the user supplied function should filter the candidates.
|
|
7
|
1243
|
|
|
1244 The following example lists user names to a Finger command >
|
|
|
1245 :com -complete=custom,ListUsers -nargs=1 Finger !finger <args>
|
|
|
1246 :fun ListUsers(A,L,P)
|
|
|
1247 : return system("cut -d: -f1 /etc/passwd")
|
|
|
1248 :endfun
|
|
|
1249
|
|
406
|
1250 The following example completes filenames from the directories specified in
|
|
|
1251 the 'path' option: >
|
|
|
1252 :com -nargs=1 -bang -complete=customlist,EditFileComplete
|
|
|
1253 \ EditFile edit<bang> <args>
|
|
|
1254 :fun EditFileComplete(A,L,P)
|
|
434
|
1255 : return split(globpath(&path, a:ArgLead), "\n")
|
|
406
|
1256 :endfun
|
|
|
1257 <
|
|
557
|
1258
|
|
1132
|
1259 Range handling *E177* *E178* *:command-range*
|
|
|
1260 *:command-count*
|
|
236
|
1261 By default, user-defined commands do not accept a line number range. However,
|
|
7
|
1262 it is possible to specify that the command does take a range (the -range
|
|
|
1263 attribute), or that it takes an arbitrary count value, either in the line
|
|
|
1264 number position (-range=N, like the |:split| command) or as a "count"
|
|
1132
|
1265 argument (-count=N, like the |:Next| command). The count will then be
|
|
|
1266 available in the argument with |<count>|.
|
|
|
1267
|
|
|
1268 Possible attributes are:
|
|
7
|
1269
|
|
|
1270 -range Range allowed, default is current line
|
|
|
1271 -range=% Range allowed, default is whole file (1,$)
|
|
|
1272 -range=N A count (default N) which is specified in the line
|
|
|
1273 number position (like |:split|)
|
|
|
1274 -count=N A count (default N) which is specified either in the line
|
|
171
|
1275 number position, or as an initial argument (like |:Next|).
|
|
7
|
1276 Specifying -count (without a default) acts like -count=0
|
|
|
1277
|
|
|
1278 Note that -range=N and -count=N are mutually exclusive - only one should be
|
|
|
1279 specified.
|
|
|
1280
|
|
1132
|
1281 Special cases *:command-bang* *:command-bar*
|
|
|
1282 *:command-register* *:command-buffer*
|
|
7
|
1283 There are some special cases as well:
|
|
|
1284
|
|
|
1285 -bang The command can take a ! modifier (like :q or :w)
|
|
|
1286 -bar The command can be followed by a "|" and another command.
|
|
|
1287 A "|" inside the command argument is not allowed then.
|
|
|
1288 Also checks for a " to start a comment.
|
|
|
1289 -register The first argument to the command can be an optional
|
|
|
1290 register name (like :del, :put, :yank).
|
|
|
1291 -buffer The command will only be available in the current buffer.
|
|
|
1292
|
|
|
1293 In the cases of the -count and -register attributes, if the optional argument
|
|
|
1294 is supplied, it is removed from the argument list and is available to the
|
|
|
1295 replacement text separately.
|
|
|
1296
|
|
|
1297 Replacement text
|
|
|
1298
|
|
|
1299 The replacement text for a user defined command is scanned for special escape
|
|
236
|
1300 sequences, using <...> notation. Escape sequences are replaced with values
|
|
|
1301 from the entered command line, and all other text is copied unchanged. The
|
|
788
|
1302 resulting string is executed as an Ex command. To avoid the replacement use
|
|
|
1303 <lt> in plade of the initial <. Thus to include "<bang>" literally use
|
|
|
1304 "<lt>bang>".
|
|
7
|
1305
|
|
|
1306 The valid escape sequences are
|
|
|
1307
|
|
|
1308 *<line1>*
|
|
|
1309 <line1> The starting line of the command range.
|
|
|
1310 *<line2>*
|
|
|
1311 <line2> The final line of the command range.
|
|
|
1312 *<count>*
|
|
|
1313 <count> Any count supplied (as described for the '-range'
|
|
|
1314 and '-count' attributes).
|
|
|
1315 *<bang>*
|
|
|
1316 <bang> (See the '-bang' attribute) Expands to a ! if the
|
|
|
1317 command was executed with a ! modifier, otherwise
|
|
|
1318 expands to nothing.
|
|
|
1319 *<reg>* *<register>*
|
|
|
1320 <reg> (See the '-register' attribute) The optional register,
|
|
236
|
1321 if specified. Otherwise, expands to nothing. <register>
|
|
7
|
1322 is a synonym for this.
|
|
|
1323 *<args>*
|
|
|
1324 <args> The command arguments, exactly as supplied (but as
|
|
|
1325 noted above, any count or register can consume some
|
|
|
1326 of the arguments, which are then not part of <args>).
|
|
|
1327 <lt> A single '<' (Less-Than) character. This is needed if you
|
|
|
1328 want to get a literal copy of one of these escape sequences
|
|
|
1329 into the expansion - for example, to get <bang>, use
|
|
|
1330 <lt>bang>.
|
|
|
1331
|
|
|
1332 *<q-args>*
|
|
|
1333 If the first two characters of an escape sequence are "q-" (for example,
|
|
|
1334 <q-args>) then the value is quoted in such a way as to make it a valid value
|
|
|
1335 for use in an expression. This uses the argument as one single value.
|
|
300
|
1336 When there is no argument <q-args> is an empty string.
|
|
1088
|
1337 *<f-args>*
|
|
7
|
1338 To allow commands to pass their arguments on to a user-defined function, there
|
|
236
|
1339 is a special form <f-args> ("function args"). This splits the command
|
|
1236
|
1340 arguments at spaces and tabs, quotes each argument individually, and the
|
|
7
|
1341 <f-args> sequence is replaced by the comma-separated list of quoted arguments.
|
|
856
|
1342 See the Mycmd example below. If no arguments are given <f-args> is removed.
|
|
1088
|
1343 To embed whitespace into an argument of <f-args>, prepend a backslash.
|
|
|
1344 <f-args> replaces every pair of backslashes (\\) with one backslash. A
|
|
|
1345 backslash followed by a character other than white space or a backslash
|
|
|
1346 remains unmodified. Overview:
|
|
|
1347
|
|
|
1348 command <f-args> ~
|
|
|
1349 XX ab 'ab'
|
|
|
1350 XX a\b 'a\b'
|
|
|
1351 XX a\ b 'a b'
|
|
|
1352 XX a\ b 'a ', 'b'
|
|
|
1353 XX a\\b 'a\b'
|
|
|
1354 XX a\\ b 'a\', 'b'
|
|
|
1355 XX a\\\b 'a\\b'
|
|
|
1356 XX a\\\ b 'a\ b'
|
|
|
1357 XX a\\\\b 'a\\b'
|
|
|
1358 XX a\\\\ b 'a\\', 'b'
|
|
7
|
1359
|
|
|
1360 Examples >
|
|
|
1361
|
|
|
1362 " Delete everything after here to the end
|
|
|
1363 :com Ddel +,$d
|
|
|
1364
|
|
|
1365 " Rename the current buffer
|
|
|
1366 :com -nargs=1 -bang -complete=file Ren f <args>|w<bang>
|
|
|
1367
|
|
|
1368 " Replace a range with the contents of a file
|
|
|
1369 " (Enter this all as one line)
|
|
|
1370 :com -range -nargs=1 -complete=file
|
|
|
1371 Replace <line1>-pu_|<line1>,<line2>d|r <args>|<line1>d
|
|
|
1372
|
|
|
1373 " Count the number of lines in the range
|
|
42
|
1374 :com! -range -nargs=0 Lines echo <line2> - <line1> + 1 "lines"
|
|
7
|
1375
|
|
|
1376 " Call a user function (example of <f-args>)
|
|
|
1377 :com -nargs=* Mycmd call Myfunc(<f-args>)
|
|
|
1378
|
|
|
1379 When executed as: >
|
|
|
1380 :Mycmd arg1 arg2
|
|
|
1381 This will invoke: >
|
|
|
1382 :call Myfunc("arg1","arg2")
|
|
|
1383
|
|
|
1384 :" A more substantial example
|
|
|
1385 :function Allargs(command)
|
|
1619
|
1386 : let i = 0
|
|
|
1387 : while i < argc()
|
|
|
1388 : if filereadable(argv(i))
|
|
|
1389 : execute "e " . argv(i)
|
|
7
|
1390 : execute a:command
|
|
|
1391 : endif
|
|
|
1392 : let i = i + 1
|
|
|
1393 : endwhile
|
|
|
1394 :endfunction
|
|
|
1395 :command -nargs=+ -complete=command Allargs call Allargs(<q-args>)
|
|
|
1396
|
|
|
1397 The command Allargs takes any Vim command(s) as argument and executes it on all
|
|
|
1398 files in the argument list. Usage example (note use of the "e" flag to ignore
|
|
|
1399 errors and the "update" command to write modified buffers): >
|
|
|
1400 :Allargs %s/foo/bar/ge|update
|
|
|
1401 This will invoke: >
|
|
|
1402 :call Allargs("%s/foo/bar/ge|update")
|
|
|
1403 <
|
|
|
1404 When defining an user command in a script, it will be able to call functions
|
|
|
1405 local to the script and use mappings local to the script. When the user
|
|
|
1406 invokes the user command, it will run in the context of the script it was
|
|
|
1407 defined in. This matters if |<SID>| is used in a command.
|
|
|
1408
|
|
|
1409 vim:tw=78:ts=8:ft=help:norl:
|
