代码拉取完成，页面将自动刷新
<!doctype html>
<html>
<head>
<meta charset="UTF-8">
<title>map - Vim Documentation</title>
<meta name="Generator" content="Vim/8.0">
<meta name="plugin-version" content="vim8.0">
<meta name="syntax" content="help">
<meta name="settings" content="no_pre,use_css,expand_tabs">
<link rel="stylesheet" href="style.css" type="text/css" />
<script src="jquery.min.js" type="text/javascript"></script>
<script src="mark-current-page.js" type="text/javascript"></script>
</head>
<body>
<header>
<div class="header">
<a href="http://vim-jp.org/">vim-jp</a>
/ <a href="http://vim-jp.org/vimdoc-en/">vimdoc-en</a>
/ map<br />
<a name="top"></a><h1>map - Vim Documentation</h1>
<a href="index.html">Return to main</a>
<span class="EnglishJapaneseLink">
<span class="CurrentLanguage">English</span>
</span>
</div>
</header>
<nav>
<dl>
<dt>BASIC</dt>
<dd><ul>
<li><a href="quickref.html">quickref</a></li>
<li><a href="sponsor.html">sponsor</a></li>
</ul></dd>
<dt>USER MANUAL</dt>
<dd><ul>
<li><a href="usr_toc.html">usr_toc</a></li>
</ul></dd>
<dt>Getting Started</dt>
<dd><ul>
<li><a href="usr_01.html">usr_01</a></li>
<li><a href="usr_02.html">usr_02</a></li>
<li><a href="usr_03.html">usr_03</a></li>
<li><a href="usr_04.html">usr_04</a></li>
<li><a href="usr_05.html">usr_05</a></li>
<li><a href="usr_06.html">usr_06</a></li>
<li><a href="usr_07.html">usr_07</a></li>
<li><a href="usr_08.html">usr_08</a></li>
<li><a href="usr_09.html">usr_09</a></li>
<li><a href="usr_10.html">usr_10</a></li>
<li><a href="usr_11.html">usr_11</a></li>
<li><a href="usr_12.html">usr_12</a></li>
</ul></dd>
<dt>Editing Effectively</dt>
<dd><ul>
<li><a href="usr_20.html">usr_20</a></li>
<li><a href="usr_21.html">usr_21</a></li>
<li><a href="usr_22.html">usr_22</a></li>
<li><a href="usr_23.html">usr_23</a></li>
<li><a href="usr_24.html">usr_24</a></li>
<li><a href="usr_25.html">usr_25</a></li>
<li><a href="usr_26.html">usr_26</a></li>
<li><a href="usr_27.html">usr_27</a></li>
<li><a href="usr_28.html">usr_28</a></li>
<li><a href="usr_29.html">usr_29</a></li>
<li><a href="usr_30.html">usr_30</a></li>
<li><a href="usr_31.html">usr_31</a></li>
<li><a href="usr_32.html">usr_32</a></li>
</ul></dd>
<dt>Tuning Vim</dt>
<dd><ul>
<li><a href="usr_40.html">usr_40</a></li>
<li><a href="usr_41.html">usr_41</a></li>
<li><a href="usr_42.html">usr_42</a></li>
<li><a href="usr_43.html">usr_43</a></li>
<li><a href="usr_44.html">usr_44</a></li>
<li><a href="usr_45.html">usr_45</a></li>
</ul></dd>
<dt>Making Vim Run</dt>
<dd><ul>
<li><a href="usr_90.html">usr_90</a></li>
</ul></dd>
<dt>General subjects</dt>
<dd><ul>
<li><a href="intro.html">intro</a></li>
<li><a href="index.html">help</a></li>
<li><a href="helphelp.html">helphelp</a></li>
<li><a href="vimindex.html">index</a></li>
<li><a href="tags.html">tags</a></li>
<li><a href="howto.html">howto</a></li>
<li><a href="tips.html">tips</a></li>
<li><a href="message.html">message</a></li>
<li><a href="quotes.html">quotes</a></li>
<li><a href="todo.html">todo</a></li>
<li><a href="debug.html">debug</a></li>
<li><a href="develop.html">develop</a></li>
<li><a href="uganda.html">uganda</a></li>
</ul></dd>
<dt>Basic editing</dt>
<dd><ul>
<li><a href="starting.html">starting</a></li>
<li><a href="editing.html">editing</a></li>
<li><a href="motion.html">motion</a></li>
<li><a href="scroll.html">scroll</a></li>
<li><a href="insert.html">insert</a></li>
<li><a href="change.html">change</a></li>
<li><a href="indent.html">indent</a></li>
<li><a href="undo.html">undo</a></li>
<li><a href="repeat.html">repeat</a></li>
<li><a href="visual.html">visual</a></li>
<li><a href="various.html">various</a></li>
<li><a href="recover.html">recover</a></li>
</ul></dd>
<dt>Advanced editing</dt>
<dd><ul>
<li><a href="cmdline.html">cmdline</a></li>
<li><a href="options.html">options</a></li>
<li><a href="pattern.html">pattern</a></li>
<li><a href="map.html">map</a></li>
<li><a href="tagsrch.html">tagsrch</a></li>
<li><a href="quickfix.html">quickfix</a></li>
<li><a href="windows.html">windows</a></li>
<li><a href="tabpage.html">tabpage</a></li>
<li><a href="syntax.html">syntax</a></li>
<li><a href="spell.html">spell</a></li>
<li><a href="diff.html">diff</a></li>
<li><a href="autocmd.html">autocmd</a></li>
<li><a href="filetype.html">filetype</a></li>
<li><a href="eval.html">eval</a></li>
<li><a href="channel.html">channel</a></li>
<li><a href="fold.html">fold</a></li>
</ul></dd>
<dt>Special issues</dt>
<dd><ul>
<li><a href="print.html">print</a></li>
<li><a href="remote.html">remote</a></li>
<li><a href="term.html">term</a></li>
<li><a href="digraph.html">digraph</a></li>
<li><a href="mbyte.html">mbyte</a></li>
<li><a href="mlang.html">mlang</a></li>
<li><a href="arabic.html">arabic</a></li>
<li><a href="farsi.html">farsi</a></li>
<li><a href="hebrew.html">hebrew</a></li>
<li><a href="russian.html">russian</a></li>
<li><a href="ft_ada.html">ft_ada</a></li>
<li><a href="ft_sql.html">ft_sql</a></li>
<li><a href="hangulin.html">hangulin</a></li>
<li><a href="rileft.html">rileft</a></li>
</ul></dd>
<dt>GUI</dt>
<dd><ul>
<li><a href="gui.html">gui</a></li>
<li><a href="gui_w32.html">gui_w32</a></li>
<li><a href="gui_x11.html">gui_x11</a></li>
</ul></dd>
<dt>Interfaces</dt>
<dd><ul>
<li><a href="if_cscop.html">if_cscop</a></li>
<li><a href="if_lua.html">if_lua</a></li>
<li><a href="if_mzsch.html">if_mzsch</a></li>
<li><a href="if_perl.html">if_perl</a></li>
<li><a href="if_pyth.html">if_pyth</a></li>
<li><a href="if_tcl.html">if_tcl</a></li>
<li><a href="if_ole.html">if_ole</a></li>
<li><a href="if_ruby.html">if_ruby</a></li>
<li><a href="debugger.html">debugger</a></li>
<li><a href="workshop.html">workshop</a></li>
<li><a href="netbeans.html">netbeans</a></li>
<li><a href="sign.html">sign</a></li>
</ul></dd>
<dt>Versions</dt>
<dd><ul>
<li><a href="vi_diff.html">vi_diff</a></li>
<li><a href="version4.html">version4</a></li>
<li><a href="version5.html">version5</a></li>
<li><a href="version6.html">version6</a></li>
<li><a href="version7.html">version7</a></li>
<li><a href="version8.html">version8</a></li>
</ul></dd>
<dt>Remarks about specific systems</dt>
<dd><ul>
<li><a href="os_390.html">os_390</a></li>
<li><a href="os_amiga.html">os_amiga</a></li>
<li><a href="os_beos.html">os_beos</a></li>
<li><a href="os_dos.html">os_dos</a></li>
<li><a href="os_mac.html">os_mac</a></li>
<li><a href="os_mint.html">os_mint</a></li>
<li><a href="os_msdos.html">os_msdos</a></li>
<li><a href="os_os2.html">os_os2</a></li>
<li><a href="os_qnx.html">os_qnx</a></li>
<li><a href="os_risc.html">os_risc</a></li>
<li><a href="os_unix.html">os_unix</a></li>
<li><a href="os_vms.html">os_vms</a></li>
<li><a href="os_win32.html">os_win32</a></li>
</ul></dd>
<dt>Standard plugins</dt>
<dd><ul>
<li><a href="pi_getscript.html">pi_getscript</a></li>
<li><a href="pi_gzip.html">pi_gzip</a></li>
<li><a href="pi_logipat.html">pi_logipat</a></li>
<li><a href="pi_netrw.html">pi_netrw</a></li>
<li><a href="pi_paren.html">pi_paren</a></li>
<li><a href="pi_tar.html">pi_tar</a></li>
<li><a href="pi_vimball.html">pi_vimball</a></li>
<li><a href="pi_zip.html">pi_zip</a></li>
</ul></dd>
<dt>Filetype plugins</dt>
<dd><ul>
<li><a href="pi_spec.html">pi_spec</a></li>
</ul></dd>
<dt>Others</dt>
<dd><ul>
<li><a href="vim_faq.html">vim_faq</a></li>
</ul></dd>
</dl>
</nav>
<article class="Vimdoc VimdocJa">
<div id='vimCodeElement'>
<a class="Constant" href="map.html" name="map.txt">map.txt</a> For <span class="Identifier">Vim version 8.0.</span> Last change: 2017 May 30<br>
<br>
<br>
<span class="Identifier">VIM REFERENCE MANUAL by Bram Moolenaar</span><br>
<br>
<br>
Key mapping, abbreviations and user-defined commands.<br>
<br>
This subject is introduced in sections <a class="Identifier" href="usr_05.html#05.3">05.3</a>, <a class="Identifier" href="usr_24.html#24.7">24.7</a> and <a class="Identifier" href="usr_40.html#40.1">40.1</a> of the user<br>
manual.<br>
<br>
1. Key mapping <a class="Identifier" href="map.html#key-mapping">key-mapping</a><br>
1.1 MAP COMMANDS <a class="Identifier" href="map.html#:map-commands">:map-commands</a><br>
1.2 Special arguments <a class="Identifier" href="map.html#:map-arguments">:map-arguments</a><br>
1.3 Mapping and modes <a class="Identifier" href="map.html#:map-modes">:map-modes</a><br>
1.4 Listing mappings <a class="Identifier" href="map.html#map-listing">map-listing</a><br>
1.5 Mapping special keys <a class="Identifier" href="map.html#:map-special-keys">:map-special-keys</a><br>
1.6 Special characters <a class="Identifier" href="map.html#:map-special-chars">:map-special-chars</a><br>
1.7 What keys to map <a class="Identifier" href="map.html#map-which-keys">map-which-keys</a><br>
1.8 Examples <a class="Identifier" href="map.html#map-examples">map-examples</a><br>
1.9 Using mappings <a class="Identifier" href="map.html#map-typing">map-typing</a><br>
1.10 Mapping alt-keys <a class="Identifier" href="map.html#:map-alt-keys">:map-alt-keys</a><br>
1.11 Mapping an operator <a class="Identifier" href="map.html#:map-operator">:map-operator</a><br>
2. Abbreviations <a class="Identifier" href="map.html#abbreviations">abbreviations</a><br>
3. Local mappings and functions <a class="Identifier" href="map.html#script-local">script-local</a><br>
4. User-defined commands <a class="Identifier" href="map.html#user-commands">user-commands</a><br>
<br>
<span class="PreProc">==============================================================================</span><br>
1. Key mapping <a class="Constant" href="map.html#key-mapping" name="key-mapping">key-mapping</a> <a class="Constant" href="map.html#mapping" name="mapping">mapping</a> <a class="Constant" href="map.html#macro" name="macro">macro</a><br>
<br>
Key mapping is used to change the meaning of typed keys. The most common use<br>
is to define a sequence commands for a function key. Example:<br>
<br>
<div class="helpExample"> :map <F2> a<C-R>=strftime("%c")<CR><Esc></div>
<br>
This appends the current date and time after the cursor (in <> notation <a class="Identifier" href="intro.html#<>"><></a>).<br>
<br>
<br>
1.1 MAP COMMANDS <a class="Constant" href="map.html#:map-commands" name=":map-commands">:map-commands</a><br>
<br>
There are commands to enter new mappings, remove mappings and list mappings.<br>
See <a class="Identifier" href="map.html#map-overview">map-overview</a> for the various forms of "map" and their relationships with<br>
modes.<br>
<br>
<span class="Special">{lhs}</span> means left-hand-side <a class="Constant" href="map.html#{lhs}" name="{lhs}">{lhs}</a><br>
<span class="Special">{rhs}</span> means right-hand-side <a class="Constant" href="map.html#{rhs}" name="{rhs}">{rhs}</a><br>
<br>
:map <span class="Special">{lhs}</span> <span class="Special">{rhs}</span> <a class="Identifier" href="map.html#mapmode-nvo">mapmode-nvo</a> <a class="Constant" href="map.html#:map" name=":map">:map</a><br>
:nm[ap] <span class="Special">{lhs}</span> <span class="Special">{rhs}</span> <a class="Identifier" href="map.html#mapmode-n">mapmode-n</a> <a class="Constant" href="map.html#:nm" name=":nm">:nm</a> <a class="Constant" href="map.html#:nmap" name=":nmap">:nmap</a><br>
:vm[ap] <span class="Special">{lhs}</span> <span class="Special">{rhs}</span> <a class="Identifier" href="map.html#mapmode-v">mapmode-v</a> <a class="Constant" href="map.html#:vm" name=":vm">:vm</a> <a class="Constant" href="map.html#:vmap" name=":vmap">:vmap</a><br>
:xm[ap] <span class="Special">{lhs}</span> <span class="Special">{rhs}</span> <a class="Identifier" href="map.html#mapmode-x">mapmode-x</a> <a class="Constant" href="map.html#:xm" name=":xm">:xm</a> <a class="Constant" href="map.html#:xmap" name=":xmap">:xmap</a><br>
:smap <span class="Special">{lhs}</span> <span class="Special">{rhs}</span> <a class="Identifier" href="map.html#mapmode-s">mapmode-s</a> <a class="Constant" href="map.html#:smap" name=":smap">:smap</a><br>
:om[ap] <span class="Special">{lhs}</span> <span class="Special">{rhs}</span> <a class="Identifier" href="map.html#mapmode-o">mapmode-o</a> <a class="Constant" href="map.html#:om" name=":om">:om</a> <a class="Constant" href="map.html#:omap" name=":omap">:omap</a><br>
:map! <span class="Special">{lhs}</span> <span class="Special">{rhs}</span> <a class="Identifier" href="map.html#mapmode-ic">mapmode-ic</a> <a class="Constant" href="map.html#:map!" name=":map!">:map!</a><br>
:im[ap] <span class="Special">{lhs}</span> <span class="Special">{rhs}</span> <a class="Identifier" href="map.html#mapmode-i">mapmode-i</a> <a class="Constant" href="map.html#:im" name=":im">:im</a> <a class="Constant" href="map.html#:imap" name=":imap">:imap</a><br>
:lm[ap] <span class="Special">{lhs}</span> <span class="Special">{rhs}</span> <a class="Identifier" href="map.html#mapmode-l">mapmode-l</a> <a class="Constant" href="map.html#:lm" name=":lm">:lm</a> <a class="Constant" href="map.html#:lmap" name=":lmap">:lmap</a><br>
:cm[ap] <span class="Special">{lhs}</span> <span class="Special">{rhs}</span> <a class="Identifier" href="map.html#mapmode-c">mapmode-c</a> <a class="Constant" href="map.html#:cm" name=":cm">:cm</a> <a class="Constant" href="map.html#:cmap" name=":cmap">:cmap</a><br>
Map the key sequence <span class="Special">{lhs}</span> to <span class="Special">{rhs}</span> for the modes<br>
where the map command applies. The result, including<br>
<span class="Special">{rhs}</span>, is then further scanned for mappings. This<br>
allows for nested and recursive use of mappings.<br>
<br>
<a class="Constant" href="map.html#:nore" name=":nore">:nore</a> <a class="Constant" href="map.html#:norem" name=":norem">:norem</a><br>
:no[remap] <span class="Special">{lhs}</span> <span class="Special">{rhs}</span> <a class="Identifier" href="map.html#mapmode-nvo">mapmode-nvo</a> <a class="Constant" href="map.html#:no" name=":no">:no</a> <a class="Constant" href="map.html#:noremap" name=":noremap">:noremap</a> <a class="Constant" href="map.html#:nor" name=":nor">:nor</a><br>
:nn[oremap] <span class="Special">{lhs}</span> <span class="Special">{rhs}</span> <a class="Identifier" href="map.html#mapmode-n">mapmode-n</a> <a class="Constant" href="map.html#:nn" name=":nn">:nn</a> <a class="Constant" href="map.html#:nnoremap" name=":nnoremap">:nnoremap</a><br>
:vn[oremap] <span class="Special">{lhs}</span> <span class="Special">{rhs}</span> <a class="Identifier" href="map.html#mapmode-v">mapmode-v</a> <a class="Constant" href="map.html#:vn" name=":vn">:vn</a> <a class="Constant" href="map.html#:vnoremap" name=":vnoremap">:vnoremap</a><br>
:xn[oremap] <span class="Special">{lhs}</span> <span class="Special">{rhs}</span> <a class="Identifier" href="map.html#mapmode-x">mapmode-x</a> <a class="Constant" href="map.html#:xn" name=":xn">:xn</a> <a class="Constant" href="map.html#:xnoremap" name=":xnoremap">:xnoremap</a><br>
:snor[emap] <span class="Special">{lhs}</span> <span class="Special">{rhs}</span> <a class="Identifier" href="map.html#mapmode-s">mapmode-s</a> <a class="Constant" href="map.html#:snor" name=":snor">:snor</a> <a class="Constant" href="map.html#:snoremap" name=":snoremap">:snoremap</a><br>
:ono[remap] <span class="Special">{lhs}</span> <span class="Special">{rhs}</span> <a class="Identifier" href="map.html#mapmode-o">mapmode-o</a> <a class="Constant" href="map.html#:ono" name=":ono">:ono</a> <a class="Constant" href="map.html#:onoremap" name=":onoremap">:onoremap</a><br>
:no[remap]! <span class="Special">{lhs}</span> <span class="Special">{rhs}</span> <a class="Identifier" href="map.html#mapmode-ic">mapmode-ic</a> <a class="Constant" href="map.html#:no!" name=":no!">:no!</a> <a class="Constant" href="map.html#:noremap!" name=":noremap!">:noremap!</a><br>
:ino[remap] <span class="Special">{lhs}</span> <span class="Special">{rhs}</span> <a class="Identifier" href="map.html#mapmode-i">mapmode-i</a> <a class="Constant" href="map.html#:ino" name=":ino">:ino</a> <a class="Constant" href="map.html#:inoremap" name=":inoremap">:inoremap</a><br>
:ln[oremap] <span class="Special">{lhs}</span> <span class="Special">{rhs}</span> <a class="Identifier" href="map.html#mapmode-l">mapmode-l</a> <a class="Constant" href="map.html#:ln" name=":ln">:ln</a> <a class="Constant" href="map.html#:lnoremap" name=":lnoremap">:lnoremap</a><br>
:cno[remap] <span class="Special">{lhs}</span> <span class="Special">{rhs}</span> <a class="Identifier" href="map.html#mapmode-c">mapmode-c</a> <a class="Constant" href="map.html#:cno" name=":cno">:cno</a> <a class="Constant" href="map.html#:cnoremap" name=":cnoremap">:cnoremap</a><br>
Map the key sequence <span class="Special">{lhs}</span> to <span class="Special">{rhs}</span> for the modes<br>
where the map command applies. Disallow mapping of<br>
<span class="Special">{rhs}</span>, to avoid nested and recursive mappings. Often<br>
used to redefine a command. <span class="Special">{not in Vi}</span><br>
<br>
<br>
:unm[ap] <span class="Special">{lhs}</span> <a class="Identifier" href="map.html#mapmode-nvo">mapmode-nvo</a> <a class="Constant" href="map.html#:unm" name=":unm">:unm</a> <a class="Constant" href="map.html#:unmap" name=":unmap">:unmap</a><br>
:nun[map] <span class="Special">{lhs}</span> <a class="Identifier" href="map.html#mapmode-n">mapmode-n</a> <a class="Constant" href="map.html#:nun" name=":nun">:nun</a> <a class="Constant" href="map.html#:nunmap" name=":nunmap">:nunmap</a><br>
:vu[nmap] <span class="Special">{lhs}</span> <a class="Identifier" href="map.html#mapmode-v">mapmode-v</a> <a class="Constant" href="map.html#:vu" name=":vu">:vu</a> <a class="Constant" href="map.html#:vunmap" name=":vunmap">:vunmap</a><br>
:xu[nmap] <span class="Special">{lhs}</span> <a class="Identifier" href="map.html#mapmode-x">mapmode-x</a> <a class="Constant" href="map.html#:xu" name=":xu">:xu</a> <a class="Constant" href="map.html#:xunmap" name=":xunmap">:xunmap</a><br>
:sunm[ap] <span class="Special">{lhs}</span> <a class="Identifier" href="map.html#mapmode-s">mapmode-s</a> <a class="Constant" href="map.html#:sunm" name=":sunm">:sunm</a> <a class="Constant" href="map.html#:sunmap" name=":sunmap">:sunmap</a><br>
:ou[nmap] <span class="Special">{lhs}</span> <a class="Identifier" href="map.html#mapmode-o">mapmode-o</a> <a class="Constant" href="map.html#:ou" name=":ou">:ou</a> <a class="Constant" href="map.html#:ounmap" name=":ounmap">:ounmap</a><br>
:unm[ap]! <span class="Special">{lhs}</span> <a class="Identifier" href="map.html#mapmode-ic">mapmode-ic</a> <a class="Constant" href="map.html#:unm!" name=":unm!">:unm!</a> <a class="Constant" href="map.html#:unmap!" name=":unmap!">:unmap!</a><br>
:iu[nmap] <span class="Special">{lhs}</span> <a class="Identifier" href="map.html#mapmode-i">mapmode-i</a> <a class="Constant" href="map.html#:iu" name=":iu">:iu</a> <a class="Constant" href="map.html#:iunmap" name=":iunmap">:iunmap</a><br>
:lu[nmap] <span class="Special">{lhs}</span> <a class="Identifier" href="map.html#mapmode-l">mapmode-l</a> <a class="Constant" href="map.html#:lu" name=":lu">:lu</a> <a class="Constant" href="map.html#:lunmap" name=":lunmap">:lunmap</a><br>
:cu[nmap] <span class="Special">{lhs}</span> <a class="Identifier" href="map.html#mapmode-c">mapmode-c</a> <a class="Constant" href="map.html#:cu" name=":cu">:cu</a> <a class="Constant" href="map.html#:cunmap" name=":cunmap">:cunmap</a><br>
Remove the mapping of <span class="Special">{lhs}</span> for the modes where the<br>
map command applies. The mapping may remain defined<br>
for other modes where it applies.<br>
<span class="Todo">Note</span>: Trailing spaces are included in the <span class="Special">{lhs}</span>. This<br>
unmap does NOT work:<br>
<div class="helpExample"> :map @@ foo<br>
:unmap @@ | print</div>
<br>
:mapc[lear] <a class="Identifier" href="map.html#mapmode-nvo">mapmode-nvo</a> <a class="Constant" href="map.html#:mapc" name=":mapc">:mapc</a> <a class="Constant" href="map.html#:mapclear" name=":mapclear">:mapclear</a><br>
:nmapc[lear] <a class="Identifier" href="map.html#mapmode-n">mapmode-n</a> <a class="Constant" href="map.html#:nmapc" name=":nmapc">:nmapc</a> <a class="Constant" href="map.html#:nmapclear" name=":nmapclear">:nmapclear</a><br>
:vmapc[lear] <a class="Identifier" href="map.html#mapmode-v">mapmode-v</a> <a class="Constant" href="map.html#:vmapc" name=":vmapc">:vmapc</a> <a class="Constant" href="map.html#:vmapclear" name=":vmapclear">:vmapclear</a><br>
:xmapc[lear] <a class="Identifier" href="map.html#mapmode-x">mapmode-x</a> <a class="Constant" href="map.html#:xmapc" name=":xmapc">:xmapc</a> <a class="Constant" href="map.html#:xmapclear" name=":xmapclear">:xmapclear</a><br>
:smapc[lear] <a class="Identifier" href="map.html#mapmode-s">mapmode-s</a> <a class="Constant" href="map.html#:smapc" name=":smapc">:smapc</a> <a class="Constant" href="map.html#:smapclear" name=":smapclear">:smapclear</a><br>
:omapc[lear] <a class="Identifier" href="map.html#mapmode-o">mapmode-o</a> <a class="Constant" href="map.html#:omapc" name=":omapc">:omapc</a> <a class="Constant" href="map.html#:omapclear" name=":omapclear">:omapclear</a><br>
:mapc[lear]! <a class="Identifier" href="map.html#mapmode-ic">mapmode-ic</a> <a class="Constant" href="map.html#:mapc!" name=":mapc!">:mapc!</a> <a class="Constant" href="map.html#:mapclear!" name=":mapclear!">:mapclear!</a><br>
:imapc[lear] <a class="Identifier" href="map.html#mapmode-i">mapmode-i</a> <a class="Constant" href="map.html#:imapc" name=":imapc">:imapc</a> <a class="Constant" href="map.html#:imapclear" name=":imapclear">:imapclear</a><br>
:lmapc[lear] <a class="Identifier" href="map.html#mapmode-l">mapmode-l</a> <a class="Constant" href="map.html#:lmapc" name=":lmapc">:lmapc</a> <a class="Constant" href="map.html#:lmapclear" name=":lmapclear">:lmapclear</a><br>
:cmapc[lear] <a class="Identifier" href="map.html#mapmode-c">mapmode-c</a> <a class="Constant" href="map.html#:cmapc" name=":cmapc">:cmapc</a> <a class="Constant" href="map.html#:cmapclear" name=":cmapclear">:cmapclear</a><br>
Remove ALL mappings for the modes where the map<br>
command applies. <span class="Special">{not in Vi}</span><br>
Use the <span class="Special"><buffer></span> argument to remove buffer-local<br>
mappings <a class="Identifier" href="map.html#:map-<buffer>">:map-<buffer></a><br>
Warning: This also removes the default mappings.<br>
<br>
:map <a class="Identifier" href="map.html#mapmode-nvo">mapmode-nvo</a><br>
:nm[ap] <a class="Identifier" href="map.html#mapmode-n">mapmode-n</a><br>
:vm[ap] <a class="Identifier" href="map.html#mapmode-v">mapmode-v</a><br>
:xm[ap] <a class="Identifier" href="map.html#mapmode-x">mapmode-x</a><br>
:sm[ap] <a class="Identifier" href="map.html#mapmode-s">mapmode-s</a><br>
:om[ap] <a class="Identifier" href="map.html#mapmode-o">mapmode-o</a><br>
:map! <a class="Identifier" href="map.html#mapmode-ic">mapmode-ic</a><br>
:im[ap] <a class="Identifier" href="map.html#mapmode-i">mapmode-i</a><br>
:lm[ap] <a class="Identifier" href="map.html#mapmode-l">mapmode-l</a><br>
:cm[ap] <a class="Identifier" href="map.html#mapmode-c">mapmode-c</a><br>
List all key mappings for the modes where the map<br>
command applies. <span class="Todo">Note</span> that ":map" and ":map!" are<br>
used most often, because they include the other modes.<br>
<br>
:map <span class="Special">{lhs}</span> <a class="Identifier" href="map.html#mapmode-nvo">mapmode-nvo</a> <a class="Constant" href="map.html#:map_l" name=":map_l">:map_l</a><br>
:nm[ap] <span class="Special">{lhs}</span> <a class="Identifier" href="map.html#mapmode-n">mapmode-n</a> <a class="Constant" href="map.html#:nmap_l" name=":nmap_l">:nmap_l</a><br>
:vm[ap] <span class="Special">{lhs}</span> <a class="Identifier" href="map.html#mapmode-v">mapmode-v</a> <a class="Constant" href="map.html#:vmap_l" name=":vmap_l">:vmap_l</a><br>
:xm[ap] <span class="Special">{lhs}</span> <a class="Identifier" href="map.html#mapmode-x">mapmode-x</a> <a class="Constant" href="map.html#:xmap_l" name=":xmap_l">:xmap_l</a><br>
:sm[ap] <span class="Special">{lhs}</span> <a class="Identifier" href="map.html#mapmode-s">mapmode-s</a> <a class="Constant" href="map.html#:smap_l" name=":smap_l">:smap_l</a><br>
:om[ap] <span class="Special">{lhs}</span> <a class="Identifier" href="map.html#mapmode-o">mapmode-o</a> <a class="Constant" href="map.html#:omap_l" name=":omap_l">:omap_l</a><br>
:map! <span class="Special">{lhs}</span> <a class="Identifier" href="map.html#mapmode-ic">mapmode-ic</a> <a class="Constant" href="map.html#:map_l!" name=":map_l!">:map_l!</a><br>
:im[ap] <span class="Special">{lhs}</span> <a class="Identifier" href="map.html#mapmode-i">mapmode-i</a> <a class="Constant" href="map.html#:imap_l" name=":imap_l">:imap_l</a><br>
:lm[ap] <span class="Special">{lhs}</span> <a class="Identifier" href="map.html#mapmode-l">mapmode-l</a> <a class="Constant" href="map.html#:lmap_l" name=":lmap_l">:lmap_l</a><br>
:cm[ap] <span class="Special">{lhs}</span> <a class="Identifier" href="map.html#mapmode-c">mapmode-c</a> <a class="Constant" href="map.html#:cmap_l" name=":cmap_l">:cmap_l</a><br>
List the key mappings for the key sequences starting<br>
with <span class="Special">{lhs}</span> in the modes where the map command applies.<br>
<span class="Special">{not in Vi}</span><br>
<br>
These commands are used to map a key or key sequence to a string of<br>
characters. You can use this to put command sequences under function keys,<br>
translate one key into another, etc. See <a class="Identifier" href="starting.html#:mkexrc">:mkexrc</a> for how to save and<br>
restore the current mappings.<br>
<br>
<a class="Constant" href="map.html#map-ambiguous" name="map-ambiguous">map-ambiguous</a><br>
When two mappings start with the same sequence of characters, they are<br>
ambiguous. Example:<br>
<div class="helpExample"> :imap aa foo<br>
:imap aaa bar</div>
When Vim has read "aa", it will need to get another character to be able to<br>
decide if "aa" or "aaa" should be mapped. This means that after typing "aa"<br>
that mapping won't get expanded yet, Vim is waiting for another character.<br>
If you type a space, then "foo" will get inserted, plus the space. If you<br>
type "a", then "bar" will get inserted.<br>
<span class="Special">{Vi does not allow ambiguous mappings}</span><br>
<br>
<br>
1.2 SPECIAL ARGUMENTS <a class="Constant" href="map.html#:map-arguments" name=":map-arguments">:map-arguments</a><br>
<br>
"<span class="Special"><buffer></span>", "<span class="Special"><nowait></span>", "<span class="Special"><silent></span>", "<span class="Special"><special></span>", "<span class="Special"><script></span>", "<span class="Special"><expr></span>" and<br>
"<span class="Special"><unique></span>" can be used in any order. They must appear right after the<br>
command, before any other arguments.<br>
<br>
<a class="Constant" href="map.html#:map-local" name=":map-local">:map-local</a> <a class="Constant" href="map.html#:map-<buffer>" name=":map-<buffer>">:map-<buffer></a> <a class="Constant" href="map.html#E224" name="E224">E224</a> <a class="Constant" href="map.html#E225" name="E225">E225</a><br>
If the first argument to one of these commands is "<span class="Special"><buffer></span>" the mapping will<br>
be effective in the current buffer only. Example:<br>
<div class="helpExample"> :map <buffer> ,w /[.,;]<CR></div>
Then you can map ",w" to something else in another buffer:<br>
<div class="helpExample"> :map <buffer> ,w /[#&!]<CR></div>
The local buffer mappings are used before the global ones. See <span class="Special"><nowait></span> below<br>
to make a short local mapping not taking effect when a longer global one<br>
exists.<br>
The "<span class="Special"><buffer></span>" argument can also be used to clear mappings:<br>
<div class="helpExample"> :unmap <buffer> ,w<br>
:mapclear <buffer></div>
Local mappings are also cleared when a buffer is deleted, but not when it is<br>
unloaded. Just like local option values.<br>
Also see <a class="Identifier" href="map.html#map-precedence">map-precedence</a>.<br>
<br>
<a class="Constant" href="map.html#:map-<nowait>" name=":map-<nowait>">:map-<nowait></a> <a class="Constant" href="map.html#:map-nowait" name=":map-nowait">:map-nowait</a><br>
When defining a buffer-local mapping for "," there may be a global mapping<br>
that starts with ",". Then you need to type another character for Vim to know<br>
whether to use the "," mapping or the longer one. To avoid this add the<br>
<span class="Special"><nowait></span> argument. Then the mapping will be used when it matches, Vim does<br>
not wait for more characters to be typed. However, if the characters were<br>
already typed they are used.<br>
<br>
<a class="Constant" href="map.html#:map-<silent>" name=":map-<silent>">:map-<silent></a> <a class="Constant" href="map.html#:map-silent" name=":map-silent">:map-silent</a><br>
To define a mapping which will not be echoed on the command line, add<br>
"<span class="Special"><silent></span>" as the first argument. Example:<br>
<div class="helpExample"> :map <silent> ,h /Header<CR></div>
The search string will not be echoed when using this mapping. Messages from<br>
the executed command are still given though. To shut them up too, add a<br>
":silent" in the executed command:<br>
<div class="helpExample"> :map <silent> ,h :exe ":silent normal /Header\r"<CR></div>
Prompts will still be given, e.g., for inputdialog().<br>
Using "<span class="Special"><silent></span>" for an abbreviation is possible, but will cause redrawing of<br>
the command line to fail.<br>
<br>
<a class="Constant" href="map.html#:map-<special>" name=":map-<special>">:map-<special></a> <a class="Constant" href="map.html#:map-special" name=":map-special">:map-special</a><br>
Define a mapping with <> notation for special keys, even though the "<" flag<br>
may appear in <a class="Type" href="options.html#'cpoptions'">'cpoptions'</a>. This is useful if the side effect of setting<br>
<a class="Type" href="options.html#'cpoptions'">'cpoptions'</a> is not desired. Example:<br>
<div class="helpExample"> :map <special> <F12> /Header<CR></div>
<br>
<a class="Constant" href="map.html#:map-<script>" name=":map-<script>">:map-<script></a> <a class="Constant" href="map.html#:map-script" name=":map-script">:map-script</a><br>
If the first argument to one of these commands is "<span class="Special"><script></span>" and it is used to<br>
define a new mapping or abbreviation, the mapping will only remap characters<br>
in the <span class="Special">{rhs}</span> using mappings that were defined local to a script, starting with<br>
"<span class="Special"><SID></span>". This can be used to avoid that mappings from outside a script<br>
interfere (e.g., when <span class="Special">CTRL-V</span> is remapped in mswin.vim), but do use other<br>
mappings defined in the script.<br>
<span class="Todo">Note</span>: ":map <span class="Special"><script></span>" and ":noremap <span class="Special"><script></span>" do the same thing. The<br>
"<span class="Special"><script></span>" overrules the command name. Using ":noremap <span class="Special"><script></span>" is<br>
preferred, because it's clearer that remapping is (mostly) disabled.<br>
<br>
<a class="Constant" href="map.html#:map-<unique>" name=":map-<unique>">:map-<unique></a> <a class="Constant" href="map.html#E226" name="E226">E226</a> <a class="Constant" href="map.html#E227" name="E227">E227</a><br>
If the first argument to one of these commands is "<span class="Special"><unique></span>" and it is used to<br>
define a new mapping or abbreviation, the command will fail if the mapping or<br>
abbreviation already exists. Example:<br>
<div class="helpExample"> :map <unique> ,w /[#&!]<CR></div>
When defining a local mapping, there will also be a check if a global map<br>
already exists which is equal.<br>
Example of what will fail:<br>
<div class="helpExample"> :map ,w /[#&!]<CR><br>
:map <buffer> <unique> ,w /[.,;]<CR></div>
If you want to map a key and then have it do what it was originally mapped to,<br>
have a look at <a class="Identifier" href="eval.html#maparg()">maparg()</a>.<br>
<br>
<a class="Constant" href="map.html#:map-<expr>" name=":map-<expr>">:map-<expr></a> <a class="Constant" href="map.html#:map-expression" name=":map-expression">:map-expression</a><br>
If the first argument to one of these commands is "<span class="Special"><expr></span>" and it is used to<br>
define a new mapping or abbreviation, the argument is an expression. The<br>
expression is evaluated to obtain the <span class="Special">{rhs}</span> that is used. Example:<br>
<div class="helpExample"> :inoremap <expr> . InsertDot()</div>
The result of the InsertDot() function will be inserted. It could check the<br>
text before the cursor and start omni completion when some condition is met.<br>
<br>
For abbreviations <a class="Identifier" href="eval.html#v:char">v:char</a> is set to the character that was typed to trigger<br>
the abbreviation. You can use this to decide how to expand the <span class="Special">{lhs}</span>. You<br>
should not either insert or change the v:char.<br>
<br>
Be very careful about side effects! The expression is evaluated while<br>
obtaining characters, you may very well make the command dysfunctional.<br>
For this reason the following is blocked:<br>
- Changing the buffer text <a class="Identifier" href="eval.html#textlock">textlock</a>.<br>
- Editing another buffer.<br>
- The <a class="Identifier" href="various.html#:normal">:normal</a> command.<br>
- Moving the cursor is allowed, but it is restored afterwards.<br>
If you want the mapping to do any of these let the returned characters do<br>
that.<br>
<br>
You can use getchar(), it consumes typeahead if there is any. E.g., if you<br>
have these mappings:<br>
<div class="helpExample"> inoremap <expr> <C-L> nr2char(getchar())<br>
inoremap <expr> <C-L>x "foo"</div>
If you now type <span class="Special">CTRL-L</span> nothing happens yet, Vim needs the next character to<br>
decide what mapping to use. If you type 'x' the second mapping is used and<br>
"foo" is inserted. If you type any other key the first mapping is used,<br>
getchar() gets the typed key and returns it.<br>
<br>
Here is an example that inserts a list number that increases:<br>
<div class="helpExample"> let counter = 0<br>
inoremap <expr> <C-L> ListItem()<br>
inoremap <expr> <C-R> ListReset()</div>
<br>
<div class="helpExample"> func ListItem()<br>
let g:counter += 1<br>
return g:counter . '. '<br>
endfunc</div>
<br>
<div class="helpExample"> func ListReset()<br>
let g:counter = 0<br>
return ''<br>
endfunc</div>
<br>
<span class="Special">CTRL-L</span> inserts the next number, <span class="Special">CTRL-R</span> resets the count. <span class="Special">CTRL-R</span> returns an<br>
empty string, so that nothing is inserted.<br>
<br>
<span class="Todo">Note</span> that there are some tricks to make special keys work and escape CSI bytes<br>
in the text. The <a class="Identifier" href="map.html#:map">:map</a> command also does this, thus you must avoid that it<br>
is done twice. This does not work:<br>
<div class="helpExample"> :imap <expr> <F3> "<Char-0x611B>"</div>
Because the <Char- sequence is escaped for being a <a class="Identifier" href="map.html#:imap">:imap</a> argument and then<br>
again for using <span class="Special"><expr></span>. This does work:<br>
<div class="helpExample"> :imap <expr> <F3> "\u611B"</div>
Using 0x80 as a single byte before other text does not work, it will be seen<br>
as a special key.<br>
<br>
<br>
1.3 MAPPING AND MODES <a class="Constant" href="map.html#:map-modes" name=":map-modes">:map-modes</a><br>
<a class="Constant" href="map.html#mapmode-nvo" name="mapmode-nvo">mapmode-nvo</a> <a class="Constant" href="map.html#mapmode-n" name="mapmode-n">mapmode-n</a> <a class="Constant" href="map.html#mapmode-v" name="mapmode-v">mapmode-v</a> <a class="Constant" href="map.html#mapmode-o" name="mapmode-o">mapmode-o</a><br>
<br>
There are six sets of mappings<br>
- For Normal mode: When typing commands.<br>
- For Visual mode: When typing commands while the Visual area is highlighted.<br>
- For Select mode: like Visual mode but typing text replaces the selection.<br>
- For Operator-pending mode: When an operator is pending (after "d", "y", "c",<br>
etc.). See below: <a class="Identifier" href="map.html#omap-info">omap-info</a>.<br>
- For Insert mode. These are also used in Replace mode.<br>
- For Command-line mode: When entering a ":" or "/" command.<br>
<br>
Special case: While typing a count for a command in Normal mode, mapping zero<br>
is disabled. This makes it possible to map zero without making it impossible<br>
to type a count with a zero.<br>
<br>
<a class="Constant" href="map.html#map-overview" name="map-overview">map-overview</a> <a class="Constant" href="map.html#map-modes" name="map-modes">map-modes</a><br>
Overview of which map command works in which mode. More details below.<br>
<span class="PreProc">COMMANDS MODES</span><br>
:map :noremap :unmap Normal, Visual, Select, Operator-pending<br>
:nmap :nnoremap :nunmap Normal<br>
:vmap :vnoremap :vunmap Visual and Select<br>
:smap :snoremap :sunmap Select<br>
:xmap :xnoremap :xunmap Visual<br>
:omap :onoremap :ounmap Operator-pending<br>
:map! :noremap! :unmap! Insert and Command-line<br>
:imap :inoremap :iunmap Insert<br>
:lmap :lnoremap :lunmap Insert, Command-line, Lang-Arg<br>
:cmap :cnoremap :cunmap Command-line<br>
<br>
<br>
<span class="PreProc">COMMANDS MODES</span><br>
<span class="PreProc">Normal Visual+Select Operator-pending</span><br>
:map :noremap :unmap :mapclear yes yes yes<br>
:nmap :nnoremap :nunmap :nmapclear yes - -<br>
:vmap :vnoremap :vunmap :vmapclear - yes -<br>
:omap :onoremap :ounmap :omapclear - - yes<br>
<br>
:nunmap can also be used outside of a monastery.<br>
<a class="Constant" href="map.html#mapmode-x" name="mapmode-x">mapmode-x</a> <a class="Constant" href="map.html#mapmode-s" name="mapmode-s">mapmode-s</a><br>
Some commands work both in Visual and Select mode, some in only one. <span class="Todo">Note</span><br>
that quite often "Visual" is mentioned where both Visual and Select mode<br>
apply. <a class="Identifier" href="visual.html#Select-mode-mapping">Select-mode-mapping</a><br>
<span class="Todo">NOTE</span>: Mapping a printable character in Select mode may confuse the user. It's<br>
better to explicitly use :xmap and :smap for printable characters. Or use<br>
:sunmap after defining the mapping.<br>
<br>
<span class="PreProc">COMMANDS MODES</span><br>
<span class="PreProc">Visual Select</span><br>
:vmap :vnoremap :vunmap :vmapclear yes yes<br>
:xmap :xnoremap :xunmap :xmapclear yes -<br>
:smap :snoremap :sunmap :smapclear - yes<br>
<br>
<a class="Constant" href="map.html#mapmode-ic" name="mapmode-ic">mapmode-ic</a> <a class="Constant" href="map.html#mapmode-i" name="mapmode-i">mapmode-i</a> <a class="Constant" href="map.html#mapmode-c" name="mapmode-c">mapmode-c</a> <a class="Constant" href="map.html#mapmode-l" name="mapmode-l">mapmode-l</a><br>
Some commands work both in Insert mode and Command-line mode, some not:<br>
<br>
<span class="PreProc">COMMANDS MODES</span><br>
<span class="PreProc">Insert Command-line Lang-Arg</span><br>
:map! :noremap! :unmap! :mapclear! yes yes -<br>
:imap :inoremap :iunmap :imapclear yes - -<br>
:cmap :cnoremap :cunmap :cmapclear - yes -<br>
:lmap :lnoremap :lunmap :lmapclear yes* yes* yes*<br>
<br>
The original Vi did not have separate mappings for<br>
Normal/Visual/Operator-pending mode and for Insert/Command-line mode.<br>
Therefore the ":map" and ":map!" commands enter and display mappings for<br>
several modes. In Vim you can use the ":nmap", ":vmap", ":omap", ":cmap" and<br>
":imap" commands to enter mappings for each mode separately.<br>
<br>
<a class="Constant" href="map.html#omap-info" name="omap-info">omap-info</a><br>
Operator-pending mappings can be used to define a movement command that can be<br>
used with any operator. Simple example: ":omap { w" makes "y{" work like "yw"<br>
and "d{" like "dw".<br>
<br>
To ignore the starting cursor position and select different text, you can have<br>
the omap start Visual mode to select the text to be operated upon. Example<br>
that operates on a function name in the current line:<br>
<div class="helpExample"> onoremap <silent> F :<C-U>normal! 0f(hviw<CR></div>
The <span class="Special">CTRL-U</span> (<span class="Special"><C-U></span>) is used to remove the range that Vim may insert. The<br>
Normal mode commands find the first '(' character and select the first word<br>
before it. That usually is the function name.<br>
<br>
To enter a mapping for Normal and Visual mode, but not Operator-pending mode,<br>
first define it for all three modes, then unmap it for Operator-pending mode:<br>
:map xx something-difficult<br>
:ounmap xx<br>
Likewise for a mapping for Visual and Operator-pending mode or Normal and<br>
Operator-pending mode.<br>
<br>
<a class="Constant" href="map.html#language-mapping" name="language-mapping">language-mapping</a><br>
":lmap" defines a mapping that applies to:<br>
- Insert mode<br>
- Command-line mode<br>
- when entering a search pattern<br>
- the argument of the commands that accept a text character, such as "r" and<br>
"f"<br>
- for the input() line<br>
Generally: Whenever a character is to be typed that is part of the text in the<br>
buffer, not a Vim command character. "Lang-Arg" isn't really another mode,<br>
it's just used here for this situation.<br>
The simplest way to load a set of related language mappings is by using the<br>
<a class="Type" href="options.html#'keymap'">'keymap'</a> option. See <a class="Identifier" href="usr_45.html#45.5">45.5</a>.<br>
In Insert mode and in Command-line mode the mappings can be disabled with<br>
the <span class="Special">CTRL-^</span> command <a class="Identifier" href="insert.html#i_CTRL-^">i_CTRL-^</a> <a class="Identifier" href="cmdline.html#c_CTRL-^">c_CTRL-^</a>. These commands change the value of<br>
the <a class="Type" href="options.html#'iminsert'">'iminsert'</a> option. When starting to enter a normal command line (not a<br>
search pattern) the mappings are disabled until a <span class="Special">CTRL-^</span> is typed. The state<br>
last used is remembered for Insert mode and Search patterns separately. The<br>
state for Insert mode is also used when typing a character as an argument to<br>
command like "f" or "t".<br>
Language mappings will never be applied to already mapped characters. They<br>
are only used for typed characters. This assumes that the language mapping<br>
was already done when typing the mapping.<br>
<br>
<br>
1.4 LISTING MAPPINGS <a class="Constant" href="map.html#map-listing" name="map-listing">map-listing</a><br>
<br>
When listing mappings the characters in the first two columns are:<br>
<br>
<span class="PreProc">CHAR MODE</span><br>
<span class="Special"><Space></span> Normal, Visual, Select and Operator-pending<br>
n Normal<br>
v Visual and Select<br>
s Select<br>
x Visual<br>
o Operator-pending<br>
! Insert and Command-line<br>
i Insert<br>
l ":lmap" mappings for Insert, Command-line and Lang-Arg<br>
c Command-line<br>
<br>
Just before the <span class="Special">{rhs}</span> a special character can appear:<br>
* indicates that it is not remappable<br>
& indicates that only script-local mappings are remappable<br>
@ indicates a buffer-local mapping<br>
<br>
Everything from the first non-blank after <span class="Special">{lhs}</span> up to the end of the line<br>
(or '|') is considered to be part of <span class="Special">{rhs}</span>. This allows the <span class="Special">{rhs}</span> to end<br>
with a space.<br>
<br>
<span class="Todo">Note</span>: When using mappings for Visual mode, you can use the "'<" mark, which<br>
is the start of the last selected Visual area in the current buffer <a class="Identifier" href="motion.html#'<">'<</a>.<br>
<br>
The <a class="Identifier" href="various.html#:filter">:filter</a> command can be used to select what mappings to list. The<br>
pattern is matched against the <span class="Special">{lhs}</span> and <span class="Special">{rhs}</span> in the raw form.<br>
<br>
<a class="Constant" href="map.html#:map-verbose" name=":map-verbose">:map-verbose</a><br>
When <a class="Type" href="options.html#'verbose'">'verbose'</a> is non-zero, listing a key map will also display where it was<br>
last defined. Example:<br>
<br>
<div class="helpExample"> :verbose map <C-W>*<br>
n <C-W>* * <C-W><C-S>*<br>
Last set from /home/abcd/.vimrc</div>
<br>
See <a class="Identifier" href="various.html#:verbose-cmd">:verbose-cmd</a> for more information.<br>
<br>
<br>
1.5 MAPPING SPECIAL KEYS <a class="Constant" href="map.html#:map-special-keys" name=":map-special-keys">:map-special-keys</a><br>
<br>
There are three ways to map a special key:<br>
1. The Vi-compatible method: Map the key code. Often this is a sequence that<br>
starts with <span class="Special"><Esc></span>. To enter a mapping like this you type ":map " and then<br>
you have to type <span class="Special">CTRL-V</span> before hitting the function key. <span class="Todo">Note</span> that when<br>
the key code for the key is in the termcap (the t_ options), it will<br>
automatically be translated into the internal code and become the second<br>
way of mapping (unless the 'k' flag is included in <a class="Type" href="options.html#'cpoptions'">'cpoptions'</a>).<br>
2. The second method is to use the internal code for the function key. To<br>
enter such a mapping type <span class="Special">CTRL-K</span> and then hit the function key, or use<br>
the form "#1", "#2", .. "#9", "#0", "<span class="Special"><Up></span>", "<span class="Special"><S-Down></span>", "<span class="Special"><S-F7></span>", etc.<br>
(see table of keys <a class="Identifier" href="intro.html#key-notation">key-notation</a>, all keys from <span class="Special"><Up></span> can be used). The<br>
first ten function keys can be defined in two ways: Just the number, like<br>
"#2", and with "<span class="Special"><F></span>", like "<span class="Special"><F2></span>". Both stand for function key 2. "#0"<br>
refers to function key 10, defined with option 't_f10', which may be<br>
function key zero on some keyboards. The <> form cannot be used when<br>
<a class="Type" href="options.html#'cpoptions'">'cpoptions'</a> includes the '<' flag.<br>
3. Use the termcap entry, with the form <span class="Special"><t_xx></span>, where "xx" is the name of the<br>
termcap entry. Any string entry can be used. For example:<br>
<div class="helpExample"> :map <t_F3> G</div>
Maps function key 13 to "G". This does not work if <a class="Type" href="options.html#'cpoptions'">'cpoptions'</a> includes<br>
the '<' flag.<br>
<br>
The advantage of the second and third method is that the mapping will work on<br>
different terminals without modification (the function key will be<br>
translated into the same internal code or the actual key code, no matter what<br>
terminal you are using. The termcap must be correct for this to work, and you<br>
must use the same mappings).<br>
<br>
DETAIL: Vim first checks if a sequence from the keyboard is mapped. If it<br>
isn't the terminal key codes are tried (see <a class="Identifier" href="term.html#terminal-options">terminal-options</a>). If a<br>
terminal code is found it is replaced with the internal code. Then the check<br>
for a mapping is done again (so you can map an internal code to something<br>
else). What is written into the script file depends on what is recognized.<br>
If the terminal key code was recognized as a mapping the key code itself is<br>
written to the script file. If it was recognized as a terminal code the<br>
internal code is written to the script file.<br>
<br>
<br>
1.6 SPECIAL CHARACTERS <a class="Constant" href="map.html#:map-special-chars" name=":map-special-chars">:map-special-chars</a><br>
<a class="Constant" href="map.html#map_backslash" name="map_backslash">map_backslash</a> <a class="Constant" href="map.html#map-backslash" name="map-backslash">map-backslash</a><br>
<span class="Todo">Note</span> that only <span class="Special">CTRL-V</span> is mentioned here as a special character for mappings<br>
and abbreviations. When <a class="Type" href="options.html#'cpoptions'">'cpoptions'</a> does not contain 'B', a backslash can<br>
also be used like <span class="Special">CTRL-V</span>. The <> notation can be fully used then <a class="Identifier" href="intro.html#<>"><></a>. But<br>
you cannot use "<span class="Special"><C-V></span>" like <span class="Special">CTRL-V</span> to escape the special meaning of what<br>
follows.<br>
<br>
To map a backslash, or use a backslash literally in the <span class="Special">{rhs}</span>, the special<br>
sequence "<span class="Special"><Bslash></span>" can be used. This avoids the need to double backslashes<br>
when using nested mappings.<br>
<br>
<a class="Constant" href="map.html#map_CTRL-C" name="map_CTRL-C">map_CTRL-C</a> <a class="Constant" href="map.html#map-CTRL-C" name="map-CTRL-C">map-CTRL-C</a><br>
Using <span class="Special">CTRL-C</span> in the <span class="Special">{lhs}</span> is possible, but it will only work when Vim is<br>
waiting for a key, not when Vim is busy with something. When Vim is busy<br>
<span class="Special">CTRL-C</span> interrupts/breaks the command.<br>
When using the GUI version on MS-Windows <span class="Special">CTRL-C</span> can be mapped to allow a Copy<br>
command to the clipboard. Use <span class="Special">CTRL-Break</span> to interrupt Vim.<br>
<br>
<a class="Constant" href="map.html#map_space_in_lhs" name="map_space_in_lhs">map_space_in_lhs</a> <a class="Constant" href="map.html#map-space_in_lhs" name="map-space_in_lhs">map-space_in_lhs</a><br>
To include a space in <span class="Special">{lhs}</span> precede it with a <span class="Special">CTRL-V</span> (type two <span class="Special">CTRL-V</span>s for<br>
each space).<br>
<a class="Constant" href="map.html#map_space_in_rhs" name="map_space_in_rhs">map_space_in_rhs</a> <a class="Constant" href="map.html#map-space_in_rhs" name="map-space_in_rhs">map-space_in_rhs</a><br>
If you want a <span class="Special">{rhs}</span> that starts with a space, use "<span class="Special"><Space></span>". To be fully Vi<br>
compatible (but unreadable) don't use the <a class="Identifier" href="intro.html#<>"><></a> notation, precede <span class="Special">{rhs}</span> with a<br>
single <span class="Special">CTRL-V</span> (you have to type <span class="Special">CTRL-V</span> two times).<br>
<a class="Constant" href="map.html#map_empty_rhs" name="map_empty_rhs">map_empty_rhs</a> <a class="Constant" href="map.html#map-empty-rhs" name="map-empty-rhs">map-empty-rhs</a><br>
You can create an empty <span class="Special">{rhs}</span> by typing nothing after a single <span class="Special">CTRL-V</span> (you<br>
have to type <span class="Special">CTRL-V</span> two times). Unfortunately, you cannot do this in a vimrc<br>
file.<br>
<a class="Constant" href="map.html#<Nop>" name="<Nop>"><Nop></a><br>
An easier way to get a mapping that doesn't produce anything, is to use<br>
"<span class="Special"><Nop></span>" for the <span class="Special">{rhs}</span>. This only works when the <a class="Identifier" href="intro.html#<>"><></a> notation is enabled.<br>
For example, to make sure that function key 8 does nothing at all:<br>
<div class="helpExample"> :map <F8> <Nop><br>
:map! <F8> <Nop></div>
<br>
<a class="Constant" href="map.html#map-multibyte" name="map-multibyte">map-multibyte</a><br>
It is possible to map multibyte characters, but only the whole character. You<br>
cannot map the first byte only. This was done to prevent problems in this<br>
scenario:<br>
<div class="helpExample"> :set encoding=latin1<br>
:imap <M-C> foo<br>
:set encoding=utf-8</div>
The mapping for <span class="Special"><M-C></span> is defined with the latin1 encoding, resulting in a 0xc3<br>
byte. If you type the character ? (0xe1 <span class="Special"><M-a></span>) in UTF-8 encoding this is the<br>
two bytes 0xc3 0xa1. You don't want the 0xc3 byte to be mapped then or<br>
otherwise it would be impossible to type the ? character.<br>
<br>
<a class="Constant" href="map.html#<Leader>" name="<Leader>"><Leader></a> <a class="Constant" href="map.html#mapleader" name="mapleader">mapleader</a><br>
To define a mapping which uses the "mapleader" variable, the special string<br>
"<span class="Special"><Leader></span>" can be used. It is replaced with the string value of "mapleader".<br>
If "mapleader" is not set or empty, a backslash is used instead. Example:<br>
<div class="helpExample"> :map <Leader>A oanother line<Esc></div>
Works like:<br>
<div class="helpExample"> :map \A oanother line<Esc></div>
But after:<br>
<div class="helpExample"> :let mapleader = ","</div>
It works like:<br>
<div class="helpExample"> :map ,A oanother line<Esc></div>
<br>
<span class="Todo">Note</span> that the value of "mapleader" is used at the moment the mapping is<br>
defined. Changing "mapleader" after that has no effect for already defined<br>
mappings.<br>
<br>
<a class="Constant" href="map.html#<LocalLeader>" name="<LocalLeader>"><LocalLeader></a> <a class="Constant" href="map.html#maplocalleader" name="maplocalleader">maplocalleader</a><br>
<span class="Special"><LocalLeader></span> is just like <span class="Special"><Leader></span>, except that it uses "maplocalleader"<br>
instead of "mapleader". <span class="Special"><LocalLeader></span> is to be used for mappings which are<br>
local to a buffer. Example:<br>
<div class="helpExample"> :map <buffer> <LocalLeader>A oanother line<Esc></div>
<br>
In a global plugin <span class="Special"><Leader></span> should be used and in a filetype plugin<br>
<span class="Special"><LocalLeader></span>. "mapleader" and "maplocalleader" can be equal. Although, if<br>
you make them different, there is a smaller chance of mappings from global<br>
plugins to clash with mappings for filetype plugins. For example, you could<br>
keep "mapleader" at the default backslash, and set "maplocalleader" to an<br>
underscore.<br>
<br>
<a class="Constant" href="map.html#map-<SID>" name="map-<SID>">map-<SID></a><br>
In a script the special key name "<span class="Special"><SID></span>" can be used to define a mapping<br>
that's local to the script. See <a class="Identifier" href="map.html#<SID>"><SID></a> for details.<br>
<br>
<a class="Constant" href="map.html#<Plug>" name="<Plug>"><Plug></a><br>
The special key name "<span class="Special"><Plug></span>" can be used for an internal mapping, which is<br>
not to be matched with any key sequence. This is useful in plugins<br>
<a class="Identifier" href="usr_41.html#using-<Plug>">using-<Plug></a>.<br>
<br>
<a class="Constant" href="map.html#<Char>" name="<Char>"><Char></a> <a class="Constant" href="map.html#<Char->" name="<Char->"><Char-></a><br>
To map a character by its decimal, octal or hexadecimal number the <span class="Special"><Char></span><br>
construct can be used:<br>
<span class="Special"><Char-123></span> character 123<br>
<span class="Special"><Char-033></span> character 27<br>
<span class="Special"><Char-0x7f></span> character 127<br>
<span class="Special"><S-Char-114></span> character 114 ('r') shifted ('R')<br>
This is useful to specify a (multi-byte) character in a <a class="Type" href="options.html#'keymap'">'keymap'</a> file.<br>
Upper and lowercase differences are ignored.<br>
<br>
<a class="Constant" href="map.html#map-comments" name="map-comments">map-comments</a><br>
It is not possible to put a comment after these commands, because the '"'<br>
character is considered to be part of the <span class="Special">{lhs}</span> or <span class="Special">{rhs}</span>. However, one can<br>
use |", since this starts a new, empty command with a comment.<br>
<br>
<a class="Constant" href="map.html#map_bar" name="map_bar">map_bar</a> <a class="Constant" href="map.html#map-bar" name="map-bar">map-bar</a><br>
Since the '|' character is used to separate a map command from the next<br>
command, you will have to do something special to include a '|' in <span class="Special">{rhs}</span>.<br>
There are three methods:<br>
<span class="PreProc">use works when example</span><br>
<span class="Special"><Bar></span> '<' is not in <a class="Type" href="options.html#'cpoptions'">'cpoptions'</a> :map _l :!ls <span class="Special"><Bar></span> more^M<br>
\| 'b' is not in <a class="Type" href="options.html#'cpoptions'">'cpoptions'</a> :map _l :!ls \| more^M<br>
^V| always, in Vim and Vi :map _l :!ls ^V| more^M<br>
<br>
(here ^V stands for <span class="Special">CTRL-V</span>; to get one <span class="Special">CTRL-V</span> you have to type it twice; you<br>
cannot use the <> notation "<span class="Special"><C-V></span>" here).<br>
<br>
All three work when you use the default setting for <a class="Type" href="options.html#'cpoptions'">'cpoptions'</a>.<br>
<br>
When 'b' is present in <a class="Type" href="options.html#'cpoptions'">'cpoptions'</a>, "\|" will be recognized as a mapping<br>
ending in a '\' and then another command. This is Vi compatible, but<br>
illogical when compared to other commands.<br>
<br>
<a class="Constant" href="map.html#map_return" name="map_return">map_return</a> <a class="Constant" href="map.html#map-return" name="map-return">map-return</a><br>
When you have a mapping that contains an Ex command, you need to put a line<br>
terminator after it to have it executed. The use of <span class="Special"><CR></span> is recommended for<br>
this (see <a class="Identifier" href="intro.html#<>"><></a>). Example:<br>
<div class="helpExample"> :map _ls :!ls -l %:S<CR>:echo "the end"<CR></div>
<br>
To avoid mapping of the characters you type in insert or Command-line mode,<br>
type a <span class="Special">CTRL-V</span> first. The mapping in Insert mode is disabled if the <a class="Type" href="options.html#'paste'">'paste'</a><br>
option is on.<br>
<a class="Constant" href="map.html#map-error" name="map-error">map-error</a><br>
<span class="Todo">Note</span> that when an error is encountered (that causes an error message or beep)<br>
the rest of the mapping is not executed. This is Vi-compatible.<br>
<br>
<span class="Todo">Note</span> that the second character (argument) of the commands @zZtTfF[]rm'`"v<br>
and <span class="Special">CTRL-X</span> is not mapped. This was done to be able to use all the named<br>
registers and marks, even when the command with the same name has been<br>
mapped.<br>
<br>
<br>
1.7 WHAT KEYS TO MAP <a class="Constant" href="map.html#map-which-keys" name="map-which-keys">map-which-keys</a><br>
<br>
If you are going to map something, you will need to choose which key(s) to use<br>
for the <span class="Special">{lhs}</span>. You will have to avoid keys that are used for Vim commands,<br>
otherwise you would not be able to use those commands anymore. Here are a few<br>
suggestions:<br>
- Function keys <span class="Special"><F2></span>, <span class="Special"><F3></span>, etc.. Also the shifted function keys <span class="Special"><S-F1></span>,<br>
<span class="Special"><S-F2></span>, etc. <span class="Todo">Note</span> that <span class="Special"><F1></span> is already used for the help command.<br>
- Meta-keys (with the ALT key pressed). Depending on your keyboard accented<br>
characters may be used as well. <a class="Identifier" href="map.html#:map-alt-keys">:map-alt-keys</a><br>
- Use the '_' or ',' character and then any other character. The "_" and ","<br>
commands do exist in Vim (see <a class="Identifier" href="motion.html#_">_</a> and <a class="Identifier" href="motion.html#,">,</a>), but you probably never use them.<br>
- Use a key that is a synonym for another command. For example: <span class="Special">CTRL-P</span> and<br>
<span class="Special">CTRL-N</span>. Use an extra character to allow more mappings.<br>
- The key defined by <span class="Special"><Leader></span> and one or more other keys. This is especially<br>
useful in scripts. <a class="Identifier" href="map.html#mapleader">mapleader</a><br>
<br>
See the file "index" for keys that are not used and thus can be mapped without<br>
losing any builtin function. You can also use ":help <span class="Special">{key}</span>^D" to find out if<br>
a key is used for some command. (<span class="Special">{key}</span> is the specific key you want to find<br>
out about, ^D is <span class="Special">CTRL-D</span>).<br>
<br>
<br>
1.8 EXAMPLES <a class="Constant" href="map.html#map-examples" name="map-examples">map-examples</a><br>
<br>
A few examples (given as you type them, for "<span class="Special"><CR></span>" you type four characters;<br>
the '<' flag must not be present in <a class="Type" href="options.html#'cpoptions'">'cpoptions'</a> for this to work).<br>
<br>
<div class="helpExample"> :map <F3> o#include<br>
:map <M-g> /foo<CR>cwbar<Esc><br>
:map _x d/END/e<CR><br>
:map! qq quadrillion questions</div>
<br>
<br>
Multiplying a count<br>
<br>
When you type a count before triggering a mapping, it's like the count was<br>
typed before the <span class="Special">{lhs}</span>. For example, with this mapping:<br>
<div class="helpExample"> :map <F4> 3w</div>
Typing 2<span class="Special"><F4></span> will result in "23w". Thus not moving 2 * 3 words but 23 words.<br>
If you want to multiply counts use the expression register:<br>
<div class="helpExample"> :map <F4> @='3w'<CR></div>
The part between quotes is the expression being executed. <a class="Identifier" href="change.html#@=">@=</a><br>
<br>
<br>
1.9 USING MAPPINGS <a class="Constant" href="map.html#map-typing" name="map-typing">map-typing</a><br>
<br>
Vim will compare what you type with the start of a mapped sequence. If there<br>
is an incomplete match, it will get more characters until there either is a<br>
complete match or until there is no match at all. Example: If you map! "qq",<br>
the first 'q' will not appear on the screen until you type another<br>
character. This is because Vim cannot know if the next character will be a<br>
'q' or not. If the <a class="Type" href="options.html#'timeout'">'timeout'</a> option is on (which is the default) Vim will<br>
only wait for one second (or as long as specified with the <a class="Type" href="options.html#'timeoutlen'">'timeoutlen'</a><br>
option). After that it assumes that the 'q' is to be interpreted as such. If<br>
you type slowly, or your system is slow, reset the <a class="Type" href="options.html#'timeout'">'timeout'</a> option. Then you<br>
might want to set the <a class="Type" href="options.html#'ttimeout'">'ttimeout'</a> option.<br>
<br>
<span class="Statement"> </span><a class="Constant" href="map.html#map-precedence" name="map-precedence">map-precedence</a><br>
Buffer-local mappings (defined using <a class="Identifier" href="map.html#:map-<buffer>">:map-<buffer></a>) take precedence over<br>
global mappings. When a buffer-local mapping is the same as a global mapping,<br>
Vim will use the buffer-local mapping. In addition, Vim will use a complete<br>
mapping immediately if it was defined with <span class="Special"><nowait></span>, even if a longer mapping<br>
has the same prefix. For example, given the following two mappings:<br>
<div class="helpExample"> :map <buffer> <nowait> \a :echo "Local \a"<CR><br>
:map \abc :echo "Global \abc"<CR></div>
When typing \a the buffer-local mapping will be used immediately. Vim will<br>
not wait for more characters to see if the user might be typing \abc.<br>
<br>
<a class="Constant" href="map.html#map-keys-fails" name="map-keys-fails">map-keys-fails</a><br>
There are situations where key codes might not be recognized:<br>
- Vim can only read part of the key code. Mostly this is only the first<br>
character. This happens on some Unix versions in an xterm.<br>
- The key code is after character(s) that are mapped. E.g., "<span class="Special"><F1><F1></span>" or<br>
"g<span class="Special"><F1></span>".<br>
<br>
The result is that the key code is not recognized in this situation, and the<br>
mapping fails. There are two actions needed to avoid this problem:<br>
<br>
- Remove the 'K' flag from <a class="Type" href="options.html#'cpoptions'">'cpoptions'</a>. This will make Vim wait for the rest<br>
of the characters of the function key.<br>
- When using <span class="Special"><F1></span> to <span class="Special"><F4></span> the actual key code generated may correspond to<br>
<span class="Special"><xF1></span> to <span class="Special"><xF4></span>. There are mappings from <span class="Special"><xF1></span> to <span class="Special"><F1></span>, <span class="Special"><xF2></span> to <span class="Special"><F2></span>, etc.,<br>
but these are not recognized after another half a mapping. Make sure the<br>
key codes for <span class="Special"><F1></span> to <span class="Special"><F4></span> are correct:<br>
<div class="helpExample"> :set <F1>=<type CTRL-V><type F1></div>
Type the <span class="Special"><F1></span> as four characters. The part after the "=" must be done with<br>
the actual keys, not the literal text.<br>
Another solution is to use the actual key code in the mapping for the second<br>
special key:<br>
<div class="helpExample"> :map <F1><Esc>OP :echo "yes"<CR></div>
Don't type a real <span class="Special"><Esc></span>, Vim will recognize the key code and replace it with<br>
<span class="Special"><F1></span> anyway.<br>
<br>
Another problem may be that when keeping ALT or Meta pressed the terminal<br>
prepends ESC instead of setting the 8th bit. See <a class="Identifier" href="map.html#:map-alt-keys">:map-alt-keys</a>.<br>
<br>
<a class="Constant" href="map.html#recursive_mapping" name="recursive_mapping">recursive_mapping</a><br>
If you include the <span class="Special">{lhs}</span> in the <span class="Special">{rhs}</span> you have a recursive mapping. When<br>
<span class="Special">{lhs}</span> is typed, it will be replaced with <span class="Special">{rhs}</span>. When the <span class="Special">{lhs}</span> which is<br>
included in <span class="Special">{rhs}</span> is encountered it will be replaced with <span class="Special">{rhs}</span>, and so on.<br>
This makes it possible to repeat a command an infinite number of times. The<br>
only problem is that the only way to stop this is by causing an error. The<br>
macros to solve a maze uses this, look there for an example. There is one<br>
exception: If the <span class="Special">{rhs}</span> starts with <span class="Special">{lhs}</span>, the first character is not mapped<br>
again (this is Vi compatible).<br>
For example:<br>
<div class="helpExample"> :map ab abcd</div>
will execute the "a" command and insert "bcd" in the text. The "ab" in the<br>
<span class="Special">{rhs}</span> will not be mapped again.<br>
<br>
If you want to exchange the meaning of two keys you should use the :noremap<br>
command. For example:<br>
<div class="helpExample"> :noremap k j<br>
:noremap j k</div>
This will exchange the cursor up and down commands.<br>
<br>
With the normal :map command, when the <a class="Type" href="options.html#'remap'">'remap'</a> option is on, mapping takes<br>
place until the text is found not to be a part of a <span class="Special">{lhs}</span>. For example, if<br>
you use:<br>
<div class="helpExample"> :map x y<br>
:map y x</div>
Vim will replace x with y, and then y with x, etc. When this has happened<br>
<a class="Type" href="options.html#'maxmapdepth'">'maxmapdepth'</a> times (default 1000), Vim will give the error message<br>
"recursive mapping".<br>
<br>
<a class="Constant" href="map.html#:map-undo" name=":map-undo">:map-undo</a><br>
If you include an undo command inside a mapped sequence, this will bring the<br>
text back in the state before executing the macro. This is compatible with<br>
the original Vi, as long as there is only one undo command in the mapped<br>
sequence (having two undo commands in a mapped sequence did not make sense<br>
in the original Vi, you would get back the text before the first undo).<br>
<br>
<br>
1.10 MAPPING ALT-KEYS <a class="Constant" href="map.html#:map-alt-keys" name=":map-alt-keys">:map-alt-keys</a><br>
<br>
In the GUI Vim handles the Alt key itself, thus mapping keys with ALT should<br>
always work. But in a terminal Vim gets a sequence of bytes and has to figure<br>
out whether ALT was pressed or not.<br>
<br>
By default Vim assumes that pressing the ALT key sets the 8th bit of a typed<br>
character. Most decent terminals can work that way, such as xterm, aterm and<br>
rxvt. If your <span class="Special"><A-k></span> mappings don't work it might be that the terminal is<br>
prefixing the character with an ESC character. But you can just as well type<br>
ESC before a character, thus Vim doesn't know what happened (except for<br>
checking the delay between characters, which is not reliable).<br>
<br>
As of this writing, some mainstream terminals like gnome-terminal and konsole<br>
use the ESC prefix. There doesn't appear a way to have them use the 8th bit<br>
instead. Xterm should work well by default. Aterm and rxvt should work well<br>
when started with the "--meta8" argument. You can also tweak resources like<br>
"metaSendsEscape", "eightBitInput" and "eightBitOutput".<br>
<br>
On the Linux console, this behavior can be toggled with the "setmetamode"<br>
command. Bear in mind that not using an ESC prefix could get you in trouble<br>
with other programs. You should make sure that bash has the "convert-meta"<br>
option set to "on" in order for your Meta keybindings to still work on it<br>
(it's the default readline behavior, unless changed by specific system<br>
configuration). For that, you can add the line:<br>
<br>
<div class="helpExample"> set convert-meta on</div>
<br>
to your ~/.inputrc file. If you're creating the file, you might want to use:<br>
<br>
<div class="helpExample"> $include /etc/inputrc</div>
<br>
as the first line, if that file exists on your system, to keep global options.<br>
This may cause a problem for entering special characters, such as the umlaut.<br>
Then you should use <span class="Special">CTRL-V</span> before that character.<br>
<br>
Bear in mind that convert-meta has been reported to have troubles when used in<br>
UTF-8 locales. On terminals like xterm, the "metaSendsEscape" resource can be<br>
toggled on the fly through the "Main Options" menu, by pressing Ctrl-LeftClick<br>
on the terminal; that's a good last resource in case you want to send ESC when<br>
using other applications but not when inside Vim.<br>
<br>
<br>
1.11 MAPPING AN OPERATOR <a class="Constant" href="map.html#:map-operator" name=":map-operator">:map-operator</a><br>
<br>
An operator is used before a <span class="Special">{motion}</span> command. To define your own operator<br>
you must create mapping that first sets the <a class="Type" href="options.html#'operatorfunc'">'operatorfunc'</a> option and then<br>
invoke the <a class="Identifier" href="map.html#g@">g@</a> operator. After the user types the <span class="Special">{motion}</span> command the<br>
specified function will be called.<br>
<br>
<a class="Constant" href="map.html#g@" name="g@">g@</a> <a class="Constant" href="map.html#E774" name="E774">E774</a> <a class="Constant" href="map.html#E775" name="E775">E775</a><br>
g@<span class="Special">{motion}</span> Call the function set by the <a class="Type" href="options.html#'operatorfunc'">'operatorfunc'</a> option.<br>
The '[ mark is positioned at the start of the text<br>
moved over by <span class="Special">{motion}</span>, the '] mark on the last<br>
character of the text.<br>
The function is called with one String argument:<br>
"line" <span class="Special">{motion}</span> was <a class="Identifier" href="motion.html#linewise">linewise</a><br>
"char" <span class="Special">{motion}</span> was <a class="Identifier" href="motion.html#characterwise">characterwise</a><br>
"block" <span class="Special">{motion}</span> was <a class="Identifier" href="visual.html#blockwise-visual">blockwise-visual</a><br>
Although "block" would rarely appear, since it can<br>
only result from Visual mode where "g@" is not useful.<br>
<span class="Special">{not available when compiled without the </span><a class="Identifier" href="various.html#+eval">+eval</a><br>
<span class="Special">feature}</span><br>
<br>
Here is an example that counts the number of spaces with <span class="Special"><F4></span>:<br>
<br>
<div class="helpExample"> nmap <silent> <F4> :set opfunc=CountSpaces<CR>g@<br>
vmap <silent> <F4> :<C-U>call CountSpaces(visualmode(), 1)<CR></div>
<br>
<div class="helpExample"> function! CountSpaces(type, ...)<br>
let sel_save = &selection<br>
let &selection = "inclusive"<br>
let reg_save = @@</div>
<br>
<div class="helpExample"> if a:0 " Invoked from Visual mode, use gv command.<br>
silent exe "normal! gvy"<br>
elseif a:type == 'line'<br>
silent exe "normal! '[V']y"<br>
else<br>
silent exe "normal! `[v`]y"<br>
endif</div>
<br>
<div class="helpExample"> echomsg strlen(substitute(@@, '[^ ]', '', 'g'))</div>
<br>
<div class="helpExample"> let &selection = sel_save<br>
let @@ = reg_save<br>
endfunction</div>
<br>
<span class="Todo">Note</span> that the <a class="Type" href="options.html#'selection'">'selection'</a> option is temporarily set to "inclusive" to be able<br>
to yank exactly the right text by using Visual mode from the '[ to the ']<br>
mark.<br>
<br>
Also <span class="Todo">note</span> that there is a separate mapping for Visual mode. It removes the<br>
"'<,'>" range that ":" inserts in Visual mode and invokes the function with<br>
visualmode() and an extra argument.<br>
<br>
<span class="PreProc">==============================================================================</span><br>
2. Abbreviations <a class="Constant" href="map.html#abbreviations" name="abbreviations">abbreviations</a> <a class="Constant" href="map.html#Abbreviations" name="Abbreviations">Abbreviations</a><br>
<br>
Abbreviations are used in Insert mode, Replace mode and Command-line mode.<br>
If you enter a word that is an abbreviation, it is replaced with the word it<br>
stands for. This can be used to save typing for often used long words. And<br>
you can use it to automatically correct obvious spelling errors.<br>
Examples:<br>
<br>
:iab ms Microsoft<br>
:iab tihs this<br>
<br>
There are three types of abbreviations:<br>
<br>
full-id The "full-id" type consists entirely of keyword characters (letters<br>
and characters from <a class="Type" href="options.html#'iskeyword'">'iskeyword'</a> option). This is the most common<br>
abbreviation.<br>
<br>
Examples: "foo", "g3", "-1"<br>
<br>
end-id The "end-id" type ends in a keyword character, but all the other<br>
characters are not keyword characters.<br>
<br>
Examples: "#i", "..f", "$/7"<br>
<br>
non-id The "non-id" type ends in a non-keyword character, the other<br>
characters may be of any type, excluding space and tab. {this type<br>
is not supported by Vi}<br>
<br>
Examples: "def#", "4/7$"<br>
<br>
Examples of strings that cannot be abbreviations: "a.b", "#def", "a b", "_$r"<br>
<br>
An abbreviation is only recognized when you type a non-keyword character.<br>
This can also be the <span class="Special"><Esc></span> that ends insert mode or the <span class="Special"><CR></span> that ends a<br>
command. The non-keyword character which ends the abbreviation is inserted<br>
after the expanded abbreviation. An exception to this is the character <span class="Special"><C-]></span>,<br>
which is used to expand an abbreviation without inserting any extra<br>
characters.<br>
<br>
Example:<br>
<div class="helpExample"> :ab hh hello</div>
"hh<span class="Special"><Space></span>" is expanded to "hello<span class="Special"><Space></span>"<br>
"hh<span class="Special"><C-]></span>" is expanded to "hello"<br>
<br>
The characters before the cursor must match the abbreviation. Each type has<br>
an additional rule:<br>
<br>
full-id In front of the match is a non-keyword character, or this is where<br>
the line or insertion starts. Exception: When the abbreviation is<br>
only one character, it is not recognized if there is a non-keyword<br>
character in front of it, other than a space or a tab.<br>
<br>
end-id In front of the match is a keyword character, or a space or a tab,<br>
or this is where the line or insertion starts.<br>
<br>
non-id In front of the match is a space, tab or the start of the line or<br>
the insertion.<br>
<br>
Examples: (<span class="Special">{CURSOR}</span> is where you type a non-keyword character)<br>
<div class="helpExample"> :ab foo four old otters</div>
" foo<span class="Special">{CURSOR}</span>" is expanded to " four old otters"<br>
" foobar<span class="Special">{CURSOR}</span>" is not expanded<br>
"barfoo<span class="Special">{CURSOR}</span>" is not expanded<br>
<br>
<div class="helpExample"> :ab #i #include</div>
"#i<span class="Special">{CURSOR}</span>" is expanded to "#include"<br>
">#i<span class="Special">{CURSOR}</span>" is not expanded<br>
<br>
<div class="helpExample"> :ab ;; <endofline></div>
"test;;" is not expanded<br>
"test ;;" is expanded to "test <span class="Special"><endofline></span>"<br>
<br>
To avoid the abbreviation in Insert mode: Type <span class="Special">CTRL-V</span> before the character<br>
that would trigger the abbreviation. E.g. <span class="Special">CTRL-V</span> <span class="Special"><Space></span>. Or type part of<br>
the abbreviation, exit insert mode with <span class="Special"><Esc></span>, re-enter insert mode with "a"<br>
and type the rest.<br>
<br>
To avoid the abbreviation in Command-line mode: Type <span class="Special">CTRL-V</span> twice somewhere in<br>
the abbreviation to avoid it to be replaced. A <span class="Special">CTRL-V</span> in front of a normal<br>
character is mostly ignored otherwise.<br>
<br>
It is possible to move the cursor after an abbreviation:<br>
<div class="helpExample"> :iab if if ()<Left></div>
This does not work if <a class="Type" href="options.html#'cpoptions'">'cpoptions'</a> includes the '<' flag. <a class="Identifier" href="intro.html#<>"><></a><br>
<br>
You can even do more complicated things. For example, to consume the space<br>
typed after an abbreviation:<br>
<div class="helpExample"> func Eatchar(pat)<br>
let c = nr2char(getchar(0))<br>
return (c =~ a:pat) ? '' : c<br>
endfunc<br>
iabbr <silent> if if ()<Left><C-R>=Eatchar('\s')<CR></div>
<br>
There are no default abbreviations.<br>
<br>
Abbreviations are never recursive. You can use ":ab f f-o-o" without any<br>
problem. But abbreviations can be mapped. {some versions of Vi support<br>
recursive abbreviations, for no apparent reason}<br>
<br>
Abbreviations are disabled if the <a class="Type" href="options.html#'paste'">'paste'</a> option is on.<br>
<br>
<a class="Constant" href="map.html#:abbreviate-local" name=":abbreviate-local">:abbreviate-local</a> <a class="Constant" href="map.html#:abbreviate-<buffer>" name=":abbreviate-<buffer>">:abbreviate-<buffer></a><br>
Just like mappings, abbreviations can be local to a buffer. This is mostly<br>
used in a <a class="Identifier" href="usr_43.html#filetype-plugin">filetype-plugin</a> file. Example for a C plugin file:<br>
<div class="helpExample"> :abb <buffer> FF for (i = 0; i < ; ++i)</div>
<br>
<a class="Constant" href="map.html#:ab" name=":ab">:ab</a> <a class="Constant" href="map.html#:abbreviate" name=":abbreviate">:abbreviate</a><br>
:ab[breviate] list all abbreviations. The character in the first<br>
column indicates the mode where the abbreviation is<br>
used: 'i' for insert mode, 'c' for Command-line<br>
mode, '!' for both. These are the same as for<br>
mappings, see <a class="Identifier" href="map.html#map-listing">map-listing</a>.<br>
<br>
<a class="Constant" href="map.html#:abbreviate-verbose" name=":abbreviate-verbose">:abbreviate-verbose</a><br>
When <a class="Type" href="options.html#'verbose'">'verbose'</a> is non-zero, listing an abbreviation will also display where it<br>
was last defined. Example:<br>
<br>
<div class="helpExample"> :verbose abbreviate<br>
! teh the<br>
Last set from /home/abcd/vim/abbr.vim</div>
<br>
See <a class="Identifier" href="various.html#:verbose-cmd">:verbose-cmd</a> for more information.<br>
<br>
:ab[breviate] <span class="Special">{lhs}</span> list the abbreviations that start with <span class="Special">{lhs}</span><br>
You may need to insert a <span class="Special">CTRL-V</span> (type it twice) to<br>
avoid that a typed <span class="Special">{lhs}</span> is expanded, since<br>
command-line abbreviations apply here.<br>
<br>
:ab[breviate] [<span class="Special"><expr></span>] [<span class="Special"><buffer></span>] <span class="Special">{lhs}</span> <span class="Special">{rhs}</span><br>
add abbreviation for <span class="Special">{lhs}</span> to <span class="Special">{rhs}</span>. If <span class="Special">{lhs}</span> already<br>
existed it is replaced with the new <span class="Special">{rhs}</span>. <span class="Special">{rhs}</span> may<br>
contain spaces.<br>
See <a class="Identifier" href="map.html#:map-<expr>">:map-<expr></a> for the optional <span class="Special"><expr></span> argument.<br>
See <a class="Identifier" href="map.html#:map-<buffer>">:map-<buffer></a> for the optional <span class="Special"><buffer></span> argument.<br>
<br>
<a class="Constant" href="map.html#:una" name=":una">:una</a> <a class="Constant" href="map.html#:unabbreviate" name=":unabbreviate">:unabbreviate</a><br>
:una[bbreviate] <span class="Special">{lhs}</span> Remove abbreviation for <span class="Special">{lhs}</span> from the list. If none<br>
is found, remove abbreviations in which <span class="Special">{lhs}</span> matches<br>
with the <span class="Special">{rhs}</span>. This is done so that you can even<br>
remove abbreviations after expansion. To avoid<br>
expansion insert a <span class="Special">CTRL-V</span> (type it twice).<br>
<br>
<a class="Constant" href="map.html#:norea" name=":norea">:norea</a> <a class="Constant" href="map.html#:noreabbrev" name=":noreabbrev">:noreabbrev</a><br>
:norea[bbrev] [<span class="Special"><expr></span>] [<span class="Special"><buffer></span>] <span class="Special">[lhs]</span> <span class="Special">[rhs]</span><br>
same as ":ab", but no remapping for this <span class="Special">{rhs}</span> <span class="Special">{not</span><br>
<span class="Special">in Vi}</span><br>
<br>
<a class="Constant" href="map.html#:ca" name=":ca">:ca</a> <a class="Constant" href="map.html#:cabbrev" name=":cabbrev">:cabbrev</a><br>
:ca[bbrev] [<span class="Special"><expr></span>] [<span class="Special"><buffer></span>] <span class="Special">[lhs]</span> <span class="Special">[rhs]</span><br>
same as ":ab", but for Command-line mode only. <span class="Special">{not</span><br>
<span class="Special">in Vi}</span><br>
<br>
<a class="Constant" href="map.html#:cuna" name=":cuna">:cuna</a> <a class="Constant" href="map.html#:cunabbrev" name=":cunabbrev">:cunabbrev</a><br>
:cuna[bbrev] <span class="Special">{lhs}</span> same as ":una", but for Command-line mode only. <span class="Special">{not</span><br>
<span class="Special">in Vi}</span><br>
<br>
<a class="Constant" href="map.html#:cnorea" name=":cnorea">:cnorea</a> <a class="Constant" href="map.html#:cnoreabbrev" name=":cnoreabbrev">:cnoreabbrev</a><br>
:cnorea[bbrev] [<span class="Special"><expr></span>] [<span class="Special"><buffer></span>] <span class="Special">[lhs]</span> <span class="Special">[rhs]</span><br>
same as ":ab", but for Command-line mode only and no<br>
remapping for this <span class="Special">{rhs}</span> <span class="Special">{not in Vi}</span><br>
<br>
<a class="Constant" href="map.html#:ia" name=":ia">:ia</a> <a class="Constant" href="map.html#:iabbrev" name=":iabbrev">:iabbrev</a><br>
:ia[bbrev] [<span class="Special"><expr></span>] [<span class="Special"><buffer></span>] <span class="Special">[lhs]</span> <span class="Special">[rhs]</span><br>
same as ":ab", but for Insert mode only. <span class="Special">{not in Vi}</span><br>
<br>
<a class="Constant" href="map.html#:iuna" name=":iuna">:iuna</a> <a class="Constant" href="map.html#:iunabbrev" name=":iunabbrev">:iunabbrev</a><br>
:iuna[bbrev] <span class="Special">{lhs}</span> same as ":una", but for insert mode only. <span class="Special">{not in</span><br>
<span class="Special">Vi}</span><br>
<br>
<a class="Constant" href="map.html#:inorea" name=":inorea">:inorea</a> <a class="Constant" href="map.html#:inoreabbrev" name=":inoreabbrev">:inoreabbrev</a><br>
:inorea[bbrev] [<span class="Special"><expr></span>] [<span class="Special"><buffer></span>] <span class="Special">[lhs]</span> <span class="Special">[rhs]</span><br>
same as ":ab", but for Insert mode only and no<br>
remapping for this <span class="Special">{rhs}</span> <span class="Special">{not in Vi}</span><br>
<br>
<a class="Constant" href="map.html#:abc" name=":abc">:abc</a> <a class="Constant" href="map.html#:abclear" name=":abclear">:abclear</a><br>
:abc[lear] [<span class="Special"><buffer></span>] Remove all abbreviations. <span class="Special">{not in Vi}</span><br>
<br>
<a class="Constant" href="map.html#:iabc" name=":iabc">:iabc</a> <a class="Constant" href="map.html#:iabclear" name=":iabclear">:iabclear</a><br>
:iabc[lear] [<span class="Special"><buffer></span>] Remove all abbreviations for Insert mode. <span class="Special">{not in Vi}</span><br>
<br>
<a class="Constant" href="map.html#:cabc" name=":cabc">:cabc</a> <a class="Constant" href="map.html#:cabclear" name=":cabclear">:cabclear</a><br>
:cabc[lear] [<span class="Special"><buffer></span>] Remove all abbreviations for Command-line mode. <span class="Special">{not</span><br>
<span class="Special">in Vi}</span><br>
<br>
<a class="Constant" href="map.html#using_CTRL-V" name="using_CTRL-V">using_CTRL-V</a><br>
It is possible to use special characters in the rhs of an abbreviation.<br>
<span class="Special">CTRL-V</span> has to be used to avoid the special meaning of most non printable<br>
characters. How many <span class="Special">CTRL-V</span>s need to be typed depends on how you enter the<br>
abbreviation. This also applies to mappings. Let's use an example here.<br>
<br>
Suppose you want to abbreviate "esc" to enter an <span class="Special"><Esc></span> character. When you<br>
type the ":ab" command in Vim, you have to enter this: (here ^V is a <span class="Special">CTRL-V</span><br>
and ^[ is <span class="Special"><Esc></span>)<br>
<br>
You type: ab esc ^V^V^V^V^V^[<br>
<br>
All keyboard input is subjected to ^V quote interpretation, so<br>
the first, third, and fifth ^V characters simply allow the second,<br>
and fourth ^Vs, and the ^[, to be entered into the command-line.<br>
<br>
You see: ab esc ^V^V^[<br>
<br>
The command-line contains two actual ^Vs before the ^[. This is<br>
how it should appear in your .exrc file, if you choose to go that<br>
route. The first ^V is there to quote the second ^V; the :ab<br>
command uses ^V as its own quote character, so you can include quoted<br>
whitespace or the | character in the abbreviation. The :ab command<br>
doesn't do anything special with the ^[ character, so it doesn't need<br>
to be quoted. (Although quoting isn't harmful; that's why typing 7<br>
[but not 8!] ^Vs works.)<br>
<br>
Stored as: esc ^V^[<br>
<br>
After parsing, the abbreviation's short form ("esc") and long form<br>
(the two characters "^V^[") are stored in the abbreviation table.<br>
If you give the :ab command with no arguments, this is how the<br>
abbreviation will be displayed.<br>
<br>
Later, when the abbreviation is expanded because the user typed in<br>
the word "esc", the long form is subjected to the same type of<br>
^V interpretation as keyboard input. So the ^V protects the ^[<br>
character from being interpreted as the "exit Insert mode" character.<br>
Instead, the ^[ is inserted into the text.<br>
<br>
Expands to: ^[<br>
<br>
[example given by Steve Kirkendall]<br>
<br>
<span class="PreProc">==============================================================================</span><br>
3. Local mappings and functions <a class="Constant" href="map.html#script-local" name="script-local">script-local</a><br>
<br>
When using several Vim script files, there is the danger that mappings and<br>
functions used in one script use the same name as in other scripts. To avoid<br>
this, they can be made local to the script.<br>
<br>
<a class="Constant" href="map.html#<SID>" name="<SID>"><SID></a> <a class="Constant" href="map.html#<SNR>" name="<SNR>"><SNR></a> <a class="Constant" href="map.html#E81" name="E81">E81</a><br>
The string "<span class="Special"><SID></span>" can be used in a mapping or menu. This requires that the<br>
'<' flag is not present in <a class="Type" href="options.html#'cpoptions'">'cpoptions'</a>.<br>
When executing the map command, Vim will replace "<span class="Special"><SID></span>" with the special<br>
key code <span class="Special"><SNR></span>, followed by a number that's unique for the script, and an<br>
underscore. Example:<br>
<div class="helpExample"> :map <SID>Add</div>
could define a mapping "<span class="Special"><SNR></span>23_Add".<br>
<br>
When defining a function in a script, "s:" can be prepended to the name to<br>
make it local to the script. But when a mapping is executed from outside of<br>
the script, it doesn't know in which script the function was defined. To<br>
avoid this problem, use "<span class="Special"><SID></span>" instead of "s:". The same translation is done<br>
as for mappings. This makes it possible to define a call to the function in<br>
a mapping.<br>
<br>
When a local function is executed, it runs in the context of the script it was<br>
defined in. This means that new functions and mappings it defines can also<br>
use "s:" or "<span class="Special"><SID></span>" and it will use the same unique number as when the<br>
function itself was defined. Also, the "s:var" local script variables can be<br>
used.<br>
<br>
When executing an autocommand or a user command, it will run in the context of<br>
the script it was defined in. This makes it possible that the command calls a<br>
local function or uses a local mapping.<br>
<br>
Otherwise, using "<span class="Special"><SID></span>" outside of a script context is an error.<br>
<br>
If you need to get the script number to use in a complicated script, you can<br>
use this function:<br>
<div class="helpExample"> function s:SID()<br>
return matchstr(expand('<sfile>'), '<SNR>\zs\d\+\ze_SID$')<br>
endfun</div>
<br>
The "<span class="Special"><SNR></span>" will be shown when listing functions and mappings. This is useful<br>
to find out what they are defined to.<br>
<br>
The <a class="Identifier" href="repeat.html#:scriptnames">:scriptnames</a> command can be used to see which scripts have been sourced<br>
and what their <span class="Special"><SNR></span> number is.<br>
<br>
This is all <span class="Special">{not in Vi}</span> and <span class="Special">{not available when compiled without the </span><a class="Identifier" href="various.html#+eval">+eval</a><br>
<span class="Special">feature}</span>.<br>
<br>
<span class="PreProc">==============================================================================</span><br>
4. User-defined commands <a class="Constant" href="map.html#user-commands" name="user-commands">user-commands</a><br>
<br>
It is possible to define your own Ex commands. A user-defined command can act<br>
just like a built-in command (it can have a range or arguments, arguments can<br>
be completed as filenames or buffer names, etc), except that when the command<br>
is executed, it is transformed into a normal Ex command and then executed.<br>
<br>
For starters: See section <a class="Identifier" href="usr_40.html#40.2">40.2</a> in the user manual.<br>
<br>
<a class="Constant" href="map.html#E183" name="E183">E183</a> <a class="Constant" href="map.html#E841" name="E841">E841</a> <a class="Constant" href="map.html#user-cmd-ambiguous" name="user-cmd-ambiguous">user-cmd-ambiguous</a><br>
All user defined commands must start with an uppercase letter, to avoid<br>
confusion with builtin commands. Exceptions are these builtin commands:<br>
:Next<br>
:X<br>
They cannot be used for a user defined command. ":Print" is also an existing<br>
command, but it is deprecated and can be overruled.<br>
<br>
The other characters of the user command can be uppercase letters, lowercase<br>
letters or digits. When using digits, <span class="Todo">note</span> that other commands that take a<br>
numeric argument may become ambiguous. For example, the command ":Cc2" could<br>
be the user command ":Cc2" without an argument, or the command ":Cc" with<br>
argument "2". It is advised to put a space between the command name and the<br>
argument to avoid these problems.<br>
<br>
When using a user-defined command, the command can be abbreviated. However, if<br>
an abbreviation is not unique, an error will be issued. Furthermore, a<br>
built-in command will always take precedence.<br>
<br>
Example:<br>
<div class="helpExample"> :command Rename ...<br>
:command Renumber ...<br>
:Rena " Means "Rename"<br>
:Renu " Means "Renumber"<br>
:Ren " Error - ambiguous<br>
:command Paste ...<br>
:P " The built-in :Print</div>
<br>
It is recommended that full names for user-defined commands are used in<br>
scripts.<br>
<br>
:com[mand] <a class="Constant" href="map.html#:com" name=":com">:com</a> <a class="Constant" href="map.html#:command" name=":command">:command</a><br>
List all user-defined commands. When listing commands,<br>
the characters in the first two columns are<br>
! Command has the -bang attribute<br>
" Command has the -register attribute<br>
b Command is local to current buffer<br>
(see below for details on attributes)<br>
The list can be filtered on command name with<br>
<a class="Identifier" href="various.html#:filter">:filter</a>, e.g., to list all commands with "Pyth" in<br>
the name:<br>
<div class="helpExample"> filter Pyth command</div>
<br>
:com[mand] <span class="Special">{cmd}</span> List the user-defined commands that start with <span class="Special">{cmd}</span><br>
<br>
<a class="Constant" href="map.html#:command-verbose" name=":command-verbose">:command-verbose</a><br>
When <a class="Type" href="options.html#'verbose'">'verbose'</a> is non-zero, listing a command will also display where it was<br>
last defined. Example:<br>
<br>
<div class="helpExample"> :verbose command TOhtml</div>
<span class="PreProc">Name Args Range Complete Definition</span><br>
<span class="PreProc">TOhtml 0 % :call Convert2HTML(<line1>, <line2>)</span><br>
<span class="PreProc">Last set from /usr/share/vim/vim-7.0/plugin/tohtml.vim</span><br>
<br>
See <a class="Identifier" href="various.html#:verbose-cmd">:verbose-cmd</a> for more information.<br>
<br>
<a class="Constant" href="map.html#E174" name="E174">E174</a> <a class="Constant" href="map.html#E182" name="E182">E182</a><br>
:com[mand][!] [<span class="Special">{attr}</span>...] <span class="Special">{cmd}</span> <span class="Special">{rep}</span><br>
Define a user command. The name of the command is<br>
<span class="Special">{cmd}</span> and its replacement text is <span class="Special">{rep}</span>. The command's<br>
attributes (see below) are <span class="Special">{attr}</span>. If the command<br>
already exists, an error is reported, unless a ! is<br>
specified, in which case the command is redefined.<br>
<br>
:delc[ommand] <span class="Special">{cmd}</span> <a class="Constant" href="map.html#:delc" name=":delc">:delc</a> <a class="Constant" href="map.html#:delcommand" name=":delcommand">:delcommand</a> <a class="Constant" href="map.html#E184" name="E184">E184</a><br>
Delete the user-defined command <span class="Special">{cmd}</span>.<br>
<br>
:comc[lear] <a class="Constant" href="map.html#:comc" name=":comc">:comc</a> <a class="Constant" href="map.html#:comclear" name=":comclear">:comclear</a><br>
Delete all user-defined commands.<br>
<br>
Command attributes<br>
<br>
User-defined commands are treated by Vim just like any other Ex commands. They<br>
can have arguments, or have a range specified. Arguments are subject to<br>
completion as filenames, buffers, etc. Exactly how this works depends upon the<br>
command's attributes, which are specified when the command is defined.<br>
<br>
There are a number of attributes, split into four categories: argument<br>
handling, completion behavior, range handling, and special cases. The<br>
attributes are described below, by category.<br>
<br>
Argument handling <a class="Constant" href="map.html#E175" name="E175">E175</a> <a class="Constant" href="map.html#E176" name="E176">E176</a> <a class="Constant" href="map.html#:command-nargs" name=":command-nargs">:command-nargs</a><br>
<br>
By default, a user defined command will take no arguments (and an error is<br>
reported if any are supplied). However, it is possible to specify that the<br>
command can take arguments, using the -nargs attribute. Valid cases are:<br>
<br>
-nargs=0 No arguments are allowed (the default)<br>
-nargs=1 Exactly one argument is required, it includes spaces <br>
-nargs=* Any number of arguments are allowed (0, 1, or many),<br>
separated by white space<br>
-nargs=? 0 or 1 arguments are allowed<br>
-nargs=+ Arguments must be supplied, but any number are allowed<br>
<br>
Arguments are considered to be separated by (unescaped) spaces or tabs in this<br>
context, except when there is one argument, then the white space is part of<br>
the argument.<br>
<br>
<span class="Todo">Note</span> that arguments are used as text, not as expressions. Specifically,<br>
"s:var" will use the script-local variable in the script where the command was<br>
defined, not where it is invoked! Example:<br>
script1.vim:<br>
<div class="helpExample"> :let s:error = "None"<br>
:command -nargs=1 Error echoerr <args></div>
script2.vim:<br>
<div class="helpExample"> :source script1.vim<br>
:let s:error = "Wrong!"<br>
:Error s:error</div>
Executing script2.vim will result in "None" being echoed. Not what you<br>
intended! Calling a function may be an alternative.<br>
<br>
Completion behavior <a class="Constant" href="map.html#:command-completion" name=":command-completion">:command-completion</a> <a class="Constant" href="map.html#E179" name="E179">E179</a><br>
<a class="Constant" href="map.html#E180" name="E180">E180</a> <a class="Constant" href="map.html#E181" name="E181">E181</a> <a class="Constant" href="map.html#:command-complete" name=":command-complete">:command-complete</a><br>
By default, the arguments of user defined commands do not undergo completion.<br>
However, by specifying one or the other of the following attributes, argument<br>
completion can be enabled:<br>
<br>
-complete=augroup autocmd groups<br>
-complete=buffer buffer names<br>
-complete=behave :behave suboptions<br>
-complete=color color schemes<br>
-complete=command Ex command (and arguments)<br>
-complete=compiler compilers<br>
-complete=cscope <a class="Identifier" href="if_cscop.html#:cscope">:cscope</a> suboptions<br>
-complete=dir directory names<br>
-complete=environment environment variable names<br>
-complete=event autocommand events<br>
-complete=expression Vim expression<br>
-complete=file file and directory names<br>
-complete=file_in_path file and directory names in <a class="Identifier" href="options.html#'path'">'path'</a><br>
-complete=filetype filetype names <a class="Identifier" href="options.html#'filetype'">'filetype'</a><br>
-complete=function function name<br>
-complete=help help subjects<br>
-complete=highlight highlight groups<br>
-complete=history :history suboptions<br>
-complete=locale locale names (as output of locale -a)<br>
-complete=mapclear buffer argument<br>
-complete=mapping mapping name<br>
-complete=menu menus<br>
-complete=messages <a class="Identifier" href="message.html#:messages">:messages</a> suboptions<br>
-complete=option options<br>
-complete=packadd optional package <a class="Identifier" href="repeat.html#pack-add">pack-add</a> names<br>
-complete=shellcmd Shell command<br>
-complete=sign <a class="Identifier" href="sign.html#:sign">:sign</a> suboptions<br>
-complete=syntax syntax file names <a class="Identifier" href="options.html#'syntax'">'syntax'</a><br>
-complete=syntime <a class="Identifier" href="syntax.html#:syntime">:syntime</a> suboptions<br>
-complete=tag tags<br>
-complete=tag_listfiles tags, file names are shown when <span class="Special">CTRL-D</span> is hit<br>
-complete=user user names<br>
-complete=var user variables<br>
-complete=custom,<span class="Special">{func}</span> custom completion, defined via <span class="Special">{func}</span><br>
-complete=customlist,<span class="Special">{func}</span> custom completion, defined via <span class="Special">{func}</span><br>
<br>
<span class="Todo">Note</span>: That some completion methods might expand environment variables.<br>
<br>
<br>
Custom completion <a class="Constant" href="map.html#:command-completion-custom" name=":command-completion-custom">:command-completion-custom</a><br>
<a class="Constant" href="map.html#:command-completion-customlist" name=":command-completion-customlist">:command-completion-customlist</a><br>
<a class="Constant" href="map.html#E467" name="E467">E467</a> <a class="Constant" href="map.html#E468" name="E468">E468</a><br>
It is possible to define customized completion schemes via the "custom,<span class="Special">{func}</span>"<br>
or the "customlist,<span class="Special">{func}</span>" completion argument. The <span class="Special">{func}</span> part should be a<br>
function with the following signature:<br>
<br>
<div class="helpExample"> :function {func}(ArgLead, CmdLine, CursorPos)</div>
<br>
The function need not use all these arguments. The function should provide the<br>
completion candidates as the return value.<br>
<br>
For the "custom" argument, the function should return the completion<br>
candidates one per line in a newline separated string.<br>
<br>
For the "customlist" argument, the function should return the completion<br>
candidates as a Vim List. Non-string items in the list are ignored.<br>
<br>
The function arguments are:<br>
ArgLead the leading portion of the argument currently being<br>
completed on<br>
CmdLine the entire command line<br>
CursorPos the cursor position in it (byte index)<br>
The function may use these for determining context. For the "custom"<br>
argument, it is not necessary to filter candidates against the (implicit<br>
pattern in) ArgLead. Vim will filter the candidates with its regexp engine<br>
after function return, and this is probably more efficient in most cases. For<br>
the "customlist" argument, Vim will not filter the returned completion<br>
candidates and the user supplied function should filter the candidates.<br>
<br>
The following example lists user names to a Finger command<br>
<div class="helpExample"> :com -complete=custom,ListUsers -nargs=1 Finger !finger <args><br>
:fun ListUsers(A,L,P)<br>
: return system("cut -d: -f1 /etc/passwd")<br>
:endfun</div>
<br>
The following example completes filenames from the directories specified in<br>
the <a class="Type" href="options.html#'path'">'path'</a> option:<br>
<div class="helpExample"> :com -nargs=1 -bang -complete=customlist,EditFileComplete<br>
\ EditFile edit<bang> <args><br>
:fun EditFileComplete(A,L,P)<br>
: return split(globpath(&path, a:A), "\n")<br>
:endfun</div>
<br>
This example does not work for file names with spaces!<br>
<br>
<br>
Range handling <a class="Constant" href="map.html#E177" name="E177">E177</a> <a class="Constant" href="map.html#E178" name="E178">E178</a> <a class="Constant" href="map.html#:command-range" name=":command-range">:command-range</a><br>
<a class="Constant" href="map.html#:command-count" name=":command-count">:command-count</a><br>
By default, user-defined commands do not accept a line number range. However,<br>
it is possible to specify that the command does take a range (the -range<br>
attribute), or that it takes an arbitrary count value, either in the line<br>
number position (-range=<span class="Special">N</span>, like the <a class="Identifier" href="windows.html#:split">:split</a> command) or as a "count"<br>
argument (-count=<span class="Special">N</span>, like the <a class="Identifier" href="editing.html#:Next">:Next</a> command). The count will then be<br>
available in the argument with <a class="Identifier" href="map.html#<count>"><count></a>.<br>
<br>
Possible attributes are:<br>
<br>
-range Range allowed, default is current line<br>
-range=% Range allowed, default is whole file (1,$)<br>
-range=<span class="Special">N</span> A count (default <span class="Special">N</span>) which is specified in the line<br>
number position (like <a class="Identifier" href="windows.html#:split">:split</a>); allows for zero line<br>
number.<br>
-count=<span class="Special">N</span> A count (default <span class="Special">N</span>) which is specified either in the line<br>
number position, or as an initial argument (like <a class="Identifier" href="editing.html#:Next">:Next</a>).<br>
Specifying -count (without a default) acts like -count=0<br>
<br>
<span class="Todo">Note</span> that -range=<span class="Special">N</span> and -count=<span class="Special">N</span> are mutually exclusive - only one should be<br>
specified.<br>
<br>
<a class="Constant" href="map.html#:command-addr" name=":command-addr">:command-addr</a><br>
It is possible that the special characters in the range like ., $ or % which<br>
by default correspond to the current line, last line and the whole buffer,<br>
relate to arguments, (loaded) buffers, windows or tab pages.<br>
<br>
Possible values are:<br>
-addr=lines Range of lines (this is the default)<br>
-addr=arguments Range for arguments<br>
-addr=buffers Range for buffers (also not loaded buffers)<br>
-addr=loaded_buffers Range for loaded buffers<br>
-addr=windows Range for windows<br>
-addr=tabs Range for tab pages<br>
<br>
Special cases <a class="Constant" href="map.html#:command-bang" name=":command-bang">:command-bang</a> <a class="Constant" href="map.html#:command-bar" name=":command-bar">:command-bar</a><br>
<a class="Constant" href="map.html#:command-register" name=":command-register">:command-register</a> <a class="Constant" href="map.html#:command-buffer" name=":command-buffer">:command-buffer</a><br>
There are some special cases as well:<br>
<br>
-bang The command can take a ! modifier (like :q or :w)<br>
-bar The command can be followed by a "|" and another command.<br>
A "|" inside the command argument is not allowed then.<br>
Also checks for a " to start a comment.<br>
-register The first argument to the command can be an optional<br>
register name (like :del, :put, :yank).<br>
-buffer The command will only be available in the current buffer.<br>
<br>
In the cases of the -count and -register attributes, if the optional argument<br>
is supplied, it is removed from the argument list and is available to the<br>
replacement text separately.<br>
<span class="Todo">Note</span> that these arguments can be abbreviated, but that is a deprecated<br>
feature. Use the full name for new scripts.<br>
<br>
Replacement text<br>
<br>
The replacement text for a user defined command is scanned for special escape<br>
sequences, using <...> notation. Escape sequences are replaced with values<br>
from the entered command line, and all other text is copied unchanged. The<br>
resulting string is executed as an Ex command. To avoid the replacement use<br>
<span class="Special"><lt></span> in place of the initial <. Thus to include "<span class="Special"><bang></span>" literally use<br>
"<span class="Special"><lt></span>bang>".<br>
<br>
The valid escape sequences are<br>
<br>
<a class="Constant" href="map.html#<line1>" name="<line1>"><line1></a><br>
<span class="Special"><line1></span> The starting line of the command range.<br>
<a class="Constant" href="map.html#<line2>" name="<line2>"><line2></a><br>
<span class="Special"><line2></span> The final line of the command range.<br>
<a class="Constant" href="map.html#<count>" name="<count>"><count></a><br>
<span class="Special"><count></span> Any count supplied (as described for the '-range'<br>
and '-count' attributes).<br>
<a class="Constant" href="map.html#<bang>" name="<bang>"><bang></a><br>
<span class="Special"><bang></span> (See the '-bang' attribute) Expands to a ! if the<br>
command was executed with a ! modifier, otherwise<br>
expands to nothing.<br>
<a class="Constant" href="map.html#<mods>" name="<mods>"><mods></a><br>
<span class="Special"><mods></span> The command modifiers, if specified. Otherwise, expands to<br>
nothing. Supported modifiers are <a class="Identifier" href="windows.html#:aboveleft">:aboveleft</a>, <a class="Identifier" href="windows.html#:belowright">:belowright</a>,<br>
<a class="Identifier" href="windows.html#:botright">:botright</a>, <a class="Identifier" href="editing.html#:browse">:browse</a>, <a class="Identifier" href="editing.html#:confirm">:confirm</a>, <a class="Identifier" href="windows.html#:hide">:hide</a>, <a class="Identifier" href="editing.html#:keepalt">:keepalt</a>,<br>
<a class="Identifier" href="motion.html#:keepjumps">:keepjumps</a>, <a class="Identifier" href="motion.html#:keepmarks">:keepmarks</a>, <a class="Identifier" href="cmdline.html#:keeppatterns">:keeppatterns</a>, <a class="Identifier" href="windows.html#:leftabove">:leftabove</a>,<br>
<a class="Identifier" href="motion.html#:lockmarks">:lockmarks</a>, <a class="Identifier" href="recover.html#:noswapfile">:noswapfile</a> <a class="Identifier" href="windows.html#:rightbelow">:rightbelow</a>, <a class="Identifier" href="various.html#:silent">:silent</a>, <a class="Identifier" href="tabpage.html#:tab">:tab</a>,<br>
<a class="Identifier" href="windows.html#:topleft">:topleft</a>, <a class="Identifier" href="various.html#:verbose">:verbose</a>, and <a class="Identifier" href="windows.html#:vertical">:vertical</a>.<br>
<span class="Todo">Note</span> that these are not yet supported: <a class="Identifier" href="autocmd.html#:noautocmd">:noautocmd</a>,<br>
<a class="Identifier" href="eval.html#:sandbox">:sandbox</a> and <a class="Identifier" href="various.html#:unsilent">:unsilent</a>.<br>
Examples:<br>
<div class="helpExample"> command! -nargs=+ -complete=file MyEdit<br>
\ for f in expand(<q-args>, 0, 1) |<br>
\ exe '<mods> split ' . f |<br>
\ endfor</div>
<br>
<div class="helpExample"> function! SpecialEdit(files, mods)<br>
for f in expand(a:files, 0, 1)<br>
exe a:mods . ' split ' . f<br>
endfor<br>
endfunction<br>
command! -nargs=+ -complete=file Sedit<br>
\ call SpecialEdit(<q-args>, <q-mods>)</div>
<br>
<a class="Constant" href="map.html#<reg>" name="<reg>"><reg></a> <a class="Constant" href="map.html#<register>" name="<register>"><register></a><br>
<span class="Special"><reg></span> (See the '-register' attribute) The optional register,<br>
if specified. Otherwise, expands to nothing. <span class="Special"><register></span><br>
is a synonym for this.<br>
<a class="Constant" href="map.html#<args>" name="<args>"><args></a><br>
<span class="Special"><args></span> The command arguments, exactly as supplied (but as<br>
noted above, any count or register can consume some<br>
of the arguments, which are then not part of <span class="Special"><args></span>).<br>
<span class="Special"><lt></span> A single '<' (Less-Than) character. This is needed if you<br>
want to get a literal copy of one of these escape sequences<br>
into the expansion - for example, to get <span class="Special"><bang></span>, use<br>
<span class="Special"><lt></span>bang>.<br>
<br>
<a class="Constant" href="map.html#<q-args>" name="<q-args>"><q-args></a><br>
If the first two characters of an escape sequence are "q-" (for example,<br>
<span class="Special"><q-args></span>) then the value is quoted in such a way as to make it a valid value<br>
for use in an expression. This uses the argument as one single value.<br>
When there is no argument <span class="Special"><q-args></span> is an empty string.<br>
<a class="Constant" href="map.html#<f-args>" name="<f-args>"><f-args></a><br>
To allow commands to pass their arguments on to a user-defined function, there<br>
is a special form <span class="Special"><f-args></span> ("function args"). This splits the command<br>
arguments at spaces and tabs, quotes each argument individually, and the<br>
<span class="Special"><f-args></span> sequence is replaced by the comma-separated list of quoted arguments.<br>
See the Mycmd example below. If no arguments are given <span class="Special"><f-args></span> is removed.<br>
To embed whitespace into an argument of <span class="Special"><f-args></span>, prepend a backslash.<br>
<span class="Special"><f-args></span> replaces every pair of backslashes (\\) with one backslash. A<br>
backslash followed by a character other than white space or a backslash<br>
remains unmodified. Overview:<br>
<br>
<span class="PreProc">command <f-args></span><br>
XX ab <span class="MissingTag">'ab'</span><br>
XX a\b 'a\b'<br>
XX a\ b 'a b'<br>
XX a\ b 'a ', 'b'<br>
XX a\\b 'a\b'<br>
XX a\\ b 'a\', 'b'<br>
XX a\\\b 'a\\b'<br>
XX a\\\ b 'a\ b'<br>
XX a\\\\b 'a\\b'<br>
XX a\\\\ b 'a\\', 'b'<br>
<br>
Examples<br>
<br>
<div class="helpExample"> " Delete everything after here to the end<br>
:com Ddel +,$d</div>
<br>
<div class="helpExample"> " Rename the current buffer<br>
:com -nargs=1 -bang -complete=file Ren f <args>|w<bang></div>
<br>
<div class="helpExample"> " Replace a range with the contents of a file<br>
" (Enter this all as one line)<br>
:com -range -nargs=1 -complete=file<br>
Replace <line1>-pu_|<line1>,<line2>d|r <args>|<line1>d</div>
<br>
<div class="helpExample"> " Count the number of lines in the range<br>
:com! -range -nargs=0 Lines echo <line2> - <line1> + 1 "lines"</div>
<br>
<div class="helpExample"> " Call a user function (example of <f-args>)<br>
:com -nargs=* Mycmd call Myfunc(<f-args>)</div>
<br>
When executed as:<br>
<div class="helpExample"> :Mycmd arg1 arg2</div>
This will invoke:<br>
<div class="helpExample"> :call Myfunc("arg1","arg2")</div>
<br>
<div class="helpExample"> :" A more substantial example<br>
:function Allargs(command)<br>
: let i = 0<br>
: while i < argc()<br>
: if filereadable(argv(i))<br>
: execute "e " . argv(i)<br>
: execute a:command<br>
: endif<br>
: let i = i + 1<br>
: endwhile<br>
:endfunction<br>
:command -nargs=+ -complete=command Allargs call Allargs(<q-args>)</div>
<br>
The command Allargs takes any Vim command(s) as argument and executes it on all<br>
files in the argument list. Usage example (<span class="Todo">note</span> use of the "e" flag to ignore<br>
errors and the "update" command to write modified buffers):<br>
<div class="helpExample"> :Allargs %s/foo/bar/ge|update</div>
This will invoke:<br>
<div class="helpExample"> :call Allargs("%s/foo/bar/ge|update")</div>
<br>
When defining a user command in a script, it will be able to call functions<br>
local to the script and use mappings local to the script. When the user<br>
invokes the user command, it will run in the context of the script it was<br>
defined in. This matters if <a class="Identifier" href="map.html#<SID>"><SID></a> is used in a command.<br>
<br>
vim:tw=78:ts=8:ft=help:norl:<br>
</div>
</article>
<footer>
<a href="#top">Return to the top</a> - <a href="index.html">Return to main</a>
<span class="EnglishJapaneseLink">
<span class="CurrentLanguage">English</span>
</span>
<br />
<div style="text-align:right;">
Hosted by <a href="https://github.com/vim-jp/vimdoc-en">vimdoc-en project</a><br />
If you met any problem, please report it to <a href="https://github.com/vim-jp/vimdoc-en/issues">issue</a>.<br />
</div>
</footer>
<!--<script src="js/check-referrer.js" type="text/javascript"></script>-->
</body>
</html>
<!-- vim:set ts=8 sts=2 sw=2 tw=0 et: -->
此处可能存在不合适展示的内容，页面不予展示。您可通过相关编辑功能自查并修改。
如您确认内容无涉及 不当用语 / 纯广告导流 / 暴力 / 低俗色情 / 侵权 / 盗版 / 虚假 / 无价值内容或违法国家有关法律法规的内容，可点击提交进行申诉，我们将尽快为您处理。
马建仓 AI 助手