patch 8.2.1978: making a mapping work in all modes is complicated
Problem: Making a mapping work in all modes is complicated.
Solution: Add the <Cmd> special key. (Yegappan Lakshmanan, closes #7282,
closes 4784, based on patch by Bjorn Linse)
diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt
index a540704..0a668c1 100644
--- a/runtime/doc/autocmd.txt
+++ b/runtime/doc/autocmd.txt
@@ -551,12 +551,15 @@
*CmdlineEnter*
CmdlineEnter After moving the cursor to the command line,
where the user can type a command or search
- string.
+ string; including non-interactive use of ":"
+ in a mapping, but not when using |<Cmd>|.
<afile> is set to a single character,
indicating the type of command-line.
|cmdwin-char|
*CmdlineLeave*
-CmdlineLeave Before leaving the command line.
+CmdlineLeave Before leaving the command line; including
+ non-interactive use of ":" in a mapping, but
+ not when using |<Cmd>|.
Also when abandoning the command line, after
typing CTRL-C or <Esc>.
When the commands result in an error the
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index c08b75b..3303cab 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -8660,6 +8660,7 @@
the following mappings: >
nnoremap <expr> GG ":echom ".screencol()."\n"
nnoremap <silent> GG :echom screencol()<CR>
+ nnoremap GG <Cmd>echom screencol()<CR>
<
screenpos({winid}, {lnum}, {col}) *screenpos()*
The result is a Dict with the screen position of the text
diff --git a/runtime/doc/map.txt b/runtime/doc/map.txt
index 276ab50..83a5428 100644
--- a/runtime/doc/map.txt
+++ b/runtime/doc/map.txt
@@ -1,4 +1,4 @@
-*map.txt* For Vim version 8.2. Last change: 2020 Oct 07
+*map.txt* For Vim version 8.2. Last change: 2020 Nov 12
VIM REFERENCE MANUAL by Bram Moolenaar
@@ -271,7 +271,7 @@
- The |:normal| command.
- Moving the cursor is allowed, but it is restored afterwards.
If you want the mapping to do any of these let the returned characters do
-that.
+that, or use a |<Cmd>| mapping instead.
You can use getchar(), it consumes typeahead if there is any. E.g., if you
have these mappings: >
@@ -303,6 +303,40 @@
Note that using 0x80 as a single byte before other text does not work, it will
be seen as a special key.
+ *<Cmd>* *:map-cmd*
+The special text <Cmd> begins a "command mapping", it executes the command
+directly without changing modes. Where you might use ":...<CR>" in the
+{rhs} of a mapping, you can instead use "<Cmd>...<CR>".
+Example: >
+ noremap x <Cmd>echo mode(1)<CR>
+<
+This is more flexible than `:<C-U>` in Visual and Operator-pending mode, or
+`<C-O>:` in Insert mode, because the commands are executed directly in the
+current mode, instead of always going to Normal mode. Visual mode is
+preserved, so tricks with |gv| are not needed. Commands can be invoked
+directly in Command-line mode (which would otherwise require timer hacks).
+Example of using <Cmd> halfway Insert mode: >
+ nnoremap <F3> aText <Cmd>echo mode(1)<CR> Added<Esc>
+
+Unlike <expr> mappings, there are no special restrictions on the <Cmd>
+command: it is executed as if an (unrestricted) |autocmd| was invoked.
+
+Note:
+- Because <Cmd> avoids mode-changes it does not trigger |CmdlineEnter| and
+ |CmdlineLeave| events, because no user interaction is expected.
+- For the same reason, |keycodes| like <C-R><C-W> are interpreted as plain,
+ unmapped keys.
+- In Select mode, |:map| and |:vmap| command mappings are executed in
+ Visual mode. Use |:smap| to handle Select mode differently.
+
+ *E1135* *E1136*
+<Cmd> commands must terminate, that is, they must be followed by <CR> in the
+{rhs} of the mapping definition. |Command-line| mode is never entered.
+
+ *E1137*
+<Cmd> commands can have only normal characters and cannot contain special
+characters like function keys.
+
1.3 MAPPING AND MODES *:map-modes*
*mapmode-nvo* *mapmode-n* *mapmode-v* *mapmode-o*