map.txt       For Vim version 7.3.  Last change: 2010 Nov 10


                  VIM REFERENCE MANUAL    by Bram Moolenaar


Key mapping, abbreviations and user-defined commands.

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

1. Key mapping                  key-mapping
   1.1 MAP COMMANDS                     :map-commands
   1.3 Mapping and modes                :map-modes
   1.4 Listing mappings                 map-listing
   1.5 Mapping special keys             :map-special-keys

NOTE: only nvoip mode mappings are supported (currently)
      normal, visual, operator-pending, insert PLATFORM-SELECT mode

NOTE: jVi supports additional map commands, :pmap, :pnoremap, :punmap.
      These are normal mode, they are valid when PLATFORM-SELECT is the
      displayed mode, for example the mouse is used to make a selection.
          :pnoremap y vy
          :pnoremap p vp
      map yank and put to work with the mouse selection

==============================================================================
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 <PageUp> <C-U>
        :map Y y$

1.1 MAP COMMANDS                                        :map-commands

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

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

:map    {lhs} {rhs}             mapmode-nvo           :map
:nm[ap] {lhs} {rhs}             mapmode-n             :nm :nmap
:vm[ap] {lhs} {rhs}             mapmode-v             :vm :vmap
:om[ap] {lhs} {rhs}             mapmode-o             :om :omap
:pm[ap] {lhs} {rhs}             mapmode-p             :pm :pmap
                        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}         mapmode-nvo           :no  :noremap
:nn[oremap] {lhs} {rhs}         mapmode-n             :nn  :nnoremap
:vn[oremap] {lhs} {rhs}         mapmode-v             :vn  :vnoremap
:ono[remap] {lhs} {rhs}         mapmode-o             :ono :onoremap
:pn[oremap] {lhs} {rhs}         mapmode-p             :pn  :pnoremap
                        Map the key sequence {lhs} to {rhs} for the modes
                        where the map command applies.  Disallow mapping of
                        {rhs}, to avoid nested and recursive mappings.  Often
                        used to redefine a command.  {not in Vi}


:unm[ap]  {lhs}                 mapmode-nvo           :unm  :unmap
:nun[map] {lhs}                 mapmode-n             :nun  :nunmap
:vu[nmap] {lhs}                 mapmode-v             :vu   :vunmap
:ou[nmap] {lhs}                 mapmode-o             :ou   :ounmap
:pun[map] {lhs}                 mapmode-p             :pun  :punmap
                        Remove the mapping of {lhs} for the modes where the
                        map command applies.  The mapping may remain defined
                        for other modes where it applies.

:map                            mapmode-nvo
:nm[ap]                         mapmode-n
:vm[ap]                         mapmode-v
:om[ap]                         mapmode-o
:pm[ap]                         mapmode-p
                        List all key mappings for the modes where the map
                        command applies.  Note that ":map" and ":map!" are
                        used most often, because they include the other modes.

:map    {lhs}                   mapmode-nvo           :map_l
:nm[ap] {lhs}                   mapmode-n             :nmap_l
:vm[ap] {lhs}                   mapmode-v             :vmap_l
:om[ap] {lhs}                   mapmode-o             :omap_l
:pm[ap] {lhs}                   mapmode-p             :pmap_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.


1.3 MAPPING AND MODES                                   :map-modes
                mapmode-nvo mapmode-n mapmode-v mapmode-o mapmode-p

There are six sets of mappings
- For Normal mode: When typing commands.
- For Visual mode: When typing commands while the Visual area is highlighted.
- For Operator-pending mode: When an operator is pending (after "d", "y", "c",
  etc.).  See below: omap-info.
- For PLATFORM-SELECT mode: when there is a mouse selection {jVi only}

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+Select  Operator-pending 
:map   :noremap   :unmap   :mapclear     yes        yes            yes
:nmap  :nnoremap  :nunmap  :nmapclear    yes         -              -
:vmap  :vnoremap  :vunmap  :vmapclear     -         yes             -
:omap  :onoremap  :ounmap  :omapclear     -          -             yes

:nunmap can also be used outside of a monastery.

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.

                                                        omap-info
Operator-pending mappings can be used to define a movement command that can be
used with any operator.  Simple example: ":omap { w" makes "y{" work like "yw"
and "d{" like "dw".

To 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.


1.4 LISTING MAPPINGS                                    map-listing

When listing mappings the characters in the first two columns are:

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

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 '<.


1.5 MAPPING SPECIAL KEYS                                :map-special-keys

jVi currently supports the following special keys. This will likely expand.
There may be semantic/incompatible changes as well.

      <Nul>     '\n'
      <BS>      '\b'
      <Tab>     '\t'
      <NL>      '\n'
      <FF>      '\f'
      <CR>      '\n'
      <Return>  '\n'
      <Enter>   '\n'
      <Esc>     '\u001b'
      <Space>   ' '
      <lt>      '<'
      <Bslash>  '\\'
      <Bar>     '|'
      <Del>     '\u007f'

      <EOL>     '\n'

The control/shifted versions can be mapped as <C-special>/<S-special>.

      <Up>
      <Down>
      <Left>
      <Right>

      <Help>
      <Undo>
      <Insert>
      <Home>
      <End>
      <PageUp>
      <PageDown>

 vim:tw=78:ts=8:sw=8:noet: