blob: d458aa661a1dd93a279e01995b226686ef4ee4c1 [file] [log] [blame]
Christian Brabandtb4ddc6c2024-01-02 16:51:11 +01001*map.txt* For Vim version 9.1. Last change: 2023 December 31
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 Moolenaar63a2e362022-11-23 20:20:18 +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 Moolenaar4be18e72023-02-03 12:28:07 +000023 1.11 Mapping meta-keys |:map-meta-keys|
24 1.12 Mapping in modifyOtherKeys mode |modifyOtherKeys|
25 1.13 Mapping with Kitty keyboard protocol |kitty-keyboard-protocol|
26 1.14 Mapping an operator |:map-operator|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000272. Abbreviations |abbreviations|
283. Local mappings and functions |script-local|
294. User-defined commands |user-commands|
30
31==============================================================================
321. Key mapping *key-mapping* *mapping* *macro*
33
34Key mapping is used to change the meaning of typed keys. The most common use
Bram Moolenaar24a98a02017-09-27 22:23:55 +020035is to define a sequence of commands for a function key. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +000036
37 :map <F2> a<C-R>=strftime("%c")<CR><Esc>
38
Bram Moolenaar402d2fe2005-04-15 21:00:38 +000039This appends the current date and time after the cursor (in <> notation |<>|).
Bram Moolenaar071d4272004-06-13 20:20:40 +000040
Bram Moolenaar5b962cf2005-12-12 21:58:40 +000041
421.1 MAP COMMANDS *:map-commands*
43
Bram Moolenaar071d4272004-06-13 20:20:40 +000044There are commands to enter new mappings, remove mappings and list mappings.
45See |map-overview| for the various forms of "map" and their relationships with
46modes.
47
48{lhs} means left-hand-side *{lhs}*
49{rhs} means right-hand-side *{rhs}*
50
Bram Moolenaar06b5db92006-02-10 23:11:56 +000051:map {lhs} {rhs} |mapmode-nvo| *:map*
52:nm[ap] {lhs} {rhs} |mapmode-n| *:nm* *:nmap*
53:vm[ap] {lhs} {rhs} |mapmode-v| *:vm* *:vmap*
Bram Moolenaar371d5402006-03-20 21:47:49 +000054:xm[ap] {lhs} {rhs} |mapmode-x| *:xm* *:xmap*
Bram Moolenaar531da592013-05-06 05:58:55 +020055:smap {lhs} {rhs} |mapmode-s| *:smap*
Bram Moolenaar06b5db92006-02-10 23:11:56 +000056:om[ap] {lhs} {rhs} |mapmode-o| *:om* *:omap*
57:map! {lhs} {rhs} |mapmode-ic| *:map!*
58:im[ap] {lhs} {rhs} |mapmode-i| *:im* *:imap*
Bram Moolenaar61da1bf2019-06-06 12:14:49 +020059:lm[ap] {lhs} {rhs} |mapmode-l| *:lm* *:lma* *:lmap*
Bram Moolenaar06b5db92006-02-10 23:11:56 +000060:cm[ap] {lhs} {rhs} |mapmode-c| *:cm* *:cmap*
Bram Moolenaar37c64c72017-09-19 22:06:03 +020061:tma[p] {lhs} {rhs} |mapmode-t| *:tma* *:tmap*
Bram Moolenaar071d4272004-06-13 20:20:40 +000062 Map the key sequence {lhs} to {rhs} for the modes
63 where the map command applies. The result, including
64 {rhs}, is then further scanned for mappings. This
65 allows for nested and recursive use of mappings.
Bram Moolenaar519cc552021-11-16 19:18:26 +000066 Note: Trailing spaces are included in the {rhs},
67 because space is a valid Normal mode command.
Bram Moolenaarcfa8f9a2022-06-03 21:59:47 +010068 See |map-trailing-white|.
Bram Moolenaar071d4272004-06-13 20:20:40 +000069
Bram Moolenaar822ff862014-06-12 21:46:14 +020070 *:nore* *:norem*
71:no[remap] {lhs} {rhs} |mapmode-nvo| *:no* *:noremap* *:nor*
72:nn[oremap] {lhs} {rhs} |mapmode-n| *:nn* *:nnoremap*
73:vn[oremap] {lhs} {rhs} |mapmode-v| *:vn* *:vnoremap*
74:xn[oremap] {lhs} {rhs} |mapmode-x| *:xn* *:xnoremap*
Bram Moolenaar61da1bf2019-06-06 12:14:49 +020075:snor[emap] {lhs} {rhs} |mapmode-s| *:snor* *:snore* *:snoremap*
Bram Moolenaar822ff862014-06-12 21:46:14 +020076:ono[remap] {lhs} {rhs} |mapmode-o| *:ono* *:onoremap*
77:no[remap]! {lhs} {rhs} |mapmode-ic| *:no!* *:noremap!*
Bram Moolenaar61da1bf2019-06-06 12:14:49 +020078:ino[remap] {lhs} {rhs} |mapmode-i| *:ino* *:inor* *:inoremap*
Bram Moolenaar822ff862014-06-12 21:46:14 +020079:ln[oremap] {lhs} {rhs} |mapmode-l| *:ln* *:lnoremap*
Bram Moolenaar61da1bf2019-06-06 12:14:49 +020080:cno[remap] {lhs} {rhs} |mapmode-c| *:cno* *:cnor* *:cnoremap*
Bram Moolenaar69fbc9e2017-09-14 20:37:57 +020081:tno[remap] {lhs} {rhs} |mapmode-t| *:tno* *:tnoremap*
Bram Moolenaar071d4272004-06-13 20:20:40 +000082 Map the key sequence {lhs} to {rhs} for the modes
83 where the map command applies. Disallow mapping of
84 {rhs}, to avoid nested and recursive mappings. Often
Bram Moolenaar25c9c682019-05-05 18:13:34 +020085 used to redefine a command.
Bram Moolenaar1fc34222022-03-03 13:56:24 +000086 Note: When <Plug> appears in the {rhs} this part is
87 always applied even if remapping is disallowed.
Bram Moolenaar071d4272004-06-13 20:20:40 +000088
89
Bram Moolenaar06b5db92006-02-10 23:11:56 +000090:unm[ap] {lhs} |mapmode-nvo| *:unm* *:unmap*
91:nun[map] {lhs} |mapmode-n| *:nun* *:nunmap*
92:vu[nmap] {lhs} |mapmode-v| *:vu* *:vunmap*
Bram Moolenaar371d5402006-03-20 21:47:49 +000093:xu[nmap] {lhs} |mapmode-x| *:xu* *:xunmap*
94:sunm[ap] {lhs} |mapmode-s| *:sunm* *:sunmap*
Bram Moolenaar06b5db92006-02-10 23:11:56 +000095:ou[nmap] {lhs} |mapmode-o| *:ou* *:ounmap*
96:unm[ap]! {lhs} |mapmode-ic| *:unm!* *:unmap!*
97:iu[nmap] {lhs} |mapmode-i| *:iu* *:iunmap*
98:lu[nmap] {lhs} |mapmode-l| *:lu* *:lunmap*
Bram Moolenaar61da1bf2019-06-06 12:14:49 +020099:cu[nmap] {lhs} |mapmode-c| *:cu* *:cun* *:cunmap*
Bram Moolenaar37c64c72017-09-19 22:06:03 +0200100:tunma[p] {lhs} |mapmode-t| *:tunma* *:tunmap*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000101 Remove the mapping of {lhs} for the modes where the
102 map command applies. The mapping may remain defined
103 for other modes where it applies.
Bram Moolenaar88a42052021-11-21 21:13:36 +0000104 It also works when {lhs} matches the {rhs} of a
Bram Moolenaar2f0936c2022-01-08 21:51:59 +0000105 mapping. This is for when an abbreviation applied.
Bram Moolenaarcfa8f9a2022-06-03 21:59:47 +0100106 Note: Trailing spaces are included in the {lhs}.
107 See |map-trailing-white|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000108
Bram Moolenaar06b5db92006-02-10 23:11:56 +0000109:mapc[lear] |mapmode-nvo| *:mapc* *:mapclear*
110:nmapc[lear] |mapmode-n| *:nmapc* *:nmapclear*
111:vmapc[lear] |mapmode-v| *:vmapc* *:vmapclear*
Bram Moolenaar371d5402006-03-20 21:47:49 +0000112:xmapc[lear] |mapmode-x| *:xmapc* *:xmapclear*
113:smapc[lear] |mapmode-s| *:smapc* *:smapclear*
Bram Moolenaar06b5db92006-02-10 23:11:56 +0000114:omapc[lear] |mapmode-o| *:omapc* *:omapclear*
115:mapc[lear]! |mapmode-ic| *:mapc!* *:mapclear!*
116:imapc[lear] |mapmode-i| *:imapc* *:imapclear*
117:lmapc[lear] |mapmode-l| *:lmapc* *:lmapclear*
118:cmapc[lear] |mapmode-c| *:cmapc* *:cmapclear*
Bram Moolenaar69fbc9e2017-09-14 20:37:57 +0200119:tmapc[lear] |mapmode-t| *:tmapc* *:tmapclear*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000120 Remove ALL mappings for the modes where the map
Bram Moolenaar25c9c682019-05-05 18:13:34 +0200121 command applies.
Bram Moolenaar251e1912011-06-19 05:09:16 +0200122 Use the <buffer> argument to remove buffer-local
123 mappings |:map-<buffer>|
Bram Moolenaar921bde82022-05-09 19:50:35 +0100124 Warning: This also removes the |mac-standard-mappings|
125 and the |dos-standard-mappings|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000126
Bram Moolenaar06b5db92006-02-10 23:11:56 +0000127:map |mapmode-nvo|
128:nm[ap] |mapmode-n|
129:vm[ap] |mapmode-v|
Bram Moolenaar371d5402006-03-20 21:47:49 +0000130:xm[ap] |mapmode-x|
131:sm[ap] |mapmode-s|
Bram Moolenaar06b5db92006-02-10 23:11:56 +0000132:om[ap] |mapmode-o|
133:map! |mapmode-ic|
134:im[ap] |mapmode-i|
135:lm[ap] |mapmode-l|
136:cm[ap] |mapmode-c|
Bram Moolenaar37c64c72017-09-19 22:06:03 +0200137:tma[p] |mapmode-t|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000138 List all key mappings for the modes where the map
139 command applies. Note that ":map" and ":map!" are
140 used most often, because they include the other modes.
141
Bram Moolenaar06b5db92006-02-10 23:11:56 +0000142:map {lhs} |mapmode-nvo| *:map_l*
143:nm[ap] {lhs} |mapmode-n| *:nmap_l*
144:vm[ap] {lhs} |mapmode-v| *:vmap_l*
Bram Moolenaar371d5402006-03-20 21:47:49 +0000145:xm[ap] {lhs} |mapmode-x| *:xmap_l*
146:sm[ap] {lhs} |mapmode-s| *:smap_l*
Bram Moolenaar06b5db92006-02-10 23:11:56 +0000147:om[ap] {lhs} |mapmode-o| *:omap_l*
148:map! {lhs} |mapmode-ic| *:map_l!*
149:im[ap] {lhs} |mapmode-i| *:imap_l*
150:lm[ap] {lhs} |mapmode-l| *:lmap_l*
151:cm[ap] {lhs} |mapmode-c| *:cmap_l*
Bram Moolenaar37c64c72017-09-19 22:06:03 +0200152:tma[p] {lhs} |mapmode-t| *:tmap_l*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000153 List the key mappings for the key sequences starting
154 with {lhs} in the modes where the map command applies.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000155
156These commands are used to map a key or key sequence to a string of
157characters. You can use this to put command sequences under function keys,
158translate one key into another, etc. See |:mkexrc| for how to save and
159restore the current mappings.
160
Bram Moolenaar5b962cf2005-12-12 21:58:40 +0000161 *map-ambiguous*
162When two mappings start with the same sequence of characters, they are
163ambiguous. Example: >
164 :imap aa foo
165 :imap aaa bar
166When Vim has read "aa", it will need to get another character to be able to
167decide if "aa" or "aaa" should be mapped. This means that after typing "aa"
168that mapping won't get expanded yet, Vim is waiting for another character.
169If you type a space, then "foo" will get inserted, plus the space. If you
170type "a", then "bar" will get inserted.
Bram Moolenaar5b962cf2005-12-12 21:58:40 +0000171
Bram Moolenaarcfa8f9a2022-06-03 21:59:47 +0100172Trailing white space ~
173 *map-trailing-white*
174This unmap command does NOT work: >
175 :map @@ foo
176 :unmap @@ | print
177
178Because it tries to unmap "@@ ", including the white space before the command
179separator "|". Other examples with trailing white space: >
180 unmap @@
181 unmap @@ # Vim9 script comment
Bram Moolenaar8a3b8052022-06-26 12:21:15 +0100182 unmap @@ " legacy script comment
Bram Moolenaarcfa8f9a2022-06-03 21:59:47 +0100183
184An error will be issued, which is very hard to identify, because the ending
185whitespace character in `unmap @@ ` is not visible.
186
187A generic solution is to put the command separator "|" right after the mapped
188keys. After that white space and a comment may follow: >
189
Bram Moolenaar8a3b8052022-06-26 12:21:15 +0100190 unmap @@| # Vim9 script comment
191 unmap @@| " legacy script comment
Bram Moolenaarcfa8f9a2022-06-03 21:59:47 +0100192
Bram Moolenaar5b962cf2005-12-12 21:58:40 +0000193
1941.2 SPECIAL ARGUMENTS *:map-arguments*
195
Bram Moolenaar72179e12013-06-29 13:58:31 +0200196"<buffer>", "<nowait>", "<silent>", "<special>", "<script>", "<expr>" and
197"<unique>" can be used in any order. They must appear right after the
198command, before any other arguments.
Bram Moolenaar4e427192006-03-10 21:34:27 +0000199
Bram Moolenaar8a3b8052022-06-26 12:21:15 +0100200 *:map-local* *:map-<buffer>* *:map-buffer*
201 *E224* *E225*
Bram Moolenaarc236c162008-07-13 17:41:49 +0000202If the first argument to one of these commands is "<buffer>" the mapping will
203be effective in the current buffer only. Example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000204 :map <buffer> ,w /[.,;]<CR>
205Then you can map ",w" to something else in another buffer: >
206 :map <buffer> ,w /[#&!]<CR>
Bram Moolenaar72179e12013-06-29 13:58:31 +0200207The local buffer mappings are used before the global ones. See <nowait> below
208to make a short local mapping not taking effect when a longer global one
209exists.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000210The "<buffer>" argument can also be used to clear mappings: >
211 :unmap <buffer> ,w
212 :mapclear <buffer>
213Local mappings are also cleared when a buffer is deleted, but not when it is
214unloaded. Just like local option values.
Bram Moolenaarec7944a2013-06-12 21:29:15 +0200215Also see |map-precedence|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000216
Bram Moolenaar72179e12013-06-29 13:58:31 +0200217 *:map-<nowait>* *:map-nowait*
218When defining a buffer-local mapping for "," there may be a global mapping
219that starts with ",". Then you need to type another character for Vim to know
220whether to use the "," mapping or the longer one. To avoid this add the
221<nowait> argument. Then the mapping will be used when it matches, Vim does
222not wait for more characters to be typed. However, if the characters were
Bram Moolenaar6aa8cea2017-06-05 14:44:35 +0200223already typed they are used.
Bram Moolenaar207f0092020-08-30 17:20:20 +0200224Note that this works when the <nowait> mapping fully matches and is found
225before any partial matches. This works when:
226- There is only one matching buffer-local mapping, since these are always
227 found before global mappings.
Bram Moolenaar1c6737b2020-09-07 22:18:52 +0200228- There is another buffer-local mapping that partly matches, but it is
Bram Moolenaar207f0092020-08-30 17:20:20 +0200229 defined earlier (last defined mapping is found first).
Bram Moolenaar72179e12013-06-29 13:58:31 +0200230
Bram Moolenaar071d4272004-06-13 20:20:40 +0000231 *:map-<silent>* *:map-silent*
232To define a mapping which will not be echoed on the command line, add
233"<silent>" as the first argument. Example: >
234 :map <silent> ,h /Header<CR>
235The search string will not be echoed when using this mapping. Messages from
236the executed command are still given though. To shut them up too, add a
237":silent" in the executed command: >
238 :map <silent> ,h :exe ":silent normal /Header\r"<CR>
Bram Moolenaar698a00f2022-11-14 22:07:45 +0000239Note that the effect of a command might also be silenced, e.g., when the
240mapping selects another entry for command line completion it won't be
241displayed.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000242Prompts will still be given, e.g., for inputdialog().
243Using "<silent>" for an abbreviation is possible, but will cause redrawing of
244the command line to fail.
245
Bram Moolenaar9c102382006-05-03 21:26:49 +0000246 *:map-<special>* *:map-special*
247Define a mapping with <> notation for special keys, even though the "<" flag
248may appear in 'cpoptions'. This is useful if the side effect of setting
249'cpoptions' is not desired. Example: >
250 :map <special> <F12> /Header<CR>
251<
Bram Moolenaar071d4272004-06-13 20:20:40 +0000252 *:map-<script>* *:map-script*
253If the first argument to one of these commands is "<script>" and it is used to
254define a new mapping or abbreviation, the mapping will only remap characters
255in the {rhs} using mappings that were defined local to a script, starting with
256"<SID>". This can be used to avoid that mappings from outside a script
257interfere (e.g., when CTRL-V is remapped in mswin.vim), but do use other
258mappings defined in the script.
259Note: ":map <script>" and ":noremap <script>" do the same thing. The
260"<script>" overrules the command name. Using ":noremap <script>" is
261preferred, because it's clearer that remapping is (mostly) disabled.
262
Bram Moolenaar0e6adf82021-12-16 14:41:10 +0000263 *:map-<unique>* *:map-unique* *E226* *E227*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000264If the first argument to one of these commands is "<unique>" and it is used to
265define a new mapping or abbreviation, the command will fail if the mapping or
266abbreviation already exists. Example: >
267 :map <unique> ,w /[#&!]<CR>
268When defining a local mapping, there will also be a check if a global map
269already exists which is equal.
270Example of what will fail: >
271 :map ,w /[#&!]<CR>
272 :map <buffer> <unique> ,w /[.,;]<CR>
Bram Moolenaara40ceaf2006-01-13 22:35:40 +0000273If you want to map a key and then have it do what it was originally mapped to,
274have a look at |maparg()|.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000275
Bram Moolenaar4e427192006-03-10 21:34:27 +0000276 *:map-<expr>* *:map-expression*
277If the first argument to one of these commands is "<expr>" and it is used to
278define a new mapping or abbreviation, the argument is an expression. The
279expression is evaluated to obtain the {rhs} that is used. Example: >
Bram Moolenaar4c295022021-05-02 17:19:11 +0200280 :inoremap <expr> . <SID>InsertDot()
281The result of the s:InsertDot() function will be inserted. It could check the
Bram Moolenaar4e427192006-03-10 21:34:27 +0000282text before the cursor and start omni completion when some condition is met.
Bram Moolenaar4c295022021-05-02 17:19:11 +0200283Using a script-local function is preferred, to avoid polluting the global
284namespace. Use <SID> in the RHS so that the script that the mapping was
285defined in can be found.
Bram Moolenaar4e427192006-03-10 21:34:27 +0000286
Bram Moolenaarda9591e2009-09-30 13:17:02 +0000287For abbreviations |v:char| is set to the character that was typed to trigger
288the abbreviation. You can use this to decide how to expand the {lhs}. You
Bram Moolenaar5302d9e2011-09-14 17:55:08 +0200289should not either insert or change the v:char.
Bram Moolenaarda9591e2009-09-30 13:17:02 +0000290
Bram Moolenaar4f4d51a2020-10-11 13:57:40 +0200291In case you want the mapping to not do anything, you can have the expression
292evaluate to an empty string. If something changed that requires Vim to
293go through the main loop (e.g. to update the display), return "\<Ignore>".
294This is similar to "nothing" but makes Vim return from the loop that waits for
295input. Example: >
296 func s:OpenPopup()
297 call popup_create(... arguments ...)
298 return "\<Ignore>"
299 endfunc
Bram Moolenaar4c295022021-05-02 17:19:11 +0200300 nnoremap <expr> <F3> <SID>OpenPopup()
Bram Moolenaar4f4d51a2020-10-11 13:57:40 +0200301
Bram Moolenaarfd31be22022-01-16 14:46:06 +0000302Keep in mind that the expression may be evaluated when looking for
Bram Moolenaar18b7d862021-03-17 13:28:05 +0100303typeahead, before the previous command has been executed. For example: >
304 func StoreColumn()
305 let g:column = col('.')
306 return 'x'
307 endfunc
308 nnoremap <expr> x StoreColumn()
309 nmap ! f!x
Bram Moolenaardad44732021-03-31 20:07:33 +0200310You will notice that g:column has the value from before executing "f!",
311because "x" is evaluated before "f!" is executed.
Bram Moolenaar18b7d862021-03-17 13:28:05 +0100312This can be solved by inserting <Ignore> before the character that is
313expression-mapped: >
314 nmap ! f!<Ignore>x
315
Bram Moolenaare32c3c42022-01-15 18:26:04 +0000316When defining a mapping in a |Vim9| script, the expression will be evaluated
317in the context of that script. This means that script-local items can be
318accessed in the expression.
319
Bram Moolenaar4e427192006-03-10 21:34:27 +0000320Be very careful about side effects! The expression is evaluated while
Bram Moolenaarc9b4b052006-04-30 18:54:39 +0000321obtaining characters, you may very well make the command dysfunctional.
322For this reason the following is blocked:
Bram Moolenaar5c5b0942007-05-06 12:07:59 +0000323- Changing the buffer text |textlock|.
324- Editing another buffer.
325- The |:normal| command.
326- Moving the cursor is allowed, but it is restored afterwards.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +0000327If you want the mapping to do any of these let the returned characters do
Bram Moolenaar957cf672020-11-12 14:21:06 +0100328that, or use a |<Cmd>| mapping instead.
Bram Moolenaar4e427192006-03-10 21:34:27 +0000329
Bram Moolenaar15146672011-10-20 22:22:38 +0200330You can use getchar(), it consumes typeahead if there is any. E.g., if you
331have these mappings: >
332 inoremap <expr> <C-L> nr2char(getchar())
333 inoremap <expr> <C-L>x "foo"
334If you now type CTRL-L nothing happens yet, Vim needs the next character to
335decide what mapping to use. If you type 'x' the second mapping is used and
Bram Moolenaarf1568ec2011-12-14 21:17:39 +0100336"foo" is inserted. If you type any other key the first mapping is used,
337getchar() gets the typed key and returns it.
Bram Moolenaar15146672011-10-20 22:22:38 +0200338
Bram Moolenaar4e427192006-03-10 21:34:27 +0000339Here is an example that inserts a list number that increases: >
340 let counter = 0
341 inoremap <expr> <C-L> ListItem()
342 inoremap <expr> <C-R> ListReset()
343
344 func ListItem()
345 let g:counter += 1
Bram Moolenaarc51cf032022-02-26 12:25:45 +0000346 return g:counter .. '. '
Bram Moolenaar4e427192006-03-10 21:34:27 +0000347 endfunc
348
349 func ListReset()
350 let g:counter = 0
351 return ''
352 endfunc
353
Bram Moolenaard9967712006-03-11 21:18:15 +0000354CTRL-L inserts the next number, CTRL-R resets the count. CTRL-R returns an
Bram Moolenaar4e427192006-03-10 21:34:27 +0000355empty string, so that nothing is inserted.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000356
Bram Moolenaar1c6737b2020-09-07 22:18:52 +0200357Note that using 0x80 as a single byte before other text does not work, it will
358be seen as a special key.
Bram Moolenaar8424a622006-04-19 21:23:36 +0000359
Bram Moolenaar957cf672020-11-12 14:21:06 +0100360 *<Cmd>* *:map-cmd*
361The special text <Cmd> begins a "command mapping", it executes the command
362directly without changing modes. Where you might use ":...<CR>" in the
363{rhs} of a mapping, you can instead use "<Cmd>...<CR>".
364Example: >
365 noremap x <Cmd>echo mode(1)<CR>
366<
367This is more flexible than `:<C-U>` in Visual and Operator-pending mode, or
368`<C-O>:` in Insert mode, because the commands are executed directly in the
369current mode, instead of always going to Normal mode. Visual mode is
370preserved, so tricks with |gv| are not needed. Commands can be invoked
371directly in Command-line mode (which would otherwise require timer hacks).
372Example of using <Cmd> halfway Insert mode: >
373 nnoremap <F3> aText <Cmd>echo mode(1)<CR> Added<Esc>
374
375Unlike <expr> mappings, there are no special restrictions on the <Cmd>
Bram Moolenaar4466ad62020-11-21 13:16:30 +0100376command: it is executed as if an (unrestricted) |autocommand| was invoked.
Bram Moolenaar957cf672020-11-12 14:21:06 +0100377
Bram Moolenaare32c3c42022-01-15 18:26:04 +0000378 *<ScriptCmd>*
379<ScriptCmd> is like <Cmd> but sets the context to the script the mapping was
380defined in, for the duration of the command execution. This is especially
381useful for |Vim9| script. It also works to access an import, which is useful
Bram Moolenaar5ed11532022-07-06 13:18:11 +0100382in a plugin using a, possibly autoloaded, script: >
Bram Moolenaare32c3c42022-01-15 18:26:04 +0000383 vim9script
384 import autoload 'implementation.vim' as impl
Bram Moolenaarfd31be22022-01-16 14:46:06 +0000385 nnoremap <F4> <ScriptCmd>impl.DoTheWork()<CR>
Bram Moolenaar5ed11532022-07-06 13:18:11 +0100386<
Bram Moolenaare32c3c42022-01-15 18:26:04 +0000387No matter where <F4> is typed, the "impl" import will be found in the script
Bram Moolenaar5ed11532022-07-06 13:18:11 +0100388context of where the mapping was defined. When it's an autoload import, as in
389the example, the "implementation.vim" script will only be loaded once <F4> is
390typed, not when the mapping is defined.
391
392Without <ScriptCmd> using "s:impl" would result in "E121: Undefined variable".
Bram Moolenaare32c3c42022-01-15 18:26:04 +0000393
Bram Moolenaar957cf672020-11-12 14:21:06 +0100394Note:
Bram Moolenaare32c3c42022-01-15 18:26:04 +0000395- Because <Cmd> and <ScriptCmd> avoid mode-changes it does not trigger
396 |CmdlineEnter| and |CmdlineLeave| events, because no user interaction is
397 expected.
Bram Moolenaar957cf672020-11-12 14:21:06 +0100398- For the same reason, |keycodes| like <C-R><C-W> are interpreted as plain,
399 unmapped keys.
Bram Moolenaar4466ad62020-11-21 13:16:30 +0100400- The command is not echo'ed, no need for <silent>.
Bram Moolenaar88a42052021-11-21 21:13:36 +0000401- The {rhs} is not subject to abbreviations nor to other mappings, even if the
402 mapping is recursive.
Bram Moolenaar10e8ff92023-06-10 21:40:39 +0100403- In Visual mode you can use `line('v')` and `col('v')` to get one end of the
Bram Moolenaar4466ad62020-11-21 13:16:30 +0100404 Visual area, the cursor is at the other end.
Bram Moolenaard799daa2022-06-20 11:17:32 +0100405
Bram Moolenaara4d131d2021-12-27 21:33:07 +0000406 *E1255* *E1136*
Bram Moolenaare32c3c42022-01-15 18:26:04 +0000407<Cmd> and <ScriptCmd> commands must terminate, that is, they must be followed
408by <CR> in the {rhs} of the mapping definition. |Command-line| mode is never
Yegappan Lakshmanan49cdd622023-12-24 11:01:23 +0100409entered. To use a literal <CR> in the {rhs}, use |<lt>|.
Bram Moolenaar957cf672020-11-12 14:21:06 +0100410
Bram Moolenaar071d4272004-06-13 20:20:40 +0000411
Bram Moolenaar5b962cf2005-12-12 21:58:40 +00004121.3 MAPPING AND MODES *:map-modes*
Bram Moolenaara7241f52008-06-24 20:39:31 +0000413 *mapmode-nvo* *mapmode-n* *mapmode-v* *mapmode-o*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000414
Bram Moolenaar1588bc82022-03-08 21:35:07 +0000415There are seven sets of mappings
Bram Moolenaar071d4272004-06-13 20:20:40 +0000416- For Normal mode: When typing commands.
417- For Visual mode: When typing commands while the Visual area is highlighted.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100418- For Select mode: like Visual mode but typing text replaces the selection.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000419- For Operator-pending mode: When an operator is pending (after "d", "y", "c",
Bram Moolenaara7241f52008-06-24 20:39:31 +0000420 etc.). See below: |omap-info|.
Bram Moolenaar402d2fe2005-04-15 21:00:38 +0000421- For Insert mode. These are also used in Replace mode.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000422- For Command-line mode: When entering a ":" or "/" command.
Bram Moolenaar1588bc82022-03-08 21:35:07 +0000423- For Terminal mode: When typing in a |:terminal| buffer.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000424
Bram Moolenaar071d4272004-06-13 20:20:40 +0000425Special case: While typing a count for a command in Normal mode, mapping zero
426is disabled. This makes it possible to map zero without making it impossible
427to type a count with a zero.
428
429 *map-overview* *map-modes*
Bram Moolenaare968e362014-05-13 20:23:24 +0200430Overview of which map command works in which mode. More details below.
431 COMMANDS MODES ~
432:map :noremap :unmap Normal, Visual, Select, Operator-pending
433:nmap :nnoremap :nunmap Normal
434:vmap :vnoremap :vunmap Visual and Select
435:smap :snoremap :sunmap Select
436:xmap :xnoremap :xunmap Visual
437:omap :onoremap :ounmap Operator-pending
438:map! :noremap! :unmap! Insert and Command-line
439:imap :inoremap :iunmap Insert
440:lmap :lnoremap :lunmap Insert, Command-line, Lang-Arg
441:cmap :cnoremap :cunmap Command-line
Bram Moolenaar69fbc9e2017-09-14 20:37:57 +0200442:tmap :tnoremap :tunmap Terminal-Job
Bram Moolenaar071d4272004-06-13 20:20:40 +0000443
Bram Moolenaar3ec32172021-05-16 12:39:47 +0200444Same information in a table:
445 *map-table*
446 Mode | Norm | Ins | Cmd | Vis | Sel | Opr | Term | Lang | ~
447Command +------+-----+-----+-----+-----+-----+------+------+ ~
448[nore]map | yes | - | - | yes | yes | yes | - | - |
449n[nore]map | yes | - | - | - | - | - | - | - |
450[nore]map! | - | yes | yes | - | - | - | - | - |
451i[nore]map | - | yes | - | - | - | - | - | - |
452c[nore]map | - | - | yes | - | - | - | - | - |
453v[nore]map | - | - | - | yes | yes | - | - | - |
454x[nore]map | - | - | - | yes | - | - | - | - |
455s[nore]map | - | - | - | - | yes | - | - | - |
456o[nore]map | - | - | - | - | - | yes | - | - |
457t[nore]map | - | - | - | - | - | - | yes | - |
458l[nore]map | - | yes | yes | - | - | - | - | yes |
459
Bram Moolenaare968e362014-05-13 20:23:24 +0200460
461 COMMANDS MODES ~
Bram Moolenaarc9b4b052006-04-30 18:54:39 +0000462 Normal Visual+Select Operator-pending ~
463:map :noremap :unmap :mapclear yes yes yes
464:nmap :nnoremap :nunmap :nmapclear yes - -
465:vmap :vnoremap :vunmap :vmapclear - yes -
466:omap :onoremap :ounmap :omapclear - - yes
Bram Moolenaar371d5402006-03-20 21:47:49 +0000467
Bram Moolenaar4c3f5362006-04-11 21:38:50 +0000468:nunmap can also be used outside of a monastery.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +0000469 *mapmode-x* *mapmode-s*
Bram Moolenaar371d5402006-03-20 21:47:49 +0000470Some commands work both in Visual and Select mode, some in only one. Note
471that quite often "Visual" is mentioned where both Visual and Select mode
472apply. |Select-mode-mapping|
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100473NOTE: Mapping a printable character in Select mode may confuse the user. It's
474better to explicitly use :xmap and :smap for printable characters. Or use
475:sunmap after defining the mapping.
Bram Moolenaar371d5402006-03-20 21:47:49 +0000476
Bram Moolenaare968e362014-05-13 20:23:24 +0200477 COMMANDS MODES ~
Bram Moolenaarc9b4b052006-04-30 18:54:39 +0000478 Visual Select ~
479:vmap :vnoremap :vunmap :vmapclear yes yes
480:xmap :xnoremap :xunmap :xmapclear yes -
481:smap :snoremap :sunmap :smapclear - yes
Bram Moolenaar071d4272004-06-13 20:20:40 +0000482
Bram Moolenaar06b5db92006-02-10 23:11:56 +0000483 *mapmode-ic* *mapmode-i* *mapmode-c* *mapmode-l*
Bram Moolenaar371d5402006-03-20 21:47:49 +0000484Some commands work both in Insert mode and Command-line mode, some not:
485
Bram Moolenaare968e362014-05-13 20:23:24 +0200486 COMMANDS MODES ~
Bram Moolenaar071d4272004-06-13 20:20:40 +0000487 Insert Command-line Lang-Arg ~
488:map! :noremap! :unmap! :mapclear! yes yes -
489:imap :inoremap :iunmap :imapclear yes - -
490:cmap :cnoremap :cunmap :cmapclear - yes -
491:lmap :lnoremap :lunmap :lmapclear yes* yes* yes*
492
Bram Moolenaar5ef1c6a2019-11-10 22:09:11 +0100493* If 'iminsert' is 1, see |language-mapping| below.
494
Bram Moolenaar071d4272004-06-13 20:20:40 +0000495The original Vi did not have separate mappings for
496Normal/Visual/Operator-pending mode and for Insert/Command-line mode.
497Therefore the ":map" and ":map!" commands enter and display mappings for
498several modes. In Vim you can use the ":nmap", ":vmap", ":omap", ":cmap" and
499":imap" commands to enter mappings for each mode separately.
500
Bram Moolenaar69fbc9e2017-09-14 20:37:57 +0200501 *mapmode-t*
502The terminal mappings are used in a terminal window, when typing keys for the
503job running in the terminal. See |terminal-typing|.
504
Bram Moolenaara7241f52008-06-24 20:39:31 +0000505 *omap-info*
506Operator-pending mappings can be used to define a movement command that can be
Bram Moolenaar95bafa22018-10-02 13:26:25 +0200507used with any operator. Simple example: >
508 :omap { w
509makes "y{" work like "yw" and "d{" like "dw".
Bram Moolenaara7241f52008-06-24 20:39:31 +0000510
511To ignore the starting cursor position and select different text, you can have
512the omap start Visual mode to select the text to be operated upon. Example
513that operates on a function name in the current line: >
514 onoremap <silent> F :<C-U>normal! 0f(hviw<CR>
515The CTRL-U (<C-U>) is used to remove the range that Vim may insert. The
516Normal mode commands find the first '(' character and select the first word
517before it. That usually is the function name.
518
Bram Moolenaar071d4272004-06-13 20:20:40 +0000519To enter a mapping for Normal and Visual mode, but not Operator-pending mode,
Bram Moolenaar95bafa22018-10-02 13:26:25 +0200520first define it for all three modes, then unmap it for
521Operator-pending mode: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000522 :map xx something-difficult
523 :ounmap xx
Bram Moolenaar95bafa22018-10-02 13:26:25 +0200524
Bram Moolenaar071d4272004-06-13 20:20:40 +0000525Likewise for a mapping for Visual and Operator-pending mode or Normal and
526Operator-pending mode.
527
528 *language-mapping*
529":lmap" defines a mapping that applies to:
530- Insert mode
531- Command-line mode
532- when entering a search pattern
533- the argument of the commands that accept a text character, such as "r" and
534 "f"
535- for the input() line
536Generally: Whenever a character is to be typed that is part of the text in the
537buffer, not a Vim command character. "Lang-Arg" isn't really another mode,
538it's just used here for this situation.
539 The simplest way to load a set of related language mappings is by using the
540'keymap' option. See |45.5|.
541 In Insert mode and in Command-line mode the mappings can be disabled with
Bram Moolenaar7cba6c02013-09-05 22:13:31 +0200542the CTRL-^ command |i_CTRL-^| |c_CTRL-^|. These commands change the value of
Bram Moolenaar3b1db362013-08-10 15:00:24 +0200543the 'iminsert' option. When starting to enter a normal command line (not a
544search pattern) the mappings are disabled until a CTRL-^ is typed. The state
545last used is remembered for Insert mode and Search patterns separately. The
546state for Insert mode is also used when typing a character as an argument to
547command like "f" or "t".
Bram Moolenaar071d4272004-06-13 20:20:40 +0000548 Language mappings will never be applied to already mapped characters. They
549are only used for typed characters. This assumes that the language mapping
550was already done when typing the mapping.
551
Bram Moolenaar071d4272004-06-13 20:20:40 +0000552
Bram Moolenaar5b962cf2005-12-12 21:58:40 +00005531.4 LISTING MAPPINGS *map-listing*
554
Bram Moolenaar071d4272004-06-13 20:20:40 +0000555When listing mappings the characters in the first two columns are:
556
557 CHAR MODE ~
Bram Moolenaar5c5b0942007-05-06 12:07:59 +0000558 <Space> Normal, Visual, Select and Operator-pending
Bram Moolenaar071d4272004-06-13 20:20:40 +0000559 n Normal
Bram Moolenaar5c5b0942007-05-06 12:07:59 +0000560 v Visual and Select
561 s Select
562 x Visual
Bram Moolenaar071d4272004-06-13 20:20:40 +0000563 o Operator-pending
564 ! Insert and Command-line
565 i Insert
566 l ":lmap" mappings for Insert, Command-line and Lang-Arg
567 c Command-line
Bram Moolenaar63c4e8a2017-09-17 20:32:20 +0200568 t Terminal-Job
Bram Moolenaar071d4272004-06-13 20:20:40 +0000569
570Just before the {rhs} a special character can appear:
571 * indicates that it is not remappable
572 & indicates that only script-local mappings are remappable
573 @ indicates a buffer-local mapping
574
575Everything from the first non-blank after {lhs} up to the end of the line
576(or '|') is considered to be part of {rhs}. This allows the {rhs} to end
577with a space.
578
579Note: When using mappings for Visual mode, you can use the "'<" mark, which
580is the start of the last selected Visual area in the current buffer |'<|.
581
Bram Moolenaar818078d2016-08-27 21:58:42 +0200582The |:filter| command can be used to select what mappings to list. The
583pattern is matched against the {lhs} and {rhs} in the raw form.
584
Bram Moolenaard13166e2022-11-18 21:49:57 +0000585While mappings are being listed, it is not possible to add or clear mappings,
586e.g. from a timer callback. *E1309*
587
Bram Moolenaarae5bce12005-08-15 21:41:48 +0000588 *:map-verbose*
Christian Brabandt0ede5e32024-01-01 18:56:52 +0100589When 'verbose' is non-zero, the detected and used 'keyprotocol' value will be
590displayed in the first line. Also a key map will also display where it was
Bram Moolenaarae5bce12005-08-15 21:41:48 +0000591last defined. Example: >
592
593 :verbose map <C-W>*
Christian Brabandt0ede5e32024-01-01 18:56:52 +0100594 Kitty keyboard protocol: Cleared
Bram Moolenaarae5bce12005-08-15 21:41:48 +0000595 n <C-W>* * <C-W><C-S>*
Bram Moolenaarc9b4b052006-04-30 18:54:39 +0000596 Last set from /home/abcd/.vimrc
Bram Moolenaarae5bce12005-08-15 21:41:48 +0000597
Bram Moolenaar5195e452005-08-19 20:32:47 +0000598See |:verbose-cmd| for more information.
Bram Moolenaarae5bce12005-08-15 21:41:48 +0000599
Bram Moolenaar5b962cf2005-12-12 21:58:40 +0000600
6011.5 MAPPING SPECIAL KEYS *:map-special-keys*
602
603There are three ways to map a special key:
6041. The Vi-compatible method: Map the key code. Often this is a sequence that
605 starts with <Esc>. To enter a mapping like this you type ":map " and then
606 you have to type CTRL-V before hitting the function key. Note that when
607 the key code for the key is in the termcap (the t_ options), it will
608 automatically be translated into the internal code and become the second
609 way of mapping (unless the 'k' flag is included in 'cpoptions').
6102. The second method is to use the internal code for the function key. To
611 enter such a mapping type CTRL-K and then hit the function key, or use
612 the form "#1", "#2", .. "#9", "#0", "<Up>", "<S-Down>", "<S-F7>", etc.
613 (see table of keys |key-notation|, all keys from <Up> can be used). The
614 first ten function keys can be defined in two ways: Just the number, like
615 "#2", and with "<F>", like "<F2>". Both stand for function key 2. "#0"
616 refers to function key 10, defined with option 't_f10', which may be
617 function key zero on some keyboards. The <> form cannot be used when
618 'cpoptions' includes the '<' flag.
6193. Use the termcap entry, with the form <t_xx>, where "xx" is the name of the
620 termcap entry. Any string entry can be used. For example: >
621 :map <t_F3> G
622< Maps function key 13 to "G". This does not work if 'cpoptions' includes
623 the '<' flag.
624
625The advantage of the second and third method is that the mapping will work on
626different terminals without modification (the function key will be
627translated into the same internal code or the actual key code, no matter what
628terminal you are using. The termcap must be correct for this to work, and you
629must use the same mappings).
630
631DETAIL: Vim first checks if a sequence from the keyboard is mapped. If it
632isn't the terminal key codes are tried (see |terminal-options|). If a
633terminal code is found it is replaced with the internal code. Then the check
634for a mapping is done again (so you can map an internal code to something
635else). What is written into the script file depends on what is recognized.
636If the terminal key code was recognized as a mapping the key code itself is
637written to the script file. If it was recognized as a terminal code the
638internal code is written to the script file.
639
640
6411.6 SPECIAL CHARACTERS *:map-special-chars*
Bram Moolenaar345efa02016-01-15 20:57:49 +0100642 *map_backslash* *map-backslash*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000643Note that only CTRL-V is mentioned here as a special character for mappings
644and abbreviations. When 'cpoptions' does not contain 'B', a backslash can
645also be used like CTRL-V. The <> notation can be fully used then |<>|. But
646you cannot use "<C-V>" like CTRL-V to escape the special meaning of what
647follows.
648
649To map a backslash, or use a backslash literally in the {rhs}, the special
650sequence "<Bslash>" can be used. This avoids the need to double backslashes
651when using nested mappings.
652
Bram Moolenaar345efa02016-01-15 20:57:49 +0100653 *map_CTRL-C* *map-CTRL-C*
Bram Moolenaar1e015462005-09-25 22:16:38 +0000654Using CTRL-C in the {lhs} is possible, but it will only work when Vim is
655waiting for a key, not when Vim is busy with something. When Vim is busy
656CTRL-C interrupts/breaks the command.
657When using the GUI version on MS-Windows CTRL-C can be mapped to allow a Copy
658command to the clipboard. Use CTRL-Break to interrupt Vim.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000659
Bram Moolenaar345efa02016-01-15 20:57:49 +0100660 *map_space_in_lhs* *map-space_in_lhs*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000661To include a space in {lhs} precede it with a CTRL-V (type two CTRL-Vs for
662each space).
Bram Moolenaar345efa02016-01-15 20:57:49 +0100663 *map_space_in_rhs* *map-space_in_rhs*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000664If you want a {rhs} that starts with a space, use "<Space>". To be fully Vi
665compatible (but unreadable) don't use the |<>| notation, precede {rhs} with a
666single CTRL-V (you have to type CTRL-V two times).
Bram Moolenaar345efa02016-01-15 20:57:49 +0100667 *map_empty_rhs* *map-empty-rhs*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000668You can create an empty {rhs} by typing nothing after a single CTRL-V (you
669have to type CTRL-V two times). Unfortunately, you cannot do this in a vimrc
670file.
671 *<Nop>*
Bram Moolenaar446beb42011-05-10 17:18:44 +0200672An easier way to get a mapping that doesn't produce anything, is to use
673"<Nop>" for the {rhs}. This only works when the |<>| notation is enabled.
674For example, to make sure that function key 8 does nothing at all: >
Bram Moolenaar071d4272004-06-13 20:20:40 +0000675 :map <F8> <Nop>
676 :map! <F8> <Nop>
677<
Bram Moolenaar5b962cf2005-12-12 21:58:40 +0000678 *map-multibyte*
679It is possible to map multibyte characters, but only the whole character. You
680cannot map the first byte only. This was done to prevent problems in this
681scenario: >
682 :set encoding=latin1
683 :imap <M-C> foo
684 :set encoding=utf-8
685The mapping for <M-C> is defined with the latin1 encoding, resulting in a 0xc3
Bram Moolenaar85eee132018-05-06 17:57:30 +0200686byte. If you type the character á (0xe1 <M-a>) in UTF-8 encoding this is the
Bram Moolenaar446beb42011-05-10 17:18:44 +0200687two bytes 0xc3 0xa1. You don't want the 0xc3 byte to be mapped then or
Bram Moolenaar85eee132018-05-06 17:57:30 +0200688otherwise it would be impossible to type the á character.
Bram Moolenaar5b962cf2005-12-12 21:58:40 +0000689
Bram Moolenaar071d4272004-06-13 20:20:40 +0000690 *<Leader>* *mapleader*
Bram Moolenaarb529cfb2022-07-25 15:42:07 +0100691To define a mapping which uses the "g:mapleader" variable, the special string
692"<Leader>" can be used. It is replaced with the string value of
693"g:mapleader". If "g:mapleader" is not set or empty, a backslash is used
694instead. Example: >
695 map <Leader>A oanother line<Esc>
Bram Moolenaar071d4272004-06-13 20:20:40 +0000696Works like: >
Bram Moolenaarb529cfb2022-07-25 15:42:07 +0100697 map \A oanother line<Esc>
698But after (legacy script): >
699 let mapleader = ","
700Or (Vim9 script): >
701 g:mapleader = ","
Bram Moolenaar071d4272004-06-13 20:20:40 +0000702It works like: >
Bram Moolenaarb529cfb2022-07-25 15:42:07 +0100703 map ,A oanother line<Esc>
Bram Moolenaar071d4272004-06-13 20:20:40 +0000704
Bram Moolenaarb529cfb2022-07-25 15:42:07 +0100705Note that the value of "g:mapleader" is used at the moment the mapping is
706defined. Changing "g:mapleader" after that has no effect for already defined
Bram Moolenaar071d4272004-06-13 20:20:40 +0000707mappings.
708
709 *<LocalLeader>* *maplocalleader*
Bram Moolenaara7241f52008-06-24 20:39:31 +0000710<LocalLeader> is just like <Leader>, except that it uses "maplocalleader"
711instead of "mapleader". <LocalLeader> is to be used for mappings which are
712local to a buffer. Example: >
Bram Moolenaarb8ff1fb2012-02-04 21:59:01 +0100713 :map <buffer> <LocalLeader>A oanother line<Esc>
Bram Moolenaar071d4272004-06-13 20:20:40 +0000714<
715In a global plugin <Leader> should be used and in a filetype plugin
716<LocalLeader>. "mapleader" and "maplocalleader" can be equal. Although, if
717you make them different, there is a smaller chance of mappings from global
718plugins to clash with mappings for filetype plugins. For example, you could
719keep "mapleader" at the default backslash, and set "maplocalleader" to an
720underscore.
721
722 *map-<SID>*
723In a script the special key name "<SID>" can be used to define a mapping
724that's local to the script. See |<SID>| for details.
725
726 *<Plug>*
727The special key name "<Plug>" can be used for an internal mapping, which is
728not to be matched with any key sequence. This is useful in plugins
729|using-<Plug>|.
730
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +0100731 *<MouseMove>*
732The special key name "<MouseMove>" can be used to handle mouse movement. It
733needs to be enabled with 'mousemoveevent'. Currently only works in the GUI.
Bram Moolenaar2d8ed022022-05-21 13:08:16 +0100734The |getmousepos()| function can be used to obtain the mouse position.
Bram Moolenaarcbaff5e2022-04-08 17:45:08 +0100735
Bram Moolenaar071d4272004-06-13 20:20:40 +0000736 *<Char>* *<Char->*
737To map a character by its decimal, octal or hexadecimal number the <Char>
738construct can be used:
739 <Char-123> character 123
740 <Char-033> character 27
741 <Char-0x7f> character 127
Bram Moolenaar5302d9e2011-09-14 17:55:08 +0200742 <S-Char-114> character 114 ('r') shifted ('R')
Bram Moolenaar207f0092020-08-30 17:20:20 +0200743This is useful to specify a (multibyte) character in a 'keymap' file.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000744Upper and lowercase differences are ignored.
745
746 *map-comments*
747It is not possible to put a comment after these commands, because the '"'
Bram Moolenaar036986f2017-03-16 17:41:02 +0100748character is considered to be part of the {lhs} or {rhs}. However, one can
749use |", since this starts a new, empty command with a comment.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000750
Bram Moolenaar345efa02016-01-15 20:57:49 +0100751 *map_bar* *map-bar*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000752Since the '|' character is used to separate a map command from the next
753command, you will have to do something special to include a '|' in {rhs}.
754There are three methods:
755 use works when example ~
756 <Bar> '<' is not in 'cpoptions' :map _l :!ls <Bar> more^M
757 \| 'b' is not in 'cpoptions' :map _l :!ls \| more^M
758 ^V| always, in Vim and Vi :map _l :!ls ^V| more^M
759
760(here ^V stands for CTRL-V; to get one CTRL-V you have to type it twice; you
761cannot use the <> notation "<C-V>" here).
762
763All three work when you use the default setting for 'cpoptions'.
764
765When 'b' is present in 'cpoptions', "\|" will be recognized as a mapping
766ending in a '\' and then another command. This is Vi compatible, but
767illogical when compared to other commands.
768
Bram Moolenaar345efa02016-01-15 20:57:49 +0100769 *map_return* *map-return*
Bram Moolenaar071d4272004-06-13 20:20:40 +0000770When you have a mapping that contains an Ex command, you need to put a line
771terminator after it to have it executed. The use of <CR> is recommended for
772this (see |<>|). Example: >
Bram Moolenaar251835e2014-02-24 02:51:51 +0100773 :map _ls :!ls -l %:S<CR>:echo "the end"<CR>
Bram Moolenaar071d4272004-06-13 20:20:40 +0000774
775To avoid mapping of the characters you type in insert or Command-line mode,
776type a CTRL-V first. The mapping in Insert mode is disabled if the 'paste'
777option is on.
Bram Moolenaare2db6952013-07-24 19:53:36 +0200778 *map-error*
Bram Moolenaar1b5f03e2023-01-09 20:12:45 +0000779Note that when an error is encountered (that causes an error message or might
780cause a beep) the rest of the mapping is not executed. This is Vi-compatible.
Bram Moolenaar071d4272004-06-13 20:20:40 +0000781
782Note that the second character (argument) of the commands @zZtTfF[]rm'`"v
783and CTRL-X is not mapped. This was done to be able to use all the named
784registers and marks, even when the command with the same name has been
785mapped.
786
Bram Moolenaar5b962cf2005-12-12 21:58:40 +0000787
7881.7 WHAT KEYS TO MAP *map-which-keys*
789
Bram Moolenaar071d4272004-06-13 20:20:40 +0000790If you are going to map something, you will need to choose which key(s) to use
791for the {lhs}. You will have to avoid keys that are used for Vim commands,
792otherwise you would not be able to use those commands anymore. Here are a few
793suggestions:
794- Function keys <F2>, <F3>, etc.. Also the shifted function keys <S-F1>,
795 <S-F2>, etc. Note that <F1> is already used for the help command.
Bram Moolenaar4be18e72023-02-03 12:28:07 +0000796- Any key with the Alt or Meta key pressed. Depending on your keyboard
797 accented characters may be used as well. |:map-alt-keys|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000798- Use the '_' or ',' character and then any other character. The "_" and ","
799 commands do exist in Vim (see |_| and |,|), but you probably never use them.
800- Use a key that is a synonym for another command. For example: CTRL-P and
801 CTRL-N. Use an extra character to allow more mappings.
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +0100802- The key defined by <Leader> and one or more other keys. This is especially
803 useful in scripts. |mapleader|
Bram Moolenaar071d4272004-06-13 20:20:40 +0000804
805See the file "index" for keys that are not used and thus can be mapped without
806losing any builtin function. You can also use ":help {key}^D" to find out if
807a key is used for some command. ({key} is the specific key you want to find
808out about, ^D is CTRL-D).
809
Bram Moolenaar5b962cf2005-12-12 21:58:40 +0000810
8111.8 EXAMPLES *map-examples*
812
Bram Moolenaar071d4272004-06-13 20:20:40 +0000813A few examples (given as you type them, for "<CR>" you type four characters;
814the '<' flag must not be present in 'cpoptions' for this to work). >
815
816 :map <F3> o#include
817 :map <M-g> /foo<CR>cwbar<Esc>
818 :map _x d/END/e<CR>
819 :map! qq quadrillion questions
Bram Moolenaar5c5b0942007-05-06 12:07:59 +0000820
821
822Multiplying a count
823
824When you type a count before triggering a mapping, it's like the count was
825typed before the {lhs}. For example, with this mapping: >
826 :map <F4> 3w
827Typing 2<F4> will result in "23w". Thus not moving 2 * 3 words but 23 words.
828If you want to multiply counts use the expression register: >
829 :map <F4> @='3w'<CR>
830The part between quotes is the expression being executed. |@=|
831
Bram Moolenaar5b962cf2005-12-12 21:58:40 +0000832
8331.9 USING MAPPINGS *map-typing*
834
Bram Moolenaar071d4272004-06-13 20:20:40 +0000835Vim will compare what you type with the start of a mapped sequence. If there
836is an incomplete match, it will get more characters until there either is a
837complete match or until there is no match at all. Example: If you map! "qq",
838the first 'q' will not appear on the screen until you type another
839character. This is because Vim cannot know if the next character will be a
840'q' or not. If the 'timeout' option is on (which is the default) Vim will
841only wait for one second (or as long as specified with the 'timeoutlen'
842option). After that it assumes that the 'q' is to be interpreted as such. If
843you type slowly, or your system is slow, reset the 'timeout' option. Then you
844might want to set the 'ttimeout' option.
845
Bram Moolenaar938ae282023-02-20 20:44:55 +0000846 *map-precedence*
Bram Moolenaarec7944a2013-06-12 21:29:15 +0200847Buffer-local mappings (defined using |:map-<buffer>|) take precedence over
848global mappings. When a buffer-local mapping is the same as a global mapping,
849Vim will use the buffer-local mapping. In addition, Vim will use a complete
Bram Moolenaar14b69452013-06-29 23:05:20 +0200850mapping immediately if it was defined with <nowait>, even if a longer mapping
851has the same prefix. For example, given the following two mappings: >
852 :map <buffer> <nowait> \a :echo "Local \a"<CR>
853 :map \abc :echo "Global \abc"<CR>
854When typing \a the buffer-local mapping will be used immediately. Vim will
855not wait for more characters to see if the user might be typing \abc.
Bram Moolenaarec7944a2013-06-12 21:29:15 +0200856
Bram Moolenaar071d4272004-06-13 20:20:40 +0000857 *map-keys-fails*
Bram Moolenaarcdbac1e2005-12-11 21:27:22 +0000858There are situations where key codes might not be recognized:
Bram Moolenaar071d4272004-06-13 20:20:40 +0000859- Vim can only read part of the key code. Mostly this is only the first
860 character. This happens on some Unix versions in an xterm.
861- The key code is after character(s) that are mapped. E.g., "<F1><F1>" or
862 "g<F1>".
Bram Moolenaarcdbac1e2005-12-11 21:27:22 +0000863
Bram Moolenaar071d4272004-06-13 20:20:40 +0000864The result is that the key code is not recognized in this situation, and the
Bram Moolenaarcdbac1e2005-12-11 21:27:22 +0000865mapping fails. There are two actions needed to avoid this problem:
866
Bram Moolenaar071d4272004-06-13 20:20:40 +0000867- Remove the 'K' flag from 'cpoptions'. This will make Vim wait for the rest
868 of the characters of the function key.
869- When using <F1> to <F4> the actual key code generated may correspond to
870 <xF1> to <xF4>. There are mappings from <xF1> to <F1>, <xF2> to <F2>, etc.,
871 but these are not recognized after another half a mapping. Make sure the
872 key codes for <F1> to <F4> are correct: >
873 :set <F1>=<type CTRL-V><type F1>
874< Type the <F1> as four characters. The part after the "=" must be done with
875 the actual keys, not the literal text.
876Another solution is to use the actual key code in the mapping for the second
877special key: >
878 :map <F1><Esc>OP :echo "yes"<CR>
879Don't type a real <Esc>, Vim will recognize the key code and replace it with
880<F1> anyway.
881
Bram Moolenaarcdbac1e2005-12-11 21:27:22 +0000882Another problem may be that when keeping ALT or Meta pressed the terminal
883prepends ESC instead of setting the 8th bit. See |:map-alt-keys|.
884
Bram Moolenaar071d4272004-06-13 20:20:40 +0000885 *recursive_mapping*
886If you include the {lhs} in the {rhs} you have a recursive mapping. When
887{lhs} is typed, it will be replaced with {rhs}. When the {lhs} which is
888included in {rhs} is encountered it will be replaced with {rhs}, and so on.
889This makes it possible to repeat a command an infinite number of times. The
890only problem is that the only way to stop this is by causing an error. The
891macros to solve a maze uses this, look there for an example. There is one
892exception: If the {rhs} starts with {lhs}, the first character is not mapped
893again (this is Vi compatible).
894For example: >
895 :map ab abcd
896will execute the "a" command and insert "bcd" in the text. The "ab" in the
897{rhs} will not be mapped again.
898
899If you want to exchange the meaning of two keys you should use the :noremap
900command. For example: >
901 :noremap k j
902 :noremap j k
903This will exchange the cursor up and down commands.
904
905With the normal :map command, when the 'remap' option is on, mapping takes
906place until the text is found not to be a part of a {lhs}. For example, if
907you use: >
908 :map x y
909 :map y x
910Vim will replace x with y, and then y with x, etc. When this has happened
911'maxmapdepth' times (default 1000), Vim will give the error message
912"recursive mapping".
913
914 *:map-undo*
915If you include an undo command inside a mapped sequence, this will bring the
916text back in the state before executing the macro. This is compatible with
917the original Vi, as long as there is only one undo command in the mapped
918sequence (having two undo commands in a mapped sequence did not make sense
919in the original Vi, you would get back the text before the first undo).
920
Bram Moolenaar071d4272004-06-13 20:20:40 +0000921
Bram Moolenaar5b962cf2005-12-12 21:58:40 +00009221.10 MAPPING ALT-KEYS *:map-alt-keys*
Bram Moolenaarcdbac1e2005-12-11 21:27:22 +0000923
Bram Moolenaar938ae282023-02-20 20:44:55 +0000924For a readable mapping command the <A-k> form can be used. Note that <A-k>
925and <A-K> are different, the latter will use an upper case letter. Actually,
926<A-K> and <A-S-K> are the same. Instead of "A" you can use "M". If you have
927an actual Meta modifier key, please see |:map-meta-keys|.
928
Bram Moolenaarcdbac1e2005-12-11 21:27:22 +0000929In the GUI Vim handles the Alt key itself, thus mapping keys with ALT should
930always work. But in a terminal Vim gets a sequence of bytes and has to figure
931out whether ALT was pressed or not.
932
Bram Moolenaar4b570182019-10-20 19:53:22 +0200933If the terminal supports the modifyOtherKeys mode and it has been enabled,
934then Vim can recognize more key combinations, see |modifyOtherKeys| below.
Bram Moolenaar4be18e72023-02-03 12:28:07 +0000935The Kitty keyboard protocol works in a similar way, see
936|kitty-keyboard-protocol|.
Bram Moolenaar4b570182019-10-20 19:53:22 +0200937
Bram Moolenaarcdbac1e2005-12-11 21:27:22 +0000938By default Vim assumes that pressing the ALT key sets the 8th bit of a typed
Bram Moolenaar97d29a12005-12-17 22:02:57 +0000939character. Most decent terminals can work that way, such as xterm, aterm and
Bram Moolenaarcdbac1e2005-12-11 21:27:22 +0000940rxvt. If your <A-k> mappings don't work it might be that the terminal is
941prefixing the character with an ESC character. But you can just as well type
942ESC before a character, thus Vim doesn't know what happened (except for
943checking the delay between characters, which is not reliable).
944
945As of this writing, some mainstream terminals like gnome-terminal and konsole
946use the ESC prefix. There doesn't appear a way to have them use the 8th bit
Bram Moolenaar97d29a12005-12-17 22:02:57 +0000947instead. Xterm should work well by default. Aterm and rxvt should work well
948when started with the "--meta8" argument. You can also tweak resources like
949"metaSendsEscape", "eightBitInput" and "eightBitOutput".
Bram Moolenaarcdbac1e2005-12-11 21:27:22 +0000950
951On the Linux console, this behavior can be toggled with the "setmetamode"
952command. Bear in mind that not using an ESC prefix could get you in trouble
953with other programs. You should make sure that bash has the "convert-meta"
954option set to "on" in order for your Meta keybindings to still work on it
955(it's the default readline behavior, unless changed by specific system
956configuration). For that, you can add the line: >
957
958 set convert-meta on
959
960to your ~/.inputrc file. If you're creating the file, you might want to use: >
961
962 $include /etc/inputrc
963
964as the first line, if that file exists on your system, to keep global options.
965This may cause a problem for entering special characters, such as the umlaut.
966Then you should use CTRL-V before that character.
967
968Bear in mind that convert-meta has been reported to have troubles when used in
969UTF-8 locales. On terminals like xterm, the "metaSendsEscape" resource can be
970toggled on the fly through the "Main Options" menu, by pressing Ctrl-LeftClick
971on the terminal; that's a good last resource in case you want to send ESC when
Bram Moolenaar6aa8cea2017-06-05 14:44:35 +0200972using other applications but not when inside Vim.
Bram Moolenaarcdbac1e2005-12-11 21:27:22 +0000973
Bram Moolenaar5b962cf2005-12-12 21:58:40 +0000974
Bram Moolenaar4be18e72023-02-03 12:28:07 +00009751.11 MAPPING META-KEYS *:map-meta-keys*
976
977Mapping keys with the Meta modifier works very similar to using the Alt key.
978What key on your keyboard produces the Meta modifier depends on your keyboard
979and configuration.
980
981Note that mapping <M-a> actually is for using the Alt key. That can be
982confusing! It cannot be changed, it would not be backwards compatible.
983
984For the Meta modifier the "T" character is used. For example, to map Meta-b
985in Insert mode: >
986 :imap <T-b> terrible
987
988
9891.12 MAPPING IN modifyOtherKeys mode *modifyOtherKeys*
Bram Moolenaar4b570182019-10-20 19:53:22 +0200990
991Xterm and a few other terminals can be put in a mode where keys with modifiers
992are sent with a special escape code. Vim recognizes these codes and can then
993make a difference between CTRL-H and Backspace, even when Backspace sends the
Bram Moolenaar47f1fdc2022-11-24 13:27:36 +0000994character 8. And many more special keys, such as Tab and CTRL-I, which cannot
995be mapped separately otherwise.
Bram Moolenaar4b570182019-10-20 19:53:22 +0200996
997For xterm modifyOtherKeys is enabled in the builtin termcap entry. If this is
998not used you can enable modifyOtherKeys with these lines in your vimrc: >
999 let &t_TI = "\<Esc>[>4;2m"
1000 let &t_TE = "\<Esc>[>4;m"
1001
Bram Moolenaar47f1fdc2022-11-24 13:27:36 +00001002This sets modifyOtherKeys to level 2. Note that modifyOtherKeys level 1 does
1003not work. Some terminals do not support level 2 and then send key codes that
1004Vim will not be able to correctly recognize.
1005
Bram Moolenaar4b570182019-10-20 19:53:22 +02001006In case the modifyOtherKeys mode causes problems you can disable it: >
1007 let &t_TI = ""
1008 let &t_TE = ""
1009It does not take effect immediately. To have this work without restarting Vim
Bram Moolenaar5ef1c6a2019-11-10 22:09:11 +01001010execute a shell command, e.g.: `!ls` Or put the lines in your |vimrc|.
1011
1012When modifyOtherKeys is enabled you can map <C-[> and <C-S-{>: >
1013 imap <C-[> [[[
Bram Moolenaar9a033d72020-10-07 17:29:48 +02001014 imap <C-{> {{{
1015Without modifyOtherKeys <C-[> and <C-{> are indistinguishable from Esc.
1016Note that <C-{> is used and not <C-S-[> or <C-S-{>. This works on most
1017keyboards. Similarly, <C-}> is used instead of <C-S-]> or <C-S-}> and
1018<C-|> instead of <C-S-\> or <C-S-|>. Note that '|' has a special meaning in a
1019mapping, see |map-bar|.
1020
1021WARNING: if you map <C-[> you may very well break any key codes that start
1022with Esc. Make sure it comes AFTER other mappings.
Bram Moolenaar4b570182019-10-20 19:53:22 +02001023
Bram Moolenaar733a69b2022-12-01 12:03:47 +00001024Starting with xterm version 377 Vim can detect the modifyOtherKeys state by
1025requesting it. For this the 't_RK' termcap entry is used. When the response
1026is found then Vim will know whether modifyOtherKeys level 2 is enabled, and
1027handle mappings accordingly.
1028
1029Before version 377 Vim automatically detects if the modifyOtherKeys mode was
1030enabled when it spots an escape sequence that must have been created by it.
1031To see if Vim detected such an escape sequence use `:verbose map`, the first
1032line will then show "Seen modifyOtherKeys: true" (possibly translated).
Bram Moolenaar9f62ea02022-10-19 13:07:03 +01001033
Bram Moolenaar938ae282023-02-20 20:44:55 +00001034This automatic detection depends on receiving an escape code starting with
Bram Moolenaar47f1fdc2022-11-24 13:27:36 +00001035"<1b>[27;". This is the normal way xterm sends these key codes. However, if
1036the *formatOtherKeys* resource is set another form is used that is not
1037recognized, therefore you must not set formatOtherKeys.
1038
Bram Moolenaar2547aa92020-07-26 17:00:44 +02001039A known side effect is that in Insert mode the raw escape sequence is inserted
1040after the CTRL-V key. This can be used to check whether modifyOtherKeys is
1041enabled: In Insert mode type CTRL-SHIFT-V CTRL-V, if you get one byte then
Bram Moolenaar47f1fdc2022-11-24 13:27:36 +00001042modifyOtherKeys is off, if you get <1b>[27;5;118~ then it is on.
Bram Moolenaar4b570182019-10-20 19:53:22 +02001043
Bram Moolenaar733a69b2022-12-01 12:03:47 +00001044Note that xterm up to version 376 has a bug that makes Shift-Esc send a
1045regular Esc code, the Shift modifier is dropped.
1046
Bram Moolenaar5ef1c6a2019-11-10 22:09:11 +01001047When the 'esckeys' option is off, then modifyOtherKeys will be disabled in
1048Insert mode to avoid every key with a modifier causing Insert mode to end.
1049
Bram Moolenaar4b570182019-10-20 19:53:22 +02001050
Bram Moolenaar4be18e72023-02-03 12:28:07 +000010511.13 MAPPING WITH KITTY KEYBOARD PROTOCOL *kitty-keyboard-protocol*
Bram Moolenaar63a2e362022-11-23 20:20:18 +00001052
1053If the value of 'term' contains "kitty" then Vim will send out an escape
1054sequence to enable the Kitty keyboard protocol. This can be changed with the
1055'keyprotocol' option.
1056
1057Like modifyOtherKeys, this will make it possible to distinguish between more
1058keys with modifiers. Also, this protocol sends an escape sequence for the Esc
1059key, so that Vim does not need to use a timeout to know whether receiving an
1060Esc character means the Esc key was pressed or it's the start of an escape
1061sequence.
1062
1063Vim automatically detects if the Kitty keyboard protocol was enabled when it
1064spots the response to the status request (this should be part of the |t_TI|
1065termcap entry). To see if Vim detected such an escape sequence use: >
1066 :verbose map
1067The first line will then show "Kitty keyboard protocol: {value}" (possibly
1068translated). The meaning of {value}:
1069 Unknown no status received yet
1070 Off protocol is not used
1071 On protocol is used
1072 Disabled protocol was used but expected to have been disabled
1073 by 't_TE'
Bram Moolenaardd60c362023-02-27 15:49:53 +00001074 Cleared protocol expected to have been disabled by 't_TE',
Bram Moolenaar938ae282023-02-20 20:44:55 +00001075 previous state is unknown
Bram Moolenaar63a2e362022-11-23 20:20:18 +00001076
1077
Bram Moolenaar4be18e72023-02-03 12:28:07 +000010781.14 MAPPING AN OPERATOR *:map-operator*
Bram Moolenaar5b962cf2005-12-12 21:58:40 +00001079
1080An operator is used before a {motion} command. To define your own operator
Bram Moolenaar1b884a02020-12-10 21:11:27 +01001081you must create a mapping that first sets the 'operatorfunc' option and then
Bram Moolenaar5b962cf2005-12-12 21:58:40 +00001082invoke the |g@| operator. After the user types the {motion} command the
1083specified function will be called.
1084
Bram Moolenaara40ceaf2006-01-13 22:35:40 +00001085 *g@* *E774* *E775*
Bram Moolenaar5b962cf2005-12-12 21:58:40 +00001086g@{motion} Call the function set by the 'operatorfunc' option.
1087 The '[ mark is positioned at the start of the text
1088 moved over by {motion}, the '] mark on the last
1089 character of the text.
1090 The function is called with one String argument:
1091 "line" {motion} was |linewise|
1092 "char" {motion} was |characterwise|
Bram Moolenaarf91787c2010-07-17 12:47:16 +02001093 "block" {motion} was |blockwise-visual|
Bram Moolenaarfa3b7232021-12-24 13:18:38 +00001094 The type can be forced, see |forced-motion|.
Bram Moolenaardb84e452010-08-15 13:50:43 +02001095 {not available when compiled without the |+eval|
Bram Moolenaar5b962cf2005-12-12 21:58:40 +00001096 feature}
1097
1098Here is an example that counts the number of spaces with <F4>: >
1099
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02001100 nnoremap <expr> <F4> CountSpaces()
1101 xnoremap <expr> <F4> CountSpaces()
1102 " doubling <F4> works on a line
1103 nnoremap <expr> <F4><F4> CountSpaces() .. '_'
Bram Moolenaar5b962cf2005-12-12 21:58:40 +00001104
Bram Moolenaarfa3b7232021-12-24 13:18:38 +00001105 function CountSpaces(context = {}, type = '') abort
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02001106 if a:type == ''
Bram Moolenaarfa3b7232021-12-24 13:18:38 +00001107 let context = #{
1108 \ dot_command: v:false,
1109 \ extend_block: '',
1110 \ virtualedit: [&l:virtualedit, &g:virtualedit],
1111 \ }
1112 let &operatorfunc = function('CountSpaces', [context])
Bram Moolenaar0e6adf82021-12-16 14:41:10 +00001113 set virtualedit=block
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02001114 return 'g@'
Bram Moolenaar0e6adf82021-12-16 14:41:10 +00001115 endif
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02001116
Bram Moolenaarfa3b7232021-12-24 13:18:38 +00001117 let save = #{
1118 \ clipboard: &clipboard,
1119 \ selection: &selection,
1120 \ virtualedit: [&l:virtualedit, &g:virtualedit],
1121 \ register: getreginfo('"'),
1122 \ visual_marks: [getpos("'<"), getpos("'>")],
1123 \ }
Bram Moolenaar5b962cf2005-12-12 21:58:40 +00001124
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02001125 try
Bram Moolenaar0e6adf82021-12-16 14:41:10 +00001126 set clipboard= selection=inclusive virtualedit=
Bram Moolenaarfa3b7232021-12-24 13:18:38 +00001127 let commands = #{
1128 \ line: "'[V']",
1129 \ char: "`[v`]",
1130 \ block: "`[\<C-V>`]",
1131 \ }[a:type]
1132 let [_, _, col, off] = getpos("']")
1133 if off != 0
1134 let vcol = getline("'[")->strpart(0, col + off)->strdisplaywidth()
1135 if vcol >= [line("'["), '$']->virtcol() - 1
1136 let a:context.extend_block = '$'
1137 else
1138 let a:context.extend_block = vcol .. '|'
1139 endif
1140 endif
1141 if a:context.extend_block != ''
1142 let commands ..= 'oO' .. a:context.extend_block
Bram Moolenaar0e6adf82021-12-16 14:41:10 +00001143 endif
1144 let commands ..= 'y'
1145 execute 'silent noautocmd keepjumps normal! ' .. commands
1146 echomsg getreg('"')->count(' ')
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02001147 finally
Bram Moolenaarfa3b7232021-12-24 13:18:38 +00001148 call setreg('"', save.register)
1149 call setpos("'<", save.visual_marks[0])
1150 call setpos("'>", save.visual_marks[1])
1151 let &clipboard = save.clipboard
1152 let &selection = save.selection
1153 let [&l:virtualedit, &g:virtualedit] = get(a:context.dot_command ? save : a:context, 'virtualedit')
1154 let a:context.dot_command = v:true
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02001155 endtry
Bram Moolenaar5b962cf2005-12-12 21:58:40 +00001156 endfunction
1157
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02001158An <expr> mapping is used to be able to fetch any prefixed count and register.
1159This also avoids using a command line, which would trigger CmdlineEnter and
1160CmdlineLeave autocommands.
1161
Bram Moolenaar5b962cf2005-12-12 21:58:40 +00001162Note that the 'selection' option is temporarily set to "inclusive" to be able
1163to yank exactly the right text by using Visual mode from the '[ to the ']
1164mark.
1165
Bram Moolenaar1c6737b2020-09-07 22:18:52 +02001166Also note that the 'clipboard' option is temporarily emptied to avoid
1167clobbering the `"*` or `"+` registers, if its value contains the item `unnamed`
1168or `unnamedplus`.
Bram Moolenaar5b962cf2005-12-12 21:58:40 +00001169
Bram Moolenaar079ba762021-10-23 12:08:41 +01001170The `mode()` function will return the state as it will be after applying the
1171operator.
1172
Yegappan Lakshmanan777175b2021-11-18 22:08:57 +00001173Here is an example for using a lambda function to create a normal-mode
1174operator to add quotes around text in the current line: >
1175
1176 nnoremap <F4> <Cmd>let &opfunc='{t ->
1177 \ getline(".")
1178 \ ->split("\\zs")
1179 \ ->insert("\"", col("'']"))
1180 \ ->insert("\"", col("''[") - 1)
1181 \ ->join("")
1182 \ ->setline(".")}'<CR>g@
1183
Bram Moolenaar071d4272004-06-13 20:20:40 +00001184==============================================================================
11852. Abbreviations *abbreviations* *Abbreviations*
1186
1187Abbreviations are used in Insert mode, Replace mode and Command-line mode.
1188If you enter a word that is an abbreviation, it is replaced with the word it
1189stands for. This can be used to save typing for often used long words. And
1190you can use it to automatically correct obvious spelling errors.
1191Examples:
1192
Bram Moolenaarc1762cc2007-05-10 16:56:30 +00001193 :iab ms Microsoft
Bram Moolenaar071d4272004-06-13 20:20:40 +00001194 :iab tihs this
1195
1196There are three types of abbreviations:
1197
1198full-id The "full-id" type consists entirely of keyword characters (letters
1199 and characters from 'iskeyword' option). This is the most common
1200 abbreviation.
1201
1202 Examples: "foo", "g3", "-1"
1203
1204end-id The "end-id" type ends in a keyword character, but all the other
1205 characters are not keyword characters.
1206
1207 Examples: "#i", "..f", "$/7"
1208
1209non-id The "non-id" type ends in a non-keyword character, the other
Bram Moolenaar34162142007-05-12 13:12:19 +00001210 characters may be of any type, excluding space and tab. {this type
Bram Moolenaar071d4272004-06-13 20:20:40 +00001211 is not supported by Vi}
1212
1213 Examples: "def#", "4/7$"
1214
1215Examples of strings that cannot be abbreviations: "a.b", "#def", "a b", "_$r"
1216
1217An abbreviation is only recognized when you type a non-keyword character.
Bram Moolenaar938ae282023-02-20 20:44:55 +00001218This can also be the <Esc> that ends Insert mode or the <CR> that ends a
Bram Moolenaar071d4272004-06-13 20:20:40 +00001219command. The non-keyword character which ends the abbreviation is inserted
1220after the expanded abbreviation. An exception to this is the character <C-]>,
1221which is used to expand an abbreviation without inserting any extra
1222characters.
1223
1224Example: >
1225 :ab hh hello
1226< "hh<Space>" is expanded to "hello<Space>"
1227 "hh<C-]>" is expanded to "hello"
1228
1229The characters before the cursor must match the abbreviation. Each type has
1230an additional rule:
1231
1232full-id In front of the match is a non-keyword character, or this is where
1233 the line or insertion starts. Exception: When the abbreviation is
1234 only one character, it is not recognized if there is a non-keyword
Bram Moolenaareb3dc872018-05-13 22:34:24 +02001235 character in front of it, other than a space or a tab. However, for
1236 the command line "'<,'>" (or any other marks) is ignored, as if the
1237 command line starts after it.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001238
Bram Moolenaar34162142007-05-12 13:12:19 +00001239end-id In front of the match is a keyword character, or a space or a tab,
Bram Moolenaar071d4272004-06-13 20:20:40 +00001240 or this is where the line or insertion starts.
1241
Bram Moolenaar34162142007-05-12 13:12:19 +00001242non-id In front of the match is a space, tab or the start of the line or
Bram Moolenaar071d4272004-06-13 20:20:40 +00001243 the insertion.
1244
1245Examples: ({CURSOR} is where you type a non-keyword character) >
1246 :ab foo four old otters
1247< " foo{CURSOR}" is expanded to " four old otters"
1248 " foobar{CURSOR}" is not expanded
1249 "barfoo{CURSOR}" is not expanded
1250>
1251 :ab #i #include
1252< "#i{CURSOR}" is expanded to "#include"
1253 ">#i{CURSOR}" is not expanded
1254>
Bram Moolenaar81695252004-12-29 20:58:21 +00001255 :ab ;; <endofline>
Bram Moolenaar071d4272004-06-13 20:20:40 +00001256< "test;;" is not expanded
1257 "test ;;" is expanded to "test <endofline>"
1258
Bram Moolenaar7d76c802014-10-15 22:51:52 +02001259To avoid the abbreviation in Insert mode: Type CTRL-V before the character
1260that would trigger the abbreviation. E.g. CTRL-V <Space>. Or type part of
1261the abbreviation, exit insert mode with <Esc>, re-enter insert mode with "a"
1262and type the rest.
1263
Bram Moolenaar071d4272004-06-13 20:20:40 +00001264To avoid the abbreviation in Command-line mode: Type CTRL-V twice somewhere in
1265the abbreviation to avoid it to be replaced. A CTRL-V in front of a normal
1266character is mostly ignored otherwise.
1267
1268It is possible to move the cursor after an abbreviation: >
1269 :iab if if ()<Left>
1270This does not work if 'cpoptions' includes the '<' flag. |<>|
1271
1272You can even do more complicated things. For example, to consume the space
1273typed after an abbreviation: >
1274 func Eatchar(pat)
Bram Moolenaar32466aa2006-02-24 23:53:04 +00001275 let c = nr2char(getchar(0))
Bram Moolenaar071d4272004-06-13 20:20:40 +00001276 return (c =~ a:pat) ? '' : c
1277 endfunc
1278 iabbr <silent> if if ()<Left><C-R>=Eatchar('\s')<CR>
1279
1280There are no default abbreviations.
1281
1282Abbreviations are never recursive. You can use ":ab f f-o-o" without any
1283problem. But abbreviations can be mapped. {some versions of Vi support
1284recursive abbreviations, for no apparent reason}
1285
1286Abbreviations are disabled if the 'paste' option is on.
1287
1288 *:abbreviate-local* *:abbreviate-<buffer>*
1289Just like mappings, abbreviations can be local to a buffer. This is mostly
1290used in a |filetype-plugin| file. Example for a C plugin file: >
1291 :abb <buffer> FF for (i = 0; i < ; ++i)
1292<
1293 *:ab* *:abbreviate*
1294:ab[breviate] list all abbreviations. The character in the first
1295 column indicates the mode where the abbreviation is
1296 used: 'i' for insert mode, 'c' for Command-line
1297 mode, '!' for both. These are the same as for
1298 mappings, see |map-listing|.
1299
Bram Moolenaare344bea2005-09-01 20:46:49 +00001300 *:abbreviate-verbose*
1301When 'verbose' is non-zero, listing an abbreviation will also display where it
1302was last defined. Example: >
1303
1304 :verbose abbreviate
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001305 ! teh the
Bram Moolenaare344bea2005-09-01 20:46:49 +00001306 Last set from /home/abcd/vim/abbr.vim
1307
1308See |:verbose-cmd| for more information.
1309
Bram Moolenaar071d4272004-06-13 20:20:40 +00001310:ab[breviate] {lhs} list the abbreviations that start with {lhs}
1311 You may need to insert a CTRL-V (type it twice) to
1312 avoid that a typed {lhs} is expanded, since
1313 command-line abbreviations apply here.
1314
Bram Moolenaar251e1912011-06-19 05:09:16 +02001315:ab[breviate] [<expr>] [<buffer>] {lhs} {rhs}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001316 add abbreviation for {lhs} to {rhs}. If {lhs} already
1317 existed it is replaced with the new {rhs}. {rhs} may
1318 contain spaces.
Bram Moolenaarfc1421e2006-04-20 22:17:20 +00001319 See |:map-<expr>| for the optional <expr> argument.
Bram Moolenaar251e1912011-06-19 05:09:16 +02001320 See |:map-<buffer>| for the optional <buffer> argument.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001321
1322 *:una* *:unabbreviate*
Bram Moolenaar95a9dd12019-12-19 22:12:03 +01001323:una[bbreviate] [<buffer>] {lhs}
1324 Remove abbreviation for {lhs} from the list. If none
Bram Moolenaar071d4272004-06-13 20:20:40 +00001325 is found, remove abbreviations in which {lhs} matches
1326 with the {rhs}. This is done so that you can even
1327 remove abbreviations after expansion. To avoid
1328 expansion insert a CTRL-V (type it twice).
1329
1330 *:norea* *:noreabbrev*
Bram Moolenaar251e1912011-06-19 05:09:16 +02001331:norea[bbrev] [<expr>] [<buffer>] [lhs] [rhs]
Bram Moolenaar25c9c682019-05-05 18:13:34 +02001332 Same as ":ab", but no remapping for this {rhs}.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001333
Bram Moolenaar61da1bf2019-06-06 12:14:49 +02001334 *:ca* *:cab* *:cabbrev*
Bram Moolenaar251e1912011-06-19 05:09:16 +02001335:ca[bbrev] [<expr>] [<buffer>] [lhs] [rhs]
Bram Moolenaar25c9c682019-05-05 18:13:34 +02001336 Same as ":ab", but for Command-line mode only.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001337
1338 *:cuna* *:cunabbrev*
Bram Moolenaar95a9dd12019-12-19 22:12:03 +01001339:cuna[bbrev] [<buffer>] {lhs}
1340 Same as ":una", but for Command-line mode only.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001341
1342 *:cnorea* *:cnoreabbrev*
Bram Moolenaar251e1912011-06-19 05:09:16 +02001343:cnorea[bbrev] [<expr>] [<buffer>] [lhs] [rhs]
Bram Moolenaar071d4272004-06-13 20:20:40 +00001344 same as ":ab", but for Command-line mode only and no
Bram Moolenaar25c9c682019-05-05 18:13:34 +02001345 remapping for this {rhs}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001346
1347 *:ia* *:iabbrev*
Bram Moolenaar251e1912011-06-19 05:09:16 +02001348:ia[bbrev] [<expr>] [<buffer>] [lhs] [rhs]
Bram Moolenaar25c9c682019-05-05 18:13:34 +02001349 Same as ":ab", but for Insert mode only.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001350
1351 *:iuna* *:iunabbrev*
Bram Moolenaar95a9dd12019-12-19 22:12:03 +01001352:iuna[bbrev] [<buffer>] {lhs}
1353 Same as ":una", but for insert mode only.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001354
1355 *:inorea* *:inoreabbrev*
Bram Moolenaar251e1912011-06-19 05:09:16 +02001356:inorea[bbrev] [<expr>] [<buffer>] [lhs] [rhs]
Bram Moolenaar25c9c682019-05-05 18:13:34 +02001357 Same as ":ab", but for Insert mode only and no
1358 remapping for this {rhs}.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001359
1360 *:abc* *:abclear*
Bram Moolenaar25c9c682019-05-05 18:13:34 +02001361:abc[lear] [<buffer>] Remove all abbreviations.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001362
1363 *:iabc* *:iabclear*
Bram Moolenaar25c9c682019-05-05 18:13:34 +02001364:iabc[lear] [<buffer>] Remove all abbreviations for Insert mode.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001365
1366 *:cabc* *:cabclear*
Bram Moolenaar25c9c682019-05-05 18:13:34 +02001367:cabc[lear] [<buffer>] Remove all abbreviations for Command-line mode.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001368
1369 *using_CTRL-V*
1370It is possible to use special characters in the rhs of an abbreviation.
1371CTRL-V has to be used to avoid the special meaning of most non printable
1372characters. How many CTRL-Vs need to be typed depends on how you enter the
1373abbreviation. This also applies to mappings. Let's use an example here.
1374
1375Suppose you want to abbreviate "esc" to enter an <Esc> character. When you
1376type the ":ab" command in Vim, you have to enter this: (here ^V is a CTRL-V
1377and ^[ is <Esc>)
1378
1379You type: ab esc ^V^V^V^V^V^[
1380
1381 All keyboard input is subjected to ^V quote interpretation, so
1382 the first, third, and fifth ^V characters simply allow the second,
1383 and fourth ^Vs, and the ^[, to be entered into the command-line.
1384
1385You see: ab esc ^V^V^[
1386
1387 The command-line contains two actual ^Vs before the ^[. This is
1388 how it should appear in your .exrc file, if you choose to go that
1389 route. The first ^V is there to quote the second ^V; the :ab
1390 command uses ^V as its own quote character, so you can include quoted
Bram Moolenaar81695252004-12-29 20:58:21 +00001391 whitespace or the | character in the abbreviation. The :ab command
Bram Moolenaar071d4272004-06-13 20:20:40 +00001392 doesn't do anything special with the ^[ character, so it doesn't need
1393 to be quoted. (Although quoting isn't harmful; that's why typing 7
1394 [but not 8!] ^Vs works.)
1395
1396Stored as: esc ^V^[
1397
1398 After parsing, the abbreviation's short form ("esc") and long form
1399 (the two characters "^V^[") are stored in the abbreviation table.
1400 If you give the :ab command with no arguments, this is how the
1401 abbreviation will be displayed.
1402
1403 Later, when the abbreviation is expanded because the user typed in
1404 the word "esc", the long form is subjected to the same type of
1405 ^V interpretation as keyboard input. So the ^V protects the ^[
Bram Moolenaar81695252004-12-29 20:58:21 +00001406 character from being interpreted as the "exit Insert mode" character.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001407 Instead, the ^[ is inserted into the text.
1408
1409Expands to: ^[
1410
1411[example given by Steve Kirkendall]
1412
1413==============================================================================
14143. Local mappings and functions *script-local*
1415
1416When using several Vim script files, there is the danger that mappings and
1417functions used in one script use the same name as in other scripts. To avoid
1418this, they can be made local to the script.
1419
1420 *<SID>* *<SNR>* *E81*
1421The string "<SID>" can be used in a mapping or menu. This requires that the
Bram Moolenaardd60c362023-02-27 15:49:53 +00001422'<' flag is not present in 'cpoptions'. This is useful if you have a
1423script-local function that you want to call from a mapping in the same script.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001424 When executing the map command, Vim will replace "<SID>" with the special
1425key code <SNR>, followed by a number that's unique for the script, and an
1426underscore. Example: >
1427 :map <SID>Add
Bram Moolenaardd60c362023-02-27 15:49:53 +00001428would define a mapping "<SNR>23_Add".
Bram Moolenaar071d4272004-06-13 20:20:40 +00001429
1430When defining a function in a script, "s:" can be prepended to the name to
Bram Moolenaar75ab5902022-04-18 15:36:40 +01001431make it local to the script (in |Vim9| script functions without a prefix are
1432local to the script). But when a mapping is executed from outside of
Bram Moolenaar071d4272004-06-13 20:20:40 +00001433the script, it doesn't know in which script the function was defined. To
1434avoid this problem, use "<SID>" instead of "s:". The same translation is done
1435as for mappings. This makes it possible to define a call to the function in
Bram Moolenaar81695252004-12-29 20:58:21 +00001436a mapping.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001437
1438When a local function is executed, it runs in the context of the script it was
1439defined in. This means that new functions and mappings it defines can also
1440use "s:" or "<SID>" and it will use the same unique number as when the
1441function itself was defined. Also, the "s:var" local script variables can be
1442used.
1443
1444When executing an autocommand or a user command, it will run in the context of
1445the script it was defined in. This makes it possible that the command calls a
1446local function or uses a local mapping.
1447
Bram Moolenaar90944302020-08-01 20:45:11 +02001448In case the value is used in a context where <SID> cannot be correctly
1449expanded, use the expand() function: >
1450 let &includexpr = expand('<SID>') .. 'My_includeexpr()'
1451
Bram Moolenaar071d4272004-06-13 20:20:40 +00001452Otherwise, using "<SID>" outside of a script context is an error.
1453
1454If you need to get the script number to use in a complicated script, you can
Bram Moolenaar4770d092006-01-12 23:22:24 +00001455use this function: >
Bram Moolenaar4466ad62020-11-21 13:16:30 +01001456 func s:ScriptNumber()
1457 return matchstr(expand('<SID>'), '<SNR>\zs\d\+\ze_')
1458 endfunc
Bram Moolenaar071d4272004-06-13 20:20:40 +00001459
1460The "<SNR>" will be shown when listing functions and mappings. This is useful
1461to find out what they are defined to.
1462
1463The |:scriptnames| command can be used to see which scripts have been sourced
1464and what their <SNR> number is.
1465
Bram Moolenaar25c9c682019-05-05 18:13:34 +02001466This is all {not available when compiled without the |+eval| feature}.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001467
1468==============================================================================
14694. User-defined commands *user-commands*
1470
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001471It is possible to define your own Ex commands. A user-defined command can act
Bram Moolenaar071d4272004-06-13 20:20:40 +00001472just like a built-in command (it can have a range or arguments, arguments can
1473be completed as filenames or buffer names, etc), except that when the command
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001474is executed, it is transformed into a normal Ex command and then executed.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001475
1476For starters: See section |40.2| in the user manual.
1477
Bram Moolenaar166af9b2010-11-16 20:34:40 +01001478 *E183* *E841* *user-cmd-ambiguous*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001479All user defined commands must start with an uppercase letter, to avoid
Bram Moolenaar166af9b2010-11-16 20:34:40 +01001480confusion with builtin commands. Exceptions are these builtin commands:
1481 :Next
1482 :X
1483They cannot be used for a user defined command. ":Print" is also an existing
1484command, but it is deprecated and can be overruled.
1485
1486The other characters of the user command can be uppercase letters, lowercase
1487letters or digits. When using digits, note that other commands that take a
1488numeric argument may become ambiguous. For example, the command ":Cc2" could
1489be the user command ":Cc2" without an argument, or the command ":Cc" with
1490argument "2". It is advised to put a space between the command name and the
1491argument to avoid these problems.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001492
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001493When using a user-defined command, the command can be abbreviated. However, if
1494an abbreviation is not unique, an error will be issued. Furthermore, a
Bram Moolenaar071d4272004-06-13 20:20:40 +00001495built-in command will always take precedence.
1496
1497Example: >
1498 :command Rename ...
1499 :command Renumber ...
1500 :Rena " Means "Rename"
1501 :Renu " Means "Renumber"
1502 :Ren " Error - ambiguous
1503 :command Paste ...
1504 :P " The built-in :Print
1505
1506It is recommended that full names for user-defined commands are used in
1507scripts.
1508
1509:com[mand] *:com* *:command*
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001510 List all user-defined commands. When listing commands,
Bram Moolenaara561a412019-04-25 21:27:58 +02001511 the characters in the first columns are:
Bram Moolenaar071d4272004-06-13 20:20:40 +00001512 ! Command has the -bang attribute
1513 " Command has the -register attribute
Bram Moolenaara561a412019-04-25 21:27:58 +02001514 | Command has the -bar attribute
Bram Moolenaar071d4272004-06-13 20:20:40 +00001515 b Command is local to current buffer
1516 (see below for details on attributes)
Bram Moolenaar818078d2016-08-27 21:58:42 +02001517 The list can be filtered on command name with
1518 |:filter|, e.g., to list all commands with "Pyth" in
1519 the name: >
1520 filter Pyth command
Bram Moolenaar071d4272004-06-13 20:20:40 +00001521
1522:com[mand] {cmd} List the user-defined commands that start with {cmd}
1523
Bram Moolenaar5b8d8fd2005-08-16 23:01:50 +00001524 *:command-verbose*
1525When 'verbose' is non-zero, listing a command will also display where it was
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00001526last defined and any completion argument. Example: >
Bram Moolenaar5b8d8fd2005-08-16 23:01:50 +00001527
1528 :verbose command TOhtml
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001529< Name Args Range Complete Definition ~
1530 TOhtml 0 % :call Convert2HTML(<line1>, <line2>) ~
1531 Last set from /usr/share/vim/vim-7.0/plugin/tohtml.vim ~
1532
Bram Moolenaar5195e452005-08-19 20:32:47 +00001533See |:verbose-cmd| for more information.
Bram Moolenaar5b8d8fd2005-08-16 23:01:50 +00001534
Bram Moolenaar071d4272004-06-13 20:20:40 +00001535 *E174* *E182*
Bram Moolenaar1b884a02020-12-10 21:11:27 +01001536:com[mand][!] [{attr}...] {cmd} {repl}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001537 Define a user command. The name of the command is
Bram Moolenaar1b884a02020-12-10 21:11:27 +01001538 {cmd} and its replacement text is {repl}. The
1539 command's attributes (see below) are {attr}. If the
1540 command already exists, an error is reported, unless a
1541 ! is specified, in which case the command is
1542 redefined. There is one exception: When sourcing a
1543 script again, a command that was previously defined in
1544 that script will be silently replaced.
Bram Moolenaar55d46912018-12-08 16:03:28 +01001545
Bram Moolenaar071d4272004-06-13 20:20:40 +00001546
1547:delc[ommand] {cmd} *:delc* *:delcommand* *E184*
1548 Delete the user-defined command {cmd}.
Bram Moolenaard13166e2022-11-18 21:49:57 +00001549 This is not allowed while listing commands, e.g. from
1550 a timer. *E1311*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001551
Bram Moolenaarbdcba242021-09-12 20:58:02 +02001552:delc[ommand] -buffer {cmd} *E1237*
1553 Delete the user-defined command {cmd} that was defined
1554 for the current buffer.
1555
Bram Moolenaar071d4272004-06-13 20:20:40 +00001556:comc[lear] *:comc* *:comclear*
1557 Delete all user-defined commands.
1558
Bram Moolenaar55d46912018-12-08 16:03:28 +01001559
1560Command attributes ~
Bram Moolenaar6ebe4f92022-10-28 20:47:54 +01001561 *command-attributes*
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001562User-defined commands are treated by Vim just like any other Ex commands. They
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001563can have arguments, or have a range specified. Arguments are subject to
1564completion as filenames, buffers, etc. Exactly how this works depends upon the
Bram Moolenaar071d4272004-06-13 20:20:40 +00001565command's attributes, which are specified when the command is defined.
1566
Bram Moolenaar71badf92023-04-22 22:40:14 +01001567When defining a user command in a script, it will be able to call functions
1568local to the script and use mappings local to the script. When the user
1569invokes the user command, it will run in the context of the script it was
1570defined in. This matters if |<SID>| is used in a command.
1571
Bram Moolenaar071d4272004-06-13 20:20:40 +00001572There are a number of attributes, split into four categories: argument
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001573handling, completion behavior, range handling, and special cases. The
Bram Moolenaar071d4272004-06-13 20:20:40 +00001574attributes are described below, by category.
1575
Bram Moolenaar071d4272004-06-13 20:20:40 +00001576
Bram Moolenaar55d46912018-12-08 16:03:28 +01001577Argument handling ~
1578 *E175* *E176* *:command-nargs*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001579By default, a user defined command will take no arguments (and an error is
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001580reported if any are supplied). However, it is possible to specify that the
1581command can take arguments, using the -nargs attribute. Valid cases are:
Bram Moolenaar071d4272004-06-13 20:20:40 +00001582
1583 -nargs=0 No arguments are allowed (the default)
Bram Moolenaar9d87a372018-12-18 21:41:50 +01001584 -nargs=1 Exactly one argument is required, it includes spaces
Bram Moolenaar446beb42011-05-10 17:18:44 +02001585 -nargs=* Any number of arguments are allowed (0, 1, or many),
1586 separated by white space
Bram Moolenaar071d4272004-06-13 20:20:40 +00001587 -nargs=? 0 or 1 arguments are allowed
1588 -nargs=+ Arguments must be supplied, but any number are allowed
1589
Bram Moolenaar34162142007-05-12 13:12:19 +00001590Arguments are considered to be separated by (unescaped) spaces or tabs in this
Bram Moolenaar446beb42011-05-10 17:18:44 +02001591context, except when there is one argument, then the white space is part of
1592the argument.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001593
1594Note that arguments are used as text, not as expressions. Specifically,
1595"s:var" will use the script-local variable in the script where the command was
1596defined, not where it is invoked! Example:
1597 script1.vim: >
1598 :let s:error = "None"
1599 :command -nargs=1 Error echoerr <args>
1600< script2.vim: >
1601 :source script1.vim
1602 :let s:error = "Wrong!"
1603 :Error s:error
Bram Moolenaara7241f52008-06-24 20:39:31 +00001604Executing script2.vim will result in "None" being echoed. Not what you
Bram Moolenaar071d4272004-06-13 20:20:40 +00001605intended! Calling a function may be an alternative.
1606
Bram Moolenaar55d46912018-12-08 16:03:28 +01001607
1608Completion behavior ~
Bram Moolenaar9d87a372018-12-18 21:41:50 +01001609 *:command-completion* *E179* *E180* *E181*
Bram Moolenaar55d46912018-12-08 16:03:28 +01001610 *:command-complete*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001611By default, the arguments of user defined commands do not undergo completion.
1612However, by specifying one or the other of the following attributes, argument
1613completion can be enabled:
1614
Bram Moolenaarcd43eff2018-03-29 15:55:38 +02001615 -complete=arglist file names in argument list
Bram Moolenaar071d4272004-06-13 20:20:40 +00001616 -complete=augroup autocmd groups
1617 -complete=buffer buffer names
Bram Moolenaar5ae636b2012-04-30 18:48:53 +02001618 -complete=behave :behave suboptions
Bram Moolenaare9edd7f2011-07-20 16:37:24 +02001619 -complete=color color schemes
Bram Moolenaar071d4272004-06-13 20:20:40 +00001620 -complete=command Ex command (and arguments)
Bram Moolenaare9edd7f2011-07-20 16:37:24 +02001621 -complete=compiler compilers
Bram Moolenaar4a748032010-09-30 21:47:56 +02001622 -complete=cscope |:cscope| suboptions
Bram Moolenaar071d4272004-06-13 20:20:40 +00001623 -complete=dir directory names
1624 -complete=environment environment variable names
1625 -complete=event autocommand events
1626 -complete=expression Vim expression
1627 -complete=file file and directory names
Bram Moolenaare9edd7f2011-07-20 16:37:24 +02001628 -complete=file_in_path file and directory names in |'path'|
Bram Moolenaara26559b2010-07-31 14:59:19 +02001629 -complete=filetype filetype names |'filetype'|
Bram Moolenaar071d4272004-06-13 20:20:40 +00001630 -complete=function function name
1631 -complete=help help subjects
1632 -complete=highlight highlight groups
Bram Moolenaar5ae636b2012-04-30 18:48:53 +02001633 -complete=history :history suboptions
Bram Moolenaare9edd7f2011-07-20 16:37:24 +02001634 -complete=locale locale names (as output of locale -a)
Bram Moolenaarcae92dc2017-08-06 15:22:15 +02001635 -complete=mapclear buffer argument
Bram Moolenaar071d4272004-06-13 20:20:40 +00001636 -complete=mapping mapping name
1637 -complete=menu menus
Bram Moolenaar9e507ca2016-10-15 15:39:39 +02001638 -complete=messages |:messages| suboptions
Bram Moolenaar071d4272004-06-13 20:20:40 +00001639 -complete=option options
Bram Moolenaar063b9d12016-07-09 20:21:48 +02001640 -complete=packadd optional package |pack-add| names
Bram Moolenaara26559b2010-07-31 14:59:19 +02001641 -complete=shellcmd Shell command
Bram Moolenaar4a748032010-09-30 21:47:56 +02001642 -complete=sign |:sign| suboptions
Bram Moolenaara26559b2010-07-31 14:59:19 +02001643 -complete=syntax syntax file names |'syntax'|
Bram Moolenaarcd9c4622013-06-08 15:24:48 +02001644 -complete=syntime |:syntime| suboptions
Bram Moolenaar071d4272004-06-13 20:20:40 +00001645 -complete=tag tags
1646 -complete=tag_listfiles tags, file names are shown when CTRL-D is hit
Bram Moolenaar24305862012-08-15 14:05:05 +02001647 -complete=user user names
Bram Moolenaar071d4272004-06-13 20:20:40 +00001648 -complete=var user variables
1649 -complete=custom,{func} custom completion, defined via {func}
Bram Moolenaara466c992005-07-09 21:03:22 +00001650 -complete=customlist,{func} custom completion, defined via {func}
Bram Moolenaar071d4272004-06-13 20:20:40 +00001651
Bram Moolenaar6f4754b2022-01-23 12:07:04 +00001652If you specify completion while there is nothing to complete (-nargs=0, the
1653default) then you get error *E1208* .
Bram Moolenaar3a991dd2014-10-02 01:41:41 +02001654Note: That some completion methods might expand environment variables.
1655
Bram Moolenaara5792f52005-11-23 21:25:05 +00001656
Bram Moolenaar55d46912018-12-08 16:03:28 +01001657Custom completion ~
1658 *:command-completion-custom*
1659 *:command-completion-customlist* *E467* *E468*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001660It is possible to define customized completion schemes via the "custom,{func}"
Bram Moolenaara466c992005-07-09 21:03:22 +00001661or the "customlist,{func}" completion argument. The {func} part should be a
Bram Moolenaara7241f52008-06-24 20:39:31 +00001662function with the following signature: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001663
1664 :function {func}(ArgLead, CmdLine, CursorPos)
1665
Bram Moolenaara466c992005-07-09 21:03:22 +00001666The function need not use all these arguments. The function should provide the
1667completion candidates as the return value.
1668
1669For the "custom" argument, the function should return the completion
1670candidates one per line in a newline separated string.
Bram Moolenaar9712ff12022-09-18 13:04:22 +01001671 *E1303*
Bram Moolenaara466c992005-07-09 21:03:22 +00001672For the "customlist" argument, the function should return the completion
Bram Moolenaara5792f52005-11-23 21:25:05 +00001673candidates as a Vim List. Non-string items in the list are ignored.
Bram Moolenaara466c992005-07-09 21:03:22 +00001674
1675The function arguments are:
Bram Moolenaar071d4272004-06-13 20:20:40 +00001676 ArgLead the leading portion of the argument currently being
1677 completed on
1678 CmdLine the entire command line
Bram Moolenaara5792f52005-11-23 21:25:05 +00001679 CursorPos the cursor position in it (byte index)
Bram Moolenaara466c992005-07-09 21:03:22 +00001680The function may use these for determining context. For the "custom"
1681argument, it is not necessary to filter candidates against the (implicit
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001682pattern in) ArgLead. Vim will filter the candidates with its regexp engine
Bram Moolenaar1588bc82022-03-08 21:35:07 +00001683after function return, and this is probably more efficient in most cases. If
1684'wildoptions' contains "fuzzy", then the candidates will be filtered using
1685|fuzzy-matching|. For the "customlist" argument, Vim will not
1686filter the returned completion candidates and the user supplied function
1687should filter the candidates.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001688
1689The following example lists user names to a Finger command >
1690 :com -complete=custom,ListUsers -nargs=1 Finger !finger <args>
1691 :fun ListUsers(A,L,P)
1692 : return system("cut -d: -f1 /etc/passwd")
1693 :endfun
1694
Bram Moolenaara466c992005-07-09 21:03:22 +00001695The following example completes filenames from the directories specified in
1696the 'path' option: >
1697 :com -nargs=1 -bang -complete=customlist,EditFileComplete
1698 \ EditFile edit<bang> <args>
1699 :fun EditFileComplete(A,L,P)
Bram Moolenaar8f3f58f2010-01-06 20:52:26 +01001700 : return split(globpath(&path, a:A), "\n")
Bram Moolenaara466c992005-07-09 21:03:22 +00001701 :endfun
1702<
Bram Moolenaar5ac3b1a2010-07-27 22:50:36 +02001703This example does not work for file names with spaces!
1704
Bram Moolenaara5792f52005-11-23 21:25:05 +00001705
Bram Moolenaar55d46912018-12-08 16:03:28 +01001706Range handling ~
1707 *E177* *E178* *:command-range* *:command-count*
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001708By default, user-defined commands do not accept a line number range. However,
Bram Moolenaar071d4272004-06-13 20:20:40 +00001709it is possible to specify that the command does take a range (the -range
1710attribute), or that it takes an arbitrary count value, either in the line
1711number position (-range=N, like the |:split| command) or as a "count"
Bram Moolenaar5c5b0942007-05-06 12:07:59 +00001712argument (-count=N, like the |:Next| command). The count will then be
1713available in the argument with |<count>|.
1714
1715Possible attributes are:
Bram Moolenaar071d4272004-06-13 20:20:40 +00001716
1717 -range Range allowed, default is current line
1718 -range=% Range allowed, default is whole file (1,$)
1719 -range=N A count (default N) which is specified in the line
Bram Moolenaar8e5af3e2011-04-28 19:02:44 +02001720 number position (like |:split|); allows for zero line
1721 number.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001722 -count=N A count (default N) which is specified either in the line
Bram Moolenaar32e7b2d2005-02-27 22:36:47 +00001723 number position, or as an initial argument (like |:Next|).
Bram Moolenaar86b48162022-12-06 18:20:10 +00001724 -count Acts like -count=0
Bram Moolenaar071d4272004-06-13 20:20:40 +00001725
1726Note that -range=N and -count=N are mutually exclusive - only one should be
1727specified.
1728
Bram Moolenaaraa3b15d2016-04-21 08:53:19 +02001729 *:command-addr*
Bram Moolenaarf1d6ccf2014-12-08 04:16:44 +01001730It is possible that the special characters in the range like ., $ or % which
1731by default correspond to the current line, last line and the whole buffer,
1732relate to arguments, (loaded) buffers, windows or tab pages.
1733
Bram Moolenaara561a412019-04-25 21:27:58 +02001734Possible values are (second column is the short name used in listing):
Bram Moolenaar938ae282023-02-20 20:44:55 +00001735 -addr=lines Range of lines (this is the default for -range)
Bram Moolenaara561a412019-04-25 21:27:58 +02001736 -addr=arguments arg Range for arguments
1737 -addr=buffers buf Range for buffers (also not loaded buffers)
1738 -addr=loaded_buffers load Range for loaded buffers
1739 -addr=windows win Range for windows
1740 -addr=tabs tab Range for tab pages
1741 -addr=quickfix qf Range for quickfix entries
Bram Moolenaar86b48162022-12-06 18:20:10 +00001742 -addr=other ? Other kind of range; can use ".", "$" and "%"
Bram Moolenaar25c9c682019-05-05 18:13:34 +02001743 as with "lines" (this is the default for
1744 -count)
Bram Moolenaarf1d6ccf2014-12-08 04:16:44 +01001745
Bram Moolenaar55d46912018-12-08 16:03:28 +01001746
1747Special cases ~
1748 *:command-bang* *:command-bar*
Bram Moolenaar5c5b0942007-05-06 12:07:59 +00001749 *:command-register* *:command-buffer*
Bram Moolenaar519cc552021-11-16 19:18:26 +00001750 *:command-keepscript*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001751There are some special cases as well:
1752
1753 -bang The command can take a ! modifier (like :q or :w)
1754 -bar The command can be followed by a "|" and another command.
1755 A "|" inside the command argument is not allowed then.
1756 Also checks for a " to start a comment.
1757 -register The first argument to the command can be an optional
1758 register name (like :del, :put, :yank).
1759 -buffer The command will only be available in the current buffer.
Bram Moolenaar58ef8a32021-11-12 11:25:11 +00001760 -keepscript Do not use the location of where the user command was
1761 defined for verbose messages, use the location of where
1762 the user command was invoked.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001763
1764In the cases of the -count and -register attributes, if the optional argument
1765is supplied, it is removed from the argument list and is available to the
1766replacement text separately.
Bram Moolenaar7cba6c02013-09-05 22:13:31 +02001767Note that these arguments can be abbreviated, but that is a deprecated
1768feature. Use the full name for new scripts.
Bram Moolenaar071d4272004-06-13 20:20:40 +00001769
Bram Moolenaar55d46912018-12-08 16:03:28 +01001770
1771Replacement text ~
Bram Moolenaar73b8b0a2021-08-01 14:52:32 +02001772 *:command-repl*
Bram Moolenaar5d7c2df2021-07-27 21:17:32 +02001773The {repl} argument is normally one long string, possibly with "|" separated
1774commands. A special case is when the argument is "{", then the following
1775lines, up to a line starting with "}" are used and |Vim9| syntax applies.
1776Example: >
1777 :command MyCommand {
1778 echo 'hello'
1779 g:calledMyCommand = true
1780 }
Bram Moolenaar63b91732021-08-05 20:40:03 +02001781< *E1231*
1782There must be white space before the "{". No nesting is supported, inline
1783functions cannot be used. Commands where a "|" may appear in the argument,
1784such as commands with an expression argument, cannot be followed by a "|" and
1785another command.
Bram Moolenaar5d7c2df2021-07-27 21:17:32 +02001786
Bram Moolenaar71badf92023-04-22 22:40:14 +01001787If the command is defined in Vim9 script (a script that starts with
1788`:vim9script` and in a `:def` function) then {repl} will be executed as in Vim9
1789script. Thus this depends on where the command is defined, not where it is
1790used.
1791
Bram Moolenaar1b884a02020-12-10 21:11:27 +01001792The replacement text {repl} for a user defined command is scanned for special
1793escape sequences, using <...> notation. Escape sequences are replaced with
1794values from the entered command line, and all other text is copied unchanged.
1795The resulting string is executed as an Ex command. To avoid the replacement
1796use <lt> in place of the initial <. Thus to include "<bang>" literally use
Bram Moolenaar371d5402006-03-20 21:47:49 +00001797"<lt>bang>".
Bram Moolenaar071d4272004-06-13 20:20:40 +00001798
1799The valid escape sequences are
1800
1801 *<line1>*
1802 <line1> The starting line of the command range.
1803 *<line2>*
1804 <line2> The final line of the command range.
Bram Moolenaarc168bd42017-09-10 17:34:35 +02001805 *<range>*
1806 <range> The number of items in the command range: 0, 1 or 2
Bram Moolenaar071d4272004-06-13 20:20:40 +00001807 *<count>*
1808 <count> Any count supplied (as described for the '-range'
1809 and '-count' attributes).
1810 *<bang>*
1811 <bang> (See the '-bang' attribute) Expands to a ! if the
1812 command was executed with a ! modifier, otherwise
1813 expands to nothing.
Bram Moolenaar1d59aa12020-09-19 18:50:13 +02001814 *<mods>* *<q-mods>* *:command-modifiers*
Bram Moolenaar63a60de2016-06-04 22:08:55 +02001815 <mods> The command modifiers, if specified. Otherwise, expands to
Bram Moolenaarc95a3022016-06-12 23:01:46 +02001816 nothing. Supported modifiers are |:aboveleft|, |:belowright|,
zeertzjqd3de1782022-09-01 12:58:52 +01001817 |:botright|, |:browse|, |:confirm|, |:hide|, |:horizontal|,
1818 |:keepalt|, |:keepjumps|, |:keepmarks|, |:keeppatterns|,
1819 |:leftabove|, |:lockmarks|, |:noautocmd|, |:noswapfile|
1820 |:rightbelow|, |:sandbox|, |:silent|, |:tab|, |:topleft|,
1821 |:unsilent|, |:verbose|, and |:vertical|.
zeertzjq9359e8a2022-07-03 13:16:09 +01001822 Note that |:filter| is not supported.
Bram Moolenaar63a60de2016-06-04 22:08:55 +02001823 Examples: >
1824 command! -nargs=+ -complete=file MyEdit
1825 \ for f in expand(<q-args>, 0, 1) |
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001826 \ exe '<mods> split ' .. f |
Bram Moolenaar63a60de2016-06-04 22:08:55 +02001827 \ endfor
1828
1829 function! SpecialEdit(files, mods)
1830 for f in expand(a:files, 0, 1)
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001831 exe a:mods .. ' split ' .. f
Bram Moolenaar63a60de2016-06-04 22:08:55 +02001832 endfor
1833 endfunction
1834 command! -nargs=+ -complete=file Sedit
1835 \ call SpecialEdit(<q-args>, <q-mods>)
1836<
Bram Moolenaar071d4272004-06-13 20:20:40 +00001837 *<reg>* *<register>*
1838 <reg> (See the '-register' attribute) The optional register,
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001839 if specified. Otherwise, expands to nothing. <register>
Bram Moolenaar071d4272004-06-13 20:20:40 +00001840 is a synonym for this.
1841 *<args>*
1842 <args> The command arguments, exactly as supplied (but as
1843 noted above, any count or register can consume some
1844 of the arguments, which are then not part of <args>).
1845 <lt> A single '<' (Less-Than) character. This is needed if you
1846 want to get a literal copy of one of these escape sequences
1847 into the expansion - for example, to get <bang>, use
1848 <lt>bang>.
1849
1850 *<q-args>*
1851If the first two characters of an escape sequence are "q-" (for example,
1852<q-args>) then the value is quoted in such a way as to make it a valid value
1853for use in an expression. This uses the argument as one single value.
Bram Moolenaar9fbdbb82022-09-27 17:30:34 +01001854When there is no argument <q-args> is an empty string. See the
1855|q-args-example| below.
Bram Moolenaar552f8a12007-03-08 17:12:08 +00001856 *<f-args>*
Bram Moolenaar071d4272004-06-13 20:20:40 +00001857To allow commands to pass their arguments on to a user-defined function, there
Bram Moolenaar402d2fe2005-04-15 21:00:38 +00001858is a special form <f-args> ("function args"). This splits the command
Bram Moolenaar34162142007-05-12 13:12:19 +00001859arguments at spaces and tabs, quotes each argument individually, and the
Bram Moolenaar071d4272004-06-13 20:20:40 +00001860<f-args> sequence is replaced by the comma-separated list of quoted arguments.
Bram Moolenaarc9b4b052006-04-30 18:54:39 +00001861See the Mycmd example below. If no arguments are given <f-args> is removed.
Bram Moolenaar552f8a12007-03-08 17:12:08 +00001862 To embed whitespace into an argument of <f-args>, prepend a backslash.
1863<f-args> replaces every pair of backslashes (\\) with one backslash. A
1864backslash followed by a character other than white space or a backslash
Bram Moolenaar9fbdbb82022-09-27 17:30:34 +01001865remains unmodified. Also see |f-args-example| below. Overview:
Bram Moolenaar552f8a12007-03-08 17:12:08 +00001866
1867 command <f-args> ~
1868 XX ab 'ab'
1869 XX a\b 'a\b'
1870 XX a\ b 'a b'
1871 XX a\ b 'a ', 'b'
1872 XX a\\b 'a\b'
1873 XX a\\ b 'a\', 'b'
1874 XX a\\\b 'a\\b'
1875 XX a\\\ b 'a\ b'
1876 XX a\\\\b 'a\\b'
1877 XX a\\\\ b 'a\\', 'b'
Bram Moolenaarb7398fe2023-05-14 18:50:25 +01001878 XX [nothing]
Bram Moolenaar071d4272004-06-13 20:20:40 +00001879
Bram Moolenaar9fbdbb82022-09-27 17:30:34 +01001880
Bram Moolenaarb7398fe2023-05-14 18:50:25 +01001881Note that if the "no arguments" situation is to be handled, you have to make
1882sure that the function can be called without arguments. For a compiled
1883function you might want to use variable arguments, see
1884|vim9-variable-arguments|.
1885
Bram Moolenaar9fbdbb82022-09-27 17:30:34 +01001886Examples for user commands: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001887
1888 " Delete everything after here to the end
1889 :com Ddel +,$d
1890
1891 " Rename the current buffer
1892 :com -nargs=1 -bang -complete=file Ren f <args>|w<bang>
1893
1894 " Replace a range with the contents of a file
1895 " (Enter this all as one line)
1896 :com -range -nargs=1 -complete=file
1897 Replace <line1>-pu_|<line1>,<line2>d|r <args>|<line1>d
1898
1899 " Count the number of lines in the range
Bram Moolenaar81695252004-12-29 20:58:21 +00001900 :com! -range -nargs=0 Lines echo <line2> - <line1> + 1 "lines"
Bram Moolenaar071d4272004-06-13 20:20:40 +00001901
Bram Moolenaar9fbdbb82022-09-27 17:30:34 +01001902< *f-args-example*
1903Call a user function (example of <f-args>) >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001904 :com -nargs=* Mycmd call Myfunc(<f-args>)
1905
1906When executed as: >
1907 :Mycmd arg1 arg2
1908This will invoke: >
1909 :call Myfunc("arg1","arg2")
1910
Bram Moolenaarb59ae592022-11-23 23:46:31 +00001911< *q-args-example*
Bram Moolenaar9fbdbb82022-09-27 17:30:34 +01001912A more substantial example: >
Bram Moolenaar071d4272004-06-13 20:20:40 +00001913 :function Allargs(command)
Bram Moolenaara7241f52008-06-24 20:39:31 +00001914 : let i = 0
1915 : while i < argc()
1916 : if filereadable(argv(i))
Bram Moolenaarc51cf032022-02-26 12:25:45 +00001917 : execute "e " .. argv(i)
Bram Moolenaar071d4272004-06-13 20:20:40 +00001918 : execute a:command
1919 : endif
1920 : let i = i + 1
1921 : endwhile
1922 :endfunction
1923 :command -nargs=+ -complete=command Allargs call Allargs(<q-args>)
1924
1925The command Allargs takes any Vim command(s) as argument and executes it on all
1926files in the argument list. Usage example (note use of the "e" flag to ignore
1927errors and the "update" command to write modified buffers): >
1928 :Allargs %s/foo/bar/ge|update
1929This will invoke: >
1930 :call Allargs("%s/foo/bar/ge|update")
1931<
Bram Moolenaar071d4272004-06-13 20:20:40 +00001932
Bram Moolenaar91f84f62018-07-29 15:07:52 +02001933 vim:tw=78:ts=8:noet:ft=help:norl: