Mercurial > vim
annotate runtime/doc/map.txt @ 32104:5a1113ece237 v9.0.1383
patch 9.0.1383: xxd: combination of little endian and cols fails
Commit: https://github.com/vim/vim/commit/4390d872b6c9498527a43fc7c30a5384f2e1db12
Author: Bram Moolenaar <Bram@vim.org>
Date: Sun Mar 5 20:17:39 2023 +0000
patch 9.0.1383: xxd: combination of little endian and cols fails
Problem: xxd: combination of little endian and cols fails. (Aapo
Rantalainen)
Solution: Round up the space taken by the hex output. (closes #12097)
author | Bram Moolenaar <Bram@vim.org> |
---|---|
date | Sun, 05 Mar 2023 21:30:03 +0100 |
parents | b2412874362f |
children | b2e8663e6dcc |
rev | line source |
---|---|
32061 | 1 *map.txt* For Vim version 9.0. Last change: 2023 Feb 27 |
7 | 2 |
3 | |
4 VIM REFERENCE MANUAL by Bram Moolenaar | |
5 | |
6 | |
7 Key mapping, abbreviations and user-defined commands. | |
8 | |
27036 | 9 This subject is introduced in sections |05.4|, |24.7| and |40.1| of the user |
7 | 10 manual. |
11 | |
12 1. Key mapping |key-mapping| | |
31192
dcde141f2d1e
patch 9.0.0930: cannot debug the Kitty keyboard protocol with TermDebug
Bram Moolenaar <Bram@vim.org>
parents:
31139
diff
changeset
|
13 1.1 MAP COMMANDS |:map-commands| |
dcde141f2d1e
patch 9.0.0930: cannot debug the Kitty keyboard protocol with TermDebug
Bram Moolenaar <Bram@vim.org>
parents:
31139
diff
changeset
|
14 1.2 Special arguments |:map-arguments| |
dcde141f2d1e
patch 9.0.0930: cannot debug the Kitty keyboard protocol with TermDebug
Bram Moolenaar <Bram@vim.org>
parents:
31139
diff
changeset
|
15 1.3 Mapping and modes |:map-modes| |
dcde141f2d1e
patch 9.0.0930: cannot debug the Kitty keyboard protocol with TermDebug
Bram Moolenaar <Bram@vim.org>
parents:
31139
diff
changeset
|
16 1.4 Listing mappings |map-listing| |
dcde141f2d1e
patch 9.0.0930: cannot debug the Kitty keyboard protocol with TermDebug
Bram Moolenaar <Bram@vim.org>
parents:
31139
diff
changeset
|
17 1.5 Mapping special keys |:map-special-keys| |
dcde141f2d1e
patch 9.0.0930: cannot debug the Kitty keyboard protocol with TermDebug
Bram Moolenaar <Bram@vim.org>
parents:
31139
diff
changeset
|
18 1.6 Special characters |:map-special-chars| |
dcde141f2d1e
patch 9.0.0930: cannot debug the Kitty keyboard protocol with TermDebug
Bram Moolenaar <Bram@vim.org>
parents:
31139
diff
changeset
|
19 1.7 What keys to map |map-which-keys| |
dcde141f2d1e
patch 9.0.0930: cannot debug the Kitty keyboard protocol with TermDebug
Bram Moolenaar <Bram@vim.org>
parents:
31139
diff
changeset
|
20 1.8 Examples |map-examples| |
dcde141f2d1e
patch 9.0.0930: cannot debug the Kitty keyboard protocol with TermDebug
Bram Moolenaar <Bram@vim.org>
parents:
31139
diff
changeset
|
21 1.9 Using mappings |map-typing| |
dcde141f2d1e
patch 9.0.0930: cannot debug the Kitty keyboard protocol with TermDebug
Bram Moolenaar <Bram@vim.org>
parents:
31139
diff
changeset
|
22 1.10 Mapping alt-keys |:map-alt-keys| |
31888
b374dfaa8645
patch 9.0.1276: some mappings with Meta and Shift do not work
Bram Moolenaar <Bram@vim.org>
parents:
31671
diff
changeset
|
23 1.11 Mapping meta-keys |:map-meta-keys| |
b374dfaa8645
patch 9.0.1276: some mappings with Meta and Shift do not work
Bram Moolenaar <Bram@vim.org>
parents:
31671
diff
changeset
|
24 1.12 Mapping in modifyOtherKeys mode |modifyOtherKeys| |
b374dfaa8645
patch 9.0.1276: some mappings with Meta and Shift do not work
Bram Moolenaar <Bram@vim.org>
parents:
31671
diff
changeset
|
25 1.13 Mapping with Kitty keyboard protocol |kitty-keyboard-protocol| |
b374dfaa8645
patch 9.0.1276: some mappings with Meta and Shift do not work
Bram Moolenaar <Bram@vim.org>
parents:
31671
diff
changeset
|
26 1.14 Mapping an operator |:map-operator| |
7 | 27 2. Abbreviations |abbreviations| |
28 3. Local mappings and functions |script-local| | |
29 4. User-defined commands |user-commands| | |
30 | |
31 ============================================================================== | |
32 1. Key mapping *key-mapping* *mapping* *macro* | |
33 | |
34 Key mapping is used to change the meaning of typed keys. The most common use | |
12559 | 35 is to define a sequence of commands for a function key. Example: > |
7 | 36 |
37 :map <F2> a<C-R>=strftime("%c")<CR><Esc> | |
38 | |
236 | 39 This appends the current date and time after the cursor (in <> notation |<>|). |
7 | 40 |
592 | 41 |
42 1.1 MAP COMMANDS *:map-commands* | |
43 | |
7 | 44 There are commands to enter new mappings, remove mappings and list mappings. |
45 See |map-overview| for the various forms of "map" and their relationships with | |
46 modes. | |
47 | |
48 {lhs} means left-hand-side *{lhs}* | |
49 {rhs} means right-hand-side *{rhs}* | |
50 | |
663 | 51 :map {lhs} {rhs} |mapmode-nvo| *:map* |
52 :nm[ap] {lhs} {rhs} |mapmode-n| *:nm* *:nmap* | |
53 :vm[ap] {lhs} {rhs} |mapmode-v| *:vm* *:vmap* | |
788 | 54 :xm[ap] {lhs} {rhs} |mapmode-x| *:xm* *:xmap* |
4358 | 55 :smap {lhs} {rhs} |mapmode-s| *:smap* |
663 | 56 :om[ap] {lhs} {rhs} |mapmode-o| *:om* *:omap* |
57 :map! {lhs} {rhs} |mapmode-ic| *:map!* | |
58 :im[ap] {lhs} {rhs} |mapmode-i| *:im* *:imap* | |
16944 | 59 :lm[ap] {lhs} {rhs} |mapmode-l| *:lm* *:lma* *:lmap* |
663 | 60 :cm[ap] {lhs} {rhs} |mapmode-c| *:cm* *:cmap* |
12499 | 61 :tma[p] {lhs} {rhs} |mapmode-t| *:tma* *:tmap* |
7 | 62 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. | |
26148 | 66 Note: Trailing spaces are included in the {rhs}, |
67 because space is a valid Normal mode command. | |
29066 | 68 See |map-trailing-white|. |
7 | 69 |
5968 | 70 *: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* | |
16944 | 75 :snor[emap] {lhs} {rhs} |mapmode-s| *:snor* *:snore* *:snoremap* |
5968 | 76 :ono[remap] {lhs} {rhs} |mapmode-o| *:ono* *:onoremap* |
77 :no[remap]! {lhs} {rhs} |mapmode-ic| *:no!* *:noremap!* | |
16944 | 78 :ino[remap] {lhs} {rhs} |mapmode-i| *:ino* *:inor* *:inoremap* |
5968 | 79 :ln[oremap] {lhs} {rhs} |mapmode-l| *:ln* *:lnoremap* |
16944 | 80 :cno[remap] {lhs} {rhs} |mapmode-c| *:cno* *:cnor* *:cnoremap* |
12457
dfb8254aa735
patch 8.0.1108: cannot specify mappings for the terminal window
Christian Brabandt <cb@256bit.org>
parents:
12419
diff
changeset
|
81 :tno[remap] {lhs} {rhs} |mapmode-t| *:tno* *:tnoremap* |
7 | 82 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 | |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16399
diff
changeset
|
85 used to redefine a command. |
27946
5147f3d3ed30
patch 8.2.4498: using <Plug> with "noremap" does not work
Bram Moolenaar <Bram@vim.org>
parents:
27903
diff
changeset
|
86 Note: When <Plug> appears in the {rhs} this part is |
5147f3d3ed30
patch 8.2.4498: using <Plug> with "noremap" does not work
Bram Moolenaar <Bram@vim.org>
parents:
27903
diff
changeset
|
87 always applied even if remapping is disallowed. |
7 | 88 |
89 | |
663 | 90 :unm[ap] {lhs} |mapmode-nvo| *:unm* *:unmap* |
91 :nun[map] {lhs} |mapmode-n| *:nun* *:nunmap* | |
92 :vu[nmap] {lhs} |mapmode-v| *:vu* *:vunmap* | |
788 | 93 :xu[nmap] {lhs} |mapmode-x| *:xu* *:xunmap* |
94 :sunm[ap] {lhs} |mapmode-s| *:sunm* *:sunmap* | |
663 | 95 :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* | |
16944 | 99 :cu[nmap] {lhs} |mapmode-c| *:cu* *:cun* *:cunmap* |
12499 | 100 :tunma[p] {lhs} |mapmode-t| *:tunma* *:tunmap* |
7 | 101 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. | |
26219 | 104 It also works when {lhs} matches the {rhs} of a |
27036 | 105 mapping. This is for when an abbreviation applied. |
29066 | 106 Note: Trailing spaces are included in the {lhs}. |
107 See |map-trailing-white|. | |
7 | 108 |
663 | 109 :mapc[lear] |mapmode-nvo| *:mapc* *:mapclear* |
110 :nmapc[lear] |mapmode-n| *:nmapc* *:nmapclear* | |
111 :vmapc[lear] |mapmode-v| *:vmapc* *:vmapclear* | |
788 | 112 :xmapc[lear] |mapmode-x| *:xmapc* *:xmapclear* |
113 :smapc[lear] |mapmode-s| *:smapc* *:smapclear* | |
663 | 114 :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* | |
12457
dfb8254aa735
patch 8.0.1108: cannot specify mappings for the terminal window
Christian Brabandt <cb@256bit.org>
parents:
12419
diff
changeset
|
119 :tmapc[lear] |mapmode-t| *:tmapc* *:tmapclear* |
7 | 120 Remove ALL mappings for the modes where the map |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16399
diff
changeset
|
121 command applies. |
2908 | 122 Use the <buffer> argument to remove buffer-local |
123 mappings |:map-<buffer>| | |
28808
0f0fed554cdc
Update runtime files, translations
Bram Moolenaar <Bram@vim.org>
parents:
28517
diff
changeset
|
124 Warning: This also removes the |mac-standard-mappings| |
0f0fed554cdc
Update runtime files, translations
Bram Moolenaar <Bram@vim.org>
parents:
28517
diff
changeset
|
125 and the |dos-standard-mappings|. |
7 | 126 |
663 | 127 :map |mapmode-nvo| |
128 :nm[ap] |mapmode-n| | |
129 :vm[ap] |mapmode-v| | |
788 | 130 :xm[ap] |mapmode-x| |
131 :sm[ap] |mapmode-s| | |
663 | 132 :om[ap] |mapmode-o| |
133 :map! |mapmode-ic| | |
134 :im[ap] |mapmode-i| | |
135 :lm[ap] |mapmode-l| | |
136 :cm[ap] |mapmode-c| | |
12499 | 137 :tma[p] |mapmode-t| |
7 | 138 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 | |
663 | 142 :map {lhs} |mapmode-nvo| *:map_l* |
143 :nm[ap] {lhs} |mapmode-n| *:nmap_l* | |
144 :vm[ap] {lhs} |mapmode-v| *:vmap_l* | |
788 | 145 :xm[ap] {lhs} |mapmode-x| *:xmap_l* |
146 :sm[ap] {lhs} |mapmode-s| *:smap_l* | |
663 | 147 :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* | |
12499 | 152 :tma[p] {lhs} |mapmode-t| *:tmap_l* |
7 | 153 List the key mappings for the key sequences starting |
154 with {lhs} in the modes where the map command applies. | |
155 | |
156 These commands are used to map a key or key sequence to a string of | |
157 characters. You can use this to put command sequences under function keys, | |
158 translate one key into another, etc. See |:mkexrc| for how to save and | |
159 restore the current mappings. | |
160 | |
592 | 161 *map-ambiguous* |
162 When two mappings start with the same sequence of characters, they are | |
163 ambiguous. Example: > | |
164 :imap aa foo | |
165 :imap aaa bar | |
166 When Vim has read "aa", it will need to get another character to be able to | |
167 decide if "aa" or "aaa" should be mapped. This means that after typing "aa" | |
168 that mapping won't get expanded yet, Vim is waiting for another character. | |
169 If you type a space, then "foo" will get inserted, plus the space. If you | |
170 type "a", then "bar" will get inserted. | |
171 | |
29066 | 172 Trailing white space ~ |
173 *map-trailing-white* | |
174 This unmap command does NOT work: > | |
175 :map @@ foo | |
176 :unmap @@ | print | |
177 | |
178 Because it tries to unmap "@@ ", including the white space before the command | |
179 separator "|". Other examples with trailing white space: > | |
180 unmap @@ | |
181 unmap @@ # Vim9 script comment | |
29290 | 182 unmap @@ " legacy script comment |
29066 | 183 |
184 An error will be issued, which is very hard to identify, because the ending | |
185 whitespace character in `unmap @@ ` is not visible. | |
186 | |
187 A generic solution is to put the command separator "|" right after the mapped | |
188 keys. After that white space and a comment may follow: > | |
189 | |
29290 | 190 unmap @@| # Vim9 script comment |
191 unmap @@| " legacy script comment | |
29066 | 192 |
592 | 193 |
194 1.2 SPECIAL ARGUMENTS *:map-arguments* | |
195 | |
5035
1cf89d38aa76
updated for version 7.3.1261
Bram Moolenaar <bram@vim.org>
parents:
4869
diff
changeset
|
196 "<buffer>", "<nowait>", "<silent>", "<special>", "<script>", "<expr>" and |
1cf89d38aa76
updated for version 7.3.1261
Bram Moolenaar <bram@vim.org>
parents:
4869
diff
changeset
|
197 "<unique>" can be used in any order. They must appear right after the |
1cf89d38aa76
updated for version 7.3.1261
Bram Moolenaar <bram@vim.org>
parents:
4869
diff
changeset
|
198 command, before any other arguments. |
721 | 199 |
29290 | 200 *:map-local* *:map-<buffer>* *:map-buffer* |
201 *E224* *E225* | |
1668 | 202 If the first argument to one of these commands is "<buffer>" the mapping will |
203 be effective in the current buffer only. Example: > | |
7 | 204 :map <buffer> ,w /[.,;]<CR> |
205 Then you can map ",w" to something else in another buffer: > | |
206 :map <buffer> ,w /[#&!]<CR> | |
5035
1cf89d38aa76
updated for version 7.3.1261
Bram Moolenaar <bram@vim.org>
parents:
4869
diff
changeset
|
207 The local buffer mappings are used before the global ones. See <nowait> below |
1cf89d38aa76
updated for version 7.3.1261
Bram Moolenaar <bram@vim.org>
parents:
4869
diff
changeset
|
208 to make a short local mapping not taking effect when a longer global one |
1cf89d38aa76
updated for version 7.3.1261
Bram Moolenaar <bram@vim.org>
parents:
4869
diff
changeset
|
209 exists. |
7 | 210 The "<buffer>" argument can also be used to clear mappings: > |
211 :unmap <buffer> ,w | |
212 :mapclear <buffer> | |
213 Local mappings are also cleared when a buffer is deleted, but not when it is | |
214 unloaded. Just like local option values. | |
4869 | 215 Also see |map-precedence|. |
7 | 216 |
5035
1cf89d38aa76
updated for version 7.3.1261
Bram Moolenaar <bram@vim.org>
parents:
4869
diff
changeset
|
217 *:map-<nowait>* *:map-nowait* |
1cf89d38aa76
updated for version 7.3.1261
Bram Moolenaar <bram@vim.org>
parents:
4869
diff
changeset
|
218 When defining a buffer-local mapping for "," there may be a global mapping |
1cf89d38aa76
updated for version 7.3.1261
Bram Moolenaar <bram@vim.org>
parents:
4869
diff
changeset
|
219 that starts with ",". Then you need to type another character for Vim to know |
1cf89d38aa76
updated for version 7.3.1261
Bram Moolenaar <bram@vim.org>
parents:
4869
diff
changeset
|
220 whether to use the "," mapping or the longer one. To avoid this add the |
1cf89d38aa76
updated for version 7.3.1261
Bram Moolenaar <bram@vim.org>
parents:
4869
diff
changeset
|
221 <nowait> argument. Then the mapping will be used when it matches, Vim does |
1cf89d38aa76
updated for version 7.3.1261
Bram Moolenaar <bram@vim.org>
parents:
4869
diff
changeset
|
222 not wait for more characters to be typed. However, if the characters were |
11473 | 223 already typed they are used. |
21991 | 224 Note that this works when the <nowait> mapping fully matches and is found |
225 before any partial matches. This works when: | |
226 - There is only one matching buffer-local mapping, since these are always | |
227 found before global mappings. | |
22171 | 228 - There is another buffer-local mapping that partly matches, but it is |
21991 | 229 defined earlier (last defined mapping is found first). |
5035
1cf89d38aa76
updated for version 7.3.1261
Bram Moolenaar <bram@vim.org>
parents:
4869
diff
changeset
|
230 |
7 | 231 *:map-<silent>* *:map-silent* |
232 To 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> | |
235 The search string will not be echoed when using this mapping. Messages from | |
236 the 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> | |
31097
4f709e5f24d2
patch 9.0.0883: a silent mapping may cause dots on the command line
Bram Moolenaar <Bram@vim.org>
parents:
30967
diff
changeset
|
239 Note that the effect of a command might also be silenced, e.g., when the |
4f709e5f24d2
patch 9.0.0883: a silent mapping may cause dots on the command line
Bram Moolenaar <Bram@vim.org>
parents:
30967
diff
changeset
|
240 mapping selects another entry for command line completion it won't be |
4f709e5f24d2
patch 9.0.0883: a silent mapping may cause dots on the command line
Bram Moolenaar <Bram@vim.org>
parents:
30967
diff
changeset
|
241 displayed. |
7 | 242 Prompts will still be given, e.g., for inputdialog(). |
243 Using "<silent>" for an abbreviation is possible, but will cause redrawing of | |
244 the command line to fail. | |
245 | |
859 | 246 *:map-<special>* *:map-special* |
247 Define a mapping with <> notation for special keys, even though the "<" flag | |
248 may 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 < | |
7 | 252 *:map-<script>* *:map-script* |
253 If the first argument to one of these commands is "<script>" and it is used to | |
254 define a new mapping or abbreviation, the mapping will only remap characters | |
255 in 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 | |
257 interfere (e.g., when CTRL-V is remapped in mswin.vim), but do use other | |
258 mappings defined in the script. | |
259 Note: ":map <script>" and ":noremap <script>" do the same thing. The | |
260 "<script>" overrules the command name. Using ":noremap <script>" is | |
261 preferred, because it's clearer that remapping is (mostly) disabled. | |
262 | |
26591 | 263 *:map-<unique>* *:map-unique* *E226* *E227* |
7 | 264 If the first argument to one of these commands is "<unique>" and it is used to |
265 define a new mapping or abbreviation, the command will fail if the mapping or | |
266 abbreviation already exists. Example: > | |
267 :map <unique> ,w /[#&!]<CR> | |
268 When defining a local mapping, there will also be a check if a global map | |
269 already exists which is equal. | |
270 Example of what will fail: > | |
271 :map ,w /[#&!]<CR> | |
272 :map <buffer> <unique> ,w /[.,;]<CR> | |
626 | 273 If you want to map a key and then have it do what it was originally mapped to, |
274 have a look at |maparg()|. | |
7 | 275 |
721 | 276 *:map-<expr>* *:map-expression* |
277 If the first argument to one of these commands is "<expr>" and it is used to | |
278 define a new mapping or abbreviation, the argument is an expression. The | |
279 expression is evaluated to obtain the {rhs} that is used. Example: > | |
24569 | 280 :inoremap <expr> . <SID>InsertDot() |
281 The result of the s:InsertDot() function will be inserted. It could check the | |
721 | 282 text before the cursor and start omni completion when some condition is met. |
24569 | 283 Using a script-local function is preferred, to avoid polluting the global |
284 namespace. Use <SID> in the RHS so that the script that the mapping was | |
285 defined in can be found. | |
721 | 286 |
1969 | 287 For abbreviations |v:char| is set to the character that was typed to trigger |
288 the abbreviation. You can use this to decide how to expand the {lhs}. You | |
3082 | 289 should not either insert or change the v:char. |
1969 | 290 |
22565 | 291 In case you want the mapping to not do anything, you can have the expression |
292 evaluate to an empty string. If something changed that requires Vim to | |
293 go through the main loop (e.g. to update the display), return "\<Ignore>". | |
294 This is similar to "nothing" but makes Vim return from the loop that waits for | |
295 input. Example: > | |
296 func s:OpenPopup() | |
297 call popup_create(... arguments ...) | |
298 return "\<Ignore>" | |
299 endfunc | |
24569 | 300 nnoremap <expr> <F3> <SID>OpenPopup() |
22565 | 301 |
27162 | 302 Keep in mind that the expression may be evaluated when looking for |
24142
34acfef7f60c
patch 8.2.2612: col('.') may get outdated column value
Bram Moolenaar <Bram@vim.org>
parents:
23164
diff
changeset
|
303 typeahead, before the previous command has been executed. For example: > |
34acfef7f60c
patch 8.2.2612: col('.') may get outdated column value
Bram Moolenaar <Bram@vim.org>
parents:
23164
diff
changeset
|
304 func StoreColumn() |
34acfef7f60c
patch 8.2.2612: col('.') may get outdated column value
Bram Moolenaar <Bram@vim.org>
parents:
23164
diff
changeset
|
305 let g:column = col('.') |
34acfef7f60c
patch 8.2.2612: col('.') may get outdated column value
Bram Moolenaar <Bram@vim.org>
parents:
23164
diff
changeset
|
306 return 'x' |
34acfef7f60c
patch 8.2.2612: col('.') may get outdated column value
Bram Moolenaar <Bram@vim.org>
parents:
23164
diff
changeset
|
307 endfunc |
34acfef7f60c
patch 8.2.2612: col('.') may get outdated column value
Bram Moolenaar <Bram@vim.org>
parents:
23164
diff
changeset
|
308 nnoremap <expr> x StoreColumn() |
34acfef7f60c
patch 8.2.2612: col('.') may get outdated column value
Bram Moolenaar <Bram@vim.org>
parents:
23164
diff
changeset
|
309 nmap ! f!x |
24278 | 310 You will notice that g:column has the value from before executing "f!", |
311 because "x" is evaluated before "f!" is executed. | |
24142
34acfef7f60c
patch 8.2.2612: col('.') may get outdated column value
Bram Moolenaar <Bram@vim.org>
parents:
23164
diff
changeset
|
312 This can be solved by inserting <Ignore> before the character that is |
34acfef7f60c
patch 8.2.2612: col('.') may get outdated column value
Bram Moolenaar <Bram@vim.org>
parents:
23164
diff
changeset
|
313 expression-mapped: > |
34acfef7f60c
patch 8.2.2612: col('.') may get outdated column value
Bram Moolenaar <Bram@vim.org>
parents:
23164
diff
changeset
|
314 nmap ! f!<Ignore>x |
34acfef7f60c
patch 8.2.2612: col('.') may get outdated column value
Bram Moolenaar <Bram@vim.org>
parents:
23164
diff
changeset
|
315 |
27140
a9eeb18e749c
patch 8.2.4099: Vim9: cannot use Vim9 syntax in mapping
Bram Moolenaar <Bram@vim.org>
parents:
27036
diff
changeset
|
316 When defining a mapping in a |Vim9| script, the expression will be evaluated |
a9eeb18e749c
patch 8.2.4099: Vim9: cannot use Vim9 syntax in mapping
Bram Moolenaar <Bram@vim.org>
parents:
27036
diff
changeset
|
317 in the context of that script. This means that script-local items can be |
a9eeb18e749c
patch 8.2.4099: Vim9: cannot use Vim9 syntax in mapping
Bram Moolenaar <Bram@vim.org>
parents:
27036
diff
changeset
|
318 accessed in the expression. |
a9eeb18e749c
patch 8.2.4099: Vim9: cannot use Vim9 syntax in mapping
Bram Moolenaar <Bram@vim.org>
parents:
27036
diff
changeset
|
319 |
721 | 320 Be very careful about side effects! The expression is evaluated while |
856 | 321 obtaining characters, you may very well make the command dysfunctional. |
322 For this reason the following is blocked: | |
1132 | 323 - Changing the buffer text |textlock|. |
324 - Editing another buffer. | |
325 - The |:normal| command. | |
326 - Moving the cursor is allowed, but it is restored afterwards. | |
856 | 327 If you want the mapping to do any of these let the returned characters do |
22862
6d50182e7e24
patch 8.2.1978: making a mapping work in all modes is complicated
Bram Moolenaar <Bram@vim.org>
parents:
22565
diff
changeset
|
328 that, or use a |<Cmd>| mapping instead. |
721 | 329 |
3153 | 330 You can use getchar(), it consumes typeahead if there is any. E.g., if you |
331 have these mappings: > | |
332 inoremap <expr> <C-L> nr2char(getchar()) | |
333 inoremap <expr> <C-L>x "foo" | |
334 If you now type CTRL-L nothing happens yet, Vim needs the next character to | |
335 decide what mapping to use. If you type 'x' the second mapping is used and | |
3224 | 336 "foo" is inserted. If you type any other key the first mapping is used, |
337 getchar() gets the typed key and returns it. | |
3153 | 338 |
721 | 339 Here 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 | |
27903 | 346 return g:counter .. '. ' |
721 | 347 endfunc |
348 | |
349 func ListReset() | |
350 let g:counter = 0 | |
351 return '' | |
352 endfunc | |
353 | |
727 | 354 CTRL-L inserts the next number, CTRL-R resets the count. CTRL-R returns an |
721 | 355 empty string, so that nothing is inserted. |
7 | 356 |
22171 | 357 Note that using 0x80 as a single byte before other text does not work, it will |
358 be seen as a special key. | |
837 | 359 |
22862
6d50182e7e24
patch 8.2.1978: making a mapping work in all modes is complicated
Bram Moolenaar <Bram@vim.org>
parents:
22565
diff
changeset
|
360 *<Cmd>* *:map-cmd* |
6d50182e7e24
patch 8.2.1978: making a mapping work in all modes is complicated
Bram Moolenaar <Bram@vim.org>
parents:
22565
diff
changeset
|
361 The special text <Cmd> begins a "command mapping", it executes the command |
6d50182e7e24
patch 8.2.1978: making a mapping work in all modes is complicated
Bram Moolenaar <Bram@vim.org>
parents:
22565
diff
changeset
|
362 directly without changing modes. Where you might use ":...<CR>" in the |
6d50182e7e24
patch 8.2.1978: making a mapping work in all modes is complicated
Bram Moolenaar <Bram@vim.org>
parents:
22565
diff
changeset
|
363 {rhs} of a mapping, you can instead use "<Cmd>...<CR>". |
6d50182e7e24
patch 8.2.1978: making a mapping work in all modes is complicated
Bram Moolenaar <Bram@vim.org>
parents:
22565
diff
changeset
|
364 Example: > |
6d50182e7e24
patch 8.2.1978: making a mapping work in all modes is complicated
Bram Moolenaar <Bram@vim.org>
parents:
22565
diff
changeset
|
365 noremap x <Cmd>echo mode(1)<CR> |
6d50182e7e24
patch 8.2.1978: making a mapping work in all modes is complicated
Bram Moolenaar <Bram@vim.org>
parents:
22565
diff
changeset
|
366 < |
6d50182e7e24
patch 8.2.1978: making a mapping work in all modes is complicated
Bram Moolenaar <Bram@vim.org>
parents:
22565
diff
changeset
|
367 This is more flexible than `:<C-U>` in Visual and Operator-pending mode, or |
6d50182e7e24
patch 8.2.1978: making a mapping work in all modes is complicated
Bram Moolenaar <Bram@vim.org>
parents:
22565
diff
changeset
|
368 `<C-O>:` in Insert mode, because the commands are executed directly in the |
6d50182e7e24
patch 8.2.1978: making a mapping work in all modes is complicated
Bram Moolenaar <Bram@vim.org>
parents:
22565
diff
changeset
|
369 current mode, instead of always going to Normal mode. Visual mode is |
6d50182e7e24
patch 8.2.1978: making a mapping work in all modes is complicated
Bram Moolenaar <Bram@vim.org>
parents:
22565
diff
changeset
|
370 preserved, so tricks with |gv| are not needed. Commands can be invoked |
6d50182e7e24
patch 8.2.1978: making a mapping work in all modes is complicated
Bram Moolenaar <Bram@vim.org>
parents:
22565
diff
changeset
|
371 directly in Command-line mode (which would otherwise require timer hacks). |
6d50182e7e24
patch 8.2.1978: making a mapping work in all modes is complicated
Bram Moolenaar <Bram@vim.org>
parents:
22565
diff
changeset
|
372 Example of using <Cmd> halfway Insert mode: > |
6d50182e7e24
patch 8.2.1978: making a mapping work in all modes is complicated
Bram Moolenaar <Bram@vim.org>
parents:
22565
diff
changeset
|
373 nnoremap <F3> aText <Cmd>echo mode(1)<CR> Added<Esc> |
6d50182e7e24
patch 8.2.1978: making a mapping work in all modes is complicated
Bram Moolenaar <Bram@vim.org>
parents:
22565
diff
changeset
|
374 |
6d50182e7e24
patch 8.2.1978: making a mapping work in all modes is complicated
Bram Moolenaar <Bram@vim.org>
parents:
22565
diff
changeset
|
375 Unlike <expr> mappings, there are no special restrictions on the <Cmd> |
22958 | 376 command: it is executed as if an (unrestricted) |autocommand| was invoked. |
22862
6d50182e7e24
patch 8.2.1978: making a mapping work in all modes is complicated
Bram Moolenaar <Bram@vim.org>
parents:
22565
diff
changeset
|
377 |
27140
a9eeb18e749c
patch 8.2.4099: Vim9: cannot use Vim9 syntax in mapping
Bram Moolenaar <Bram@vim.org>
parents:
27036
diff
changeset
|
378 *<ScriptCmd>* |
a9eeb18e749c
patch 8.2.4099: Vim9: cannot use Vim9 syntax in mapping
Bram Moolenaar <Bram@vim.org>
parents:
27036
diff
changeset
|
379 <ScriptCmd> is like <Cmd> but sets the context to the script the mapping was |
a9eeb18e749c
patch 8.2.4099: Vim9: cannot use Vim9 syntax in mapping
Bram Moolenaar <Bram@vim.org>
parents:
27036
diff
changeset
|
380 defined in, for the duration of the command execution. This is especially |
a9eeb18e749c
patch 8.2.4099: Vim9: cannot use Vim9 syntax in mapping
Bram Moolenaar <Bram@vim.org>
parents:
27036
diff
changeset
|
381 useful for |Vim9| script. It also works to access an import, which is useful |
29403 | 382 in a plugin using a, possibly autoloaded, script: > |
27140
a9eeb18e749c
patch 8.2.4099: Vim9: cannot use Vim9 syntax in mapping
Bram Moolenaar <Bram@vim.org>
parents:
27036
diff
changeset
|
383 vim9script |
a9eeb18e749c
patch 8.2.4099: Vim9: cannot use Vim9 syntax in mapping
Bram Moolenaar <Bram@vim.org>
parents:
27036
diff
changeset
|
384 import autoload 'implementation.vim' as impl |
27162 | 385 nnoremap <F4> <ScriptCmd>impl.DoTheWork()<CR> |
29403 | 386 < |
27140
a9eeb18e749c
patch 8.2.4099: Vim9: cannot use Vim9 syntax in mapping
Bram Moolenaar <Bram@vim.org>
parents:
27036
diff
changeset
|
387 No matter where <F4> is typed, the "impl" import will be found in the script |
29403 | 388 context of where the mapping was defined. When it's an autoload import, as in |
389 the example, the "implementation.vim" script will only be loaded once <F4> is | |
390 typed, not when the mapping is defined. | |
391 | |
392 Without <ScriptCmd> using "s:impl" would result in "E121: Undefined variable". | |
27140
a9eeb18e749c
patch 8.2.4099: Vim9: cannot use Vim9 syntax in mapping
Bram Moolenaar <Bram@vim.org>
parents:
27036
diff
changeset
|
393 |
22862
6d50182e7e24
patch 8.2.1978: making a mapping work in all modes is complicated
Bram Moolenaar <Bram@vim.org>
parents:
22565
diff
changeset
|
394 Note: |
27140
a9eeb18e749c
patch 8.2.4099: Vim9: cannot use Vim9 syntax in mapping
Bram Moolenaar <Bram@vim.org>
parents:
27036
diff
changeset
|
395 - Because <Cmd> and <ScriptCmd> avoid mode-changes it does not trigger |
a9eeb18e749c
patch 8.2.4099: Vim9: cannot use Vim9 syntax in mapping
Bram Moolenaar <Bram@vim.org>
parents:
27036
diff
changeset
|
396 |CmdlineEnter| and |CmdlineLeave| events, because no user interaction is |
a9eeb18e749c
patch 8.2.4099: Vim9: cannot use Vim9 syntax in mapping
Bram Moolenaar <Bram@vim.org>
parents:
27036
diff
changeset
|
397 expected. |
22862
6d50182e7e24
patch 8.2.1978: making a mapping work in all modes is complicated
Bram Moolenaar <Bram@vim.org>
parents:
22565
diff
changeset
|
398 - For the same reason, |keycodes| like <C-R><C-W> are interpreted as plain, |
6d50182e7e24
patch 8.2.1978: making a mapping work in all modes is complicated
Bram Moolenaar <Bram@vim.org>
parents:
22565
diff
changeset
|
399 unmapped keys. |
22958 | 400 - The command is not echo'ed, no need for <silent>. |
26219 | 401 - The {rhs} is not subject to abbreviations nor to other mappings, even if the |
402 mapping is recursive. | |
22958 | 403 - In Visual mode you can use `line('v')` and `col('v')` to get one end of the |
404 Visual area, the cursor is at the other end. | |
29236 | 405 |
26779 | 406 *E1255* *E1136* |
27140
a9eeb18e749c
patch 8.2.4099: Vim9: cannot use Vim9 syntax in mapping
Bram Moolenaar <Bram@vim.org>
parents:
27036
diff
changeset
|
407 <Cmd> and <ScriptCmd> commands must terminate, that is, they must be followed |
a9eeb18e749c
patch 8.2.4099: Vim9: cannot use Vim9 syntax in mapping
Bram Moolenaar <Bram@vim.org>
parents:
27036
diff
changeset
|
408 by <CR> in the {rhs} of the mapping definition. |Command-line| mode is never |
a9eeb18e749c
patch 8.2.4099: Vim9: cannot use Vim9 syntax in mapping
Bram Moolenaar <Bram@vim.org>
parents:
27036
diff
changeset
|
409 entered. |
22862
6d50182e7e24
patch 8.2.1978: making a mapping work in all modes is complicated
Bram Moolenaar <Bram@vim.org>
parents:
22565
diff
changeset
|
410 |
6d50182e7e24
patch 8.2.1978: making a mapping work in all modes is complicated
Bram Moolenaar <Bram@vim.org>
parents:
22565
diff
changeset
|
411 *E1137* |
27140
a9eeb18e749c
patch 8.2.4099: Vim9: cannot use Vim9 syntax in mapping
Bram Moolenaar <Bram@vim.org>
parents:
27036
diff
changeset
|
412 <Cmd> and <ScriptCmd> commands can have only normal characters and cannot |
a9eeb18e749c
patch 8.2.4099: Vim9: cannot use Vim9 syntax in mapping
Bram Moolenaar <Bram@vim.org>
parents:
27036
diff
changeset
|
413 contain special characters like function keys. |
22862
6d50182e7e24
patch 8.2.1978: making a mapping work in all modes is complicated
Bram Moolenaar <Bram@vim.org>
parents:
22565
diff
changeset
|
414 |
7 | 415 |
592 | 416 1.3 MAPPING AND MODES *:map-modes* |
1619 | 417 *mapmode-nvo* *mapmode-n* *mapmode-v* *mapmode-o* |
7 | 418 |
28010 | 419 There are seven sets of mappings |
7 | 420 - For Normal mode: When typing commands. |
421 - For Visual mode: When typing commands while the Visual area is highlighted. | |
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1969
diff
changeset
|
422 - For Select mode: like Visual mode but typing text replaces the selection. |
7 | 423 - For Operator-pending mode: When an operator is pending (after "d", "y", "c", |
1619 | 424 etc.). See below: |omap-info|. |
236 | 425 - For Insert mode. These are also used in Replace mode. |
7 | 426 - For Command-line mode: When entering a ":" or "/" command. |
28010 | 427 - For Terminal mode: When typing in a |:terminal| buffer. |
7 | 428 |
429 Special case: While typing a count for a command in Normal mode, mapping zero | |
430 is disabled. This makes it possible to map zero without making it impossible | |
431 to type a count with a zero. | |
432 | |
433 *map-overview* *map-modes* | |
5908 | 434 Overview of which map command works in which mode. More details below. |
435 COMMANDS MODES ~ | |
436 :map :noremap :unmap Normal, Visual, Select, Operator-pending | |
437 :nmap :nnoremap :nunmap Normal | |
438 :vmap :vnoremap :vunmap Visual and Select | |
439 :smap :snoremap :sunmap Select | |
440 :xmap :xnoremap :xunmap Visual | |
441 :omap :onoremap :ounmap Operator-pending | |
442 :map! :noremap! :unmap! Insert and Command-line | |
443 :imap :inoremap :iunmap Insert | |
444 :lmap :lnoremap :lunmap Insert, Command-line, Lang-Arg | |
445 :cmap :cnoremap :cunmap Command-line | |
12457
dfb8254aa735
patch 8.0.1108: cannot specify mappings for the terminal window
Christian Brabandt <cb@256bit.org>
parents:
12419
diff
changeset
|
446 :tmap :tnoremap :tunmap Terminal-Job |
7 | 447 |
24636 | 448 Same information in a table: |
449 *map-table* | |
450 Mode | Norm | Ins | Cmd | Vis | Sel | Opr | Term | Lang | ~ | |
451 Command +------+-----+-----+-----+-----+-----+------+------+ ~ | |
452 [nore]map | yes | - | - | yes | yes | yes | - | - | | |
453 n[nore]map | yes | - | - | - | - | - | - | - | | |
454 [nore]map! | - | yes | yes | - | - | - | - | - | | |
455 i[nore]map | - | yes | - | - | - | - | - | - | | |
456 c[nore]map | - | - | yes | - | - | - | - | - | | |
457 v[nore]map | - | - | - | yes | yes | - | - | - | | |
458 x[nore]map | - | - | - | yes | - | - | - | - | | |
459 s[nore]map | - | - | - | - | yes | - | - | - | | |
460 o[nore]map | - | - | - | - | - | yes | - | - | | |
461 t[nore]map | - | - | - | - | - | - | yes | - | | |
462 l[nore]map | - | yes | yes | - | - | - | - | yes | | |
463 | |
5908 | 464 |
465 COMMANDS MODES ~ | |
856 | 466 Normal Visual+Select Operator-pending ~ |
467 :map :noremap :unmap :mapclear yes yes yes | |
468 :nmap :nnoremap :nunmap :nmapclear yes - - | |
469 :vmap :vnoremap :vunmap :vmapclear - yes - | |
470 :omap :onoremap :ounmap :omapclear - - yes | |
788 | 471 |
826 | 472 :nunmap can also be used outside of a monastery. |
856 | 473 *mapmode-x* *mapmode-s* |
788 | 474 Some commands work both in Visual and Select mode, some in only one. Note |
475 that quite often "Visual" is mentioned where both Visual and Select mode | |
476 apply. |Select-mode-mapping| | |
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1969
diff
changeset
|
477 NOTE: Mapping a printable character in Select mode may confuse the user. It's |
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1969
diff
changeset
|
478 better to explicitly use :xmap and :smap for printable characters. Or use |
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1969
diff
changeset
|
479 :sunmap after defining the mapping. |
788 | 480 |
5908 | 481 COMMANDS MODES ~ |
856 | 482 Visual Select ~ |
483 :vmap :vnoremap :vunmap :vmapclear yes yes | |
484 :xmap :xnoremap :xunmap :xmapclear yes - | |
485 :smap :snoremap :sunmap :smapclear - yes | |
7 | 486 |
663 | 487 *mapmode-ic* *mapmode-i* *mapmode-c* *mapmode-l* |
788 | 488 Some commands work both in Insert mode and Command-line mode, some not: |
489 | |
5908 | 490 COMMANDS MODES ~ |
7 | 491 Insert Command-line Lang-Arg ~ |
492 :map! :noremap! :unmap! :mapclear! yes yes - | |
493 :imap :inoremap :iunmap :imapclear yes - - | |
494 :cmap :cnoremap :cunmap :cmapclear - yes - | |
495 :lmap :lnoremap :lunmap :lmapclear yes* yes* yes* | |
496 | |
18594 | 497 * If 'iminsert' is 1, see |language-mapping| below. |
498 | |
7 | 499 The original Vi did not have separate mappings for |
500 Normal/Visual/Operator-pending mode and for Insert/Command-line mode. | |
501 Therefore the ":map" and ":map!" commands enter and display mappings for | |
502 several modes. In Vim you can use the ":nmap", ":vmap", ":omap", ":cmap" and | |
503 ":imap" commands to enter mappings for each mode separately. | |
504 | |
12457
dfb8254aa735
patch 8.0.1108: cannot specify mappings for the terminal window
Christian Brabandt <cb@256bit.org>
parents:
12419
diff
changeset
|
505 *mapmode-t* |
dfb8254aa735
patch 8.0.1108: cannot specify mappings for the terminal window
Christian Brabandt <cb@256bit.org>
parents:
12419
diff
changeset
|
506 The terminal mappings are used in a terminal window, when typing keys for the |
dfb8254aa735
patch 8.0.1108: cannot specify mappings for the terminal window
Christian Brabandt <cb@256bit.org>
parents:
12419
diff
changeset
|
507 job running in the terminal. See |terminal-typing|. |
dfb8254aa735
patch 8.0.1108: cannot specify mappings for the terminal window
Christian Brabandt <cb@256bit.org>
parents:
12419
diff
changeset
|
508 |
1619 | 509 *omap-info* |
510 Operator-pending mappings can be used to define a movement command that can be | |
14864 | 511 used with any operator. Simple example: > |
512 :omap { w | |
513 makes "y{" work like "yw" and "d{" like "dw". | |
1619 | 514 |
515 To ignore the starting cursor position and select different text, you can have | |
516 the omap start Visual mode to select the text to be operated upon. Example | |
517 that operates on a function name in the current line: > | |
518 onoremap <silent> F :<C-U>normal! 0f(hviw<CR> | |
519 The CTRL-U (<C-U>) is used to remove the range that Vim may insert. The | |
520 Normal mode commands find the first '(' character and select the first word | |
521 before it. That usually is the function name. | |
522 | |
7 | 523 To enter a mapping for Normal and Visual mode, but not Operator-pending mode, |
14864 | 524 first define it for all three modes, then unmap it for |
525 Operator-pending mode: > | |
7 | 526 :map xx something-difficult |
527 :ounmap xx | |
14864 | 528 |
7 | 529 Likewise for a mapping for Visual and Operator-pending mode or Normal and |
530 Operator-pending mode. | |
531 | |
532 *language-mapping* | |
533 ":lmap" defines a mapping that applies to: | |
534 - Insert mode | |
535 - Command-line mode | |
536 - when entering a search pattern | |
537 - the argument of the commands that accept a text character, such as "r" and | |
538 "f" | |
539 - for the input() line | |
540 Generally: Whenever a character is to be typed that is part of the text in the | |
541 buffer, not a Vim command character. "Lang-Arg" isn't really another mode, | |
542 it's just used here for this situation. | |
543 The simplest way to load a set of related language mappings is by using the | |
544 'keymap' option. See |45.5|. | |
545 In Insert mode and in Command-line mode the mappings can be disabled with | |
5340 | 546 the CTRL-^ command |i_CTRL-^| |c_CTRL-^|. These commands change the value of |
5294 | 547 the 'iminsert' option. When starting to enter a normal command line (not a |
548 search pattern) the mappings are disabled until a CTRL-^ is typed. The state | |
549 last used is remembered for Insert mode and Search patterns separately. The | |
550 state for Insert mode is also used when typing a character as an argument to | |
551 command like "f" or "t". | |
7 | 552 Language mappings will never be applied to already mapped characters. They |
553 are only used for typed characters. This assumes that the language mapping | |
554 was already done when typing the mapping. | |
555 | |
556 | |
592 | 557 1.4 LISTING MAPPINGS *map-listing* |
558 | |
7 | 559 When listing mappings the characters in the first two columns are: |
560 | |
561 CHAR MODE ~ | |
1132 | 562 <Space> Normal, Visual, Select and Operator-pending |
7 | 563 n Normal |
1132 | 564 v Visual and Select |
565 s Select | |
566 x Visual | |
7 | 567 o Operator-pending |
568 ! Insert and Command-line | |
569 i Insert | |
570 l ":lmap" mappings for Insert, Command-line and Lang-Arg | |
571 c Command-line | |
12481
bcd9b3e4a5c8
patch 8.0.1120: :tm means :tmap instead of :tmenu
Christian Brabandt <cb@256bit.org>
parents:
12457
diff
changeset
|
572 t Terminal-Job |
7 | 573 |
574 Just before the {rhs} a special character can appear: | |
575 * indicates that it is not remappable | |
576 & indicates that only script-local mappings are remappable | |
577 @ indicates a buffer-local mapping | |
578 | |
579 Everything from the first non-blank after {lhs} up to the end of the line | |
580 (or '|') is considered to be part of {rhs}. This allows the {rhs} to end | |
581 with a space. | |
582 | |
583 Note: When using mappings for Visual mode, you can use the "'<" mark, which | |
584 is the start of the last selected Visual area in the current buffer |'<|. | |
585 | |
10004
8061455d9179
commit https://github.com/vim/vim/commit/818078ddfbb8cc2546f697c5675a251d095722ec
Christian Brabandt <cb@256bit.org>
parents:
9737
diff
changeset
|
586 The |:filter| command can be used to select what mappings to list. The |
8061455d9179
commit https://github.com/vim/vim/commit/818078ddfbb8cc2546f697c5675a251d095722ec
Christian Brabandt <cb@256bit.org>
parents:
9737
diff
changeset
|
587 pattern is matched against the {lhs} and {rhs} in the raw form. |
8061455d9179
commit https://github.com/vim/vim/commit/818078ddfbb8cc2546f697c5675a251d095722ec
Christian Brabandt <cb@256bit.org>
parents:
9737
diff
changeset
|
588 |
31139 | 589 While mappings are being listed, it is not possible to add or clear mappings, |
590 e.g. from a timer callback. *E1309* | |
591 | |
481 | 592 *:map-verbose* |
593 When 'verbose' is non-zero, listing a key map will also display where it was | |
594 last defined. Example: > | |
595 | |
596 :verbose map <C-W>* | |
597 n <C-W>* * <C-W><C-S>* | |
856 | 598 Last set from /home/abcd/.vimrc |
481 | 599 |
483 | 600 See |:verbose-cmd| for more information. |
481 | 601 |
592 | 602 |
603 1.5 MAPPING SPECIAL KEYS *:map-special-keys* | |
604 | |
605 There are three ways to map a special key: | |
606 1. The Vi-compatible method: Map the key code. Often this is a sequence that | |
607 starts with <Esc>. To enter a mapping like this you type ":map " and then | |
608 you have to type CTRL-V before hitting the function key. Note that when | |
609 the key code for the key is in the termcap (the t_ options), it will | |
610 automatically be translated into the internal code and become the second | |
611 way of mapping (unless the 'k' flag is included in 'cpoptions'). | |
612 2. The second method is to use the internal code for the function key. To | |
613 enter such a mapping type CTRL-K and then hit the function key, or use | |
614 the form "#1", "#2", .. "#9", "#0", "<Up>", "<S-Down>", "<S-F7>", etc. | |
615 (see table of keys |key-notation|, all keys from <Up> can be used). The | |
616 first ten function keys can be defined in two ways: Just the number, like | |
617 "#2", and with "<F>", like "<F2>". Both stand for function key 2. "#0" | |
618 refers to function key 10, defined with option 't_f10', which may be | |
619 function key zero on some keyboards. The <> form cannot be used when | |
620 'cpoptions' includes the '<' flag. | |
621 3. Use the termcap entry, with the form <t_xx>, where "xx" is the name of the | |
622 termcap entry. Any string entry can be used. For example: > | |
623 :map <t_F3> G | |
624 < Maps function key 13 to "G". This does not work if 'cpoptions' includes | |
625 the '<' flag. | |
626 | |
627 The advantage of the second and third method is that the mapping will work on | |
628 different terminals without modification (the function key will be | |
629 translated into the same internal code or the actual key code, no matter what | |
630 terminal you are using. The termcap must be correct for this to work, and you | |
631 must use the same mappings). | |
632 | |
633 DETAIL: Vim first checks if a sequence from the keyboard is mapped. If it | |
634 isn't the terminal key codes are tried (see |terminal-options|). If a | |
635 terminal code is found it is replaced with the internal code. Then the check | |
636 for a mapping is done again (so you can map an internal code to something | |
637 else). What is written into the script file depends on what is recognized. | |
638 If the terminal key code was recognized as a mapping the key code itself is | |
639 written to the script file. If it was recognized as a terminal code the | |
640 internal code is written to the script file. | |
641 | |
642 | |
643 1.6 SPECIAL CHARACTERS *:map-special-chars* | |
7597
3012eaddb6b2
commit https://github.com/vim/vim/commit/345efa013dc6d1754ba06e5596a26c48c9935937
Christian Brabandt <cb@256bit.org>
parents:
6447
diff
changeset
|
644 *map_backslash* *map-backslash* |
7 | 645 Note that only CTRL-V is mentioned here as a special character for mappings |
646 and abbreviations. When 'cpoptions' does not contain 'B', a backslash can | |
647 also be used like CTRL-V. The <> notation can be fully used then |<>|. But | |
648 you cannot use "<C-V>" like CTRL-V to escape the special meaning of what | |
649 follows. | |
650 | |
651 To map a backslash, or use a backslash literally in the {rhs}, the special | |
652 sequence "<Bslash>" can be used. This avoids the need to double backslashes | |
653 when using nested mappings. | |
654 | |
7597
3012eaddb6b2
commit https://github.com/vim/vim/commit/345efa013dc6d1754ba06e5596a26c48c9935937
Christian Brabandt <cb@256bit.org>
parents:
6447
diff
changeset
|
655 *map_CTRL-C* *map-CTRL-C* |
532 | 656 Using CTRL-C in the {lhs} is possible, but it will only work when Vim is |
657 waiting for a key, not when Vim is busy with something. When Vim is busy | |
658 CTRL-C interrupts/breaks the command. | |
659 When using the GUI version on MS-Windows CTRL-C can be mapped to allow a Copy | |
660 command to the clipboard. Use CTRL-Break to interrupt Vim. | |
7 | 661 |
7597
3012eaddb6b2
commit https://github.com/vim/vim/commit/345efa013dc6d1754ba06e5596a26c48c9935937
Christian Brabandt <cb@256bit.org>
parents:
6447
diff
changeset
|
662 *map_space_in_lhs* *map-space_in_lhs* |
7 | 663 To include a space in {lhs} precede it with a CTRL-V (type two CTRL-Vs for |
664 each space). | |
7597
3012eaddb6b2
commit https://github.com/vim/vim/commit/345efa013dc6d1754ba06e5596a26c48c9935937
Christian Brabandt <cb@256bit.org>
parents:
6447
diff
changeset
|
665 *map_space_in_rhs* *map-space_in_rhs* |
7 | 666 If you want a {rhs} that starts with a space, use "<Space>". To be fully Vi |
667 compatible (but unreadable) don't use the |<>| notation, precede {rhs} with a | |
668 single CTRL-V (you have to type CTRL-V two times). | |
7597
3012eaddb6b2
commit https://github.com/vim/vim/commit/345efa013dc6d1754ba06e5596a26c48c9935937
Christian Brabandt <cb@256bit.org>
parents:
6447
diff
changeset
|
669 *map_empty_rhs* *map-empty-rhs* |
7 | 670 You can create an empty {rhs} by typing nothing after a single CTRL-V (you |
671 have to type CTRL-V two times). Unfortunately, you cannot do this in a vimrc | |
672 file. | |
673 *<Nop>* | |
2826 | 674 An easier way to get a mapping that doesn't produce anything, is to use |
675 "<Nop>" for the {rhs}. This only works when the |<>| notation is enabled. | |
676 For example, to make sure that function key 8 does nothing at all: > | |
7 | 677 :map <F8> <Nop> |
678 :map! <F8> <Nop> | |
679 < | |
592 | 680 *map-multibyte* |
681 It is possible to map multibyte characters, but only the whole character. You | |
682 cannot map the first byte only. This was done to prevent problems in this | |
683 scenario: > | |
684 :set encoding=latin1 | |
685 :imap <M-C> foo | |
686 :set encoding=utf-8 | |
687 The mapping for <M-C> is defined with the latin1 encoding, resulting in a 0xc3 | |
13857 | 688 byte. If you type the character á (0xe1 <M-a>) in UTF-8 encoding this is the |
2826 | 689 two bytes 0xc3 0xa1. You don't want the 0xc3 byte to be mapped then or |
13857 | 690 otherwise it would be impossible to type the á character. |
592 | 691 |
7 | 692 *<Leader>* *mapleader* |
29450 | 693 To define a mapping which uses the "g:mapleader" variable, the special string |
694 "<Leader>" can be used. It is replaced with the string value of | |
695 "g:mapleader". If "g:mapleader" is not set or empty, a backslash is used | |
696 instead. Example: > | |
697 map <Leader>A oanother line<Esc> | |
7 | 698 Works like: > |
29450 | 699 map \A oanother line<Esc> |
700 But after (legacy script): > | |
701 let mapleader = "," | |
702 Or (Vim9 script): > | |
703 g:mapleader = "," | |
7 | 704 It works like: > |
29450 | 705 map ,A oanother line<Esc> |
7 | 706 |
29450 | 707 Note that the value of "g:mapleader" is used at the moment the mapping is |
708 defined. Changing "g:mapleader" after that has no effect for already defined | |
7 | 709 mappings. |
710 | |
711 *<LocalLeader>* *maplocalleader* | |
1619 | 712 <LocalLeader> is just like <Leader>, except that it uses "maplocalleader" |
713 instead of "mapleader". <LocalLeader> is to be used for mappings which are | |
714 local to a buffer. Example: > | |
3312 | 715 :map <buffer> <LocalLeader>A oanother line<Esc> |
7 | 716 < |
717 In a global plugin <Leader> should be used and in a filetype plugin | |
718 <LocalLeader>. "mapleader" and "maplocalleader" can be equal. Although, if | |
719 you make them different, there is a smaller chance of mappings from global | |
720 plugins to clash with mappings for filetype plugins. For example, you could | |
721 keep "mapleader" at the default backslash, and set "maplocalleader" to an | |
722 underscore. | |
723 | |
724 *map-<SID>* | |
725 In a script the special key name "<SID>" can be used to define a mapping | |
726 that's local to the script. See |<SID>| for details. | |
727 | |
728 *<Plug>* | |
729 The special key name "<Plug>" can be used for an internal mapping, which is | |
730 not to be matched with any key sequence. This is useful in plugins | |
731 |using-<Plug>|. | |
732 | |
28379 | 733 *<MouseMove>* |
734 The special key name "<MouseMove>" can be used to handle mouse movement. It | |
735 needs to be enabled with 'mousemoveevent'. Currently only works in the GUI. | |
28933 | 736 The |getmousepos()| function can be used to obtain the mouse position. |
28379 | 737 |
7 | 738 *<Char>* *<Char->* |
739 To map a character by its decimal, octal or hexadecimal number the <Char> | |
740 construct can be used: | |
741 <Char-123> character 123 | |
742 <Char-033> character 27 | |
743 <Char-0x7f> character 127 | |
3082 | 744 <S-Char-114> character 114 ('r') shifted ('R') |
21991 | 745 This is useful to specify a (multibyte) character in a 'keymap' file. |
7 | 746 Upper and lowercase differences are ignored. |
747 | |
748 *map-comments* | |
749 It is not possible to put a comment after these commands, because the '"' | |
11160 | 750 character is considered to be part of the {lhs} or {rhs}. However, one can |
751 use |", since this starts a new, empty command with a comment. | |
7 | 752 |
7597
3012eaddb6b2
commit https://github.com/vim/vim/commit/345efa013dc6d1754ba06e5596a26c48c9935937
Christian Brabandt <cb@256bit.org>
parents:
6447
diff
changeset
|
753 *map_bar* *map-bar* |
7 | 754 Since the '|' character is used to separate a map command from the next |
755 command, you will have to do something special to include a '|' in {rhs}. | |
756 There are three methods: | |
757 use works when example ~ | |
758 <Bar> '<' is not in 'cpoptions' :map _l :!ls <Bar> more^M | |
759 \| 'b' is not in 'cpoptions' :map _l :!ls \| more^M | |
760 ^V| always, in Vim and Vi :map _l :!ls ^V| more^M | |
761 | |
762 (here ^V stands for CTRL-V; to get one CTRL-V you have to type it twice; you | |
763 cannot use the <> notation "<C-V>" here). | |
764 | |
765 All three work when you use the default setting for 'cpoptions'. | |
766 | |
767 When 'b' is present in 'cpoptions', "\|" will be recognized as a mapping | |
768 ending in a '\' and then another command. This is Vi compatible, but | |
769 illogical when compared to other commands. | |
770 | |
7597
3012eaddb6b2
commit https://github.com/vim/vim/commit/345efa013dc6d1754ba06e5596a26c48c9935937
Christian Brabandt <cb@256bit.org>
parents:
6447
diff
changeset
|
771 *map_return* *map-return* |
7 | 772 When you have a mapping that contains an Ex command, you need to put a line |
773 terminator after it to have it executed. The use of <CR> is recommended for | |
774 this (see |<>|). Example: > | |
5692
80e5f9584b02
Update runtime files. Add Euphoria syntax files.
Bram Moolenaar <bram@vim.org>
parents:
5340
diff
changeset
|
775 :map _ls :!ls -l %:S<CR>:echo "the end"<CR> |
7 | 776 |
777 To avoid mapping of the characters you type in insert or Command-line mode, | |
778 type a CTRL-V first. The mapping in Insert mode is disabled if the 'paste' | |
779 option is on. | |
5239 | 780 *map-error* |
31671 | 781 Note that when an error is encountered (that causes an error message or might |
782 cause a beep) the rest of the mapping is not executed. This is Vi-compatible. | |
7 | 783 |
784 Note that the second character (argument) of the commands @zZtTfF[]rm'`"v | |
785 and CTRL-X is not mapped. This was done to be able to use all the named | |
786 registers and marks, even when the command with the same name has been | |
787 mapped. | |
788 | |
592 | 789 |
790 1.7 WHAT KEYS TO MAP *map-which-keys* | |
791 | |
7 | 792 If you are going to map something, you will need to choose which key(s) to use |
793 for the {lhs}. You will have to avoid keys that are used for Vim commands, | |
794 otherwise you would not be able to use those commands anymore. Here are a few | |
795 suggestions: | |
796 - Function keys <F2>, <F3>, etc.. Also the shifted function keys <S-F1>, | |
797 <S-F2>, etc. Note that <F1> is already used for the help command. | |
31888
b374dfaa8645
patch 9.0.1276: some mappings with Meta and Shift do not work
Bram Moolenaar <Bram@vim.org>
parents:
31671
diff
changeset
|
798 - Any key with the Alt or Meta key pressed. Depending on your keyboard |
b374dfaa8645
patch 9.0.1276: some mappings with Meta and Shift do not work
Bram Moolenaar <Bram@vim.org>
parents:
31671
diff
changeset
|
799 accented characters may be used as well. |:map-alt-keys| |
7 | 800 - Use the '_' or ',' character and then any other character. The "_" and "," |
801 commands do exist in Vim (see |_| and |,|), but you probably never use them. | |
802 - Use a key that is a synonym for another command. For example: CTRL-P and | |
803 CTRL-N. Use an extra character to allow more mappings. | |
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1969
diff
changeset
|
804 - The key defined by <Leader> and one or more other keys. This is especially |
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1969
diff
changeset
|
805 useful in scripts. |mapleader| |
7 | 806 |
807 See the file "index" for keys that are not used and thus can be mapped without | |
808 losing any builtin function. You can also use ":help {key}^D" to find out if | |
809 a key is used for some command. ({key} is the specific key you want to find | |
810 out about, ^D is CTRL-D). | |
811 | |
592 | 812 |
813 1.8 EXAMPLES *map-examples* | |
814 | |
7 | 815 A few examples (given as you type them, for "<CR>" you type four characters; |
816 the '<' flag must not be present in 'cpoptions' for this to work). > | |
817 | |
818 :map <F3> o#include | |
819 :map <M-g> /foo<CR>cwbar<Esc> | |
820 :map _x d/END/e<CR> | |
821 :map! qq quadrillion questions | |
1132 | 822 |
823 | |
824 Multiplying a count | |
825 | |
826 When you type a count before triggering a mapping, it's like the count was | |
827 typed before the {lhs}. For example, with this mapping: > | |
828 :map <F4> 3w | |
829 Typing 2<F4> will result in "23w". Thus not moving 2 * 3 words but 23 words. | |
830 If you want to multiply counts use the expression register: > | |
831 :map <F4> @='3w'<CR> | |
832 The part between quotes is the expression being executed. |@=| | |
833 | |
592 | 834 |
835 1.9 USING MAPPINGS *map-typing* | |
836 | |
7 | 837 Vim will compare what you type with the start of a mapped sequence. If there |
838 is an incomplete match, it will get more characters until there either is a | |
839 complete match or until there is no match at all. Example: If you map! "qq", | |
840 the first 'q' will not appear on the screen until you type another | |
841 character. This is because Vim cannot know if the next character will be a | |
842 'q' or not. If the 'timeout' option is on (which is the default) Vim will | |
843 only wait for one second (or as long as specified with the 'timeoutlen' | |
844 option). After that it assumes that the 'q' is to be interpreted as such. If | |
845 you type slowly, or your system is slow, reset the 'timeout' option. Then you | |
846 might want to set the 'ttimeout' option. | |
847 | |
32004 | 848 *map-precedence* |
4869 | 849 Buffer-local mappings (defined using |:map-<buffer>|) take precedence over |
850 global mappings. When a buffer-local mapping is the same as a global mapping, | |
851 Vim will use the buffer-local mapping. In addition, Vim will use a complete | |
5055 | 852 mapping immediately if it was defined with <nowait>, even if a longer mapping |
853 has the same prefix. For example, given the following two mappings: > | |
854 :map <buffer> <nowait> \a :echo "Local \a"<CR> | |
855 :map \abc :echo "Global \abc"<CR> | |
856 When typing \a the buffer-local mapping will be used immediately. Vim will | |
857 not wait for more characters to see if the user might be typing \abc. | |
4869 | 858 |
7 | 859 *map-keys-fails* |
588 | 860 There are situations where key codes might not be recognized: |
7 | 861 - Vim can only read part of the key code. Mostly this is only the first |
862 character. This happens on some Unix versions in an xterm. | |
863 - The key code is after character(s) that are mapped. E.g., "<F1><F1>" or | |
864 "g<F1>". | |
588 | 865 |
7 | 866 The result is that the key code is not recognized in this situation, and the |
588 | 867 mapping fails. There are two actions needed to avoid this problem: |
868 | |
7 | 869 - Remove the 'K' flag from 'cpoptions'. This will make Vim wait for the rest |
870 of the characters of the function key. | |
871 - When using <F1> to <F4> the actual key code generated may correspond to | |
872 <xF1> to <xF4>. There are mappings from <xF1> to <F1>, <xF2> to <F2>, etc., | |
873 but these are not recognized after another half a mapping. Make sure the | |
874 key codes for <F1> to <F4> are correct: > | |
875 :set <F1>=<type CTRL-V><type F1> | |
876 < Type the <F1> as four characters. The part after the "=" must be done with | |
877 the actual keys, not the literal text. | |
878 Another solution is to use the actual key code in the mapping for the second | |
879 special key: > | |
880 :map <F1><Esc>OP :echo "yes"<CR> | |
881 Don't type a real <Esc>, Vim will recognize the key code and replace it with | |
882 <F1> anyway. | |
883 | |
588 | 884 Another problem may be that when keeping ALT or Meta pressed the terminal |
885 prepends ESC instead of setting the 8th bit. See |:map-alt-keys|. | |
886 | |
7 | 887 *recursive_mapping* |
888 If you include the {lhs} in the {rhs} you have a recursive mapping. When | |
889 {lhs} is typed, it will be replaced with {rhs}. When the {lhs} which is | |
890 included in {rhs} is encountered it will be replaced with {rhs}, and so on. | |
891 This makes it possible to repeat a command an infinite number of times. The | |
892 only problem is that the only way to stop this is by causing an error. The | |
893 macros to solve a maze uses this, look there for an example. There is one | |
894 exception: If the {rhs} starts with {lhs}, the first character is not mapped | |
895 again (this is Vi compatible). | |
896 For example: > | |
897 :map ab abcd | |
898 will execute the "a" command and insert "bcd" in the text. The "ab" in the | |
899 {rhs} will not be mapped again. | |
900 | |
901 If you want to exchange the meaning of two keys you should use the :noremap | |
902 command. For example: > | |
903 :noremap k j | |
904 :noremap j k | |
905 This will exchange the cursor up and down commands. | |
906 | |
907 With the normal :map command, when the 'remap' option is on, mapping takes | |
908 place until the text is found not to be a part of a {lhs}. For example, if | |
909 you use: > | |
910 :map x y | |
911 :map y x | |
912 Vim will replace x with y, and then y with x, etc. When this has happened | |
913 'maxmapdepth' times (default 1000), Vim will give the error message | |
914 "recursive mapping". | |
915 | |
916 *:map-undo* | |
917 If you include an undo command inside a mapped sequence, this will bring the | |
918 text back in the state before executing the macro. This is compatible with | |
919 the original Vi, as long as there is only one undo command in the mapped | |
920 sequence (having two undo commands in a mapped sequence did not make sense | |
921 in the original Vi, you would get back the text before the first undo). | |
922 | |
923 | |
592 | 924 1.10 MAPPING ALT-KEYS *:map-alt-keys* |
588 | 925 |
32004 | 926 For a readable mapping command the <A-k> form can be used. Note that <A-k> |
927 and <A-K> are different, the latter will use an upper case letter. Actually, | |
928 <A-K> and <A-S-K> are the same. Instead of "A" you can use "M". If you have | |
929 an actual Meta modifier key, please see |:map-meta-keys|. | |
930 | |
588 | 931 In the GUI Vim handles the Alt key itself, thus mapping keys with ALT should |
932 always work. But in a terminal Vim gets a sequence of bytes and has to figure | |
933 out whether ALT was pressed or not. | |
934 | |
18400
f66fee58e7e2
patch 8.1.2194: modifyOtherKeys is not enabled by default
Bram Moolenaar <Bram@vim.org>
parents:
16944
diff
changeset
|
935 If the terminal supports the modifyOtherKeys mode and it has been enabled, |
f66fee58e7e2
patch 8.1.2194: modifyOtherKeys is not enabled by default
Bram Moolenaar <Bram@vim.org>
parents:
16944
diff
changeset
|
936 then Vim can recognize more key combinations, see |modifyOtherKeys| below. |
31888
b374dfaa8645
patch 9.0.1276: some mappings with Meta and Shift do not work
Bram Moolenaar <Bram@vim.org>
parents:
31671
diff
changeset
|
937 The Kitty keyboard protocol works in a similar way, see |
b374dfaa8645
patch 9.0.1276: some mappings with Meta and Shift do not work
Bram Moolenaar <Bram@vim.org>
parents:
31671
diff
changeset
|
938 |kitty-keyboard-protocol|. |
18400
f66fee58e7e2
patch 8.1.2194: modifyOtherKeys is not enabled by default
Bram Moolenaar <Bram@vim.org>
parents:
16944
diff
changeset
|
939 |
588 | 940 By default Vim assumes that pressing the ALT key sets the 8th bit of a typed |
605 | 941 character. Most decent terminals can work that way, such as xterm, aterm and |
588 | 942 rxvt. If your <A-k> mappings don't work it might be that the terminal is |
943 prefixing the character with an ESC character. But you can just as well type | |
944 ESC before a character, thus Vim doesn't know what happened (except for | |
945 checking the delay between characters, which is not reliable). | |
946 | |
947 As of this writing, some mainstream terminals like gnome-terminal and konsole | |
948 use the ESC prefix. There doesn't appear a way to have them use the 8th bit | |
605 | 949 instead. Xterm should work well by default. Aterm and rxvt should work well |
950 when started with the "--meta8" argument. You can also tweak resources like | |
951 "metaSendsEscape", "eightBitInput" and "eightBitOutput". | |
588 | 952 |
953 On the Linux console, this behavior can be toggled with the "setmetamode" | |
954 command. Bear in mind that not using an ESC prefix could get you in trouble | |
955 with other programs. You should make sure that bash has the "convert-meta" | |
956 option set to "on" in order for your Meta keybindings to still work on it | |
957 (it's the default readline behavior, unless changed by specific system | |
958 configuration). For that, you can add the line: > | |
959 | |
960 set convert-meta on | |
961 | |
962 to your ~/.inputrc file. If you're creating the file, you might want to use: > | |
963 | |
964 $include /etc/inputrc | |
965 | |
966 as the first line, if that file exists on your system, to keep global options. | |
967 This may cause a problem for entering special characters, such as the umlaut. | |
968 Then you should use CTRL-V before that character. | |
969 | |
970 Bear in mind that convert-meta has been reported to have troubles when used in | |
971 UTF-8 locales. On terminals like xterm, the "metaSendsEscape" resource can be | |
972 toggled on the fly through the "Main Options" menu, by pressing Ctrl-LeftClick | |
973 on the terminal; that's a good last resource in case you want to send ESC when | |
11473 | 974 using other applications but not when inside Vim. |
588 | 975 |
592 | 976 |
31888
b374dfaa8645
patch 9.0.1276: some mappings with Meta and Shift do not work
Bram Moolenaar <Bram@vim.org>
parents:
31671
diff
changeset
|
977 1.11 MAPPING META-KEYS *:map-meta-keys* |
b374dfaa8645
patch 9.0.1276: some mappings with Meta and Shift do not work
Bram Moolenaar <Bram@vim.org>
parents:
31671
diff
changeset
|
978 |
b374dfaa8645
patch 9.0.1276: some mappings with Meta and Shift do not work
Bram Moolenaar <Bram@vim.org>
parents:
31671
diff
changeset
|
979 Mapping keys with the Meta modifier works very similar to using the Alt key. |
b374dfaa8645
patch 9.0.1276: some mappings with Meta and Shift do not work
Bram Moolenaar <Bram@vim.org>
parents:
31671
diff
changeset
|
980 What key on your keyboard produces the Meta modifier depends on your keyboard |
b374dfaa8645
patch 9.0.1276: some mappings with Meta and Shift do not work
Bram Moolenaar <Bram@vim.org>
parents:
31671
diff
changeset
|
981 and configuration. |
b374dfaa8645
patch 9.0.1276: some mappings with Meta and Shift do not work
Bram Moolenaar <Bram@vim.org>
parents:
31671
diff
changeset
|
982 |
b374dfaa8645
patch 9.0.1276: some mappings with Meta and Shift do not work
Bram Moolenaar <Bram@vim.org>
parents:
31671
diff
changeset
|
983 Note that mapping <M-a> actually is for using the Alt key. That can be |
b374dfaa8645
patch 9.0.1276: some mappings with Meta and Shift do not work
Bram Moolenaar <Bram@vim.org>
parents:
31671
diff
changeset
|
984 confusing! It cannot be changed, it would not be backwards compatible. |
b374dfaa8645
patch 9.0.1276: some mappings with Meta and Shift do not work
Bram Moolenaar <Bram@vim.org>
parents:
31671
diff
changeset
|
985 |
b374dfaa8645
patch 9.0.1276: some mappings with Meta and Shift do not work
Bram Moolenaar <Bram@vim.org>
parents:
31671
diff
changeset
|
986 For the Meta modifier the "T" character is used. For example, to map Meta-b |
b374dfaa8645
patch 9.0.1276: some mappings with Meta and Shift do not work
Bram Moolenaar <Bram@vim.org>
parents:
31671
diff
changeset
|
987 in Insert mode: > |
b374dfaa8645
patch 9.0.1276: some mappings with Meta and Shift do not work
Bram Moolenaar <Bram@vim.org>
parents:
31671
diff
changeset
|
988 :imap <T-b> terrible |
b374dfaa8645
patch 9.0.1276: some mappings with Meta and Shift do not work
Bram Moolenaar <Bram@vim.org>
parents:
31671
diff
changeset
|
989 |
b374dfaa8645
patch 9.0.1276: some mappings with Meta and Shift do not work
Bram Moolenaar <Bram@vim.org>
parents:
31671
diff
changeset
|
990 |
b374dfaa8645
patch 9.0.1276: some mappings with Meta and Shift do not work
Bram Moolenaar <Bram@vim.org>
parents:
31671
diff
changeset
|
991 1.12 MAPPING IN modifyOtherKeys mode *modifyOtherKeys* |
18400
f66fee58e7e2
patch 8.1.2194: modifyOtherKeys is not enabled by default
Bram Moolenaar <Bram@vim.org>
parents:
16944
diff
changeset
|
992 |
f66fee58e7e2
patch 8.1.2194: modifyOtherKeys is not enabled by default
Bram Moolenaar <Bram@vim.org>
parents:
16944
diff
changeset
|
993 Xterm and a few other terminals can be put in a mode where keys with modifiers |
f66fee58e7e2
patch 8.1.2194: modifyOtherKeys is not enabled by default
Bram Moolenaar <Bram@vim.org>
parents:
16944
diff
changeset
|
994 are sent with a special escape code. Vim recognizes these codes and can then |
f66fee58e7e2
patch 8.1.2194: modifyOtherKeys is not enabled by default
Bram Moolenaar <Bram@vim.org>
parents:
16944
diff
changeset
|
995 make a difference between CTRL-H and Backspace, even when Backspace sends the |
31211
d6355c3af211
patch 9.0.0939: still using simplified mappings when using kitty protocol
Bram Moolenaar <Bram@vim.org>
parents:
31200
diff
changeset
|
996 character 8. And many more special keys, such as Tab and CTRL-I, which cannot |
d6355c3af211
patch 9.0.0939: still using simplified mappings when using kitty protocol
Bram Moolenaar <Bram@vim.org>
parents:
31200
diff
changeset
|
997 be mapped separately otherwise. |
18400
f66fee58e7e2
patch 8.1.2194: modifyOtherKeys is not enabled by default
Bram Moolenaar <Bram@vim.org>
parents:
16944
diff
changeset
|
998 |
f66fee58e7e2
patch 8.1.2194: modifyOtherKeys is not enabled by default
Bram Moolenaar <Bram@vim.org>
parents:
16944
diff
changeset
|
999 For xterm modifyOtherKeys is enabled in the builtin termcap entry. If this is |
f66fee58e7e2
patch 8.1.2194: modifyOtherKeys is not enabled by default
Bram Moolenaar <Bram@vim.org>
parents:
16944
diff
changeset
|
1000 not used you can enable modifyOtherKeys with these lines in your vimrc: > |
f66fee58e7e2
patch 8.1.2194: modifyOtherKeys is not enabled by default
Bram Moolenaar <Bram@vim.org>
parents:
16944
diff
changeset
|
1001 let &t_TI = "\<Esc>[>4;2m" |
f66fee58e7e2
patch 8.1.2194: modifyOtherKeys is not enabled by default
Bram Moolenaar <Bram@vim.org>
parents:
16944
diff
changeset
|
1002 let &t_TE = "\<Esc>[>4;m" |
f66fee58e7e2
patch 8.1.2194: modifyOtherKeys is not enabled by default
Bram Moolenaar <Bram@vim.org>
parents:
16944
diff
changeset
|
1003 |
31211
d6355c3af211
patch 9.0.0939: still using simplified mappings when using kitty protocol
Bram Moolenaar <Bram@vim.org>
parents:
31200
diff
changeset
|
1004 This sets modifyOtherKeys to level 2. Note that modifyOtherKeys level 1 does |
d6355c3af211
patch 9.0.0939: still using simplified mappings when using kitty protocol
Bram Moolenaar <Bram@vim.org>
parents:
31200
diff
changeset
|
1005 not work. Some terminals do not support level 2 and then send key codes that |
d6355c3af211
patch 9.0.0939: still using simplified mappings when using kitty protocol
Bram Moolenaar <Bram@vim.org>
parents:
31200
diff
changeset
|
1006 Vim will not be able to correctly recognize. |
d6355c3af211
patch 9.0.0939: still using simplified mappings when using kitty protocol
Bram Moolenaar <Bram@vim.org>
parents:
31200
diff
changeset
|
1007 |
18400
f66fee58e7e2
patch 8.1.2194: modifyOtherKeys is not enabled by default
Bram Moolenaar <Bram@vim.org>
parents:
16944
diff
changeset
|
1008 In case the modifyOtherKeys mode causes problems you can disable it: > |
f66fee58e7e2
patch 8.1.2194: modifyOtherKeys is not enabled by default
Bram Moolenaar <Bram@vim.org>
parents:
16944
diff
changeset
|
1009 let &t_TI = "" |
f66fee58e7e2
patch 8.1.2194: modifyOtherKeys is not enabled by default
Bram Moolenaar <Bram@vim.org>
parents:
16944
diff
changeset
|
1010 let &t_TE = "" |
f66fee58e7e2
patch 8.1.2194: modifyOtherKeys is not enabled by default
Bram Moolenaar <Bram@vim.org>
parents:
16944
diff
changeset
|
1011 It does not take effect immediately. To have this work without restarting Vim |
18594 | 1012 execute a shell command, e.g.: `!ls` Or put the lines in your |vimrc|. |
1013 | |
1014 When modifyOtherKeys is enabled you can map <C-[> and <C-S-{>: > | |
1015 imap <C-[> [[[ | |
22526
6325ef9143bc
patch 8.2.1811: mapping Ctrl-key does not work for '{', '}' and '|'
Bram Moolenaar <Bram@vim.org>
parents:
22328
diff
changeset
|
1016 imap <C-{> {{{ |
6325ef9143bc
patch 8.2.1811: mapping Ctrl-key does not work for '{', '}' and '|'
Bram Moolenaar <Bram@vim.org>
parents:
22328
diff
changeset
|
1017 Without modifyOtherKeys <C-[> and <C-{> are indistinguishable from Esc. |
6325ef9143bc
patch 8.2.1811: mapping Ctrl-key does not work for '{', '}' and '|'
Bram Moolenaar <Bram@vim.org>
parents:
22328
diff
changeset
|
1018 Note that <C-{> is used and not <C-S-[> or <C-S-{>. This works on most |
6325ef9143bc
patch 8.2.1811: mapping Ctrl-key does not work for '{', '}' and '|'
Bram Moolenaar <Bram@vim.org>
parents:
22328
diff
changeset
|
1019 keyboards. Similarly, <C-}> is used instead of <C-S-]> or <C-S-}> and |
6325ef9143bc
patch 8.2.1811: mapping Ctrl-key does not work for '{', '}' and '|'
Bram Moolenaar <Bram@vim.org>
parents:
22328
diff
changeset
|
1020 <C-|> instead of <C-S-\> or <C-S-|>. Note that '|' has a special meaning in a |
6325ef9143bc
patch 8.2.1811: mapping Ctrl-key does not work for '{', '}' and '|'
Bram Moolenaar <Bram@vim.org>
parents:
22328
diff
changeset
|
1021 mapping, see |map-bar|. |
6325ef9143bc
patch 8.2.1811: mapping Ctrl-key does not work for '{', '}' and '|'
Bram Moolenaar <Bram@vim.org>
parents:
22328
diff
changeset
|
1022 |
6325ef9143bc
patch 8.2.1811: mapping Ctrl-key does not work for '{', '}' and '|'
Bram Moolenaar <Bram@vim.org>
parents:
22328
diff
changeset
|
1023 WARNING: if you map <C-[> you may very well break any key codes that start |
6325ef9143bc
patch 8.2.1811: mapping Ctrl-key does not work for '{', '}' and '|'
Bram Moolenaar <Bram@vim.org>
parents:
22328
diff
changeset
|
1024 with Esc. Make sure it comes AFTER other mappings. |
18400
f66fee58e7e2
patch 8.1.2194: modifyOtherKeys is not enabled by default
Bram Moolenaar <Bram@vim.org>
parents:
16944
diff
changeset
|
1025 |
31293
ff4473b3fc58
patch 9.0.0980: the keyboard state response may end up in a shell command
Bram Moolenaar <Bram@vim.org>
parents:
31211
diff
changeset
|
1026 Starting with xterm version 377 Vim can detect the modifyOtherKeys state by |
ff4473b3fc58
patch 9.0.0980: the keyboard state response may end up in a shell command
Bram Moolenaar <Bram@vim.org>
parents:
31211
diff
changeset
|
1027 requesting it. For this the 't_RK' termcap entry is used. When the response |
ff4473b3fc58
patch 9.0.0980: the keyboard state response may end up in a shell command
Bram Moolenaar <Bram@vim.org>
parents:
31211
diff
changeset
|
1028 is found then Vim will know whether modifyOtherKeys level 2 is enabled, and |
ff4473b3fc58
patch 9.0.0980: the keyboard state response may end up in a shell command
Bram Moolenaar <Bram@vim.org>
parents:
31211
diff
changeset
|
1029 handle mappings accordingly. |
ff4473b3fc58
patch 9.0.0980: the keyboard state response may end up in a shell command
Bram Moolenaar <Bram@vim.org>
parents:
31211
diff
changeset
|
1030 |
ff4473b3fc58
patch 9.0.0980: the keyboard state response may end up in a shell command
Bram Moolenaar <Bram@vim.org>
parents:
31211
diff
changeset
|
1031 Before version 377 Vim automatically detects if the modifyOtherKeys mode was |
ff4473b3fc58
patch 9.0.0980: the keyboard state response may end up in a shell command
Bram Moolenaar <Bram@vim.org>
parents:
31211
diff
changeset
|
1032 enabled when it spots an escape sequence that must have been created by it. |
ff4473b3fc58
patch 9.0.0980: the keyboard state response may end up in a shell command
Bram Moolenaar <Bram@vim.org>
parents:
31211
diff
changeset
|
1033 To see if Vim detected such an escape sequence use `:verbose map`, the first |
ff4473b3fc58
patch 9.0.0980: the keyboard state response may end up in a shell command
Bram Moolenaar <Bram@vim.org>
parents:
31211
diff
changeset
|
1034 line will then show "Seen modifyOtherKeys: true" (possibly translated). |
30920
93b603c24d23
patch 9.0.0794: there is no way to find out if modifyOtherKeys has been seen
Bram Moolenaar <Bram@vim.org>
parents:
30547
diff
changeset
|
1035 |
32004 | 1036 This automatic detection depends on receiving an escape code starting with |
31211
d6355c3af211
patch 9.0.0939: still using simplified mappings when using kitty protocol
Bram Moolenaar <Bram@vim.org>
parents:
31200
diff
changeset
|
1037 "<1b>[27;". This is the normal way xterm sends these key codes. However, if |
d6355c3af211
patch 9.0.0939: still using simplified mappings when using kitty protocol
Bram Moolenaar <Bram@vim.org>
parents:
31200
diff
changeset
|
1038 the *formatOtherKeys* resource is set another form is used that is not |
d6355c3af211
patch 9.0.0939: still using simplified mappings when using kitty protocol
Bram Moolenaar <Bram@vim.org>
parents:
31200
diff
changeset
|
1039 recognized, therefore you must not set formatOtherKeys. |
d6355c3af211
patch 9.0.0939: still using simplified mappings when using kitty protocol
Bram Moolenaar <Bram@vim.org>
parents:
31200
diff
changeset
|
1040 |
21499 | 1041 A known side effect is that in Insert mode the raw escape sequence is inserted |
1042 after the CTRL-V key. This can be used to check whether modifyOtherKeys is | |
1043 enabled: In Insert mode type CTRL-SHIFT-V CTRL-V, if you get one byte then | |
31211
d6355c3af211
patch 9.0.0939: still using simplified mappings when using kitty protocol
Bram Moolenaar <Bram@vim.org>
parents:
31200
diff
changeset
|
1044 modifyOtherKeys is off, if you get <1b>[27;5;118~ then it is on. |
18400
f66fee58e7e2
patch 8.1.2194: modifyOtherKeys is not enabled by default
Bram Moolenaar <Bram@vim.org>
parents:
16944
diff
changeset
|
1045 |
31293
ff4473b3fc58
patch 9.0.0980: the keyboard state response may end up in a shell command
Bram Moolenaar <Bram@vim.org>
parents:
31211
diff
changeset
|
1046 Note that xterm up to version 376 has a bug that makes Shift-Esc send a |
ff4473b3fc58
patch 9.0.0980: the keyboard state response may end up in a shell command
Bram Moolenaar <Bram@vim.org>
parents:
31211
diff
changeset
|
1047 regular Esc code, the Shift modifier is dropped. |
ff4473b3fc58
patch 9.0.0980: the keyboard state response may end up in a shell command
Bram Moolenaar <Bram@vim.org>
parents:
31211
diff
changeset
|
1048 |
18594 | 1049 When the 'esckeys' option is off, then modifyOtherKeys will be disabled in |
1050 Insert mode to avoid every key with a modifier causing Insert mode to end. | |
1051 | |
18400
f66fee58e7e2
patch 8.1.2194: modifyOtherKeys is not enabled by default
Bram Moolenaar <Bram@vim.org>
parents:
16944
diff
changeset
|
1052 |
31888
b374dfaa8645
patch 9.0.1276: some mappings with Meta and Shift do not work
Bram Moolenaar <Bram@vim.org>
parents:
31671
diff
changeset
|
1053 1.13 MAPPING WITH KITTY KEYBOARD PROTOCOL *kitty-keyboard-protocol* |
31192
dcde141f2d1e
patch 9.0.0930: cannot debug the Kitty keyboard protocol with TermDebug
Bram Moolenaar <Bram@vim.org>
parents:
31139
diff
changeset
|
1054 |
dcde141f2d1e
patch 9.0.0930: cannot debug the Kitty keyboard protocol with TermDebug
Bram Moolenaar <Bram@vim.org>
parents:
31139
diff
changeset
|
1055 If the value of 'term' contains "kitty" then Vim will send out an escape |
dcde141f2d1e
patch 9.0.0930: cannot debug the Kitty keyboard protocol with TermDebug
Bram Moolenaar <Bram@vim.org>
parents:
31139
diff
changeset
|
1056 sequence to enable the Kitty keyboard protocol. This can be changed with the |
dcde141f2d1e
patch 9.0.0930: cannot debug the Kitty keyboard protocol with TermDebug
Bram Moolenaar <Bram@vim.org>
parents:
31139
diff
changeset
|
1057 'keyprotocol' option. |
dcde141f2d1e
patch 9.0.0930: cannot debug the Kitty keyboard protocol with TermDebug
Bram Moolenaar <Bram@vim.org>
parents:
31139
diff
changeset
|
1058 |
dcde141f2d1e
patch 9.0.0930: cannot debug the Kitty keyboard protocol with TermDebug
Bram Moolenaar <Bram@vim.org>
parents:
31139
diff
changeset
|
1059 Like modifyOtherKeys, this will make it possible to distinguish between more |
dcde141f2d1e
patch 9.0.0930: cannot debug the Kitty keyboard protocol with TermDebug
Bram Moolenaar <Bram@vim.org>
parents:
31139
diff
changeset
|
1060 keys with modifiers. Also, this protocol sends an escape sequence for the Esc |
dcde141f2d1e
patch 9.0.0930: cannot debug the Kitty keyboard protocol with TermDebug
Bram Moolenaar <Bram@vim.org>
parents:
31139
diff
changeset
|
1061 key, so that Vim does not need to use a timeout to know whether receiving an |
dcde141f2d1e
patch 9.0.0930: cannot debug the Kitty keyboard protocol with TermDebug
Bram Moolenaar <Bram@vim.org>
parents:
31139
diff
changeset
|
1062 Esc character means the Esc key was pressed or it's the start of an escape |
dcde141f2d1e
patch 9.0.0930: cannot debug the Kitty keyboard protocol with TermDebug
Bram Moolenaar <Bram@vim.org>
parents:
31139
diff
changeset
|
1063 sequence. |
dcde141f2d1e
patch 9.0.0930: cannot debug the Kitty keyboard protocol with TermDebug
Bram Moolenaar <Bram@vim.org>
parents:
31139
diff
changeset
|
1064 |
dcde141f2d1e
patch 9.0.0930: cannot debug the Kitty keyboard protocol with TermDebug
Bram Moolenaar <Bram@vim.org>
parents:
31139
diff
changeset
|
1065 Vim automatically detects if the Kitty keyboard protocol was enabled when it |
dcde141f2d1e
patch 9.0.0930: cannot debug the Kitty keyboard protocol with TermDebug
Bram Moolenaar <Bram@vim.org>
parents:
31139
diff
changeset
|
1066 spots the response to the status request (this should be part of the |t_TI| |
dcde141f2d1e
patch 9.0.0930: cannot debug the Kitty keyboard protocol with TermDebug
Bram Moolenaar <Bram@vim.org>
parents:
31139
diff
changeset
|
1067 termcap entry). To see if Vim detected such an escape sequence use: > |
dcde141f2d1e
patch 9.0.0930: cannot debug the Kitty keyboard protocol with TermDebug
Bram Moolenaar <Bram@vim.org>
parents:
31139
diff
changeset
|
1068 :verbose map |
dcde141f2d1e
patch 9.0.0930: cannot debug the Kitty keyboard protocol with TermDebug
Bram Moolenaar <Bram@vim.org>
parents:
31139
diff
changeset
|
1069 The first line will then show "Kitty keyboard protocol: {value}" (possibly |
dcde141f2d1e
patch 9.0.0930: cannot debug the Kitty keyboard protocol with TermDebug
Bram Moolenaar <Bram@vim.org>
parents:
31139
diff
changeset
|
1070 translated). The meaning of {value}: |
dcde141f2d1e
patch 9.0.0930: cannot debug the Kitty keyboard protocol with TermDebug
Bram Moolenaar <Bram@vim.org>
parents:
31139
diff
changeset
|
1071 Unknown no status received yet |
dcde141f2d1e
patch 9.0.0930: cannot debug the Kitty keyboard protocol with TermDebug
Bram Moolenaar <Bram@vim.org>
parents:
31139
diff
changeset
|
1072 Off protocol is not used |
dcde141f2d1e
patch 9.0.0930: cannot debug the Kitty keyboard protocol with TermDebug
Bram Moolenaar <Bram@vim.org>
parents:
31139
diff
changeset
|
1073 On protocol is used |
dcde141f2d1e
patch 9.0.0930: cannot debug the Kitty keyboard protocol with TermDebug
Bram Moolenaar <Bram@vim.org>
parents:
31139
diff
changeset
|
1074 Disabled protocol was used but expected to have been disabled |
dcde141f2d1e
patch 9.0.0930: cannot debug the Kitty keyboard protocol with TermDebug
Bram Moolenaar <Bram@vim.org>
parents:
31139
diff
changeset
|
1075 by 't_TE' |
32061 | 1076 Cleared protocol expected to have been disabled by 't_TE', |
32004 | 1077 previous state is unknown |
31192
dcde141f2d1e
patch 9.0.0930: cannot debug the Kitty keyboard protocol with TermDebug
Bram Moolenaar <Bram@vim.org>
parents:
31139
diff
changeset
|
1078 |
dcde141f2d1e
patch 9.0.0930: cannot debug the Kitty keyboard protocol with TermDebug
Bram Moolenaar <Bram@vim.org>
parents:
31139
diff
changeset
|
1079 |
31888
b374dfaa8645
patch 9.0.1276: some mappings with Meta and Shift do not work
Bram Moolenaar <Bram@vim.org>
parents:
31671
diff
changeset
|
1080 1.14 MAPPING AN OPERATOR *:map-operator* |
592 | 1081 |
1082 An operator is used before a {motion} command. To define your own operator | |
23164 | 1083 you must create a mapping that first sets the 'operatorfunc' option and then |
592 | 1084 invoke the |g@| operator. After the user types the {motion} command the |
1085 specified function will be called. | |
1086 | |
626 | 1087 *g@* *E774* *E775* |
592 | 1088 g@{motion} Call the function set by the 'operatorfunc' option. |
1089 The '[ mark is positioned at the start of the text | |
1090 moved over by {motion}, the '] mark on the last | |
1091 character of the text. | |
1092 The function is called with one String argument: | |
1093 "line" {motion} was |linewise| | |
1094 "char" {motion} was |characterwise| | |
2324
0a258a67051d
In Visual mode with 'showcmd' display the number of bytes and characters.
Bram Moolenaar <bram@vim.org>
parents:
2154
diff
changeset
|
1095 "block" {motion} was |blockwise-visual| |
26708 | 1096 The type can be forced, see |forced-motion|. |
2570
71b56b4e7785
Make the references to features in the help more consistent. (Sylvain Hitier)
Bram Moolenaar <bram@vim.org>
parents:
2561
diff
changeset
|
1097 {not available when compiled without the |+eval| |
592 | 1098 feature} |
1099 | |
1100 Here is an example that counts the number of spaces with <F4>: > | |
1101 | |
22171 | 1102 nnoremap <expr> <F4> CountSpaces() |
1103 xnoremap <expr> <F4> CountSpaces() | |
1104 " doubling <F4> works on a line | |
1105 nnoremap <expr> <F4><F4> CountSpaces() .. '_' | |
592 | 1106 |
26708 | 1107 function CountSpaces(context = {}, type = '') abort |
22171 | 1108 if a:type == '' |
26708 | 1109 let context = #{ |
1110 \ dot_command: v:false, | |
1111 \ extend_block: '', | |
1112 \ virtualedit: [&l:virtualedit, &g:virtualedit], | |
1113 \ } | |
1114 let &operatorfunc = function('CountSpaces', [context]) | |
26591 | 1115 set virtualedit=block |
22171 | 1116 return 'g@' |
26591 | 1117 endif |
22171 | 1118 |
26708 | 1119 let save = #{ |
1120 \ clipboard: &clipboard, | |
1121 \ selection: &selection, | |
1122 \ virtualedit: [&l:virtualedit, &g:virtualedit], | |
1123 \ register: getreginfo('"'), | |
1124 \ visual_marks: [getpos("'<"), getpos("'>")], | |
1125 \ } | |
592 | 1126 |
22171 | 1127 try |
26591 | 1128 set clipboard= selection=inclusive virtualedit= |
26708 | 1129 let commands = #{ |
1130 \ line: "'[V']", | |
1131 \ char: "`[v`]", | |
1132 \ block: "`[\<C-V>`]", | |
1133 \ }[a:type] | |
1134 let [_, _, col, off] = getpos("']") | |
1135 if off != 0 | |
1136 let vcol = getline("'[")->strpart(0, col + off)->strdisplaywidth() | |
1137 if vcol >= [line("'["), '$']->virtcol() - 1 | |
1138 let a:context.extend_block = '$' | |
1139 else | |
1140 let a:context.extend_block = vcol .. '|' | |
1141 endif | |
1142 endif | |
1143 if a:context.extend_block != '' | |
1144 let commands ..= 'oO' .. a:context.extend_block | |
26591 | 1145 endif |
1146 let commands ..= 'y' | |
1147 execute 'silent noautocmd keepjumps normal! ' .. commands | |
1148 echomsg getreg('"')->count(' ') | |
22171 | 1149 finally |
26708 | 1150 call setreg('"', save.register) |
1151 call setpos("'<", save.visual_marks[0]) | |
1152 call setpos("'>", save.visual_marks[1]) | |
1153 let &clipboard = save.clipboard | |
1154 let &selection = save.selection | |
1155 let [&l:virtualedit, &g:virtualedit] = get(a:context.dot_command ? save : a:context, 'virtualedit') | |
1156 let a:context.dot_command = v:true | |
22171 | 1157 endtry |
1158 endfunction | |
592 | 1159 |
22171 | 1160 An <expr> mapping is used to be able to fetch any prefixed count and register. |
1161 This also avoids using a command line, which would trigger CmdlineEnter and | |
1162 CmdlineLeave autocommands. | |
592 | 1163 |
1164 Note that the 'selection' option is temporarily set to "inclusive" to be able | |
1165 to yank exactly the right text by using Visual mode from the '[ to the '] | |
1166 mark. | |
1167 | |
22171 | 1168 Also note that the 'clipboard' option is temporarily emptied to avoid |
1169 clobbering the `"*` or `"+` registers, if its value contains the item `unnamed` | |
1170 or `unnamedplus`. | |
592 | 1171 |
26050 | 1172 The `mode()` function will return the state as it will be after applying the |
1173 operator. | |
1174 | |
26175
6b4f017d7005
patch 8.2.3619: cannot use a lambda for 'operatorfunc'
Bram Moolenaar <Bram@vim.org>
parents:
26148
diff
changeset
|
1175 Here is an example for using a lambda function to create a normal-mode |
6b4f017d7005
patch 8.2.3619: cannot use a lambda for 'operatorfunc'
Bram Moolenaar <Bram@vim.org>
parents:
26148
diff
changeset
|
1176 operator to add quotes around text in the current line: > |
6b4f017d7005
patch 8.2.3619: cannot use a lambda for 'operatorfunc'
Bram Moolenaar <Bram@vim.org>
parents:
26148
diff
changeset
|
1177 |
6b4f017d7005
patch 8.2.3619: cannot use a lambda for 'operatorfunc'
Bram Moolenaar <Bram@vim.org>
parents:
26148
diff
changeset
|
1178 nnoremap <F4> <Cmd>let &opfunc='{t -> |
6b4f017d7005
patch 8.2.3619: cannot use a lambda for 'operatorfunc'
Bram Moolenaar <Bram@vim.org>
parents:
26148
diff
changeset
|
1179 \ getline(".") |
6b4f017d7005
patch 8.2.3619: cannot use a lambda for 'operatorfunc'
Bram Moolenaar <Bram@vim.org>
parents:
26148
diff
changeset
|
1180 \ ->split("\\zs") |
6b4f017d7005
patch 8.2.3619: cannot use a lambda for 'operatorfunc'
Bram Moolenaar <Bram@vim.org>
parents:
26148
diff
changeset
|
1181 \ ->insert("\"", col("'']")) |
6b4f017d7005
patch 8.2.3619: cannot use a lambda for 'operatorfunc'
Bram Moolenaar <Bram@vim.org>
parents:
26148
diff
changeset
|
1182 \ ->insert("\"", col("''[") - 1) |
6b4f017d7005
patch 8.2.3619: cannot use a lambda for 'operatorfunc'
Bram Moolenaar <Bram@vim.org>
parents:
26148
diff
changeset
|
1183 \ ->join("") |
6b4f017d7005
patch 8.2.3619: cannot use a lambda for 'operatorfunc'
Bram Moolenaar <Bram@vim.org>
parents:
26148
diff
changeset
|
1184 \ ->setline(".")}'<CR>g@ |
6b4f017d7005
patch 8.2.3619: cannot use a lambda for 'operatorfunc'
Bram Moolenaar <Bram@vim.org>
parents:
26148
diff
changeset
|
1185 |
7 | 1186 ============================================================================== |
1187 2. Abbreviations *abbreviations* *Abbreviations* | |
1188 | |
1189 Abbreviations are used in Insert mode, Replace mode and Command-line mode. | |
1190 If you enter a word that is an abbreviation, it is replaced with the word it | |
1191 stands for. This can be used to save typing for often used long words. And | |
1192 you can use it to automatically correct obvious spelling errors. | |
1193 Examples: | |
1194 | |
1190 | 1195 :iab ms Microsoft |
7 | 1196 :iab tihs this |
1197 | |
1198 There are three types of abbreviations: | |
1199 | |
1200 full-id The "full-id" type consists entirely of keyword characters (letters | |
1201 and characters from 'iskeyword' option). This is the most common | |
1202 abbreviation. | |
1203 | |
1204 Examples: "foo", "g3", "-1" | |
1205 | |
1206 end-id The "end-id" type ends in a keyword character, but all the other | |
1207 characters are not keyword characters. | |
1208 | |
1209 Examples: "#i", "..f", "$/7" | |
1210 | |
1211 non-id The "non-id" type ends in a non-keyword character, the other | |
1236 | 1212 characters may be of any type, excluding space and tab. {this type |
7 | 1213 is not supported by Vi} |
1214 | |
1215 Examples: "def#", "4/7$" | |
1216 | |
1217 Examples of strings that cannot be abbreviations: "a.b", "#def", "a b", "_$r" | |
1218 | |
1219 An abbreviation is only recognized when you type a non-keyword character. | |
32004 | 1220 This can also be the <Esc> that ends Insert mode or the <CR> that ends a |
7 | 1221 command. The non-keyword character which ends the abbreviation is inserted |
1222 after the expanded abbreviation. An exception to this is the character <C-]>, | |
1223 which is used to expand an abbreviation without inserting any extra | |
1224 characters. | |
1225 | |
1226 Example: > | |
1227 :ab hh hello | |
1228 < "hh<Space>" is expanded to "hello<Space>" | |
1229 "hh<C-]>" is expanded to "hello" | |
1230 | |
1231 The characters before the cursor must match the abbreviation. Each type has | |
1232 an additional rule: | |
1233 | |
1234 full-id In front of the match is a non-keyword character, or this is where | |
1235 the line or insertion starts. Exception: When the abbreviation is | |
1236 only one character, it is not recognized if there is a non-keyword | |
13937 | 1237 character in front of it, other than a space or a tab. However, for |
1238 the command line "'<,'>" (or any other marks) is ignored, as if the | |
1239 command line starts after it. | |
7 | 1240 |
1236 | 1241 end-id In front of the match is a keyword character, or a space or a tab, |
7 | 1242 or this is where the line or insertion starts. |
1243 | |
1236 | 1244 non-id In front of the match is a space, tab or the start of the line or |
7 | 1245 the insertion. |
1246 | |
1247 Examples: ({CURSOR} is where you type a non-keyword character) > | |
1248 :ab foo four old otters | |
1249 < " foo{CURSOR}" is expanded to " four old otters" | |
1250 " foobar{CURSOR}" is not expanded | |
1251 "barfoo{CURSOR}" is not expanded | |
1252 > | |
1253 :ab #i #include | |
1254 < "#i{CURSOR}" is expanded to "#include" | |
1255 ">#i{CURSOR}" is not expanded | |
1256 > | |
42 | 1257 :ab ;; <endofline> |
7 | 1258 < "test;;" is not expanded |
1259 "test ;;" is expanded to "test <endofline>" | |
1260 | |
6292
31f7581068a9
Update runtime files and translations.
Bram Moolenaar <bram@vim.org>
parents:
6259
diff
changeset
|
1261 To avoid the abbreviation in Insert mode: Type CTRL-V before the character |
31f7581068a9
Update runtime files and translations.
Bram Moolenaar <bram@vim.org>
parents:
6259
diff
changeset
|
1262 that would trigger the abbreviation. E.g. CTRL-V <Space>. Or type part of |
31f7581068a9
Update runtime files and translations.
Bram Moolenaar <bram@vim.org>
parents:
6259
diff
changeset
|
1263 the abbreviation, exit insert mode with <Esc>, re-enter insert mode with "a" |
31f7581068a9
Update runtime files and translations.
Bram Moolenaar <bram@vim.org>
parents:
6259
diff
changeset
|
1264 and type the rest. |
31f7581068a9
Update runtime files and translations.
Bram Moolenaar <bram@vim.org>
parents:
6259
diff
changeset
|
1265 |
7 | 1266 To avoid the abbreviation in Command-line mode: Type CTRL-V twice somewhere in |
1267 the abbreviation to avoid it to be replaced. A CTRL-V in front of a normal | |
1268 character is mostly ignored otherwise. | |
1269 | |
1270 It is possible to move the cursor after an abbreviation: > | |
1271 :iab if if ()<Left> | |
1272 This does not work if 'cpoptions' includes the '<' flag. |<>| | |
1273 | |
1274 You can even do more complicated things. For example, to consume the space | |
1275 typed after an abbreviation: > | |
1276 func Eatchar(pat) | |
685 | 1277 let c = nr2char(getchar(0)) |
7 | 1278 return (c =~ a:pat) ? '' : c |
1279 endfunc | |
1280 iabbr <silent> if if ()<Left><C-R>=Eatchar('\s')<CR> | |
1281 | |
1282 There are no default abbreviations. | |
1283 | |
1284 Abbreviations are never recursive. You can use ":ab f f-o-o" without any | |
1285 problem. But abbreviations can be mapped. {some versions of Vi support | |
1286 recursive abbreviations, for no apparent reason} | |
1287 | |
1288 Abbreviations are disabled if the 'paste' option is on. | |
1289 | |
1290 *:abbreviate-local* *:abbreviate-<buffer>* | |
1291 Just like mappings, abbreviations can be local to a buffer. This is mostly | |
1292 used in a |filetype-plugin| file. Example for a C plugin file: > | |
1293 :abb <buffer> FF for (i = 0; i < ; ++i) | |
1294 < | |
1295 *:ab* *:abbreviate* | |
1296 :ab[breviate] list all abbreviations. The character in the first | |
1297 column indicates the mode where the abbreviation is | |
1298 used: 'i' for insert mode, 'c' for Command-line | |
1299 mode, '!' for both. These are the same as for | |
1300 mappings, see |map-listing|. | |
1301 | |
502 | 1302 *:abbreviate-verbose* |
1303 When 'verbose' is non-zero, listing an abbreviation will also display where it | |
1304 was last defined. Example: > | |
1305 | |
1306 :verbose abbreviate | |
856 | 1307 ! teh the |
502 | 1308 Last set from /home/abcd/vim/abbr.vim |
1309 | |
1310 See |:verbose-cmd| for more information. | |
1311 | |
7 | 1312 :ab[breviate] {lhs} list the abbreviations that start with {lhs} |
1313 You may need to insert a CTRL-V (type it twice) to | |
1314 avoid that a typed {lhs} is expanded, since | |
1315 command-line abbreviations apply here. | |
1316 | |
2908 | 1317 :ab[breviate] [<expr>] [<buffer>] {lhs} {rhs} |
7 | 1318 add abbreviation for {lhs} to {rhs}. If {lhs} already |
1319 existed it is replaced with the new {rhs}. {rhs} may | |
1320 contain spaces. | |
838 | 1321 See |:map-<expr>| for the optional <expr> argument. |
2908 | 1322 See |:map-<buffer>| for the optional <buffer> argument. |
7 | 1323 |
1324 *:una* *:unabbreviate* | |
18928 | 1325 :una[bbreviate] [<buffer>] {lhs} |
1326 Remove abbreviation for {lhs} from the list. If none | |
7 | 1327 is found, remove abbreviations in which {lhs} matches |
1328 with the {rhs}. This is done so that you can even | |
1329 remove abbreviations after expansion. To avoid | |
1330 expansion insert a CTRL-V (type it twice). | |
1331 | |
1332 *:norea* *:noreabbrev* | |
2908 | 1333 :norea[bbrev] [<expr>] [<buffer>] [lhs] [rhs] |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16399
diff
changeset
|
1334 Same as ":ab", but no remapping for this {rhs}. |
7 | 1335 |
16944 | 1336 *:ca* *:cab* *:cabbrev* |
2908 | 1337 :ca[bbrev] [<expr>] [<buffer>] [lhs] [rhs] |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16399
diff
changeset
|
1338 Same as ":ab", but for Command-line mode only. |
7 | 1339 |
1340 *:cuna* *:cunabbrev* | |
18928 | 1341 :cuna[bbrev] [<buffer>] {lhs} |
1342 Same as ":una", but for Command-line mode only. | |
7 | 1343 |
1344 *:cnorea* *:cnoreabbrev* | |
2908 | 1345 :cnorea[bbrev] [<expr>] [<buffer>] [lhs] [rhs] |
7 | 1346 same as ":ab", but for Command-line mode only and no |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16399
diff
changeset
|
1347 remapping for this {rhs} |
7 | 1348 |
1349 *:ia* *:iabbrev* | |
2908 | 1350 :ia[bbrev] [<expr>] [<buffer>] [lhs] [rhs] |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16399
diff
changeset
|
1351 Same as ":ab", but for Insert mode only. |
7 | 1352 |
1353 *:iuna* *:iunabbrev* | |
18928 | 1354 :iuna[bbrev] [<buffer>] {lhs} |
1355 Same as ":una", but for insert mode only. | |
7 | 1356 |
1357 *:inorea* *:inoreabbrev* | |
2908 | 1358 :inorea[bbrev] [<expr>] [<buffer>] [lhs] [rhs] |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16399
diff
changeset
|
1359 Same as ":ab", but for Insert mode only and no |
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16399
diff
changeset
|
1360 remapping for this {rhs}. |
7 | 1361 |
1362 *:abc* *:abclear* | |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16399
diff
changeset
|
1363 :abc[lear] [<buffer>] Remove all abbreviations. |
7 | 1364 |
1365 *:iabc* *:iabclear* | |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16399
diff
changeset
|
1366 :iabc[lear] [<buffer>] Remove all abbreviations for Insert mode. |
7 | 1367 |
1368 *:cabc* *:cabclear* | |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16399
diff
changeset
|
1369 :cabc[lear] [<buffer>] Remove all abbreviations for Command-line mode. |
7 | 1370 |
1371 *using_CTRL-V* | |
1372 It is possible to use special characters in the rhs of an abbreviation. | |
1373 CTRL-V has to be used to avoid the special meaning of most non printable | |
1374 characters. How many CTRL-Vs need to be typed depends on how you enter the | |
1375 abbreviation. This also applies to mappings. Let's use an example here. | |
1376 | |
1377 Suppose you want to abbreviate "esc" to enter an <Esc> character. When you | |
1378 type the ":ab" command in Vim, you have to enter this: (here ^V is a CTRL-V | |
1379 and ^[ is <Esc>) | |
1380 | |
1381 You type: ab esc ^V^V^V^V^V^[ | |
1382 | |
1383 All keyboard input is subjected to ^V quote interpretation, so | |
1384 the first, third, and fifth ^V characters simply allow the second, | |
1385 and fourth ^Vs, and the ^[, to be entered into the command-line. | |
1386 | |
1387 You see: ab esc ^V^V^[ | |
1388 | |
1389 The command-line contains two actual ^Vs before the ^[. This is | |
1390 how it should appear in your .exrc file, if you choose to go that | |
1391 route. The first ^V is there to quote the second ^V; the :ab | |
1392 command uses ^V as its own quote character, so you can include quoted | |
42 | 1393 whitespace or the | character in the abbreviation. The :ab command |
7 | 1394 doesn't do anything special with the ^[ character, so it doesn't need |
1395 to be quoted. (Although quoting isn't harmful; that's why typing 7 | |
1396 [but not 8!] ^Vs works.) | |
1397 | |
1398 Stored as: esc ^V^[ | |
1399 | |
1400 After parsing, the abbreviation's short form ("esc") and long form | |
1401 (the two characters "^V^[") are stored in the abbreviation table. | |
1402 If you give the :ab command with no arguments, this is how the | |
1403 abbreviation will be displayed. | |
1404 | |
1405 Later, when the abbreviation is expanded because the user typed in | |
1406 the word "esc", the long form is subjected to the same type of | |
1407 ^V interpretation as keyboard input. So the ^V protects the ^[ | |
42 | 1408 character from being interpreted as the "exit Insert mode" character. |
7 | 1409 Instead, the ^[ is inserted into the text. |
1410 | |
1411 Expands to: ^[ | |
1412 | |
1413 [example given by Steve Kirkendall] | |
1414 | |
1415 ============================================================================== | |
1416 3. Local mappings and functions *script-local* | |
1417 | |
1418 When using several Vim script files, there is the danger that mappings and | |
1419 functions used in one script use the same name as in other scripts. To avoid | |
1420 this, they can be made local to the script. | |
1421 | |
1422 *<SID>* *<SNR>* *E81* | |
1423 The string "<SID>" can be used in a mapping or menu. This requires that the | |
32061 | 1424 '<' flag is not present in 'cpoptions'. This is useful if you have a |
1425 script-local function that you want to call from a mapping in the same script. | |
7 | 1426 When executing the map command, Vim will replace "<SID>" with the special |
1427 key code <SNR>, followed by a number that's unique for the script, and an | |
1428 underscore. Example: > | |
1429 :map <SID>Add | |
32061 | 1430 would define a mapping "<SNR>23_Add". |
7 | 1431 |
1432 When defining a function in a script, "s:" can be prepended to the name to | |
28517 | 1433 make it local to the script (in |Vim9| script functions without a prefix are |
1434 local to the script). But when a mapping is executed from outside of | |
7 | 1435 the script, it doesn't know in which script the function was defined. To |
1436 avoid this problem, use "<SID>" instead of "s:". The same translation is done | |
1437 as for mappings. This makes it possible to define a call to the function in | |
42 | 1438 a mapping. |
7 | 1439 |
1440 When a local function is executed, it runs in the context of the script it was | |
1441 defined in. This means that new functions and mappings it defines can also | |
1442 use "s:" or "<SID>" and it will use the same unique number as when the | |
1443 function itself was defined. Also, the "s:var" local script variables can be | |
1444 used. | |
1445 | |
1446 When executing an autocommand or a user command, it will run in the context of | |
1447 the script it was defined in. This makes it possible that the command calls a | |
1448 local function or uses a local mapping. | |
1449 | |
21594
5daca8504c63
patch 8.2.1347: cannot easily get the script ID
Bram Moolenaar <Bram@vim.org>
parents:
21499
diff
changeset
|
1450 In case the value is used in a context where <SID> cannot be correctly |
5daca8504c63
patch 8.2.1347: cannot easily get the script ID
Bram Moolenaar <Bram@vim.org>
parents:
21499
diff
changeset
|
1451 expanded, use the expand() function: > |
5daca8504c63
patch 8.2.1347: cannot easily get the script ID
Bram Moolenaar <Bram@vim.org>
parents:
21499
diff
changeset
|
1452 let &includexpr = expand('<SID>') .. 'My_includeexpr()' |
5daca8504c63
patch 8.2.1347: cannot easily get the script ID
Bram Moolenaar <Bram@vim.org>
parents:
21499
diff
changeset
|
1453 |
7 | 1454 Otherwise, using "<SID>" outside of a script context is an error. |
1455 | |
1456 If you need to get the script number to use in a complicated script, you can | |
625 | 1457 use this function: > |
22958 | 1458 func s:ScriptNumber() |
1459 return matchstr(expand('<SID>'), '<SNR>\zs\d\+\ze_') | |
1460 endfunc | |
7 | 1461 |
1462 The "<SNR>" will be shown when listing functions and mappings. This is useful | |
1463 to find out what they are defined to. | |
1464 | |
1465 The |:scriptnames| command can be used to see which scripts have been sourced | |
1466 and what their <SNR> number is. | |
1467 | |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16399
diff
changeset
|
1468 This is all {not available when compiled without the |+eval| feature}. |
7 | 1469 |
1470 ============================================================================== | |
1471 4. User-defined commands *user-commands* | |
1472 | |
236 | 1473 It is possible to define your own Ex commands. A user-defined command can act |
7 | 1474 just like a built-in command (it can have a range or arguments, arguments can |
1475 be completed as filenames or buffer names, etc), except that when the command | |
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1969
diff
changeset
|
1476 is executed, it is transformed into a normal Ex command and then executed. |
7 | 1477 |
1478 For starters: See section |40.2| in the user manual. | |
1479 | |
2642 | 1480 *E183* *E841* *user-cmd-ambiguous* |
7 | 1481 All user defined commands must start with an uppercase letter, to avoid |
2642 | 1482 confusion with builtin commands. Exceptions are these builtin commands: |
1483 :Next | |
1484 :X | |
1485 They cannot be used for a user defined command. ":Print" is also an existing | |
1486 command, but it is deprecated and can be overruled. | |
1487 | |
1488 The other characters of the user command can be uppercase letters, lowercase | |
1489 letters or digits. When using digits, note that other commands that take a | |
1490 numeric argument may become ambiguous. For example, the command ":Cc2" could | |
1491 be the user command ":Cc2" without an argument, or the command ":Cc" with | |
1492 argument "2". It is advised to put a space between the command name and the | |
1493 argument to avoid these problems. | |
7 | 1494 |
236 | 1495 When using a user-defined command, the command can be abbreviated. However, if |
1496 an abbreviation is not unique, an error will be issued. Furthermore, a | |
7 | 1497 built-in command will always take precedence. |
1498 | |
1499 Example: > | |
1500 :command Rename ... | |
1501 :command Renumber ... | |
1502 :Rena " Means "Rename" | |
1503 :Renu " Means "Renumber" | |
1504 :Ren " Error - ambiguous | |
1505 :command Paste ... | |
1506 :P " The built-in :Print | |
1507 | |
1508 It is recommended that full names for user-defined commands are used in | |
1509 scripts. | |
1510 | |
1511 :com[mand] *:com* *:command* | |
236 | 1512 List all user-defined commands. When listing commands, |
16399
47d6e874955c
patch 8.1.1204: output of :command with address completion is not nice
Bram Moolenaar <Bram@vim.org>
parents:
15194
diff
changeset
|
1513 the characters in the first columns are: |
7 | 1514 ! Command has the -bang attribute |
1515 " Command has the -register attribute | |
16399
47d6e874955c
patch 8.1.1204: output of :command with address completion is not nice
Bram Moolenaar <Bram@vim.org>
parents:
15194
diff
changeset
|
1516 | Command has the -bar attribute |
7 | 1517 b Command is local to current buffer |
1518 (see below for details on attributes) | |
10004
8061455d9179
commit https://github.com/vim/vim/commit/818078ddfbb8cc2546f697c5675a251d095722ec
Christian Brabandt <cb@256bit.org>
parents:
9737
diff
changeset
|
1519 The list can be filtered on command name with |
8061455d9179
commit https://github.com/vim/vim/commit/818078ddfbb8cc2546f697c5675a251d095722ec
Christian Brabandt <cb@256bit.org>
parents:
9737
diff
changeset
|
1520 |:filter|, e.g., to list all commands with "Pyth" in |
8061455d9179
commit https://github.com/vim/vim/commit/818078ddfbb8cc2546f697c5675a251d095722ec
Christian Brabandt <cb@256bit.org>
parents:
9737
diff
changeset
|
1521 the name: > |
8061455d9179
commit https://github.com/vim/vim/commit/818078ddfbb8cc2546f697c5675a251d095722ec
Christian Brabandt <cb@256bit.org>
parents:
9737
diff
changeset
|
1522 filter Pyth command |
7 | 1523 |
1524 :com[mand] {cmd} List the user-defined commands that start with {cmd} | |
1525 | |
482 | 1526 *:command-verbose* |
1527 When 'verbose' is non-zero, listing a command will also display where it was | |
27321 | 1528 last defined and any completion argument. Example: > |
482 | 1529 |
1530 :verbose command TOhtml | |
856 | 1531 < Name Args Range Complete Definition ~ |
1532 TOhtml 0 % :call Convert2HTML(<line1>, <line2>) ~ | |
1533 Last set from /usr/share/vim/vim-7.0/plugin/tohtml.vim ~ | |
1534 | |
483 | 1535 See |:verbose-cmd| for more information. |
482 | 1536 |
7 | 1537 *E174* *E182* |
23164 | 1538 :com[mand][!] [{attr}...] {cmd} {repl} |
7 | 1539 Define a user command. The name of the command is |
23164 | 1540 {cmd} and its replacement text is {repl}. The |
1541 command's attributes (see below) are {attr}. If the | |
1542 command already exists, an error is reported, unless a | |
1543 ! is specified, in which case the command is | |
1544 redefined. There is one exception: When sourcing a | |
1545 script again, a command that was previously defined in | |
1546 that script will be silently replaced. | |
15125
b101b193d5ff
patch 8.1.0573: cannot redefine user command without ! in same script
Bram Moolenaar <Bram@vim.org>
parents:
14864
diff
changeset
|
1547 |
7 | 1548 |
1549 :delc[ommand] {cmd} *:delc* *:delcommand* *E184* | |
1550 Delete the user-defined command {cmd}. | |
31139 | 1551 This is not allowed while listing commands, e.g. from |
1552 a timer. *E1311* | |
7 | 1553 |
25796
60e4892dfa45
patch 8.2.3433: :delcommand does not take a -buffer option
Bram Moolenaar <Bram@vim.org>
parents:
25619
diff
changeset
|
1554 :delc[ommand] -buffer {cmd} *E1237* |
60e4892dfa45
patch 8.2.3433: :delcommand does not take a -buffer option
Bram Moolenaar <Bram@vim.org>
parents:
25619
diff
changeset
|
1555 Delete the user-defined command {cmd} that was defined |
60e4892dfa45
patch 8.2.3433: :delcommand does not take a -buffer option
Bram Moolenaar <Bram@vim.org>
parents:
25619
diff
changeset
|
1556 for the current buffer. |
60e4892dfa45
patch 8.2.3433: :delcommand does not take a -buffer option
Bram Moolenaar <Bram@vim.org>
parents:
25619
diff
changeset
|
1557 |
7 | 1558 :comc[lear] *:comc* *:comclear* |
1559 Delete all user-defined commands. | |
1560 | |
15125
b101b193d5ff
patch 8.1.0573: cannot redefine user command without ! in same script
Bram Moolenaar <Bram@vim.org>
parents:
14864
diff
changeset
|
1561 |
b101b193d5ff
patch 8.1.0573: cannot redefine user command without ! in same script
Bram Moolenaar <Bram@vim.org>
parents:
14864
diff
changeset
|
1562 Command attributes ~ |
30967 | 1563 *command-attributes* |
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1969
diff
changeset
|
1564 User-defined commands are treated by Vim just like any other Ex commands. They |
236 | 1565 can have arguments, or have a range specified. Arguments are subject to |
1566 completion as filenames, buffers, etc. Exactly how this works depends upon the | |
7 | 1567 command's attributes, which are specified when the command is defined. |
1568 | |
1569 There are a number of attributes, split into four categories: argument | |
236 | 1570 handling, completion behavior, range handling, and special cases. The |
7 | 1571 attributes are described below, by category. |
1572 | |
1573 | |
15125
b101b193d5ff
patch 8.1.0573: cannot redefine user command without ! in same script
Bram Moolenaar <Bram@vim.org>
parents:
14864
diff
changeset
|
1574 Argument handling ~ |
b101b193d5ff
patch 8.1.0573: cannot redefine user command without ! in same script
Bram Moolenaar <Bram@vim.org>
parents:
14864
diff
changeset
|
1575 *E175* *E176* *:command-nargs* |
7 | 1576 By default, a user defined command will take no arguments (and an error is |
236 | 1577 reported if any are supplied). However, it is possible to specify that the |
1578 command can take arguments, using the -nargs attribute. Valid cases are: | |
7 | 1579 |
1580 -nargs=0 No arguments are allowed (the default) | |
15194 | 1581 -nargs=1 Exactly one argument is required, it includes spaces |
2826 | 1582 -nargs=* Any number of arguments are allowed (0, 1, or many), |
1583 separated by white space | |
7 | 1584 -nargs=? 0 or 1 arguments are allowed |
1585 -nargs=+ Arguments must be supplied, but any number are allowed | |
1586 | |
1236 | 1587 Arguments are considered to be separated by (unescaped) spaces or tabs in this |
2826 | 1588 context, except when there is one argument, then the white space is part of |
1589 the argument. | |
7 | 1590 |
1591 Note that arguments are used as text, not as expressions. Specifically, | |
1592 "s:var" will use the script-local variable in the script where the command was | |
1593 defined, not where it is invoked! Example: | |
1594 script1.vim: > | |
1595 :let s:error = "None" | |
1596 :command -nargs=1 Error echoerr <args> | |
1597 < script2.vim: > | |
1598 :source script1.vim | |
1599 :let s:error = "Wrong!" | |
1600 :Error s:error | |
1619 | 1601 Executing script2.vim will result in "None" being echoed. Not what you |
7 | 1602 intended! Calling a function may be an alternative. |
1603 | |
15125
b101b193d5ff
patch 8.1.0573: cannot redefine user command without ! in same script
Bram Moolenaar <Bram@vim.org>
parents:
14864
diff
changeset
|
1604 |
b101b193d5ff
patch 8.1.0573: cannot redefine user command without ! in same script
Bram Moolenaar <Bram@vim.org>
parents:
14864
diff
changeset
|
1605 Completion behavior ~ |
15194 | 1606 *:command-completion* *E179* *E180* *E181* |
15125
b101b193d5ff
patch 8.1.0573: cannot redefine user command without ! in same script
Bram Moolenaar <Bram@vim.org>
parents:
14864
diff
changeset
|
1607 *:command-complete* |
7 | 1608 By default, the arguments of user defined commands do not undergo completion. |
1609 However, by specifying one or the other of the following attributes, argument | |
1610 completion can be enabled: | |
1611 | |
13551
1fd0f8392946
patch 8.0.1649: no completion for argument list commands
Christian Brabandt <cb@256bit.org>
parents:
12559
diff
changeset
|
1612 -complete=arglist file names in argument list |
7 | 1613 -complete=augroup autocmd groups |
1614 -complete=buffer buffer names | |
3503 | 1615 -complete=behave :behave suboptions |
2970 | 1616 -complete=color color schemes |
7 | 1617 -complete=command Ex command (and arguments) |
2970 | 1618 -complete=compiler compilers |
2596 | 1619 -complete=cscope |:cscope| suboptions |
7 | 1620 -complete=dir directory names |
1621 -complete=environment environment variable names | |
1622 -complete=event autocommand events | |
1623 -complete=expression Vim expression | |
1624 -complete=file file and directory names | |
2970 | 1625 -complete=file_in_path file and directory names in |'path'| |
2444
3fbd9bce03f1
Support syntax and filetype completion for user commands. (Christian Brabandt)
Bram Moolenaar <bram@vim.org>
parents:
2420
diff
changeset
|
1626 -complete=filetype filetype names |'filetype'| |
7 | 1627 -complete=function function name |
1628 -complete=help help subjects | |
1629 -complete=highlight highlight groups | |
3503 | 1630 -complete=history :history suboptions |
2970 | 1631 -complete=locale locale names (as output of locale -a) |
11995
7df3dd3c0ac1
patch 8.0.0878: no completion for :mapclear
Christian Brabandt <cb@256bit.org>
parents:
11473
diff
changeset
|
1632 -complete=mapclear buffer argument |
7 | 1633 -complete=mapping mapping name |
1634 -complete=menu menus | |
10275
6d8b2da002e9
commit https://github.com/vim/vim/commit/9e507ca8a3e1535e62de4bd86374b0fcd18ef5b8
Christian Brabandt <cb@256bit.org>
parents:
10198
diff
changeset
|
1635 -complete=messages |:messages| suboptions |
7 | 1636 -complete=option options |
9464
be72f4201a1d
commit https://github.com/vim/vim/commit/063b9d15abea041a5bfff3ffc4e219e26fd1d4fa
Christian Brabandt <cb@256bit.org>
parents:
9286
diff
changeset
|
1637 -complete=packadd optional package |pack-add| names |
2444
3fbd9bce03f1
Support syntax and filetype completion for user commands. (Christian Brabandt)
Bram Moolenaar <bram@vim.org>
parents:
2420
diff
changeset
|
1638 -complete=shellcmd Shell command |
2596 | 1639 -complete=sign |:sign| suboptions |
2444
3fbd9bce03f1
Support syntax and filetype completion for user commands. (Christian Brabandt)
Bram Moolenaar <bram@vim.org>
parents:
2420
diff
changeset
|
1640 -complete=syntax syntax file names |'syntax'| |
4803
220bdea4f579
updated for version 7.3.1148
Bram Moolenaar <bram@vim.org>
parents:
4358
diff
changeset
|
1641 -complete=syntime |:syntime| suboptions |
7 | 1642 -complete=tag tags |
1643 -complete=tag_listfiles tags, file names are shown when CTRL-D is hit | |
3744 | 1644 -complete=user user names |
7 | 1645 -complete=var user variables |
1646 -complete=custom,{func} custom completion, defined via {func} | |
406 | 1647 -complete=customlist,{func} custom completion, defined via {func} |
7 | 1648 |
27321 | 1649 If you specify completion while there is nothing to complete (-nargs=0, the |
1650 default) then you get error *E1208* . | |
6259 | 1651 Note: That some completion methods might expand environment variables. |
1652 | |
557 | 1653 |
15125
b101b193d5ff
patch 8.1.0573: cannot redefine user command without ! in same script
Bram Moolenaar <Bram@vim.org>
parents:
14864
diff
changeset
|
1654 Custom completion ~ |
b101b193d5ff
patch 8.1.0573: cannot redefine user command without ! in same script
Bram Moolenaar <Bram@vim.org>
parents:
14864
diff
changeset
|
1655 *:command-completion-custom* |
b101b193d5ff
patch 8.1.0573: cannot redefine user command without ! in same script
Bram Moolenaar <Bram@vim.org>
parents:
14864
diff
changeset
|
1656 *:command-completion-customlist* *E467* *E468* |
7 | 1657 It is possible to define customized completion schemes via the "custom,{func}" |
406 | 1658 or the "customlist,{func}" completion argument. The {func} part should be a |
1619 | 1659 function with the following signature: > |
7 | 1660 |
1661 :function {func}(ArgLead, CmdLine, CursorPos) | |
1662 | |
406 | 1663 The function need not use all these arguments. The function should provide the |
1664 completion candidates as the return value. | |
1665 | |
1666 For the "custom" argument, the function should return the completion | |
1667 candidates one per line in a newline separated string. | |
30324 | 1668 *E1303* |
406 | 1669 For the "customlist" argument, the function should return the completion |
557 | 1670 candidates as a Vim List. Non-string items in the list are ignored. |
406 | 1671 |
1672 The function arguments are: | |
7 | 1673 ArgLead the leading portion of the argument currently being |
1674 completed on | |
1675 CmdLine the entire command line | |
557 | 1676 CursorPos the cursor position in it (byte index) |
406 | 1677 The function may use these for determining context. For the "custom" |
1678 argument, it is not necessary to filter candidates against the (implicit | |
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1969
diff
changeset
|
1679 pattern in) ArgLead. Vim will filter the candidates with its regexp engine |
28010 | 1680 after function return, and this is probably more efficient in most cases. If |
1681 'wildoptions' contains "fuzzy", then the candidates will be filtered using | |
1682 |fuzzy-matching|. For the "customlist" argument, Vim will not | |
1683 filter the returned completion candidates and the user supplied function | |
1684 should filter the candidates. | |
7 | 1685 |
1686 The following example lists user names to a Finger command > | |
1687 :com -complete=custom,ListUsers -nargs=1 Finger !finger <args> | |
1688 :fun ListUsers(A,L,P) | |
1689 : return system("cut -d: -f1 /etc/passwd") | |
1690 :endfun | |
1691 | |
406 | 1692 The following example completes filenames from the directories specified in |
1693 the 'path' option: > | |
1694 :com -nargs=1 -bang -complete=customlist,EditFileComplete | |
1695 \ EditFile edit<bang> <args> | |
1696 :fun EditFileComplete(A,L,P) | |
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1969
diff
changeset
|
1697 : return split(globpath(&path, a:A), "\n") |
406 | 1698 :endfun |
1699 < | |
2420
6de9efd58dc0
Updated runtime files. New netrw plugin version.
Bram Moolenaar <bram@vim.org>
parents:
2413
diff
changeset
|
1700 This example does not work for file names with spaces! |
6de9efd58dc0
Updated runtime files. New netrw plugin version.
Bram Moolenaar <bram@vim.org>
parents:
2413
diff
changeset
|
1701 |
557 | 1702 |
15125
b101b193d5ff
patch 8.1.0573: cannot redefine user command without ! in same script
Bram Moolenaar <Bram@vim.org>
parents:
14864
diff
changeset
|
1703 Range handling ~ |
b101b193d5ff
patch 8.1.0573: cannot redefine user command without ! in same script
Bram Moolenaar <Bram@vim.org>
parents:
14864
diff
changeset
|
1704 *E177* *E178* *:command-range* *:command-count* |
236 | 1705 By default, user-defined commands do not accept a line number range. However, |
7 | 1706 it is possible to specify that the command does take a range (the -range |
1707 attribute), or that it takes an arbitrary count value, either in the line | |
1708 number position (-range=N, like the |:split| command) or as a "count" | |
1132 | 1709 argument (-count=N, like the |:Next| command). The count will then be |
1710 available in the argument with |<count>|. | |
1711 | |
1712 Possible attributes are: | |
7 | 1713 |
1714 -range Range allowed, default is current line | |
1715 -range=% Range allowed, default is whole file (1,$) | |
1716 -range=N A count (default N) which is specified in the line | |
2788 | 1717 number position (like |:split|); allows for zero line |
1718 number. | |
7 | 1719 -count=N A count (default N) which is specified either in the line |
171 | 1720 number position, or as an initial argument (like |:Next|). |
31383 | 1721 -count Acts like -count=0 |
7 | 1722 |
1723 Note that -range=N and -count=N are mutually exclusive - only one should be | |
1724 specified. | |
1725 | |
8951
0bdeaf7092bc
commit https://github.com/vim/vim/commit/aa3b15dbebf333282503d6031e2f9ba6ee4398ed
Christian Brabandt <cb@256bit.org>
parents:
7597
diff
changeset
|
1726 *:command-addr* |
6424 | 1727 It is possible that the special characters in the range like ., $ or % which |
1728 by default correspond to the current line, last line and the whole buffer, | |
1729 relate to arguments, (loaded) buffers, windows or tab pages. | |
1730 | |
16399
47d6e874955c
patch 8.1.1204: output of :command with address completion is not nice
Bram Moolenaar <Bram@vim.org>
parents:
15194
diff
changeset
|
1731 Possible values are (second column is the short name used in listing): |
32004 | 1732 -addr=lines Range of lines (this is the default for -range) |
16399
47d6e874955c
patch 8.1.1204: output of :command with address completion is not nice
Bram Moolenaar <Bram@vim.org>
parents:
15194
diff
changeset
|
1733 -addr=arguments arg Range for arguments |
47d6e874955c
patch 8.1.1204: output of :command with address completion is not nice
Bram Moolenaar <Bram@vim.org>
parents:
15194
diff
changeset
|
1734 -addr=buffers buf Range for buffers (also not loaded buffers) |
47d6e874955c
patch 8.1.1204: output of :command with address completion is not nice
Bram Moolenaar <Bram@vim.org>
parents:
15194
diff
changeset
|
1735 -addr=loaded_buffers load Range for loaded buffers |
47d6e874955c
patch 8.1.1204: output of :command with address completion is not nice
Bram Moolenaar <Bram@vim.org>
parents:
15194
diff
changeset
|
1736 -addr=windows win Range for windows |
47d6e874955c
patch 8.1.1204: output of :command with address completion is not nice
Bram Moolenaar <Bram@vim.org>
parents:
15194
diff
changeset
|
1737 -addr=tabs tab Range for tab pages |
47d6e874955c
patch 8.1.1204: output of :command with address completion is not nice
Bram Moolenaar <Bram@vim.org>
parents:
15194
diff
changeset
|
1738 -addr=quickfix qf Range for quickfix entries |
31383 | 1739 -addr=other ? Other kind of range; can use ".", "$" and "%" |
16553
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16399
diff
changeset
|
1740 as with "lines" (this is the default for |
0e473e9e70c2
patch 8.1.1280: remarks about functionality not in Vi clutters the help
Bram Moolenaar <Bram@vim.org>
parents:
16399
diff
changeset
|
1741 -count) |
6424 | 1742 |
15125
b101b193d5ff
patch 8.1.0573: cannot redefine user command without ! in same script
Bram Moolenaar <Bram@vim.org>
parents:
14864
diff
changeset
|
1743 |
b101b193d5ff
patch 8.1.0573: cannot redefine user command without ! in same script
Bram Moolenaar <Bram@vim.org>
parents:
14864
diff
changeset
|
1744 Special cases ~ |
b101b193d5ff
patch 8.1.0573: cannot redefine user command without ! in same script
Bram Moolenaar <Bram@vim.org>
parents:
14864
diff
changeset
|
1745 *:command-bang* *:command-bar* |
1132 | 1746 *:command-register* *:command-buffer* |
26148 | 1747 *:command-keepscript* |
7 | 1748 There are some special cases as well: |
1749 | |
1750 -bang The command can take a ! modifier (like :q or :w) | |
1751 -bar The command can be followed by a "|" and another command. | |
1752 A "|" inside the command argument is not allowed then. | |
1753 Also checks for a " to start a comment. | |
1754 -register The first argument to the command can be an optional | |
1755 register name (like :del, :put, :yank). | |
1756 -buffer The command will only be available in the current buffer. | |
26103
d079ab2ba260
patch 8.2.3584: "verbose set efm" reports location of the :compiler command
Bram Moolenaar <Bram@vim.org>
parents:
26050
diff
changeset
|
1757 -keepscript Do not use the location of where the user command was |
d079ab2ba260
patch 8.2.3584: "verbose set efm" reports location of the :compiler command
Bram Moolenaar <Bram@vim.org>
parents:
26050
diff
changeset
|
1758 defined for verbose messages, use the location of where |
d079ab2ba260
patch 8.2.3584: "verbose set efm" reports location of the :compiler command
Bram Moolenaar <Bram@vim.org>
parents:
26050
diff
changeset
|
1759 the user command was invoked. |
7 | 1760 |
1761 In the cases of the -count and -register attributes, if the optional argument | |
1762 is supplied, it is removed from the argument list and is available to the | |
1763 replacement text separately. | |
5340 | 1764 Note that these arguments can be abbreviated, but that is a deprecated |
1765 feature. Use the full name for new scripts. | |
7 | 1766 |
15125
b101b193d5ff
patch 8.1.0573: cannot redefine user command without ! in same script
Bram Moolenaar <Bram@vim.org>
parents:
14864
diff
changeset
|
1767 |
b101b193d5ff
patch 8.1.0573: cannot redefine user command without ! in same script
Bram Moolenaar <Bram@vim.org>
parents:
14864
diff
changeset
|
1768 Replacement text ~ |
25463
05f9e8f2016c
patch 8.2.3268: cannot use a block with :autocmd like with :command
Bram Moolenaar <Bram@vim.org>
parents:
25402
diff
changeset
|
1769 *:command-repl* |
25382
b80e4e9c4988
patch 8.2.3228: cannot use a simple block for the :command argument
Bram Moolenaar <Bram@vim.org>
parents:
24636
diff
changeset
|
1770 The {repl} argument is normally one long string, possibly with "|" separated |
b80e4e9c4988
patch 8.2.3228: cannot use a simple block for the :command argument
Bram Moolenaar <Bram@vim.org>
parents:
24636
diff
changeset
|
1771 commands. A special case is when the argument is "{", then the following |
b80e4e9c4988
patch 8.2.3228: cannot use a simple block for the :command argument
Bram Moolenaar <Bram@vim.org>
parents:
24636
diff
changeset
|
1772 lines, up to a line starting with "}" are used and |Vim9| syntax applies. |
b80e4e9c4988
patch 8.2.3228: cannot use a simple block for the :command argument
Bram Moolenaar <Bram@vim.org>
parents:
24636
diff
changeset
|
1773 Example: > |
b80e4e9c4988
patch 8.2.3228: cannot use a simple block for the :command argument
Bram Moolenaar <Bram@vim.org>
parents:
24636
diff
changeset
|
1774 :command MyCommand { |
b80e4e9c4988
patch 8.2.3228: cannot use a simple block for the :command argument
Bram Moolenaar <Bram@vim.org>
parents:
24636
diff
changeset
|
1775 echo 'hello' |
b80e4e9c4988
patch 8.2.3228: cannot use a simple block for the :command argument
Bram Moolenaar <Bram@vim.org>
parents:
24636
diff
changeset
|
1776 g:calledMyCommand = true |
b80e4e9c4988
patch 8.2.3228: cannot use a simple block for the :command argument
Bram Moolenaar <Bram@vim.org>
parents:
24636
diff
changeset
|
1777 } |
25521
2063b858cad9
patch 8.2.3297: cannot use all commands inside a {} block
Bram Moolenaar <Bram@vim.org>
parents:
25463
diff
changeset
|
1778 < *E1231* |
2063b858cad9
patch 8.2.3297: cannot use all commands inside a {} block
Bram Moolenaar <Bram@vim.org>
parents:
25463
diff
changeset
|
1779 There must be white space before the "{". No nesting is supported, inline |
2063b858cad9
patch 8.2.3297: cannot use all commands inside a {} block
Bram Moolenaar <Bram@vim.org>
parents:
25463
diff
changeset
|
1780 functions cannot be used. Commands where a "|" may appear in the argument, |
2063b858cad9
patch 8.2.3297: cannot use all commands inside a {} block
Bram Moolenaar <Bram@vim.org>
parents:
25463
diff
changeset
|
1781 such as commands with an expression argument, cannot be followed by a "|" and |
2063b858cad9
patch 8.2.3297: cannot use all commands inside a {} block
Bram Moolenaar <Bram@vim.org>
parents:
25463
diff
changeset
|
1782 another command. |
25382
b80e4e9c4988
patch 8.2.3228: cannot use a simple block for the :command argument
Bram Moolenaar <Bram@vim.org>
parents:
24636
diff
changeset
|
1783 |
23164 | 1784 The replacement text {repl} for a user defined command is scanned for special |
1785 escape sequences, using <...> notation. Escape sequences are replaced with | |
1786 values from the entered command line, and all other text is copied unchanged. | |
1787 The resulting string is executed as an Ex command. To avoid the replacement | |
1788 use <lt> in place of the initial <. Thus to include "<bang>" literally use | |
788 | 1789 "<lt>bang>". |
7 | 1790 |
1791 The valid escape sequences are | |
1792 | |
1793 *<line1>* | |
1794 <line1> The starting line of the command range. | |
1795 *<line2>* | |
1796 <line2> The final line of the command range. | |
12419
d216d9e8ac57
patch 8.0.1089: cannot get range count in user command
Christian Brabandt <cb@256bit.org>
parents:
11995
diff
changeset
|
1797 *<range>* |
d216d9e8ac57
patch 8.0.1089: cannot get range count in user command
Christian Brabandt <cb@256bit.org>
parents:
11995
diff
changeset
|
1798 <range> The number of items in the command range: 0, 1 or 2 |
7 | 1799 *<count>* |
1800 <count> Any count supplied (as described for the '-range' | |
1801 and '-count' attributes). | |
1802 *<bang>* | |
1803 <bang> (See the '-bang' attribute) Expands to a ! if the | |
1804 command was executed with a ! modifier, otherwise | |
1805 expands to nothing. | |
22328 | 1806 *<mods>* *<q-mods>* *:command-modifiers* |
9230
f7fb117883ba
commit https://github.com/vim/vim/commit/63a60ded3fd584847a05dccf058026e682abad90
Christian Brabandt <cb@256bit.org>
parents:
8951
diff
changeset
|
1807 <mods> The command modifiers, if specified. Otherwise, expands to |
9286
64035abb986b
commit https://github.com/vim/vim/commit/c95a302a4c42ec8230473cd4a5e0064d0a143aa8
Christian Brabandt <cb@256bit.org>
parents:
9230
diff
changeset
|
1808 nothing. Supported modifiers are |:aboveleft|, |:belowright|, |
30017
578e71f924fe
patch 9.0.0346: :horizontal modifier not fully supported
Bram Moolenaar <Bram@vim.org>
parents:
29450
diff
changeset
|
1809 |:botright|, |:browse|, |:confirm|, |:hide|, |:horizontal|, |
578e71f924fe
patch 9.0.0346: :horizontal modifier not fully supported
Bram Moolenaar <Bram@vim.org>
parents:
29450
diff
changeset
|
1810 |:keepalt|, |:keepjumps|, |:keepmarks|, |:keeppatterns|, |
578e71f924fe
patch 9.0.0346: :horizontal modifier not fully supported
Bram Moolenaar <Bram@vim.org>
parents:
29450
diff
changeset
|
1811 |:leftabove|, |:lockmarks|, |:noautocmd|, |:noswapfile| |
578e71f924fe
patch 9.0.0346: :horizontal modifier not fully supported
Bram Moolenaar <Bram@vim.org>
parents:
29450
diff
changeset
|
1812 |:rightbelow|, |:sandbox|, |:silent|, |:tab|, |:topleft|, |
578e71f924fe
patch 9.0.0346: :horizontal modifier not fully supported
Bram Moolenaar <Bram@vim.org>
parents:
29450
diff
changeset
|
1813 |:unsilent|, |:verbose|, and |:vertical|. |
29377
48b086982c01
patch 9.0.0031: <cmod> of user command does not have correct verbose value
Bram Moolenaar <Bram@vim.org>
parents:
29314
diff
changeset
|
1814 Note that |:filter| is not supported. |
9230
f7fb117883ba
commit https://github.com/vim/vim/commit/63a60ded3fd584847a05dccf058026e682abad90
Christian Brabandt <cb@256bit.org>
parents:
8951
diff
changeset
|
1815 Examples: > |
f7fb117883ba
commit https://github.com/vim/vim/commit/63a60ded3fd584847a05dccf058026e682abad90
Christian Brabandt <cb@256bit.org>
parents:
8951
diff
changeset
|
1816 command! -nargs=+ -complete=file MyEdit |
f7fb117883ba
commit https://github.com/vim/vim/commit/63a60ded3fd584847a05dccf058026e682abad90
Christian Brabandt <cb@256bit.org>
parents:
8951
diff
changeset
|
1817 \ for f in expand(<q-args>, 0, 1) | |
27903 | 1818 \ exe '<mods> split ' .. f | |
9230
f7fb117883ba
commit https://github.com/vim/vim/commit/63a60ded3fd584847a05dccf058026e682abad90
Christian Brabandt <cb@256bit.org>
parents:
8951
diff
changeset
|
1819 \ endfor |
f7fb117883ba
commit https://github.com/vim/vim/commit/63a60ded3fd584847a05dccf058026e682abad90
Christian Brabandt <cb@256bit.org>
parents:
8951
diff
changeset
|
1820 |
f7fb117883ba
commit https://github.com/vim/vim/commit/63a60ded3fd584847a05dccf058026e682abad90
Christian Brabandt <cb@256bit.org>
parents:
8951
diff
changeset
|
1821 function! SpecialEdit(files, mods) |
f7fb117883ba
commit https://github.com/vim/vim/commit/63a60ded3fd584847a05dccf058026e682abad90
Christian Brabandt <cb@256bit.org>
parents:
8951
diff
changeset
|
1822 for f in expand(a:files, 0, 1) |
27903 | 1823 exe a:mods .. ' split ' .. f |
9230
f7fb117883ba
commit https://github.com/vim/vim/commit/63a60ded3fd584847a05dccf058026e682abad90
Christian Brabandt <cb@256bit.org>
parents:
8951
diff
changeset
|
1824 endfor |
f7fb117883ba
commit https://github.com/vim/vim/commit/63a60ded3fd584847a05dccf058026e682abad90
Christian Brabandt <cb@256bit.org>
parents:
8951
diff
changeset
|
1825 endfunction |
f7fb117883ba
commit https://github.com/vim/vim/commit/63a60ded3fd584847a05dccf058026e682abad90
Christian Brabandt <cb@256bit.org>
parents:
8951
diff
changeset
|
1826 command! -nargs=+ -complete=file Sedit |
f7fb117883ba
commit https://github.com/vim/vim/commit/63a60ded3fd584847a05dccf058026e682abad90
Christian Brabandt <cb@256bit.org>
parents:
8951
diff
changeset
|
1827 \ call SpecialEdit(<q-args>, <q-mods>) |
f7fb117883ba
commit https://github.com/vim/vim/commit/63a60ded3fd584847a05dccf058026e682abad90
Christian Brabandt <cb@256bit.org>
parents:
8951
diff
changeset
|
1828 < |
7 | 1829 *<reg>* *<register>* |
1830 <reg> (See the '-register' attribute) The optional register, | |
236 | 1831 if specified. Otherwise, expands to nothing. <register> |
7 | 1832 is a synonym for this. |
1833 *<args>* | |
1834 <args> The command arguments, exactly as supplied (but as | |
1835 noted above, any count or register can consume some | |
1836 of the arguments, which are then not part of <args>). | |
1837 <lt> A single '<' (Less-Than) character. This is needed if you | |
1838 want to get a literal copy of one of these escape sequences | |
1839 into the expansion - for example, to get <bang>, use | |
1840 <lt>bang>. | |
1841 | |
1842 *<q-args>* | |
1843 If the first two characters of an escape sequence are "q-" (for example, | |
1844 <q-args>) then the value is quoted in such a way as to make it a valid value | |
1845 for use in an expression. This uses the argument as one single value. | |
30547 | 1846 When there is no argument <q-args> is an empty string. See the |
1847 |q-args-example| below. | |
1088 | 1848 *<f-args>* |
7 | 1849 To allow commands to pass their arguments on to a user-defined function, there |
236 | 1850 is a special form <f-args> ("function args"). This splits the command |
1236 | 1851 arguments at spaces and tabs, quotes each argument individually, and the |
7 | 1852 <f-args> sequence is replaced by the comma-separated list of quoted arguments. |
856 | 1853 See the Mycmd example below. If no arguments are given <f-args> is removed. |
1088 | 1854 To embed whitespace into an argument of <f-args>, prepend a backslash. |
1855 <f-args> replaces every pair of backslashes (\\) with one backslash. A | |
1856 backslash followed by a character other than white space or a backslash | |
30547 | 1857 remains unmodified. Also see |f-args-example| below. Overview: |
1088 | 1858 |
1859 command <f-args> ~ | |
1860 XX ab 'ab' | |
1861 XX a\b 'a\b' | |
1862 XX a\ b 'a b' | |
1863 XX a\ b 'a ', 'b' | |
1864 XX a\\b 'a\b' | |
1865 XX a\\ b 'a\', 'b' | |
1866 XX a\\\b 'a\\b' | |
1867 XX a\\\ b 'a\ b' | |
1868 XX a\\\\b 'a\\b' | |
1869 XX a\\\\ b 'a\\', 'b' | |
7 | 1870 |
30547 | 1871 |
1872 Examples for user commands: > | |
7 | 1873 |
1874 " Delete everything after here to the end | |
1875 :com Ddel +,$d | |
1876 | |
1877 " Rename the current buffer | |
1878 :com -nargs=1 -bang -complete=file Ren f <args>|w<bang> | |
1879 | |
1880 " Replace a range with the contents of a file | |
1881 " (Enter this all as one line) | |
1882 :com -range -nargs=1 -complete=file | |
1883 Replace <line1>-pu_|<line1>,<line2>d|r <args>|<line1>d | |
1884 | |
1885 " Count the number of lines in the range | |
42 | 1886 :com! -range -nargs=0 Lines echo <line2> - <line1> + 1 "lines" |
7 | 1887 |
30547 | 1888 < *f-args-example* |
1889 Call a user function (example of <f-args>) > | |
7 | 1890 :com -nargs=* Mycmd call Myfunc(<f-args>) |
1891 | |
1892 When executed as: > | |
1893 :Mycmd arg1 arg2 | |
1894 This will invoke: > | |
1895 :call Myfunc("arg1","arg2") | |
1896 | |
31200 | 1897 < *q-args-example* |
30547 | 1898 A more substantial example: > |
7 | 1899 :function Allargs(command) |
1619 | 1900 : let i = 0 |
1901 : while i < argc() | |
1902 : if filereadable(argv(i)) | |
27903 | 1903 : execute "e " .. argv(i) |
7 | 1904 : execute a:command |
1905 : endif | |
1906 : let i = i + 1 | |
1907 : endwhile | |
1908 :endfunction | |
1909 :command -nargs=+ -complete=command Allargs call Allargs(<q-args>) | |
1910 | |
1911 The command Allargs takes any Vim command(s) as argument and executes it on all | |
1912 files in the argument list. Usage example (note use of the "e" flag to ignore | |
1913 errors and the "update" command to write modified buffers): > | |
1914 :Allargs %s/foo/bar/ge|update | |
1915 This will invoke: > | |
1916 :call Allargs("%s/foo/bar/ge|update") | |
1917 < | |
23164 | 1918 If the command is defined in Vim9 script (a script that starts with |
1919 `:vim9script` and in a `:def` function) then {repl} will be executed as in Vim9 | |
1920 script. Thus this depends on where the command is defined, not where it is | |
1921 used. | |
1922 | |
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1969
diff
changeset
|
1923 When defining a user command in a script, it will be able to call functions |
7 | 1924 local to the script and use mappings local to the script. When the user |
1925 invokes the user command, it will run in the context of the script it was | |
1926 defined in. This matters if |<SID>| is used in a command. | |
1927 | |
14421 | 1928 vim:tw=78:ts=8:noet:ft=help:norl: |