blob: 877be58098edde3fb863efcf26c3cd8a1799fd4b [file] [log] [blame]
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00001*map.txt* For Vim version 8.2. Last change: 2022 Jan 23
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
Bram Moolenaar2f0936c2022-01-08 21:51:59 +00009This subject is introduced in sections |05.4|, |24.7| and |40.1| of the user
Bram Moolenaar071d4272004-06-13 20:20:40 +000010manual.
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 Moolenaar1fc34222022-03-03 13:56:24 +000083 Note: When <Plug> appears in the {rhs} this part is
84 always applied even if remapping is disallowed.
Bram Moolenaar071d4272004-06-13 20:20:40 +000085
86
Bram Moolenaar06b5db92006-02-10 23:11:56 +000087:unm[ap] {lhs} |mapmode-nvo| *:unm* *:unmap*
88:nun[map] {lhs} |mapmode-n| *:nun* *:nunmap*
89:vu[nmap] {lhs} |mapmode-v| *:vu* *:vunmap*
Bram Moolenaar371d5402006-03-20 21:47:49 +000090:xu[nmap] {lhs} |mapmode-x| *:xu* *:xunmap*
91:sunm[ap] {lhs} |mapmode-s| *:sunm* *:sunmap*
Bram Moolenaar06b5db92006-02-10 23:11:56 +000092:ou[nmap] {lhs} |mapmode-o| *:ou* *:ounmap*
93:unm[ap]! {lhs} |mapmode-ic| *:unm!* *:unmap!*
94:iu[nmap] {lhs} |mapmode-i| *:iu* *:iunmap*
95:lu[nmap] {lhs} |mapmode-l| *:lu* *:lunmap*
Bram Moolenaar61da1bf2019-06-06 12:14:49 +020096:cu[nmap] {lhs} |mapmode-c| *:cu* *:cun* *:cunmap*
Bram Moolenaar37c64c72017-09-19 22:06:03 +020097:tunma[p] {lhs} |mapmode-t| *:tunma* *:tunmap*
Bram Moolenaar071d4272004-06-13 20:20:40 +000098 Remove the mapping of {lhs} for the modes where the
99 map command applies. The mapping may remain defined
100 for other modes where it applies.
Bram Moolenaar88a42052021-11-21 21:13:36 +0000101 It also works when {lhs} matches the {rhs} of a
Bram Moolenaar2f0936c2022-01-08 21:51:59 +0000102 mapping. This is for when an abbreviation applied.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000103 Note: Trailing spaces are included in the {lhs}. This
104 unmap does NOT work: >
105 :map @@ foo
106 :unmap @@ | print
107
Bram Moolenaar06b5db92006-02-10 23:11:56 +0000108:mapc[lear] |mapmode-nvo| *:mapc* *:mapclear*
109:nmapc[lear] |mapmode-n| *:nmapc* *:nmapclear*
110:vmapc[lear] |mapmode-v| *:vmapc* *:vmapclear*
Bram Moolenaar371d5402006-03-20 21:47:49 +0000111:xmapc[lear] |mapmode-x| *:xmapc* *:xmapclear*
112:smapc[lear] |mapmode-s| *:smapc* *:smapclear*
Bram Moolenaar06b5db92006-02-10 23:11:56 +0000113:omapc[lear] |mapmode-o| *:omapc* *:omapclear*
114:mapc[lear]! |mapmode-ic| *:mapc!* *:mapclear!*
115:imapc[lear] |mapmode-i| *:imapc* *:imapclear*
116:lmapc[lear] |mapmode-l| *:lmapc* *:lmapclear*
117:cmapc[lear] |mapmode-c| *:cmapc* *:cmapclear*
Bram Moolenaar69fbc9e2017-09-14 20:37:57 +0200118:tmapc[lear] |mapmode-t| *:tmapc* *:tmapclear*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000119 Remove ALL mappings for the modes where the map
Bram Moolenaar25c9c682019-05-05 18:13:34 +0200120 command applies.
Bram Moolenaar251e1912011-06-19 05:09:16 +0200121 Use the <buffer> argument to remove buffer-local
122 mappings |:map-<buffer>|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000123 Warning: This also removes the default mappings.
124
Bram Moolenaar06b5db92006-02-10 23:11:56 +0000125:map |mapmode-nvo|
126:nm[ap] |mapmode-n|
127:vm[ap] |mapmode-v|
Bram Moolenaar371d5402006-03-20 21:47:49 +0000128:xm[ap] |mapmode-x|
129:sm[ap] |mapmode-s|
Bram Moolenaar06b5db92006-02-10 23:11:56 +0000130:om[ap] |mapmode-o|
131:map! |mapmode-ic|
132:im[ap] |mapmode-i|
133:lm[ap] |mapmode-l|
134:cm[ap] |mapmode-c|
Bram Moolenaar37c64c72017-09-19 22:06:03 +0200135:tma[p] |mapmode-t|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000136 List all key mappings for the modes where the map
137 command applies. Note that ":map" and ":map!" are
138 used most often, because they include the other modes.
139
Bram Moolenaar06b5db92006-02-10 23:11:56 +0000140:map {lhs} |mapmode-nvo| *:map_l*
141:nm[ap] {lhs} |mapmode-n| *:nmap_l*
142:vm[ap] {lhs} |mapmode-v| *:vmap_l*
Bram Moolenaar371d5402006-03-20 21:47:49 +0000143:xm[ap] {lhs} |mapmode-x| *:xmap_l*
144:sm[ap] {lhs} |mapmode-s| *:smap_l*
Bram Moolenaar06b5db92006-02-10 23:11:56 +0000145:om[ap] {lhs} |mapmode-o| *:omap_l*
146:map! {lhs} |mapmode-ic| *:map_l!*
147:im[ap] {lhs} |mapmode-i| *:imap_l*
148:lm[ap] {lhs} |mapmode-l| *:lmap_l*
149:cm[ap] {lhs} |mapmode-c| *:cmap_l*
Bram Moolenaar37c64c72017-09-19 22:06:03 +0200150:tma[p] {lhs} |mapmode-t| *:tmap_l*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000151 List the key mappings for the key sequences starting
152 with {lhs} in the modes where the map command applies.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000153
154These commands are used to map a key or key sequence to a string of
155characters. You can use this to put command sequences under function keys,
156translate one key into another, etc. See |:mkexrc| for how to save and
157restore the current mappings.
158
Bram Moolenaar5b962cf2005-12-12 21:58:40 +0000159 *map-ambiguous*
160When two mappings start with the same sequence of characters, they are
161ambiguous. Example: >
162 :imap aa foo
163 :imap aaa bar
164When Vim has read "aa", it will need to get another character to be able to
165decide if "aa" or "aaa" should be mapped. This means that after typing "aa"
166that mapping won't get expanded yet, Vim is waiting for another character.
167If you type a space, then "foo" will get inserted, plus the space. If you
168type "a", then "bar" will get inserted.
Bram Moolenaar5b962cf2005-12-12 21:58:40 +0000169
170
1711.2 SPECIAL ARGUMENTS *:map-arguments*
172
Bram Moolenaar72179e12013-06-29 13:58:31 +0200173"<buffer>", "<nowait>", "<silent>", "<special>", "<script>", "<expr>" and
174"<unique>" can be used in any order. They must appear right after the
175command, before any other arguments.
Bram Moolenaar4e427192006-03-10 21:34:27 +0000176
Bram Moolenaar0e6adf82021-12-16 14:41:10 +0000177 *:map-local* *:map-<buffer>* *:map-buffer* *E224* *E225*
Bram Moolenaarc236c162008-07-13 17:41:49 +0000178If the first argument to one of these commands is "<buffer>" the mapping will
179be effective in the current buffer only. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000180 :map <buffer> ,w /[.,;]<CR>
181Then you can map ",w" to something else in another buffer: >
182 :map <buffer> ,w /[#&!]<CR>
Bram Moolenaar72179e12013-06-29 13:58:31 +0200183The local buffer mappings are used before the global ones. See <nowait> below
184to make a short local mapping not taking effect when a longer global one
185exists.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000186The "<buffer>" argument can also be used to clear mappings: >
187 :unmap <buffer> ,w
188 :mapclear <buffer>
189Local mappings are also cleared when a buffer is deleted, but not when it is
190unloaded. Just like local option values.
Bram Moolenaarec7944a2013-06-12 21:29:15 +0200191Also see |map-precedence|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000192
Bram Moolenaar72179e12013-06-29 13:58:31 +0200193 *:map-<nowait>* *:map-nowait*
194When defining a buffer-local mapping for "," there may be a global mapping
195that starts with ",". Then you need to type another character for Vim to know
196whether to use the "," mapping or the longer one. To avoid this add the
197<nowait> argument. Then the mapping will be used when it matches, Vim does
198not wait for more characters to be typed. However, if the characters were
Bram Moolenaar6aa8cea2017-06-05 14:44:35 +0200199already typed they are used.
Bram Moolenaar207f0092020-08-30 17:20:20 +0200200Note that this works when the <nowait> mapping fully matches and is found
201before any partial matches. This works when:
202- There is only one matching buffer-local mapping, since these are always
203 found before global mappings.
Bram Moolenaar1c6737b2020-09-07 22:18:52 +0200204- There is another buffer-local mapping that partly matches, but it is
Bram Moolenaar207f0092020-08-30 17:20:20 +0200205 defined earlier (last defined mapping is found first).
Bram Moolenaar72179e12013-06-29 13:58:31 +0200206
Bram Moolenaar071d4272004-06-13 20:20:40 +0000207 *:map-<silent>* *:map-silent*
208To define a mapping which will not be echoed on the command line, add
209"<silent>" as the first argument. Example: >
210 :map <silent> ,h /Header<CR>
211The search string will not be echoed when using this mapping. Messages from
212the executed command are still given though. To shut them up too, add a
213":silent" in the executed command: >
214 :map <silent> ,h :exe ":silent normal /Header\r"<CR>
215Prompts will still be given, e.g., for inputdialog().
216Using "<silent>" for an abbreviation is possible, but will cause redrawing of
217the command line to fail.
218
Bram Moolenaar9c102382006-05-03 21:26:49 +0000219 *:map-<special>* *:map-special*
220Define a mapping with <> notation for special keys, even though the "<" flag
221may appear in 'cpoptions'. This is useful if the side effect of setting
222'cpoptions' is not desired. Example: >
223 :map <special> <F12> /Header<CR>
224<
Bram Moolenaar071d4272004-06-13 20:20:40 +0000225 *:map-<script>* *:map-script*
226If the first argument to one of these commands is "<script>" and it is used to
227define a new mapping or abbreviation, the mapping will only remap characters
228in the {rhs} using mappings that were defined local to a script, starting with
229"<SID>". This can be used to avoid that mappings from outside a script
230interfere (e.g., when CTRL-V is remapped in mswin.vim), but do use other
231mappings defined in the script.
232Note: ":map <script>" and ":noremap <script>" do the same thing. The
233"<script>" overrules the command name. Using ":noremap <script>" is
234preferred, because it's clearer that remapping is (mostly) disabled.
235
Bram Moolenaar0e6adf82021-12-16 14:41:10 +0000236 *:map-<unique>* *:map-unique* *E226* *E227*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000237If the first argument to one of these commands is "<unique>" and it is used to
238define a new mapping or abbreviation, the command will fail if the mapping or
239abbreviation already exists. Example: >
240 :map <unique> ,w /[#&!]<CR>
241When defining a local mapping, there will also be a check if a global map
242already exists which is equal.
243Example of what will fail: >
244 :map ,w /[#&!]<CR>
245 :map <buffer> <unique> ,w /[.,;]<CR>
Bram Moolenaara40ceaf2006-01-13 22:35:40 +0000246If you want to map a key and then have it do what it was originally mapped to,
247have a look at |maparg()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000248
Bram Moolenaar4e427192006-03-10 21:34:27 +0000249 *:map-<expr>* *:map-expression*
250If the first argument to one of these commands is "<expr>" and it is used to
251define a new mapping or abbreviation, the argument is an expression. The
252expression is evaluated to obtain the {rhs} that is used. Example: >
Bram Moolenaar4c295022021-05-02 17:19:11 +0200253 :inoremap <expr> . <SID>InsertDot()
254The result of the s:InsertDot() function will be inserted. It could check the
Bram Moolenaar4e427192006-03-10 21:34:27 +0000255text before the cursor and start omni completion when some condition is met.
Bram Moolenaar4c295022021-05-02 17:19:11 +0200256Using a script-local function is preferred, to avoid polluting the global
257namespace. Use <SID> in the RHS so that the script that the mapping was
258defined in can be found.
Bram Moolenaar4e427192006-03-10 21:34:27 +0000259
Bram Moolenaarda9591e2009-09-30 13:17:02 +0000260For abbreviations |v:char| is set to the character that was typed to trigger
261the abbreviation. You can use this to decide how to expand the {lhs}. You
Bram Moolenaar5302d9e2011-09-14 17:55:08 +0200262should not either insert or change the v:char.
Bram Moolenaarda9591e2009-09-30 13:17:02 +0000263
Bram Moolenaar4f4d51a2020-10-11 13:57:40 +0200264In case you want the mapping to not do anything, you can have the expression
265evaluate to an empty string. If something changed that requires Vim to
266go through the main loop (e.g. to update the display), return "\<Ignore>".
267This is similar to "nothing" but makes Vim return from the loop that waits for
268input. Example: >
269 func s:OpenPopup()
270 call popup_create(... arguments ...)
271 return "\<Ignore>"
272 endfunc
Bram Moolenaar4c295022021-05-02 17:19:11 +0200273 nnoremap <expr> <F3> <SID>OpenPopup()
Bram Moolenaar4f4d51a2020-10-11 13:57:40 +0200274
Bram Moolenaarfd31be22022-01-16 14:46:06 +0000275Keep in mind that the expression may be evaluated when looking for
Bram Moolenaar18b7d862021-03-17 13:28:05 +0100276typeahead, before the previous command has been executed. For example: >
277 func StoreColumn()
278 let g:column = col('.')
279 return 'x'
280 endfunc
281 nnoremap <expr> x StoreColumn()
282 nmap ! f!x
Bram Moolenaardad44732021-03-31 20:07:33 +0200283You will notice that g:column has the value from before executing "f!",
284because "x" is evaluated before "f!" is executed.
Bram Moolenaar18b7d862021-03-17 13:28:05 +0100285This can be solved by inserting <Ignore> before the character that is
286expression-mapped: >
287 nmap ! f!<Ignore>x
288
Bram Moolenaare32c3c42022-01-15 18:26:04 +0000289When defining a mapping in a |Vim9| script, the expression will be evaluated
290in the context of that script. This means that script-local items can be
291accessed in the expression.
292
Bram Moolenaar4e427192006-03-10 21:34:27 +0000293Be very careful about side effects! The expression is evaluated while
Bram Moolenaarc9b4b052006-04-30 18:54:39 +0000294obtaining characters, you may very well make the command dysfunctional.
295For this reason the following is blocked:
Bram Moolenaar5c5b0942007-05-06 12:07:59 +0000296- Changing the buffer text |textlock|.
297- Editing another buffer.
298- The |:normal| command.
299- Moving the cursor is allowed, but it is restored afterwards.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +0000300If you want the mapping to do any of these let the returned characters do
Bram Moolenaar957cf672020-11-12 14:21:06 +0100301that, or use a |<Cmd>| mapping instead.
Bram Moolenaar4e427192006-03-10 21:34:27 +0000302
Bram Moolenaar15146672011-10-20 22:22:38 +0200303You can use getchar(), it consumes typeahead if there is any. E.g., if you
304have these mappings: >
305 inoremap <expr> <C-L> nr2char(getchar())
306 inoremap <expr> <C-L>x "foo"
307If you now type CTRL-L nothing happens yet, Vim needs the next character to
308decide what mapping to use. If you type 'x' the second mapping is used and
Bram Moolenaarf1568ec2011-12-14 21:17:39 +0100309"foo" is inserted. If you type any other key the first mapping is used,
310getchar() gets the typed key and returns it.
Bram Moolenaar15146672011-10-20 22:22:38 +0200311
Bram Moolenaar4e427192006-03-10 21:34:27 +0000312Here is an example that inserts a list number that increases: >
313 let counter = 0
314 inoremap <expr> <C-L> ListItem()
315 inoremap <expr> <C-R> ListReset()
316
317 func ListItem()
318 let g:counter += 1
Bram Moolenaarc51cf032022-02-26 12:25:45 +0000319 return g:counter .. '. '
Bram Moolenaar4e427192006-03-10 21:34:27 +0000320 endfunc
321
322 func ListReset()
323 let g:counter = 0
324 return ''
325 endfunc
326
Bram Moolenaard9967712006-03-11 21:18:15 +0000327CTRL-L inserts the next number, CTRL-R resets the count. CTRL-R returns an
Bram Moolenaar4e427192006-03-10 21:34:27 +0000328empty string, so that nothing is inserted.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000329
Bram Moolenaar1c6737b2020-09-07 22:18:52 +0200330Note that using 0x80 as a single byte before other text does not work, it will
331be seen as a special key.
Bram Moolenaar8424a622006-04-19 21:23:36 +0000332
Bram Moolenaar957cf672020-11-12 14:21:06 +0100333 *<Cmd>* *:map-cmd*
334The special text <Cmd> begins a "command mapping", it executes the command
335directly without changing modes. Where you might use ":...<CR>" in the
336{rhs} of a mapping, you can instead use "<Cmd>...<CR>".
337Example: >
338 noremap x <Cmd>echo mode(1)<CR>
339<
340This is more flexible than `:<C-U>` in Visual and Operator-pending mode, or
341`<C-O>:` in Insert mode, because the commands are executed directly in the
342current mode, instead of always going to Normal mode. Visual mode is
343preserved, so tricks with |gv| are not needed. Commands can be invoked
344directly in Command-line mode (which would otherwise require timer hacks).
345Example of using <Cmd> halfway Insert mode: >
346 nnoremap <F3> aText <Cmd>echo mode(1)<CR> Added<Esc>
347
348Unlike <expr> mappings, there are no special restrictions on the <Cmd>
Bram Moolenaar4466ad62020-11-21 13:16:30 +0100349command: it is executed as if an (unrestricted) |autocommand| was invoked.
Bram Moolenaar957cf672020-11-12 14:21:06 +0100350
Bram Moolenaare32c3c42022-01-15 18:26:04 +0000351 *<ScriptCmd>*
352<ScriptCmd> is like <Cmd> but sets the context to the script the mapping was
353defined in, for the duration of the command execution. This is especially
354useful for |Vim9| script. It also works to access an import, which is useful
355in a plugin using an autoload script: >
356 vim9script
357 import autoload 'implementation.vim' as impl
Bram Moolenaarfd31be22022-01-16 14:46:06 +0000358 nnoremap <F4> <ScriptCmd>impl.DoTheWork()<CR>
Bram Moolenaare32c3c42022-01-15 18:26:04 +0000359
360No matter where <F4> is typed, the "impl" import will be found in the script
361context of where the mapping was defined. And since it's an autoload import,
362the "implementation.vim" script will only be loaded once <F4> is typed, not
363when the mapping is defined.
364
Bram Moolenaar957cf672020-11-12 14:21:06 +0100365Note:
Bram Moolenaare32c3c42022-01-15 18:26:04 +0000366- Because <Cmd> and <ScriptCmd> avoid mode-changes it does not trigger
367 |CmdlineEnter| and |CmdlineLeave| events, because no user interaction is
368 expected.
Bram Moolenaar957cf672020-11-12 14:21:06 +0100369- For the same reason, |keycodes| like <C-R><C-W> are interpreted as plain,
370 unmapped keys.
Bram Moolenaar4466ad62020-11-21 13:16:30 +0100371- The command is not echo'ed, no need for <silent>.
Bram Moolenaar88a42052021-11-21 21:13:36 +0000372- The {rhs} is not subject to abbreviations nor to other mappings, even if the
373 mapping is recursive.
Bram Moolenaar4466ad62020-11-21 13:16:30 +0100374- In Visual mode you can use `line('v')` and `col('v')` to get one end of the
375 Visual area, the cursor is at the other end.
Bram Moolenaar957cf672020-11-12 14:21:06 +0100376- In Select mode, |:map| and |:vmap| command mappings are executed in
377 Visual mode. Use |:smap| to handle Select mode differently.
378
Bram Moolenaara4d131d2021-12-27 21:33:07 +0000379 *E1255* *E1136*
Bram Moolenaare32c3c42022-01-15 18:26:04 +0000380<Cmd> and <ScriptCmd> commands must terminate, that is, they must be followed
381by <CR> in the {rhs} of the mapping definition. |Command-line| mode is never
382entered.
Bram Moolenaar957cf672020-11-12 14:21:06 +0100383
384 *E1137*
Bram Moolenaare32c3c42022-01-15 18:26:04 +0000385<Cmd> and <ScriptCmd> commands can have only normal characters and cannot
386contain special characters like function keys.
Bram Moolenaar957cf672020-11-12 14:21:06 +0100387
Bram Moolenaar071d4272004-06-13 20:20:40 +0000388
Bram Moolenaar5b962cf2005-12-12 21:58:40 +00003891.3 MAPPING AND MODES *:map-modes*
Bram Moolenaara7241f52008-06-24 20:39:31 +0000390 *mapmode-nvo* *mapmode-n* *mapmode-v* *mapmode-o*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000391
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100392There are six sets of mappings
Bram Moolenaar071d4272004-06-13 20:20:40 +0000393- For Normal mode: When typing commands.
394- For Visual mode: When typing commands while the Visual area is highlighted.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100395- For Select mode: like Visual mode but typing text replaces the selection.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000396- For Operator-pending mode: When an operator is pending (after "d", "y", "c",
Bram Moolenaara7241f52008-06-24 20:39:31 +0000397 etc.). See below: |omap-info|.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000398- For Insert mode. These are also used in Replace mode.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000399- For Command-line mode: When entering a ":" or "/" command.
400
Bram Moolenaar071d4272004-06-13 20:20:40 +0000401Special case: While typing a count for a command in Normal mode, mapping zero
402is disabled. This makes it possible to map zero without making it impossible
403to type a count with a zero.
404
405 *map-overview* *map-modes*
Bram Moolenaare968e362014-05-13 20:23:24 +0200406Overview of which map command works in which mode. More details below.
407 COMMANDS MODES ~
408:map :noremap :unmap Normal, Visual, Select, Operator-pending
409:nmap :nnoremap :nunmap Normal
410:vmap :vnoremap :vunmap Visual and Select
411:smap :snoremap :sunmap Select
412:xmap :xnoremap :xunmap Visual
413:omap :onoremap :ounmap Operator-pending
414:map! :noremap! :unmap! Insert and Command-line
415:imap :inoremap :iunmap Insert
416:lmap :lnoremap :lunmap Insert, Command-line, Lang-Arg
417:cmap :cnoremap :cunmap Command-line
Bram Moolenaar69fbc9e2017-09-14 20:37:57 +0200418:tmap :tnoremap :tunmap Terminal-Job
Bram Moolenaar071d4272004-06-13 20:20:40 +0000419
Bram Moolenaar3ec32172021-05-16 12:39:47 +0200420Same information in a table:
421 *map-table*
422 Mode | Norm | Ins | Cmd | Vis | Sel | Opr | Term | Lang | ~
423Command +------+-----+-----+-----+-----+-----+------+------+ ~
424[nore]map | yes | - | - | yes | yes | yes | - | - |
425n[nore]map | yes | - | - | - | - | - | - | - |
426[nore]map! | - | yes | yes | - | - | - | - | - |
427i[nore]map | - | yes | - | - | - | - | - | - |
428c[nore]map | - | - | yes | - | - | - | - | - |
429v[nore]map | - | - | - | yes | yes | - | - | - |
430x[nore]map | - | - | - | yes | - | - | - | - |
431s[nore]map | - | - | - | - | yes | - | - | - |
432o[nore]map | - | - | - | - | - | yes | - | - |
433t[nore]map | - | - | - | - | - | - | yes | - |
434l[nore]map | - | yes | yes | - | - | - | - | yes |
435
Bram Moolenaare968e362014-05-13 20:23:24 +0200436
437 COMMANDS MODES ~
Bram Moolenaarc9b4b052006-04-30 18:54:39 +0000438 Normal Visual+Select Operator-pending ~
439:map :noremap :unmap :mapclear yes yes yes
440:nmap :nnoremap :nunmap :nmapclear yes - -
441:vmap :vnoremap :vunmap :vmapclear - yes -
442:omap :onoremap :ounmap :omapclear - - yes
Bram Moolenaar371d5402006-03-20 21:47:49 +0000443
Bram Moolenaar4c3f5362006-04-11 21:38:50 +0000444:nunmap can also be used outside of a monastery.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +0000445 *mapmode-x* *mapmode-s*
Bram Moolenaar371d5402006-03-20 21:47:49 +0000446Some commands work both in Visual and Select mode, some in only one. Note
447that quite often "Visual" is mentioned where both Visual and Select mode
448apply. |Select-mode-mapping|
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100449NOTE: Mapping a printable character in Select mode may confuse the user. It's
450better to explicitly use :xmap and :smap for printable characters. Or use
451:sunmap after defining the mapping.
Bram Moolenaar371d5402006-03-20 21:47:49 +0000452
Bram Moolenaare968e362014-05-13 20:23:24 +0200453 COMMANDS MODES ~
Bram Moolenaarc9b4b052006-04-30 18:54:39 +0000454 Visual Select ~
455:vmap :vnoremap :vunmap :vmapclear yes yes
456:xmap :xnoremap :xunmap :xmapclear yes -
457:smap :snoremap :sunmap :smapclear - yes
Bram Moolenaar071d4272004-06-13 20:20:40 +0000458
Bram Moolenaar06b5db92006-02-10 23:11:56 +0000459 *mapmode-ic* *mapmode-i* *mapmode-c* *mapmode-l*
Bram Moolenaar371d5402006-03-20 21:47:49 +0000460Some commands work both in Insert mode and Command-line mode, some not:
461
Bram Moolenaare968e362014-05-13 20:23:24 +0200462 COMMANDS MODES ~
Bram Moolenaar071d4272004-06-13 20:20:40 +0000463 Insert Command-line Lang-Arg ~
464:map! :noremap! :unmap! :mapclear! yes yes -
465:imap :inoremap :iunmap :imapclear yes - -
466:cmap :cnoremap :cunmap :cmapclear - yes -
467:lmap :lnoremap :lunmap :lmapclear yes* yes* yes*
468
Bram Moolenaar5ef1c6a2019-11-10 22:09:11 +0100469* If 'iminsert' is 1, see |language-mapping| below.
470
Bram Moolenaar071d4272004-06-13 20:20:40 +0000471The original Vi did not have separate mappings for
472Normal/Visual/Operator-pending mode and for Insert/Command-line mode.
473Therefore the ":map" and ":map!" commands enter and display mappings for
474several modes. In Vim you can use the ":nmap", ":vmap", ":omap", ":cmap" and
475":imap" commands to enter mappings for each mode separately.
476
Bram Moolenaar69fbc9e2017-09-14 20:37:57 +0200477 *mapmode-t*
478The terminal mappings are used in a terminal window, when typing keys for the
479job running in the terminal. See |terminal-typing|.
480
Bram Moolenaara7241f52008-06-24 20:39:31 +0000481 *omap-info*
482Operator-pending mappings can be used to define a movement command that can be
Bram Moolenaar95bafa22018-10-02 13:26:25 +0200483used with any operator. Simple example: >
484 :omap { w
485makes "y{" work like "yw" and "d{" like "dw".
Bram Moolenaara7241f52008-06-24 20:39:31 +0000486
487To ignore the starting cursor position and select different text, you can have
488the omap start Visual mode to select the text to be operated upon. Example
489that operates on a function name in the current line: >
490 onoremap <silent> F :<C-U>normal! 0f(hviw<CR>
491The CTRL-U (<C-U>) is used to remove the range that Vim may insert. The
492Normal mode commands find the first '(' character and select the first word
493before it. That usually is the function name.
494
Bram Moolenaar071d4272004-06-13 20:20:40 +0000495To enter a mapping for Normal and Visual mode, but not Operator-pending mode,
Bram Moolenaar95bafa22018-10-02 13:26:25 +0200496first define it for all three modes, then unmap it for
497Operator-pending mode: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000498 :map xx something-difficult
499 :ounmap xx
Bram Moolenaar95bafa22018-10-02 13:26:25 +0200500
Bram Moolenaar071d4272004-06-13 20:20:40 +0000501Likewise for a mapping for Visual and Operator-pending mode or Normal and
502Operator-pending mode.
503
504 *language-mapping*
505":lmap" defines a mapping that applies to:
506- Insert mode
507- Command-line mode
508- when entering a search pattern
509- the argument of the commands that accept a text character, such as "r" and
510 "f"
511- for the input() line
512Generally: Whenever a character is to be typed that is part of the text in the
513buffer, not a Vim command character. "Lang-Arg" isn't really another mode,
514it's just used here for this situation.
515 The simplest way to load a set of related language mappings is by using the
516'keymap' option. See |45.5|.
517 In Insert mode and in Command-line mode the mappings can be disabled with
Bram Moolenaar7cba6c02013-09-05 22:13:31 +0200518the CTRL-^ command |i_CTRL-^| |c_CTRL-^|. These commands change the value of
Bram Moolenaar3b1db362013-08-10 15:00:24 +0200519the 'iminsert' option. When starting to enter a normal command line (not a
520search pattern) the mappings are disabled until a CTRL-^ is typed. The state
521last used is remembered for Insert mode and Search patterns separately. The
522state for Insert mode is also used when typing a character as an argument to
523command like "f" or "t".
Bram Moolenaar071d4272004-06-13 20:20:40 +0000524 Language mappings will never be applied to already mapped characters. They
525are only used for typed characters. This assumes that the language mapping
526was already done when typing the mapping.
527
Bram Moolenaar071d4272004-06-13 20:20:40 +0000528
Bram Moolenaar5b962cf2005-12-12 21:58:40 +00005291.4 LISTING MAPPINGS *map-listing*
530
Bram Moolenaar071d4272004-06-13 20:20:40 +0000531When listing mappings the characters in the first two columns are:
532
533 CHAR MODE ~
Bram Moolenaar5c5b0942007-05-06 12:07:59 +0000534 <Space> Normal, Visual, Select and Operator-pending
Bram Moolenaar071d4272004-06-13 20:20:40 +0000535 n Normal
Bram Moolenaar5c5b0942007-05-06 12:07:59 +0000536 v Visual and Select
537 s Select
538 x Visual
Bram Moolenaar071d4272004-06-13 20:20:40 +0000539 o Operator-pending
540 ! Insert and Command-line
541 i Insert
542 l ":lmap" mappings for Insert, Command-line and Lang-Arg
543 c Command-line
Bram Moolenaar63c4e8a2017-09-17 20:32:20 +0200544 t Terminal-Job
Bram Moolenaar071d4272004-06-13 20:20:40 +0000545
546Just before the {rhs} a special character can appear:
547 * indicates that it is not remappable
548 & indicates that only script-local mappings are remappable
549 @ indicates a buffer-local mapping
550
551Everything from the first non-blank after {lhs} up to the end of the line
552(or '|') is considered to be part of {rhs}. This allows the {rhs} to end
553with a space.
554
555Note: When using mappings for Visual mode, you can use the "'<" mark, which
556is the start of the last selected Visual area in the current buffer |'<|.
557
Bram Moolenaar818078d2016-08-27 21:58:42 +0200558The |:filter| command can be used to select what mappings to list. The
559pattern is matched against the {lhs} and {rhs} in the raw form.
560
Bram Moolenaarae5bce12005-08-15 21:41:48 +0000561 *:map-verbose*
562When 'verbose' is non-zero, listing a key map will also display where it was
563last defined. Example: >
564
565 :verbose map <C-W>*
566 n <C-W>* * <C-W><C-S>*
Bram Moolenaarc9b4b052006-04-30 18:54:39 +0000567 Last set from /home/abcd/.vimrc
Bram Moolenaarae5bce12005-08-15 21:41:48 +0000568
Bram Moolenaar5195e452005-08-19 20:32:47 +0000569See |:verbose-cmd| for more information.
Bram Moolenaarae5bce12005-08-15 21:41:48 +0000570
Bram Moolenaar5b962cf2005-12-12 21:58:40 +0000571
5721.5 MAPPING SPECIAL KEYS *:map-special-keys*
573
574There are three ways to map a special key:
5751. The Vi-compatible method: Map the key code. Often this is a sequence that
576 starts with <Esc>. To enter a mapping like this you type ":map " and then
577 you have to type CTRL-V before hitting the function key. Note that when
578 the key code for the key is in the termcap (the t_ options), it will
579 automatically be translated into the internal code and become the second
580 way of mapping (unless the 'k' flag is included in 'cpoptions').
5812. The second method is to use the internal code for the function key. To
582 enter such a mapping type CTRL-K and then hit the function key, or use
583 the form "#1", "#2", .. "#9", "#0", "<Up>", "<S-Down>", "<S-F7>", etc.
584 (see table of keys |key-notation|, all keys from <Up> can be used). The
585 first ten function keys can be defined in two ways: Just the number, like
586 "#2", and with "<F>", like "<F2>". Both stand for function key 2. "#0"
587 refers to function key 10, defined with option 't_f10', which may be
588 function key zero on some keyboards. The <> form cannot be used when
589 'cpoptions' includes the '<' flag.
5903. Use the termcap entry, with the form <t_xx>, where "xx" is the name of the
591 termcap entry. Any string entry can be used. For example: >
592 :map <t_F3> G
593< Maps function key 13 to "G". This does not work if 'cpoptions' includes
594 the '<' flag.
595
596The advantage of the second and third method is that the mapping will work on
597different terminals without modification (the function key will be
598translated into the same internal code or the actual key code, no matter what
599terminal you are using. The termcap must be correct for this to work, and you
600must use the same mappings).
601
602DETAIL: Vim first checks if a sequence from the keyboard is mapped. If it
603isn't the terminal key codes are tried (see |terminal-options|). If a
604terminal code is found it is replaced with the internal code. Then the check
605for a mapping is done again (so you can map an internal code to something
606else). What is written into the script file depends on what is recognized.
607If the terminal key code was recognized as a mapping the key code itself is
608written to the script file. If it was recognized as a terminal code the
609internal code is written to the script file.
610
611
6121.6 SPECIAL CHARACTERS *:map-special-chars*
Bram Moolenaar345efa02016-01-15 20:57:49 +0100613 *map_backslash* *map-backslash*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000614Note that only CTRL-V is mentioned here as a special character for mappings
615and abbreviations. When 'cpoptions' does not contain 'B', a backslash can
616also be used like CTRL-V. The <> notation can be fully used then |<>|. But
617you cannot use "<C-V>" like CTRL-V to escape the special meaning of what
618follows.
619
620To map a backslash, or use a backslash literally in the {rhs}, the special
621sequence "<Bslash>" can be used. This avoids the need to double backslashes
622when using nested mappings.
623
Bram Moolenaar345efa02016-01-15 20:57:49 +0100624 *map_CTRL-C* *map-CTRL-C*
Bram Moolenaar1e015462005-09-25 22:16:38 +0000625Using CTRL-C in the {lhs} is possible, but it will only work when Vim is
626waiting for a key, not when Vim is busy with something. When Vim is busy
627CTRL-C interrupts/breaks the command.
628When using the GUI version on MS-Windows CTRL-C can be mapped to allow a Copy
629command to the clipboard. Use CTRL-Break to interrupt Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000630
Bram Moolenaar345efa02016-01-15 20:57:49 +0100631 *map_space_in_lhs* *map-space_in_lhs*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000632To include a space in {lhs} precede it with a CTRL-V (type two CTRL-Vs for
633each space).
Bram Moolenaar345efa02016-01-15 20:57:49 +0100634 *map_space_in_rhs* *map-space_in_rhs*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000635If you want a {rhs} that starts with a space, use "<Space>". To be fully Vi
636compatible (but unreadable) don't use the |<>| notation, precede {rhs} with a
637single CTRL-V (you have to type CTRL-V two times).
Bram Moolenaar345efa02016-01-15 20:57:49 +0100638 *map_empty_rhs* *map-empty-rhs*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000639You can create an empty {rhs} by typing nothing after a single CTRL-V (you
640have to type CTRL-V two times). Unfortunately, you cannot do this in a vimrc
641file.
642 *<Nop>*
Bram Moolenaar446beb42011-05-10 17:18:44 +0200643An easier way to get a mapping that doesn't produce anything, is to use
644"<Nop>" for the {rhs}. This only works when the |<>| notation is enabled.
645For example, to make sure that function key 8 does nothing at all: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000646 :map <F8> <Nop>
647 :map! <F8> <Nop>
648<
Bram Moolenaar5b962cf2005-12-12 21:58:40 +0000649 *map-multibyte*
650It is possible to map multibyte characters, but only the whole character. You
651cannot map the first byte only. This was done to prevent problems in this
652scenario: >
653 :set encoding=latin1
654 :imap <M-C> foo
655 :set encoding=utf-8
656The mapping for <M-C> is defined with the latin1 encoding, resulting in a 0xc3
Bram Moolenaar85eee132018-05-06 17:57:30 +0200657byte. If you type the character á (0xe1 <M-a>) in UTF-8 encoding this is the
Bram Moolenaar446beb42011-05-10 17:18:44 +0200658two bytes 0xc3 0xa1. You don't want the 0xc3 byte to be mapped then or
Bram Moolenaar85eee132018-05-06 17:57:30 +0200659otherwise it would be impossible to type the á character.
Bram Moolenaar5b962cf2005-12-12 21:58:40 +0000660
Bram Moolenaar071d4272004-06-13 20:20:40 +0000661 *<Leader>* *mapleader*
662To define a mapping which uses the "mapleader" variable, the special string
663"<Leader>" can be used. It is replaced with the string value of "mapleader".
664If "mapleader" is not set or empty, a backslash is used instead. Example: >
665 :map <Leader>A oanother line<Esc>
666Works like: >
667 :map \A oanother line<Esc>
668But after: >
669 :let mapleader = ","
670It works like: >
671 :map ,A oanother line<Esc>
672
673Note that the value of "mapleader" is used at the moment the mapping is
674defined. Changing "mapleader" after that has no effect for already defined
675mappings.
676
677 *<LocalLeader>* *maplocalleader*
Bram Moolenaara7241f52008-06-24 20:39:31 +0000678<LocalLeader> is just like <Leader>, except that it uses "maplocalleader"
679instead of "mapleader". <LocalLeader> is to be used for mappings which are
680local to a buffer. Example: >
Bram Moolenaarb8ff1fb2012-02-04 21:59:01 +0100681 :map <buffer> <LocalLeader>A oanother line<Esc>
Bram Moolenaar071d4272004-06-13 20:20:40 +0000682<
683In a global plugin <Leader> should be used and in a filetype plugin
684<LocalLeader>. "mapleader" and "maplocalleader" can be equal. Although, if
685you make them different, there is a smaller chance of mappings from global
686plugins to clash with mappings for filetype plugins. For example, you could
687keep "mapleader" at the default backslash, and set "maplocalleader" to an
688underscore.
689
690 *map-<SID>*
691In a script the special key name "<SID>" can be used to define a mapping
692that's local to the script. See |<SID>| for details.
693
694 *<Plug>*
695The special key name "<Plug>" can be used for an internal mapping, which is
696not to be matched with any key sequence. This is useful in plugins
697|using-<Plug>|.
698
699 *<Char>* *<Char->*
700To map a character by its decimal, octal or hexadecimal number the <Char>
701construct can be used:
702 <Char-123> character 123
703 <Char-033> character 27
704 <Char-0x7f> character 127
Bram Moolenaar5302d9e2011-09-14 17:55:08 +0200705 <S-Char-114> character 114 ('r') shifted ('R')
Bram Moolenaar207f0092020-08-30 17:20:20 +0200706This is useful to specify a (multibyte) character in a 'keymap' file.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000707Upper and lowercase differences are ignored.
708
709 *map-comments*
710It is not possible to put a comment after these commands, because the '"'
Bram Moolenaar036986f2017-03-16 17:41:02 +0100711character is considered to be part of the {lhs} or {rhs}. However, one can
712use |", since this starts a new, empty command with a comment.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000713
Bram Moolenaar345efa02016-01-15 20:57:49 +0100714 *map_bar* *map-bar*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000715Since the '|' character is used to separate a map command from the next
716command, you will have to do something special to include a '|' in {rhs}.
717There are three methods:
718 use works when example ~
719 <Bar> '<' is not in 'cpoptions' :map _l :!ls <Bar> more^M
720 \| 'b' is not in 'cpoptions' :map _l :!ls \| more^M
721 ^V| always, in Vim and Vi :map _l :!ls ^V| more^M
722
723(here ^V stands for CTRL-V; to get one CTRL-V you have to type it twice; you
724cannot use the <> notation "<C-V>" here).
725
726All three work when you use the default setting for 'cpoptions'.
727
728When 'b' is present in 'cpoptions', "\|" will be recognized as a mapping
729ending in a '\' and then another command. This is Vi compatible, but
730illogical when compared to other commands.
731
Bram Moolenaar345efa02016-01-15 20:57:49 +0100732 *map_return* *map-return*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000733When you have a mapping that contains an Ex command, you need to put a line
734terminator after it to have it executed. The use of <CR> is recommended for
735this (see |<>|). Example: >
Bram Moolenaar251835e2014-02-24 02:51:51 +0100736 :map _ls :!ls -l %:S<CR>:echo "the end"<CR>
Bram Moolenaar071d4272004-06-13 20:20:40 +0000737
738To avoid mapping of the characters you type in insert or Command-line mode,
739type a CTRL-V first. The mapping in Insert mode is disabled if the 'paste'
740option is on.
Bram Moolenaare2db6952013-07-24 19:53:36 +0200741 *map-error*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000742Note that when an error is encountered (that causes an error message or beep)
743the rest of the mapping is not executed. This is Vi-compatible.
744
745Note that the second character (argument) of the commands @zZtTfF[]rm'`"v
746and CTRL-X is not mapped. This was done to be able to use all the named
747registers and marks, even when the command with the same name has been
748mapped.
749
Bram Moolenaar5b962cf2005-12-12 21:58:40 +0000750
7511.7 WHAT KEYS TO MAP *map-which-keys*
752
Bram Moolenaar071d4272004-06-13 20:20:40 +0000753If you are going to map something, you will need to choose which key(s) to use
754for the {lhs}. You will have to avoid keys that are used for Vim commands,
755otherwise you would not be able to use those commands anymore. Here are a few
756suggestions:
757- Function keys <F2>, <F3>, etc.. Also the shifted function keys <S-F1>,
758 <S-F2>, etc. Note that <F1> is already used for the help command.
Bram Moolenaarf91787c2010-07-17 12:47:16 +0200759- Meta-keys (with the ALT key pressed). Depending on your keyboard accented
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100760 characters may be used as well. |:map-alt-keys|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000761- Use the '_' or ',' character and then any other character. The "_" and ","
762 commands do exist in Vim (see |_| and |,|), but you probably never use them.
763- Use a key that is a synonym for another command. For example: CTRL-P and
764 CTRL-N. Use an extra character to allow more mappings.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100765- The key defined by <Leader> and one or more other keys. This is especially
766 useful in scripts. |mapleader|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000767
768See the file "index" for keys that are not used and thus can be mapped without
769losing any builtin function. You can also use ":help {key}^D" to find out if
770a key is used for some command. ({key} is the specific key you want to find
771out about, ^D is CTRL-D).
772
Bram Moolenaar5b962cf2005-12-12 21:58:40 +0000773
7741.8 EXAMPLES *map-examples*
775
Bram Moolenaar071d4272004-06-13 20:20:40 +0000776A few examples (given as you type them, for "<CR>" you type four characters;
777the '<' flag must not be present in 'cpoptions' for this to work). >
778
779 :map <F3> o#include
780 :map <M-g> /foo<CR>cwbar<Esc>
781 :map _x d/END/e<CR>
782 :map! qq quadrillion questions
Bram Moolenaar5c5b0942007-05-06 12:07:59 +0000783
784
785Multiplying a count
786
787When you type a count before triggering a mapping, it's like the count was
788typed before the {lhs}. For example, with this mapping: >
789 :map <F4> 3w
790Typing 2<F4> will result in "23w". Thus not moving 2 * 3 words but 23 words.
791If you want to multiply counts use the expression register: >
792 :map <F4> @='3w'<CR>
793The part between quotes is the expression being executed. |@=|
794
Bram Moolenaar5b962cf2005-12-12 21:58:40 +0000795
7961.9 USING MAPPINGS *map-typing*
797
Bram Moolenaar071d4272004-06-13 20:20:40 +0000798Vim will compare what you type with the start of a mapped sequence. If there
799is an incomplete match, it will get more characters until there either is a
800complete match or until there is no match at all. Example: If you map! "qq",
801the first 'q' will not appear on the screen until you type another
802character. This is because Vim cannot know if the next character will be a
803'q' or not. If the 'timeout' option is on (which is the default) Vim will
804only wait for one second (or as long as specified with the 'timeoutlen'
805option). After that it assumes that the 'q' is to be interpreted as such. If
806you type slowly, or your system is slow, reset the 'timeout' option. Then you
807might want to set the 'ttimeout' option.
808
Bram Moolenaar37c64c72017-09-19 22:06:03 +0200809 *map-precedence*
Bram Moolenaarec7944a2013-06-12 21:29:15 +0200810Buffer-local mappings (defined using |:map-<buffer>|) take precedence over
811global mappings. When a buffer-local mapping is the same as a global mapping,
812Vim will use the buffer-local mapping. In addition, Vim will use a complete
Bram Moolenaar14b69452013-06-29 23:05:20 +0200813mapping immediately if it was defined with <nowait>, even if a longer mapping
814has the same prefix. For example, given the following two mappings: >
815 :map <buffer> <nowait> \a :echo "Local \a"<CR>
816 :map \abc :echo "Global \abc"<CR>
817When typing \a the buffer-local mapping will be used immediately. Vim will
818not wait for more characters to see if the user might be typing \abc.
Bram Moolenaarec7944a2013-06-12 21:29:15 +0200819
Bram Moolenaar071d4272004-06-13 20:20:40 +0000820 *map-keys-fails*
Bram Moolenaarcdbac1e2005-12-11 21:27:22 +0000821There are situations where key codes might not be recognized:
Bram Moolenaar071d4272004-06-13 20:20:40 +0000822- Vim can only read part of the key code. Mostly this is only the first
823 character. This happens on some Unix versions in an xterm.
824- The key code is after character(s) that are mapped. E.g., "<F1><F1>" or
825 "g<F1>".
Bram Moolenaarcdbac1e2005-12-11 21:27:22 +0000826
Bram Moolenaar071d4272004-06-13 20:20:40 +0000827The result is that the key code is not recognized in this situation, and the
Bram Moolenaarcdbac1e2005-12-11 21:27:22 +0000828mapping fails. There are two actions needed to avoid this problem:
829
Bram Moolenaar071d4272004-06-13 20:20:40 +0000830- Remove the 'K' flag from 'cpoptions'. This will make Vim wait for the rest
831 of the characters of the function key.
832- When using <F1> to <F4> the actual key code generated may correspond to
833 <xF1> to <xF4>. There are mappings from <xF1> to <F1>, <xF2> to <F2>, etc.,
834 but these are not recognized after another half a mapping. Make sure the
835 key codes for <F1> to <F4> are correct: >
836 :set <F1>=<type CTRL-V><type F1>
837< Type the <F1> as four characters. The part after the "=" must be done with
838 the actual keys, not the literal text.
839Another solution is to use the actual key code in the mapping for the second
840special key: >
841 :map <F1><Esc>OP :echo "yes"<CR>
842Don't type a real <Esc>, Vim will recognize the key code and replace it with
843<F1> anyway.
844
Bram Moolenaarcdbac1e2005-12-11 21:27:22 +0000845Another problem may be that when keeping ALT or Meta pressed the terminal
846prepends ESC instead of setting the 8th bit. See |:map-alt-keys|.
847
Bram Moolenaar071d4272004-06-13 20:20:40 +0000848 *recursive_mapping*
849If you include the {lhs} in the {rhs} you have a recursive mapping. When
850{lhs} is typed, it will be replaced with {rhs}. When the {lhs} which is
851included in {rhs} is encountered it will be replaced with {rhs}, and so on.
852This makes it possible to repeat a command an infinite number of times. The
853only problem is that the only way to stop this is by causing an error. The
854macros to solve a maze uses this, look there for an example. There is one
855exception: If the {rhs} starts with {lhs}, the first character is not mapped
856again (this is Vi compatible).
857For example: >
858 :map ab abcd
859will execute the "a" command and insert "bcd" in the text. The "ab" in the
860{rhs} will not be mapped again.
861
862If you want to exchange the meaning of two keys you should use the :noremap
863command. For example: >
864 :noremap k j
865 :noremap j k
866This will exchange the cursor up and down commands.
867
868With the normal :map command, when the 'remap' option is on, mapping takes
869place until the text is found not to be a part of a {lhs}. For example, if
870you use: >
871 :map x y
872 :map y x
873Vim will replace x with y, and then y with x, etc. When this has happened
874'maxmapdepth' times (default 1000), Vim will give the error message
875"recursive mapping".
876
877 *:map-undo*
878If you include an undo command inside a mapped sequence, this will bring the
879text back in the state before executing the macro. This is compatible with
880the original Vi, as long as there is only one undo command in the mapped
881sequence (having two undo commands in a mapped sequence did not make sense
882in the original Vi, you would get back the text before the first undo).
883
Bram Moolenaar071d4272004-06-13 20:20:40 +0000884
Bram Moolenaar5b962cf2005-12-12 21:58:40 +00008851.10 MAPPING ALT-KEYS *:map-alt-keys*
Bram Moolenaarcdbac1e2005-12-11 21:27:22 +0000886
887In the GUI Vim handles the Alt key itself, thus mapping keys with ALT should
888always work. But in a terminal Vim gets a sequence of bytes and has to figure
889out whether ALT was pressed or not.
890
Bram Moolenaar4b570182019-10-20 19:53:22 +0200891If the terminal supports the modifyOtherKeys mode and it has been enabled,
892then Vim can recognize more key combinations, see |modifyOtherKeys| below.
893
Bram Moolenaarcdbac1e2005-12-11 21:27:22 +0000894By default Vim assumes that pressing the ALT key sets the 8th bit of a typed
Bram Moolenaar97d29a12005-12-17 22:02:57 +0000895character. Most decent terminals can work that way, such as xterm, aterm and
Bram Moolenaarcdbac1e2005-12-11 21:27:22 +0000896rxvt. If your <A-k> mappings don't work it might be that the terminal is
897prefixing the character with an ESC character. But you can just as well type
898ESC before a character, thus Vim doesn't know what happened (except for
899checking the delay between characters, which is not reliable).
900
901As of this writing, some mainstream terminals like gnome-terminal and konsole
902use the ESC prefix. There doesn't appear a way to have them use the 8th bit
Bram Moolenaar97d29a12005-12-17 22:02:57 +0000903instead. Xterm should work well by default. Aterm and rxvt should work well
904when started with the "--meta8" argument. You can also tweak resources like
905"metaSendsEscape", "eightBitInput" and "eightBitOutput".
Bram Moolenaarcdbac1e2005-12-11 21:27:22 +0000906
907On the Linux console, this behavior can be toggled with the "setmetamode"
908command. Bear in mind that not using an ESC prefix could get you in trouble
909with other programs. You should make sure that bash has the "convert-meta"
910option set to "on" in order for your Meta keybindings to still work on it
911(it's the default readline behavior, unless changed by specific system
912configuration). For that, you can add the line: >
913
914 set convert-meta on
915
916to your ~/.inputrc file. If you're creating the file, you might want to use: >
917
918 $include /etc/inputrc
919
920as the first line, if that file exists on your system, to keep global options.
921This may cause a problem for entering special characters, such as the umlaut.
922Then you should use CTRL-V before that character.
923
924Bear in mind that convert-meta has been reported to have troubles when used in
925UTF-8 locales. On terminals like xterm, the "metaSendsEscape" resource can be
926toggled on the fly through the "Main Options" menu, by pressing Ctrl-LeftClick
927on the terminal; that's a good last resource in case you want to send ESC when
Bram Moolenaar6aa8cea2017-06-05 14:44:35 +0200928using other applications but not when inside Vim.
Bram Moolenaarcdbac1e2005-12-11 21:27:22 +0000929
Bram Moolenaar5b962cf2005-12-12 21:58:40 +0000930
Bram Moolenaar4b570182019-10-20 19:53:22 +02009311.11 MAPPING IN modifyOtherKeys mode *modifyOtherKeys*
932
933Xterm and a few other terminals can be put in a mode where keys with modifiers
934are sent with a special escape code. Vim recognizes these codes and can then
935make a difference between CTRL-H and Backspace, even when Backspace sends the
936character 8. And many more special keys.
937
938For xterm modifyOtherKeys is enabled in the builtin termcap entry. If this is
939not used you can enable modifyOtherKeys with these lines in your vimrc: >
940 let &t_TI = "\<Esc>[>4;2m"
941 let &t_TE = "\<Esc>[>4;m"
942
943In case the modifyOtherKeys mode causes problems you can disable it: >
944 let &t_TI = ""
945 let &t_TE = ""
946It does not take effect immediately. To have this work without restarting Vim
Bram Moolenaar5ef1c6a2019-11-10 22:09:11 +0100947execute a shell command, e.g.: `!ls` Or put the lines in your |vimrc|.
948
949When modifyOtherKeys is enabled you can map <C-[> and <C-S-{>: >
950 imap <C-[> [[[
Bram Moolenaar9a033d72020-10-07 17:29:48 +0200951 imap <C-{> {{{
952Without modifyOtherKeys <C-[> and <C-{> are indistinguishable from Esc.
953Note that <C-{> is used and not <C-S-[> or <C-S-{>. This works on most
954keyboards. Similarly, <C-}> is used instead of <C-S-]> or <C-S-}> and
955<C-|> instead of <C-S-\> or <C-S-|>. Note that '|' has a special meaning in a
956mapping, see |map-bar|.
957
958WARNING: if you map <C-[> you may very well break any key codes that start
959with Esc. Make sure it comes AFTER other mappings.
Bram Moolenaar4b570182019-10-20 19:53:22 +0200960
Bram Moolenaar2547aa92020-07-26 17:00:44 +0200961A known side effect is that in Insert mode the raw escape sequence is inserted
962after the CTRL-V key. This can be used to check whether modifyOtherKeys is
963enabled: In Insert mode type CTRL-SHIFT-V CTRL-V, if you get one byte then
964modifyOtherKeys is off, if you get <1b>27;5;118~ then it is on.
Bram Moolenaar4b570182019-10-20 19:53:22 +0200965
Bram Moolenaar5ef1c6a2019-11-10 22:09:11 +0100966When the 'esckeys' option is off, then modifyOtherKeys will be disabled in
967Insert mode to avoid every key with a modifier causing Insert mode to end.
968
Bram Moolenaar4b570182019-10-20 19:53:22 +0200969
9701.12 MAPPING AN OPERATOR *:map-operator*
Bram Moolenaar5b962cf2005-12-12 21:58:40 +0000971
972An operator is used before a {motion} command. To define your own operator
Bram Moolenaar1b884a02020-12-10 21:11:27 +0100973you must create a mapping that first sets the 'operatorfunc' option and then
Bram Moolenaar5b962cf2005-12-12 21:58:40 +0000974invoke the |g@| operator. After the user types the {motion} command the
975specified function will be called.
976
Bram Moolenaara40ceaf2006-01-13 22:35:40 +0000977 *g@* *E774* *E775*
Bram Moolenaar5b962cf2005-12-12 21:58:40 +0000978g@{motion} Call the function set by the 'operatorfunc' option.
979 The '[ mark is positioned at the start of the text
980 moved over by {motion}, the '] mark on the last
981 character of the text.
982 The function is called with one String argument:
983 "line" {motion} was |linewise|
984 "char" {motion} was |characterwise|
Bram Moolenaarf91787c2010-07-17 12:47:16 +0200985 "block" {motion} was |blockwise-visual|
Bram Moolenaarfa3b7232021-12-24 13:18:38 +0000986 The type can be forced, see |forced-motion|.
Bram Moolenaardb84e452010-08-15 13:50:43 +0200987 {not available when compiled without the |+eval|
Bram Moolenaar5b962cf2005-12-12 21:58:40 +0000988 feature}
989
990Here is an example that counts the number of spaces with <F4>: >
991
Bram Moolenaar1c6737b2020-09-07 22:18:52 +0200992 nnoremap <expr> <F4> CountSpaces()
993 xnoremap <expr> <F4> CountSpaces()
994 " doubling <F4> works on a line
995 nnoremap <expr> <F4><F4> CountSpaces() .. '_'
Bram Moolenaar5b962cf2005-12-12 21:58:40 +0000996
Bram Moolenaarfa3b7232021-12-24 13:18:38 +0000997 function CountSpaces(context = {}, type = '') abort
Bram Moolenaar1c6737b2020-09-07 22:18:52 +0200998 if a:type == ''
Bram Moolenaarfa3b7232021-12-24 13:18:38 +0000999 let context = #{
1000 \ dot_command: v:false,
1001 \ extend_block: '',
1002 \ virtualedit: [&l:virtualedit, &g:virtualedit],
1003 \ }
1004 let &operatorfunc = function('CountSpaces', [context])
Bram Moolenaar0e6adf82021-12-16 14:41:10 +00001005 set virtualedit=block
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02001006 return 'g@'
Bram Moolenaar0e6adf82021-12-16 14:41:10 +00001007 endif
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02001008
Bram Moolenaarfa3b7232021-12-24 13:18:38 +00001009 let save = #{
1010 \ clipboard: &clipboard,
1011 \ selection: &selection,
1012 \ virtualedit: [&l:virtualedit, &g:virtualedit],
1013 \ register: getreginfo('"'),
1014 \ visual_marks: [getpos("'<"), getpos("'>")],
1015 \ }
Bram Moolenaar5b962cf2005-12-12 21:58:40 +00001016
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02001017 try
Bram Moolenaar0e6adf82021-12-16 14:41:10 +00001018 set clipboard= selection=inclusive virtualedit=
Bram Moolenaarfa3b7232021-12-24 13:18:38 +00001019 let commands = #{
1020 \ line: "'[V']",
1021 \ char: "`[v`]",
1022 \ block: "`[\<C-V>`]",
1023 \ }[a:type]
1024 let [_, _, col, off] = getpos("']")
1025 if off != 0
1026 let vcol = getline("'[")->strpart(0, col + off)->strdisplaywidth()
1027 if vcol >= [line("'["), '$']->virtcol() - 1
1028 let a:context.extend_block = '$'
1029 else
1030 let a:context.extend_block = vcol .. '|'
1031 endif
1032 endif
1033 if a:context.extend_block != ''
1034 let commands ..= 'oO' .. a:context.extend_block
Bram Moolenaar0e6adf82021-12-16 14:41:10 +00001035 endif
1036 let commands ..= 'y'
1037 execute 'silent noautocmd keepjumps normal! ' .. commands
1038 echomsg getreg('"')->count(' ')
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02001039 finally
Bram Moolenaarfa3b7232021-12-24 13:18:38 +00001040 call setreg('"', save.register)
1041 call setpos("'<", save.visual_marks[0])
1042 call setpos("'>", save.visual_marks[1])
1043 let &clipboard = save.clipboard
1044 let &selection = save.selection
1045 let [&l:virtualedit, &g:virtualedit] = get(a:context.dot_command ? save : a:context, 'virtualedit')
1046 let a:context.dot_command = v:true
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02001047 endtry
Bram Moolenaar5b962cf2005-12-12 21:58:40 +00001048 endfunction
1049
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02001050An <expr> mapping is used to be able to fetch any prefixed count and register.
1051This also avoids using a command line, which would trigger CmdlineEnter and
1052CmdlineLeave autocommands.
1053
Bram Moolenaar5b962cf2005-12-12 21:58:40 +00001054Note that the 'selection' option is temporarily set to "inclusive" to be able
1055to yank exactly the right text by using Visual mode from the '[ to the ']
1056mark.
1057
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02001058Also note that the 'clipboard' option is temporarily emptied to avoid
1059clobbering the `"*` or `"+` registers, if its value contains the item `unnamed`
1060or `unnamedplus`.
Bram Moolenaar5b962cf2005-12-12 21:58:40 +00001061
Bram Moolenaar079ba762021-10-23 12:08:41 +01001062The `mode()` function will return the state as it will be after applying the
1063operator.
1064
Yegappan Lakshmanan777175b2021-11-18 22:08:57 +00001065Here is an example for using a lambda function to create a normal-mode
1066operator to add quotes around text in the current line: >
1067
1068 nnoremap <F4> <Cmd>let &opfunc='{t ->
1069 \ getline(".")
1070 \ ->split("\\zs")
1071 \ ->insert("\"", col("'']"))
1072 \ ->insert("\"", col("''[") - 1)
1073 \ ->join("")
1074 \ ->setline(".")}'<CR>g@
1075
Bram Moolenaar071d4272004-06-13 20:20:40 +00001076==============================================================================
10772. Abbreviations *abbreviations* *Abbreviations*
1078
1079Abbreviations are used in Insert mode, Replace mode and Command-line mode.
1080If you enter a word that is an abbreviation, it is replaced with the word it
1081stands for. This can be used to save typing for often used long words. And
1082you can use it to automatically correct obvious spelling errors.
1083Examples:
1084
Bram Moolenaarc1762cc2007-05-10 16:56:30 +00001085 :iab ms Microsoft
Bram Moolenaar071d4272004-06-13 20:20:40 +00001086 :iab tihs this
1087
1088There are three types of abbreviations:
1089
1090full-id The "full-id" type consists entirely of keyword characters (letters
1091 and characters from 'iskeyword' option). This is the most common
1092 abbreviation.
1093
1094 Examples: "foo", "g3", "-1"
1095
1096end-id The "end-id" type ends in a keyword character, but all the other
1097 characters are not keyword characters.
1098
1099 Examples: "#i", "..f", "$/7"
1100
1101non-id The "non-id" type ends in a non-keyword character, the other
Bram Moolenaar34162142007-05-12 13:12:19 +00001102 characters may be of any type, excluding space and tab. {this type
Bram Moolenaar071d4272004-06-13 20:20:40 +00001103 is not supported by Vi}
1104
1105 Examples: "def#", "4/7$"
1106
1107Examples of strings that cannot be abbreviations: "a.b", "#def", "a b", "_$r"
1108
1109An abbreviation is only recognized when you type a non-keyword character.
1110This can also be the <Esc> that ends insert mode or the <CR> that ends a
1111command. The non-keyword character which ends the abbreviation is inserted
1112after the expanded abbreviation. An exception to this is the character <C-]>,
1113which is used to expand an abbreviation without inserting any extra
1114characters.
1115
1116Example: >
1117 :ab hh hello
1118< "hh<Space>" is expanded to "hello<Space>"
1119 "hh<C-]>" is expanded to "hello"
1120
1121The characters before the cursor must match the abbreviation. Each type has
1122an additional rule:
1123
1124full-id In front of the match is a non-keyword character, or this is where
1125 the line or insertion starts. Exception: When the abbreviation is
1126 only one character, it is not recognized if there is a non-keyword
Bram Moolenaareb3dc872018-05-13 22:34:24 +02001127 character in front of it, other than a space or a tab. However, for
1128 the command line "'<,'>" (or any other marks) is ignored, as if the
1129 command line starts after it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001130
Bram Moolenaar34162142007-05-12 13:12:19 +00001131end-id In front of the match is a keyword character, or a space or a tab,
Bram Moolenaar071d4272004-06-13 20:20:40 +00001132 or this is where the line or insertion starts.
1133
Bram Moolenaar34162142007-05-12 13:12:19 +00001134non-id In front of the match is a space, tab or the start of the line or
Bram Moolenaar071d4272004-06-13 20:20:40 +00001135 the insertion.
1136
1137Examples: ({CURSOR} is where you type a non-keyword character) >
1138 :ab foo four old otters
1139< " foo{CURSOR}" is expanded to " four old otters"
1140 " foobar{CURSOR}" is not expanded
1141 "barfoo{CURSOR}" is not expanded
1142>
1143 :ab #i #include
1144< "#i{CURSOR}" is expanded to "#include"
1145 ">#i{CURSOR}" is not expanded
1146>
Bram Moolenaar81695252004-12-29 20:58:21 +00001147 :ab ;; <endofline>
Bram Moolenaar071d4272004-06-13 20:20:40 +00001148< "test;;" is not expanded
1149 "test ;;" is expanded to "test <endofline>"
1150
Bram Moolenaar7d76c802014-10-15 22:51:52 +02001151To avoid the abbreviation in Insert mode: Type CTRL-V before the character
1152that would trigger the abbreviation. E.g. CTRL-V <Space>. Or type part of
1153the abbreviation, exit insert mode with <Esc>, re-enter insert mode with "a"
1154and type the rest.
1155
Bram Moolenaar071d4272004-06-13 20:20:40 +00001156To avoid the abbreviation in Command-line mode: Type CTRL-V twice somewhere in
1157the abbreviation to avoid it to be replaced. A CTRL-V in front of a normal
1158character is mostly ignored otherwise.
1159
1160It is possible to move the cursor after an abbreviation: >
1161 :iab if if ()<Left>
1162This does not work if 'cpoptions' includes the '<' flag. |<>|
1163
1164You can even do more complicated things. For example, to consume the space
1165typed after an abbreviation: >
1166 func Eatchar(pat)
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001167 let c = nr2char(getchar(0))
Bram Moolenaar071d4272004-06-13 20:20:40 +00001168 return (c =~ a:pat) ? '' : c
1169 endfunc
1170 iabbr <silent> if if ()<Left><C-R>=Eatchar('\s')<CR>
1171
1172There are no default abbreviations.
1173
1174Abbreviations are never recursive. You can use ":ab f f-o-o" without any
1175problem. But abbreviations can be mapped. {some versions of Vi support
1176recursive abbreviations, for no apparent reason}
1177
1178Abbreviations are disabled if the 'paste' option is on.
1179
1180 *:abbreviate-local* *:abbreviate-<buffer>*
1181Just like mappings, abbreviations can be local to a buffer. This is mostly
1182used in a |filetype-plugin| file. Example for a C plugin file: >
1183 :abb <buffer> FF for (i = 0; i < ; ++i)
1184<
1185 *:ab* *:abbreviate*
1186:ab[breviate] list all abbreviations. The character in the first
1187 column indicates the mode where the abbreviation is
1188 used: 'i' for insert mode, 'c' for Command-line
1189 mode, '!' for both. These are the same as for
1190 mappings, see |map-listing|.
1191
Bram Moolenaare344bea2005-09-01 20:46:49 +00001192 *:abbreviate-verbose*
1193When 'verbose' is non-zero, listing an abbreviation will also display where it
1194was last defined. Example: >
1195
1196 :verbose abbreviate
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001197 ! teh the
Bram Moolenaare344bea2005-09-01 20:46:49 +00001198 Last set from /home/abcd/vim/abbr.vim
1199
1200See |:verbose-cmd| for more information.
1201
Bram Moolenaar071d4272004-06-13 20:20:40 +00001202:ab[breviate] {lhs} list the abbreviations that start with {lhs}
1203 You may need to insert a CTRL-V (type it twice) to
1204 avoid that a typed {lhs} is expanded, since
1205 command-line abbreviations apply here.
1206
Bram Moolenaar251e1912011-06-19 05:09:16 +02001207:ab[breviate] [<expr>] [<buffer>] {lhs} {rhs}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001208 add abbreviation for {lhs} to {rhs}. If {lhs} already
1209 existed it is replaced with the new {rhs}. {rhs} may
1210 contain spaces.
Bram Moolenaarfc1421e2006-04-20 22:17:20 +00001211 See |:map-<expr>| for the optional <expr> argument.
Bram Moolenaar251e1912011-06-19 05:09:16 +02001212 See |:map-<buffer>| for the optional <buffer> argument.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001213
1214 *:una* *:unabbreviate*
Bram Moolenaar95a9dd12019-12-19 22:12:03 +01001215:una[bbreviate] [<buffer>] {lhs}
1216 Remove abbreviation for {lhs} from the list. If none
Bram Moolenaar071d4272004-06-13 20:20:40 +00001217 is found, remove abbreviations in which {lhs} matches
1218 with the {rhs}. This is done so that you can even
1219 remove abbreviations after expansion. To avoid
1220 expansion insert a CTRL-V (type it twice).
1221
1222 *:norea* *:noreabbrev*
Bram Moolenaar251e1912011-06-19 05:09:16 +02001223:norea[bbrev] [<expr>] [<buffer>] [lhs] [rhs]
Bram Moolenaar25c9c682019-05-05 18:13:34 +02001224 Same as ":ab", but no remapping for this {rhs}.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001225
Bram Moolenaar61da1bf2019-06-06 12:14:49 +02001226 *:ca* *:cab* *:cabbrev*
Bram Moolenaar251e1912011-06-19 05:09:16 +02001227:ca[bbrev] [<expr>] [<buffer>] [lhs] [rhs]
Bram Moolenaar25c9c682019-05-05 18:13:34 +02001228 Same as ":ab", but for Command-line mode only.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001229
1230 *:cuna* *:cunabbrev*
Bram Moolenaar95a9dd12019-12-19 22:12:03 +01001231:cuna[bbrev] [<buffer>] {lhs}
1232 Same as ":una", but for Command-line mode only.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001233
1234 *:cnorea* *:cnoreabbrev*
Bram Moolenaar251e1912011-06-19 05:09:16 +02001235:cnorea[bbrev] [<expr>] [<buffer>] [lhs] [rhs]
Bram Moolenaar071d4272004-06-13 20:20:40 +00001236 same as ":ab", but for Command-line mode only and no
Bram Moolenaar25c9c682019-05-05 18:13:34 +02001237 remapping for this {rhs}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001238
1239 *:ia* *:iabbrev*
Bram Moolenaar251e1912011-06-19 05:09:16 +02001240:ia[bbrev] [<expr>] [<buffer>] [lhs] [rhs]
Bram Moolenaar25c9c682019-05-05 18:13:34 +02001241 Same as ":ab", but for Insert mode only.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001242
1243 *:iuna* *:iunabbrev*
Bram Moolenaar95a9dd12019-12-19 22:12:03 +01001244:iuna[bbrev] [<buffer>] {lhs}
1245 Same as ":una", but for insert mode only.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001246
1247 *:inorea* *:inoreabbrev*
Bram Moolenaar251e1912011-06-19 05:09:16 +02001248:inorea[bbrev] [<expr>] [<buffer>] [lhs] [rhs]
Bram Moolenaar25c9c682019-05-05 18:13:34 +02001249 Same as ":ab", but for Insert mode only and no
1250 remapping for this {rhs}.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001251
1252 *:abc* *:abclear*
Bram Moolenaar25c9c682019-05-05 18:13:34 +02001253:abc[lear] [<buffer>] Remove all abbreviations.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001254
1255 *:iabc* *:iabclear*
Bram Moolenaar25c9c682019-05-05 18:13:34 +02001256:iabc[lear] [<buffer>] Remove all abbreviations for Insert mode.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001257
1258 *:cabc* *:cabclear*
Bram Moolenaar25c9c682019-05-05 18:13:34 +02001259:cabc[lear] [<buffer>] Remove all abbreviations for Command-line mode.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001260
1261 *using_CTRL-V*
1262It is possible to use special characters in the rhs of an abbreviation.
1263CTRL-V has to be used to avoid the special meaning of most non printable
1264characters. How many CTRL-Vs need to be typed depends on how you enter the
1265abbreviation. This also applies to mappings. Let's use an example here.
1266
1267Suppose you want to abbreviate "esc" to enter an <Esc> character. When you
1268type the ":ab" command in Vim, you have to enter this: (here ^V is a CTRL-V
1269and ^[ is <Esc>)
1270
1271You type: ab esc ^V^V^V^V^V^[
1272
1273 All keyboard input is subjected to ^V quote interpretation, so
1274 the first, third, and fifth ^V characters simply allow the second,
1275 and fourth ^Vs, and the ^[, to be entered into the command-line.
1276
1277You see: ab esc ^V^V^[
1278
1279 The command-line contains two actual ^Vs before the ^[. This is
1280 how it should appear in your .exrc file, if you choose to go that
1281 route. The first ^V is there to quote the second ^V; the :ab
1282 command uses ^V as its own quote character, so you can include quoted
Bram Moolenaar81695252004-12-29 20:58:21 +00001283 whitespace or the | character in the abbreviation. The :ab command
Bram Moolenaar071d4272004-06-13 20:20:40 +00001284 doesn't do anything special with the ^[ character, so it doesn't need
1285 to be quoted. (Although quoting isn't harmful; that's why typing 7
1286 [but not 8!] ^Vs works.)
1287
1288Stored as: esc ^V^[
1289
1290 After parsing, the abbreviation's short form ("esc") and long form
1291 (the two characters "^V^[") are stored in the abbreviation table.
1292 If you give the :ab command with no arguments, this is how the
1293 abbreviation will be displayed.
1294
1295 Later, when the abbreviation is expanded because the user typed in
1296 the word "esc", the long form is subjected to the same type of
1297 ^V interpretation as keyboard input. So the ^V protects the ^[
Bram Moolenaar81695252004-12-29 20:58:21 +00001298 character from being interpreted as the "exit Insert mode" character.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001299 Instead, the ^[ is inserted into the text.
1300
1301Expands to: ^[
1302
1303[example given by Steve Kirkendall]
1304
1305==============================================================================
13063. Local mappings and functions *script-local*
1307
1308When using several Vim script files, there is the danger that mappings and
1309functions used in one script use the same name as in other scripts. To avoid
1310this, they can be made local to the script.
1311
1312 *<SID>* *<SNR>* *E81*
1313The string "<SID>" can be used in a mapping or menu. This requires that the
1314'<' flag is not present in 'cpoptions'.
1315 When executing the map command, Vim will replace "<SID>" with the special
1316key code <SNR>, followed by a number that's unique for the script, and an
1317underscore. Example: >
1318 :map <SID>Add
1319could define a mapping "<SNR>23_Add".
1320
1321When defining a function in a script, "s:" can be prepended to the name to
1322make it local to the script. But when a mapping is executed from outside of
1323the script, it doesn't know in which script the function was defined. To
1324avoid this problem, use "<SID>" instead of "s:". The same translation is done
1325as for mappings. This makes it possible to define a call to the function in
Bram Moolenaar81695252004-12-29 20:58:21 +00001326a mapping.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001327
1328When a local function is executed, it runs in the context of the script it was
1329defined in. This means that new functions and mappings it defines can also
1330use "s:" or "<SID>" and it will use the same unique number as when the
1331function itself was defined. Also, the "s:var" local script variables can be
1332used.
1333
1334When executing an autocommand or a user command, it will run in the context of
1335the script it was defined in. This makes it possible that the command calls a
1336local function or uses a local mapping.
1337
Bram Moolenaar90944302020-08-01 20:45:11 +02001338In case the value is used in a context where <SID> cannot be correctly
1339expanded, use the expand() function: >
1340 let &includexpr = expand('<SID>') .. 'My_includeexpr()'
1341
Bram Moolenaar071d4272004-06-13 20:20:40 +00001342Otherwise, using "<SID>" outside of a script context is an error.
1343
1344If you need to get the script number to use in a complicated script, you can
Bram Moolenaar4770d092006-01-12 23:22:24 +00001345use this function: >
Bram Moolenaar4466ad62020-11-21 13:16:30 +01001346 func s:ScriptNumber()
1347 return matchstr(expand('<SID>'), '<SNR>\zs\d\+\ze_')
1348 endfunc
Bram Moolenaar071d4272004-06-13 20:20:40 +00001349
1350The "<SNR>" will be shown when listing functions and mappings. This is useful
1351to find out what they are defined to.
1352
1353The |:scriptnames| command can be used to see which scripts have been sourced
1354and what their <SNR> number is.
1355
Bram Moolenaar25c9c682019-05-05 18:13:34 +02001356This is all {not available when compiled without the |+eval| feature}.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001357
1358==============================================================================
13594. User-defined commands *user-commands*
1360
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001361It is possible to define your own Ex commands. A user-defined command can act
Bram Moolenaar071d4272004-06-13 20:20:40 +00001362just like a built-in command (it can have a range or arguments, arguments can
1363be completed as filenames or buffer names, etc), except that when the command
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001364is executed, it is transformed into a normal Ex command and then executed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001365
1366For starters: See section |40.2| in the user manual.
1367
Bram Moolenaar166af9b2010-11-16 20:34:40 +01001368 *E183* *E841* *user-cmd-ambiguous*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001369All user defined commands must start with an uppercase letter, to avoid
Bram Moolenaar166af9b2010-11-16 20:34:40 +01001370confusion with builtin commands. Exceptions are these builtin commands:
1371 :Next
1372 :X
1373They cannot be used for a user defined command. ":Print" is also an existing
1374command, but it is deprecated and can be overruled.
1375
1376The other characters of the user command can be uppercase letters, lowercase
1377letters or digits. When using digits, note that other commands that take a
1378numeric argument may become ambiguous. For example, the command ":Cc2" could
1379be the user command ":Cc2" without an argument, or the command ":Cc" with
1380argument "2". It is advised to put a space between the command name and the
1381argument to avoid these problems.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001382
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001383When using a user-defined command, the command can be abbreviated. However, if
1384an abbreviation is not unique, an error will be issued. Furthermore, a
Bram Moolenaar071d4272004-06-13 20:20:40 +00001385built-in command will always take precedence.
1386
1387Example: >
1388 :command Rename ...
1389 :command Renumber ...
1390 :Rena " Means "Rename"
1391 :Renu " Means "Renumber"
1392 :Ren " Error - ambiguous
1393 :command Paste ...
1394 :P " The built-in :Print
1395
1396It is recommended that full names for user-defined commands are used in
1397scripts.
1398
1399:com[mand] *:com* *:command*
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001400 List all user-defined commands. When listing commands,
Bram Moolenaara561a412019-04-25 21:27:58 +02001401 the characters in the first columns are:
Bram Moolenaar071d4272004-06-13 20:20:40 +00001402 ! Command has the -bang attribute
1403 " Command has the -register attribute
Bram Moolenaara561a412019-04-25 21:27:58 +02001404 | Command has the -bar attribute
Bram Moolenaar071d4272004-06-13 20:20:40 +00001405 b Command is local to current buffer
1406 (see below for details on attributes)
Bram Moolenaar818078d2016-08-27 21:58:42 +02001407 The list can be filtered on command name with
1408 |:filter|, e.g., to list all commands with "Pyth" in
1409 the name: >
1410 filter Pyth command
Bram Moolenaar071d4272004-06-13 20:20:40 +00001411
1412:com[mand] {cmd} List the user-defined commands that start with {cmd}
1413
Bram Moolenaar5b8d8fd2005-08-16 23:01:50 +00001414 *:command-verbose*
1415When 'verbose' is non-zero, listing a command will also display where it was
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00001416last defined and any completion argument. Example: >
Bram Moolenaar5b8d8fd2005-08-16 23:01:50 +00001417
1418 :verbose command TOhtml
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001419< Name Args Range Complete Definition ~
1420 TOhtml 0 % :call Convert2HTML(<line1>, <line2>) ~
1421 Last set from /usr/share/vim/vim-7.0/plugin/tohtml.vim ~
1422
Bram Moolenaar5195e452005-08-19 20:32:47 +00001423See |:verbose-cmd| for more information.
Bram Moolenaar5b8d8fd2005-08-16 23:01:50 +00001424
Bram Moolenaar071d4272004-06-13 20:20:40 +00001425 *E174* *E182*
Bram Moolenaar1b884a02020-12-10 21:11:27 +01001426:com[mand][!] [{attr}...] {cmd} {repl}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001427 Define a user command. The name of the command is
Bram Moolenaar1b884a02020-12-10 21:11:27 +01001428 {cmd} and its replacement text is {repl}. The
1429 command's attributes (see below) are {attr}. If the
1430 command already exists, an error is reported, unless a
1431 ! is specified, in which case the command is
1432 redefined. There is one exception: When sourcing a
1433 script again, a command that was previously defined in
1434 that script will be silently replaced.
Bram Moolenaar55d46912018-12-08 16:03:28 +01001435
Bram Moolenaar071d4272004-06-13 20:20:40 +00001436
1437:delc[ommand] {cmd} *:delc* *:delcommand* *E184*
1438 Delete the user-defined command {cmd}.
1439
Bram Moolenaarbdcba242021-09-12 20:58:02 +02001440:delc[ommand] -buffer {cmd} *E1237*
1441 Delete the user-defined command {cmd} that was defined
1442 for the current buffer.
1443
Bram Moolenaar071d4272004-06-13 20:20:40 +00001444:comc[lear] *:comc* *:comclear*
1445 Delete all user-defined commands.
1446
Bram Moolenaar55d46912018-12-08 16:03:28 +01001447
1448Command attributes ~
Bram Moolenaar071d4272004-06-13 20:20:40 +00001449
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001450User-defined commands are treated by Vim just like any other Ex commands. They
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001451can have arguments, or have a range specified. Arguments are subject to
1452completion as filenames, buffers, etc. Exactly how this works depends upon the
Bram Moolenaar071d4272004-06-13 20:20:40 +00001453command's attributes, which are specified when the command is defined.
1454
1455There are a number of attributes, split into four categories: argument
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001456handling, completion behavior, range handling, and special cases. The
Bram Moolenaar071d4272004-06-13 20:20:40 +00001457attributes are described below, by category.
1458
Bram Moolenaar071d4272004-06-13 20:20:40 +00001459
Bram Moolenaar55d46912018-12-08 16:03:28 +01001460Argument handling ~
1461 *E175* *E176* *:command-nargs*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001462By default, a user defined command will take no arguments (and an error is
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001463reported if any are supplied). However, it is possible to specify that the
1464command can take arguments, using the -nargs attribute. Valid cases are:
Bram Moolenaar071d4272004-06-13 20:20:40 +00001465
1466 -nargs=0 No arguments are allowed (the default)
Bram Moolenaar9d87a372018-12-18 21:41:50 +01001467 -nargs=1 Exactly one argument is required, it includes spaces
Bram Moolenaar446beb42011-05-10 17:18:44 +02001468 -nargs=* Any number of arguments are allowed (0, 1, or many),
1469 separated by white space
Bram Moolenaar071d4272004-06-13 20:20:40 +00001470 -nargs=? 0 or 1 arguments are allowed
1471 -nargs=+ Arguments must be supplied, but any number are allowed
1472
Bram Moolenaar34162142007-05-12 13:12:19 +00001473Arguments are considered to be separated by (unescaped) spaces or tabs in this
Bram Moolenaar446beb42011-05-10 17:18:44 +02001474context, except when there is one argument, then the white space is part of
1475the argument.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001476
1477Note that arguments are used as text, not as expressions. Specifically,
1478"s:var" will use the script-local variable in the script where the command was
1479defined, not where it is invoked! Example:
1480 script1.vim: >
1481 :let s:error = "None"
1482 :command -nargs=1 Error echoerr <args>
1483< script2.vim: >
1484 :source script1.vim
1485 :let s:error = "Wrong!"
1486 :Error s:error
Bram Moolenaara7241f52008-06-24 20:39:31 +00001487Executing script2.vim will result in "None" being echoed. Not what you
Bram Moolenaar071d4272004-06-13 20:20:40 +00001488intended! Calling a function may be an alternative.
1489
Bram Moolenaar55d46912018-12-08 16:03:28 +01001490
1491Completion behavior ~
Bram Moolenaar9d87a372018-12-18 21:41:50 +01001492 *:command-completion* *E179* *E180* *E181*
Bram Moolenaar55d46912018-12-08 16:03:28 +01001493 *:command-complete*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001494By default, the arguments of user defined commands do not undergo completion.
1495However, by specifying one or the other of the following attributes, argument
1496completion can be enabled:
1497
Bram Moolenaarcd43eff2018-03-29 15:55:38 +02001498 -complete=arglist file names in argument list
Bram Moolenaar071d4272004-06-13 20:20:40 +00001499 -complete=augroup autocmd groups
1500 -complete=buffer buffer names
Bram Moolenaar5ae636b2012-04-30 18:48:53 +02001501 -complete=behave :behave suboptions
Bram Moolenaare9edd7f2011-07-20 16:37:24 +02001502 -complete=color color schemes
Bram Moolenaar071d4272004-06-13 20:20:40 +00001503 -complete=command Ex command (and arguments)
Bram Moolenaare9edd7f2011-07-20 16:37:24 +02001504 -complete=compiler compilers
Bram Moolenaar4a748032010-09-30 21:47:56 +02001505 -complete=cscope |:cscope| suboptions
Bram Moolenaar071d4272004-06-13 20:20:40 +00001506 -complete=dir directory names
1507 -complete=environment environment variable names
1508 -complete=event autocommand events
1509 -complete=expression Vim expression
1510 -complete=file file and directory names
Bram Moolenaare9edd7f2011-07-20 16:37:24 +02001511 -complete=file_in_path file and directory names in |'path'|
Bram Moolenaara26559b2010-07-31 14:59:19 +02001512 -complete=filetype filetype names |'filetype'|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001513 -complete=function function name
1514 -complete=help help subjects
1515 -complete=highlight highlight groups
Bram Moolenaar5ae636b2012-04-30 18:48:53 +02001516 -complete=history :history suboptions
Bram Moolenaare9edd7f2011-07-20 16:37:24 +02001517 -complete=locale locale names (as output of locale -a)
Bram Moolenaarcae92dc2017-08-06 15:22:15 +02001518 -complete=mapclear buffer argument
Bram Moolenaar071d4272004-06-13 20:20:40 +00001519 -complete=mapping mapping name
1520 -complete=menu menus
Bram Moolenaar9e507ca2016-10-15 15:39:39 +02001521 -complete=messages |:messages| suboptions
Bram Moolenaar071d4272004-06-13 20:20:40 +00001522 -complete=option options
Bram Moolenaar063b9d12016-07-09 20:21:48 +02001523 -complete=packadd optional package |pack-add| names
Bram Moolenaara26559b2010-07-31 14:59:19 +02001524 -complete=shellcmd Shell command
Bram Moolenaar4a748032010-09-30 21:47:56 +02001525 -complete=sign |:sign| suboptions
Bram Moolenaara26559b2010-07-31 14:59:19 +02001526 -complete=syntax syntax file names |'syntax'|
Bram Moolenaarcd9c4622013-06-08 15:24:48 +02001527 -complete=syntime |:syntime| suboptions
Bram Moolenaar071d4272004-06-13 20:20:40 +00001528 -complete=tag tags
1529 -complete=tag_listfiles tags, file names are shown when CTRL-D is hit
Bram Moolenaar24305862012-08-15 14:05:05 +02001530 -complete=user user names
Bram Moolenaar071d4272004-06-13 20:20:40 +00001531 -complete=var user variables
1532 -complete=custom,{func} custom completion, defined via {func}
Bram Moolenaara466c992005-07-09 21:03:22 +00001533 -complete=customlist,{func} custom completion, defined via {func}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001534
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00001535If you specify completion while there is nothing to complete (-nargs=0, the
1536default) then you get error *E1208* .
Bram Moolenaar3a991dd2014-10-02 01:41:41 +02001537Note: That some completion methods might expand environment variables.
1538
Bram Moolenaara5792f52005-11-23 21:25:05 +00001539
Bram Moolenaar55d46912018-12-08 16:03:28 +01001540Custom completion ~
1541 *:command-completion-custom*
1542 *:command-completion-customlist* *E467* *E468*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001543It is possible to define customized completion schemes via the "custom,{func}"
Bram Moolenaara466c992005-07-09 21:03:22 +00001544or the "customlist,{func}" completion argument. The {func} part should be a
Bram Moolenaara7241f52008-06-24 20:39:31 +00001545function with the following signature: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001546
1547 :function {func}(ArgLead, CmdLine, CursorPos)
1548
Bram Moolenaara466c992005-07-09 21:03:22 +00001549The function need not use all these arguments. The function should provide the
1550completion candidates as the return value.
1551
1552For the "custom" argument, the function should return the completion
1553candidates one per line in a newline separated string.
1554
1555For the "customlist" argument, the function should return the completion
Bram Moolenaara5792f52005-11-23 21:25:05 +00001556candidates as a Vim List. Non-string items in the list are ignored.
Bram Moolenaara466c992005-07-09 21:03:22 +00001557
1558The function arguments are:
Bram Moolenaar071d4272004-06-13 20:20:40 +00001559 ArgLead the leading portion of the argument currently being
1560 completed on
1561 CmdLine the entire command line
Bram Moolenaara5792f52005-11-23 21:25:05 +00001562 CursorPos the cursor position in it (byte index)
Bram Moolenaara466c992005-07-09 21:03:22 +00001563The function may use these for determining context. For the "custom"
1564argument, it is not necessary to filter candidates against the (implicit
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001565pattern in) ArgLead. Vim will filter the candidates with its regexp engine
Bram Moolenaara466c992005-07-09 21:03:22 +00001566after function return, and this is probably more efficient in most cases. For
1567the "customlist" argument, Vim will not filter the returned completion
1568candidates and the user supplied function should filter the candidates.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001569
1570The following example lists user names to a Finger command >
1571 :com -complete=custom,ListUsers -nargs=1 Finger !finger <args>
1572 :fun ListUsers(A,L,P)
1573 : return system("cut -d: -f1 /etc/passwd")
1574 :endfun
1575
Bram Moolenaara466c992005-07-09 21:03:22 +00001576The following example completes filenames from the directories specified in
1577the 'path' option: >
1578 :com -nargs=1 -bang -complete=customlist,EditFileComplete
1579 \ EditFile edit<bang> <args>
1580 :fun EditFileComplete(A,L,P)
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001581 : return split(globpath(&path, a:A), "\n")
Bram Moolenaara466c992005-07-09 21:03:22 +00001582 :endfun
1583<
Bram Moolenaar5ac3b1a2010-07-27 22:50:36 +02001584This example does not work for file names with spaces!
1585
Bram Moolenaara5792f52005-11-23 21:25:05 +00001586
Bram Moolenaar55d46912018-12-08 16:03:28 +01001587Range handling ~
1588 *E177* *E178* *:command-range* *:command-count*
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001589By default, user-defined commands do not accept a line number range. However,
Bram Moolenaar071d4272004-06-13 20:20:40 +00001590it is possible to specify that the command does take a range (the -range
1591attribute), or that it takes an arbitrary count value, either in the line
1592number position (-range=N, like the |:split| command) or as a "count"
Bram Moolenaar5c5b0942007-05-06 12:07:59 +00001593argument (-count=N, like the |:Next| command). The count will then be
1594available in the argument with |<count>|.
1595
1596Possible attributes are:
Bram Moolenaar071d4272004-06-13 20:20:40 +00001597
1598 -range Range allowed, default is current line
1599 -range=% Range allowed, default is whole file (1,$)
1600 -range=N A count (default N) which is specified in the line
Bram Moolenaar8e5af3e2011-04-28 19:02:44 +02001601 number position (like |:split|); allows for zero line
1602 number.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001603 -count=N A count (default N) which is specified either in the line
Bram Moolenaar32e7b2d2005-02-27 22:36:47 +00001604 number position, or as an initial argument (like |:Next|).
Bram Moolenaar25c9c682019-05-05 18:13:34 +02001605 -count acts like -count=0
Bram Moolenaar071d4272004-06-13 20:20:40 +00001606
1607Note that -range=N and -count=N are mutually exclusive - only one should be
1608specified.
1609
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02001610 *:command-addr*
Bram Moolenaarf1d6ccf2014-12-08 04:16:44 +01001611It is possible that the special characters in the range like ., $ or % which
1612by default correspond to the current line, last line and the whole buffer,
1613relate to arguments, (loaded) buffers, windows or tab pages.
1614
Bram Moolenaara561a412019-04-25 21:27:58 +02001615Possible values are (second column is the short name used in listing):
Bram Moolenaar25c9c682019-05-05 18:13:34 +02001616 -addr=lines Range of lines (this is the default for -range)
Bram Moolenaara561a412019-04-25 21:27:58 +02001617 -addr=arguments arg Range for arguments
1618 -addr=buffers buf Range for buffers (also not loaded buffers)
1619 -addr=loaded_buffers load Range for loaded buffers
1620 -addr=windows win Range for windows
1621 -addr=tabs tab Range for tab pages
1622 -addr=quickfix qf Range for quickfix entries
Bram Moolenaar25c9c682019-05-05 18:13:34 +02001623 -addr=other ? other kind of range; can use ".", "$" and "%"
1624 as with "lines" (this is the default for
1625 -count)
Bram Moolenaarf1d6ccf2014-12-08 04:16:44 +01001626
Bram Moolenaar55d46912018-12-08 16:03:28 +01001627
1628Special cases ~
1629 *:command-bang* *:command-bar*
Bram Moolenaar5c5b0942007-05-06 12:07:59 +00001630 *:command-register* *:command-buffer*
Bram Moolenaar519cc552021-11-16 19:18:26 +00001631 *:command-keepscript*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001632There are some special cases as well:
1633
1634 -bang The command can take a ! modifier (like :q or :w)
1635 -bar The command can be followed by a "|" and another command.
1636 A "|" inside the command argument is not allowed then.
1637 Also checks for a " to start a comment.
1638 -register The first argument to the command can be an optional
1639 register name (like :del, :put, :yank).
1640 -buffer The command will only be available in the current buffer.
Bram Moolenaar58ef8a32021-11-12 11:25:11 +00001641 -keepscript Do not use the location of where the user command was
1642 defined for verbose messages, use the location of where
1643 the user command was invoked.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001644
1645In the cases of the -count and -register attributes, if the optional argument
1646is supplied, it is removed from the argument list and is available to the
1647replacement text separately.
Bram Moolenaar7cba6c02013-09-05 22:13:31 +02001648Note that these arguments can be abbreviated, but that is a deprecated
1649feature. Use the full name for new scripts.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001650
Bram Moolenaar55d46912018-12-08 16:03:28 +01001651
1652Replacement text ~
Bram Moolenaar73b8b0a2021-08-01 14:52:32 +02001653 *:command-repl*
Bram Moolenaar5d7c2df2021-07-27 21:17:32 +02001654The {repl} argument is normally one long string, possibly with "|" separated
1655commands. A special case is when the argument is "{", then the following
1656lines, up to a line starting with "}" are used and |Vim9| syntax applies.
1657Example: >
1658 :command MyCommand {
1659 echo 'hello'
1660 g:calledMyCommand = true
1661 }
Bram Moolenaar63b91732021-08-05 20:40:03 +02001662< *E1231*
1663There must be white space before the "{". No nesting is supported, inline
1664functions cannot be used. Commands where a "|" may appear in the argument,
1665such as commands with an expression argument, cannot be followed by a "|" and
1666another command.
Bram Moolenaar5d7c2df2021-07-27 21:17:32 +02001667
Bram Moolenaar1b884a02020-12-10 21:11:27 +01001668The replacement text {repl} for a user defined command is scanned for special
1669escape sequences, using <...> notation. Escape sequences are replaced with
1670values from the entered command line, and all other text is copied unchanged.
1671The resulting string is executed as an Ex command. To avoid the replacement
1672use <lt> in place of the initial <. Thus to include "<bang>" literally use
Bram Moolenaar371d5402006-03-20 21:47:49 +00001673"<lt>bang>".
Bram Moolenaar071d4272004-06-13 20:20:40 +00001674
1675The valid escape sequences are
1676
1677 *<line1>*
1678 <line1> The starting line of the command range.
1679 *<line2>*
1680 <line2> The final line of the command range.
Bram Moolenaarc168bd42017-09-10 17:34:35 +02001681 *<range>*
1682 <range> The number of items in the command range: 0, 1 or 2
Bram Moolenaar071d4272004-06-13 20:20:40 +00001683 *<count>*
1684 <count> Any count supplied (as described for the '-range'
1685 and '-count' attributes).
1686 *<bang>*
1687 <bang> (See the '-bang' attribute) Expands to a ! if the
1688 command was executed with a ! modifier, otherwise
1689 expands to nothing.
Bram Moolenaar1d59aa12020-09-19 18:50:13 +02001690 *<mods>* *<q-mods>* *:command-modifiers*
Bram Moolenaar63a60de2016-06-04 22:08:55 +02001691 <mods> The command modifiers, if specified. Otherwise, expands to
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001692 nothing. Supported modifiers are |:aboveleft|, |:belowright|,
1693 |:botright|, |:browse|, |:confirm|, |:hide|, |:keepalt|,
Bram Moolenaarbc8801c2016-08-02 21:04:33 +02001694 |:keepjumps|, |:keepmarks|, |:keeppatterns|, |:leftabove|,
1695 |:lockmarks|, |:noswapfile| |:rightbelow|, |:silent|, |:tab|,
1696 |:topleft|, |:verbose|, and |:vertical|.
1697 Note that these are not yet supported: |:noautocmd|,
1698 |:sandbox| and |:unsilent|.
Bram Moolenaar63a60de2016-06-04 22:08:55 +02001699 Examples: >
1700 command! -nargs=+ -complete=file MyEdit
1701 \ for f in expand(<q-args>, 0, 1) |
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001702 \ exe '<mods> split ' .. f |
Bram Moolenaar63a60de2016-06-04 22:08:55 +02001703 \ endfor
1704
1705 function! SpecialEdit(files, mods)
1706 for f in expand(a:files, 0, 1)
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001707 exe a:mods .. ' split ' .. f
Bram Moolenaar63a60de2016-06-04 22:08:55 +02001708 endfor
1709 endfunction
1710 command! -nargs=+ -complete=file Sedit
1711 \ call SpecialEdit(<q-args>, <q-mods>)
1712<
Bram Moolenaar071d4272004-06-13 20:20:40 +00001713 *<reg>* *<register>*
1714 <reg> (See the '-register' attribute) The optional register,
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001715 if specified. Otherwise, expands to nothing. <register>
Bram Moolenaar071d4272004-06-13 20:20:40 +00001716 is a synonym for this.
1717 *<args>*
1718 <args> The command arguments, exactly as supplied (but as
1719 noted above, any count or register can consume some
1720 of the arguments, which are then not part of <args>).
1721 <lt> A single '<' (Less-Than) character. This is needed if you
1722 want to get a literal copy of one of these escape sequences
1723 into the expansion - for example, to get <bang>, use
1724 <lt>bang>.
1725
1726 *<q-args>*
1727If the first two characters of an escape sequence are "q-" (for example,
1728<q-args>) then the value is quoted in such a way as to make it a valid value
1729for use in an expression. This uses the argument as one single value.
Bram Moolenaar51485f02005-06-04 21:55:20 +00001730When there is no argument <q-args> is an empty string.
Bram Moolenaar552f8a12007-03-08 17:12:08 +00001731 *<f-args>*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001732To allow commands to pass their arguments on to a user-defined function, there
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001733is a special form <f-args> ("function args"). This splits the command
Bram Moolenaar34162142007-05-12 13:12:19 +00001734arguments at spaces and tabs, quotes each argument individually, and the
Bram Moolenaar071d4272004-06-13 20:20:40 +00001735<f-args> sequence is replaced by the comma-separated list of quoted arguments.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001736See the Mycmd example below. If no arguments are given <f-args> is removed.
Bram Moolenaar552f8a12007-03-08 17:12:08 +00001737 To embed whitespace into an argument of <f-args>, prepend a backslash.
1738<f-args> replaces every pair of backslashes (\\) with one backslash. A
1739backslash followed by a character other than white space or a backslash
1740remains unmodified. Overview:
1741
1742 command <f-args> ~
1743 XX ab 'ab'
1744 XX a\b 'a\b'
1745 XX a\ b 'a b'
1746 XX a\ b 'a ', 'b'
1747 XX a\\b 'a\b'
1748 XX a\\ b 'a\', 'b'
1749 XX a\\\b 'a\\b'
1750 XX a\\\ b 'a\ b'
1751 XX a\\\\b 'a\\b'
1752 XX a\\\\ b 'a\\', 'b'
Bram Moolenaar071d4272004-06-13 20:20:40 +00001753
1754Examples >
1755
1756 " Delete everything after here to the end
1757 :com Ddel +,$d
1758
1759 " Rename the current buffer
1760 :com -nargs=1 -bang -complete=file Ren f <args>|w<bang>
1761
1762 " Replace a range with the contents of a file
1763 " (Enter this all as one line)
1764 :com -range -nargs=1 -complete=file
1765 Replace <line1>-pu_|<line1>,<line2>d|r <args>|<line1>d
1766
1767 " Count the number of lines in the range
Bram Moolenaar81695252004-12-29 20:58:21 +00001768 :com! -range -nargs=0 Lines echo <line2> - <line1> + 1 "lines"
Bram Moolenaar071d4272004-06-13 20:20:40 +00001769
1770 " Call a user function (example of <f-args>)
1771 :com -nargs=* Mycmd call Myfunc(<f-args>)
1772
1773When executed as: >
1774 :Mycmd arg1 arg2
1775This will invoke: >
1776 :call Myfunc("arg1","arg2")
1777
1778 :" A more substantial example
1779 :function Allargs(command)
Bram Moolenaara7241f52008-06-24 20:39:31 +00001780 : let i = 0
1781 : while i < argc()
1782 : if filereadable(argv(i))
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001783 : execute "e " .. argv(i)
Bram Moolenaar071d4272004-06-13 20:20:40 +00001784 : execute a:command
1785 : endif
1786 : let i = i + 1
1787 : endwhile
1788 :endfunction
1789 :command -nargs=+ -complete=command Allargs call Allargs(<q-args>)
1790
1791The command Allargs takes any Vim command(s) as argument and executes it on all
1792files in the argument list. Usage example (note use of the "e" flag to ignore
1793errors and the "update" command to write modified buffers): >
1794 :Allargs %s/foo/bar/ge|update
1795This will invoke: >
1796 :call Allargs("%s/foo/bar/ge|update")
1797<
Bram Moolenaar1b884a02020-12-10 21:11:27 +01001798If the command is defined in Vim9 script (a script that starts with
1799`:vim9script` and in a `:def` function) then {repl} will be executed as in Vim9
1800script. Thus this depends on where the command is defined, not where it is
1801used.
1802
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001803When defining a user command in a script, it will be able to call functions
Bram Moolenaar071d4272004-06-13 20:20:40 +00001804local to the script and use mappings local to the script. When the user
1805invokes the user command, it will run in the context of the script it was
1806defined in. This matters if |<SID>| is used in a command.
1807
Bram Moolenaar91f84f62018-07-29 15:07:52 +02001808 vim:tw=78:ts=8:noet:ft=help:norl: