path: root/runtime/doc/map.txt

*map.txt*       For Vim version 7.0aa.  Last change: 2005 Aug 16


		  VIM REFERENCE MANUAL    by Bram Moolenaar


Key mapping, abbreviations and user-defined commands.

This subject is introduced in sections |05.3|, |24.7| and |40.1| of the user
manual.

1. Key mapping			|key-mapping|
2. Abbreviations		|abbreviations|
3. Local mappings and functions	|script-local|
4. User-defined commands	|user-commands|

==============================================================================
1. Key mapping				*key-mapping* *mapping* *macro*

Key mapping is used to change the meaning of typed keys.  The most common use
is to define a sequence commands for a function key.  Example: >

	:map <F2> a<C-R>=strftime("%c")<CR><Esc>

This appends the current date and time after the cursor (in <> notation |<>|).

There are commands to enter new mappings, remove mappings and list mappings.
See |map-overview| for the various forms of "map" and their relationships with
modes.

{lhs}	means left-hand-side	*{lhs}*
{rhs}	means right-hand-side	*{rhs}*

:map	{lhs} {rhs}					*:map*
:nm[ap]	{lhs} {rhs}					*:nm* *:nmap*
:vm[ap]	{lhs} {rhs}					*:vm* *:vmap*
:om[ap]	{lhs} {rhs}					*:om* *:omap*
:map!	{lhs} {rhs}					*:map!*
:im[ap]	{lhs} {rhs}					*:im* *:imap*
:lm[ap]	{lhs} {rhs}					*:lm* *:lmap*
:cm[ap]	{lhs} {rhs}					*:cm* *:cmap*
			Map the key sequence {lhs} to {rhs} for the modes
			where the map command applies.  The result, including
			{rhs}, is then further scanned for mappings.  This
			allows for nested and recursive use of mappings.


:no[remap]  {lhs} {rhs}					*:no*  *:noremap*
:nn[oremap] {lhs} {rhs}					*:nn*  *:nnoremap*
:vn[oremap] {lhs} {rhs}					*:vn*  *:vnoremap*
:ono[remap] {lhs} {rhs}					*:ono* *:onoremap*
:no[remap]! {lhs} {rhs}					*:no!* *:noremap!*
:ino[remap] {lhs} {rhs}					*:ino* *:inoremap*
:ln[oremap] {lhs} {rhs}					*:ln*  *:lnoremap*
:cno[remap] {lhs} {rhs}					*:cno* *:cnoremap*
			Map the key sequence {lhs} to {rhs} for the modes
			where the map command applies.  Disallow mapping of
			{rhs}, to avoid nested and recursive mappings.  Often
			used to redefine a command.  {not in Vi}


:unm[ap]  {lhs}						*:unm*  *:unmap*
:nun[map] {lhs}						*:nun*  *:nunmap*
:vu[nmap] {lhs}						*:vu*   *:vunmap*
:ou[nmap] {lhs}						*:ou*   *:ounmap*
:unm[ap]! {lhs}						*:unm!* *:unmap!*
:iu[nmap] {lhs}						*:iu*   *:iunmap*
:lu[nmap] {lhs}						*:lu*   *:lunmap*
:cu[nmap] {lhs}						*:cu*   *:cunmap*
			Remove the mapping of {lhs} for the modes where the
			map command applies.  The mapping may remain defined
			for other modes where it applies.
			Note: Trailing spaces are included in the {lhs}.  This
			unmap does NOT work: >
				:map @@ foo
				:unmap @@ | print

:mapc[lear]						*:mapc*   *:mapclear*
:nmapc[lear]						*:nmapc*  *:nmapclear*
:vmapc[lear]						*:vmapc*  *:vmapclear*
:omapc[lear]						*:omapc*  *:omapclear*
:mapc[lear]!						*:mapc!*  *:mapclear!*
:imapc[lear]						*:imapc*  *:imapclear*
:lmapc[lear]						*:lmapc*  *:lmapclear*
:cmapc[lear]						*:cmapc*  *:cmapclear*
			Remove ALL mappings for the modes where the map
			command applies.  {not in Vi}
			Warning: This also removes the default mappings.

:map
:nm[ap]
:vm[ap]
:om[ap]
:map!
:im[ap]
:lm[ap]
:cm[ap]
			List all key mappings for the modes where the map
			command applies.  Note that ":map" and ":map!" are
			used most often, because they include the other modes.

:map    {lhs}						*:map_l*
:nm[ap] {lhs}						*:nmap_l*
:vm[ap] {lhs}						*:vmap_l*
:om[ap] {lhs}						*:omap_l*
:map!   {lhs}						*:map_l!*
:im[ap] {lhs}						*:imap_l*
:lm[ap] {lhs}						*:lmap_l*
:cm[ap] {lhs}						*:cmap_l*
			List the key mappings for the key sequences starting
			with {lhs} in the modes where the map command applies.
			{not in Vi}

These commands are used to map a key or key sequence to a string of
characters.  You can use this to put command sequences under function keys,
translate one key into another, etc.  See |:mkexrc| for how to save and
restore the current mappings.

				*:map-local* *:map-<buffer>* *E224* *E225*
If the first argument to one of these commands is "<buffer>" it will apply to
mappings locally to the current buffer only.  Example: >
	:map <buffer>  ,w  /[.,;]<CR>
Then you can map ",w" to something else in another buffer: >
	:map <buffer>  ,w  /[#&!]<CR>
The local buffer mappings are used before the global ones.
The "<buffer>" argument can also be used to clear mappings: >
	:unmap <buffer> ,w
	:mapclear <buffer>
Local mappings are also cleared when a buffer is deleted, but not when it is
unloaded.  Just like local option values.

						*:map-<silent>* *:map-silent*
To define a mapping which will not be echoed on the command line, add
"<silent>" as the first argument.  Example: >
	:map <silent> ,h /Header<CR>
The search string will not be echoed when using this mapping.  Messages from
the executed command are still given though.  To shut them up too, add a
":silent" in the executed command: >
	:map <silent> ,h :exe ":silent normal /Header\r"<CR>
Prompts will still be given, e.g., for inputdialog().
Using "<silent>" for an abbreviation is possible, but will cause redrawing of
the command line to fail.

						*:map-<script>* *:map-script*
If the first argument to one of these commands is "<script>" and it is used to
define a new mapping or abbreviation, the mapping will only remap characters
in the {rhs} using mappings that were defined local to a script, starting with
"<SID>".  This can be used to avoid that mappings from outside a script
interfere (e.g., when CTRL-V is remapped in mswin.vim), but do use other
mappings defined in the script.
Note: ":map <script>" and ":noremap <script>" do the same thing.  The
"<script>" overrules the command name.  Using ":noremap <script>" is
preferred, because it's clearer that remapping is (mostly) disabled.

						*:map-<unique>* *E226* *E227*
If the first argument to one of these commands is "<unique>" and it is used to
define a new mapping or abbreviation, the command will fail if the mapping or
abbreviation already exists.  Example: >
	:map <unique> ,w  /[#&!]<CR>
When defining a local mapping, there will also be a check if a global map
already exists which is equal.
Example of what will fail: >
	:map ,w  /[#&!]<CR>
	:map <buffer> <unique> ,w  /[.,;]<CR>

"<buffer>", "<silent>", "<script>" and "<unique>" can be used in any order.
They must appear right after the command, before any other arguments.


MAPPING AND MODES

There are five sets of mappings
- For Normal mode: When typing commands.
- For Visual mode: When typing commands while the Visual area is highlighted.
- For Operator-pending mode: When an operator is pending (after "d", "y", "c",
  etc.).  Example: ":omap { w" makes "y{" work like "yw" and "d{" like "dw".
- For Insert mode.  These are also used in Replace mode.
- For Command-line mode: When entering a ":" or "/" command.

There are no separate mappings for Select mode.  The same as for Visual mode
are used |Select-mode-mapping|.

Special case: While typing a count for a command in Normal mode, mapping zero
is disabled.  This makes it possible to map zero without making it impossible
to type a count with a zero.

						*map-overview* *map-modes*
Overview of which map command works in which mode:

    commands:				      modes: ~
					  Normal     Visual  Operator-pending ~
:map   :noremap   :unmap   :mapclear	    yes	       yes	  yes
:nmap  :nnoremap  :nunmap  :nmapclear	    yes		-	   -
:vmap  :vnoremap  :vunmap  :vmapclear	     -	       yes	   -
:omap  :onoremap  :ounmap  :omapclear	     -		-	  yes

					  Insert  Command-line	Lang-Arg ~
:map!  :noremap!  :unmap!  :mapclear!	    yes	       yes	   -
:imap  :inoremap  :iunmap  :imapclear	    yes		-	   -
:cmap  :cnoremap  :cunmap  :cmapclear	     -	       yes	   -
:lmap  :lnoremap  :lunmap  :lmapclear	    yes*       yes*	  yes*

The original Vi did not have separate mappings for
Normal/Visual/Operator-pending mode and for Insert/Command-line mode.
Therefore the ":map" and ":map!" commands enter and display mappings for
several modes.  In Vim you can use the ":nmap", ":vmap", ":omap", ":cmap" and
":imap" commands to enter mappings for each mode separately.

To enter a mapping for Normal and Visual mode, but not Operator-pending mode,
first define it for all three modes, then unmap it for Operator-pending mode:
	:map    xx something-difficult
	:ounmap xx
Likewise for a mapping for Visual and Operator-pending mode or Normal and
Operator-pending mode.

						*language-mapping*
":lmap" defines a mapping that applies to:
- Insert mode
- Command-line mode
- when entering a search pattern
- the argument of the commands that accept a text character, such as "r" and
  "f"
- for the input() line
Generally: Whenever a character is to be typed that is part of the text in the
buffer, not a Vim command character.  "Lang-Arg" isn't really another mode,
it's just used here for this situation.
   The simplest way to load a set of related language mappings is by using the
'keymap' option.  See |45.5|.
   In Insert mode and in Command-line mode the mappings can be disabled with
the CTRL-^ command |i_CTRL-^| |c_CTRL-^|.  When starting to enter a normal
command line (not a search pattern) the mappings are disabled until a CTRL-^
is typed.  The state last used is remembered for Insert mode and Search
patterns separately.  The state for Insert mode is also used when typing a
character as an argument to command like "f" or "t".
   Language mappings will never be applied to already mapped characters.  They
are only used for typed characters.  This assumes that the language mapping
was already done when typing the mapping.

							*map-multibyte*
It is possible to map multibyte characters, but only the whole character.  You
cannot map the first byte only.  This was done to prevent problems in this
scenario: >
	:set encoding=latin1
	:imap <M-C> foo
	:set encoding=utf-8
The mapping for <M-C> is defined with the latin1 encoding, resulting in a 0xc3
byte.  If you type the character � (0xea <M-a>) in UTF-8 encoding this is the
two bytes 0xc3 0xa1.  You don't want the 0xc3 byte to be mapped then,
otherwise it would be impossible to type the � character.

							*map-listing*
When listing mappings the characters in the first two columns are:

      CHAR	MODE	~
     <Space>	Normal, Visual and Operator-pending
	n	Normal
	v	Visual
	o	Operator-pending
	!	Insert and Command-line
	i	Insert
	l	":lmap" mappings for Insert, Command-line and Lang-Arg
	c	Command-line

Just before the {rhs} a special character can appear:
	*	indicates that it is not remappable
	&	indicates that only script-local mappings are remappable
	@	indicates a buffer-local mapping

Everything from the first non-blank after {lhs} up to the end of the line
(or '|') is considered to be part of {rhs}.  This allows the {rhs} to end
with a space.

Note: When using mappings for Visual mode, you can use the "'<" mark, which
is the start of the last selected Visual area in the current buffer |'<|.

							*:map-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.

							*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
thi