*map.txt* For Vim version 7.3. Last change: 2012 Apr 13 VIM REFERENCE MANUAL by Bram Moolenaar Key mapping, abbreviations and user-defined commands. This subject is introduced in sections |05.3|, |24.7| and |40.1| of the user manual. 1. Key mapping |key-mapping| 1.1 MAP COMMANDS |:map-commands| 1.2 Special arguments |:map-arguments| 1.3 Mapping and modes |:map-modes| 1.4 Listing mappings |map-listing| 1.5 Mapping special keys |:map-special-keys| 1.6 Special characters |:map-special-chars| 1.7 What keys to map |map-which-keys| 1.8 Examples |map-examples| 1.9 Using mappings |map-typing| 1.10 Mapping alt-keys |:map-alt-keys| 1.11 Mapping an operator |:map-operator| 2. Abbreviations |abbreviations| 3. Local mappings and functions |script-local| 4. User-defined commands |user-commands| ============================================================================== 1. Key mapping *key-mapping* *mapping* *macro* Key mapping is used to change the meaning of typed keys. The most common use is to define a sequence commands for a function key. Example: > :map a=strftime("%c") This appends the current date and time after the cursor (in <> notation |<>|). 1.1 MAP COMMANDS *:map-commands* There are commands to enter new mappings, remove mappings and list mappings. See |map-overview| for the various forms of "map" and their relationships with modes. {lhs} means left-hand-side *{lhs}* {rhs} means right-hand-side *{rhs}* :map {lhs} {rhs} |mapmode-nvo| *:map* :nm[ap] {lhs} {rhs} |mapmode-n| *:nm* *:nmap* :vm[ap] {lhs} {rhs} |mapmode-v| *:vm* *:vmap* :xm[ap] {lhs} {rhs} |mapmode-x| *:xm* *:xmap* :smap {lhs} {rhs} |mapmode-s| *:smap* :om[ap] {lhs} {rhs} |mapmode-o| *:om* *:omap* :map! {lhs} {rhs} |mapmode-ic| *:map!* :im[ap] {lhs} {rhs} |mapmode-i| *:im* *:imap* :lm[ap] {lhs} {rhs} |mapmode-l| *:lm* *:lmap* :cm[ap] {lhs} {rhs} |mapmode-c| *:cm* *:cmap* 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* :xn[oremap] {lhs} {rhs} |mapmode-x| *:xn* *:xnoremap* :snor[emap] {lhs} {rhs} |mapmode-s| *:snor* *:snoremap* :ono[remap] {lhs} {rhs} |mapmode-o| *:ono* *:onoremap* :no[remap]! {lhs} {rhs} |mapmode-ic| *:no!* *:noremap!* :ino[remap] {lhs} {rhs} |mapmode-i| *:ino* *:inoremap* :ln[oremap] {lhs} {rhs} |mapmode-l| *:ln* *:lnoremap* :cno[remap] {lhs} {rhs} |mapmode-c| *:cno* *:cnoremap* Map the key sequence {lhs} to {rhs} for the modes where the map command applies. Disallow mapping of {rhs}, to avoid nested and recursive mappings. Often used to redefine a command. {not in Vi} :unm[ap] {lhs} |mapmode-nvo| *:unm* *:unmap* :nun[map] {lhs} |mapmode-n| *:nun* *:nunmap* :vu[nmap] {lhs} |mapmode-v| *:vu* *:vunmap* :xu[nmap] {lhs} |mapmode-x| *:xu* *:xunmap* :sunm[ap] {lhs} |mapmode-s| *:sunm* *:sunmap* :ou[nmap] {lhs} |mapmode-o| *:ou* *:ounmap* :unm[ap]! {lhs} |mapmode-ic| *:unm!* *:unmap!* :iu[nmap] {lhs} |mapmode-i| *:iu* *:iunmap* :lu[nmap] {lhs} |mapmode-l| *:lu* *:lunmap* :cu[nmap] {lhs} |mapmode-c| *:cu* *:cunmap* Remove the mapping of {lhs} for the modes where the map command applies. The mapping may remain defined for other modes where it applies. Note: Trailing spaces are included in the {lhs}. This unmap does NOT work: > :map @@ foo :unmap @@ | print :mapc[lear] |mapmode-nvo| *:mapc* *:mapclear* :nmapc[lear] |mapmode-n| *:nmapc* *:nmapclear* :vmapc[lear] |mapmode-v| *:vmapc* *:vmapclear* :xmapc[lear] |mapmode-x| *:xmapc* *:xmapclear* :smapc[lear] |mapmode-s| *:smapc* *:smapclear* :omapc[lear] |mapmode-o| *:omapc* *:omapclear* :mapc[lear]! |mapmode-ic| *:mapc!* *:mapclear!* :imapc[lear] |mapmode-i| *:imapc* *:imapclear* :lmapc[lear] |mapmode-l| *:lmapc* *:lmapclear* :cmapc[lear] |mapmode-c| *:cmapc* *:cmapclear* Remove ALL mappings for the modes where the map command applies. {not in Vi} Use the argument to remove buffer-local mappings |:map-| Warning: This also removes the default mappings. :map |mapmode-nvo| :nm[ap] |mapmode-n| :vm[ap] |mapmode-v| :xm[ap] |mapmode-x| :sm[ap] |mapmode-s| :om[ap] |mapmode-o| :map! |mapmode-ic| :im[ap] |mapmode-i| :lm[ap] |mapmode-l| :cm[ap] |mapmode-c| List all key mappings for the modes where the map command applies. Note that ":map" and ":map!" are used most often, because they include the other modes. :map {lhs} |mapmode-nvo| *:map_l* :nm[ap] {lhs} |mapmode-n| *:nmap_l* :vm[ap] {lhs} |mapmode-v| *:vmap_l* :xm[ap] {lhs} |mapmode-x| *:xmap_l* :sm[ap] {lhs} |mapmode-s| *:smap_l* :om[ap] {lhs} |mapmode-o| *:omap_l* :map! {lhs} |mapmode-ic| *:map_l!* :im[ap] {lhs} |mapmode-i| *:imap_l* :lm[ap] {lhs} |mapmode-l| *:lmap_l* :cm[ap] {lhs} |mapmode-c| *:cmap_l* List the key mappings for the key sequences starting with {lhs} in the modes where the map command applies. {not in Vi} These commands are used to map a key or key sequence to a string of characters. You can use this to put command sequences under function keys, translate one key into another, etc. See |:mkexrc| for how to save and restore the current mappings. *map-ambiguous* When two mappings start with the same sequence of characters, they are ambiguous. Example: > :imap aa foo :imap aaa bar When Vim has read "aa", it will need to get another character to be able to decide if "aa" or "aaa" should be mapped. This means that after typing "aa" that mapping won't get expanded yet, Vim is waiting for another character. If you type a space, then "foo" will get inserted, plus the space. If you type "a", then "bar" will get inserted. {Vi does not allow ambiguous mappings} 1.2 SPECIAL ARGUMENTS *:map-arguments* "", "", "", "