blob: 4d23f4a5dc1dc34238cf8a3d3044f0665ac17177 [file] [log] [blame]
Bram Moolenaar519cc552021-11-16 19:18:26 +00001*map.txt* For Vim version 8.2. Last change: 2021 Nov 15
Bram Moolenaar071d4272004-06-13 20:20:40 +00002
3
4 VIM REFERENCE MANUAL by Bram Moolenaar
5
6
7Key mapping, abbreviations and user-defined commands.
8
9This subject is introduced in sections |05.3|, |24.7| and |40.1| of the user
10manual.
11
121. Key mapping |key-mapping|
Bram Moolenaar5b962cf2005-12-12 21:58:40 +000013 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|
Bram Moolenaar4b570182019-10-20 19:53:22 +020023 1.11 Mapping in modifyOtherKeys mode |modifyOtherKeys|
24 1.12 Mapping an operator |:map-operator|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000252. Abbreviations |abbreviations|
263. Local mappings and functions |script-local|
274. User-defined commands |user-commands|
28
29==============================================================================
301. Key mapping *key-mapping* *mapping* *macro*
31
32Key mapping is used to change the meaning of typed keys. The most common use
Bram Moolenaar24a98a02017-09-27 22:23:55 +020033is to define a sequence of commands for a function key. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +000034
35 :map <F2> a<C-R>=strftime("%c")<CR><Esc>
36
Bram Moolenaar402d2fe2005-04-15 21:00:38 +000037This appends the current date and time after the cursor (in <> notation |<>|).
Bram Moolenaar071d4272004-06-13 20:20:40 +000038
Bram Moolenaar5b962cf2005-12-12 21:58:40 +000039
401.1 MAP COMMANDS *:map-commands*
41
Bram Moolenaar071d4272004-06-13 20:20:40 +000042There are commands to enter new mappings, remove mappings and list mappings.
43See |map-overview| for the various forms of "map" and their relationships with
44modes.
45
46{lhs} means left-hand-side *{lhs}*
47{rhs} means right-hand-side *{rhs}*
48
Bram Moolenaar06b5db92006-02-10 23:11:56 +000049:map {lhs} {rhs} |mapmode-nvo| *:map*
50:nm[ap] {lhs} {rhs} |mapmode-n| *:nm* *:nmap*
51:vm[ap] {lhs} {rhs} |mapmode-v| *:vm* *:vmap*
Bram Moolenaar371d5402006-03-20 21:47:49 +000052:xm[ap] {lhs} {rhs} |mapmode-x| *:xm* *:xmap*
Bram Moolenaar531da592013-05-06 05:58:55 +020053:smap {lhs} {rhs} |mapmode-s| *:smap*
Bram Moolenaar06b5db92006-02-10 23:11:56 +000054:om[ap] {lhs} {rhs} |mapmode-o| *:om* *:omap*
55:map! {lhs} {rhs} |mapmode-ic| *:map!*
56:im[ap] {lhs} {rhs} |mapmode-i| *:im* *:imap*
Bram Moolenaar61da1bf2019-06-06 12:14:49 +020057:lm[ap] {lhs} {rhs} |mapmode-l| *:lm* *:lma* *:lmap*
Bram Moolenaar06b5db92006-02-10 23:11:56 +000058:cm[ap] {lhs} {rhs} |mapmode-c| *:cm* *:cmap*
Bram Moolenaar37c64c72017-09-19 22:06:03 +020059:tma[p] {lhs} {rhs} |mapmode-t| *:tma* *:tmap*
Bram Moolenaar071d4272004-06-13 20:20:40 +000060 Map the key sequence {lhs} to {rhs} for the modes
61 where the map command applies. The result, including
62 {rhs}, is then further scanned for mappings. This
63 allows for nested and recursive use of mappings.
Bram Moolenaar519cc552021-11-16 19:18:26 +000064 Note: Trailing spaces are included in the {rhs},
65 because space is a valid Normal mode command.
Bram Moolenaar071d4272004-06-13 20:20:40 +000066
Bram Moolenaar822ff862014-06-12 21:46:14 +020067 *:nore* *:norem*
68:no[remap] {lhs} {rhs} |mapmode-nvo| *:no* *:noremap* *:nor*
69:nn[oremap] {lhs} {rhs} |mapmode-n| *:nn* *:nnoremap*
70:vn[oremap] {lhs} {rhs} |mapmode-v| *:vn* *:vnoremap*
71:xn[oremap] {lhs} {rhs} |mapmode-x| *:xn* *:xnoremap*
Bram Moolenaar61da1bf2019-06-06 12:14:49 +020072:snor[emap] {lhs} {rhs} |mapmode-s| *:snor* *:snore* *:snoremap*
Bram Moolenaar822ff862014-06-12 21:46:14 +020073:ono[remap] {lhs} {rhs} |mapmode-o| *:ono* *:onoremap*
74:no[remap]! {lhs} {rhs} |mapmode-ic| *:no!* *:noremap!*
Bram Moolenaar61da1bf2019-06-06 12:14:49 +020075:ino[remap] {lhs} {rhs} |mapmode-i| *:ino* *:inor* *:inoremap*
Bram Moolenaar822ff862014-06-12 21:46:14 +020076:ln[oremap] {lhs} {rhs} |mapmode-l| *:ln* *:lnoremap*
Bram Moolenaar61da1bf2019-06-06 12:14:49 +020077:cno[remap] {lhs} {rhs} |mapmode-c| *:cno* *:cnor* *:cnoremap*
Bram Moolenaar69fbc9e2017-09-14 20:37:57 +020078:tno[remap] {lhs} {rhs} |mapmode-t| *:tno* *:tnoremap*
Bram Moolenaar071d4272004-06-13 20:20:40 +000079 Map the key sequence {lhs} to {rhs} for the modes
80 where the map command applies. Disallow mapping of
81 {rhs}, to avoid nested and recursive mappings. Often
Bram Moolenaar25c9c682019-05-05 18:13:34 +020082 used to redefine a command.
Bram Moolenaar071d4272004-06-13 20:20:40 +000083
84
Bram Moolenaar06b5db92006-02-10 23:11:56 +000085:unm[ap] {lhs} |mapmode-nvo| *:unm* *:unmap*
86:nun[map] {lhs} |mapmode-n| *:nun* *:nunmap*
87:vu[nmap] {lhs} |mapmode-v| *:vu* *:vunmap*
Bram Moolenaar371d5402006-03-20 21:47:49 +000088:xu[nmap] {lhs} |mapmode-x| *:xu* *:xunmap*
89:sunm[ap] {lhs} |mapmode-s| *:sunm* *:sunmap*
Bram Moolenaar06b5db92006-02-10 23:11:56 +000090:ou[nmap] {lhs} |mapmode-o| *:ou* *:ounmap*
91:unm[ap]! {lhs} |mapmode-ic| *:unm!* *:unmap!*
92:iu[nmap] {lhs} |mapmode-i| *:iu* *:iunmap*
93:lu[nmap] {lhs} |mapmode-l| *:lu* *:lunmap*
Bram Moolenaar61da1bf2019-06-06 12:14:49 +020094:cu[nmap] {lhs} |mapmode-c| *:cu* *:cun* *:cunmap*
Bram Moolenaar37c64c72017-09-19 22:06:03 +020095:tunma[p] {lhs} |mapmode-t| *:tunma* *:tunmap*
Bram Moolenaar071d4272004-06-13 20:20:40 +000096 Remove the mapping of {lhs} for the modes where the
97 map command applies. The mapping may remain defined
98 for other modes where it applies.
99 Note: Trailing spaces are included in the {lhs}. This
100 unmap does NOT work: >
101 :map @@ foo
102 :unmap @@ | print
103
Bram Moolenaar06b5db92006-02-10 23:11:56 +0000104:mapc[lear] |mapmode-nvo| *:mapc* *:mapclear*
105:nmapc[lear] |mapmode-n| *:nmapc* *:nmapclear*
106:vmapc[lear] |mapmode-v| *:vmapc* *:vmapclear*
Bram Moolenaar371d5402006-03-20 21:47:49 +0000107:xmapc[lear] |mapmode-x| *:xmapc* *:xmapclear*
108:smapc[lear] |mapmode-s| *:smapc* *:smapclear*
Bram Moolenaar06b5db92006-02-10 23:11:56 +0000109:omapc[lear] |mapmode-o| *:omapc* *:omapclear*
110:mapc[lear]! |mapmode-ic| *:mapc!* *:mapclear!*
111:imapc[lear] |mapmode-i| *:imapc* *:imapclear*
112:lmapc[lear] |mapmode-l| *:lmapc* *:lmapclear*
113:cmapc[lear] |mapmode-c| *:cmapc* *:cmapclear*
Bram Moolenaar69fbc9e2017-09-14 20:37:57 +0200114:tmapc[lear] |mapmode-t| *:tmapc* *:tmapclear*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000115 Remove ALL mappings for the modes where the map
Bram Moolenaar25c9c682019-05-05 18:13:34 +0200116 command applies.
Bram Moolenaar251e1912011-06-19 05:09:16 +0200117 Use the <buffer> argument to remove buffer-local
118 mappings |:map-<buffer>|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000119 Warning: This also removes the default mappings.
120
Bram Moolenaar06b5db92006-02-10 23:11:56 +0000121:map |mapmode-nvo|
122:nm[ap] |mapmode-n|
123:vm[ap] |mapmode-v|
Bram Moolenaar371d5402006-03-20 21:47:49 +0000124:xm[ap] |mapmode-x|
125:sm[ap] |mapmode-s|
Bram Moolenaar06b5db92006-02-10 23:11:56 +0000126:om[ap] |mapmode-o|
127:map! |mapmode-ic|
128:im[ap] |mapmode-i|
129:lm[ap] |mapmode-l|
130:cm[ap] |mapmode-c|
Bram Moolenaar37c64c72017-09-19 22:06:03 +0200131:tma[p] |mapmode-t|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000132 List all key mappings for the modes where the map
133 command applies. Note that ":map" and ":map!" are
134 used most often, because they include the other modes.
135
Bram Moolenaar06b5db92006-02-10 23:11:56 +0000136:map {lhs} |mapmode-nvo| *:map_l*
137:nm[ap] {lhs} |mapmode-n| *:nmap_l*
138:vm[ap] {lhs} |mapmode-v| *:vmap_l*
Bram Moolenaar371d5402006-03-20 21:47:49 +0000139:xm[ap] {lhs} |mapmode-x| *:xmap_l*
140:sm[ap] {lhs} |mapmode-s| *:smap_l*
Bram Moolenaar06b5db92006-02-10 23:11:56 +0000141:om[ap] {lhs} |mapmode-o| *:omap_l*
142:map! {lhs} |mapmode-ic| *:map_l!*
143:im[ap] {lhs} |mapmode-i| *:imap_l*
144:lm[ap] {lhs} |mapmode-l| *:lmap_l*
145:cm[ap] {lhs} |mapmode-c| *:cmap_l*
Bram Moolenaar37c64c72017-09-19 22:06:03 +0200146:tma[p] {lhs} |mapmode-t| *:tmap_l*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000147 List the key mappings for the key sequences starting
148 with {lhs} in the modes where the map command applies.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000149
150These commands are used to map a key or key sequence to a string of
151characters. You can use this to put command sequences under function keys,
152translate one key into another, etc. See |:mkexrc| for how to save and
153restore the current mappings.
154
Bram Moolenaar5b962cf2005-12-12 21:58:40 +0000155 *map-ambiguous*
156When two mappings start with the same sequence of characters, they are
157ambiguous. Example: >
158 :imap aa foo
159 :imap aaa bar
160When Vim has read "aa", it will need to get another character to be able to
161decide if "aa" or "aaa" should be mapped. This means that after typing "aa"
162that mapping won't get expanded yet, Vim is waiting for another character.
163If you type a space, then "foo" will get inserted, plus the space. If you
164type "a", then "bar" will get inserted.
Bram Moolenaar5b962cf2005-12-12 21:58:40 +0000165
166
1671.2 SPECIAL ARGUMENTS *:map-arguments*
168
Bram Moolenaar72179e12013-06-29 13:58:31 +0200169"<buffer>", "<nowait>", "<silent>", "<special>", "<script>", "<expr>" and
170"<unique>" can be used in any order. They must appear right after the
171command, before any other arguments.
Bram Moolenaar4e427192006-03-10 21:34:27 +0000172
Bram Moolenaar071d4272004-06-13 20:20:40 +0000173 *:map-local* *:map-<buffer>* *E224* *E225*
Bram Moolenaarc236c162008-07-13 17:41:49 +0000174If the first argument to one of these commands is "<buffer>" the mapping will
175be effective in the current buffer only. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000176 :map <buffer> ,w /[.,;]<CR>
177Then you can map ",w" to something else in another buffer: >
178 :map <buffer> ,w /[#&!]<CR>
Bram Moolenaar72179e12013-06-29 13:58:31 +0200179The local buffer mappings are used before the global ones. See <nowait> below
180to make a short local mapping not taking effect when a longer global one
181exists.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000182The "<buffer>" argument can also be used to clear mappings: >
183 :unmap <buffer> ,w
184 :mapclear <buffer>
185Local mappings are also cleared when a buffer is deleted, but not when it is
186unloaded. Just like local option values.
Bram Moolenaarec7944a2013-06-12 21:29:15 +0200187Also see |map-precedence|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000188
Bram Moolenaar72179e12013-06-29 13:58:31 +0200189 *:map-<nowait>* *:map-nowait*
190When defining a buffer-local mapping for "," there may be a global mapping
191that starts with ",". Then you need to type another character for Vim to know
192whether to use the "," mapping or the longer one. To avoid this add the
193<nowait> argument. Then the mapping will be used when it matches, Vim does
194not wait for more characters to be typed. However, if the characters were
Bram Moolenaar6aa8cea2017-06-05 14:44:35 +0200195already typed they are used.
Bram Moolenaar207f0092020-08-30 17:20:20 +0200196Note that this works when the <nowait> mapping fully matches and is found
197before any partial matches. This works when:
198- There is only one matching buffer-local mapping, since these are always
199 found before global mappings.
Bram Moolenaar1c6737b2020-09-07 22:18:52 +0200200- There is another buffer-local mapping that partly matches, but it is
Bram Moolenaar207f0092020-08-30 17:20:20 +0200201 defined earlier (last defined mapping is found first).
Bram Moolenaar72179e12013-06-29 13:58:31 +0200202
Bram Moolenaar071d4272004-06-13 20:20:40 +0000203 *:map-<silent>* *:map-silent*
204To define a mapping which will not be echoed on the command line, add
205"<silent>" as the first argument. Example: >
206 :map <silent> ,h /Header<CR>
207The search string will not be echoed when using this mapping. Messages from
208the executed command are still given though. To shut them up too, add a
209":silent" in the executed command: >
210 :map <silent> ,h :exe ":silent normal /Header\r"<CR>
211Prompts will still be given, e.g., for inputdialog().
212Using "<silent>" for an abbreviation is possible, but will cause redrawing of
213the command line to fail.
214
Bram Moolenaar9c102382006-05-03 21:26:49 +0000215 *:map-<special>* *:map-special*
216Define a mapping with <> notation for special keys, even though the "<" flag
217may appear in 'cpoptions'. This is useful if the side effect of setting
218'cpoptions' is not desired. Example: >
219 :map <special> <F12> /Header<CR>
220<
Bram Moolenaar071d4272004-06-13 20:20:40 +0000221 *:map-<script>* *:map-script*
222If the first argument to one of these commands is "<script>" and it is used to
223define a new mapping or abbreviation, the mapping will only remap characters
224in the {rhs} using mappings that were defined local to a script, starting with
225"<SID>". This can be used to avoid that mappings from outside a script
226interfere (e.g., when CTRL-V is remapped in mswin.vim), but do use other
227mappings defined in the script.
228Note: ":map <script>" and ":noremap <script>" do the same thing. The
229"<script>" overrules the command name. Using ":noremap <script>" is
230preferred, because it's clearer that remapping is (mostly) disabled.
231
232 *:map-<unique>* *E226* *E227*
233If the first argument to one of these commands is "<unique>" and it is used to
234define a new mapping or abbreviation, the command will fail if the mapping or
235abbreviation already exists. Example: >
236 :map <unique> ,w /[#&!]<CR>
237When defining a local mapping, there will also be a check if a global map
238already exists which is equal.
239Example of what will fail: >
240 :map ,w /[#&!]<CR>
241 :map <buffer> <unique> ,w /[.,;]<CR>
Bram Moolenaara40ceaf2006-01-13 22:35:40 +0000242If you want to map a key and then have it do what it was originally mapped to,
243have a look at |maparg()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000244
Bram Moolenaar4e427192006-03-10 21:34:27 +0000245 *:map-<expr>* *:map-expression*
246If the first argument to one of these commands is "<expr>" and it is used to
247define a new mapping or abbreviation, the argument is an expression. The
248expression is evaluated to obtain the {rhs} that is used. Example: >
Bram Moolenaar4c295022021-05-02 17:19:11 +0200249 :inoremap <expr> . <SID>InsertDot()
250The result of the s:InsertDot() function will be inserted. It could check the
Bram Moolenaar4e427192006-03-10 21:34:27 +0000251text before the cursor and start omni completion when some condition is met.
Bram Moolenaar4c295022021-05-02 17:19:11 +0200252Using a script-local function is preferred, to avoid polluting the global
253namespace. Use <SID> in the RHS so that the script that the mapping was
254defined in can be found.
Bram Moolenaar4e427192006-03-10 21:34:27 +0000255
Bram Moolenaarda9591e2009-09-30 13:17:02 +0000256For abbreviations |v:char| is set to the character that was typed to trigger
257the abbreviation. You can use this to decide how to expand the {lhs}. You
Bram Moolenaar5302d9e2011-09-14 17:55:08 +0200258should not either insert or change the v:char.
Bram Moolenaarda9591e2009-09-30 13:17:02 +0000259
Bram Moolenaar4f4d51a2020-10-11 13:57:40 +0200260In case you want the mapping to not do anything, you can have the expression
261evaluate to an empty string. If something changed that requires Vim to
262go through the main loop (e.g. to update the display), return "\<Ignore>".
263This is similar to "nothing" but makes Vim return from the loop that waits for
264input. Example: >
265 func s:OpenPopup()
266 call popup_create(... arguments ...)
267 return "\<Ignore>"
268 endfunc
Bram Moolenaar4c295022021-05-02 17:19:11 +0200269 nnoremap <expr> <F3> <SID>OpenPopup()
Bram Moolenaar4f4d51a2020-10-11 13:57:40 +0200270
Bram Moolenaar18b7d862021-03-17 13:28:05 +0100271Also, keep in mind that the expression may be evaluated when looking for
272typeahead, before the previous command has been executed. For example: >
273 func StoreColumn()
274 let g:column = col('.')
275 return 'x'
276 endfunc
277 nnoremap <expr> x StoreColumn()
278 nmap ! f!x
Bram Moolenaardad44732021-03-31 20:07:33 +0200279You will notice that g:column has the value from before executing "f!",
280because "x" is evaluated before "f!" is executed.
Bram Moolenaar18b7d862021-03-17 13:28:05 +0100281This can be solved by inserting <Ignore> before the character that is
282expression-mapped: >
283 nmap ! f!<Ignore>x
284
Bram Moolenaar4e427192006-03-10 21:34:27 +0000285Be very careful about side effects! The expression is evaluated while
Bram Moolenaarc9b4b052006-04-30 18:54:39 +0000286obtaining characters, you may very well make the command dysfunctional.
287For this reason the following is blocked:
Bram Moolenaar5c5b0942007-05-06 12:07:59 +0000288- Changing the buffer text |textlock|.
289- Editing another buffer.
290- The |:normal| command.
291- Moving the cursor is allowed, but it is restored afterwards.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +0000292If you want the mapping to do any of these let the returned characters do
Bram Moolenaar957cf672020-11-12 14:21:06 +0100293that, or use a |<Cmd>| mapping instead.
Bram Moolenaar4e427192006-03-10 21:34:27 +0000294
Bram Moolenaar15146672011-10-20 22:22:38 +0200295You can use getchar(), it consumes typeahead if there is any. E.g., if you
296have these mappings: >
297 inoremap <expr> <C-L> nr2char(getchar())
298 inoremap <expr> <C-L>x "foo"
299If you now type CTRL-L nothing happens yet, Vim needs the next character to
300decide what mapping to use. If you type 'x' the second mapping is used and
Bram Moolenaarf1568ec2011-12-14 21:17:39 +0100301"foo" is inserted. If you type any other key the first mapping is used,
302getchar() gets the typed key and returns it.
Bram Moolenaar15146672011-10-20 22:22:38 +0200303
Bram Moolenaar4e427192006-03-10 21:34:27 +0000304Here is an example that inserts a list number that increases: >
305 let counter = 0
306 inoremap <expr> <C-L> ListItem()
307 inoremap <expr> <C-R> ListReset()
308
309 func ListItem()
310 let g:counter += 1
311 return g:counter . '. '
312 endfunc
313
314 func ListReset()
315 let g:counter = 0
316 return ''
317 endfunc
318
Bram Moolenaard9967712006-03-11 21:18:15 +0000319CTRL-L inserts the next number, CTRL-R resets the count. CTRL-R returns an
Bram Moolenaar4e427192006-03-10 21:34:27 +0000320empty string, so that nothing is inserted.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000321
Bram Moolenaar1c6737b2020-09-07 22:18:52 +0200322Note that using 0x80 as a single byte before other text does not work, it will
323be seen as a special key.
Bram Moolenaar8424a622006-04-19 21:23:36 +0000324
Bram Moolenaar957cf672020-11-12 14:21:06 +0100325 *<Cmd>* *:map-cmd*
326The special text <Cmd> begins a "command mapping", it executes the command
327directly without changing modes. Where you might use ":...<CR>" in the
328{rhs} of a mapping, you can instead use "<Cmd>...<CR>".
329Example: >
330 noremap x <Cmd>echo mode(1)<CR>
331<
332This is more flexible than `:<C-U>` in Visual and Operator-pending mode, or
333`<C-O>:` in Insert mode, because the commands are executed directly in the
334current mode, instead of always going to Normal mode. Visual mode is
335preserved, so tricks with |gv| are not needed. Commands can be invoked
336directly in Command-line mode (which would otherwise require timer hacks).
337Example of using <Cmd> halfway Insert mode: >
338 nnoremap <F3> aText <Cmd>echo mode(1)<CR> Added<Esc>
339
340Unlike <expr> mappings, there are no special restrictions on the <Cmd>
Bram Moolenaar4466ad62020-11-21 13:16:30 +0100341command: it is executed as if an (unrestricted) |autocommand| was invoked.
Bram Moolenaar957cf672020-11-12 14:21:06 +0100342
343Note:
344- Because <Cmd> avoids mode-changes it does not trigger |CmdlineEnter| and
345 |CmdlineLeave| events, because no user interaction is expected.
346- For the same reason, |keycodes| like <C-R><C-W> are interpreted as plain,
347 unmapped keys.
Bram Moolenaar4466ad62020-11-21 13:16:30 +0100348- The command is not echo'ed, no need for <silent>.
349- In Visual mode you can use `line('v')` and `col('v')` to get one end of the
350 Visual area, the cursor is at the other end.
Bram Moolenaar957cf672020-11-12 14:21:06 +0100351- In Select mode, |:map| and |:vmap| command mappings are executed in
352 Visual mode. Use |:smap| to handle Select mode differently.
353
354 *E1135* *E1136*
355<Cmd> commands must terminate, that is, they must be followed by <CR> in the
356{rhs} of the mapping definition. |Command-line| mode is never entered.
357
358 *E1137*
359<Cmd> commands can have only normal characters and cannot contain special
360characters like function keys.
361
Bram Moolenaar071d4272004-06-13 20:20:40 +0000362
Bram Moolenaar5b962cf2005-12-12 21:58:40 +00003631.3 MAPPING AND MODES *:map-modes*
Bram Moolenaara7241f52008-06-24 20:39:31 +0000364 *mapmode-nvo* *mapmode-n* *mapmode-v* *mapmode-o*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000365
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100366There are six sets of mappings
Bram Moolenaar071d4272004-06-13 20:20:40 +0000367- For Normal mode: When typing commands.
368- For Visual mode: When typing commands while the Visual area is highlighted.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100369- For Select mode: like Visual mode but typing text replaces the selection.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000370- For Operator-pending mode: When an operator is pending (after "d", "y", "c",
Bram Moolenaara7241f52008-06-24 20:39:31 +0000371 etc.). See below: |omap-info|.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000372- For Insert mode. These are also used in Replace mode.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000373- For Command-line mode: When entering a ":" or "/" command.
374
Bram Moolenaar071d4272004-06-13 20:20:40 +0000375Special case: While typing a count for a command in Normal mode, mapping zero
376is disabled. This makes it possible to map zero without making it impossible
377to type a count with a zero.
378
379 *map-overview* *map-modes*
Bram Moolenaare968e362014-05-13 20:23:24 +0200380Overview of which map command works in which mode. More details below.
381 COMMANDS MODES ~
382:map :noremap :unmap Normal, Visual, Select, Operator-pending
383:nmap :nnoremap :nunmap Normal
384:vmap :vnoremap :vunmap Visual and Select
385:smap :snoremap :sunmap Select
386:xmap :xnoremap :xunmap Visual
387:omap :onoremap :ounmap Operator-pending
388:map! :noremap! :unmap! Insert and Command-line
389:imap :inoremap :iunmap Insert
390:lmap :lnoremap :lunmap Insert, Command-line, Lang-Arg
391:cmap :cnoremap :cunmap Command-line
Bram Moolenaar69fbc9e2017-09-14 20:37:57 +0200392:tmap :tnoremap :tunmap Terminal-Job
Bram Moolenaar071d4272004-06-13 20:20:40 +0000393
Bram Moolenaar3ec32172021-05-16 12:39:47 +0200394Same information in a table:
395 *map-table*
396 Mode | Norm | Ins | Cmd | Vis | Sel | Opr | Term | Lang | ~
397Command +------+-----+-----+-----+-----+-----+------+------+ ~
398[nore]map | yes | - | - | yes | yes | yes | - | - |
399n[nore]map | yes | - | - | - | - | - | - | - |
400[nore]map! | - | yes | yes | - | - | - | - | - |
401i[nore]map | - | yes | - | - | - | - | - | - |
402c[nore]map | - | - | yes | - | - | - | - | - |
403v[nore]map | - | - | - | yes | yes | - | - | - |
404x[nore]map | - | - | - | yes | - | - | - | - |
405s[nore]map | - | - | - | - | yes | - | - | - |
406o[nore]map | - | - | - | - | - | yes | - | - |
407t[nore]map | - | - | - | - | - | - | yes | - |
408l[nore]map | - | yes | yes | - | - | - | - | yes |
409
Bram Moolenaare968e362014-05-13 20:23:24 +0200410
411 COMMANDS MODES ~
Bram Moolenaarc9b4b052006-04-30 18:54:39 +0000412 Normal Visual+Select Operator-pending ~
413:map :noremap :unmap :mapclear yes yes yes
414:nmap :nnoremap :nunmap :nmapclear yes - -
415:vmap :vnoremap :vunmap :vmapclear - yes -
416:omap :onoremap :ounmap :omapclear - - yes
Bram Moolenaar371d5402006-03-20 21:47:49 +0000417
Bram Moolenaar4c3f5362006-04-11 21:38:50 +0000418:nunmap can also be used outside of a monastery.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +0000419 *mapmode-x* *mapmode-s*
Bram Moolenaar371d5402006-03-20 21:47:49 +0000420Some commands work both in Visual and Select mode, some in only one. Note
421that quite often "Visual" is mentioned where both Visual and Select mode
422apply. |Select-mode-mapping|
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100423NOTE: Mapping a printable character in Select mode may confuse the user. It's
424better to explicitly use :xmap and :smap for printable characters. Or use
425:sunmap after defining the mapping.
Bram Moolenaar371d5402006-03-20 21:47:49 +0000426
Bram Moolenaare968e362014-05-13 20:23:24 +0200427 COMMANDS MODES ~
Bram Moolenaarc9b4b052006-04-30 18:54:39 +0000428 Visual Select ~
429:vmap :vnoremap :vunmap :vmapclear yes yes
430:xmap :xnoremap :xunmap :xmapclear yes -
431:smap :snoremap :sunmap :smapclear - yes
Bram Moolenaar071d4272004-06-13 20:20:40 +0000432
Bram Moolenaar06b5db92006-02-10 23:11:56 +0000433 *mapmode-ic* *mapmode-i* *mapmode-c* *mapmode-l*
Bram Moolenaar371d5402006-03-20 21:47:49 +0000434Some commands work both in Insert mode and Command-line mode, some not:
435
Bram Moolenaare968e362014-05-13 20:23:24 +0200436 COMMANDS MODES ~
Bram Moolenaar071d4272004-06-13 20:20:40 +0000437 Insert Command-line Lang-Arg ~
438:map! :noremap! :unmap! :mapclear! yes yes -
439:imap :inoremap :iunmap :imapclear yes - -
440:cmap :cnoremap :cunmap :cmapclear - yes -
441:lmap :lnoremap :lunmap :lmapclear yes* yes* yes*
442
Bram Moolenaar5ef1c6a2019-11-10 22:09:11 +0100443* If 'iminsert' is 1, see |language-mapping| below.
444
Bram Moolenaar071d4272004-06-13 20:20:40 +0000445The original Vi did not have separate mappings for
446Normal/Visual/Operator-pending mode and for Insert/Command-line mode.
447Therefore the ":map" and ":map!" commands enter and display mappings for
448several modes. In Vim you can use the ":nmap", ":vmap", ":omap", ":cmap" and
449":imap" commands to enter mappings for each mode separately.
450
Bram Moolenaar69fbc9e2017-09-14 20:37:57 +0200451 *mapmode-t*
452The terminal mappings are used in a terminal window, when typing keys for the
453job running in the terminal. See |terminal-typing|.
454
Bram Moolenaara7241f52008-06-24 20:39:31 +0000455 *omap-info*
456Operator-pending mappings can be used to define a movement command that can be
Bram Moolenaar95bafa22018-10-02 13:26:25 +0200457used with any operator. Simple example: >
458 :omap { w
459makes "y{" work like "yw" and "d{" like "dw".
Bram Moolenaara7241f52008-06-24 20:39:31 +0000460
461To ignore the starting cursor position and select different text, you can have
462the omap start Visual mode to select the text to be operated upon. Example
463that operates on a function name in the current line: >
464 onoremap <silent> F :<C-U>normal! 0f(hviw<CR>
465The CTRL-U (<C-U>) is used to remove the range that Vim may insert. The
466Normal mode commands find the first '(' character and select the first word
467before it. That usually is the function name.
468
Bram Moolenaar071d4272004-06-13 20:20:40 +0000469To enter a mapping for Normal and Visual mode, but not Operator-pending mode,
Bram Moolenaar95bafa22018-10-02 13:26:25 +0200470first define it for all three modes, then unmap it for
471Operator-pending mode: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000472 :map xx something-difficult
473 :ounmap xx
Bram Moolenaar95bafa22018-10-02 13:26:25 +0200474
Bram Moolenaar071d4272004-06-13 20:20:40 +0000475Likewise for a mapping for Visual and Operator-pending mode or Normal and
476Operator-pending mode.
477
478 *language-mapping*
479":lmap" defines a mapping that applies to:
480- Insert mode
481- Command-line mode
482- when entering a search pattern
483- the argument of the commands that accept a text character, such as "r" and
484 "f"
485- for the input() line
486Generally: Whenever a character is to be typed that is part of the text in the
487buffer, not a Vim command character. "Lang-Arg" isn't really another mode,
488it's just used here for this situation.
489 The simplest way to load a set of related language mappings is by using the
490'keymap' option. See |45.5|.
491 In Insert mode and in Command-line mode the mappings can be disabled with
Bram Moolenaar7cba6c02013-09-05 22:13:31 +0200492the CTRL-^ command |i_CTRL-^| |c_CTRL-^|. These commands change the value of
Bram Moolenaar3b1db362013-08-10 15:00:24 +0200493the 'iminsert' option. When starting to enter a normal command line (not a
494search pattern) the mappings are disabled until a CTRL-^ is typed. The state
495last used is remembered for Insert mode and Search patterns separately. The
496state for Insert mode is also used when typing a character as an argument to
497command like "f" or "t".
Bram Moolenaar071d4272004-06-13 20:20:40 +0000498 Language mappings will never be applied to already mapped characters. They
499are only used for typed characters. This assumes that the language mapping
500was already done when typing the mapping.
501
Bram Moolenaar071d4272004-06-13 20:20:40 +0000502
Bram Moolenaar5b962cf2005-12-12 21:58:40 +00005031.4 LISTING MAPPINGS *map-listing*
504
Bram Moolenaar071d4272004-06-13 20:20:40 +0000505When listing mappings the characters in the first two columns are:
506
507 CHAR MODE ~
Bram Moolenaar5c5b0942007-05-06 12:07:59 +0000508 <Space> Normal, Visual, Select and Operator-pending
Bram Moolenaar071d4272004-06-13 20:20:40 +0000509 n Normal
Bram Moolenaar5c5b0942007-05-06 12:07:59 +0000510 v Visual and Select
511 s Select
512 x Visual
Bram Moolenaar071d4272004-06-13 20:20:40 +0000513 o Operator-pending
514 ! Insert and Command-line
515 i Insert
516 l ":lmap" mappings for Insert, Command-line and Lang-Arg
517 c Command-line
Bram Moolenaar63c4e8a2017-09-17 20:32:20 +0200518 t Terminal-Job
Bram Moolenaar071d4272004-06-13 20:20:40 +0000519
520Just before the {rhs} a special character can appear:
521 * indicates that it is not remappable
522 & indicates that only script-local mappings are remappable
523 @ indicates a buffer-local mapping
524
525Everything from the first non-blank after {lhs} up to the end of the line
526(or '|') is considered to be part of {rhs}. This allows the {rhs} to end
527with a space.
528
529Note: When using mappings for Visual mode, you can use the "'<" mark, which
530is the start of the last selected Visual area in the current buffer |'<|.
531
Bram Moolenaar818078d2016-08-27 21:58:42 +0200532The |:filter| command can be used to select what mappings to list. The
533pattern is matched against the {lhs} and {rhs} in the raw form.
534
Bram Moolenaarae5bce12005-08-15 21:41:48 +0000535 *:map-verbose*
536When 'verbose' is non-zero, listing a key map will also display where it was
537last defined. Example: >
538
539 :verbose map <C-W>*
540 n <C-W>* * <C-W><C-S>*
Bram Moolenaarc9b4b052006-04-30 18:54:39 +0000541 Last set from /home/abcd/.vimrc
Bram Moolenaarae5bce12005-08-15 21:41:48 +0000542
Bram Moolenaar5195e452005-08-19 20:32:47 +0000543See |:verbose-cmd| for more information.
Bram Moolenaarae5bce12005-08-15 21:41:48 +0000544
Bram Moolenaar5b962cf2005-12-12 21:58:40 +0000545
5461.5 MAPPING SPECIAL KEYS *:map-special-keys*
547
548There are three ways to map a special key:
5491. The Vi-compatible method: Map the key code. Often this is a sequence that
550 starts with <Esc>. To enter a mapping like this you type ":map " and then
551 you have to type CTRL-V before hitting the function key. Note that when
552 the key code for the key is in the termcap (the t_ options), it will
553 automatically be translated into the internal code and become the second
554 way of mapping (unless the 'k' flag is included in 'cpoptions').
5552. The second method is to use the internal code for the function key. To
556 enter such a mapping type CTRL-K and then hit the function key, or use
557 the form "#1", "#2", .. "#9", "#0", "<Up>", "<S-Down>", "<S-F7>", etc.
558 (see table of keys |key-notation|, all keys from <Up> can be used). The
559 first ten function keys can be defined in two ways: Just the number, like
560 "#2", and with "<F>", like "<F2>". Both stand for function key 2. "#0"
561 refers to function key 10, defined with option 't_f10', which may be
562 function key zero on some keyboards. The <> form cannot be used when
563 'cpoptions' includes the '<' flag.
5643. Use the termcap entry, with the form <t_xx>, where "xx" is the name of the
565 termcap entry. Any string entry can be used. For example: >
566 :map <t_F3> G
567< Maps function key 13 to "G". This does not work if 'cpoptions' includes
568 the '<' flag.
569
570The advantage of the second and third method is that the mapping will work on
571different terminals without modification (the function key will be
572translated into the same internal code or the actual key code, no matter what
573terminal you are using. The termcap must be correct for this to work, and you
574must use the same mappings).
575
576DETAIL: Vim first checks if a sequence from the keyboard is mapped. If it
577isn't the terminal key codes are tried (see |terminal-options|). If a
578terminal code is found it is replaced with the internal code. Then the check
579for a mapping is done again (so you can map an internal code to something
580else). What is written into the script file depends on what is recognized.
581If the terminal key code was recognized as a mapping the key code itself is
582written to the script file. If it was recognized as a terminal code the
583internal code is written to the script file.
584
585
5861.6 SPECIAL CHARACTERS *:map-special-chars*
Bram Moolenaar345efa02016-01-15 20:57:49 +0100587 *map_backslash* *map-backslash*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000588Note that only CTRL-V is mentioned here as a special character for mappings
589and abbreviations. When 'cpoptions' does not contain 'B', a backslash can
590also be used like CTRL-V. The <> notation can be fully used then |<>|. But
591you cannot use "<C-V>" like CTRL-V to escape the special meaning of what
592follows.
593
594To map a backslash, or use a backslash literally in the {rhs}, the special
595sequence "<Bslash>" can be used. This avoids the need to double backslashes
596when using nested mappings.
597
Bram Moolenaar345efa02016-01-15 20:57:49 +0100598 *map_CTRL-C* *map-CTRL-C*
Bram Moolenaar1e015462005-09-25 22:16:38 +0000599Using CTRL-C in the {lhs} is possible, but it will only work when Vim is
600waiting for a key, not when Vim is busy with something. When Vim is busy
601CTRL-C interrupts/breaks the command.
602When using the GUI version on MS-Windows CTRL-C can be mapped to allow a Copy
603command to the clipboard. Use CTRL-Break to interrupt Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000604
Bram Moolenaar345efa02016-01-15 20:57:49 +0100605 *map_space_in_lhs* *map-space_in_lhs*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000606To include a space in {lhs} precede it with a CTRL-V (type two CTRL-Vs for
607each space).
Bram Moolenaar345efa02016-01-15 20:57:49 +0100608 *map_space_in_rhs* *map-space_in_rhs*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000609If you want a {rhs} that starts with a space, use "<Space>". To be fully Vi
610compatible (but unreadable) don't use the |<>| notation, precede {rhs} with a
611single CTRL-V (you have to type CTRL-V two times).
Bram Moolenaar345efa02016-01-15 20:57:49 +0100612 *map_empty_rhs* *map-empty-rhs*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000613You can create an empty {rhs} by typing nothing after a single CTRL-V (you
614have to type CTRL-V two times). Unfortunately, you cannot do this in a vimrc
615file.
616 *<Nop>*
Bram Moolenaar446beb42011-05-10 17:18:44 +0200617An easier way to get a mapping that doesn't produce anything, is to use
618"<Nop>" for the {rhs}. This only works when the |<>| notation is enabled.
619For example, to make sure that function key 8 does nothing at all: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000620 :map <F8> <Nop>
621 :map! <F8> <Nop>
622<
Bram Moolenaar5b962cf2005-12-12 21:58:40 +0000623 *map-multibyte*
624It is possible to map multibyte characters, but only the whole character. You
625cannot map the first byte only. This was done to prevent problems in this
626scenario: >
627 :set encoding=latin1
628 :imap <M-C> foo
629 :set encoding=utf-8
630The mapping for <M-C> is defined with the latin1 encoding, resulting in a 0xc3
Bram Moolenaar85eee132018-05-06 17:57:30 +0200631byte. If you type the character á (0xe1 <M-a>) in UTF-8 encoding this is the
Bram Moolenaar446beb42011-05-10 17:18:44 +0200632two bytes 0xc3 0xa1. You don't want the 0xc3 byte to be mapped then or
Bram Moolenaar85eee132018-05-06 17:57:30 +0200633otherwise it would be impossible to type the á character.
Bram Moolenaar5b962cf2005-12-12 21:58:40 +0000634
Bram Moolenaar071d4272004-06-13 20:20:40 +0000635 *<Leader>* *mapleader*
636To define a mapping which uses the "mapleader" variable, the special string
637"<Leader>" can be used. It is replaced with the string value of "mapleader".
638If "mapleader" is not set or empty, a backslash is used instead. Example: >
639 :map <Leader>A oanother line<Esc>
640Works like: >
641 :map \A oanother line<Esc>
642But after: >
643 :let mapleader = ","
644It works like: >
645 :map ,A oanother line<Esc>
646
647Note that the value of "mapleader" is used at the moment the mapping is
648defined. Changing "mapleader" after that has no effect for already defined
649mappings.
650
651 *<LocalLeader>* *maplocalleader*
Bram Moolenaara7241f52008-06-24 20:39:31 +0000652<LocalLeader> is just like <Leader>, except that it uses "maplocalleader"
653instead of "mapleader". <LocalLeader> is to be used for mappings which are
654local to a buffer. Example: >
Bram Moolenaarb8ff1fb2012-02-04 21:59:01 +0100655 :map <buffer> <LocalLeader>A oanother line<Esc>
Bram Moolenaar071d4272004-06-13 20:20:40 +0000656<
657In a global plugin <Leader> should be used and in a filetype plugin
658<LocalLeader>. "mapleader" and "maplocalleader" can be equal. Although, if
659you make them different, there is a smaller chance of mappings from global
660plugins to clash with mappings for filetype plugins. For example, you could
661keep "mapleader" at the default backslash, and set "maplocalleader" to an
662underscore.
663
664 *map-<SID>*
665In a script the special key name "<SID>" can be used to define a mapping
666that's local to the script. See |<SID>| for details.
667
668 *<Plug>*
669The special key name "<Plug>" can be used for an internal mapping, which is
670not to be matched with any key sequence. This is useful in plugins
671|using-<Plug>|.
672
673 *<Char>* *<Char->*
674To map a character by its decimal, octal or hexadecimal number the <Char>
675construct can be used:
676 <Char-123> character 123
677 <Char-033> character 27
678 <Char-0x7f> character 127
Bram Moolenaar5302d9e2011-09-14 17:55:08 +0200679 <S-Char-114> character 114 ('r') shifted ('R')
Bram Moolenaar207f0092020-08-30 17:20:20 +0200680This is useful to specify a (multibyte) character in a 'keymap' file.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000681Upper and lowercase differences are ignored.
682
683 *map-comments*
684It is not possible to put a comment after these commands, because the '"'
Bram Moolenaar036986f2017-03-16 17:41:02 +0100685character is considered to be part of the {lhs} or {rhs}. However, one can
686use |", since this starts a new, empty command with a comment.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000687
Bram Moolenaar345efa02016-01-15 20:57:49 +0100688 *map_bar* *map-bar*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000689Since the '|' character is used to separate a map command from the next
690command, you will have to do something special to include a '|' in {rhs}.
691There are three methods:
692 use works when example ~
693 <Bar> '<' is not in 'cpoptions' :map _l :!ls <Bar> more^M
694 \| 'b' is not in 'cpoptions' :map _l :!ls \| more^M
695 ^V| always, in Vim and Vi :map _l :!ls ^V| more^M
696
697(here ^V stands for CTRL-V; to get one CTRL-V you have to type it twice; you
698cannot use the <> notation "<C-V>" here).
699
700All three work when you use the default setting for 'cpoptions'.
701
702When 'b' is present in 'cpoptions', "\|" will be recognized as a mapping
703ending in a '\' and then another command. This is Vi compatible, but
704illogical when compared to other commands.
705
Bram Moolenaar345efa02016-01-15 20:57:49 +0100706 *map_return* *map-return*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000707When you have a mapping that contains an Ex command, you need to put a line
708terminator after it to have it executed. The use of <CR> is recommended for
709this (see |<>|). Example: >
Bram Moolenaar251835e2014-02-24 02:51:51 +0100710 :map _ls :!ls -l %:S<CR>:echo "the end"<CR>
Bram Moolenaar071d4272004-06-13 20:20:40 +0000711
712To avoid mapping of the characters you type in insert or Command-line mode,
713type a CTRL-V first. The mapping in Insert mode is disabled if the 'paste'
714option is on.
Bram Moolenaare2db6952013-07-24 19:53:36 +0200715 *map-error*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000716Note that when an error is encountered (that causes an error message or beep)
717the rest of the mapping is not executed. This is Vi-compatible.
718
719Note that the second character (argument) of the commands @zZtTfF[]rm'`"v
720and CTRL-X is not mapped. This was done to be able to use all the named
721registers and marks, even when the command with the same name has been
722mapped.
723
Bram Moolenaar5b962cf2005-12-12 21:58:40 +0000724
7251.7 WHAT KEYS TO MAP *map-which-keys*
726
Bram Moolenaar071d4272004-06-13 20:20:40 +0000727If you are going to map something, you will need to choose which key(s) to use
728for the {lhs}. You will have to avoid keys that are used for Vim commands,
729otherwise you would not be able to use those commands anymore. Here are a few
730suggestions:
731- Function keys <F2>, <F3>, etc.. Also the shifted function keys <S-F1>,
732 <S-F2>, etc. Note that <F1> is already used for the help command.
Bram Moolenaarf91787c2010-07-17 12:47:16 +0200733- Meta-keys (with the ALT key pressed). Depending on your keyboard accented
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100734 characters may be used as well. |:map-alt-keys|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000735- Use the '_' or ',' character and then any other character. The "_" and ","
736 commands do exist in Vim (see |_| and |,|), but you probably never use them.
737- Use a key that is a synonym for another command. For example: CTRL-P and
738 CTRL-N. Use an extra character to allow more mappings.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100739- The key defined by <Leader> and one or more other keys. This is especially
740 useful in scripts. |mapleader|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000741
742See the file "index" for keys that are not used and thus can be mapped without
743losing any builtin function. You can also use ":help {key}^D" to find out if
744a key is used for some command. ({key} is the specific key you want to find
745out about, ^D is CTRL-D).
746
Bram Moolenaar5b962cf2005-12-12 21:58:40 +0000747
7481.8 EXAMPLES *map-examples*
749
Bram Moolenaar071d4272004-06-13 20:20:40 +0000750A few examples (given as you type them, for "<CR>" you type four characters;
751the '<' flag must not be present in 'cpoptions' for this to work). >
752
753 :map <F3> o#include
754 :map <M-g> /foo<CR>cwbar<Esc>
755 :map _x d/END/e<CR>
756 :map! qq quadrillion questions
Bram Moolenaar5c5b0942007-05-06 12:07:59 +0000757
758
759Multiplying a count
760
761When you type a count before triggering a mapping, it's like the count was
762typed before the {lhs}. For example, with this mapping: >
763 :map <F4> 3w
764Typing 2<F4> will result in "23w". Thus not moving 2 * 3 words but 23 words.
765If you want to multiply counts use the expression register: >
766 :map <F4> @='3w'<CR>
767The part between quotes is the expression being executed. |@=|
768
Bram Moolenaar5b962cf2005-12-12 21:58:40 +0000769
7701.9 USING MAPPINGS *map-typing*
771
Bram Moolenaar071d4272004-06-13 20:20:40 +0000772Vim will compare what you type with the start of a mapped sequence. If there
773is an incomplete match, it will get more characters until there either is a
774complete match or until there is no match at all. Example: If you map! "qq",
775the first 'q' will not appear on the screen until you type another
776character. This is because Vim cannot know if the next character will be a
777'q' or not. If the 'timeout' option is on (which is the default) Vim will
778only wait for one second (or as long as specified with the 'timeoutlen'
779option). After that it assumes that the 'q' is to be interpreted as such. If
780you type slowly, or your system is slow, reset the 'timeout' option. Then you
781might want to set the 'ttimeout' option.
782
Bram Moolenaar37c64c72017-09-19 22:06:03 +0200783 *map-precedence*
Bram Moolenaarec7944a2013-06-12 21:29:15 +0200784Buffer-local mappings (defined using |:map-<buffer>|) take precedence over
785global mappings. When a buffer-local mapping is the same as a global mapping,
786Vim will use the buffer-local mapping. In addition, Vim will use a complete
Bram Moolenaar14b69452013-06-29 23:05:20 +0200787mapping immediately if it was defined with <nowait>, even if a longer mapping
788has the same prefix. For example, given the following two mappings: >
789 :map <buffer> <nowait> \a :echo "Local \a"<CR>
790 :map \abc :echo "Global \abc"<CR>
791When typing \a the buffer-local mapping will be used immediately. Vim will
792not wait for more characters to see if the user might be typing \abc.
Bram Moolenaarec7944a2013-06-12 21:29:15 +0200793
Bram Moolenaar071d4272004-06-13 20:20:40 +0000794 *map-keys-fails*
Bram Moolenaarcdbac1e2005-12-11 21:27:22 +0000795There are situations where key codes might not be recognized:
Bram Moolenaar071d4272004-06-13 20:20:40 +0000796- Vim can only read part of the key code. Mostly this is only the first
797 character. This happens on some Unix versions in an xterm.
798- The key code is after character(s) that are mapped. E.g., "<F1><F1>" or
799 "g<F1>".
Bram Moolenaarcdbac1e2005-12-11 21:27:22 +0000800
Bram Moolenaar071d4272004-06-13 20:20:40 +0000801The result is that the key code is not recognized in this situation, and the
Bram Moolenaarcdbac1e2005-12-11 21:27:22 +0000802mapping fails. There are two actions needed to avoid this problem:
803
Bram Moolenaar071d4272004-06-13 20:20:40 +0000804- Remove the 'K' flag from 'cpoptions'. This will make Vim wait for the rest
805 of the characters of the function key.
806- When using <F1> to <F4> the actual key code generated may correspond to
807 <xF1> to <xF4>. There are mappings from <xF1> to <F1>, <xF2> to <F2>, etc.,
808 but these are not recognized after another half a mapping. Make sure the
809 key codes for <F1> to <F4> are correct: >
810 :set <F1>=<type CTRL-V><type F1>
811< Type the <F1> as four characters. The part after the "=" must be done with
812 the actual keys, not the literal text.
813Another solution is to use the actual key code in the mapping for the second
814special key: >
815 :map <F1><Esc>OP :echo "yes"<CR>
816Don't type a real <Esc>, Vim will recognize the key code and replace it with
817<F1> anyway.
818
Bram Moolenaarcdbac1e2005-12-11 21:27:22 +0000819Another problem may be that when keeping ALT or Meta pressed the terminal
820prepends ESC instead of setting the 8th bit. See |:map-alt-keys|.
821
Bram Moolenaar071d4272004-06-13 20:20:40 +0000822 *recursive_mapping*
823If you include the {lhs} in the {rhs} you have a recursive mapping. When
824{lhs} is typed, it will be replaced with {rhs}. When the {lhs} which is
825included in {rhs} is encountered it will be replaced with {rhs}, and so on.
826This makes it possible to repeat a command an infinite number of times. The
827only problem is that the only way to stop this is by causing an error. The
828macros to solve a maze uses this, look there for an example. There is one
829exception: If the {rhs} starts with {lhs}, the first character is not mapped
830again (this is Vi compatible).
831For example: >
832 :map ab abcd
833will execute the "a" command and insert "bcd" in the text. The "ab" in the
834{rhs} will not be mapped again.
835
836If you want to exchange the meaning of two keys you should use the :noremap
837command. For example: >
838 :noremap k j
839 :noremap j k
840This will exchange the cursor up and down commands.
841
842With the normal :map command, when the 'remap' option is on, mapping takes
843place until the text is found not to be a part of a {lhs}. For example, if
844you use: >
845 :map x y
846 :map y x
847Vim will replace x with y, and then y with x, etc. When this has happened
848'maxmapdepth' times (default 1000), Vim will give the error message
849"recursive mapping".
850
851 *:map-undo*
852If you include an undo command inside a mapped sequence, this will bring the
853text back in the state before executing the macro. This is compatible with
854the original Vi, as long as there is only one undo command in the mapped
855sequence (having two undo commands in a mapped sequence did not make sense
856in the original Vi, you would get back the text before the first undo).
857
Bram Moolenaar071d4272004-06-13 20:20:40 +0000858
Bram Moolenaar5b962cf2005-12-12 21:58:40 +00008591.10 MAPPING ALT-KEYS *:map-alt-keys*
Bram Moolenaarcdbac1e2005-12-11 21:27:22 +0000860
861In the GUI Vim handles the Alt key itself, thus mapping keys with ALT should
862always work. But in a terminal Vim gets a sequence of bytes and has to figure
863out whether ALT was pressed or not.
864
Bram Moolenaar4b570182019-10-20 19:53:22 +0200865If the terminal supports the modifyOtherKeys mode and it has been enabled,
866then Vim can recognize more key combinations, see |modifyOtherKeys| below.
867
Bram Moolenaarcdbac1e2005-12-11 21:27:22 +0000868By default Vim assumes that pressing the ALT key sets the 8th bit of a typed
Bram Moolenaar97d29a12005-12-17 22:02:57 +0000869character. Most decent terminals can work that way, such as xterm, aterm and
Bram Moolenaarcdbac1e2005-12-11 21:27:22 +0000870rxvt. If your <A-k> mappings don't work it might be that the terminal is
871prefixing the character with an ESC character. But you can just as well type
872ESC before a character, thus Vim doesn't know what happened (except for
873checking the delay between characters, which is not reliable).
874
875As of this writing, some mainstream terminals like gnome-terminal and konsole
876use the ESC prefix. There doesn't appear a way to have them use the 8th bit
Bram Moolenaar97d29a12005-12-17 22:02:57 +0000877instead. Xterm should work well by default. Aterm and rxvt should work well
878when started with the "--meta8" argument. You can also tweak resources like
879"metaSendsEscape", "eightBitInput" and "eightBitOutput".
Bram Moolenaarcdbac1e2005-12-11 21:27:22 +0000880
881On the Linux console, this behavior can be toggled with the "setmetamode"
882command. Bear in mind that not using an ESC prefix could get you in trouble
883with other programs. You should make sure that bash has the "convert-meta"
884option set to "on" in order for your Meta keybindings to still work on it
885(it's the default readline behavior, unless changed by specific system
886configuration). For that, you can add the line: >
887
888 set convert-meta on
889
890to your ~/.inputrc file. If you're creating the file, you might want to use: >
891
892 $include /etc/inputrc
893
894as the first line, if that file exists on your system, to keep global options.
895This may cause a problem for entering special characters, such as the umlaut.
896Then you should use CTRL-V before that character.
897
898Bear in mind that convert-meta has been reported to have troubles when used in
899UTF-8 locales. On terminals like xterm, the "metaSendsEscape" resource can be
900toggled on the fly through the "Main Options" menu, by pressing Ctrl-LeftClick
901on the terminal; that's a good last resource in case you want to send ESC when
Bram Moolenaar6aa8cea2017-06-05 14:44:35 +0200902using other applications but not when inside Vim.
Bram Moolenaarcdbac1e2005-12-11 21:27:22 +0000903
Bram Moolenaar5b962cf2005-12-12 21:58:40 +0000904
Bram Moolenaar4b570182019-10-20 19:53:22 +02009051.11 MAPPING IN modifyOtherKeys mode *modifyOtherKeys*
906
907Xterm and a few other terminals can be put in a mode where keys with modifiers
908are sent with a special escape code. Vim recognizes these codes and can then
909make a difference between CTRL-H and Backspace, even when Backspace sends the
910character 8. And many more special keys.
911
912For xterm modifyOtherKeys is enabled in the builtin termcap entry. If this is
913not used you can enable modifyOtherKeys with these lines in your vimrc: >
914 let &t_TI = "\<Esc>[>4;2m"
915 let &t_TE = "\<Esc>[>4;m"
916
917In case the modifyOtherKeys mode causes problems you can disable it: >
918 let &t_TI = ""
919 let &t_TE = ""
920It does not take effect immediately. To have this work without restarting Vim
Bram Moolenaar5ef1c6a2019-11-10 22:09:11 +0100921execute a shell command, e.g.: `!ls` Or put the lines in your |vimrc|.
922
923When modifyOtherKeys is enabled you can map <C-[> and <C-S-{>: >
924 imap <C-[> [[[
Bram Moolenaar9a033d72020-10-07 17:29:48 +0200925 imap <C-{> {{{
926Without modifyOtherKeys <C-[> and <C-{> are indistinguishable from Esc.
927Note that <C-{> is used and not <C-S-[> or <C-S-{>. This works on most
928keyboards. Similarly, <C-}> is used instead of <C-S-]> or <C-S-}> and
929<C-|> instead of <C-S-\> or <C-S-|>. Note that '|' has a special meaning in a
930mapping, see |map-bar|.
931
932WARNING: if you map <C-[> you may very well break any key codes that start
933with Esc. Make sure it comes AFTER other mappings.
Bram Moolenaar4b570182019-10-20 19:53:22 +0200934
Bram Moolenaar2547aa92020-07-26 17:00:44 +0200935A known side effect is that in Insert mode the raw escape sequence is inserted
936after the CTRL-V key. This can be used to check whether modifyOtherKeys is
937enabled: In Insert mode type CTRL-SHIFT-V CTRL-V, if you get one byte then
938modifyOtherKeys is off, if you get <1b>27;5;118~ then it is on.
Bram Moolenaar4b570182019-10-20 19:53:22 +0200939
Bram Moolenaar5ef1c6a2019-11-10 22:09:11 +0100940When the 'esckeys' option is off, then modifyOtherKeys will be disabled in
941Insert mode to avoid every key with a modifier causing Insert mode to end.
942
Bram Moolenaar4b570182019-10-20 19:53:22 +0200943
9441.12 MAPPING AN OPERATOR *:map-operator*
Bram Moolenaar5b962cf2005-12-12 21:58:40 +0000945
946An operator is used before a {motion} command. To define your own operator
Bram Moolenaar1b884a02020-12-10 21:11:27 +0100947you must create a mapping that first sets the 'operatorfunc' option and then
Bram Moolenaar5b962cf2005-12-12 21:58:40 +0000948invoke the |g@| operator. After the user types the {motion} command the
949specified function will be called.
950
Bram Moolenaara40ceaf2006-01-13 22:35:40 +0000951 *g@* *E774* *E775*
Bram Moolenaar5b962cf2005-12-12 21:58:40 +0000952g@{motion} Call the function set by the 'operatorfunc' option.
953 The '[ mark is positioned at the start of the text
954 moved over by {motion}, the '] mark on the last
955 character of the text.
956 The function is called with one String argument:
957 "line" {motion} was |linewise|
958 "char" {motion} was |characterwise|
Bram Moolenaarf91787c2010-07-17 12:47:16 +0200959 "block" {motion} was |blockwise-visual|
Bram Moolenaar5b962cf2005-12-12 21:58:40 +0000960 Although "block" would rarely appear, since it can
961 only result from Visual mode where "g@" is not useful.
Bram Moolenaardb84e452010-08-15 13:50:43 +0200962 {not available when compiled without the |+eval|
Bram Moolenaar5b962cf2005-12-12 21:58:40 +0000963 feature}
964
965Here is an example that counts the number of spaces with <F4>: >
966
Bram Moolenaar1c6737b2020-09-07 22:18:52 +0200967 nnoremap <expr> <F4> CountSpaces()
968 xnoremap <expr> <F4> CountSpaces()
969 " doubling <F4> works on a line
970 nnoremap <expr> <F4><F4> CountSpaces() .. '_'
Bram Moolenaar5b962cf2005-12-12 21:58:40 +0000971
Bram Moolenaar1c6737b2020-09-07 22:18:52 +0200972 function CountSpaces(type = '') abort
973 if a:type == ''
974 set opfunc=CountSpaces
975 return 'g@'
976 endif
977
Bram Moolenaar5b962cf2005-12-12 21:58:40 +0000978 let sel_save = &selection
Bram Moolenaar1c6737b2020-09-07 22:18:52 +0200979 let reg_save = getreginfo('"')
980 let cb_save = &clipboard
981 let visual_marks_save = [getpos("'<"), getpos("'>")]
Bram Moolenaar5b962cf2005-12-12 21:58:40 +0000982
Bram Moolenaar1c6737b2020-09-07 22:18:52 +0200983 try
984 set clipboard= selection=inclusive
985 let commands = #{line: "'[V']y", char: "`[v`]y", block: "`[\<c-v>`]y"}
986 silent exe 'noautocmd keepjumps normal! ' .. get(commands, a:type, '')
987 echom getreg('"')->count(' ')
988 finally
989 call setreg('"', reg_save)
990 call setpos("'<", visual_marks_save[0])
991 call setpos("'>", visual_marks_save[1])
992 let &clipboard = cb_save
993 let &selection = sel_save
994 endtry
Bram Moolenaar5b962cf2005-12-12 21:58:40 +0000995 endfunction
996
Bram Moolenaar1c6737b2020-09-07 22:18:52 +0200997An <expr> mapping is used to be able to fetch any prefixed count and register.
998This also avoids using a command line, which would trigger CmdlineEnter and
999CmdlineLeave autocommands.
1000
Bram Moolenaar5b962cf2005-12-12 21:58:40 +00001001Note that the 'selection' option is temporarily set to "inclusive" to be able
1002to yank exactly the right text by using Visual mode from the '[ to the ']
1003mark.
1004
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02001005Also note that the 'clipboard' option is temporarily emptied to avoid
1006clobbering the `"*` or `"+` registers, if its value contains the item `unnamed`
1007or `unnamedplus`.
Bram Moolenaar5b962cf2005-12-12 21:58:40 +00001008
Bram Moolenaar079ba762021-10-23 12:08:41 +01001009The `mode()` function will return the state as it will be after applying the
1010operator.
1011
Yegappan Lakshmanan777175b2021-11-18 22:08:57 +00001012The `mode()` function will return the state as it will be after applying the
1013operator.
1014
1015Here is an example for using a lambda function to create a normal-mode
1016operator to add quotes around text in the current line: >
1017
1018 nnoremap <F4> <Cmd>let &opfunc='{t ->
1019 \ getline(".")
1020 \ ->split("\\zs")
1021 \ ->insert("\"", col("'']"))
1022 \ ->insert("\"", col("''[") - 1)
1023 \ ->join("")
1024 \ ->setline(".")}'<CR>g@
1025
Bram Moolenaar071d4272004-06-13 20:20:40 +00001026==============================================================================
10272. Abbreviations *abbreviations* *Abbreviations*
1028
1029Abbreviations are used in Insert mode, Replace mode and Command-line mode.
1030If you enter a word that is an abbreviation, it is replaced with the word it
1031stands for. This can be used to save typing for often used long words. And
1032you can use it to automatically correct obvious spelling errors.
1033Examples:
1034
Bram Moolenaarc1762cc2007-05-10 16:56:30 +00001035 :iab ms Microsoft
Bram Moolenaar071d4272004-06-13 20:20:40 +00001036 :iab tihs this
1037
1038There are three types of abbreviations:
1039
1040full-id The "full-id" type consists entirely of keyword characters (letters
1041 and characters from 'iskeyword' option). This is the most common
1042 abbreviation.
1043
1044 Examples: "foo", "g3", "-1"
1045
1046end-id The "end-id" type ends in a keyword character, but all the other
1047 characters are not keyword characters.
1048
1049 Examples: "#i", "..f", "$/7"
1050
1051non-id The "non-id" type ends in a non-keyword character, the other
Bram Moolenaar34162142007-05-12 13:12:19 +00001052 characters may be of any type, excluding space and tab. {this type
Bram Moolenaar071d4272004-06-13 20:20:40 +00001053 is not supported by Vi}
1054
1055 Examples: "def#", "4/7$"
1056
1057Examples of strings that cannot be abbreviations: "a.b", "#def", "a b", "_$r"
1058
1059An abbreviation is only recognized when you type a non-keyword character.
1060This can also be the <Esc> that ends insert mode or the <CR> that ends a
1061command. The non-keyword character which ends the abbreviation is inserted
1062after the expanded abbreviation. An exception to this is the character <C-]>,
1063which is used to expand an abbreviation without inserting any extra
1064characters.
1065
1066Example: >
1067 :ab hh hello
1068< "hh<Space>" is expanded to "hello<Space>"
1069 "hh<C-]>" is expanded to "hello"
1070
1071The characters before the cursor must match the abbreviation. Each type has
1072an additional rule:
1073
1074full-id In front of the match is a non-keyword character, or this is where
1075 the line or insertion starts. Exception: When the abbreviation is
1076 only one character, it is not recognized if there is a non-keyword
Bram Moolenaareb3dc872018-05-13 22:34:24 +02001077 character in front of it, other than a space or a tab. However, for
1078 the command line "'<,'>" (or any other marks) is ignored, as if the
1079 command line starts after it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001080
Bram Moolenaar34162142007-05-12 13:12:19 +00001081end-id In front of the match is a keyword character, or a space or a tab,
Bram Moolenaar071d4272004-06-13 20:20:40 +00001082 or this is where the line or insertion starts.
1083
Bram Moolenaar34162142007-05-12 13:12:19 +00001084non-id In front of the match is a space, tab or the start of the line or
Bram Moolenaar071d4272004-06-13 20:20:40 +00001085 the insertion.
1086
1087Examples: ({CURSOR} is where you type a non-keyword character) >
1088 :ab foo four old otters
1089< " foo{CURSOR}" is expanded to " four old otters"
1090 " foobar{CURSOR}" is not expanded
1091 "barfoo{CURSOR}" is not expanded
1092>
1093 :ab #i #include
1094< "#i{CURSOR}" is expanded to "#include"
1095 ">#i{CURSOR}" is not expanded
1096>
Bram Moolenaar81695252004-12-29 20:58:21 +00001097 :ab ;; <endofline>
Bram Moolenaar071d4272004-06-13 20:20:40 +00001098< "test;;" is not expanded
1099 "test ;;" is expanded to "test <endofline>"
1100
Bram Moolenaar7d76c802014-10-15 22:51:52 +02001101To avoid the abbreviation in Insert mode: Type CTRL-V before the character
1102that would trigger the abbreviation. E.g. CTRL-V <Space>. Or type part of
1103the abbreviation, exit insert mode with <Esc>, re-enter insert mode with "a"
1104and type the rest.
1105
Bram Moolenaar071d4272004-06-13 20:20:40 +00001106To avoid the abbreviation in Command-line mode: Type CTRL-V twice somewhere in
1107the abbreviation to avoid it to be replaced. A CTRL-V in front of a normal
1108character is mostly ignored otherwise.
1109
1110It is possible to move the cursor after an abbreviation: >
1111 :iab if if ()<Left>
1112This does not work if 'cpoptions' includes the '<' flag. |<>|
1113
1114You can even do more complicated things. For example, to consume the space
1115typed after an abbreviation: >
1116 func Eatchar(pat)
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001117 let c = nr2char(getchar(0))
Bram Moolenaar071d4272004-06-13 20:20:40 +00001118 return (c =~ a:pat) ? '' : c
1119 endfunc
1120 iabbr <silent> if if ()<Left><C-R>=Eatchar('\s')<CR>
1121
1122There are no default abbreviations.
1123
1124Abbreviations are never recursive. You can use ":ab f f-o-o" without any
1125problem. But abbreviations can be mapped. {some versions of Vi support
1126recursive abbreviations, for no apparent reason}
1127
1128Abbreviations are disabled if the 'paste' option is on.
1129
1130 *:abbreviate-local* *:abbreviate-<buffer>*
1131Just like mappings, abbreviations can be local to a buffer. This is mostly
1132used in a |filetype-plugin| file. Example for a C plugin file: >
1133 :abb <buffer> FF for (i = 0; i < ; ++i)
1134<
1135 *:ab* *:abbreviate*
1136:ab[breviate] list all abbreviations. The character in the first
1137 column indicates the mode where the abbreviation is
1138 used: 'i' for insert mode, 'c' for Command-line
1139 mode, '!' for both. These are the same as for
1140 mappings, see |map-listing|.
1141
Bram Moolenaare344bea2005-09-01 20:46:49 +00001142 *:abbreviate-verbose*
1143When 'verbose' is non-zero, listing an abbreviation will also display where it
1144was last defined. Example: >
1145
1146 :verbose abbreviate
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001147 ! teh the
Bram Moolenaare344bea2005-09-01 20:46:49 +00001148 Last set from /home/abcd/vim/abbr.vim
1149
1150See |:verbose-cmd| for more information.
1151
Bram Moolenaar071d4272004-06-13 20:20:40 +00001152:ab[breviate] {lhs} list the abbreviations that start with {lhs}
1153 You may need to insert a CTRL-V (type it twice) to
1154 avoid that a typed {lhs} is expanded, since
1155 command-line abbreviations apply here.
1156
Bram Moolenaar251e1912011-06-19 05:09:16 +02001157:ab[breviate] [<expr>] [<buffer>] {lhs} {rhs}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001158 add abbreviation for {lhs} to {rhs}. If {lhs} already
1159 existed it is replaced with the new {rhs}. {rhs} may
1160 contain spaces.
Bram Moolenaarfc1421e2006-04-20 22:17:20 +00001161 See |:map-<expr>| for the optional <expr> argument.
Bram Moolenaar251e1912011-06-19 05:09:16 +02001162 See |:map-<buffer>| for the optional <buffer> argument.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001163
1164 *:una* *:unabbreviate*
Bram Moolenaar95a9dd12019-12-19 22:12:03 +01001165:una[bbreviate] [<buffer>] {lhs}
1166 Remove abbreviation for {lhs} from the list. If none
Bram Moolenaar071d4272004-06-13 20:20:40 +00001167 is found, remove abbreviations in which {lhs} matches
1168 with the {rhs}. This is done so that you can even
1169 remove abbreviations after expansion. To avoid
1170 expansion insert a CTRL-V (type it twice).
1171
1172 *:norea* *:noreabbrev*
Bram Moolenaar251e1912011-06-19 05:09:16 +02001173:norea[bbrev] [<expr>] [<buffer>] [lhs] [rhs]
Bram Moolenaar25c9c682019-05-05 18:13:34 +02001174 Same as ":ab", but no remapping for this {rhs}.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001175
Bram Moolenaar61da1bf2019-06-06 12:14:49 +02001176 *:ca* *:cab* *:cabbrev*
Bram Moolenaar251e1912011-06-19 05:09:16 +02001177:ca[bbrev] [<expr>] [<buffer>] [lhs] [rhs]
Bram Moolenaar25c9c682019-05-05 18:13:34 +02001178 Same as ":ab", but for Command-line mode only.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001179
1180 *:cuna* *:cunabbrev*
Bram Moolenaar95a9dd12019-12-19 22:12:03 +01001181:cuna[bbrev] [<buffer>] {lhs}
1182 Same as ":una", but for Command-line mode only.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001183
1184 *:cnorea* *:cnoreabbrev*
Bram Moolenaar251e1912011-06-19 05:09:16 +02001185:cnorea[bbrev] [<expr>] [<buffer>] [lhs] [rhs]
Bram Moolenaar071d4272004-06-13 20:20:40 +00001186 same as ":ab", but for Command-line mode only and no
Bram Moolenaar25c9c682019-05-05 18:13:34 +02001187 remapping for this {rhs}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001188
1189 *:ia* *:iabbrev*
Bram Moolenaar251e1912011-06-19 05:09:16 +02001190:ia[bbrev] [<expr>] [<buffer>] [lhs] [rhs]
Bram Moolenaar25c9c682019-05-05 18:13:34 +02001191 Same as ":ab", but for Insert mode only.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001192
1193 *:iuna* *:iunabbrev*
Bram Moolenaar95a9dd12019-12-19 22:12:03 +01001194:iuna[bbrev] [<buffer>] {lhs}
1195 Same as ":una", but for insert mode only.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001196
1197 *:inorea* *:inoreabbrev*
Bram Moolenaar251e1912011-06-19 05:09:16 +02001198:inorea[bbrev] [<expr>] [<buffer>] [lhs] [rhs]
Bram Moolenaar25c9c682019-05-05 18:13:34 +02001199 Same as ":ab", but for Insert mode only and no
1200 remapping for this {rhs}.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001201
1202 *:abc* *:abclear*
Bram Moolenaar25c9c682019-05-05 18:13:34 +02001203:abc[lear] [<buffer>] Remove all abbreviations.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001204
1205 *:iabc* *:iabclear*
Bram Moolenaar25c9c682019-05-05 18:13:34 +02001206:iabc[lear] [<buffer>] Remove all abbreviations for Insert mode.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001207
1208 *:cabc* *:cabclear*
Bram Moolenaar25c9c682019-05-05 18:13:34 +02001209:cabc[lear] [<buffer>] Remove all abbreviations for Command-line mode.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001210
1211 *using_CTRL-V*
1212It is possible to use special characters in the rhs of an abbreviation.
1213CTRL-V has to be used to avoid the special meaning of most non printable
1214characters. How many CTRL-Vs need to be typed depends on how you enter the
1215abbreviation. This also applies to mappings. Let's use an example here.
1216
1217Suppose you want to abbreviate "esc" to enter an <Esc> character. When you
1218type the ":ab" command in Vim, you have to enter this: (here ^V is a CTRL-V
1219and ^[ is <Esc>)
1220
1221You type: ab esc ^V^V^V^V^V^[
1222
1223 All keyboard input is subjected to ^V quote interpretation, so
1224 the first, third, and fifth ^V characters simply allow the second,
1225 and fourth ^Vs, and the ^[, to be entered into the command-line.
1226
1227You see: ab esc ^V^V^[
1228
1229 The command-line contains two actual ^Vs before the ^[. This is
1230 how it should appear in your .exrc file, if you choose to go that
1231 route. The first ^V is there to quote the second ^V; the :ab
1232 command uses ^V as its own quote character, so you can include quoted
Bram Moolenaar81695252004-12-29 20:58:21 +00001233 whitespace or the | character in the abbreviation. The :ab command
Bram Moolenaar071d4272004-06-13 20:20:40 +00001234 doesn't do anything special with the ^[ character, so it doesn't need
1235 to be quoted. (Although quoting isn't harmful; that's why typing 7
1236 [but not 8!] ^Vs works.)
1237
1238Stored as: esc ^V^[
1239
1240 After parsing, the abbreviation's short form ("esc") and long form
1241 (the two characters "^V^[") are stored in the abbreviation table.
1242 If you give the :ab command with no arguments, this is how the
1243 abbreviation will be displayed.
1244
1245 Later, when the abbreviation is expanded because the user typed in
1246 the word "esc", the long form is subjected to the same type of
1247 ^V interpretation as keyboard input. So the ^V protects the ^[
Bram Moolenaar81695252004-12-29 20:58:21 +00001248 character from being interpreted as the "exit Insert mode" character.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001249 Instead, the ^[ is inserted into the text.
1250
1251Expands to: ^[
1252
1253[example given by Steve Kirkendall]
1254
1255==============================================================================
12563. Local mappings and functions *script-local*
1257
1258When using several Vim script files, there is the danger that mappings and
1259functions used in one script use the same name as in other scripts. To avoid
1260this, they can be made local to the script.
1261
1262 *<SID>* *<SNR>* *E81*
1263The string "<SID>" can be used in a mapping or menu. This requires that the
1264'<' flag is not present in 'cpoptions'.
1265 When executing the map command, Vim will replace "<SID>" with the special
1266key code <SNR>, followed by a number that's unique for the script, and an
1267underscore. Example: >
1268 :map <SID>Add
1269could define a mapping "<SNR>23_Add".
1270
1271When defining a function in a script, "s:" can be prepended to the name to
1272make it local to the script. But when a mapping is executed from outside of
1273the script, it doesn't know in which script the function was defined. To
1274avoid this problem, use "<SID>" instead of "s:". The same translation is done
1275as for mappings. This makes it possible to define a call to the function in
Bram Moolenaar81695252004-12-29 20:58:21 +00001276a mapping.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001277
1278When a local function is executed, it runs in the context of the script it was
1279defined in. This means that new functions and mappings it defines can also
1280use "s:" or "<SID>" and it will use the same unique number as when the
1281function itself was defined. Also, the "s:var" local script variables can be
1282used.
1283
1284When executing an autocommand or a user command, it will run in the context of
1285the script it was defined in. This makes it possible that the command calls a
1286local function or uses a local mapping.
1287
Bram Moolenaar90944302020-08-01 20:45:11 +02001288In case the value is used in a context where <SID> cannot be correctly
1289expanded, use the expand() function: >
1290 let &includexpr = expand('<SID>') .. 'My_includeexpr()'
1291
Bram Moolenaar071d4272004-06-13 20:20:40 +00001292Otherwise, using "<SID>" outside of a script context is an error.
1293
1294If you need to get the script number to use in a complicated script, you can
Bram Moolenaar4770d092006-01-12 23:22:24 +00001295use this function: >
Bram Moolenaar4466ad62020-11-21 13:16:30 +01001296 func s:ScriptNumber()
1297 return matchstr(expand('<SID>'), '<SNR>\zs\d\+\ze_')
1298 endfunc
Bram Moolenaar071d4272004-06-13 20:20:40 +00001299
1300The "<SNR>" will be shown when listing functions and mappings. This is useful
1301to find out what they are defined to.
1302
1303The |:scriptnames| command can be used to see which scripts have been sourced
1304and what their <SNR> number is.
1305
Bram Moolenaar25c9c682019-05-05 18:13:34 +02001306This is all {not available when compiled without the |+eval| feature}.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001307
1308==============================================================================
13094. User-defined commands *user-commands*
1310
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001311It is possible to define your own Ex commands. A user-defined command can act
Bram Moolenaar071d4272004-06-13 20:20:40 +00001312just like a built-in command (it can have a range or arguments, arguments can
1313be completed as filenames or buffer names, etc), except that when the command
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001314is executed, it is transformed into a normal Ex command and then executed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001315
1316For starters: See section |40.2| in the user manual.
1317
Bram Moolenaar166af9b2010-11-16 20:34:40 +01001318 *E183* *E841* *user-cmd-ambiguous*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001319All user defined commands must start with an uppercase letter, to avoid
Bram Moolenaar166af9b2010-11-16 20:34:40 +01001320confusion with builtin commands. Exceptions are these builtin commands:
1321 :Next
1322 :X
1323They cannot be used for a user defined command. ":Print" is also an existing
1324command, but it is deprecated and can be overruled.
1325
1326The other characters of the user command can be uppercase letters, lowercase
1327letters or digits. When using digits, note that other commands that take a
1328numeric argument may become ambiguous. For example, the command ":Cc2" could
1329be the user command ":Cc2" without an argument, or the command ":Cc" with
1330argument "2". It is advised to put a space between the command name and the
1331argument to avoid these problems.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001332
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001333When using a user-defined command, the command can be abbreviated. However, if
1334an abbreviation is not unique, an error will be issued. Furthermore, a
Bram Moolenaar071d4272004-06-13 20:20:40 +00001335built-in command will always take precedence.
1336
1337Example: >
1338 :command Rename ...
1339 :command Renumber ...
1340 :Rena " Means "Rename"
1341 :Renu " Means "Renumber"
1342 :Ren " Error - ambiguous
1343 :command Paste ...
1344 :P " The built-in :Print
1345
1346It is recommended that full names for user-defined commands are used in
1347scripts.
1348
1349:com[mand] *:com* *:command*
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001350 List all user-defined commands. When listing commands,
Bram Moolenaara561a412019-04-25 21:27:58 +02001351 the characters in the first columns are:
Bram Moolenaar071d4272004-06-13 20:20:40 +00001352 ! Command has the -bang attribute
1353 " Command has the -register attribute
Bram Moolenaara561a412019-04-25 21:27:58 +02001354 | Command has the -bar attribute
Bram Moolenaar071d4272004-06-13 20:20:40 +00001355 b Command is local to current buffer
1356 (see below for details on attributes)
Bram Moolenaar818078d2016-08-27 21:58:42 +02001357 The list can be filtered on command name with
1358 |:filter|, e.g., to list all commands with "Pyth" in
1359 the name: >
1360 filter Pyth command
Bram Moolenaar071d4272004-06-13 20:20:40 +00001361
1362:com[mand] {cmd} List the user-defined commands that start with {cmd}
1363
Bram Moolenaar5b8d8fd2005-08-16 23:01:50 +00001364 *:command-verbose*
1365When 'verbose' is non-zero, listing a command will also display where it was
1366last defined. Example: >
1367
1368 :verbose command TOhtml
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001369< Name Args Range Complete Definition ~
1370 TOhtml 0 % :call Convert2HTML(<line1>, <line2>) ~
1371 Last set from /usr/share/vim/vim-7.0/plugin/tohtml.vim ~
1372
Bram Moolenaar5195e452005-08-19 20:32:47 +00001373See |:verbose-cmd| for more information.
Bram Moolenaar5b8d8fd2005-08-16 23:01:50 +00001374
Bram Moolenaar071d4272004-06-13 20:20:40 +00001375 *E174* *E182*
Bram Moolenaar1b884a02020-12-10 21:11:27 +01001376:com[mand][!] [{attr}...] {cmd} {repl}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001377 Define a user command. The name of the command is
Bram Moolenaar1b884a02020-12-10 21:11:27 +01001378 {cmd} and its replacement text is {repl}. The
1379 command's attributes (see below) are {attr}. If the
1380 command already exists, an error is reported, unless a
1381 ! is specified, in which case the command is
1382 redefined. There is one exception: When sourcing a
1383 script again, a command that was previously defined in
1384 that script will be silently replaced.
Bram Moolenaar55d46912018-12-08 16:03:28 +01001385
Bram Moolenaar071d4272004-06-13 20:20:40 +00001386
1387:delc[ommand] {cmd} *:delc* *:delcommand* *E184*
1388 Delete the user-defined command {cmd}.
1389
Bram Moolenaarbdcba242021-09-12 20:58:02 +02001390:delc[ommand] -buffer {cmd} *E1237*
1391 Delete the user-defined command {cmd} that was defined
1392 for the current buffer.
1393
Bram Moolenaar071d4272004-06-13 20:20:40 +00001394:comc[lear] *:comc* *:comclear*
1395 Delete all user-defined commands.
1396
Bram Moolenaar55d46912018-12-08 16:03:28 +01001397
1398Command attributes ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00001399
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001400User-defined commands are treated by Vim just like any other Ex commands. They
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001401can have arguments, or have a range specified. Arguments are subject to
1402completion as filenames, buffers, etc. Exactly how this works depends upon the
Bram Moolenaar071d4272004-06-13 20:20:40 +00001403command's attributes, which are specified when the command is defined.
1404
1405There are a number of attributes, split into four categories: argument
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001406handling, completion behavior, range handling, and special cases. The
Bram Moolenaar071d4272004-06-13 20:20:40 +00001407attributes are described below, by category.
1408
Bram Moolenaar071d4272004-06-13 20:20:40 +00001409
Bram Moolenaar55d46912018-12-08 16:03:28 +01001410Argument handling ~
1411 *E175* *E176* *:command-nargs*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001412By default, a user defined command will take no arguments (and an error is
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001413reported if any are supplied). However, it is possible to specify that the
1414command can take arguments, using the -nargs attribute. Valid cases are:
Bram Moolenaar071d4272004-06-13 20:20:40 +00001415
1416 -nargs=0 No arguments are allowed (the default)
Bram Moolenaar9d87a372018-12-18 21:41:50 +01001417 -nargs=1 Exactly one argument is required, it includes spaces
Bram Moolenaar446beb42011-05-10 17:18:44 +02001418 -nargs=* Any number of arguments are allowed (0, 1, or many),
1419 separated by white space
Bram Moolenaar071d4272004-06-13 20:20:40 +00001420 -nargs=? 0 or 1 arguments are allowed
1421 -nargs=+ Arguments must be supplied, but any number are allowed
1422
Bram Moolenaar34162142007-05-12 13:12:19 +00001423Arguments are considered to be separated by (unescaped) spaces or tabs in this
Bram Moolenaar446beb42011-05-10 17:18:44 +02001424context, except when there is one argument, then the white space is part of
1425the argument.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001426
1427Note that arguments are used as text, not as expressions. Specifically,
1428"s:var" will use the script-local variable in the script where the command was
1429defined, not where it is invoked! Example:
1430 script1.vim: >
1431 :let s:error = "None"
1432 :command -nargs=1 Error echoerr <args>
1433< script2.vim: >
1434 :source script1.vim
1435 :let s:error = "Wrong!"
1436 :Error s:error
Bram Moolenaara7241f52008-06-24 20:39:31 +00001437Executing script2.vim will result in "None" being echoed. Not what you
Bram Moolenaar071d4272004-06-13 20:20:40 +00001438intended! Calling a function may be an alternative.
1439
Bram Moolenaar55d46912018-12-08 16:03:28 +01001440
1441Completion behavior ~
Bram Moolenaar9d87a372018-12-18 21:41:50 +01001442 *:command-completion* *E179* *E180* *E181*
Bram Moolenaar55d46912018-12-08 16:03:28 +01001443 *:command-complete*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001444By default, the arguments of user defined commands do not undergo completion.
1445However, by specifying one or the other of the following attributes, argument
1446completion can be enabled:
1447
Bram Moolenaarcd43eff2018-03-29 15:55:38 +02001448 -complete=arglist file names in argument list
Bram Moolenaar071d4272004-06-13 20:20:40 +00001449 -complete=augroup autocmd groups
1450 -complete=buffer buffer names
Bram Moolenaar5ae636b2012-04-30 18:48:53 +02001451 -complete=behave :behave suboptions
Bram Moolenaare9edd7f2011-07-20 16:37:24 +02001452 -complete=color color schemes
Bram Moolenaar071d4272004-06-13 20:20:40 +00001453 -complete=command Ex command (and arguments)
Bram Moolenaare9edd7f2011-07-20 16:37:24 +02001454 -complete=compiler compilers
Bram Moolenaar4a748032010-09-30 21:47:56 +02001455 -complete=cscope |:cscope| suboptions
Bram Moolenaar071d4272004-06-13 20:20:40 +00001456 -complete=dir directory names
1457 -complete=environment environment variable names
1458 -complete=event autocommand events
1459 -complete=expression Vim expression
1460 -complete=file file and directory names
Bram Moolenaare9edd7f2011-07-20 16:37:24 +02001461 -complete=file_in_path file and directory names in |'path'|
Bram Moolenaara26559b2010-07-31 14:59:19 +02001462 -complete=filetype filetype names |'filetype'|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001463 -complete=function function name
1464 -complete=help help subjects
1465 -complete=highlight highlight groups
Bram Moolenaar5ae636b2012-04-30 18:48:53 +02001466 -complete=history :history suboptions
Bram Moolenaare9edd7f2011-07-20 16:37:24 +02001467 -complete=locale locale names (as output of locale -a)
Bram Moolenaarcae92dc2017-08-06 15:22:15 +02001468 -complete=mapclear buffer argument
Bram Moolenaar071d4272004-06-13 20:20:40 +00001469 -complete=mapping mapping name
1470 -complete=menu menus
Bram Moolenaar9e507ca2016-10-15 15:39:39 +02001471 -complete=messages |:messages| suboptions
Bram Moolenaar071d4272004-06-13 20:20:40 +00001472 -complete=option options
Bram Moolenaar063b9d12016-07-09 20:21:48 +02001473 -complete=packadd optional package |pack-add| names
Bram Moolenaara26559b2010-07-31 14:59:19 +02001474 -complete=shellcmd Shell command
Bram Moolenaar4a748032010-09-30 21:47:56 +02001475 -complete=sign |:sign| suboptions
Bram Moolenaara26559b2010-07-31 14:59:19 +02001476 -complete=syntax syntax file names |'syntax'|
Bram Moolenaarcd9c4622013-06-08 15:24:48 +02001477 -complete=syntime |:syntime| suboptions
Bram Moolenaar071d4272004-06-13 20:20:40 +00001478 -complete=tag tags
1479 -complete=tag_listfiles tags, file names are shown when CTRL-D is hit
Bram Moolenaar24305862012-08-15 14:05:05 +02001480 -complete=user user names
Bram Moolenaar071d4272004-06-13 20:20:40 +00001481 -complete=var user variables
1482 -complete=custom,{func} custom completion, defined via {func}
Bram Moolenaara466c992005-07-09 21:03:22 +00001483 -complete=customlist,{func} custom completion, defined via {func}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001484
Bram Moolenaar3a991dd2014-10-02 01:41:41 +02001485Note: That some completion methods might expand environment variables.
1486
Bram Moolenaara5792f52005-11-23 21:25:05 +00001487
Bram Moolenaar55d46912018-12-08 16:03:28 +01001488Custom completion ~
1489 *:command-completion-custom*
1490 *:command-completion-customlist* *E467* *E468*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001491It is possible to define customized completion schemes via the "custom,{func}"
Bram Moolenaara466c992005-07-09 21:03:22 +00001492or the "customlist,{func}" completion argument. The {func} part should be a
Bram Moolenaara7241f52008-06-24 20:39:31 +00001493function with the following signature: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001494
1495 :function {func}(ArgLead, CmdLine, CursorPos)
1496
Bram Moolenaara466c992005-07-09 21:03:22 +00001497The function need not use all these arguments. The function should provide the
1498completion candidates as the return value.
1499
1500For the "custom" argument, the function should return the completion
1501candidates one per line in a newline separated string.
1502
1503For the "customlist" argument, the function should return the completion
Bram Moolenaara5792f52005-11-23 21:25:05 +00001504candidates as a Vim List. Non-string items in the list are ignored.
Bram Moolenaara466c992005-07-09 21:03:22 +00001505
1506The function arguments are:
Bram Moolenaar071d4272004-06-13 20:20:40 +00001507 ArgLead the leading portion of the argument currently being
1508 completed on
1509 CmdLine the entire command line
Bram Moolenaara5792f52005-11-23 21:25:05 +00001510 CursorPos the cursor position in it (byte index)
Bram Moolenaara466c992005-07-09 21:03:22 +00001511The function may use these for determining context. For the "custom"
1512argument, it is not necessary to filter candidates against the (implicit
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001513pattern in) ArgLead. Vim will filter the candidates with its regexp engine
Bram Moolenaara466c992005-07-09 21:03:22 +00001514after function return, and this is probably more efficient in most cases. For
1515the "customlist" argument, Vim will not filter the returned completion
1516candidates and the user supplied function should filter the candidates.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001517
1518The following example lists user names to a Finger command >
1519 :com -complete=custom,ListUsers -nargs=1 Finger !finger <args>
1520 :fun ListUsers(A,L,P)
1521 : return system("cut -d: -f1 /etc/passwd")
1522 :endfun
1523
Bram Moolenaara466c992005-07-09 21:03:22 +00001524The following example completes filenames from the directories specified in
1525the 'path' option: >
1526 :com -nargs=1 -bang -complete=customlist,EditFileComplete
1527 \ EditFile edit<bang> <args>
1528 :fun EditFileComplete(A,L,P)
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001529 : return split(globpath(&path, a:A), "\n")
Bram Moolenaara466c992005-07-09 21:03:22 +00001530 :endfun
1531<
Bram Moolenaar5ac3b1a2010-07-27 22:50:36 +02001532This example does not work for file names with spaces!
1533
Bram Moolenaara5792f52005-11-23 21:25:05 +00001534
Bram Moolenaar55d46912018-12-08 16:03:28 +01001535Range handling ~
1536 *E177* *E178* *:command-range* *:command-count*
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001537By default, user-defined commands do not accept a line number range. However,
Bram Moolenaar071d4272004-06-13 20:20:40 +00001538it is possible to specify that the command does take a range (the -range
1539attribute), or that it takes an arbitrary count value, either in the line
1540number position (-range=N, like the |:split| command) or as a "count"
Bram Moolenaar5c5b0942007-05-06 12:07:59 +00001541argument (-count=N, like the |:Next| command). The count will then be
1542available in the argument with |<count>|.
1543
1544Possible attributes are:
Bram Moolenaar071d4272004-06-13 20:20:40 +00001545
1546 -range Range allowed, default is current line
1547 -range=% Range allowed, default is whole file (1,$)
1548 -range=N A count (default N) which is specified in the line
Bram Moolenaar8e5af3e2011-04-28 19:02:44 +02001549 number position (like |:split|); allows for zero line
1550 number.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001551 -count=N A count (default N) which is specified either in the line
Bram Moolenaar32e7b2d2005-02-27 22:36:47 +00001552 number position, or as an initial argument (like |:Next|).
Bram Moolenaar25c9c682019-05-05 18:13:34 +02001553 -count acts like -count=0
Bram Moolenaar071d4272004-06-13 20:20:40 +00001554
1555Note that -range=N and -count=N are mutually exclusive - only one should be
1556specified.
1557
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02001558 *:command-addr*
Bram Moolenaarf1d6ccf2014-12-08 04:16:44 +01001559It is possible that the special characters in the range like ., $ or % which
1560by default correspond to the current line, last line and the whole buffer,
1561relate to arguments, (loaded) buffers, windows or tab pages.
1562
Bram Moolenaara561a412019-04-25 21:27:58 +02001563Possible values are (second column is the short name used in listing):
Bram Moolenaar25c9c682019-05-05 18:13:34 +02001564 -addr=lines Range of lines (this is the default for -range)
Bram Moolenaara561a412019-04-25 21:27:58 +02001565 -addr=arguments arg Range for arguments
1566 -addr=buffers buf Range for buffers (also not loaded buffers)
1567 -addr=loaded_buffers load Range for loaded buffers
1568 -addr=windows win Range for windows
1569 -addr=tabs tab Range for tab pages
1570 -addr=quickfix qf Range for quickfix entries
Bram Moolenaar25c9c682019-05-05 18:13:34 +02001571 -addr=other ? other kind of range; can use ".", "$" and "%"
1572 as with "lines" (this is the default for
1573 -count)
Bram Moolenaarf1d6ccf2014-12-08 04:16:44 +01001574
Bram Moolenaar55d46912018-12-08 16:03:28 +01001575
1576Special cases ~
1577 *:command-bang* *:command-bar*
Bram Moolenaar5c5b0942007-05-06 12:07:59 +00001578 *:command-register* *:command-buffer*
Bram Moolenaar519cc552021-11-16 19:18:26 +00001579 *:command-keepscript*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001580There are some special cases as well:
1581
1582 -bang The command can take a ! modifier (like :q or :w)
1583 -bar The command can be followed by a "|" and another command.
1584 A "|" inside the command argument is not allowed then.
1585 Also checks for a " to start a comment.
1586 -register The first argument to the command can be an optional
1587 register name (like :del, :put, :yank).
1588 -buffer The command will only be available in the current buffer.
Bram Moolenaar58ef8a32021-11-12 11:25:11 +00001589 -keepscript Do not use the location of where the user command was
1590 defined for verbose messages, use the location of where
1591 the user command was invoked.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001592
1593In the cases of the -count and -register attributes, if the optional argument
1594is supplied, it is removed from the argument list and is available to the
1595replacement text separately.
Bram Moolenaar7cba6c02013-09-05 22:13:31 +02001596Note that these arguments can be abbreviated, but that is a deprecated
1597feature. Use the full name for new scripts.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001598
Bram Moolenaar55d46912018-12-08 16:03:28 +01001599
1600Replacement text ~
Bram Moolenaar73b8b0a2021-08-01 14:52:32 +02001601 *:command-repl*
Bram Moolenaar5d7c2df2021-07-27 21:17:32 +02001602The {repl} argument is normally one long string, possibly with "|" separated
1603commands. A special case is when the argument is "{", then the following
1604lines, up to a line starting with "}" are used and |Vim9| syntax applies.
1605Example: >
1606 :command MyCommand {
1607 echo 'hello'
1608 g:calledMyCommand = true
1609 }
Bram Moolenaar63b91732021-08-05 20:40:03 +02001610< *E1231*
1611There must be white space before the "{". No nesting is supported, inline
1612functions cannot be used. Commands where a "|" may appear in the argument,
1613such as commands with an expression argument, cannot be followed by a "|" and
1614another command.
Bram Moolenaar5d7c2df2021-07-27 21:17:32 +02001615
Bram Moolenaar1b884a02020-12-10 21:11:27 +01001616The replacement text {repl} for a user defined command is scanned for special
1617escape sequences, using <...> notation. Escape sequences are replaced with
1618values from the entered command line, and all other text is copied unchanged.
1619The resulting string is executed as an Ex command. To avoid the replacement
1620use <lt> in place of the initial <. Thus to include "<bang>" literally use
Bram Moolenaar371d5402006-03-20 21:47:49 +00001621"<lt>bang>".
Bram Moolenaar071d4272004-06-13 20:20:40 +00001622
1623The valid escape sequences are
1624
1625 *<line1>*
1626 <line1> The starting line of the command range.
1627 *<line2>*
1628 <line2> The final line of the command range.
Bram Moolenaarc168bd42017-09-10 17:34:35 +02001629 *<range>*
1630 <range> The number of items in the command range: 0, 1 or 2
Bram Moolenaar071d4272004-06-13 20:20:40 +00001631 *<count>*
1632 <count> Any count supplied (as described for the '-range'
1633 and '-count' attributes).
1634 *<bang>*
1635 <bang> (See the '-bang' attribute) Expands to a ! if the
1636 command was executed with a ! modifier, otherwise
1637 expands to nothing.
Bram Moolenaar1d59aa12020-09-19 18:50:13 +02001638 *<mods>* *<q-mods>* *:command-modifiers*
Bram Moolenaar63a60de2016-06-04 22:08:55 +02001639 <mods> The command modifiers, if specified. Otherwise, expands to
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001640 nothing. Supported modifiers are |:aboveleft|, |:belowright|,
1641 |:botright|, |:browse|, |:confirm|, |:hide|, |:keepalt|,
Bram Moolenaarbc8801c2016-08-02 21:04:33 +02001642 |:keepjumps|, |:keepmarks|, |:keeppatterns|, |:leftabove|,
1643 |:lockmarks|, |:noswapfile| |:rightbelow|, |:silent|, |:tab|,
1644 |:topleft|, |:verbose|, and |:vertical|.
1645 Note that these are not yet supported: |:noautocmd|,
1646 |:sandbox| and |:unsilent|.
Bram Moolenaar63a60de2016-06-04 22:08:55 +02001647 Examples: >
1648 command! -nargs=+ -complete=file MyEdit
1649 \ for f in expand(<q-args>, 0, 1) |
1650 \ exe '<mods> split ' . f |
1651 \ endfor
1652
1653 function! SpecialEdit(files, mods)
1654 for f in expand(a:files, 0, 1)
1655 exe a:mods . ' split ' . f
1656 endfor
1657 endfunction
1658 command! -nargs=+ -complete=file Sedit
1659 \ call SpecialEdit(<q-args>, <q-mods>)
1660<
Bram Moolenaar071d4272004-06-13 20:20:40 +00001661 *<reg>* *<register>*
1662 <reg> (See the '-register' attribute) The optional register,
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001663 if specified. Otherwise, expands to nothing. <register>
Bram Moolenaar071d4272004-06-13 20:20:40 +00001664 is a synonym for this.
1665 *<args>*
1666 <args> The command arguments, exactly as supplied (but as
1667 noted above, any count or register can consume some
1668 of the arguments, which are then not part of <args>).
1669 <lt> A single '<' (Less-Than) character. This is needed if you
1670 want to get a literal copy of one of these escape sequences
1671 into the expansion - for example, to get <bang>, use
1672 <lt>bang>.
1673
1674 *<q-args>*
1675If the first two characters of an escape sequence are "q-" (for example,
1676<q-args>) then the value is quoted in such a way as to make it a valid value
1677for use in an expression. This uses the argument as one single value.
Bram Moolenaar51485f02005-06-04 21:55:20 +00001678When there is no argument <q-args> is an empty string.
Bram Moolenaar552f8a12007-03-08 17:12:08 +00001679 *<f-args>*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001680To allow commands to pass their arguments on to a user-defined function, there
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001681is a special form <f-args> ("function args"). This splits the command
Bram Moolenaar34162142007-05-12 13:12:19 +00001682arguments at spaces and tabs, quotes each argument individually, and the
Bram Moolenaar071d4272004-06-13 20:20:40 +00001683<f-args> sequence is replaced by the comma-separated list of quoted arguments.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001684See the Mycmd example below. If no arguments are given <f-args> is removed.
Bram Moolenaar552f8a12007-03-08 17:12:08 +00001685 To embed whitespace into an argument of <f-args>, prepend a backslash.
1686<f-args> replaces every pair of backslashes (\\) with one backslash. A
1687backslash followed by a character other than white space or a backslash
1688remains unmodified. Overview:
1689
1690 command <f-args> ~
1691 XX ab 'ab'
1692 XX a\b 'a\b'
1693 XX a\ b 'a b'
1694 XX a\ b 'a ', 'b'
1695 XX a\\b 'a\b'
1696 XX a\\ b 'a\', 'b'
1697 XX a\\\b 'a\\b'
1698 XX a\\\ b 'a\ b'
1699 XX a\\\\b 'a\\b'
1700 XX a\\\\ b 'a\\', 'b'
Bram Moolenaar071d4272004-06-13 20:20:40 +00001701
1702Examples >
1703
1704 " Delete everything after here to the end
1705 :com Ddel +,$d
1706
1707 " Rename the current buffer
1708 :com -nargs=1 -bang -complete=file Ren f <args>|w<bang>
1709
1710 " Replace a range with the contents of a file
1711 " (Enter this all as one line)
1712 :com -range -nargs=1 -complete=file
1713 Replace <line1>-pu_|<line1>,<line2>d|r <args>|<line1>d
1714
1715 " Count the number of lines in the range
Bram Moolenaar81695252004-12-29 20:58:21 +00001716 :com! -range -nargs=0 Lines echo <line2> - <line1> + 1 "lines"
Bram Moolenaar071d4272004-06-13 20:20:40 +00001717
1718 " Call a user function (example of <f-args>)
1719 :com -nargs=* Mycmd call Myfunc(<f-args>)
1720
1721When executed as: >
1722 :Mycmd arg1 arg2
1723This will invoke: >
1724 :call Myfunc("arg1","arg2")
1725
1726 :" A more substantial example
1727 :function Allargs(command)
Bram Moolenaara7241f52008-06-24 20:39:31 +00001728 : let i = 0
1729 : while i < argc()
1730 : if filereadable(argv(i))
1731 : execute "e " . argv(i)
Bram Moolenaar071d4272004-06-13 20:20:40 +00001732 : execute a:command
1733 : endif
1734 : let i = i + 1
1735 : endwhile
1736 :endfunction
1737 :command -nargs=+ -complete=command Allargs call Allargs(<q-args>)
1738
1739The command Allargs takes any Vim command(s) as argument and executes it on all
1740files in the argument list. Usage example (note use of the "e" flag to ignore
1741errors and the "update" command to write modified buffers): >
1742 :Allargs %s/foo/bar/ge|update
1743This will invoke: >
1744 :call Allargs("%s/foo/bar/ge|update")
1745<
Bram Moolenaar1b884a02020-12-10 21:11:27 +01001746If the command is defined in Vim9 script (a script that starts with
1747`:vim9script` and in a `:def` function) then {repl} will be executed as in Vim9
1748script. Thus this depends on where the command is defined, not where it is
1749used.
1750
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001751When defining a user command in a script, it will be able to call functions
Bram Moolenaar071d4272004-06-13 20:20:40 +00001752local to the script and use mappings local to the script. When the user
1753invokes the user command, it will run in the context of the script it was
1754defined in. This matters if |<SID>| is used in a command.
1755
Bram Moolenaar91f84f62018-07-29 15:07:52 +02001756 vim:tw=78:ts=8:noet:ft=help:norl: