summaryrefslogtreecommitdiff
path: root/runtime/doc/map.txt
diff options
context:
space:
mode:
authorBram Moolenaar <Bram@vim.org>2004-06-13 20:20:40 +0000
committerBram Moolenaar <Bram@vim.org>2004-06-13 20:20:40 +0000
commit071d4279d6ab81b7187b48f3a0fc61e587b6db6c (patch)
tree221cbe3c40e043163c06f61c52a7ba2eb41e12ce /runtime/doc/map.txt
parentb4210b3bc14e2918f153a7307530fbe6eba659e1 (diff)
downloadvim-git-071d4279d6ab81b7187b48f3a0fc61e587b6db6c.tar.gz
updated for version 7.0001v7.0001
Diffstat (limited to 'runtime/doc/map.txt')
-rw-r--r--runtime/doc/map.txt1094
1 files changed, 1094 insertions, 0 deletions
diff --git a/runtime/doc/map.txt b/runtime/doc/map.txt
new file mode 100644
index 000000000..8c05ddc76
--- /dev/null
+++ b/runtime/doc/map.txt
@@ -0,0 +1,1094 @@
+*map.txt* For Vim version 7.0aa. Last change: 2004 May 21
+
+
+ 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".
+ When adding a ":lmap" mapping the use of these mappings in Insert mode and
+for Search patterns will be switched on.
+ 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 input-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
+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: