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