diff options
Diffstat (limited to 'runtime/doc/map.txt')
| -rw-r--r-- | runtime/doc/map.txt | 1570 |
1 files changed, 1570 insertions, 0 deletions
diff --git a/runtime/doc/map.txt b/runtime/doc/map.txt new file mode 100644 index 0000000..2832bed --- /dev/null +++ b/runtime/doc/map.txt @@ -0,0 +1,1570 @@ +*map.txt* For Vim version 8.1. Last change: 2018 Dec 18 + + + 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| + 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| + +============================================================================== +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 of 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 |<>|). + + +1.1 MAP COMMANDS *:map-commands* + +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} |mapmode-nvo| *:map* +:nm[ap] {lhs} {rhs} |mapmode-n| *:nm* *:nmap* +:vm[ap] {lhs} {rhs} |mapmode-v| *:vm* *:vmap* +:xm[ap] {lhs} {rhs} |mapmode-x| *:xm* *:xmap* +:smap {lhs} {rhs} |mapmode-s| *:smap* +:om[ap] {lhs} {rhs} |mapmode-o| *:om* *:omap* +:map! {lhs} {rhs} |mapmode-ic| *:map!* +: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 + allows for nested and recursive use of mappings. + + *:nore* *:norem* +:no[remap] {lhs} {rhs} |mapmode-nvo| *:no* *:noremap* *:nor* +:nn[oremap] {lhs} {rhs} |mapmode-n| *:nn* *:nnoremap* +:vn[oremap] {lhs} {rhs} |mapmode-v| *:vn* *:vnoremap* +:xn[oremap] {lhs} {rhs} |mapmode-x| *:xn* *:xnoremap* +:snor[emap] {lhs} {rhs} |mapmode-s| *:snor* *:snoremap* +:ono[remap] {lhs} {rhs} |mapmode-o| *:ono* *:onoremap* +:no[remap]! {lhs} {rhs} |mapmode-ic| *:no!* *:noremap!* +: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 + used to redefine a command. {not in Vi} + + +:unm[ap] {lhs} |mapmode-nvo| *:unm* *:unmap* +:nun[map] {lhs} |mapmode-n| *:nun* *:nunmap* +:vu[nmap] {lhs} |mapmode-v| *:vu* *:vunmap* +:xu[nmap] {lhs} |mapmode-x| *:xu* *:xunmap* +:sunm[ap] {lhs} |mapmode-s| *:sunm* *:sunmap* +:ou[nmap] {lhs} |mapmode-o| *:ou* *:ounmap* +:unm[ap]! {lhs} |mapmode-ic| *:unm!* *:unmap!* +: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. + Note: Trailing spaces are included in the {lhs}. This + unmap does NOT work: > + :map @@ foo + :unmap @@ | print + +:mapc[lear] |mapmode-nvo| *:mapc* *:mapclear* +:nmapc[lear] |mapmode-n| *:nmapc* *:nmapclear* +:vmapc[lear] |mapmode-v| *:vmapc* *:vmapclear* +:xmapc[lear] |mapmode-x| *:xmapc* *:xmapclear* +:smapc[lear] |mapmode-s| *:smapc* *:smapclear* +:omapc[lear] |mapmode-o| *:omapc* *:omapclear* +:mapc[lear]! |mapmode-ic| *:mapc!* *:mapclear!* +: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. {not in Vi} + Use the <buffer> argument to remove buffer-local + mappings |:map-<buffer>| + Warning: This also removes the default mappings. + +:map |mapmode-nvo| +:nm[ap] |mapmode-n| +:vm[ap] |mapmode-v| +:xm[ap] |mapmode-x| +:sm[ap] |mapmode-s| +:om[ap] |mapmode-o| +:map! |mapmode-ic| +: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. + +:map {lhs} |mapmode-nvo| *:map_l* +:nm[ap] {lhs} |mapmode-n| *:nmap_l* +:vm[ap] {lhs} |mapmode-v| *:vmap_l* +:xm[ap] {lhs} |mapmode-x| *:xmap_l* +:sm[ap] {lhs} |mapmode-s| *:smap_l* +:om[ap] {lhs} |mapmode-o| *:omap_l* +:map! {lhs} |mapmode-ic| *:map_l!* +: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. + {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-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} + + +1.2 SPECIAL ARGUMENTS *:map-arguments* + +"<buffer>", "<nowait>", "<silent>", "<special>", "<script>", "<expr>" and +"<unique>" can be used in any order. They must appear right after the +command, before any other arguments. + + *:map-local* *:map-<buffer>* *E224* *E225* +If the first argument to one of these commands is "<buffer>" the mapping will +be effective in 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. See <nowait> below +to make a short local mapping not taking effect when a longer global one +exists. +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. +Also see |map-precedence|. + + *:map-<nowait>* *:map-nowait* +When defining a buffer-local mapping for "," there may be a global mapping +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 typed they are used. + + *: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-<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 +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> +If you want to map a key and then have it do what it was originally mapped to, +have a look at |maparg()|. + + *:map-<expr>* *:map-expression* +If the first argument to one of these commands is "<expr>" and it is used to +define a new mapping or abbreviation, the argument is an expression. The +expression is evaluated to obtain the {rhs} that is used. Example: > + :inoremap <expr> . InsertDot() +The result of the InsertDot() function will be inserted. It could check the +text before the cursor and start omni completion when some condition is met. + +For abbreviations |v:char| is set to the character that was typed to trigger +the abbreviation. You can use this to decide how to expand the {lhs}. You +should not either insert or change the v:char. + +Be very careful about side effects! The expression is evaluated while +obtaining characters, you may very well make the command dysfunctional. +For this reason the following is blocked: +- Changing the buffer text |textlock|. +- Editing another buffer. +- 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. + +You can use getchar(), it consumes typeahead if there is any. E.g., if you +have these mappings: > + inoremap <expr> <C-L> nr2char(getchar()) + inoremap <expr> <C-L>x "foo" +If you now type CTRL-L nothing happens yet, Vim needs the next character to +decide what mapping to use. If you type 'x' the second mapping is used and +"foo" is inserted. If you type any other key the first mapping is used, +getchar() gets the typed key and returns it. + +Here is an example that inserts a list number that increases: > + let counter = 0 + inoremap <expr> <C-L> ListItem() + inoremap <expr> <C-R> ListReset() + + func ListItem() + let g:counter += 1 + return g:counter . '. ' + endfunc + + func ListReset() + let g:counter = 0 + return '' + endfunc + +CTRL-L inserts the next number, CTRL-R resets the count. CTRL-R returns an +empty string, so that nothing is inserted. + +Note that there are some tricks to make special keys work and escape CSI bytes +in the text. The |:map| command also does this, thus you must avoid that it +is done twice. This does not work: > + :imap <expr> <F3> "<Char-0x611B>" +Because the <Char- sequence is escaped for being a |:imap| argument and then +again for using <expr>. This does work: > + :imap <expr> <F3> "\u611B" +Using 0x80 as a single byte before other text does not work, it will be seen +as a special key. + + +1.3 MAPPING AND MODES *:map-modes* + *mapmode-nvo* *mapmode-n* *mapmode-v* *mapmode-o* + +There are six 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. +- For Operator-pending mode: When an operator is pending (after "d", "y", "c", + etc.). See below: |omap-info|. +- For Insert mode. These are also used in Replace mode. +- For Command-line mode: When entering a ":" or "/" command. + +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. More details below. + COMMANDS MODES ~ +:map :noremap :unmap Normal, Visual, Select, Operator-pending +:nmap :nnoremap :nunmap Normal +:vmap :vnoremap :vunmap Visual and Select +:smap :snoremap :sunmap Select +:xmap :xnoremap :xunmap Visual +:omap :onoremap :ounmap Operator-pending +:map! :noremap! :unmap! Insert and Command-line +:imap :inoremap :iunmap Insert +:lmap :lnoremap :lunmap Insert, Command-line, Lang-Arg +:cmap :cnoremap :cunmap Command-line +:tmap :tnoremap :tunmap Terminal-Job + + + COMMANDS MODES ~ + Normal Visual+Select Operator-pending ~ +:map :noremap :unmap :mapclear yes yes yes +:nmap :nnoremap :nunmap :nmapclear yes - - +:vmap :vnoremap :vunmap :vmapclear - yes - +:omap :onoremap :ounmap :omapclear - - yes + +:nunmap can also be used outside of a monastery. + *mapmode-x* *mapmode-s* +Some commands work both in Visual and Select mode, some in only one. Note +that quite often "Visual" is mentioned where both Visual and Select mode +apply. |Select-mode-mapping| +NOTE: Mapping a printable character in Select mode may confuse the user. It's +better to explicitly use :xmap and :smap for printable characters. Or use +:sunmap after defining the mapping. + + COMMANDS MODES ~ + Visual Select ~ +:vmap :vnoremap :vunmap :vmapclear yes yes +:xmap :xnoremap :xunmap :xmapclear yes - +:smap :snoremap :sunmap :smapclear - yes + + *mapmode-ic* *mapmode-i* *mapmode-c* *mapmode-l* +Some commands work both in Insert mode and Command-line mode, some not: + + COMMANDS MODES ~ + 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. + + *mapmode-t* +The terminal mappings are used in a terminal window, when typing keys for the +job running in the terminal. See |terminal-typing|. + + *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". + +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 +that operates on a function name in the current line: > + onoremap <silent> F :<C-U>normal! 0f(hviw<CR> +The CTRL-U (<C-U>) is used to remove the range that Vim may insert. The +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: > + :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-^|. These commands change the value of +the 'iminsert' option. 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. + + +1.4 LISTING MAPPINGS *map-listing* + +When listing mappings the characters in the first two columns are: + + CHAR MODE ~ + <Space> Normal, Visual, Select and Operator-pending + n Normal + v Visual and Select + s Select + x Visual + o Operator-pending + ! Insert and Command-line + i Insert + l ":lmap" mappings for Insert, Command-line and Lang-Arg + c Command-line + t Terminal-Job + +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 |'<|. + +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: > + + :verbose map <C-W>* + n <C-W>* * <C-W><C-S>* + Last set from /home/abcd/.vimrc + +See |:verbose-cmd| for more information. + + +1.5 MAPPING SPECIAL KEYS *: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. + + +1.6 SPECIAL CHARACTERS *:map-special-chars* + *map_backslash* *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_CTRL-C* *map-CTRL-C* +Using CTRL-C in the {lhs} is possible, but it will only work when Vim is +waiting for a key, not when Vim is busy with something. When Vim is busy +CTRL-C interrupts/breaks the command. +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* *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* *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* *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>* +An 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> +< + *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 á (0xe1 <M-a>) in UTF-8 encoding this is the +two bytes 0xc3 0xa1. You don't want the 0xc3 byte to be mapped then or +otherwise it would be impossible to type the á character. + + *<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* +<LocalLeader> is 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 <buffer> <LocalLeader>A oanother line<Esc> +< +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 + <S-Char-114> character 114 ('r') shifted ('R') +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}. 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 + \| '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* *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 %:S<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. + *map-error* +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. + + +1.7 WHAT KEYS TO MAP *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). Depending on your keyboard accented + characters may be used as well. |:map-alt-keys| +- 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. +- The key defined by <Leader> and one or more other keys. This is especially + useful in scripts. |mapleader| + +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). + + +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). > + + :map <F3> o#include + :map <M-g> /foo<CR>cwbar<Esc> + :map _x d/END/e<CR> + :map! qq quadrillion questions + + +Multiplying a count + +When you type a count before triggering a mapping, it's like the count was +typed before the {lhs}. For example, with this mapping: > + :map <F4> 3w +Typing 2<F4> will result in "23w". Thus not moving 2 * 3 words but 23 words. +If you want to multiply counts use the expression register: > + :map <F4> @='3w'<CR> +The part between quotes is the expression being executed. |@=| + + +1.9 USING MAPPINGS *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-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 +mapping immediately if it was defined with <nowait>, even if a longer mapping +has the same prefix. For example, given the following two mappings: > + :map <buffer> <nowait> \a :echo "Local \a"<CR> + :map \abc :echo "Global \abc"<CR> +When typing \a the buffer-local mapping will be used immediately. Vim will +not wait for more characters to see if the user might be typing \abc. + + *map-keys-fails* +There are situations 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. + +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 +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). + + +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. + + +1.11 MAPPING AN OPERATOR *:map-operator* + +An operator is used before a {motion} command. To define your own operator +you must create mapping that first sets the 'operatorfunc' option and then +invoke the |g@| operator. After the user types the {motion} command the +specified function will be called. + + *g@* *E774* *E775* +g@{motion} Call the function set by the 'operatorfunc' option. + The '[ mark is positioned at the start of the text + moved over by {motion}, the '] mark on the last + character of the text. + The function is called with one String argument: + "line" {motion} was |linewise| + "char" {motion} was |characterwise| + "block" {motion} was |blockwise-visual| + Although "block" would rarely appear, since it can + only result from Visual mode where "g@" is not useful. + {not available when compiled without the |+eval| + feature} + +Here is an example that counts the number of spaces with <F4>: > + + nmap <silent> <F4> :set opfunc=CountSpaces<CR>g@ + vmap <silent> <F4> :<C-U>call CountSpaces(visualmode(), 1)<CR> + + function! CountSpaces(type, ...) + let sel_save = &selection + let &selection = "inclusive" + let reg_save = @@ + + if a:0 " Invoked from Visual mode, use gv command. + silent exe "normal! gvy" + elseif a:type == 'line' + silent exe "normal! '[V']y" + else + silent exe "normal! `[v`]y" + endif + + echomsg strlen(substitute(@@, '[^ ]', '', 'g')) + + let &selection = sel_save + let @@ = reg_save + endfunction + +Note that the 'selection' option is temporarily set to "inclusive" to be able +to yank exactly the right text by using Visual mode from the '[ to the '] +mark. + +Also note that there is a separate mapping for Visual mode. It removes the +"'<,'>" range that ":" inserts in Visual mode and invokes the function with +visualmode() and an extra argument. + +============================================================================== +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. 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. + +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 CTRL-V before the character +that would trigger the abbreviation. E.g. CTRL-V <Space>. Or type part of +the abbreviation, exit insert mode with <Esc>, re-enter insert mode with "a" +and type the rest. + +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(0)) + 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|. + + *:abbreviate-verbose* +When 'verbose' is non-zero, listing an abbreviation will also display where it +was last defined. Example: > + + :verbose abbreviate + ! teh the + Last set from /home/abcd/vim/abbr.vim + +See |:verbose-cmd| for more information. + +: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] [<expr>] [<buffer>] {lhs} {rhs} + add abbreviation for {lhs} to {rhs}. If {lhs} already + existed it is replaced with the new {rhs}. {rhs} may + contain spaces. + See |:map-<expr>| for the optional <expr> argument. + See |:map-<buffer>| for the optional <buffer> argument. + + *: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] [<expr>] [<buffer>] [lhs] [rhs] + same as ":ab", but no remapping for this {rhs} {not + in Vi} + + *:ca* *:cabbrev* +:ca[bbrev] [<expr>] [<buffer>] [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] [<expr>] [<buffer>] [lhs] [rhs] + same as ":ab", but for Command-line mode only and no + remapping for this {rhs} {not in Vi} + + *:ia* *:iabbrev* +:ia[bbrev] [<expr>] [<buffer>] [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] [<expr>] [<buffer>] [lhs] [rhs] + same as ":ab", but for Insert mode only and no + remapping for this {rhs} {not in Vi} + + *:abc* *:abclear* +:abc[lear] [<buffer>] Remove all abbreviations. {not in Vi} + + *:iabc* *:iabclear* +:iabc[lear] [<buffer>] Remove all abbreviations for Insert mode. {not in Vi} + + *:cabc* *:cabclear* +:cabc[lear] [<buffer>] 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 function: > + function s:SID() + return matchstr(expand('<sfile>'), '<SNR>\zs\d\+\ze_SID$') + endfun + +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* *E841* *user-cmd-ambiguous* +All user defined commands must start with an uppercase letter, to avoid +confusion with builtin commands. Exceptions are these builtin commands: + :Next + :X +They cannot be used for a user defined command. ":Print" is also an existing +command, but it is deprecated and can be overruled. + +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) + 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} + + *:command-verbose* +When 'verbose' is non-zero, listing a command will also display where it was +last defined. Example: > + + :verbose command TOhtml +< Name Args Range Complete Definition ~ + TOhtml 0 % :call Convert2HTML(<line1>, <line2>) ~ + Last set from /usr/share/vim/vim-7.0/plugin/tohtml.vim ~ + +See |:verbose-cmd| for more information. + + *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. + There is one exception: When sourcing a script again, + a command that was previously defined in that script + will be silently replaced. + + +: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* *:command-nargs* +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, it includes spaces + -nargs=* Any number of arguments are allowed (0, 1, or many), + separated by white space + -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, except when there is one argument, then the white space is part of +the argument. + +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" being echoed. Not what you +intended! Calling a function may be an alternative. + + +Completion behavior ~ + *:command-completion* *E179* *E180* *E181* + *:command-complete* +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 + -complete=color color schemes + -complete=command Ex command (and arguments) + -complete=compiler compilers + -complete=cscope |:cscope| suboptions + -complete=dir directory names + -complete=environment environment variable names + -complete=event autocommand events + -complete=expression Vim expression + -complete=file file and directory names + -complete=file_in_path file and directory names in |'path'| + -complete=filetype filetype names |'filetype'| + -complete=function function name + -complete=help help subjects + -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'| + -complete=syntime |:syntime| suboptions + -complete=tag tags + -complete=tag_listfiles tags, file names are shown when CTRL-D is hit + -complete=user user names + -complete=var user variables + -complete=custom,{func} custom completion, defined via {func} + -complete=customlist,{func} custom completion, defined via {func} + +Note: That some completion methods might expand environment variables. + + +Custom completion ~ + *:command-completion-custom* + *:command-completion-customlist* *E467* *E468* +It is possible to define customized completion schemes via the "custom,{func}" +or the "customlist,{func}" completion argument. The {func} part should be a +function with the following signature: > + + :function {func}(ArgLead, CmdLine, CursorPos) + +The function need not use all these arguments. The function should provide the +completion candidates as the return value. + +For the "custom" argument, the function should return the completion +candidates one per line in a newline separated string. + +For the "customlist" argument, the function should return the completion +candidates as a Vim List. Non-string items in the list are ignored. + +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 (byte index) +The function may use these for determining context. For the "custom" +argument, it is not necessary to filter candidates against the (implicit +pattern in) ArgLead. Vim will filter the candidates with its regexp engine +after function return, and this is probably more efficient in most cases. For +the "customlist" argument, Vim will not filter the returned completion +candidates and the user supplied function should filter the candidates. + +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 + +The following example completes filenames from the directories specified in +the 'path' option: > + :com -nargs=1 -bang -complete=customlist,EditFileComplete + \ EditFile edit<bang> <args> + :fun EditFileComplete(A,L,P) + : return split(globpath(&path, a:A), "\n") + :endfun +< +This example does not work for file names with spaces! + + +Range handling ~ + *E177* *E178* *:command-range* *:command-count* +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). The count will then be +available in the argument with |<count>|. + +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|); allows for zero line + number. + -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. + + *: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. + +Possible values are: + -addr=lines Range of lines (this is the default) + -addr=arguments Range for arguments + -addr=buffers Range for buffers (also not loaded buffers) + -addr=loaded_buffers Range for loaded buffers + -addr=windows Range for windows + -addr=tabs Range for tab pages + -addr=other other kind of range + + +Special cases ~ + *:command-bang* *:command-bar* + *:command-register* *:command-buffer* +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. +Note that these arguments can be abbreviated, but that is a deprecated +feature. Use the full name for new scripts. + + +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. To avoid the replacement use +<lt> in place of the initial <. Thus to include "<bang>" literally use +"<lt>bang>". + +The valid escape sequences are + + *<line1>* + <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). + *<bang>* + <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> + 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. +When there is no argument <q-args> is an empty string. + *<f-args>* +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. If no arguments are given <f-args> is removed. + To embed whitespace into an argument of <f-args>, prepend a backslash. +<f-args> replaces every pair of backslashes (\\) with one backslash. A +backslash followed by a character other than white space or a backslash +remains unmodified. Overview: + + command <f-args> ~ + XX ab 'ab' + XX a\b 'a\b' + XX a\ b 'a b' + XX a\ b 'a ', 'b' + XX a\\b 'a\b' + XX a\\ b 'a\', 'b' + XX a\\\b 'a\\b' + XX a\\\ b 'a\ b' + XX a\\\\b 'a\\b' + XX a\\\\ b 'a\\', 'b' + +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 a 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:noet:ft=help:norl: |