diff options
Diffstat (limited to 'runtime/doc/map.txt')
| -rw-r--r-- | runtime/doc/map.txt | 157 |
1 files changed, 48 insertions, 109 deletions
diff --git a/runtime/doc/map.txt b/runtime/doc/map.txt index 53b152dc06..9b61fa6527 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 Jul 06 +*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,7 +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* -:tm[ap] {lhs} {rhs} |mapmode-t| *:tm* *:tmap* +: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 @@ -89,7 +75,7 @@ modes. :iu[nmap] {lhs} |mapmode-i| *:iu* *:iunmap* :lu[nmap] {lhs} |mapmode-l| *:lu* *:lunmap* :cu[nmap] {lhs} |mapmode-c| *:cu* *:cunmap* -:tu[nmap] {lhs} |mapmode-t| *:tu* *:tunmap* +: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. @@ -125,7 +111,7 @@ modes. :im[ap] |mapmode-i| :lm[ap] |mapmode-l| :cm[ap] |mapmode-c| -:tm[ap] |mapmode-t| +: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. @@ -140,7 +126,7 @@ modes. :im[ap] {lhs} |mapmode-i| *:imap_l* :lm[ap] {lhs} |mapmode-l| *:lmap_l* :cm[ap] {lhs} |mapmode-c| *:cmap_l* -:tm[ap] {lhs} |mapmode-t| *:tmap_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. @@ -163,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. @@ -189,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 @@ -203,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 @@ -437,6 +417,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: > @@ -450,42 +433,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* @@ -587,16 +556,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). @@ -651,8 +621,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> @@ -684,7 +653,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 @@ -720,9 +689,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 @@ -762,46 +728,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* @@ -939,7 +873,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: > @@ -1087,8 +1020,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: > @@ -1171,6 +1103,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} @@ -1267,6 +1203,7 @@ completion can be enabled: -complete=locale locale names (as output of locale -a) -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 @@ -1411,9 +1348,11 @@ The valid escape sequences are <mods> The command modifiers, if specified. Otherwise, expands to nothing. Supported modifiers are |:aboveleft|, |:belowright|, |:botright|, |:browse|, |:confirm|, |:hide|, |:keepalt|, - |:keepjumps|, |:keepmarks|, |:keeppatterns|, |:lockmarks|, - |:noswapfile|, |:silent|, |:tab|, |:topleft|, |:verbose|, and - |:vertical|. + |: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) | |