|
1 | | -*map.txt* For Vim version 8.2. Last change: 2020 Oct 07 |
| 1 | +*map.txt* For Vim version 8.2. Last change: 2020 Nov 12 |
2 | 2 |
|
3 | 3 |
|
4 | 4 | VIM REFERENCE MANUAL by Bram Moolenaar |
@@ -271,7 +271,7 @@ For this reason the following is blocked: |
271 | 271 | - The |:normal| command. |
272 | 272 | - Moving the cursor is allowed, but it is restored afterwards. |
273 | 273 | If you want the mapping to do any of these let the returned characters do |
274 | | -that. |
| 274 | +that, or use a |<Cmd>| mapping instead. |
275 | 275 |
|
276 | 276 | You can use getchar(), it consumes typeahead if there is any. E.g., if you |
277 | 277 | have these mappings: > |
@@ -303,6 +303,40 @@ empty string, so that nothing is inserted. |
303 | 303 | Note that using 0x80 as a single byte before other text does not work, it will |
304 | 304 | be seen as a special key. |
305 | 305 |
|
| 306 | + *<Cmd>* *:map-cmd* |
| 307 | +The special text <Cmd> begins a "command mapping", it executes the command |
| 308 | +directly without changing modes. Where you might use ":...<CR>" in the |
| 309 | +{rhs} of a mapping, you can instead use "<Cmd>...<CR>". |
| 310 | +Example: > |
| 311 | + noremap x <Cmd>echo mode(1)<CR> |
| 312 | +< |
| 313 | +This is more flexible than `:<C-U>` in Visual and Operator-pending mode, or |
| 314 | +`<C-O>:` in Insert mode, because the commands are executed directly in the |
| 315 | +current mode, instead of always going to Normal mode. Visual mode is |
| 316 | +preserved, so tricks with |gv| are not needed. Commands can be invoked |
| 317 | +directly in Command-line mode (which would otherwise require timer hacks). |
| 318 | +Example of using <Cmd> halfway Insert mode: > |
| 319 | + nnoremap <F3> aText <Cmd>echo mode(1)<CR> Added<Esc> |
| 320 | +
|
| 321 | +Unlike <expr> mappings, there are no special restrictions on the <Cmd> |
| 322 | +command: it is executed as if an (unrestricted) |autocmd| was invoked. |
| 323 | + |
| 324 | +Note: |
| 325 | +- Because <Cmd> avoids mode-changes it does not trigger |CmdlineEnter| and |
| 326 | + |CmdlineLeave| events, because no user interaction is expected. |
| 327 | +- For the same reason, |keycodes| like <C-R><C-W> are interpreted as plain, |
| 328 | + unmapped keys. |
| 329 | +- In Select mode, |:map| and |:vmap| command mappings are executed in |
| 330 | + Visual mode. Use |:smap| to handle Select mode differently. |
| 331 | + |
| 332 | + *E1135* *E1136* |
| 333 | +<Cmd> commands must terminate, that is, they must be followed by <CR> in the |
| 334 | +{rhs} of the mapping definition. |Command-line| mode is never entered. |
| 335 | + |
| 336 | + *E1137* |
| 337 | +<Cmd> commands can have only normal characters and cannot contain special |
| 338 | +characters like function keys. |
| 339 | + |
306 | 340 |
|
307 | 341 | 1.3 MAPPING AND MODES *:map-modes* |
308 | 342 | *mapmode-nvo* *mapmode-n* *mapmode-v* *mapmode-o* |
|
0 commit comments