diff options
Diffstat (limited to 'runtime/doc/map.txt')
| -rw-r--r-- | runtime/doc/map.txt | 231 |
1 files changed, 119 insertions, 112 deletions
diff --git a/runtime/doc/map.txt b/runtime/doc/map.txt index 31c3198f72..fa5e10b5e5 100644 --- a/runtime/doc/map.txt +++ b/runtime/doc/map.txt @@ -1,4 +1,4 @@ -*map.txt* For Vim version 7.4. Last change: 2016 Jan 10 +*map.txt* Nvim VIM REFERENCE MANUAL by Bram Moolenaar @@ -9,27 +9,13 @@ Key mapping, abbreviations and user-defined commands. This subject is introduced in sections |05.3|, |24.7| and |40.1| of the user manual. -1. Key mapping |key-mapping| - 1.1 MAP COMMANDS |:map-commands| - 1.2 Special arguments |:map-arguments| - 1.3 Mapping and modes |:map-modes| - 1.4 Listing mappings |map-listing| - 1.5 Mapping special keys |:map-special-keys| - 1.6 Special characters |:map-special-chars| - 1.7 What keys to map |map-which-keys| - 1.8 Examples |map-examples| - 1.9 Using mappings |map-typing| - 1.10 Mapping alt-keys |:map-alt-keys| - 1.11 Mapping an operator |:map-operator| -2. Abbreviations |abbreviations| -3. Local mappings and functions |script-local| -4. User-defined commands |user-commands| + Type |gO| to see the table of contents. ============================================================================== 1. Key mapping *key-mapping* *mapping* *macro* Key mapping is used to change the meaning of typed keys. The most common use -is to define a sequence commands for a function key. Example: > +is to define a sequence of commands for a function key. Example: > :map <F2> a<C-R>=strftime("%c")<CR><Esc> @@ -55,6 +41,7 @@ modes. :im[ap] {lhs} {rhs} |mapmode-i| *:im* *:imap* :lm[ap] {lhs} {rhs} |mapmode-l| *:lm* *:lmap* :cm[ap] {lhs} {rhs} |mapmode-c| *:cm* *:cmap* +:tma[p] {lhs} {rhs} |mapmode-t| *:tma* *:tmap* Map the key sequence {lhs} to {rhs} for the modes where the map command applies. The result, including {rhs}, is then further scanned for mappings. This @@ -71,6 +58,7 @@ modes. :ino[remap] {lhs} {rhs} |mapmode-i| *:ino* *:inoremap* :ln[oremap] {lhs} {rhs} |mapmode-l| *:ln* *:lnoremap* :cno[remap] {lhs} {rhs} |mapmode-c| *:cno* *:cnoremap* +:tno[remap] {lhs} {rhs} |mapmode-t| *:tno* *:tnoremap* Map the key sequence {lhs} to {rhs} for the modes where the map command applies. Disallow mapping of {rhs}, to avoid nested and recursive mappings. Often @@ -87,6 +75,7 @@ modes. :iu[nmap] {lhs} |mapmode-i| *:iu* *:iunmap* :lu[nmap] {lhs} |mapmode-l| *:lu* *:lunmap* :cu[nmap] {lhs} |mapmode-c| *:cu* *:cunmap* +:tunma[p] {lhs} |mapmode-t| *:tunma* *:tunmap* Remove the mapping of {lhs} for the modes where the map command applies. The mapping may remain defined for other modes where it applies. @@ -105,6 +94,7 @@ modes. :imapc[lear] |mapmode-i| *:imapc* *:imapclear* :lmapc[lear] |mapmode-l| *:lmapc* *:lmapclear* :cmapc[lear] |mapmode-c| *:cmapc* *:cmapclear* +:tmapc[lear] |mapmode-t| *:tmapc* *:tmapclear* Remove ALL mappings for the modes where the map command applies. Use the <buffer> argument to remove buffer-local @@ -121,6 +111,7 @@ modes. :im[ap] |mapmode-i| :lm[ap] |mapmode-l| :cm[ap] |mapmode-c| +:tma[p] |mapmode-t| List all key mappings for the modes where the map command applies. Note that ":map" and ":map!" are used most often, because they include the other modes. @@ -135,6 +126,7 @@ modes. :im[ap] {lhs} |mapmode-i| *:imap_l* :lm[ap] {lhs} |mapmode-l| *:lmap_l* :cm[ap] {lhs} |mapmode-c| *:cmap_l* +:tma[p] {lhs} |mapmode-t| *:tmap_l* List the key mappings for the key sequences starting with {lhs} in the modes where the map command applies. @@ -157,7 +149,7 @@ type "a", then "bar" will get inserted. 1.2 SPECIAL ARGUMENTS *:map-arguments* -"<buffer>", "<nowait>", "<silent>", "<special>", "<script>", "<expr>" and +"<buffer>", "<nowait>", "<silent>", "<script>", "<expr>" and "<unique>" can be used in any order. They must appear right after the command, before any other arguments. @@ -183,7 +175,7 @@ that starts with ",". Then you need to type another character for Vim to know whether to use the "," mapping or the longer one. To avoid this add the <nowait> argument. Then the mapping will be used when it matches, Vim does not wait for more characters to be typed. However, if the characters were -already type they are used. +already typed they are used. *:map-<silent>* *:map-silent* To define a mapping which will not be echoed on the command line, add @@ -197,12 +189,6 @@ Prompts will still be given, e.g., for inputdialog(). Using "<silent>" for an abbreviation is possible, but will cause redrawing of the command line to fail. - *:map-<special>* *:map-special* -Define a mapping with <> notation for special keys, even though the "<" flag -may appear in 'cpoptions'. This is useful if the side effect of setting -'cpoptions' is not desired. Example: > - :map <special> <F12> /Header<CR> -< *:map-<script>* *:map-script* If the first argument to one of these commands is "<script>" and it is used to define a new mapping or abbreviation, the mapping will only remap characters @@ -246,8 +232,9 @@ For this reason the following is blocked: - Editing another buffer. - The |:normal| command. - Moving the cursor is allowed, but it is restored afterwards. +- If the cmdline is changed, the old text and cursor position are restored. If you want the mapping to do any of these let the returned characters do -that. +that. Or use a |<Cmd>| mapping (which doesn't have these restrictions). You can use getchar(), it consumes typeahead if there is any. E.g., if you have these mappings: > @@ -286,11 +273,38 @@ again for using <expr>. This does work: > Using 0x80 as a single byte before other text does not work, it will be seen as a special key. + *<Cmd>* *:map-cmd* +The <Cmd> pseudokey may be used to define a "command mapping", which executes +the command directly (without changing modes, etc.). Where you might use +":...<CR>" in the {lhs} 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 cmdline-mode (which otherwise would require timer hacks). + +Because <Cmd> avoids mode-changes (unlike ":") it does not trigger +|CmdlineEnter| and |CmdlineLeave| events. This helps performance. + +Unlike <expr> mappings, there are no special restrictions on the <Cmd> +command: it is executed as if an (unrestricted) |autocmd| was invoked or an +async event event was processed. + +In select-mode, |:map| and |:vmap| command mappings are executed in +visual-mode. Use |:smap| to handle select-mode. + + *E5520* +<Cmd> commands must terminate, that is, they must be followed by <CR> in the +{lhs} of the mapping definition. |Command-line| mode is never entered. + 1.3 MAPPING AND MODES *:map-modes* - *mapmode-nvo* *mapmode-n* *mapmode-v* *mapmode-o* + *mapmode-nvo* *mapmode-n* *mapmode-v* *mapmode-o* *mapmode-t* -There are six sets of mappings +There are seven sets of mappings - For Normal mode: When typing commands. - For Visual mode: When typing commands while the Visual area is highlighted. - For Select mode: like Visual mode but typing text replaces the selection. @@ -298,6 +312,7 @@ There are six sets of mappings etc.). See below: |omap-info|. - For Insert mode. These are also used in Replace mode. - For Command-line mode: When entering a ":" or "/" command. +- For Terminal mode: When typing in a |:terminal| buffer. Special case: While typing a count for a command in Normal mode, mapping zero is disabled. This makes it possible to map zero without making it impossible @@ -316,6 +331,7 @@ Overview of which map command works in which mode. More details below. :imap :inoremap :iunmap Insert :lmap :lnoremap :lunmap Insert, Command-line, Lang-Arg :cmap :cnoremap :cunmap Command-line +:tmap :tnoremap :tunmap Terminal COMMANDS MODES ~ @@ -358,8 +374,9 @@ several modes. In Vim you can use the ":nmap", ":vmap", ":omap", ":cmap" and *omap-info* Operator-pending mappings can be used to define a movement command that can be -used with any operator. Simple example: ":omap { w" makes "y{" work like "yw" -and "d{" like "dw". +used with any operator. Simple example: > + :omap { w +makes "y{" work like "yw" and "d{" like "dw". To ignore the starting cursor position and select different text, you can have the omap start Visual mode to select the text to be operated upon. Example @@ -370,9 +387,11 @@ Normal mode commands find the first '(' character and select the first word before it. That usually is the function name. To enter a mapping for Normal and Visual mode, but not Operator-pending mode, -first define it for all three modes, then unmap it for Operator-pending mode: +first define it for all three modes, then unmap it for +Operator-pending mode: > :map xx something-difficult :ounmap xx + Likewise for a mapping for Visual and Operator-pending mode or Normal and Operator-pending mode. @@ -398,7 +417,8 @@ state for Insert mode is also used when typing a character as an argument to command like "f" or "t". Language mappings will never be applied to already mapped characters. They are only used for typed characters. This assumes that the language mapping -was already done when typing the mapping. +was already done when typing the mapping. Correspondingly, language mappings +are applied when recording macros, rather than when applying them. 1.4 LISTING MAPPINGS *map-listing* @@ -429,6 +449,9 @@ with a space. Note: When using mappings for Visual mode, you can use the "'<" mark, which is the start of the last selected Visual area in the current buffer |'<|. +The |:filter| command can be used to select what mappings to list. The +pattern is matched against the {lhs} and {rhs} in the raw form. + *:map-verbose* When 'verbose' is non-zero, listing a key map will also display where it was last defined. Example: > @@ -442,42 +465,28 @@ See |:verbose-cmd| for more information. 1.5 MAPPING SPECIAL KEYS *:map-special-keys* -There are three ways to map a special key: +There are two ways to map a special key: 1. The Vi-compatible method: Map the key code. Often this is a sequence that starts with <Esc>. To enter a mapping like this you type ":map " and then you have to type CTRL-V before hitting the function key. Note that when - the key code for the key is in the termcap (the t_ options), it will - automatically be translated into the internal code and become the second - way of mapping (unless the 'k' flag is included in 'cpoptions'). + the key code for the key is in the |terminfo| entry, it will automatically + be translated into the internal code and become the second way of mapping. 2. The second method is to use the internal code for the function key. To enter such a mapping type CTRL-K and then hit the function key, or use the form "#1", "#2", .. "#9", "#0", "<Up>", "<S-Down>", "<S-F7>", etc. (see table of keys |key-notation|, all keys from <Up> can be used). The first ten function keys can be defined in two ways: Just the number, like "#2", and with "<F>", like "<F2>". Both stand for function key 2. "#0" - refers to function key 10, defined with option 't_f10', which may be - function key zero on some keyboards. The <> form cannot be used when - 'cpoptions' includes the '<' flag. -3. Use the termcap entry, with the form <t_xx>, where "xx" is the name of the - termcap entry. Any string entry can be used. For example: > - :map <t_F3> G -< Maps function key 13 to "G". This does not work if 'cpoptions' includes - the '<' flag. - -The advantage of the second and third method is that the mapping will work on -different terminals without modification (the function key will be -translated into the same internal code or the actual key code, no matter what -terminal you are using. The termcap must be correct for this to work, and you -must use the same mappings). + refers to function key 10. DETAIL: Vim first checks if a sequence from the keyboard is mapped. If it -isn't the terminal key codes are tried (see |terminal-options|). If a -terminal code is found it is replaced with the internal code. Then the check -for a mapping is done again (so you can map an internal code to something -else). What is written into the script file depends on what is recognized. -If the terminal key code was recognized as a mapping the key code itself is -written to the script file. If it was recognized as a terminal code the -internal code is written to the script file. +isn't the terminal key codes are tried. If a terminal code is found it is +replaced with the internal code. Then the check for a mapping is done again +(so you can map an internal code to something else). What is written into the +script file depends on what is recognized. If the terminal key code was +recognized as a mapping the key code itself is written to the script file. If +it was recognized as a terminal code the internal code is written to the +script file. 1.6 SPECIAL CHARACTERS *:map-special-chars* @@ -579,16 +588,17 @@ Upper and lowercase differences are ignored. *map-comments* It is not possible to put a comment after these commands, because the '"' -character is considered to be part of the {lhs} or {rhs}. +character is considered to be part of the {lhs} or {rhs}. However, one can +use |", since this starts a new, empty command with a comment. *map_bar* *map-bar* Since the '|' character is used to separate a map command from the next command, you will have to do something special to include a '|' in {rhs}. There are three methods: use works when example ~ - <Bar> '<' is not in 'cpoptions' :map _l :!ls <Bar> more^M + <Bar> always :map _l :!ls <Bar> more^M \| 'b' is not in 'cpoptions' :map _l :!ls \| more^M - ^V| always, in Vim and Vi :map _l :!ls ^V| more^M + ^V| always :map _l :!ls ^V| more^M (here ^V stands for CTRL-V; to get one CTRL-V you have to type it twice; you cannot use the <> notation "<C-V>" here). @@ -643,8 +653,7 @@ out about, ^D is CTRL-D). 1.8 EXAMPLES *map-examples* -A few examples (given as you type them, for "<CR>" you type four characters; -the '<' flag must not be present in 'cpoptions' for this to work). > +A few examples (as you type them: for "<CR>" you type four characters). > :map <F3> o#include :map <M-g> /foo<CR>cwbar<Esc> @@ -676,7 +685,7 @@ option). After that it assumes that the 'q' is to be interpreted as such. If you type slowly, or your system is slow, reset the 'timeout' option. Then you might want to set the 'ttimeout' option. - *map-precedence* + *map-precedence* Buffer-local mappings (defined using |:map-<buffer>|) take precedence over global mappings. When a buffer-local mapping is the same as a global mapping, Vim will use the buffer-local mapping. In addition, Vim will use a complete @@ -712,9 +721,6 @@ special key: > Don't type a real <Esc>, Vim will recognize the key code and replace it with <F1> anyway. -Another problem may be that when keeping ALT or Meta pressed the terminal -prepends ESC instead of setting the 8th bit. See |:map-alt-keys|. - *recursive_mapping* If you include the {lhs} in the {rhs} you have a recursive mapping. When {lhs} is typed, it will be replaced with {rhs}. When the {lhs} which is @@ -754,46 +760,14 @@ in the original Vi, you would get back the text before the first undo). 1.10 MAPPING ALT-KEYS *:map-alt-keys* -In the GUI Vim handles the Alt key itself, thus mapping keys with ALT should -always work. But in a terminal Vim gets a sequence of bytes and has to figure -out whether ALT was pressed or not. - -By default Vim assumes that pressing the ALT key sets the 8th bit of a typed -character. Most decent terminals can work that way, such as xterm, aterm and -rxvt. If your <A-k> mappings don't work it might be that the terminal is -prefixing the character with an ESC character. But you can just as well type -ESC before a character, thus Vim doesn't know what happened (except for -checking the delay between characters, which is not reliable). - -As of this writing, some mainstream terminals like gnome-terminal and konsole -use the ESC prefix. There doesn't appear a way to have them use the 8th bit -instead. Xterm should work well by default. Aterm and rxvt should work well -when started with the "--meta8" argument. You can also tweak resources like -"metaSendsEscape", "eightBitInput" and "eightBitOutput". - -On the Linux console, this behavior can be toggled with the "setmetamode" -command. Bear in mind that not using an ESC prefix could get you in trouble -with other programs. You should make sure that bash has the "convert-meta" -option set to "on" in order for your Meta keybindings to still work on it -(it's the default readline behavior, unless changed by specific system -configuration). For that, you can add the line: > - - set convert-meta on - -to your ~/.inputrc file. If you're creating the file, you might want to use: > - - $include /etc/inputrc - -as the first line, if that file exists on your system, to keep global options. -This may cause a problem for entering special characters, such as the umlaut. -Then you should use CTRL-V before that character. - -Bear in mind that convert-meta has been reported to have troubles when used in -UTF-8 locales. On terminals like xterm, the "metaSendsEscape" resource can be -toggled on the fly through the "Main Options" menu, by pressing Ctrl-LeftClick -on the terminal; that's a good last resource in case you want to send ESC when -using other applications but not when inside VIM. - +In the GUI Nvim handles the |ALT| key itself, thus mapping keys with ALT +should always work. But in a terminal Nvim gets a sequence of bytes and has +to figure out whether ALT was pressed. Terminals may use ESC to indicate that +ALT was pressed. If ESC is followed by a {key} within 'ttimeoutlen' +milliseconds, the ESC is interpreted as: + <ALT-{key}> +otherwise it is interpreted as two key presses: + <ESC> {key} 1.11 MAPPING AN OPERATOR *:map-operator* @@ -898,7 +872,9 @@ an additional rule: full-id In front of the match is a non-keyword character, or this is where the line or insertion starts. Exception: When the abbreviation is only one character, it is not recognized if there is a non-keyword - character in front of it, other than a space or a tab. + character in front of it, other than a space or a tab. However, for + the command line "'<,'>" (or any other marks) is ignored, as if the + command line starts after it. end-id In front of the match is a keyword character, or a space or a tab, or this is where the line or insertion starts. @@ -931,7 +907,6 @@ character is mostly ignored otherwise. It is possible to move the cursor after an abbreviation: > :iab if if ()<Left> -This does not work if 'cpoptions' includes the '<' flag. |<>| You can even do more complicated things. For example, to consume the space typed after an abbreviation: > @@ -1079,8 +1054,7 @@ functions used in one script use the same name as in other scripts. To avoid this, they can be made local to the script. *<SID>* *<SNR>* *E81* -The string "<SID>" can be used in a mapping or menu. This requires that the -'<' flag is not present in 'cpoptions'. +The string "<SID>" can be used in a mapping or menu. When executing the map command, Vim will replace "<SID>" with the special key code <SNR>, followed by a number that's unique for the script, and an underscore. Example: > @@ -1163,6 +1137,10 @@ scripts. " Command has the -register attribute b Command is local to current buffer (see below for details on attributes) + The list can be filtered on command name with + |:filter|, e.g., to list all commands with "Pyth" in + the name: > + filter Pyth command :com[mand] {cmd} List the user-defined commands that start with {cmd} @@ -1238,6 +1216,7 @@ By default, the arguments of user defined commands do not undergo completion. However, by specifying one or the other of the following attributes, argument completion can be enabled: + -complete=arglist file names in argument list -complete=augroup autocmd groups -complete=buffer buffer names -complete=behave :behave suboptions @@ -1257,9 +1236,12 @@ completion can be enabled: -complete=highlight highlight groups -complete=history :history suboptions -complete=locale locale names (as output of locale -a) + -complete=mapclear buffer argument -complete=mapping mapping name -complete=menu menus + -complete=messages |:messages| suboptions -complete=option options + -complete=packadd optional package |pack-add| names -complete=shellcmd Shell command -complete=sign |:sign| suboptions -complete=syntax syntax file names |'syntax'| @@ -1344,7 +1326,7 @@ Possible attributes are: Note that -range=N and -count=N are mutually exclusive - only one should be specified. - *E889* *:command-addr* + *:command-addr* It is possible that the special characters in the range like `.`, `$` or `%` which by default correspond to the current line, last line and the whole buffer, relate to arguments, (loaded) buffers, windows or tab pages. @@ -1391,6 +1373,8 @@ The valid escape sequences are <line1> The starting line of the command range. *<line2>* <line2> The final line of the command range. + *<range>* + <range> The number of items in the command range: 0, 1 or 2 *<count>* <count> Any count supplied (as described for the '-range' and '-count' attributes). @@ -1398,6 +1382,29 @@ The valid escape sequences are <bang> (See the '-bang' attribute) Expands to a ! if the command was executed with a ! modifier, otherwise expands to nothing. + *<mods>* + <mods> The command modifiers, if specified. Otherwise, expands to + nothing. Supported modifiers are |:aboveleft|, |:belowright|, + |:botright|, |:browse|, |:confirm|, |:hide|, |:keepalt|, + |:keepjumps|, |:keepmarks|, |:keeppatterns|, |:leftabove|, + |:lockmarks|, |:noswapfile| |:rightbelow|, |:silent|, |:tab|, + |:topleft|, |:verbose|, and |:vertical|. + Note that these are not yet supported: |:noautocmd|, + |:sandbox| and |:unsilent|. + Examples: > + command! -nargs=+ -complete=file MyEdit + \ for f in expand(<q-args>, 0, 1) | + \ exe '<mods> split ' . f | + \ endfor + + function! SpecialEdit(files, mods) + for f in expand(a:files, 0, 1) + exe a:mods . ' split ' . f + endfor + endfunction + command! -nargs=+ -complete=file Sedit + \ call SpecialEdit(<q-args>, <q-mods>) +< *<reg>* *<register>* <reg> (See the '-register' attribute) The optional register, if specified. Otherwise, expands to nothing. <register> @@ -1488,4 +1495,4 @@ local to the script and use mappings local to the script. When the user invokes the user command, it will run in the context of the script it was defined in. This matters if |<SID>| is used in a command. - vim:tw=78:ts=8:ft=help:norl: + vim:tw=78:ts=8:noet:ft=help:norl: |