| *map.txt* For Vim version 7.0aa. Last change: 2005 Mar 29 |
| |
| |
| VIM REFERENCE MANUAL by Bram Moolenaar |
| |
| |
| 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| |
| 2. Abbreviations |abbreviations| |
| 3. Local mappings and functions |script-local| |
| 4. User-defined commands |user-commands| |
| |
| ============================================================================== |
| 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: > |
| |
| :map <F2> a<C-R>=strftime("%c")<CR><Esc> |
| |
| This appends the current date and time after the cursor (in <> notation |<>|). |
| |
| There are commands to enter new mappings, remove mappings and list mappings. |
| See |map-overview| for the various forms of "map" and their relationships with |
| modes. |
| |
| {lhs} means left-hand-side *{lhs}* |
| {rhs} means right-hand-side *{rhs}* |
| |
| :map {lhs} {rhs} *:map* |
| :nm[ap] {lhs} {rhs} *:nm* *:nmap* |
| :vm[ap] {lhs} {rhs} *:vm* *:vmap* |
| :om[ap] {lhs} {rhs} *:om* *:omap* |
| :map! {lhs} {rhs} *:map!* |
| :im[ap] {lhs} {rhs} *:im* *:imap* |
| :lm[ap] {lhs} {rhs} *:lm* *:lmap* |
| :cm[ap] {lhs} {rhs} *:cm* *:cmap* |
| 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 |
| allows for nested and recursive use of mappings. |
| |
| |
| :no[remap] {lhs} {rhs} *:no* *:noremap* |
| :nn[oremap] {lhs} {rhs} *:nn* *:nnoremap* |
| :vn[oremap] {lhs} {rhs} *:vn* *:vnoremap* |
| :ono[remap] {lhs} {rhs} *:ono* *:onoremap* |
| :no[remap]! {lhs} {rhs} *:no!* *:noremap!* |
| :ino[remap] {lhs} {rhs} *:ino* *:inoremap* |
| :ln[oremap] {lhs} {rhs} *:ln* *:lnoremap* |
| :cno[remap] {lhs} {rhs} *:cno* *:cnoremap* |
| 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 |
| used to redefine a command. {not in Vi} |
| |
| |
| :unm[ap] {lhs} *:unm* *:unmap* |
| :nun[map] {lhs} *:nun* *:nunmap* |
| :vu[nmap] {lhs} *:vu* *:vunmap* |
| :ou[nmap] {lhs} *:ou* *:ounmap* |
| :unm[ap]! {lhs} *:unm!* *:unmap!* |
| :iu[nmap] {lhs} *:iu* *:iunmap* |
| :lu[nmap] {lhs} *:lu* *:lunmap* |
| :cu[nmap] {lhs} *:cu* *:cunmap* |
| Remove the mapping of {lhs} for the modes where the |
| map command applies. The mapping may remain defined |
| for other modes where it applies. |
| Note: Trailing spaces are included in the {lhs}. This |
| unmap does NOT work: > |
| :map @@ foo |
| :unmap @@ | print |
| |
| :mapc[lear] *:mapc* *:mapclear* |
| :nmapc[lear] *:nmapc* *:nmapclear* |
| :vmapc[lear] *:vmapc* *:vmapclear* |
| :omapc[lear] *:omapc* *:omapclear* |
| :mapc[lear]! *:mapc!* *:mapclear!* |
| :imapc[lear] *:imapc* *:imapclear* |
| :lmapc[lear] *:lmapc* *:lmapclear* |
| :cmapc[lear] *:cmapc* *:cmapclear* |
| Remove ALL mappings for the modes where the map |
| command applies. {not in Vi} |
| Warning: This also removes the default mappings. |
| |
| :map |
| :nm[ap] |
| :vm[ap] |
| :om[ap] |
| :map! |
| :im[ap] |
| :lm[ap] |
| :cm[ap] |
| 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. |
| |
| :map {lhs} *:map_l* |
| :nm[ap] {lhs} *:nmap_l* |
| :vm[ap] {lhs} *:vmap_l* |
| :om[ap] {lhs} *:omap_l* |
| :map! {lhs} *:map_l!* |
| :im[ap] {lhs} *:imap_l* |
| :lm[ap] {lhs} *:lmap_l* |
| :cm[ap] {lhs} *:cmap_l* |
| List the key mappings for the key sequences starting |
| with {lhs} in the modes where the map command applies. |
| {not in Vi} |
| |
| These commands are used to map a key or key sequence to a string of |
| characters. You can use this to put command sequences under function keys, |
| translate one key into another, etc. See |:mkexrc| for how to save and |
| restore the current mappings. |
| |
| *:map-local* *:map-<buffer>* *E224* *E225* |
| If the first argument to one of these commands is "<buffer>" it will apply to |
| mappings locally to the current buffer only. Example: > |
| :map <buffer> ,w /[.,;]<CR> |
| Then you can map ",w" to something else in another buffer: > |
| :map <buffer> ,w /[#&!]<CR> |
| The local buffer mappings are used before the global ones. |
| The "<buffer>" argument can also be used to clear mappings: > |
| :unmap <buffer> ,w |
| :mapclear <buffer> |
| Local mappings are also cleared when a buffer is deleted, but not when it is |
| unloaded. Just like local option values. |
| |
| *:map-<silent>* *:map-silent* |
| To define a mapping which will not be echoed on the command line, add |
| "<silent>" as the first argument. Example: > |
| :map <silent> ,h /Header<CR> |
| The search string will not be echoed when using this mapping. Messages from |
| the executed command are still given though. To shut them up too, add a |
| ":silent" in the executed command: > |
| :map <silent> ,h :exe ":silent normal /Header\r"<CR> |
| 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-<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 |
| in the {rhs} using mappings that were defined local to a script, starting with |
| "<SID>". This can be used to avoid that mappings from outside a script |
| interfere (e.g., when CTRL-V is remapped in mswin.vim), but do use other |
| mappings defined in the script. |
| Note: ":map <script>" and ":noremap <script>" do the same thing. The |
| "<script>" overrules the command name. Using ":noremap <script>" is |
| preferred, because it's clearer that remapping is (mostly) disabled. |
| |
| *:map-<unique>* *E226* *E227* |
| If the first argument to one of these commands is "<unique>" and it is used to |
| define a new mapping or abbreviation, the command will fail if the mapping or |
| abbreviation already exists. Example: > |
| :map <unique> ,w /[#&!]<CR> |
| When defining a local mapping, there will also be a check if a global map |
| already exists which is equal. |
| Example of what will fail: > |
| :map ,w /[#&!]<CR> |
| :map <buffer> <unique> ,w /[.,;]<CR> |
| |
| "<buffer>", "<silent>", "<script>" and "<unique>" can be used in any order. |
| They must appear right after the command, before any other arguments. |
| |
| |
| MAPPING AND MODES |
| |
| There are five sets of mappings |
| - For Normal mode: When typing commands. |
| - For Visual mode: When typing commands while the Visual area is highlighted. |
| - For Operator-pending mode: When an operator is pending (after "d", "y", "c", |
| etc.). Example: ":omap { w" makes "y{" work like "yw" and "d{" like "dw". |
| - For Insert mode. These are also used in Replace mode. |
| - For Command-line mode: When entering a ":" or "/" command. |
| |
| There are no separate mappings for Select mode. The same as for Visual mode |
| are used |Select-mode-mapping|. |
| |
| 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 |
| to type a count with a zero. |
| |
| *map-overview* *map-modes* |
| Overview of which map command works in which mode: |
| |
| commands: modes: ~ |
| Normal Visual Operator-pending ~ |
| :map :noremap :unmap :mapclear yes yes yes |
| :nmap :nnoremap :nunmap :nmapclear yes - - |
| :vmap :vnoremap :vunmap :vmapclear - yes - |
| :omap :onoremap :ounmap :omapclear - - yes |
| |
| Insert Command-line Lang-Arg ~ |
| :map! :noremap! :unmap! :mapclear! yes yes - |
| :imap :inoremap :iunmap :imapclear yes - - |
| :cmap :cnoremap :cunmap :cmapclear - yes - |
| :lmap :lnoremap :lunmap :lmapclear yes* yes* yes* |
| |
| The original Vi did not have separate mappings for |
| Normal/Visual/Operator-pending mode and for Insert/Command-line mode. |
| Therefore the ":map" and ":map!" commands enter and display mappings for |
| several modes. In Vim you can use the ":nmap", ":vmap", ":omap", ":cmap" and |
| ":imap" commands to enter mappings for each mode separately. |
| |
| 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: |
| :map xx something-difficult |
| :ounmap xx |
| Likewise for a mapping for Visual and Operator-pending mode or Normal and |
| Operator-pending mode. |
| |
| *language-mapping* |
| ":lmap" defines a mapping that applies to: |
| - Insert mode |
| - Command-line mode |
| - when entering a search pattern |
| - the argument of the commands that accept a text character, such as "r" and |
| "f" |
| - for the input() line |
| Generally: Whenever a character is to be typed that is part of the text in the |
| buffer, not a Vim command character. "Lang-Arg" isn't really another mode, |
| it's just used here for this situation. |
| The simplest way to load a set of related language mappings is by using the |
| 'keymap' option. See |45.5|. |
| In Insert mode and in Command-line mode the mappings can be disabled with |
| the CTRL-^ command |i_CTRL-^| |c_CTRL-^|. When starting to enter a normal |
| command line (not a search pattern) the mappings are disabled until a CTRL-^ |
| is typed. The state last used is remembered for Insert mode and Search |
| patterns separately. The 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. |
| |
| *map-multibyte* |
| It is possible to map multibyte characters, but only the whole character. You |
| cannot map the first byte only. This was done to prevent problems in this |
| scenario: > |
| :set encoding=latin1 |
| :imap <M-C> foo |
| :set encoding=utf-8 |
| The mapping for <M-C> is defined with the latin1 encoding, resulting in a 0xc3 |
| byte. If you type the character á (0xea <M-a>) in UTF-8 encoding this is the |
| two bytes 0xc3 0xa1. You don't want the 0xc3 byte to be mapped then, |
| otherwise it would be impossible to type the á character. |
| |
| *map-listing* |
| When listing mappings the characters in the first two columns are: |
| |
| CHAR MODE ~ |
| <Space> Normal, Visual and Operator-pending |
| n Normal |
| v Visual |
| o Operator-pending |
| ! Insert and Command-line |
| i Insert |
| l ":lmap" mappings for Insert, Command-line and Lang-Arg |
| c Command-line |
| |
| Just before the {rhs} a special character can appear: |
| * indicates that it is not remappable |
| & indicates that only script-local mappings are remappable |
| @ indicates a buffer-local mapping |
| |
| Everything from the first non-blank after {lhs} up to the end of the line |
| (or '|') is considered to be part of {rhs}. This allows the {rhs} to end |
| 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 |'<|. |
| |
| *map_backslash* |
| Note that only CTRL-V is mentioned here as a special character for mappings |
| and abbreviations. When 'cpoptions' does not contain 'B', a backslash can |
| also be used like CTRL-V. The <> notation can be fully used then |<>|. But |
| you cannot use "<C-V>" like CTRL-V to escape the special meaning of what |
| follows. |
| |
| To map a backslash, or use a backslash literally in the {rhs}, the special |
| sequence "<Bslash>" can be used. This avoids the need to double backslashes |
| when using nested mappings. |
| |
| *map-ambiguous* |
| When two mappings start with the same sequence of characters, they are |
| ambiguous. Example: > |
| :imap aa foo |
| :imap aaa bar |
| When Vim has read "aa", it will need to get another character to be able to |
| decide if "aa" or "aaa" should be mapped. This means that after typing "aa" |
| that mapping won't get expanded yet, Vim is waiting for another character. |
| If you type a space, then "foo" will get inserted, plus the space. If you |
| type "a", then "bar" will get inserted. |
| {Vi does not allow ambiguous mappings} |
| |
| *map_CTRL_C* |
| It's not possible to use a CTRL-C in the {lhs}. You just can't map CTRL-C. |
| The reason is that CTRL-C must always be available to break a running command. |
| Exception: When using the GUI version on MS-Windows CTRL-C can be mapped to |
| allow a Copy command to the clipboard. Use CTRL-Break to interrupt Vim. |
| |
| *map_space_in_lhs* |
| To include a space in {lhs} precede it with a CTRL-V (type two CTRL-Vs for |
| each space). |
| *map_space_in_rhs* |
| If you want a {rhs} that starts with a space, use "<Space>". To be fully Vi |
| compatible (but unreadable) don't use the |<>| notation, precede {rhs} with a |
| single CTRL-V (you have to type CTRL-V two times). |
| *map_empty_rhs* |
| You can create an empty {rhs} by typing nothing after a single CTRL-V (you |
| have to type CTRL-V two times). Unfortunately, you cannot do this in a vimrc |
| file. |
| *<Nop>* |
| A easier way to get a mapping that doesn't produce anything, is to use "<Nop>" |
| for the {rhs}. This only works when the |<>| notation is enabled. For |
| example, to make sure that function key 8 does nothing at all: > |
| :map <F8> <Nop> |
| :map! <F8> <Nop> |
| < |
| *<Leader>* *mapleader* |
| To define a mapping which uses the "mapleader" variable, the special string |
| "<Leader>" can be used. It is replaced with the string value of "mapleader". |
| If "mapleader" is not set or empty, a backslash is used instead. Example: > |
| :map <Leader>A oanother line<Esc> |
| Works like: > |
| :map \A oanother line<Esc> |
| But after: > |
| :let mapleader = "," |
| It works like: > |
| :map ,A oanother line<Esc> |
| |
| Note that the value of "mapleader" is used at the moment the mapping is |
| defined. Changing "mapleader" after that has no effect for already defined |
| mappings. |
| |
| *<LocalLeader>* *maplocalleader* |
| Just like <Leader>, except that it uses "maplocalleader" instead of |
| "mapleader". <LocalLeader> is to be used for mappings which are local to a |
| buffer. Example: > |
| :map <LocalLeader>q \DoItNow |
| < |
| In a global plugin <Leader> should be used and in a filetype plugin |
| <LocalLeader>. "mapleader" and "maplocalleader" can be equal. Although, if |
| you make them different, there is a smaller chance of mappings from global |
| plugins to clash with mappings for filetype plugins. For example, you could |
| keep "mapleader" at the default backslash, and set "maplocalleader" to an |
| underscore. |
| |
| *map-<SID>* |
| In a script the special key name "<SID>" can be used to define a mapping |
| that's local to the script. See |<SID>| for details. |
| |
| *<Plug>* |
| The special key name "<Plug>" can be used for an internal mapping, which is |
| not to be matched with any key sequence. This is useful in plugins |
| |using-<Plug>|. |
| |
| *<Char>* *<Char->* |
| To map a character by its decimal, octal or hexadecimal number the <Char> |
| construct can be used: |
| <Char-123> character 123 |
| <Char-033> character 27 |
| <Char-0x7f> character 127 |
| This is useful to specify a (multi-byte) character in a 'keymap' file. |
| 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}. |
| |
| *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 |
| \| 'b' is not in 'cpoptions' :map _l :!ls \| more^M |
| ^V| always, in Vim and Vi :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). |
| |
| All three work when you use the default setting for 'cpoptions'. |
| |
| When 'b' is present in 'cpoptions', "\|" will be recognized as a mapping |
| ending in a '\' and then another command. This is Vi compatible, but |
| illogical when compared to other commands. |
| |
| *map_return* |
| When you have a mapping that contains an Ex command, you need to put a line |
| terminator after it to have it executed. The use of <CR> is recommended for |
| this (see |<>|). Example: > |
| :map _ls :!ls -l %<CR>:echo "the end"<CR> |
| |
| To avoid mapping of the characters you type in insert or Command-line mode, |
| type a CTRL-V first. The mapping in Insert mode is disabled if the 'paste' |
| option is on. |
| |
| Note that when an error is encountered (that causes an error message or beep) |
| the rest of the mapping is not executed. This is Vi-compatible. |
| |
| Note that the second character (argument) of the commands @zZtTfF[]rm'`"v |
| and CTRL-X is not mapped. This was done to be able to use all the named |
| registers and marks, even when the command with the same name has been |
| mapped. |
| |
| *map-which-keys* |
| If you are going to map something, you will need to choose which key(s) to use |
| for the {lhs}. You will have to avoid keys that are used for Vim commands, |
| otherwise you would not be able to use those commands anymore. Here are a few |
| suggestions: |
| - Function keys <F2>, <F3>, etc.. Also the shifted function keys <S-F1>, |
| <S-F2>, etc. Note that <F1> is already used for the help command. |
| - Meta-keys (with the ALT key pressed). |
| - Use the '_' or ',' character and then any other character. The "_" and "," |
| commands do exist in Vim (see |_| and |,|), but you probably never use them. |
| - Use a key that is a synonym for another command. For example: CTRL-P and |
| CTRL-N. Use an extra character to allow more mappings. |
| |
| See the file "index" for keys that are not used and thus can be mapped without |
| losing any builtin function. You can also use ":help {key}^D" to find out if |
| a key is used for some command. ({key} is the specific key you want to find |
| out about, ^D is CTRL-D). |
| |
| *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). > |
| |
| :map <F3> o#include |
| :map <M-g> /foo<CR>cwbar<Esc> |
| :map _x d/END/e<CR> |
| :map! qq quadrillion questions |
| < |
| *map-typing* |
| Vim will compare what you type with the start of a mapped sequence. If there |
| is an incomplete match, it will get more characters until there either is a |
| complete match or until there is no match at all. Example: If you map! "qq", |
| the first 'q' will not appear on the screen until you type another |
| character. This is because Vim cannot know if the next character will be a |
| 'q' or not. If the 'timeout' option is on (which is the default) Vim will |
| only wait for one second (or as long as specified with the 'timeoutlen' |
| 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-keys-fails* |
| There is one situation where key codes might not be recognized: |
| - Vim can only read part of the key code. Mostly this is only the first |
| character. This happens on some Unix versions in an xterm. |
| - The key code is after character(s) that are mapped. E.g., "<F1><F1>" or |
| "g<F1>". |
| The result is that the key code is not recognized in this situation, and the |
| mapping fails. |
| There are two actions needed to avoid this problem: |
| - Remove the 'K' flag from 'cpoptions'. This will make Vim wait for the rest |
| of the characters of the function key. |
| - When using <F1> to <F4> the actual key code generated may correspond to |
| <xF1> to <xF4>. There are mappings from <xF1> to <F1>, <xF2> to <F2>, etc., |
| but these are not recognized after another half a mapping. Make sure the |
| key codes for <F1> to <F4> are correct: > |
| :set <F1>=<type CTRL-V><type F1> |
| < Type the <F1> as four characters. The part after the "=" must be done with |
| the actual keys, not the literal text. |
| Another solution is to use the actual key code in the mapping for the second |
| special key: > |
| :map <F1><Esc>OP :echo "yes"<CR> |
| Don't type a real <Esc>, Vim will recognize the key code and replace it with |
| <F1> anyway. |
| |
| *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 |
| included in {rhs} is encountered it will be replaced with {rhs}, and so on. |
| This makes it possible to repeat a command an infinite number of times. The |
| only problem is that the only way to stop this is by causing an error. The |
| macros to solve a maze uses this, look there for an example. There is one |
| exception: If the {rhs} starts with {lhs}, the first character is not mapped |
| again (this is Vi compatible). |
| For example: > |
| :map ab abcd |
| will execute the "a" command and insert "bcd" in the text. The "ab" in the |
| {rhs} will not be mapped again. |
| |
| If you want to exchange the meaning of two keys you should use the :noremap |
| command. For example: > |
| :noremap k j |
| :noremap j k |
| This will exchange the cursor up and down commands. |
| |
| With the normal :map command, when the 'remap' option is on, mapping takes |
| place until the text is found not to be a part of a {lhs}. For example, if |
| you use: > |
| :map x y |
| :map y x |
| Vim will replace x with y, and then y with x, etc. When this has happened |
| 'maxmapdepth' times (default 1000), Vim will give the error message |
| "recursive mapping". |
| |
| *:map-undo* |
| If you include an undo command inside a mapped sequence, this will bring the |
| text back in the state before executing the macro. This is compatible with |
| the original Vi, as long as there is only one undo command in the mapped |
| sequence (having two undo commands in a mapped sequence did not make sense |
| in the original Vi, you would get back the text before the first undo). |
| |
| *:map-special-keys* |
| There are three 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'). |
| 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). |
| |
| 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. |
| |
| ============================================================================== |
| 2. Abbreviations *abbreviations* *Abbreviations* |
| |
| Abbreviations are used in Insert mode, Replace mode and Command-line mode. |
| If you enter a word that is an abbreviation, it is replaced with the word it |
| stands for. This can be used to save typing for often used long words. And |
| you can use it to automatically correct obvious spelling errors. |
| Examples: |
| |
| :iab ms MicroSoft |
| :iab tihs this |
| |
| There are three types of abbreviations: |
| |
| full-id The "full-id" type consists entirely of keyword characters (letters |
| and characters from 'iskeyword' option). This is the most common |
| abbreviation. |
| |
| Examples: "foo", "g3", "-1" |
| |
| end-id The "end-id" type ends in a keyword character, but all the other |
| characters are not keyword characters. |
| |
| Examples: "#i", "..f", "$/7" |
| |
| non-id The "non-id" type ends in a non-keyword character, the other |
| characters may be of any type, excluding space and Tab. {this type |
| is not supported by Vi} |
| |
| Examples: "def#", "4/7$" |
| |
| Examples of strings that cannot be abbreviations: "a.b", "#def", "a b", "_$r" |
| |
| An abbreviation is only recognized when you type a non-keyword character. |
| This can also be the <Esc> that ends insert mode or the <CR> that ends a |
| command. The non-keyword character which ends the abbreviation is inserted |
| after the expanded abbreviation. An exception to this is the character <C-]>, |
| which is used to expand an abbreviation without inserting any extra |
| characters. |
| |
| Example: > |
| :ab hh hello |
| < "hh<Space>" is expanded to "hello<Space>" |
| "hh<C-]>" is expanded to "hello" |
| |
| The characters before the cursor must match the abbreviation. Each type has |
| 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>. |
| |
| 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. |
| |
| non-id In front of the match is a space, <Tab> or the start of the line or |
| the insertion. |
| |
| Examples: ({CURSOR} is where you type a non-keyword character) > |
| :ab foo four old otters |
| < " foo{CURSOR}" is expanded to " four old otters" |
| " foobar{CURSOR}" is not expanded |
| "barfoo{CURSOR}" is not expanded |
| > |
| :ab #i #include |
| < "#i{CURSOR}" is expanded to "#include" |
| ">#i{CURSOR}" is not expanded |
| > |
| :ab ;; <endofline> |
| < "test;;" is not expanded |
| "test ;;" is expanded to "test <endofline>" |
| |
| To avoid the abbreviation in insert mode: Type part of the abbreviation, exit |
| insert mode with <Esc>, re-enter insert mode with "a" and type the rest. Or |
| type CTRL-V before the character after the abbreviation. |
| To avoid the abbreviation in Command-line mode: Type CTRL-V twice somewhere in |
| the abbreviation to avoid it to be replaced. A CTRL-V in front of a normal |
| 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: > |
| func Eatchar(pat) |
| let c = nr2char(getchar()) |
| return (c =~ a:pat) ? '' : c |
| endfunc |
| iabbr <silent> if if ()<Left><C-R>=Eatchar('\s')<CR> |
| |
| There are no default abbreviations. |
| |
| Abbreviations are never recursive. You can use ":ab f f-o-o" without any |
| problem. But abbreviations can be mapped. {some versions of Vi support |
| recursive abbreviations, for no apparent reason} |
| |
| Abbreviations are disabled if the 'paste' option is on. |
| |
| *:abbreviate-local* *:abbreviate-<buffer>* |
| Just like mappings, abbreviations can be local to a buffer. This is mostly |
| used in a |filetype-plugin| file. Example for a C plugin file: > |
| :abb <buffer> FF for (i = 0; i < ; ++i) |
| < |
| *:ab* *:abbreviate* |
| :ab[breviate] list all abbreviations. The character in the first |
| column indicates the mode where the abbreviation is |
| used: 'i' for insert mode, 'c' for Command-line |
| mode, '!' for both. These are the same as for |
| mappings, see |map-listing|. |
| |
| :ab[breviate] {lhs} list the abbreviations that start with {lhs} |
| You may need to insert a CTRL-V (type it twice) to |
| avoid that a typed {lhs} is expanded, since |
| command-line abbreviations apply here. |
| |
| :ab[breviate] {lhs} {rhs} |
| add abbreviation for {lhs} to {rhs}. If {lhs} already |
| existed it is replaced with the new {rhs}. {rhs} may |
| contain spaces. |
| |
| *:una* *:unabbreviate* |
| :una[bbreviate] {lhs} Remove abbreviation for {lhs} from the list. If none |
| is found, remove abbreviations in which {lhs} matches |
| with the {rhs}. This is done so that you can even |
| remove abbreviations after expansion. To avoid |
| expansion insert a CTRL-V (type it twice). |
| |
| *:norea* *:noreabbrev* |
| :norea[bbrev] [lhs] [rhs] |
| same as ":ab", but no remapping for this {rhs} {not |
| in Vi} |
| |
| *:ca* *:cabbrev* |
| :ca[bbrev] [lhs] [rhs] same as ":ab", but for Command-line mode only. {not |
| in Vi} |
| |
| *:cuna* *:cunabbrev* |
| :cuna[bbrev] {lhs} same as ":una", but for Command-line mode only. {not |
| in Vi} |
| |
| *:cnorea* *:cnoreabbrev* |
| :cnorea[bbrev] [lhs] [rhs] |
| same as ":ab", but for Command-line mode only and no |
| remapping for this {rhs} {not in Vi} |
| |
| *:ia* *:iabbrev* |
| :ia[bbrev] [lhs] [rhs] same as ":ab", but for Insert mode only. {not in Vi} |
| |
| *:iuna* *:iunabbrev* |
| :iuna[bbrev] {lhs} same as ":una", but for insert mode only. {not in |
| Vi} |
| |
| *:inorea* *:inoreabbrev* |
| :inorea[bbrev] [lhs] [rhs] |
| same as ":ab", but for Insert mode only and no |
| remapping for this {rhs} {not in Vi} |
| |
| *:abc* *:abclear* |
| :abc[lear] Remove all abbreviations. {not in Vi} |
| |
| *:iabc* *:iabclear* |
| :iabc[lear] Remove all abbreviations for Insert mode. {not in Vi} |
| |
| *:cabc* *:cabclear* |
| :cabc[lear] Remove all abbreviations for Command-line mode. {not |
| in Vi} |
| |
| *using_CTRL-V* |
| It is possible to use special characters in the rhs of an abbreviation. |
| CTRL-V has to be used to avoid the special meaning of most non printable |
| characters. How many CTRL-Vs need to be typed depends on how you enter the |
| abbreviation. This also applies to mappings. Let's use an example here. |
| |
| Suppose you want to abbreviate "esc" to enter an <Esc> character. When you |
| type the ":ab" command in Vim, you have to enter this: (here ^V is a CTRL-V |
| and ^[ is <Esc>) |
| |
| You type: ab esc ^V^V^V^V^V^[ |
| |
| All keyboard input is subjected to ^V quote interpretation, so |
| the first, third, and fifth ^V characters simply allow the second, |
| and fourth ^Vs, and the ^[, to be entered into the command-line. |
| |
| You see: ab esc ^V^V^[ |
| |
| The command-line contains two actual ^Vs before the ^[. This is |
| how it should appear in your .exrc file, if you choose to go that |
| route. The first ^V is there to quote the second ^V; the :ab |
| command uses ^V as its own quote character, so you can include quoted |
| whitespace or the | character in the abbreviation. The :ab command |
| doesn't do anything special with the ^[ character, so it doesn't need |
| to be quoted. (Although quoting isn't harmful; that's why typing 7 |
| [but not 8!] ^Vs works.) |
| |
| Stored as: esc ^V^[ |
| |
| After parsing, the abbreviation's short form ("esc") and long form |
| (the two characters "^V^[") are stored in the abbreviation table. |
| If you give the :ab command with no arguments, this is how the |
| abbreviation will be displayed. |
| |
| Later, when the abbreviation is expanded because the user typed in |
| the word "esc", the long form is subjected to the same type of |
| ^V interpretation as keyboard input. So the ^V protects the ^[ |
| character from being interpreted as the "exit Insert mode" character. |
| Instead, the ^[ is inserted into the text. |
| |
| Expands to: ^[ |
| |
| [example given by Steve Kirkendall] |
| |
| ============================================================================== |
| 3. Local mappings and functions *script-local* |
| |
| When using several Vim script files, there is the danger that mappings and |
| 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'. |
| 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: > |
| :map <SID>Add |
| could define a mapping "<SNR>23_Add". |
| |
| When defining a function in a script, "s:" can be prepended to the name to |
| make it local to the script. But when a mapping is executed from outside of |
| the script, it doesn't know in which script the function was defined. To |
| avoid this problem, use "<SID>" instead of "s:". The same translation is done |
| as for mappings. This makes it possible to define a call to the function in |
| a mapping. |
| |
| When a local function is executed, it runs in the context of the script it was |
| defined in. This means that new functions and mappings it defines can also |
| use "s:" or "<SID>" and it will use the same unique number as when the |
| function itself was defined. Also, the "s:var" local script variables can be |
| used. |
| |
| When executing an autocommand or a user command, it will run in the context of |
| the script it was defined in. This makes it possible that the command calls a |
| local function or uses a local mapping. |
| |
| Otherwise, using "<SID>" outside of a script context is an error. |
| |
| If you need to get the script number to use in a complicated script, you can |
| use this trick: > |
| :map <SID>xx <SID>xx |
| :let s:sid = maparg("<SID>xx") |
| :unmap <SID>xx |
| And remove the trailing "xx". |
| |
| The "<SNR>" will be shown when listing functions and mappings. This is useful |
| to find out what they are defined to. |
| |
| The |:scriptnames| command can be used to see which scripts have been sourced |
| and what their <SNR> number is. |
| |
| This is all {not in Vi} and {not available when compiled without the +eval |
| feature}. |
| |
| ============================================================================== |
| 4. User-defined commands *user-commands* |
| |
| It is possible to define your own Ex commands. A user-defined command can act |
| just like a built-in command (it can have a range or arguments, arguments can |
| be completed as filenames or buffer names, etc), except that when the command |
| is executed, it is transformed into a normal ex command and then executed. |
| |
| For starters: See section |40.2| in the user manual. |
| |
| *E183* *user-cmd-ambiguous* |
| All user defined commands must start with an uppercase letter, to avoid |
| confusion with builtin commands. (There are a few builtin commands, notably |
| :Next, :Print and :X, which do start with an uppercase letter. The builtin |
| will always take precedence in these cases). The other characters of the user |
| command can be uppercase letters, lowercase letters or digits. When using |
| digits, note that other commands that take a numeric argument may become |
| ambiguous. For example, the command ":Cc2" could be the user command ":Cc2" |
| without an argument, or the command ":Cc" with argument "2". It is advised to |
| put a space between the command name and the argument to avoid these problems. |
| |
| When using a user-defined command, the command can be abbreviated. However, if |
| an abbreviation is not unique, an error will be issued. Furthermore, a |
| built-in command will always take precedence. |
| |
| Example: > |
| :command Rename ... |
| :command Renumber ... |
| :Rena " Means "Rename" |
| :Renu " Means "Renumber" |
| :Ren " Error - ambiguous |
| :command Paste ... |
| :P " The built-in :Print |
| |
| It is recommended that full names for user-defined commands are used in |
| scripts. |
| |
| :com[mand] *:com* *:command* |
| List all user-defined commands. When listing commands, |
| the characters in the first two columns are |
| ! Command has the -bang attribute |
| " Command has the -register attribute |
| b Command is local to current buffer |
| (see below for details on attributes) |
| |
| :com[mand] {cmd} List the user-defined commands that start with {cmd} |
| |
| *E174* *E182* |
| :com[mand][!] [{attr}...] {cmd} {rep} |
| Define a user command. The name of the command is |
| {cmd} and its replacement text is {rep}. The command's |
| attributes (see below) are {attr}. If the command |
| already exists, an error is reported, unless a ! is |
| specified, in which case the command is redefined. |
| |
| :delc[ommand] {cmd} *:delc* *:delcommand* *E184* |
| Delete the user-defined command {cmd}. |
| |
| :comc[lear] *:comc* *:comclear* |
| Delete all user-defined commands. |
| |
| Command attributes |
| |
| User-defined commands are treated by Vim just like any other ex commands. They |
| can have arguments, or have a range specified. Arguments are subject to |
| completion as filenames, buffers, etc. Exactly how this works depends upon the |
| command's attributes, which are specified when the command is defined. |
| |
| There are a number of attributes, split into four categories: argument |
| handling, completion behavior, range handling, and special cases. The |
| attributes are described below, by category. |
| |
| Argument handling *E175* *E176* |
| |
| By default, a user defined command will take no arguments (and an error is |
| reported if any are supplied). However, it is possible to specify that the |
| command can take arguments, using the -nargs attribute. Valid cases are: |
| |
| -nargs=0 No arguments are allowed (the default) |
| -nargs=1 Exactly one argument is required |
| -nargs=* Any number of arguments are allowed (0, 1, or many) |
| -nargs=? 0 or 1 arguments are allowed |
| -nargs=+ Arguments must be supplied, but any number are allowed |
| |
| Arguments are considered to be separated by (unescaped) spaces or Tabs in this |
| context. |
| |
| Note that arguments are used as text, not as expressions. Specifically, |
| "s:var" will use the script-local variable in the script where the command was |
| defined, not where it is invoked! Example: |
| script1.vim: > |
| :let s:error = "None" |
| :command -nargs=1 Error echoerr <args> |
| < script2.vim: > |
| :source script1.vim |
| :let s:error = "Wrong!" |
| :Error s:error |
| Executing script2.vim will result in "None" to be echoed. Not what you |
| intended! Calling a function may be an alternative. |
| |
| Completion behavior *:command-completion* |
| *E179* *E180* *E181* |
| 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=augroup autocmd groups |
| -complete=buffer buffer names |
| -complete=command Ex command (and arguments) |
| -complete=dir directory names |
| -complete=environment environment variable names |
| -complete=event autocommand events |
| -complete=expression Vim expression |
| -complete=file file and directory names |
| -complete=function function name |
| -complete=help help subjects |
| -complete=highlight highlight groups |
| -complete=mapping mapping name |
| -complete=menu menus |
| -complete=option options |
| -complete=tag tags |
| -complete=tag_listfiles tags, file names are shown when CTRL-D is hit |
| -complete=var user variables |
| -complete=custom,{func} custom completion, defined via {func} |
| |
| Custom completion *:command-completion-custom* |
| *E467* *E468* |
| It is possible to define customized completion schemes via the "custom,{func}" |
| completion argument. The {func} part should be a function with the following |
| prototype > |
| |
| :function {func}(ArgLead, CmdLine, CursorPos) |
| |
| The function need not use all these arguments, but it should provide the |
| completion candidates as the return value, one per line in a newline separated |
| string. The function arguments are: |
| ArgLead the leading portion of the argument currently being |
| completed on |
| CmdLine the entire command line |
| CursorPos the cursor position in it |
| The function may use these for determining context. It is not necessary to |
| filter candidates against the (implicit pattern in) ArgLead. Vim will do |
| filter the candidates with its regexp engine after function return, and this |
| is probably more efficient in most cases. |
| |
| The following example lists user names to a Finger command > |
| :com -complete=custom,ListUsers -nargs=1 Finger !finger <args> |
| :fun ListUsers(A,L,P) |
| : return system("cut -d: -f1 /etc/passwd") |
| :endfun |
| |
| Range handling *E177* *E178* |
| |
| By default, user-defined commands do not accept a line number range. However, |
| it is possible to specify that the command does take a range (the -range |
| attribute), or that it takes an arbitrary count value, either in the line |
| number position (-range=N, like the |:split| command) or as a "count" |
| argument (-count=N, like the |:Next| command). Possible attributes are: |
| |
| -range Range allowed, default is current line |
| -range=% Range allowed, default is whole file (1,$) |
| -range=N A count (default N) which is specified in the line |
| number position (like |:split|) |
| -count=N A count (default N) which is specified either in the line |
| number position, or as an initial argument (like |:Next|). |
| Specifying -count (without a default) acts like -count=0 |
| |
| Note that -range=N and -count=N are mutually exclusive - only one should be |
| specified. |
| |
| Special cases |
| |
| There are some special cases as well: |
| |
| -bang The command can take a ! modifier (like :q or :w) |
| -bar The command can be followed by a "|" and another command. |
| A "|" inside the command argument is not allowed then. |
| Also checks for a " to start a comment. |
| -register The first argument to the command can be an optional |
| register name (like :del, :put, :yank). |
| -buffer The command will only be available in the current buffer. |
| |
| In the cases of the -count and -register attributes, if the optional argument |
| is supplied, it is removed from the argument list and is available to the |
| replacement text separately. |
| |
| Replacement text |
| |
| The replacement text for a user defined command is scanned for special escape |
| sequences, using <...> notation. Escape sequences are replaced with values |
| from the entered command line, and all other text is copied unchanged. The |
| resulting string is executed as an Ex command. If the initial < of an escape |
| sequence is preceded by a backslash, the sequence is copied unchanged. |
| |
| The valid escape sequences are |
| |
| *<line1>* |
| <line1> The starting line of the command range. |
| *<line2>* |
| <line2> The final line of the command range. |
| *<count>* |
| <count> Any count supplied (as described for the '-range' |
| and '-count' attributes). |
| *<bang>* |
| <bang> (See the '-bang' attribute) Expands to a ! if the |
| command was executed with a ! modifier, otherwise |
| expands to nothing. |
| *<reg>* *<register>* |
| <reg> (See the '-register' attribute) The optional register, |
| if specified. Otherwise, expands to nothing. <register> |
| is a synonym for this. |
| *<args>* |
| <args> The command arguments, exactly as supplied (but as |
| noted above, any count or register can consume some |
| of the arguments, which are then not part of <args>). |
| <lt> A single '<' (Less-Than) character. This is needed if you |
| want to get a literal copy of one of these escape sequences |
| into the expansion - for example, to get <bang>, use |
| <lt>bang>. |
| |
| *<q-args>* |
| If the first two characters of an escape sequence are "q-" (for example, |
| <q-args>) then the value is quoted in such a way as to make it a valid value |
| for use in an expression. This uses the argument as one single value. |
| |
| To allow commands to pass their arguments on to a user-defined function, there |
| is a special form <f-args> ("function args"). This splits the command |
| arguments at spaces and Tabs, quotes each argument individually, and the |
| <f-args> sequence is replaced by the comma-separated list of quoted arguments. |
| See the Mycmd example below. When there is no argument, <f-args> also has no |
| argument. |
| |
| Examples > |
| |
| " Delete everything after here to the end |
| :com Ddel +,$d |
| |
| " Rename the current buffer |
| :com -nargs=1 -bang -complete=file Ren f <args>|w<bang> |
| |
| " Replace a range with the contents of a file |
| " (Enter this all as one line) |
| :com -range -nargs=1 -complete=file |
| Replace <line1>-pu_|<line1>,<line2>d|r <args>|<line1>d |
| |
| " Count the number of lines in the range |
| :com! -range -nargs=0 Lines echo <line2> - <line1> + 1 "lines" |
| |
| " Call a user function (example of <f-args>) |
| :com -nargs=* Mycmd call Myfunc(<f-args>) |
| |
| When executed as: > |
| :Mycmd arg1 arg2 |
| This will invoke: > |
| :call Myfunc("arg1","arg2") |
| |
| :" A more substantial example |
| :function Allargs(command) |
| : let i = 0 |
| : while i < argc() |
| : if filereadable(argv(i)) |
| : execute "e " . argv(i) |
| : execute a:command |
| : endif |
| : let i = i + 1 |
| : endwhile |
| :endfunction |
| :command -nargs=+ -complete=command Allargs call Allargs(<q-args>) |
| |
| The command Allargs takes any Vim command(s) as argument and executes it on all |
| files in the argument list. Usage example (note use of the "e" flag to ignore |
| errors and the "update" command to write modified buffers): > |
| :Allargs %s/foo/bar/ge|update |
| This will invoke: > |
| :call Allargs("%s/foo/bar/ge|update") |
| < |
| When defining an user command in a script, it will be able to call functions |
| 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: |