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