Bram Moolenaar | 85eee13 | 2018-05-06 17:57:30 +0200 | [diff] [blame] | 1 | *map.txt* For Vim version 8.0. Last change: 2018 May 06 |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 2 | |
| 3 | |
| 4 | VIM REFERENCE MANUAL by Bram Moolenaar |
| 5 | |
| 6 | |
| 7 | Key mapping, abbreviations and user-defined commands. |
| 8 | |
| 9 | This subject is introduced in sections |05.3|, |24.7| and |40.1| of the user |
| 10 | manual. |
| 11 | |
| 12 | 1. Key mapping |key-mapping| |
Bram Moolenaar | 5b962cf | 2005-12-12 21:58:40 +0000 | [diff] [blame] | 13 | 1.1 MAP COMMANDS |:map-commands| |
| 14 | 1.2 Special arguments |:map-arguments| |
| 15 | 1.3 Mapping and modes |:map-modes| |
| 16 | 1.4 Listing mappings |map-listing| |
| 17 | 1.5 Mapping special keys |:map-special-keys| |
| 18 | 1.6 Special characters |:map-special-chars| |
| 19 | 1.7 What keys to map |map-which-keys| |
| 20 | 1.8 Examples |map-examples| |
| 21 | 1.9 Using mappings |map-typing| |
| 22 | 1.10 Mapping alt-keys |:map-alt-keys| |
| 23 | 1.11 Mapping an operator |:map-operator| |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 24 | 2. Abbreviations |abbreviations| |
| 25 | 3. Local mappings and functions |script-local| |
| 26 | 4. User-defined commands |user-commands| |
| 27 | |
| 28 | ============================================================================== |
| 29 | 1. Key mapping *key-mapping* *mapping* *macro* |
| 30 | |
| 31 | Key mapping is used to change the meaning of typed keys. The most common use |
Bram Moolenaar | 24a98a0 | 2017-09-27 22:23:55 +0200 | [diff] [blame] | 32 | is to define a sequence of commands for a function key. Example: > |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 33 | |
| 34 | :map <F2> a<C-R>=strftime("%c")<CR><Esc> |
| 35 | |
Bram Moolenaar | 402d2fe | 2005-04-15 21:00:38 +0000 | [diff] [blame] | 36 | This appends the current date and time after the cursor (in <> notation |<>|). |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 37 | |
Bram Moolenaar | 5b962cf | 2005-12-12 21:58:40 +0000 | [diff] [blame] | 38 | |
| 39 | 1.1 MAP COMMANDS *:map-commands* |
| 40 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 41 | There are commands to enter new mappings, remove mappings and list mappings. |
| 42 | See |map-overview| for the various forms of "map" and their relationships with |
| 43 | modes. |
| 44 | |
| 45 | {lhs} means left-hand-side *{lhs}* |
| 46 | {rhs} means right-hand-side *{rhs}* |
| 47 | |
Bram Moolenaar | 06b5db9 | 2006-02-10 23:11:56 +0000 | [diff] [blame] | 48 | :map {lhs} {rhs} |mapmode-nvo| *:map* |
| 49 | :nm[ap] {lhs} {rhs} |mapmode-n| *:nm* *:nmap* |
| 50 | :vm[ap] {lhs} {rhs} |mapmode-v| *:vm* *:vmap* |
Bram Moolenaar | 371d540 | 2006-03-20 21:47:49 +0000 | [diff] [blame] | 51 | :xm[ap] {lhs} {rhs} |mapmode-x| *:xm* *:xmap* |
Bram Moolenaar | 531da59 | 2013-05-06 05:58:55 +0200 | [diff] [blame] | 52 | :smap {lhs} {rhs} |mapmode-s| *:smap* |
Bram Moolenaar | 06b5db9 | 2006-02-10 23:11:56 +0000 | [diff] [blame] | 53 | :om[ap] {lhs} {rhs} |mapmode-o| *:om* *:omap* |
| 54 | :map! {lhs} {rhs} |mapmode-ic| *:map!* |
| 55 | :im[ap] {lhs} {rhs} |mapmode-i| *:im* *:imap* |
| 56 | :lm[ap] {lhs} {rhs} |mapmode-l| *:lm* *:lmap* |
| 57 | :cm[ap] {lhs} {rhs} |mapmode-c| *:cm* *:cmap* |
Bram Moolenaar | 37c64c7 | 2017-09-19 22:06:03 +0200 | [diff] [blame] | 58 | :tma[p] {lhs} {rhs} |mapmode-t| *:tma* *:tmap* |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 59 | Map the key sequence {lhs} to {rhs} for the modes |
| 60 | where the map command applies. The result, including |
| 61 | {rhs}, is then further scanned for mappings. This |
| 62 | allows for nested and recursive use of mappings. |
| 63 | |
Bram Moolenaar | 822ff86 | 2014-06-12 21:46:14 +0200 | [diff] [blame] | 64 | *:nore* *:norem* |
| 65 | :no[remap] {lhs} {rhs} |mapmode-nvo| *:no* *:noremap* *:nor* |
| 66 | :nn[oremap] {lhs} {rhs} |mapmode-n| *:nn* *:nnoremap* |
| 67 | :vn[oremap] {lhs} {rhs} |mapmode-v| *:vn* *:vnoremap* |
| 68 | :xn[oremap] {lhs} {rhs} |mapmode-x| *:xn* *:xnoremap* |
| 69 | :snor[emap] {lhs} {rhs} |mapmode-s| *:snor* *:snoremap* |
| 70 | :ono[remap] {lhs} {rhs} |mapmode-o| *:ono* *:onoremap* |
| 71 | :no[remap]! {lhs} {rhs} |mapmode-ic| *:no!* *:noremap!* |
| 72 | :ino[remap] {lhs} {rhs} |mapmode-i| *:ino* *:inoremap* |
| 73 | :ln[oremap] {lhs} {rhs} |mapmode-l| *:ln* *:lnoremap* |
| 74 | :cno[remap] {lhs} {rhs} |mapmode-c| *:cno* *:cnoremap* |
Bram Moolenaar | 69fbc9e | 2017-09-14 20:37:57 +0200 | [diff] [blame] | 75 | :tno[remap] {lhs} {rhs} |mapmode-t| *:tno* *:tnoremap* |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 76 | Map the key sequence {lhs} to {rhs} for the modes |
| 77 | where the map command applies. Disallow mapping of |
| 78 | {rhs}, to avoid nested and recursive mappings. Often |
| 79 | used to redefine a command. {not in Vi} |
| 80 | |
| 81 | |
Bram Moolenaar | 06b5db9 | 2006-02-10 23:11:56 +0000 | [diff] [blame] | 82 | :unm[ap] {lhs} |mapmode-nvo| *:unm* *:unmap* |
| 83 | :nun[map] {lhs} |mapmode-n| *:nun* *:nunmap* |
| 84 | :vu[nmap] {lhs} |mapmode-v| *:vu* *:vunmap* |
Bram Moolenaar | 371d540 | 2006-03-20 21:47:49 +0000 | [diff] [blame] | 85 | :xu[nmap] {lhs} |mapmode-x| *:xu* *:xunmap* |
| 86 | :sunm[ap] {lhs} |mapmode-s| *:sunm* *:sunmap* |
Bram Moolenaar | 06b5db9 | 2006-02-10 23:11:56 +0000 | [diff] [blame] | 87 | :ou[nmap] {lhs} |mapmode-o| *:ou* *:ounmap* |
| 88 | :unm[ap]! {lhs} |mapmode-ic| *:unm!* *:unmap!* |
| 89 | :iu[nmap] {lhs} |mapmode-i| *:iu* *:iunmap* |
| 90 | :lu[nmap] {lhs} |mapmode-l| *:lu* *:lunmap* |
| 91 | :cu[nmap] {lhs} |mapmode-c| *:cu* *:cunmap* |
Bram Moolenaar | 37c64c7 | 2017-09-19 22:06:03 +0200 | [diff] [blame] | 92 | :tunma[p] {lhs} |mapmode-t| *:tunma* *:tunmap* |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 93 | Remove the mapping of {lhs} for the modes where the |
| 94 | map command applies. The mapping may remain defined |
| 95 | for other modes where it applies. |
| 96 | Note: Trailing spaces are included in the {lhs}. This |
| 97 | unmap does NOT work: > |
| 98 | :map @@ foo |
| 99 | :unmap @@ | print |
| 100 | |
Bram Moolenaar | 06b5db9 | 2006-02-10 23:11:56 +0000 | [diff] [blame] | 101 | :mapc[lear] |mapmode-nvo| *:mapc* *:mapclear* |
| 102 | :nmapc[lear] |mapmode-n| *:nmapc* *:nmapclear* |
| 103 | :vmapc[lear] |mapmode-v| *:vmapc* *:vmapclear* |
Bram Moolenaar | 371d540 | 2006-03-20 21:47:49 +0000 | [diff] [blame] | 104 | :xmapc[lear] |mapmode-x| *:xmapc* *:xmapclear* |
| 105 | :smapc[lear] |mapmode-s| *:smapc* *:smapclear* |
Bram Moolenaar | 06b5db9 | 2006-02-10 23:11:56 +0000 | [diff] [blame] | 106 | :omapc[lear] |mapmode-o| *:omapc* *:omapclear* |
| 107 | :mapc[lear]! |mapmode-ic| *:mapc!* *:mapclear!* |
| 108 | :imapc[lear] |mapmode-i| *:imapc* *:imapclear* |
| 109 | :lmapc[lear] |mapmode-l| *:lmapc* *:lmapclear* |
| 110 | :cmapc[lear] |mapmode-c| *:cmapc* *:cmapclear* |
Bram Moolenaar | 69fbc9e | 2017-09-14 20:37:57 +0200 | [diff] [blame] | 111 | :tmapc[lear] |mapmode-t| *:tmapc* *:tmapclear* |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 112 | Remove ALL mappings for the modes where the map |
| 113 | command applies. {not in Vi} |
Bram Moolenaar | 251e191 | 2011-06-19 05:09:16 +0200 | [diff] [blame] | 114 | Use the <buffer> argument to remove buffer-local |
| 115 | mappings |:map-<buffer>| |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 116 | Warning: This also removes the default mappings. |
| 117 | |
Bram Moolenaar | 06b5db9 | 2006-02-10 23:11:56 +0000 | [diff] [blame] | 118 | :map |mapmode-nvo| |
| 119 | :nm[ap] |mapmode-n| |
| 120 | :vm[ap] |mapmode-v| |
Bram Moolenaar | 371d540 | 2006-03-20 21:47:49 +0000 | [diff] [blame] | 121 | :xm[ap] |mapmode-x| |
| 122 | :sm[ap] |mapmode-s| |
Bram Moolenaar | 06b5db9 | 2006-02-10 23:11:56 +0000 | [diff] [blame] | 123 | :om[ap] |mapmode-o| |
| 124 | :map! |mapmode-ic| |
| 125 | :im[ap] |mapmode-i| |
| 126 | :lm[ap] |mapmode-l| |
| 127 | :cm[ap] |mapmode-c| |
Bram Moolenaar | 37c64c7 | 2017-09-19 22:06:03 +0200 | [diff] [blame] | 128 | :tma[p] |mapmode-t| |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 129 | List all key mappings for the modes where the map |
| 130 | command applies. Note that ":map" and ":map!" are |
| 131 | used most often, because they include the other modes. |
| 132 | |
Bram Moolenaar | 06b5db9 | 2006-02-10 23:11:56 +0000 | [diff] [blame] | 133 | :map {lhs} |mapmode-nvo| *:map_l* |
| 134 | :nm[ap] {lhs} |mapmode-n| *:nmap_l* |
| 135 | :vm[ap] {lhs} |mapmode-v| *:vmap_l* |
Bram Moolenaar | 371d540 | 2006-03-20 21:47:49 +0000 | [diff] [blame] | 136 | :xm[ap] {lhs} |mapmode-x| *:xmap_l* |
| 137 | :sm[ap] {lhs} |mapmode-s| *:smap_l* |
Bram Moolenaar | 06b5db9 | 2006-02-10 23:11:56 +0000 | [diff] [blame] | 138 | :om[ap] {lhs} |mapmode-o| *:omap_l* |
| 139 | :map! {lhs} |mapmode-ic| *:map_l!* |
| 140 | :im[ap] {lhs} |mapmode-i| *:imap_l* |
| 141 | :lm[ap] {lhs} |mapmode-l| *:lmap_l* |
| 142 | :cm[ap] {lhs} |mapmode-c| *:cmap_l* |
Bram Moolenaar | 37c64c7 | 2017-09-19 22:06:03 +0200 | [diff] [blame] | 143 | :tma[p] {lhs} |mapmode-t| *:tmap_l* |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 144 | List the key mappings for the key sequences starting |
| 145 | with {lhs} in the modes where the map command applies. |
| 146 | {not in Vi} |
| 147 | |
| 148 | These commands are used to map a key or key sequence to a string of |
| 149 | characters. You can use this to put command sequences under function keys, |
| 150 | translate one key into another, etc. See |:mkexrc| for how to save and |
| 151 | restore the current mappings. |
| 152 | |
Bram Moolenaar | 5b962cf | 2005-12-12 21:58:40 +0000 | [diff] [blame] | 153 | *map-ambiguous* |
| 154 | When two mappings start with the same sequence of characters, they are |
| 155 | ambiguous. Example: > |
| 156 | :imap aa foo |
| 157 | :imap aaa bar |
| 158 | When Vim has read "aa", it will need to get another character to be able to |
| 159 | decide if "aa" or "aaa" should be mapped. This means that after typing "aa" |
| 160 | that mapping won't get expanded yet, Vim is waiting for another character. |
| 161 | If you type a space, then "foo" will get inserted, plus the space. If you |
| 162 | type "a", then "bar" will get inserted. |
| 163 | {Vi does not allow ambiguous mappings} |
| 164 | |
| 165 | |
| 166 | 1.2 SPECIAL ARGUMENTS *:map-arguments* |
| 167 | |
Bram Moolenaar | 72179e1 | 2013-06-29 13:58:31 +0200 | [diff] [blame] | 168 | "<buffer>", "<nowait>", "<silent>", "<special>", "<script>", "<expr>" and |
| 169 | "<unique>" can be used in any order. They must appear right after the |
| 170 | command, before any other arguments. |
Bram Moolenaar | 4e42719 | 2006-03-10 21:34:27 +0000 | [diff] [blame] | 171 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 172 | *:map-local* *:map-<buffer>* *E224* *E225* |
Bram Moolenaar | c236c16 | 2008-07-13 17:41:49 +0000 | [diff] [blame] | 173 | If the first argument to one of these commands is "<buffer>" the mapping will |
| 174 | be effective in the current buffer only. Example: > |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 175 | :map <buffer> ,w /[.,;]<CR> |
| 176 | Then you can map ",w" to something else in another buffer: > |
| 177 | :map <buffer> ,w /[#&!]<CR> |
Bram Moolenaar | 72179e1 | 2013-06-29 13:58:31 +0200 | [diff] [blame] | 178 | The local buffer mappings are used before the global ones. See <nowait> below |
| 179 | to make a short local mapping not taking effect when a longer global one |
| 180 | exists. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 181 | The "<buffer>" argument can also be used to clear mappings: > |
| 182 | :unmap <buffer> ,w |
| 183 | :mapclear <buffer> |
| 184 | Local mappings are also cleared when a buffer is deleted, but not when it is |
| 185 | unloaded. Just like local option values. |
Bram Moolenaar | ec7944a | 2013-06-12 21:29:15 +0200 | [diff] [blame] | 186 | Also see |map-precedence|. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 187 | |
Bram Moolenaar | 72179e1 | 2013-06-29 13:58:31 +0200 | [diff] [blame] | 188 | *:map-<nowait>* *:map-nowait* |
| 189 | When defining a buffer-local mapping for "," there may be a global mapping |
| 190 | that starts with ",". Then you need to type another character for Vim to know |
| 191 | whether to use the "," mapping or the longer one. To avoid this add the |
| 192 | <nowait> argument. Then the mapping will be used when it matches, Vim does |
| 193 | not wait for more characters to be typed. However, if the characters were |
Bram Moolenaar | 6aa8cea | 2017-06-05 14:44:35 +0200 | [diff] [blame] | 194 | already typed they are used. |
Bram Moolenaar | 72179e1 | 2013-06-29 13:58:31 +0200 | [diff] [blame] | 195 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 196 | *:map-<silent>* *:map-silent* |
| 197 | To define a mapping which will not be echoed on the command line, add |
| 198 | "<silent>" as the first argument. Example: > |
| 199 | :map <silent> ,h /Header<CR> |
| 200 | The search string will not be echoed when using this mapping. Messages from |
| 201 | the executed command are still given though. To shut them up too, add a |
| 202 | ":silent" in the executed command: > |
| 203 | :map <silent> ,h :exe ":silent normal /Header\r"<CR> |
| 204 | Prompts will still be given, e.g., for inputdialog(). |
| 205 | Using "<silent>" for an abbreviation is possible, but will cause redrawing of |
| 206 | the command line to fail. |
| 207 | |
Bram Moolenaar | 9c10238 | 2006-05-03 21:26:49 +0000 | [diff] [blame] | 208 | *:map-<special>* *:map-special* |
| 209 | Define a mapping with <> notation for special keys, even though the "<" flag |
| 210 | may appear in 'cpoptions'. This is useful if the side effect of setting |
| 211 | 'cpoptions' is not desired. Example: > |
| 212 | :map <special> <F12> /Header<CR> |
| 213 | < |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 214 | *:map-<script>* *:map-script* |
| 215 | If the first argument to one of these commands is "<script>" and it is used to |
| 216 | define a new mapping or abbreviation, the mapping will only remap characters |
| 217 | in the {rhs} using mappings that were defined local to a script, starting with |
| 218 | "<SID>". This can be used to avoid that mappings from outside a script |
| 219 | interfere (e.g., when CTRL-V is remapped in mswin.vim), but do use other |
| 220 | mappings defined in the script. |
| 221 | Note: ":map <script>" and ":noremap <script>" do the same thing. The |
| 222 | "<script>" overrules the command name. Using ":noremap <script>" is |
| 223 | preferred, because it's clearer that remapping is (mostly) disabled. |
| 224 | |
| 225 | *:map-<unique>* *E226* *E227* |
| 226 | If the first argument to one of these commands is "<unique>" and it is used to |
| 227 | define a new mapping or abbreviation, the command will fail if the mapping or |
| 228 | abbreviation already exists. Example: > |
| 229 | :map <unique> ,w /[#&!]<CR> |
| 230 | When defining a local mapping, there will also be a check if a global map |
| 231 | already exists which is equal. |
| 232 | Example of what will fail: > |
| 233 | :map ,w /[#&!]<CR> |
| 234 | :map <buffer> <unique> ,w /[.,;]<CR> |
Bram Moolenaar | a40ceaf | 2006-01-13 22:35:40 +0000 | [diff] [blame] | 235 | If you want to map a key and then have it do what it was originally mapped to, |
| 236 | have a look at |maparg()|. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 237 | |
Bram Moolenaar | 4e42719 | 2006-03-10 21:34:27 +0000 | [diff] [blame] | 238 | *:map-<expr>* *:map-expression* |
| 239 | If the first argument to one of these commands is "<expr>" and it is used to |
| 240 | define a new mapping or abbreviation, the argument is an expression. The |
| 241 | expression is evaluated to obtain the {rhs} that is used. Example: > |
| 242 | :inoremap <expr> . InsertDot() |
| 243 | The result of the InsertDot() function will be inserted. It could check the |
| 244 | text before the cursor and start omni completion when some condition is met. |
| 245 | |
Bram Moolenaar | da9591e | 2009-09-30 13:17:02 +0000 | [diff] [blame] | 246 | For abbreviations |v:char| is set to the character that was typed to trigger |
| 247 | the abbreviation. You can use this to decide how to expand the {lhs}. You |
Bram Moolenaar | 5302d9e | 2011-09-14 17:55:08 +0200 | [diff] [blame] | 248 | should not either insert or change the v:char. |
Bram Moolenaar | da9591e | 2009-09-30 13:17:02 +0000 | [diff] [blame] | 249 | |
Bram Moolenaar | 4e42719 | 2006-03-10 21:34:27 +0000 | [diff] [blame] | 250 | Be very careful about side effects! The expression is evaluated while |
Bram Moolenaar | c9b4b05 | 2006-04-30 18:54:39 +0000 | [diff] [blame] | 251 | obtaining characters, you may very well make the command dysfunctional. |
| 252 | For this reason the following is blocked: |
Bram Moolenaar | 5c5b094 | 2007-05-06 12:07:59 +0000 | [diff] [blame] | 253 | - Changing the buffer text |textlock|. |
| 254 | - Editing another buffer. |
| 255 | - The |:normal| command. |
| 256 | - Moving the cursor is allowed, but it is restored afterwards. |
Bram Moolenaar | c9b4b05 | 2006-04-30 18:54:39 +0000 | [diff] [blame] | 257 | If you want the mapping to do any of these let the returned characters do |
| 258 | that. |
Bram Moolenaar | 4e42719 | 2006-03-10 21:34:27 +0000 | [diff] [blame] | 259 | |
Bram Moolenaar | 1514667 | 2011-10-20 22:22:38 +0200 | [diff] [blame] | 260 | You can use getchar(), it consumes typeahead if there is any. E.g., if you |
| 261 | have these mappings: > |
| 262 | inoremap <expr> <C-L> nr2char(getchar()) |
| 263 | inoremap <expr> <C-L>x "foo" |
| 264 | If you now type CTRL-L nothing happens yet, Vim needs the next character to |
| 265 | decide what mapping to use. If you type 'x' the second mapping is used and |
Bram Moolenaar | f1568ec | 2011-12-14 21:17:39 +0100 | [diff] [blame] | 266 | "foo" is inserted. If you type any other key the first mapping is used, |
| 267 | getchar() gets the typed key and returns it. |
Bram Moolenaar | 1514667 | 2011-10-20 22:22:38 +0200 | [diff] [blame] | 268 | |
Bram Moolenaar | 4e42719 | 2006-03-10 21:34:27 +0000 | [diff] [blame] | 269 | Here is an example that inserts a list number that increases: > |
| 270 | let counter = 0 |
| 271 | inoremap <expr> <C-L> ListItem() |
| 272 | inoremap <expr> <C-R> ListReset() |
| 273 | |
| 274 | func ListItem() |
| 275 | let g:counter += 1 |
| 276 | return g:counter . '. ' |
| 277 | endfunc |
| 278 | |
| 279 | func ListReset() |
| 280 | let g:counter = 0 |
| 281 | return '' |
| 282 | endfunc |
| 283 | |
Bram Moolenaar | d996771 | 2006-03-11 21:18:15 +0000 | [diff] [blame] | 284 | CTRL-L inserts the next number, CTRL-R resets the count. CTRL-R returns an |
Bram Moolenaar | 4e42719 | 2006-03-10 21:34:27 +0000 | [diff] [blame] | 285 | empty string, so that nothing is inserted. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 286 | |
Bram Moolenaar | 8424a62 | 2006-04-19 21:23:36 +0000 | [diff] [blame] | 287 | Note that there are some tricks to make special keys work and escape CSI bytes |
| 288 | in the text. The |:map| command also does this, thus you must avoid that it |
| 289 | is done twice. This does not work: > |
| 290 | :imap <expr> <F3> "<Char-0x611B>" |
| 291 | Because the <Char- sequence is escaped for being a |:imap| argument and then |
| 292 | again for using <expr>. This does work: > |
| 293 | :imap <expr> <F3> "\u611B" |
| 294 | Using 0x80 as a single byte before other text does not work, it will be seen |
| 295 | as a special key. |
| 296 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 297 | |
Bram Moolenaar | 5b962cf | 2005-12-12 21:58:40 +0000 | [diff] [blame] | 298 | 1.3 MAPPING AND MODES *:map-modes* |
Bram Moolenaar | a7241f5 | 2008-06-24 20:39:31 +0000 | [diff] [blame] | 299 | *mapmode-nvo* *mapmode-n* *mapmode-v* *mapmode-o* |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 300 | |
Bram Moolenaar | 8f3f58f | 2010-01-06 20:52:26 +0100 | [diff] [blame] | 301 | There are six sets of mappings |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 302 | - For Normal mode: When typing commands. |
| 303 | - For Visual mode: When typing commands while the Visual area is highlighted. |
Bram Moolenaar | 8f3f58f | 2010-01-06 20:52:26 +0100 | [diff] [blame] | 304 | - For Select mode: like Visual mode but typing text replaces the selection. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 305 | - For Operator-pending mode: When an operator is pending (after "d", "y", "c", |
Bram Moolenaar | a7241f5 | 2008-06-24 20:39:31 +0000 | [diff] [blame] | 306 | etc.). See below: |omap-info|. |
Bram Moolenaar | 402d2fe | 2005-04-15 21:00:38 +0000 | [diff] [blame] | 307 | - For Insert mode. These are also used in Replace mode. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 308 | - For Command-line mode: When entering a ":" or "/" command. |
| 309 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 310 | Special case: While typing a count for a command in Normal mode, mapping zero |
| 311 | is disabled. This makes it possible to map zero without making it impossible |
| 312 | to type a count with a zero. |
| 313 | |
| 314 | *map-overview* *map-modes* |
Bram Moolenaar | e968e36 | 2014-05-13 20:23:24 +0200 | [diff] [blame] | 315 | Overview of which map command works in which mode. More details below. |
| 316 | COMMANDS MODES ~ |
| 317 | :map :noremap :unmap Normal, Visual, Select, Operator-pending |
| 318 | :nmap :nnoremap :nunmap Normal |
| 319 | :vmap :vnoremap :vunmap Visual and Select |
| 320 | :smap :snoremap :sunmap Select |
| 321 | :xmap :xnoremap :xunmap Visual |
| 322 | :omap :onoremap :ounmap Operator-pending |
| 323 | :map! :noremap! :unmap! Insert and Command-line |
| 324 | :imap :inoremap :iunmap Insert |
| 325 | :lmap :lnoremap :lunmap Insert, Command-line, Lang-Arg |
| 326 | :cmap :cnoremap :cunmap Command-line |
Bram Moolenaar | 69fbc9e | 2017-09-14 20:37:57 +0200 | [diff] [blame] | 327 | :tmap :tnoremap :tunmap Terminal-Job |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 328 | |
Bram Moolenaar | e968e36 | 2014-05-13 20:23:24 +0200 | [diff] [blame] | 329 | |
| 330 | COMMANDS MODES ~ |
Bram Moolenaar | c9b4b05 | 2006-04-30 18:54:39 +0000 | [diff] [blame] | 331 | Normal Visual+Select Operator-pending ~ |
| 332 | :map :noremap :unmap :mapclear yes yes yes |
| 333 | :nmap :nnoremap :nunmap :nmapclear yes - - |
| 334 | :vmap :vnoremap :vunmap :vmapclear - yes - |
| 335 | :omap :onoremap :ounmap :omapclear - - yes |
Bram Moolenaar | 371d540 | 2006-03-20 21:47:49 +0000 | [diff] [blame] | 336 | |
Bram Moolenaar | 4c3f536 | 2006-04-11 21:38:50 +0000 | [diff] [blame] | 337 | :nunmap can also be used outside of a monastery. |
Bram Moolenaar | c9b4b05 | 2006-04-30 18:54:39 +0000 | [diff] [blame] | 338 | *mapmode-x* *mapmode-s* |
Bram Moolenaar | 371d540 | 2006-03-20 21:47:49 +0000 | [diff] [blame] | 339 | Some commands work both in Visual and Select mode, some in only one. Note |
| 340 | that quite often "Visual" is mentioned where both Visual and Select mode |
| 341 | apply. |Select-mode-mapping| |
Bram Moolenaar | 8f3f58f | 2010-01-06 20:52:26 +0100 | [diff] [blame] | 342 | NOTE: Mapping a printable character in Select mode may confuse the user. It's |
| 343 | better to explicitly use :xmap and :smap for printable characters. Or use |
| 344 | :sunmap after defining the mapping. |
Bram Moolenaar | 371d540 | 2006-03-20 21:47:49 +0000 | [diff] [blame] | 345 | |
Bram Moolenaar | e968e36 | 2014-05-13 20:23:24 +0200 | [diff] [blame] | 346 | COMMANDS MODES ~ |
Bram Moolenaar | c9b4b05 | 2006-04-30 18:54:39 +0000 | [diff] [blame] | 347 | Visual Select ~ |
| 348 | :vmap :vnoremap :vunmap :vmapclear yes yes |
| 349 | :xmap :xnoremap :xunmap :xmapclear yes - |
| 350 | :smap :snoremap :sunmap :smapclear - yes |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 351 | |
Bram Moolenaar | 06b5db9 | 2006-02-10 23:11:56 +0000 | [diff] [blame] | 352 | *mapmode-ic* *mapmode-i* *mapmode-c* *mapmode-l* |
Bram Moolenaar | 371d540 | 2006-03-20 21:47:49 +0000 | [diff] [blame] | 353 | Some commands work both in Insert mode and Command-line mode, some not: |
| 354 | |
Bram Moolenaar | e968e36 | 2014-05-13 20:23:24 +0200 | [diff] [blame] | 355 | COMMANDS MODES ~ |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 356 | Insert Command-line Lang-Arg ~ |
| 357 | :map! :noremap! :unmap! :mapclear! yes yes - |
| 358 | :imap :inoremap :iunmap :imapclear yes - - |
| 359 | :cmap :cnoremap :cunmap :cmapclear - yes - |
| 360 | :lmap :lnoremap :lunmap :lmapclear yes* yes* yes* |
| 361 | |
| 362 | The original Vi did not have separate mappings for |
| 363 | Normal/Visual/Operator-pending mode and for Insert/Command-line mode. |
| 364 | Therefore the ":map" and ":map!" commands enter and display mappings for |
| 365 | several modes. In Vim you can use the ":nmap", ":vmap", ":omap", ":cmap" and |
| 366 | ":imap" commands to enter mappings for each mode separately. |
| 367 | |
Bram Moolenaar | 69fbc9e | 2017-09-14 20:37:57 +0200 | [diff] [blame] | 368 | *mapmode-t* |
| 369 | The terminal mappings are used in a terminal window, when typing keys for the |
| 370 | job running in the terminal. See |terminal-typing|. |
| 371 | |
Bram Moolenaar | a7241f5 | 2008-06-24 20:39:31 +0000 | [diff] [blame] | 372 | *omap-info* |
| 373 | Operator-pending mappings can be used to define a movement command that can be |
| 374 | used with any operator. Simple example: ":omap { w" makes "y{" work like "yw" |
| 375 | and "d{" like "dw". |
| 376 | |
| 377 | To ignore the starting cursor position and select different text, you can have |
| 378 | the omap start Visual mode to select the text to be operated upon. Example |
| 379 | that operates on a function name in the current line: > |
| 380 | onoremap <silent> F :<C-U>normal! 0f(hviw<CR> |
| 381 | The CTRL-U (<C-U>) is used to remove the range that Vim may insert. The |
| 382 | Normal mode commands find the first '(' character and select the first word |
| 383 | before it. That usually is the function name. |
| 384 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 385 | To enter a mapping for Normal and Visual mode, but not Operator-pending mode, |
| 386 | first define it for all three modes, then unmap it for Operator-pending mode: |
| 387 | :map xx something-difficult |
| 388 | :ounmap xx |
| 389 | Likewise for a mapping for Visual and Operator-pending mode or Normal and |
| 390 | Operator-pending mode. |
| 391 | |
| 392 | *language-mapping* |
| 393 | ":lmap" defines a mapping that applies to: |
| 394 | - Insert mode |
| 395 | - Command-line mode |
| 396 | - when entering a search pattern |
| 397 | - the argument of the commands that accept a text character, such as "r" and |
| 398 | "f" |
| 399 | - for the input() line |
| 400 | Generally: Whenever a character is to be typed that is part of the text in the |
| 401 | buffer, not a Vim command character. "Lang-Arg" isn't really another mode, |
| 402 | it's just used here for this situation. |
| 403 | The simplest way to load a set of related language mappings is by using the |
| 404 | 'keymap' option. See |45.5|. |
| 405 | In Insert mode and in Command-line mode the mappings can be disabled with |
Bram Moolenaar | 7cba6c0 | 2013-09-05 22:13:31 +0200 | [diff] [blame] | 406 | the CTRL-^ command |i_CTRL-^| |c_CTRL-^|. These commands change the value of |
Bram Moolenaar | 3b1db36 | 2013-08-10 15:00:24 +0200 | [diff] [blame] | 407 | the 'iminsert' option. When starting to enter a normal command line (not a |
| 408 | search pattern) the mappings are disabled until a CTRL-^ is typed. The state |
| 409 | last used is remembered for Insert mode and Search patterns separately. The |
| 410 | state for Insert mode is also used when typing a character as an argument to |
| 411 | command like "f" or "t". |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 412 | Language mappings will never be applied to already mapped characters. They |
| 413 | are only used for typed characters. This assumes that the language mapping |
| 414 | was already done when typing the mapping. |
| 415 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 416 | |
Bram Moolenaar | 5b962cf | 2005-12-12 21:58:40 +0000 | [diff] [blame] | 417 | 1.4 LISTING MAPPINGS *map-listing* |
| 418 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 419 | When listing mappings the characters in the first two columns are: |
| 420 | |
| 421 | CHAR MODE ~ |
Bram Moolenaar | 5c5b094 | 2007-05-06 12:07:59 +0000 | [diff] [blame] | 422 | <Space> Normal, Visual, Select and Operator-pending |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 423 | n Normal |
Bram Moolenaar | 5c5b094 | 2007-05-06 12:07:59 +0000 | [diff] [blame] | 424 | v Visual and Select |
| 425 | s Select |
| 426 | x Visual |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 427 | o Operator-pending |
| 428 | ! Insert and Command-line |
| 429 | i Insert |
| 430 | l ":lmap" mappings for Insert, Command-line and Lang-Arg |
| 431 | c Command-line |
Bram Moolenaar | 63c4e8a | 2017-09-17 20:32:20 +0200 | [diff] [blame] | 432 | t Terminal-Job |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 433 | |
| 434 | Just before the {rhs} a special character can appear: |
| 435 | * indicates that it is not remappable |
| 436 | & indicates that only script-local mappings are remappable |
| 437 | @ indicates a buffer-local mapping |
| 438 | |
| 439 | Everything from the first non-blank after {lhs} up to the end of the line |
| 440 | (or '|') is considered to be part of {rhs}. This allows the {rhs} to end |
| 441 | with a space. |
| 442 | |
| 443 | Note: When using mappings for Visual mode, you can use the "'<" mark, which |
| 444 | is the start of the last selected Visual area in the current buffer |'<|. |
| 445 | |
Bram Moolenaar | 818078d | 2016-08-27 21:58:42 +0200 | [diff] [blame] | 446 | The |:filter| command can be used to select what mappings to list. The |
| 447 | pattern is matched against the {lhs} and {rhs} in the raw form. |
| 448 | |
Bram Moolenaar | ae5bce1 | 2005-08-15 21:41:48 +0000 | [diff] [blame] | 449 | *:map-verbose* |
| 450 | When 'verbose' is non-zero, listing a key map will also display where it was |
| 451 | last defined. Example: > |
| 452 | |
| 453 | :verbose map <C-W>* |
| 454 | n <C-W>* * <C-W><C-S>* |
Bram Moolenaar | c9b4b05 | 2006-04-30 18:54:39 +0000 | [diff] [blame] | 455 | Last set from /home/abcd/.vimrc |
Bram Moolenaar | ae5bce1 | 2005-08-15 21:41:48 +0000 | [diff] [blame] | 456 | |
Bram Moolenaar | 5195e45 | 2005-08-19 20:32:47 +0000 | [diff] [blame] | 457 | See |:verbose-cmd| for more information. |
Bram Moolenaar | ae5bce1 | 2005-08-15 21:41:48 +0000 | [diff] [blame] | 458 | |
Bram Moolenaar | 5b962cf | 2005-12-12 21:58:40 +0000 | [diff] [blame] | 459 | |
| 460 | 1.5 MAPPING SPECIAL KEYS *:map-special-keys* |
| 461 | |
| 462 | There are three ways to map a special key: |
| 463 | 1. The Vi-compatible method: Map the key code. Often this is a sequence that |
| 464 | starts with <Esc>. To enter a mapping like this you type ":map " and then |
| 465 | you have to type CTRL-V before hitting the function key. Note that when |
| 466 | the key code for the key is in the termcap (the t_ options), it will |
| 467 | automatically be translated into the internal code and become the second |
| 468 | way of mapping (unless the 'k' flag is included in 'cpoptions'). |
| 469 | 2. The second method is to use the internal code for the function key. To |
| 470 | enter such a mapping type CTRL-K and then hit the function key, or use |
| 471 | the form "#1", "#2", .. "#9", "#0", "<Up>", "<S-Down>", "<S-F7>", etc. |
| 472 | (see table of keys |key-notation|, all keys from <Up> can be used). The |
| 473 | first ten function keys can be defined in two ways: Just the number, like |
| 474 | "#2", and with "<F>", like "<F2>". Both stand for function key 2. "#0" |
| 475 | refers to function key 10, defined with option 't_f10', which may be |
| 476 | function key zero on some keyboards. The <> form cannot be used when |
| 477 | 'cpoptions' includes the '<' flag. |
| 478 | 3. Use the termcap entry, with the form <t_xx>, where "xx" is the name of the |
| 479 | termcap entry. Any string entry can be used. For example: > |
| 480 | :map <t_F3> G |
| 481 | < Maps function key 13 to "G". This does not work if 'cpoptions' includes |
| 482 | the '<' flag. |
| 483 | |
| 484 | The advantage of the second and third method is that the mapping will work on |
| 485 | different terminals without modification (the function key will be |
| 486 | translated into the same internal code or the actual key code, no matter what |
| 487 | terminal you are using. The termcap must be correct for this to work, and you |
| 488 | must use the same mappings). |
| 489 | |
| 490 | DETAIL: Vim first checks if a sequence from the keyboard is mapped. If it |
| 491 | isn't the terminal key codes are tried (see |terminal-options|). If a |
| 492 | terminal code is found it is replaced with the internal code. Then the check |
| 493 | for a mapping is done again (so you can map an internal code to something |
| 494 | else). What is written into the script file depends on what is recognized. |
| 495 | If the terminal key code was recognized as a mapping the key code itself is |
| 496 | written to the script file. If it was recognized as a terminal code the |
| 497 | internal code is written to the script file. |
| 498 | |
| 499 | |
| 500 | 1.6 SPECIAL CHARACTERS *:map-special-chars* |
Bram Moolenaar | 345efa0 | 2016-01-15 20:57:49 +0100 | [diff] [blame] | 501 | *map_backslash* *map-backslash* |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 502 | Note that only CTRL-V is mentioned here as a special character for mappings |
| 503 | and abbreviations. When 'cpoptions' does not contain 'B', a backslash can |
| 504 | also be used like CTRL-V. The <> notation can be fully used then |<>|. But |
| 505 | you cannot use "<C-V>" like CTRL-V to escape the special meaning of what |
| 506 | follows. |
| 507 | |
| 508 | To map a backslash, or use a backslash literally in the {rhs}, the special |
| 509 | sequence "<Bslash>" can be used. This avoids the need to double backslashes |
| 510 | when using nested mappings. |
| 511 | |
Bram Moolenaar | 345efa0 | 2016-01-15 20:57:49 +0100 | [diff] [blame] | 512 | *map_CTRL-C* *map-CTRL-C* |
Bram Moolenaar | 1e01546 | 2005-09-25 22:16:38 +0000 | [diff] [blame] | 513 | Using CTRL-C in the {lhs} is possible, but it will only work when Vim is |
| 514 | waiting for a key, not when Vim is busy with something. When Vim is busy |
| 515 | CTRL-C interrupts/breaks the command. |
| 516 | When using the GUI version on MS-Windows CTRL-C can be mapped to allow a Copy |
| 517 | command to the clipboard. Use CTRL-Break to interrupt Vim. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 518 | |
Bram Moolenaar | 345efa0 | 2016-01-15 20:57:49 +0100 | [diff] [blame] | 519 | *map_space_in_lhs* *map-space_in_lhs* |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 520 | To include a space in {lhs} precede it with a CTRL-V (type two CTRL-Vs for |
| 521 | each space). |
Bram Moolenaar | 345efa0 | 2016-01-15 20:57:49 +0100 | [diff] [blame] | 522 | *map_space_in_rhs* *map-space_in_rhs* |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 523 | If you want a {rhs} that starts with a space, use "<Space>". To be fully Vi |
| 524 | compatible (but unreadable) don't use the |<>| notation, precede {rhs} with a |
| 525 | single CTRL-V (you have to type CTRL-V two times). |
Bram Moolenaar | 345efa0 | 2016-01-15 20:57:49 +0100 | [diff] [blame] | 526 | *map_empty_rhs* *map-empty-rhs* |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 527 | You can create an empty {rhs} by typing nothing after a single CTRL-V (you |
| 528 | have to type CTRL-V two times). Unfortunately, you cannot do this in a vimrc |
| 529 | file. |
| 530 | *<Nop>* |
Bram Moolenaar | 446beb4 | 2011-05-10 17:18:44 +0200 | [diff] [blame] | 531 | An easier way to get a mapping that doesn't produce anything, is to use |
| 532 | "<Nop>" for the {rhs}. This only works when the |<>| notation is enabled. |
| 533 | For example, to make sure that function key 8 does nothing at all: > |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 534 | :map <F8> <Nop> |
| 535 | :map! <F8> <Nop> |
| 536 | < |
Bram Moolenaar | 5b962cf | 2005-12-12 21:58:40 +0000 | [diff] [blame] | 537 | *map-multibyte* |
| 538 | It is possible to map multibyte characters, but only the whole character. You |
| 539 | cannot map the first byte only. This was done to prevent problems in this |
| 540 | scenario: > |
| 541 | :set encoding=latin1 |
| 542 | :imap <M-C> foo |
| 543 | :set encoding=utf-8 |
| 544 | The mapping for <M-C> is defined with the latin1 encoding, resulting in a 0xc3 |
Bram Moolenaar | 85eee13 | 2018-05-06 17:57:30 +0200 | [diff] [blame] | 545 | byte. If you type the character á (0xe1 <M-a>) in UTF-8 encoding this is the |
Bram Moolenaar | 446beb4 | 2011-05-10 17:18:44 +0200 | [diff] [blame] | 546 | two bytes 0xc3 0xa1. You don't want the 0xc3 byte to be mapped then or |
Bram Moolenaar | 85eee13 | 2018-05-06 17:57:30 +0200 | [diff] [blame] | 547 | otherwise it would be impossible to type the á character. |
Bram Moolenaar | 5b962cf | 2005-12-12 21:58:40 +0000 | [diff] [blame] | 548 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 549 | *<Leader>* *mapleader* |
| 550 | To define a mapping which uses the "mapleader" variable, the special string |
| 551 | "<Leader>" can be used. It is replaced with the string value of "mapleader". |
| 552 | If "mapleader" is not set or empty, a backslash is used instead. Example: > |
| 553 | :map <Leader>A oanother line<Esc> |
| 554 | Works like: > |
| 555 | :map \A oanother line<Esc> |
| 556 | But after: > |
| 557 | :let mapleader = "," |
| 558 | It works like: > |
| 559 | :map ,A oanother line<Esc> |
| 560 | |
| 561 | Note that the value of "mapleader" is used at the moment the mapping is |
| 562 | defined. Changing "mapleader" after that has no effect for already defined |
| 563 | mappings. |
| 564 | |
| 565 | *<LocalLeader>* *maplocalleader* |
Bram Moolenaar | a7241f5 | 2008-06-24 20:39:31 +0000 | [diff] [blame] | 566 | <LocalLeader> is just like <Leader>, except that it uses "maplocalleader" |
| 567 | instead of "mapleader". <LocalLeader> is to be used for mappings which are |
| 568 | local to a buffer. Example: > |
Bram Moolenaar | b8ff1fb | 2012-02-04 21:59:01 +0100 | [diff] [blame] | 569 | :map <buffer> <LocalLeader>A oanother line<Esc> |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 570 | < |
| 571 | In a global plugin <Leader> should be used and in a filetype plugin |
| 572 | <LocalLeader>. "mapleader" and "maplocalleader" can be equal. Although, if |
| 573 | you make them different, there is a smaller chance of mappings from global |
| 574 | plugins to clash with mappings for filetype plugins. For example, you could |
| 575 | keep "mapleader" at the default backslash, and set "maplocalleader" to an |
| 576 | underscore. |
| 577 | |
| 578 | *map-<SID>* |
| 579 | In a script the special key name "<SID>" can be used to define a mapping |
| 580 | that's local to the script. See |<SID>| for details. |
| 581 | |
| 582 | *<Plug>* |
| 583 | The special key name "<Plug>" can be used for an internal mapping, which is |
| 584 | not to be matched with any key sequence. This is useful in plugins |
| 585 | |using-<Plug>|. |
| 586 | |
| 587 | *<Char>* *<Char->* |
| 588 | To map a character by its decimal, octal or hexadecimal number the <Char> |
| 589 | construct can be used: |
| 590 | <Char-123> character 123 |
| 591 | <Char-033> character 27 |
| 592 | <Char-0x7f> character 127 |
Bram Moolenaar | 5302d9e | 2011-09-14 17:55:08 +0200 | [diff] [blame] | 593 | <S-Char-114> character 114 ('r') shifted ('R') |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 594 | This is useful to specify a (multi-byte) character in a 'keymap' file. |
| 595 | Upper and lowercase differences are ignored. |
| 596 | |
| 597 | *map-comments* |
| 598 | It is not possible to put a comment after these commands, because the '"' |
Bram Moolenaar | 036986f | 2017-03-16 17:41:02 +0100 | [diff] [blame] | 599 | character is considered to be part of the {lhs} or {rhs}. However, one can |
| 600 | use |", since this starts a new, empty command with a comment. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 601 | |
Bram Moolenaar | 345efa0 | 2016-01-15 20:57:49 +0100 | [diff] [blame] | 602 | *map_bar* *map-bar* |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 603 | Since the '|' character is used to separate a map command from the next |
| 604 | command, you will have to do something special to include a '|' in {rhs}. |
| 605 | There are three methods: |
| 606 | use works when example ~ |
| 607 | <Bar> '<' is not in 'cpoptions' :map _l :!ls <Bar> more^M |
| 608 | \| 'b' is not in 'cpoptions' :map _l :!ls \| more^M |
| 609 | ^V| always, in Vim and Vi :map _l :!ls ^V| more^M |
| 610 | |
| 611 | (here ^V stands for CTRL-V; to get one CTRL-V you have to type it twice; you |
| 612 | cannot use the <> notation "<C-V>" here). |
| 613 | |
| 614 | All three work when you use the default setting for 'cpoptions'. |
| 615 | |
| 616 | When 'b' is present in 'cpoptions', "\|" will be recognized as a mapping |
| 617 | ending in a '\' and then another command. This is Vi compatible, but |
| 618 | illogical when compared to other commands. |
| 619 | |
Bram Moolenaar | 345efa0 | 2016-01-15 20:57:49 +0100 | [diff] [blame] | 620 | *map_return* *map-return* |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 621 | When you have a mapping that contains an Ex command, you need to put a line |
| 622 | terminator after it to have it executed. The use of <CR> is recommended for |
| 623 | this (see |<>|). Example: > |
Bram Moolenaar | 251835e | 2014-02-24 02:51:51 +0100 | [diff] [blame] | 624 | :map _ls :!ls -l %:S<CR>:echo "the end"<CR> |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 625 | |
| 626 | To avoid mapping of the characters you type in insert or Command-line mode, |
| 627 | type a CTRL-V first. The mapping in Insert mode is disabled if the 'paste' |
| 628 | option is on. |
Bram Moolenaar | e2db695 | 2013-07-24 19:53:36 +0200 | [diff] [blame] | 629 | *map-error* |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 630 | Note that when an error is encountered (that causes an error message or beep) |
| 631 | the rest of the mapping is not executed. This is Vi-compatible. |
| 632 | |
| 633 | Note that the second character (argument) of the commands @zZtTfF[]rm'`"v |
| 634 | and CTRL-X is not mapped. This was done to be able to use all the named |
| 635 | registers and marks, even when the command with the same name has been |
| 636 | mapped. |
| 637 | |
Bram Moolenaar | 5b962cf | 2005-12-12 21:58:40 +0000 | [diff] [blame] | 638 | |
| 639 | 1.7 WHAT KEYS TO MAP *map-which-keys* |
| 640 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 641 | If you are going to map something, you will need to choose which key(s) to use |
| 642 | for the {lhs}. You will have to avoid keys that are used for Vim commands, |
| 643 | otherwise you would not be able to use those commands anymore. Here are a few |
| 644 | suggestions: |
| 645 | - Function keys <F2>, <F3>, etc.. Also the shifted function keys <S-F1>, |
| 646 | <S-F2>, etc. Note that <F1> is already used for the help command. |
Bram Moolenaar | f91787c | 2010-07-17 12:47:16 +0200 | [diff] [blame] | 647 | - Meta-keys (with the ALT key pressed). Depending on your keyboard accented |
Bram Moolenaar | 8f3f58f | 2010-01-06 20:52:26 +0100 | [diff] [blame] | 648 | characters may be used as well. |:map-alt-keys| |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 649 | - Use the '_' or ',' character and then any other character. The "_" and "," |
| 650 | commands do exist in Vim (see |_| and |,|), but you probably never use them. |
| 651 | - Use a key that is a synonym for another command. For example: CTRL-P and |
| 652 | CTRL-N. Use an extra character to allow more mappings. |
Bram Moolenaar | 8f3f58f | 2010-01-06 20:52:26 +0100 | [diff] [blame] | 653 | - The key defined by <Leader> and one or more other keys. This is especially |
| 654 | useful in scripts. |mapleader| |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 655 | |
| 656 | See the file "index" for keys that are not used and thus can be mapped without |
| 657 | losing any builtin function. You can also use ":help {key}^D" to find out if |
| 658 | a key is used for some command. ({key} is the specific key you want to find |
| 659 | out about, ^D is CTRL-D). |
| 660 | |
Bram Moolenaar | 5b962cf | 2005-12-12 21:58:40 +0000 | [diff] [blame] | 661 | |
| 662 | 1.8 EXAMPLES *map-examples* |
| 663 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 664 | A few examples (given as you type them, for "<CR>" you type four characters; |
| 665 | the '<' flag must not be present in 'cpoptions' for this to work). > |
| 666 | |
| 667 | :map <F3> o#include |
| 668 | :map <M-g> /foo<CR>cwbar<Esc> |
| 669 | :map _x d/END/e<CR> |
| 670 | :map! qq quadrillion questions |
Bram Moolenaar | 5c5b094 | 2007-05-06 12:07:59 +0000 | [diff] [blame] | 671 | |
| 672 | |
| 673 | Multiplying a count |
| 674 | |
| 675 | When you type a count before triggering a mapping, it's like the count was |
| 676 | typed before the {lhs}. For example, with this mapping: > |
| 677 | :map <F4> 3w |
| 678 | Typing 2<F4> will result in "23w". Thus not moving 2 * 3 words but 23 words. |
| 679 | If you want to multiply counts use the expression register: > |
| 680 | :map <F4> @='3w'<CR> |
| 681 | The part between quotes is the expression being executed. |@=| |
| 682 | |
Bram Moolenaar | 5b962cf | 2005-12-12 21:58:40 +0000 | [diff] [blame] | 683 | |
| 684 | 1.9 USING MAPPINGS *map-typing* |
| 685 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 686 | Vim will compare what you type with the start of a mapped sequence. If there |
| 687 | is an incomplete match, it will get more characters until there either is a |
| 688 | complete match or until there is no match at all. Example: If you map! "qq", |
| 689 | the first 'q' will not appear on the screen until you type another |
| 690 | character. This is because Vim cannot know if the next character will be a |
| 691 | 'q' or not. If the 'timeout' option is on (which is the default) Vim will |
| 692 | only wait for one second (or as long as specified with the 'timeoutlen' |
| 693 | option). After that it assumes that the 'q' is to be interpreted as such. If |
| 694 | you type slowly, or your system is slow, reset the 'timeout' option. Then you |
| 695 | might want to set the 'ttimeout' option. |
| 696 | |
Bram Moolenaar | 37c64c7 | 2017-09-19 22:06:03 +0200 | [diff] [blame] | 697 | *map-precedence* |
Bram Moolenaar | ec7944a | 2013-06-12 21:29:15 +0200 | [diff] [blame] | 698 | Buffer-local mappings (defined using |:map-<buffer>|) take precedence over |
| 699 | global mappings. When a buffer-local mapping is the same as a global mapping, |
| 700 | Vim will use the buffer-local mapping. In addition, Vim will use a complete |
Bram Moolenaar | 14b6945 | 2013-06-29 23:05:20 +0200 | [diff] [blame] | 701 | mapping immediately if it was defined with <nowait>, even if a longer mapping |
| 702 | has the same prefix. For example, given the following two mappings: > |
| 703 | :map <buffer> <nowait> \a :echo "Local \a"<CR> |
| 704 | :map \abc :echo "Global \abc"<CR> |
| 705 | When typing \a the buffer-local mapping will be used immediately. Vim will |
| 706 | not wait for more characters to see if the user might be typing \abc. |
Bram Moolenaar | ec7944a | 2013-06-12 21:29:15 +0200 | [diff] [blame] | 707 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 708 | *map-keys-fails* |
Bram Moolenaar | cdbac1e | 2005-12-11 21:27:22 +0000 | [diff] [blame] | 709 | There are situations where key codes might not be recognized: |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 710 | - Vim can only read part of the key code. Mostly this is only the first |
| 711 | character. This happens on some Unix versions in an xterm. |
| 712 | - The key code is after character(s) that are mapped. E.g., "<F1><F1>" or |
| 713 | "g<F1>". |
Bram Moolenaar | cdbac1e | 2005-12-11 21:27:22 +0000 | [diff] [blame] | 714 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 715 | The result is that the key code is not recognized in this situation, and the |
Bram Moolenaar | cdbac1e | 2005-12-11 21:27:22 +0000 | [diff] [blame] | 716 | mapping fails. There are two actions needed to avoid this problem: |
| 717 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 718 | - Remove the 'K' flag from 'cpoptions'. This will make Vim wait for the rest |
| 719 | of the characters of the function key. |
| 720 | - When using <F1> to <F4> the actual key code generated may correspond to |
| 721 | <xF1> to <xF4>. There are mappings from <xF1> to <F1>, <xF2> to <F2>, etc., |
| 722 | but these are not recognized after another half a mapping. Make sure the |
| 723 | key codes for <F1> to <F4> are correct: > |
| 724 | :set <F1>=<type CTRL-V><type F1> |
| 725 | < Type the <F1> as four characters. The part after the "=" must be done with |
| 726 | the actual keys, not the literal text. |
| 727 | Another solution is to use the actual key code in the mapping for the second |
| 728 | special key: > |
| 729 | :map <F1><Esc>OP :echo "yes"<CR> |
| 730 | Don't type a real <Esc>, Vim will recognize the key code and replace it with |
| 731 | <F1> anyway. |
| 732 | |
Bram Moolenaar | cdbac1e | 2005-12-11 21:27:22 +0000 | [diff] [blame] | 733 | Another problem may be that when keeping ALT or Meta pressed the terminal |
| 734 | prepends ESC instead of setting the 8th bit. See |:map-alt-keys|. |
| 735 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 736 | *recursive_mapping* |
| 737 | If you include the {lhs} in the {rhs} you have a recursive mapping. When |
| 738 | {lhs} is typed, it will be replaced with {rhs}. When the {lhs} which is |
| 739 | included in {rhs} is encountered it will be replaced with {rhs}, and so on. |
| 740 | This makes it possible to repeat a command an infinite number of times. The |
| 741 | only problem is that the only way to stop this is by causing an error. The |
| 742 | macros to solve a maze uses this, look there for an example. There is one |
| 743 | exception: If the {rhs} starts with {lhs}, the first character is not mapped |
| 744 | again (this is Vi compatible). |
| 745 | For example: > |
| 746 | :map ab abcd |
| 747 | will execute the "a" command and insert "bcd" in the text. The "ab" in the |
| 748 | {rhs} will not be mapped again. |
| 749 | |
| 750 | If you want to exchange the meaning of two keys you should use the :noremap |
| 751 | command. For example: > |
| 752 | :noremap k j |
| 753 | :noremap j k |
| 754 | This will exchange the cursor up and down commands. |
| 755 | |
| 756 | With the normal :map command, when the 'remap' option is on, mapping takes |
| 757 | place until the text is found not to be a part of a {lhs}. For example, if |
| 758 | you use: > |
| 759 | :map x y |
| 760 | :map y x |
| 761 | Vim will replace x with y, and then y with x, etc. When this has happened |
| 762 | 'maxmapdepth' times (default 1000), Vim will give the error message |
| 763 | "recursive mapping". |
| 764 | |
| 765 | *:map-undo* |
| 766 | If you include an undo command inside a mapped sequence, this will bring the |
| 767 | text back in the state before executing the macro. This is compatible with |
| 768 | the original Vi, as long as there is only one undo command in the mapped |
| 769 | sequence (having two undo commands in a mapped sequence did not make sense |
| 770 | in the original Vi, you would get back the text before the first undo). |
| 771 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 772 | |
Bram Moolenaar | 5b962cf | 2005-12-12 21:58:40 +0000 | [diff] [blame] | 773 | 1.10 MAPPING ALT-KEYS *:map-alt-keys* |
Bram Moolenaar | cdbac1e | 2005-12-11 21:27:22 +0000 | [diff] [blame] | 774 | |
| 775 | In the GUI Vim handles the Alt key itself, thus mapping keys with ALT should |
| 776 | always work. But in a terminal Vim gets a sequence of bytes and has to figure |
| 777 | out whether ALT was pressed or not. |
| 778 | |
| 779 | By default Vim assumes that pressing the ALT key sets the 8th bit of a typed |
Bram Moolenaar | 97d29a1 | 2005-12-17 22:02:57 +0000 | [diff] [blame] | 780 | character. Most decent terminals can work that way, such as xterm, aterm and |
Bram Moolenaar | cdbac1e | 2005-12-11 21:27:22 +0000 | [diff] [blame] | 781 | rxvt. If your <A-k> mappings don't work it might be that the terminal is |
| 782 | prefixing the character with an ESC character. But you can just as well type |
| 783 | ESC before a character, thus Vim doesn't know what happened (except for |
| 784 | checking the delay between characters, which is not reliable). |
| 785 | |
| 786 | As of this writing, some mainstream terminals like gnome-terminal and konsole |
| 787 | use the ESC prefix. There doesn't appear a way to have them use the 8th bit |
Bram Moolenaar | 97d29a1 | 2005-12-17 22:02:57 +0000 | [diff] [blame] | 788 | instead. Xterm should work well by default. Aterm and rxvt should work well |
| 789 | when started with the "--meta8" argument. You can also tweak resources like |
| 790 | "metaSendsEscape", "eightBitInput" and "eightBitOutput". |
Bram Moolenaar | cdbac1e | 2005-12-11 21:27:22 +0000 | [diff] [blame] | 791 | |
| 792 | On the Linux console, this behavior can be toggled with the "setmetamode" |
| 793 | command. Bear in mind that not using an ESC prefix could get you in trouble |
| 794 | with other programs. You should make sure that bash has the "convert-meta" |
| 795 | option set to "on" in order for your Meta keybindings to still work on it |
| 796 | (it's the default readline behavior, unless changed by specific system |
| 797 | configuration). For that, you can add the line: > |
| 798 | |
| 799 | set convert-meta on |
| 800 | |
| 801 | to your ~/.inputrc file. If you're creating the file, you might want to use: > |
| 802 | |
| 803 | $include /etc/inputrc |
| 804 | |
| 805 | as the first line, if that file exists on your system, to keep global options. |
| 806 | This may cause a problem for entering special characters, such as the umlaut. |
| 807 | Then you should use CTRL-V before that character. |
| 808 | |
| 809 | Bear in mind that convert-meta has been reported to have troubles when used in |
| 810 | UTF-8 locales. On terminals like xterm, the "metaSendsEscape" resource can be |
| 811 | toggled on the fly through the "Main Options" menu, by pressing Ctrl-LeftClick |
| 812 | on the terminal; that's a good last resource in case you want to send ESC when |
Bram Moolenaar | 6aa8cea | 2017-06-05 14:44:35 +0200 | [diff] [blame] | 813 | using other applications but not when inside Vim. |
Bram Moolenaar | cdbac1e | 2005-12-11 21:27:22 +0000 | [diff] [blame] | 814 | |
Bram Moolenaar | 5b962cf | 2005-12-12 21:58:40 +0000 | [diff] [blame] | 815 | |
| 816 | 1.11 MAPPING AN OPERATOR *:map-operator* |
| 817 | |
| 818 | An operator is used before a {motion} command. To define your own operator |
| 819 | you must create mapping that first sets the 'operatorfunc' option and then |
| 820 | invoke the |g@| operator. After the user types the {motion} command the |
| 821 | specified function will be called. |
| 822 | |
Bram Moolenaar | a40ceaf | 2006-01-13 22:35:40 +0000 | [diff] [blame] | 823 | *g@* *E774* *E775* |
Bram Moolenaar | 5b962cf | 2005-12-12 21:58:40 +0000 | [diff] [blame] | 824 | g@{motion} Call the function set by the 'operatorfunc' option. |
| 825 | The '[ mark is positioned at the start of the text |
| 826 | moved over by {motion}, the '] mark on the last |
| 827 | character of the text. |
| 828 | The function is called with one String argument: |
| 829 | "line" {motion} was |linewise| |
| 830 | "char" {motion} was |characterwise| |
Bram Moolenaar | f91787c | 2010-07-17 12:47:16 +0200 | [diff] [blame] | 831 | "block" {motion} was |blockwise-visual| |
Bram Moolenaar | 5b962cf | 2005-12-12 21:58:40 +0000 | [diff] [blame] | 832 | Although "block" would rarely appear, since it can |
| 833 | only result from Visual mode where "g@" is not useful. |
Bram Moolenaar | db84e45 | 2010-08-15 13:50:43 +0200 | [diff] [blame] | 834 | {not available when compiled without the |+eval| |
Bram Moolenaar | 5b962cf | 2005-12-12 21:58:40 +0000 | [diff] [blame] | 835 | feature} |
| 836 | |
| 837 | Here is an example that counts the number of spaces with <F4>: > |
| 838 | |
| 839 | nmap <silent> <F4> :set opfunc=CountSpaces<CR>g@ |
| 840 | vmap <silent> <F4> :<C-U>call CountSpaces(visualmode(), 1)<CR> |
| 841 | |
| 842 | function! CountSpaces(type, ...) |
| 843 | let sel_save = &selection |
| 844 | let &selection = "inclusive" |
| 845 | let reg_save = @@ |
| 846 | |
Bram Moolenaar | 822ff86 | 2014-06-12 21:46:14 +0200 | [diff] [blame] | 847 | if a:0 " Invoked from Visual mode, use gv command. |
| 848 | silent exe "normal! gvy" |
Bram Moolenaar | 5b962cf | 2005-12-12 21:58:40 +0000 | [diff] [blame] | 849 | elseif a:type == 'line' |
| 850 | silent exe "normal! '[V']y" |
Bram Moolenaar | 5b962cf | 2005-12-12 21:58:40 +0000 | [diff] [blame] | 851 | else |
| 852 | silent exe "normal! `[v`]y" |
| 853 | endif |
| 854 | |
| 855 | echomsg strlen(substitute(@@, '[^ ]', '', 'g')) |
| 856 | |
| 857 | let &selection = sel_save |
| 858 | let @@ = reg_save |
| 859 | endfunction |
| 860 | |
| 861 | Note that the 'selection' option is temporarily set to "inclusive" to be able |
| 862 | to yank exactly the right text by using Visual mode from the '[ to the '] |
| 863 | mark. |
| 864 | |
| 865 | Also note that there is a separate mapping for Visual mode. It removes the |
| 866 | "'<,'>" range that ":" inserts in Visual mode and invokes the function with |
| 867 | visualmode() and an extra argument. |
| 868 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 869 | ============================================================================== |
| 870 | 2. Abbreviations *abbreviations* *Abbreviations* |
| 871 | |
| 872 | Abbreviations are used in Insert mode, Replace mode and Command-line mode. |
| 873 | If you enter a word that is an abbreviation, it is replaced with the word it |
| 874 | stands for. This can be used to save typing for often used long words. And |
| 875 | you can use it to automatically correct obvious spelling errors. |
| 876 | Examples: |
| 877 | |
Bram Moolenaar | c1762cc | 2007-05-10 16:56:30 +0000 | [diff] [blame] | 878 | :iab ms Microsoft |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 879 | :iab tihs this |
| 880 | |
| 881 | There are three types of abbreviations: |
| 882 | |
| 883 | full-id The "full-id" type consists entirely of keyword characters (letters |
| 884 | and characters from 'iskeyword' option). This is the most common |
| 885 | abbreviation. |
| 886 | |
| 887 | Examples: "foo", "g3", "-1" |
| 888 | |
| 889 | end-id The "end-id" type ends in a keyword character, but all the other |
| 890 | characters are not keyword characters. |
| 891 | |
| 892 | Examples: "#i", "..f", "$/7" |
| 893 | |
| 894 | non-id The "non-id" type ends in a non-keyword character, the other |
Bram Moolenaar | 3416214 | 2007-05-12 13:12:19 +0000 | [diff] [blame] | 895 | characters may be of any type, excluding space and tab. {this type |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 896 | is not supported by Vi} |
| 897 | |
| 898 | Examples: "def#", "4/7$" |
| 899 | |
| 900 | Examples of strings that cannot be abbreviations: "a.b", "#def", "a b", "_$r" |
| 901 | |
| 902 | An abbreviation is only recognized when you type a non-keyword character. |
| 903 | This can also be the <Esc> that ends insert mode or the <CR> that ends a |
| 904 | command. The non-keyword character which ends the abbreviation is inserted |
| 905 | after the expanded abbreviation. An exception to this is the character <C-]>, |
| 906 | which is used to expand an abbreviation without inserting any extra |
| 907 | characters. |
| 908 | |
| 909 | Example: > |
| 910 | :ab hh hello |
| 911 | < "hh<Space>" is expanded to "hello<Space>" |
| 912 | "hh<C-]>" is expanded to "hello" |
| 913 | |
| 914 | The characters before the cursor must match the abbreviation. Each type has |
| 915 | an additional rule: |
| 916 | |
| 917 | full-id In front of the match is a non-keyword character, or this is where |
| 918 | the line or insertion starts. Exception: When the abbreviation is |
| 919 | only one character, it is not recognized if there is a non-keyword |
Bram Moolenaar | 3416214 | 2007-05-12 13:12:19 +0000 | [diff] [blame] | 920 | character in front of it, other than a space or a tab. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 921 | |
Bram Moolenaar | 3416214 | 2007-05-12 13:12:19 +0000 | [diff] [blame] | 922 | end-id In front of the match is a keyword character, or a space or a tab, |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 923 | or this is where the line or insertion starts. |
| 924 | |
Bram Moolenaar | 3416214 | 2007-05-12 13:12:19 +0000 | [diff] [blame] | 925 | non-id In front of the match is a space, tab or the start of the line or |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 926 | the insertion. |
| 927 | |
| 928 | Examples: ({CURSOR} is where you type a non-keyword character) > |
| 929 | :ab foo four old otters |
| 930 | < " foo{CURSOR}" is expanded to " four old otters" |
| 931 | " foobar{CURSOR}" is not expanded |
| 932 | "barfoo{CURSOR}" is not expanded |
| 933 | > |
| 934 | :ab #i #include |
| 935 | < "#i{CURSOR}" is expanded to "#include" |
| 936 | ">#i{CURSOR}" is not expanded |
| 937 | > |
Bram Moolenaar | 8169525 | 2004-12-29 20:58:21 +0000 | [diff] [blame] | 938 | :ab ;; <endofline> |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 939 | < "test;;" is not expanded |
| 940 | "test ;;" is expanded to "test <endofline>" |
| 941 | |
Bram Moolenaar | 7d76c80 | 2014-10-15 22:51:52 +0200 | [diff] [blame] | 942 | To avoid the abbreviation in Insert mode: Type CTRL-V before the character |
| 943 | that would trigger the abbreviation. E.g. CTRL-V <Space>. Or type part of |
| 944 | the abbreviation, exit insert mode with <Esc>, re-enter insert mode with "a" |
| 945 | and type the rest. |
| 946 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 947 | To avoid the abbreviation in Command-line mode: Type CTRL-V twice somewhere in |
| 948 | the abbreviation to avoid it to be replaced. A CTRL-V in front of a normal |
| 949 | character is mostly ignored otherwise. |
| 950 | |
| 951 | It is possible to move the cursor after an abbreviation: > |
| 952 | :iab if if ()<Left> |
| 953 | This does not work if 'cpoptions' includes the '<' flag. |<>| |
| 954 | |
| 955 | You can even do more complicated things. For example, to consume the space |
| 956 | typed after an abbreviation: > |
| 957 | func Eatchar(pat) |
Bram Moolenaar | 32466aa | 2006-02-24 23:53:04 +0000 | [diff] [blame] | 958 | let c = nr2char(getchar(0)) |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 959 | return (c =~ a:pat) ? '' : c |
| 960 | endfunc |
| 961 | iabbr <silent> if if ()<Left><C-R>=Eatchar('\s')<CR> |
| 962 | |
| 963 | There are no default abbreviations. |
| 964 | |
| 965 | Abbreviations are never recursive. You can use ":ab f f-o-o" without any |
| 966 | problem. But abbreviations can be mapped. {some versions of Vi support |
| 967 | recursive abbreviations, for no apparent reason} |
| 968 | |
| 969 | Abbreviations are disabled if the 'paste' option is on. |
| 970 | |
| 971 | *:abbreviate-local* *:abbreviate-<buffer>* |
| 972 | Just like mappings, abbreviations can be local to a buffer. This is mostly |
| 973 | used in a |filetype-plugin| file. Example for a C plugin file: > |
| 974 | :abb <buffer> FF for (i = 0; i < ; ++i) |
| 975 | < |
| 976 | *:ab* *:abbreviate* |
| 977 | :ab[breviate] list all abbreviations. The character in the first |
| 978 | column indicates the mode where the abbreviation is |
| 979 | used: 'i' for insert mode, 'c' for Command-line |
| 980 | mode, '!' for both. These are the same as for |
| 981 | mappings, see |map-listing|. |
| 982 | |
Bram Moolenaar | e344bea | 2005-09-01 20:46:49 +0000 | [diff] [blame] | 983 | *:abbreviate-verbose* |
| 984 | When 'verbose' is non-zero, listing an abbreviation will also display where it |
| 985 | was last defined. Example: > |
| 986 | |
| 987 | :verbose abbreviate |
Bram Moolenaar | c9b4b05 | 2006-04-30 18:54:39 +0000 | [diff] [blame] | 988 | ! teh the |
Bram Moolenaar | e344bea | 2005-09-01 20:46:49 +0000 | [diff] [blame] | 989 | Last set from /home/abcd/vim/abbr.vim |
| 990 | |
| 991 | See |:verbose-cmd| for more information. |
| 992 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 993 | :ab[breviate] {lhs} list the abbreviations that start with {lhs} |
| 994 | You may need to insert a CTRL-V (type it twice) to |
| 995 | avoid that a typed {lhs} is expanded, since |
| 996 | command-line abbreviations apply here. |
| 997 | |
Bram Moolenaar | 251e191 | 2011-06-19 05:09:16 +0200 | [diff] [blame] | 998 | :ab[breviate] [<expr>] [<buffer>] {lhs} {rhs} |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 999 | add abbreviation for {lhs} to {rhs}. If {lhs} already |
| 1000 | existed it is replaced with the new {rhs}. {rhs} may |
| 1001 | contain spaces. |
Bram Moolenaar | fc1421e | 2006-04-20 22:17:20 +0000 | [diff] [blame] | 1002 | See |:map-<expr>| for the optional <expr> argument. |
Bram Moolenaar | 251e191 | 2011-06-19 05:09:16 +0200 | [diff] [blame] | 1003 | See |:map-<buffer>| for the optional <buffer> argument. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1004 | |
| 1005 | *:una* *:unabbreviate* |
| 1006 | :una[bbreviate] {lhs} Remove abbreviation for {lhs} from the list. If none |
| 1007 | is found, remove abbreviations in which {lhs} matches |
| 1008 | with the {rhs}. This is done so that you can even |
| 1009 | remove abbreviations after expansion. To avoid |
| 1010 | expansion insert a CTRL-V (type it twice). |
| 1011 | |
| 1012 | *:norea* *:noreabbrev* |
Bram Moolenaar | 251e191 | 2011-06-19 05:09:16 +0200 | [diff] [blame] | 1013 | :norea[bbrev] [<expr>] [<buffer>] [lhs] [rhs] |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1014 | same as ":ab", but no remapping for this {rhs} {not |
| 1015 | in Vi} |
| 1016 | |
| 1017 | *:ca* *:cabbrev* |
Bram Moolenaar | 251e191 | 2011-06-19 05:09:16 +0200 | [diff] [blame] | 1018 | :ca[bbrev] [<expr>] [<buffer>] [lhs] [rhs] |
Bram Moolenaar | fc1421e | 2006-04-20 22:17:20 +0000 | [diff] [blame] | 1019 | same as ":ab", but for Command-line mode only. {not |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1020 | in Vi} |
| 1021 | |
| 1022 | *:cuna* *:cunabbrev* |
| 1023 | :cuna[bbrev] {lhs} same as ":una", but for Command-line mode only. {not |
| 1024 | in Vi} |
| 1025 | |
| 1026 | *:cnorea* *:cnoreabbrev* |
Bram Moolenaar | 251e191 | 2011-06-19 05:09:16 +0200 | [diff] [blame] | 1027 | :cnorea[bbrev] [<expr>] [<buffer>] [lhs] [rhs] |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1028 | same as ":ab", but for Command-line mode only and no |
| 1029 | remapping for this {rhs} {not in Vi} |
| 1030 | |
| 1031 | *:ia* *:iabbrev* |
Bram Moolenaar | 251e191 | 2011-06-19 05:09:16 +0200 | [diff] [blame] | 1032 | :ia[bbrev] [<expr>] [<buffer>] [lhs] [rhs] |
Bram Moolenaar | fc1421e | 2006-04-20 22:17:20 +0000 | [diff] [blame] | 1033 | same as ":ab", but for Insert mode only. {not in Vi} |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1034 | |
| 1035 | *:iuna* *:iunabbrev* |
| 1036 | :iuna[bbrev] {lhs} same as ":una", but for insert mode only. {not in |
| 1037 | Vi} |
| 1038 | |
| 1039 | *:inorea* *:inoreabbrev* |
Bram Moolenaar | 251e191 | 2011-06-19 05:09:16 +0200 | [diff] [blame] | 1040 | :inorea[bbrev] [<expr>] [<buffer>] [lhs] [rhs] |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1041 | same as ":ab", but for Insert mode only and no |
| 1042 | remapping for this {rhs} {not in Vi} |
| 1043 | |
| 1044 | *:abc* *:abclear* |
Bram Moolenaar | 251e191 | 2011-06-19 05:09:16 +0200 | [diff] [blame] | 1045 | :abc[lear] [<buffer>] Remove all abbreviations. {not in Vi} |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1046 | |
| 1047 | *:iabc* *:iabclear* |
Bram Moolenaar | 251e191 | 2011-06-19 05:09:16 +0200 | [diff] [blame] | 1048 | :iabc[lear] [<buffer>] Remove all abbreviations for Insert mode. {not in Vi} |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1049 | |
| 1050 | *:cabc* *:cabclear* |
Bram Moolenaar | 251e191 | 2011-06-19 05:09:16 +0200 | [diff] [blame] | 1051 | :cabc[lear] [<buffer>] Remove all abbreviations for Command-line mode. {not |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1052 | in Vi} |
| 1053 | |
| 1054 | *using_CTRL-V* |
| 1055 | It is possible to use special characters in the rhs of an abbreviation. |
| 1056 | CTRL-V has to be used to avoid the special meaning of most non printable |
| 1057 | characters. How many CTRL-Vs need to be typed depends on how you enter the |
| 1058 | abbreviation. This also applies to mappings. Let's use an example here. |
| 1059 | |
| 1060 | Suppose you want to abbreviate "esc" to enter an <Esc> character. When you |
| 1061 | type the ":ab" command in Vim, you have to enter this: (here ^V is a CTRL-V |
| 1062 | and ^[ is <Esc>) |
| 1063 | |
| 1064 | You type: ab esc ^V^V^V^V^V^[ |
| 1065 | |
| 1066 | All keyboard input is subjected to ^V quote interpretation, so |
| 1067 | the first, third, and fifth ^V characters simply allow the second, |
| 1068 | and fourth ^Vs, and the ^[, to be entered into the command-line. |
| 1069 | |
| 1070 | You see: ab esc ^V^V^[ |
| 1071 | |
| 1072 | The command-line contains two actual ^Vs before the ^[. This is |
| 1073 | how it should appear in your .exrc file, if you choose to go that |
| 1074 | route. The first ^V is there to quote the second ^V; the :ab |
| 1075 | command uses ^V as its own quote character, so you can include quoted |
Bram Moolenaar | 8169525 | 2004-12-29 20:58:21 +0000 | [diff] [blame] | 1076 | whitespace or the | character in the abbreviation. The :ab command |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1077 | doesn't do anything special with the ^[ character, so it doesn't need |
| 1078 | to be quoted. (Although quoting isn't harmful; that's why typing 7 |
| 1079 | [but not 8!] ^Vs works.) |
| 1080 | |
| 1081 | Stored as: esc ^V^[ |
| 1082 | |
| 1083 | After parsing, the abbreviation's short form ("esc") and long form |
| 1084 | (the two characters "^V^[") are stored in the abbreviation table. |
| 1085 | If you give the :ab command with no arguments, this is how the |
| 1086 | abbreviation will be displayed. |
| 1087 | |
| 1088 | Later, when the abbreviation is expanded because the user typed in |
| 1089 | the word "esc", the long form is subjected to the same type of |
| 1090 | ^V interpretation as keyboard input. So the ^V protects the ^[ |
Bram Moolenaar | 8169525 | 2004-12-29 20:58:21 +0000 | [diff] [blame] | 1091 | character from being interpreted as the "exit Insert mode" character. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1092 | Instead, the ^[ is inserted into the text. |
| 1093 | |
| 1094 | Expands to: ^[ |
| 1095 | |
| 1096 | [example given by Steve Kirkendall] |
| 1097 | |
| 1098 | ============================================================================== |
| 1099 | 3. Local mappings and functions *script-local* |
| 1100 | |
| 1101 | When using several Vim script files, there is the danger that mappings and |
| 1102 | functions used in one script use the same name as in other scripts. To avoid |
| 1103 | this, they can be made local to the script. |
| 1104 | |
| 1105 | *<SID>* *<SNR>* *E81* |
| 1106 | The string "<SID>" can be used in a mapping or menu. This requires that the |
| 1107 | '<' flag is not present in 'cpoptions'. |
| 1108 | When executing the map command, Vim will replace "<SID>" with the special |
| 1109 | key code <SNR>, followed by a number that's unique for the script, and an |
| 1110 | underscore. Example: > |
| 1111 | :map <SID>Add |
| 1112 | could define a mapping "<SNR>23_Add". |
| 1113 | |
| 1114 | When defining a function in a script, "s:" can be prepended to the name to |
| 1115 | make it local to the script. But when a mapping is executed from outside of |
| 1116 | the script, it doesn't know in which script the function was defined. To |
| 1117 | avoid this problem, use "<SID>" instead of "s:". The same translation is done |
| 1118 | as for mappings. This makes it possible to define a call to the function in |
Bram Moolenaar | 8169525 | 2004-12-29 20:58:21 +0000 | [diff] [blame] | 1119 | a mapping. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1120 | |
| 1121 | When a local function is executed, it runs in the context of the script it was |
| 1122 | defined in. This means that new functions and mappings it defines can also |
| 1123 | use "s:" or "<SID>" and it will use the same unique number as when the |
| 1124 | function itself was defined. Also, the "s:var" local script variables can be |
| 1125 | used. |
| 1126 | |
| 1127 | When executing an autocommand or a user command, it will run in the context of |
| 1128 | the script it was defined in. This makes it possible that the command calls a |
| 1129 | local function or uses a local mapping. |
| 1130 | |
| 1131 | Otherwise, using "<SID>" outside of a script context is an error. |
| 1132 | |
| 1133 | If you need to get the script number to use in a complicated script, you can |
Bram Moolenaar | 4770d09 | 2006-01-12 23:22:24 +0000 | [diff] [blame] | 1134 | use this function: > |
| 1135 | function s:SID() |
| 1136 | return matchstr(expand('<sfile>'), '<SNR>\zs\d\+\ze_SID$') |
| 1137 | endfun |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1138 | |
| 1139 | The "<SNR>" will be shown when listing functions and mappings. This is useful |
| 1140 | to find out what they are defined to. |
| 1141 | |
| 1142 | The |:scriptnames| command can be used to see which scripts have been sourced |
| 1143 | and what their <SNR> number is. |
| 1144 | |
Bram Moolenaar | db84e45 | 2010-08-15 13:50:43 +0200 | [diff] [blame] | 1145 | This is all {not in Vi} and {not available when compiled without the |+eval| |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1146 | feature}. |
| 1147 | |
| 1148 | ============================================================================== |
| 1149 | 4. User-defined commands *user-commands* |
| 1150 | |
Bram Moolenaar | 402d2fe | 2005-04-15 21:00:38 +0000 | [diff] [blame] | 1151 | It is possible to define your own Ex commands. A user-defined command can act |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1152 | just like a built-in command (it can have a range or arguments, arguments can |
| 1153 | be completed as filenames or buffer names, etc), except that when the command |
Bram Moolenaar | 8f3f58f | 2010-01-06 20:52:26 +0100 | [diff] [blame] | 1154 | is executed, it is transformed into a normal Ex command and then executed. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1155 | |
| 1156 | For starters: See section |40.2| in the user manual. |
| 1157 | |
Bram Moolenaar | 166af9b | 2010-11-16 20:34:40 +0100 | [diff] [blame] | 1158 | *E183* *E841* *user-cmd-ambiguous* |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1159 | All user defined commands must start with an uppercase letter, to avoid |
Bram Moolenaar | 166af9b | 2010-11-16 20:34:40 +0100 | [diff] [blame] | 1160 | confusion with builtin commands. Exceptions are these builtin commands: |
| 1161 | :Next |
| 1162 | :X |
| 1163 | They cannot be used for a user defined command. ":Print" is also an existing |
| 1164 | command, but it is deprecated and can be overruled. |
| 1165 | |
| 1166 | The other characters of the user command can be uppercase letters, lowercase |
| 1167 | letters or digits. When using digits, note that other commands that take a |
| 1168 | numeric argument may become ambiguous. For example, the command ":Cc2" could |
| 1169 | be the user command ":Cc2" without an argument, or the command ":Cc" with |
| 1170 | argument "2". It is advised to put a space between the command name and the |
| 1171 | argument to avoid these problems. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1172 | |
Bram Moolenaar | 402d2fe | 2005-04-15 21:00:38 +0000 | [diff] [blame] | 1173 | When using a user-defined command, the command can be abbreviated. However, if |
| 1174 | an abbreviation is not unique, an error will be issued. Furthermore, a |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1175 | built-in command will always take precedence. |
| 1176 | |
| 1177 | Example: > |
| 1178 | :command Rename ... |
| 1179 | :command Renumber ... |
| 1180 | :Rena " Means "Rename" |
| 1181 | :Renu " Means "Renumber" |
| 1182 | :Ren " Error - ambiguous |
| 1183 | :command Paste ... |
| 1184 | :P " The built-in :Print |
| 1185 | |
| 1186 | It is recommended that full names for user-defined commands are used in |
| 1187 | scripts. |
| 1188 | |
| 1189 | :com[mand] *:com* *:command* |
Bram Moolenaar | 402d2fe | 2005-04-15 21:00:38 +0000 | [diff] [blame] | 1190 | List all user-defined commands. When listing commands, |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1191 | the characters in the first two columns are |
| 1192 | ! Command has the -bang attribute |
| 1193 | " Command has the -register attribute |
| 1194 | b Command is local to current buffer |
| 1195 | (see below for details on attributes) |
Bram Moolenaar | 818078d | 2016-08-27 21:58:42 +0200 | [diff] [blame] | 1196 | The list can be filtered on command name with |
| 1197 | |:filter|, e.g., to list all commands with "Pyth" in |
| 1198 | the name: > |
| 1199 | filter Pyth command |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1200 | |
| 1201 | :com[mand] {cmd} List the user-defined commands that start with {cmd} |
| 1202 | |
Bram Moolenaar | 5b8d8fd | 2005-08-16 23:01:50 +0000 | [diff] [blame] | 1203 | *:command-verbose* |
| 1204 | When 'verbose' is non-zero, listing a command will also display where it was |
| 1205 | last defined. Example: > |
| 1206 | |
| 1207 | :verbose command TOhtml |
Bram Moolenaar | c9b4b05 | 2006-04-30 18:54:39 +0000 | [diff] [blame] | 1208 | < Name Args Range Complete Definition ~ |
| 1209 | TOhtml 0 % :call Convert2HTML(<line1>, <line2>) ~ |
| 1210 | Last set from /usr/share/vim/vim-7.0/plugin/tohtml.vim ~ |
| 1211 | |
Bram Moolenaar | 5195e45 | 2005-08-19 20:32:47 +0000 | [diff] [blame] | 1212 | See |:verbose-cmd| for more information. |
Bram Moolenaar | 5b8d8fd | 2005-08-16 23:01:50 +0000 | [diff] [blame] | 1213 | |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1214 | *E174* *E182* |
| 1215 | :com[mand][!] [{attr}...] {cmd} {rep} |
| 1216 | Define a user command. The name of the command is |
Bram Moolenaar | 402d2fe | 2005-04-15 21:00:38 +0000 | [diff] [blame] | 1217 | {cmd} and its replacement text is {rep}. The command's |
| 1218 | attributes (see below) are {attr}. If the command |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1219 | already exists, an error is reported, unless a ! is |
| 1220 | specified, in which case the command is redefined. |
| 1221 | |
| 1222 | :delc[ommand] {cmd} *:delc* *:delcommand* *E184* |
| 1223 | Delete the user-defined command {cmd}. |
| 1224 | |
| 1225 | :comc[lear] *:comc* *:comclear* |
| 1226 | Delete all user-defined commands. |
| 1227 | |
| 1228 | Command attributes |
| 1229 | |
Bram Moolenaar | 8f3f58f | 2010-01-06 20:52:26 +0100 | [diff] [blame] | 1230 | User-defined commands are treated by Vim just like any other Ex commands. They |
Bram Moolenaar | 402d2fe | 2005-04-15 21:00:38 +0000 | [diff] [blame] | 1231 | can have arguments, or have a range specified. Arguments are subject to |
| 1232 | completion as filenames, buffers, etc. Exactly how this works depends upon the |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1233 | command's attributes, which are specified when the command is defined. |
| 1234 | |
| 1235 | There are a number of attributes, split into four categories: argument |
Bram Moolenaar | 402d2fe | 2005-04-15 21:00:38 +0000 | [diff] [blame] | 1236 | handling, completion behavior, range handling, and special cases. The |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1237 | attributes are described below, by category. |
| 1238 | |
Bram Moolenaar | 5c5b094 | 2007-05-06 12:07:59 +0000 | [diff] [blame] | 1239 | Argument handling *E175* *E176* *:command-nargs* |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1240 | |
| 1241 | By default, a user defined command will take no arguments (and an error is |
Bram Moolenaar | 402d2fe | 2005-04-15 21:00:38 +0000 | [diff] [blame] | 1242 | reported if any are supplied). However, it is possible to specify that the |
| 1243 | command can take arguments, using the -nargs attribute. Valid cases are: |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1244 | |
| 1245 | -nargs=0 No arguments are allowed (the default) |
Bram Moolenaar | 53bfca2 | 2012-04-13 23:04:47 +0200 | [diff] [blame] | 1246 | -nargs=1 Exactly one argument is required, it includes spaces |
Bram Moolenaar | 446beb4 | 2011-05-10 17:18:44 +0200 | [diff] [blame] | 1247 | -nargs=* Any number of arguments are allowed (0, 1, or many), |
| 1248 | separated by white space |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1249 | -nargs=? 0 or 1 arguments are allowed |
| 1250 | -nargs=+ Arguments must be supplied, but any number are allowed |
| 1251 | |
Bram Moolenaar | 3416214 | 2007-05-12 13:12:19 +0000 | [diff] [blame] | 1252 | Arguments are considered to be separated by (unescaped) spaces or tabs in this |
Bram Moolenaar | 446beb4 | 2011-05-10 17:18:44 +0200 | [diff] [blame] | 1253 | context, except when there is one argument, then the white space is part of |
| 1254 | the argument. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1255 | |
| 1256 | Note that arguments are used as text, not as expressions. Specifically, |
| 1257 | "s:var" will use the script-local variable in the script where the command was |
| 1258 | defined, not where it is invoked! Example: |
| 1259 | script1.vim: > |
| 1260 | :let s:error = "None" |
| 1261 | :command -nargs=1 Error echoerr <args> |
| 1262 | < script2.vim: > |
| 1263 | :source script1.vim |
| 1264 | :let s:error = "Wrong!" |
| 1265 | :Error s:error |
Bram Moolenaar | a7241f5 | 2008-06-24 20:39:31 +0000 | [diff] [blame] | 1266 | Executing script2.vim will result in "None" being echoed. Not what you |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1267 | intended! Calling a function may be an alternative. |
| 1268 | |
Bram Moolenaar | 5c5b094 | 2007-05-06 12:07:59 +0000 | [diff] [blame] | 1269 | Completion behavior *:command-completion* *E179* |
| 1270 | *E180* *E181* *:command-complete* |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1271 | By default, the arguments of user defined commands do not undergo completion. |
| 1272 | However, by specifying one or the other of the following attributes, argument |
| 1273 | completion can be enabled: |
| 1274 | |
Bram Moolenaar | cd43eff | 2018-03-29 15:55:38 +0200 | [diff] [blame] | 1275 | -complete=arglist file names in argument list |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1276 | -complete=augroup autocmd groups |
| 1277 | -complete=buffer buffer names |
Bram Moolenaar | 5ae636b | 2012-04-30 18:48:53 +0200 | [diff] [blame] | 1278 | -complete=behave :behave suboptions |
Bram Moolenaar | e9edd7f | 2011-07-20 16:37:24 +0200 | [diff] [blame] | 1279 | -complete=color color schemes |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1280 | -complete=command Ex command (and arguments) |
Bram Moolenaar | e9edd7f | 2011-07-20 16:37:24 +0200 | [diff] [blame] | 1281 | -complete=compiler compilers |
Bram Moolenaar | 4a74803 | 2010-09-30 21:47:56 +0200 | [diff] [blame] | 1282 | -complete=cscope |:cscope| suboptions |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1283 | -complete=dir directory names |
| 1284 | -complete=environment environment variable names |
| 1285 | -complete=event autocommand events |
| 1286 | -complete=expression Vim expression |
| 1287 | -complete=file file and directory names |
Bram Moolenaar | e9edd7f | 2011-07-20 16:37:24 +0200 | [diff] [blame] | 1288 | -complete=file_in_path file and directory names in |'path'| |
Bram Moolenaar | a26559b | 2010-07-31 14:59:19 +0200 | [diff] [blame] | 1289 | -complete=filetype filetype names |'filetype'| |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1290 | -complete=function function name |
| 1291 | -complete=help help subjects |
| 1292 | -complete=highlight highlight groups |
Bram Moolenaar | 5ae636b | 2012-04-30 18:48:53 +0200 | [diff] [blame] | 1293 | -complete=history :history suboptions |
Bram Moolenaar | e9edd7f | 2011-07-20 16:37:24 +0200 | [diff] [blame] | 1294 | -complete=locale locale names (as output of locale -a) |
Bram Moolenaar | cae92dc | 2017-08-06 15:22:15 +0200 | [diff] [blame] | 1295 | -complete=mapclear buffer argument |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1296 | -complete=mapping mapping name |
| 1297 | -complete=menu menus |
Bram Moolenaar | 9e507ca | 2016-10-15 15:39:39 +0200 | [diff] [blame] | 1298 | -complete=messages |:messages| suboptions |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1299 | -complete=option options |
Bram Moolenaar | 063b9d1 | 2016-07-09 20:21:48 +0200 | [diff] [blame] | 1300 | -complete=packadd optional package |pack-add| names |
Bram Moolenaar | a26559b | 2010-07-31 14:59:19 +0200 | [diff] [blame] | 1301 | -complete=shellcmd Shell command |
Bram Moolenaar | 4a74803 | 2010-09-30 21:47:56 +0200 | [diff] [blame] | 1302 | -complete=sign |:sign| suboptions |
Bram Moolenaar | a26559b | 2010-07-31 14:59:19 +0200 | [diff] [blame] | 1303 | -complete=syntax syntax file names |'syntax'| |
Bram Moolenaar | cd9c462 | 2013-06-08 15:24:48 +0200 | [diff] [blame] | 1304 | -complete=syntime |:syntime| suboptions |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1305 | -complete=tag tags |
| 1306 | -complete=tag_listfiles tags, file names are shown when CTRL-D is hit |
Bram Moolenaar | 2430586 | 2012-08-15 14:05:05 +0200 | [diff] [blame] | 1307 | -complete=user user names |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1308 | -complete=var user variables |
| 1309 | -complete=custom,{func} custom completion, defined via {func} |
Bram Moolenaar | a466c99 | 2005-07-09 21:03:22 +0000 | [diff] [blame] | 1310 | -complete=customlist,{func} custom completion, defined via {func} |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1311 | |
Bram Moolenaar | 3a991dd | 2014-10-02 01:41:41 +0200 | [diff] [blame] | 1312 | Note: That some completion methods might expand environment variables. |
| 1313 | |
Bram Moolenaar | a5792f5 | 2005-11-23 21:25:05 +0000 | [diff] [blame] | 1314 | |
| 1315 | Custom completion *:command-completion-custom* |
| 1316 | *:command-completion-customlist* |
| 1317 | *E467* *E468* |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1318 | It is possible to define customized completion schemes via the "custom,{func}" |
Bram Moolenaar | a466c99 | 2005-07-09 21:03:22 +0000 | [diff] [blame] | 1319 | or the "customlist,{func}" completion argument. The {func} part should be a |
Bram Moolenaar | a7241f5 | 2008-06-24 20:39:31 +0000 | [diff] [blame] | 1320 | function with the following signature: > |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1321 | |
| 1322 | :function {func}(ArgLead, CmdLine, CursorPos) |
| 1323 | |
Bram Moolenaar | a466c99 | 2005-07-09 21:03:22 +0000 | [diff] [blame] | 1324 | The function need not use all these arguments. The function should provide the |
| 1325 | completion candidates as the return value. |
| 1326 | |
| 1327 | For the "custom" argument, the function should return the completion |
| 1328 | candidates one per line in a newline separated string. |
| 1329 | |
| 1330 | For the "customlist" argument, the function should return the completion |
Bram Moolenaar | a5792f5 | 2005-11-23 21:25:05 +0000 | [diff] [blame] | 1331 | candidates as a Vim List. Non-string items in the list are ignored. |
Bram Moolenaar | a466c99 | 2005-07-09 21:03:22 +0000 | [diff] [blame] | 1332 | |
| 1333 | The function arguments are: |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1334 | ArgLead the leading portion of the argument currently being |
| 1335 | completed on |
| 1336 | CmdLine the entire command line |
Bram Moolenaar | a5792f5 | 2005-11-23 21:25:05 +0000 | [diff] [blame] | 1337 | CursorPos the cursor position in it (byte index) |
Bram Moolenaar | a466c99 | 2005-07-09 21:03:22 +0000 | [diff] [blame] | 1338 | The function may use these for determining context. For the "custom" |
| 1339 | argument, it is not necessary to filter candidates against the (implicit |
Bram Moolenaar | 8f3f58f | 2010-01-06 20:52:26 +0100 | [diff] [blame] | 1340 | pattern in) ArgLead. Vim will filter the candidates with its regexp engine |
Bram Moolenaar | a466c99 | 2005-07-09 21:03:22 +0000 | [diff] [blame] | 1341 | after function return, and this is probably more efficient in most cases. For |
| 1342 | the "customlist" argument, Vim will not filter the returned completion |
| 1343 | candidates and the user supplied function should filter the candidates. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1344 | |
| 1345 | The following example lists user names to a Finger command > |
| 1346 | :com -complete=custom,ListUsers -nargs=1 Finger !finger <args> |
| 1347 | :fun ListUsers(A,L,P) |
| 1348 | : return system("cut -d: -f1 /etc/passwd") |
| 1349 | :endfun |
| 1350 | |
Bram Moolenaar | a466c99 | 2005-07-09 21:03:22 +0000 | [diff] [blame] | 1351 | The following example completes filenames from the directories specified in |
| 1352 | the 'path' option: > |
| 1353 | :com -nargs=1 -bang -complete=customlist,EditFileComplete |
| 1354 | \ EditFile edit<bang> <args> |
| 1355 | :fun EditFileComplete(A,L,P) |
Bram Moolenaar | 8f3f58f | 2010-01-06 20:52:26 +0100 | [diff] [blame] | 1356 | : return split(globpath(&path, a:A), "\n") |
Bram Moolenaar | a466c99 | 2005-07-09 21:03:22 +0000 | [diff] [blame] | 1357 | :endfun |
| 1358 | < |
Bram Moolenaar | 5ac3b1a | 2010-07-27 22:50:36 +0200 | [diff] [blame] | 1359 | This example does not work for file names with spaces! |
| 1360 | |
Bram Moolenaar | a5792f5 | 2005-11-23 21:25:05 +0000 | [diff] [blame] | 1361 | |
Bram Moolenaar | 5c5b094 | 2007-05-06 12:07:59 +0000 | [diff] [blame] | 1362 | Range handling *E177* *E178* *:command-range* |
| 1363 | *:command-count* |
Bram Moolenaar | 402d2fe | 2005-04-15 21:00:38 +0000 | [diff] [blame] | 1364 | By default, user-defined commands do not accept a line number range. However, |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1365 | it is possible to specify that the command does take a range (the -range |
| 1366 | attribute), or that it takes an arbitrary count value, either in the line |
| 1367 | number position (-range=N, like the |:split| command) or as a "count" |
Bram Moolenaar | 5c5b094 | 2007-05-06 12:07:59 +0000 | [diff] [blame] | 1368 | argument (-count=N, like the |:Next| command). The count will then be |
| 1369 | available in the argument with |<count>|. |
| 1370 | |
| 1371 | Possible attributes are: |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1372 | |
| 1373 | -range Range allowed, default is current line |
| 1374 | -range=% Range allowed, default is whole file (1,$) |
| 1375 | -range=N A count (default N) which is specified in the line |
Bram Moolenaar | 8e5af3e | 2011-04-28 19:02:44 +0200 | [diff] [blame] | 1376 | number position (like |:split|); allows for zero line |
| 1377 | number. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1378 | -count=N A count (default N) which is specified either in the line |
Bram Moolenaar | 32e7b2d | 2005-02-27 22:36:47 +0000 | [diff] [blame] | 1379 | number position, or as an initial argument (like |:Next|). |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1380 | Specifying -count (without a default) acts like -count=0 |
| 1381 | |
| 1382 | Note that -range=N and -count=N are mutually exclusive - only one should be |
| 1383 | specified. |
| 1384 | |
Bram Moolenaar | aa3b15d | 2016-04-21 08:53:19 +0200 | [diff] [blame] | 1385 | *:command-addr* |
Bram Moolenaar | f1d6ccf | 2014-12-08 04:16:44 +0100 | [diff] [blame] | 1386 | It is possible that the special characters in the range like ., $ or % which |
| 1387 | by default correspond to the current line, last line and the whole buffer, |
| 1388 | relate to arguments, (loaded) buffers, windows or tab pages. |
| 1389 | |
| 1390 | Possible values are: |
| 1391 | -addr=lines Range of lines (this is the default) |
| 1392 | -addr=arguments Range for arguments |
| 1393 | -addr=buffers Range for buffers (also not loaded buffers) |
| 1394 | -addr=loaded_buffers Range for loaded buffers |
| 1395 | -addr=windows Range for windows |
| 1396 | -addr=tabs Range for tab pages |
| 1397 | |
Bram Moolenaar | 5c5b094 | 2007-05-06 12:07:59 +0000 | [diff] [blame] | 1398 | Special cases *:command-bang* *:command-bar* |
| 1399 | *:command-register* *:command-buffer* |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1400 | There are some special cases as well: |
| 1401 | |
| 1402 | -bang The command can take a ! modifier (like :q or :w) |
| 1403 | -bar The command can be followed by a "|" and another command. |
| 1404 | A "|" inside the command argument is not allowed then. |
| 1405 | Also checks for a " to start a comment. |
| 1406 | -register The first argument to the command can be an optional |
| 1407 | register name (like :del, :put, :yank). |
| 1408 | -buffer The command will only be available in the current buffer. |
| 1409 | |
| 1410 | In the cases of the -count and -register attributes, if the optional argument |
| 1411 | is supplied, it is removed from the argument list and is available to the |
| 1412 | replacement text separately. |
Bram Moolenaar | 7cba6c0 | 2013-09-05 22:13:31 +0200 | [diff] [blame] | 1413 | Note that these arguments can be abbreviated, but that is a deprecated |
| 1414 | feature. Use the full name for new scripts. |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1415 | |
| 1416 | Replacement text |
| 1417 | |
| 1418 | The replacement text for a user defined command is scanned for special escape |
Bram Moolenaar | 402d2fe | 2005-04-15 21:00:38 +0000 | [diff] [blame] | 1419 | sequences, using <...> notation. Escape sequences are replaced with values |
| 1420 | from the entered command line, and all other text is copied unchanged. The |
Bram Moolenaar | 371d540 | 2006-03-20 21:47:49 +0000 | [diff] [blame] | 1421 | resulting string is executed as an Ex command. To avoid the replacement use |
Bram Moolenaar | ed39e1d | 2008-08-09 17:55:22 +0000 | [diff] [blame] | 1422 | <lt> in place of the initial <. Thus to include "<bang>" literally use |
Bram Moolenaar | 371d540 | 2006-03-20 21:47:49 +0000 | [diff] [blame] | 1423 | "<lt>bang>". |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1424 | |
| 1425 | The valid escape sequences are |
| 1426 | |
| 1427 | *<line1>* |
| 1428 | <line1> The starting line of the command range. |
| 1429 | *<line2>* |
| 1430 | <line2> The final line of the command range. |
Bram Moolenaar | c168bd4 | 2017-09-10 17:34:35 +0200 | [diff] [blame] | 1431 | *<range>* |
| 1432 | <range> The number of items in the command range: 0, 1 or 2 |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1433 | *<count>* |
| 1434 | <count> Any count supplied (as described for the '-range' |
| 1435 | and '-count' attributes). |
| 1436 | *<bang>* |
| 1437 | <bang> (See the '-bang' attribute) Expands to a ! if the |
| 1438 | command was executed with a ! modifier, otherwise |
| 1439 | expands to nothing. |
Bram Moolenaar | 63a60de | 2016-06-04 22:08:55 +0200 | [diff] [blame] | 1440 | *<mods>* |
| 1441 | <mods> The command modifiers, if specified. Otherwise, expands to |
Bram Moolenaar | c95a302 | 2016-06-12 23:01:46 +0200 | [diff] [blame] | 1442 | nothing. Supported modifiers are |:aboveleft|, |:belowright|, |
| 1443 | |:botright|, |:browse|, |:confirm|, |:hide|, |:keepalt|, |
Bram Moolenaar | bc8801c | 2016-08-02 21:04:33 +0200 | [diff] [blame] | 1444 | |:keepjumps|, |:keepmarks|, |:keeppatterns|, |:leftabove|, |
| 1445 | |:lockmarks|, |:noswapfile| |:rightbelow|, |:silent|, |:tab|, |
| 1446 | |:topleft|, |:verbose|, and |:vertical|. |
| 1447 | Note that these are not yet supported: |:noautocmd|, |
| 1448 | |:sandbox| and |:unsilent|. |
Bram Moolenaar | 63a60de | 2016-06-04 22:08:55 +0200 | [diff] [blame] | 1449 | Examples: > |
| 1450 | command! -nargs=+ -complete=file MyEdit |
| 1451 | \ for f in expand(<q-args>, 0, 1) | |
| 1452 | \ exe '<mods> split ' . f | |
| 1453 | \ endfor |
| 1454 | |
| 1455 | function! SpecialEdit(files, mods) |
| 1456 | for f in expand(a:files, 0, 1) |
| 1457 | exe a:mods . ' split ' . f |
| 1458 | endfor |
| 1459 | endfunction |
| 1460 | command! -nargs=+ -complete=file Sedit |
| 1461 | \ call SpecialEdit(<q-args>, <q-mods>) |
| 1462 | < |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1463 | *<reg>* *<register>* |
| 1464 | <reg> (See the '-register' attribute) The optional register, |
Bram Moolenaar | 402d2fe | 2005-04-15 21:00:38 +0000 | [diff] [blame] | 1465 | if specified. Otherwise, expands to nothing. <register> |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1466 | is a synonym for this. |
| 1467 | *<args>* |
| 1468 | <args> The command arguments, exactly as supplied (but as |
| 1469 | noted above, any count or register can consume some |
| 1470 | of the arguments, which are then not part of <args>). |
| 1471 | <lt> A single '<' (Less-Than) character. This is needed if you |
| 1472 | want to get a literal copy of one of these escape sequences |
| 1473 | into the expansion - for example, to get <bang>, use |
| 1474 | <lt>bang>. |
| 1475 | |
| 1476 | *<q-args>* |
| 1477 | If the first two characters of an escape sequence are "q-" (for example, |
| 1478 | <q-args>) then the value is quoted in such a way as to make it a valid value |
| 1479 | for use in an expression. This uses the argument as one single value. |
Bram Moolenaar | 51485f0 | 2005-06-04 21:55:20 +0000 | [diff] [blame] | 1480 | When there is no argument <q-args> is an empty string. |
Bram Moolenaar | 552f8a1 | 2007-03-08 17:12:08 +0000 | [diff] [blame] | 1481 | *<f-args>* |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1482 | To allow commands to pass their arguments on to a user-defined function, there |
Bram Moolenaar | 402d2fe | 2005-04-15 21:00:38 +0000 | [diff] [blame] | 1483 | is a special form <f-args> ("function args"). This splits the command |
Bram Moolenaar | 3416214 | 2007-05-12 13:12:19 +0000 | [diff] [blame] | 1484 | arguments at spaces and tabs, quotes each argument individually, and the |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1485 | <f-args> sequence is replaced by the comma-separated list of quoted arguments. |
Bram Moolenaar | c9b4b05 | 2006-04-30 18:54:39 +0000 | [diff] [blame] | 1486 | See the Mycmd example below. If no arguments are given <f-args> is removed. |
Bram Moolenaar | 552f8a1 | 2007-03-08 17:12:08 +0000 | [diff] [blame] | 1487 | To embed whitespace into an argument of <f-args>, prepend a backslash. |
| 1488 | <f-args> replaces every pair of backslashes (\\) with one backslash. A |
| 1489 | backslash followed by a character other than white space or a backslash |
| 1490 | remains unmodified. Overview: |
| 1491 | |
| 1492 | command <f-args> ~ |
| 1493 | XX ab 'ab' |
| 1494 | XX a\b 'a\b' |
| 1495 | XX a\ b 'a b' |
| 1496 | XX a\ b 'a ', 'b' |
| 1497 | XX a\\b 'a\b' |
| 1498 | XX a\\ b 'a\', 'b' |
| 1499 | XX a\\\b 'a\\b' |
| 1500 | XX a\\\ b 'a\ b' |
| 1501 | XX a\\\\b 'a\\b' |
| 1502 | XX a\\\\ b 'a\\', 'b' |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1503 | |
| 1504 | Examples > |
| 1505 | |
| 1506 | " Delete everything after here to the end |
| 1507 | :com Ddel +,$d |
| 1508 | |
| 1509 | " Rename the current buffer |
| 1510 | :com -nargs=1 -bang -complete=file Ren f <args>|w<bang> |
| 1511 | |
| 1512 | " Replace a range with the contents of a file |
| 1513 | " (Enter this all as one line) |
| 1514 | :com -range -nargs=1 -complete=file |
| 1515 | Replace <line1>-pu_|<line1>,<line2>d|r <args>|<line1>d |
| 1516 | |
| 1517 | " Count the number of lines in the range |
Bram Moolenaar | 8169525 | 2004-12-29 20:58:21 +0000 | [diff] [blame] | 1518 | :com! -range -nargs=0 Lines echo <line2> - <line1> + 1 "lines" |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1519 | |
| 1520 | " Call a user function (example of <f-args>) |
| 1521 | :com -nargs=* Mycmd call Myfunc(<f-args>) |
| 1522 | |
| 1523 | When executed as: > |
| 1524 | :Mycmd arg1 arg2 |
| 1525 | This will invoke: > |
| 1526 | :call Myfunc("arg1","arg2") |
| 1527 | |
| 1528 | :" A more substantial example |
| 1529 | :function Allargs(command) |
Bram Moolenaar | a7241f5 | 2008-06-24 20:39:31 +0000 | [diff] [blame] | 1530 | : let i = 0 |
| 1531 | : while i < argc() |
| 1532 | : if filereadable(argv(i)) |
| 1533 | : execute "e " . argv(i) |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1534 | : execute a:command |
| 1535 | : endif |
| 1536 | : let i = i + 1 |
| 1537 | : endwhile |
| 1538 | :endfunction |
| 1539 | :command -nargs=+ -complete=command Allargs call Allargs(<q-args>) |
| 1540 | |
| 1541 | The command Allargs takes any Vim command(s) as argument and executes it on all |
| 1542 | files in the argument list. Usage example (note use of the "e" flag to ignore |
| 1543 | errors and the "update" command to write modified buffers): > |
| 1544 | :Allargs %s/foo/bar/ge|update |
| 1545 | This will invoke: > |
| 1546 | :call Allargs("%s/foo/bar/ge|update") |
| 1547 | < |
Bram Moolenaar | 8f3f58f | 2010-01-06 20:52:26 +0100 | [diff] [blame] | 1548 | When defining a user command in a script, it will be able to call functions |
Bram Moolenaar | 071d427 | 2004-06-13 20:20:40 +0000 | [diff] [blame] | 1549 | local to the script and use mappings local to the script. When the user |
| 1550 | invokes the user command, it will run in the context of the script it was |
| 1551 | defined in. This matters if |<SID>| is used in a command. |
| 1552 | |
| 1553 | vim:tw=78:ts=8:ft=help:norl: |