*map.txt*       For Vim version 6.0ax.  Last change: 2001 Sep 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|
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*
:lno[remap] {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.

						*: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().

						*: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" ad "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|.

						*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 and Command-line mode, the
argument of the commands that accept a text character, when entering a search
pattern and for the input() line.  Generally: Whenever a character is to be
typed that is inserted in the text, 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
ca                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            