1*usr_40.txt* For Vim version 7.3. Last change: 2006 Jun 21 2 3 VIM USER MANUAL - by Bram Moolenaar 4 5 Make new commands 6 7 8Vim is an extensible editor. You can take a sequence of commands you use 9often and turn it into a new command. Or redefine an existing command. 10Autocommands make it possible to execute commands automatically. 11 12|40.1| Key mapping 13|40.2| Defining command-line commands 14|40.3| Autocommands 15 16 Next chapter: |usr_41.txt| Write a Vim script 17 Previous chapter: |usr_32.txt| The undo tree 18Table of contents: |usr_toc.txt| 19 20============================================================================== 21*40.1* Key mapping 22 23A simple mapping was explained in section |05.3|. The principle is that one 24sequence of key strokes is translated into another sequence of key strokes. 25This is a simple, yet powerful mechanism. 26 The simplest form is that one key is mapped to a sequence of keys. Since 27the function keys, except <F1>, have no predefined meaning in Vim, these are 28good choices to map. Example: > 29 30 :map <F2> GoDate: <Esc>:read !date<CR>kJ 31 32This shows how three modes are used. After going to the last line with "G", 33the "o" command opens a new line and starts Insert mode. The text "Date: " is 34inserted and <Esc> takes you out of insert mode. 35 Notice the use of special keys inside <>. This is called angle bracket 36notation. You type these as separate characters, not by pressing the key 37itself. This makes the mappings better readable and you can copy and paste 38the text without problems. 39 The ":" character takes Vim to the command line. The ":read !date" command 40reads the output from the "date" command and appends it below the current 41line. The <CR> is required to execute the ":read" command. 42 At this point of execution the text looks like this: 43 44 Date: ~ 45 Fri Jun 15 12:54:34 CEST 2001 ~ 46 47Now "kJ" moves the cursor up and joins the lines together. 48 To decide which key or keys you use for mapping, see |map-which-keys|. 49 50 51MAPPING AND MODES 52 53The ":map" command defines remapping for keys in Normal mode. You can also 54define mappings for other modes. For example, ":imap" applies to Insert mode. 55You can use it to insert a date below the cursor: > 56 57 :imap <F2> <CR>Date: <Esc>:read !date<CR>kJ 58 59It looks a lot like the mapping for <F2> in Normal mode, only the start is 60different. The <F2> mapping for Normal mode is still there. Thus you can map 61the same key differently for each mode. 62 Notice that, although this mapping starts in Insert mode, it ends in Normal 63mode. If you want it to continue in Insert mode, append an "a" to the 64mapping. 65 66Here is an overview of map commands and in which mode they work: 67 68 :map Normal, Visual and Operator-pending 69 :vmap Visual 70 :nmap Normal 71 :omap Operator-pending 72 :map! Insert and Command-line 73 :imap Insert 74 :cmap Command-line 75 76Operator-pending mode is when you typed an operator character, such as "d" or 77"y", and you are expected to type the motion command or a text object. Thus 78when you type "dw", the "w" is entered in operator-pending mode. 79 80Suppose that you want to define <F7> so that the command d<F7> deletes a C 81program block (text enclosed in curly braces, {}). Similarly y<F7> would yank 82the program block into the unnamed register. Therefore, what you need to do 83is to define <F7> to select the current program block. You can do this with 84the following command: > 85 86 :omap <F7> a{ 87 88This causes <F7> to perform a select block "a{" in operator-pending mode, just 89like you typed it. This mapping is useful if typing a { on your keyboard is a 90bit difficult. 91 92 93LISTING MAPPINGS 94 95To see the currently defined mappings, use ":map" without arguments. Or one 96of the variants that include the mode in which they work. The output could 97look like this: 98 99 _g :call MyGrep(1)<CR> ~ 100 v <F2> :s/^/> /<CR>:noh<CR>`` ~ 101 n <F2> :.,$s/^/> /<CR>:noh<CR>`` ~ 102 <xHome> <Home> 103 <xEnd> <End> 104 105 106The first column of the list shows in which mode the mapping is effective. 107This is "n" for Normal mode, "i" for Insert mode, etc. A blank is used for a 108mapping defined with ":map", thus effective in both Normal and Visual mode. 109 One useful purpose of listing the mapping is to check if special keys in <> 110form have been recognized (this only works when color is supported). For 111example, when <Esc> is displayed in color, it stands for the escape character. 112When it has the same color as the other text, it is five characters. 113 114 115REMAPPING 116 117The result of a mapping is inspected for other mappings in it. For example, 118the mappings for <F2> above could be shortened to: > 119 120 :map <F2> G<F3> 121 :imap <F2> <Esc><F3> 122 :map <F3> oDate: <Esc>:read !date<CR>kJ 123 124For Normal mode <F2> is mapped to go to the last line, and then behave like 125<F3> was pressed. In Insert mode <F2> stops Insert mode with <Esc> and then 126also uses <F3>. Then <F3> is mapped to do the actual work. 127 128Suppose you hardly ever use Ex mode, and want to use the "Q" command to format 129text (this was so in old versions of Vim). This mapping will do it: > 130 131 :map Q gq 132 133But, in rare cases you need to use Ex mode anyway. Let's map "gQ" to Q, so 134that you can still go to Ex mode: > 135 136 :map gQ Q 137 138What happens now is that when you type "gQ" it is mapped to "Q". So far so 139good. But then "Q" is mapped to "gq", thus typing "gQ" results in "gq", and 140you don't get to Ex mode at all. 141 To avoid keys to be mapped again, use the ":noremap" command: > 142 143 :noremap gQ Q 144 145Now Vim knows that the "Q" is not to be inspected for mappings that apply to 146it. There is a similar command for every mode: 147 148 :noremap Normal, Visual and Operator-pending 149 :vnoremap Visual 150 :nnoremap Normal 151 :onoremap Operator-pending 152 :noremap! Insert and Command-line 153 :inoremap Insert 154 :cnoremap Command-line 155 156 157RECURSIVE MAPPING 158 159When a mapping triggers itself, it will run forever. This can be used to 160repeat an action an unlimited number of times. 161 For example, you have a list of files that contain a version number in the 162first line. You edit these files with "vim *.txt". You are now editing the 163first file. Define this mapping: > 164 165 :map ,, :s/5.1/5.2/<CR>:wnext<CR>,, 166 167Now you type ",,". This triggers the mapping. It replaces "5.1" with "5.2" 168in the first line. Then it does a ":wnext" to write the file and edit the 169next one. The mapping ends in ",,". This triggers the same mapping again, 170thus doing the substitution, etc. 171 This continues until there is an error. In this case it could be a file 172where the substitute command doesn't find a match for "5.1". You can then 173make a change to insert "5.1" and continue by typing ",," again. Or the 174":wnext" fails, because you are in the last file in the list. 175 When a mapping runs into an error halfway, the rest of the mapping is 176discarded. CTRL-C interrupts the mapping (CTRL-Break on MS-Windows). 177 178 179DELETE A MAPPING 180 181To remove a mapping use the ":unmap" command. Again, the mode the unmapping 182applies to depends on the command used: 183 184 :unmap Normal, Visual and Operator-pending 185 :vunmap Visual 186 :nunmap Normal 187 :ounmap Operator-pending 188 :unmap! Insert and Command-line 189 :iunmap Insert 190 :cunmap Command-line 191 192There is a trick to define a mapping that works in Normal and Operator-pending 193mode, but not in Visual mode. First define it for all three modes, then 194delete it for Visual mode: > 195 196 :map <C-A> /---><CR> 197 :vunmap <C-A> 198 199Notice that the five characters "<C-A>" stand for the single key CTRL-A. 200 201To remove all mappings use the |:mapclear| command. You can guess the 202variations for different modes by now. Be careful with this command, it can't 203be undone. 204 205 206SPECIAL CHARACTERS 207 208The ":map" command can be followed by another command. A | character 209separates the two commands. This also means that a | character can't be used 210inside a map command. To include one, use <Bar> (five characters). Example: 211> 212 :map <F8> :write <Bar> !checkin %<CR> 213 214The same problem applies to the ":unmap" command, with the addition that you 215have to watch out for trailing white space. These two commands are different: 216> 217 :unmap a | unmap b 218 :unmap a| unmap b 219 220The first command tries to unmap "a ", with a trailing space. 221 222When using a space inside a mapping, use <Space> (seven characters): > 223 224 :map <Space> W 225 226This makes the spacebar move a blank-separated word forward. 227 228It is not possible to put a comment directly after a mapping, because the " 229character is considered to be part of the mapping. You can use |", this 230starts a new, empty command with a comment. Example: > 231 232 :map <Space> W| " Use spacebar to move forward a word 233 234 235MAPPINGS AND ABBREVIATIONS 236 237Abbreviations are a lot like Insert mode mappings. The arguments are handled 238in the same way. The main difference is the way they are triggered. An 239abbreviation is triggered by typing a non-word character after the word. A 240mapping is triggered when typing the last character. 241 Another difference is that the characters you type for an abbreviation are 242inserted in the text while you type them. When the abbreviation is triggered 243these characters are deleted and replaced by what the abbreviation produces. 244When typing the characters for a mapping, nothing is inserted until you type 245the last character that triggers it. If the 'showcmd' option is set, the 246typed characters are displayed in the last line of the Vim window. 247 An exception is when a mapping is ambiguous. Suppose you have done two 248mappings: > 249 250 :imap aa foo 251 :imap aaa bar 252 253Now, when you type "aa", Vim doesn't know if it should apply the first or the 254second mapping. It waits for another character to be typed. If it is an "a", 255the second mapping is applied and results in "bar". If it is a space, for 256example, the first mapping is applied, resulting in "foo", and then the space 257is inserted. 258 259 260ADDITIONALLY... 261 262The <script> keyword can be used to make a mapping local to a script. See 263|:map-<script>|. 264 265The <buffer> keyword can be used to make a mapping local to a specific buffer. 266See |:map-<buffer>| 267 268The <unique> keyword can be used to make defining a new mapping fail when it 269already exists. Otherwise a new mapping simply overwrites the old one. See 270|:map-<unique>|. 271 272To make a key do nothing, map it to <Nop> (five characters). This will make 273the <F7> key do nothing at all: > 274 275 :map <F7> <Nop>| map! <F7> <Nop> 276 277There must be no space after <Nop>. 278 279============================================================================== 280*40.2* Defining command-line commands 281 282The Vim editor enables you to define your own commands. You execute these 283commands just like any other Command-line mode command. 284 To define a command, use the ":command" command, as follows: > 285 286 :command DeleteFirst 1delete 287 288Now when you execute the command ":DeleteFirst" Vim executes ":1delete", which 289deletes the first line. 290 291 Note: 292 User-defined commands must start with a capital letter. You cannot 293 use ":X", ":Next" and ":Print". The underscore cannot be used! You 294 can use digits, but this is discouraged. 295 296To list the user-defined commands, execute the following command: > 297 298 :command 299 300Just like with the builtin commands, the user defined commands can be 301abbreviated. You need to type just enough to distinguish the command from 302another. Command line completion can be used to get the full name. 303 304 305NUMBER OF ARGUMENTS 306 307User-defined commands can take a series of arguments. The number of arguments 308must be specified by the -nargs option. For instance, the example 309:DeleteFirst command takes no arguments, so you could have defined it as 310follows: > 311 312 :command -nargs=0 DeleteFirst 1delete 313 314However, because zero arguments is the default, you do not need to add 315"-nargs=0". The other values of -nargs are as follows: 316 317 -nargs=0 No arguments 318 -nargs=1 One argument 319 -nargs=* Any number of arguments 320 -nargs=? Zero or one argument 321 -nargs=+ One or more arguments 322 323 324USING THE ARGUMENTS 325 326Inside the command definition, the arguments are represented by the 327<args> keyword. For example: > 328 329 :command -nargs=+ Say :echo "<args>" 330 331Now when you type > 332 333 :Say Hello World 334 335Vim echoes "Hello World". However, if you add a double quote, it won't work. 336For example: > 337 338 :Say he said "hello" 339 340To get special characters turned into a string, properly escaped to use as an 341expression, use "<q-args>": > 342 343 :command -nargs=+ Say :echo <q-args> 344 345Now the above ":Say" command will result in this to be executed: > 346 347 :echo "he said \"hello\"" 348 349The <f-args> keyword contains the same information as the <args> keyword, 350except in a format suitable for use as function call arguments. For example: 351> 352 :command -nargs=* DoIt :call AFunction(<f-args>) 353 :DoIt a b c 354 355Executes the following command: > 356 357 :call AFunction("a", "b", "c") 358 359 360LINE RANGE 361 362Some commands take a range as their argument. To tell Vim that you are 363defining such a command, you need to specify a -range option. The values for 364this option are as follows: 365 366 -range Range is allowed; default is the current line. 367 -range=% Range is allowed; default is the whole file. 368 -range={count} Range is allowed; the last number in it is used as a 369 single number whose default is {count}. 370 371When a range is specified, the keywords <line1> and <line2> get the values of 372the first and last line in the range. For example, the following command 373defines the SaveIt command, which writes out the specified range to the file 374"save_file": > 375 376 :command -range=% SaveIt :<line1>,<line2>write! save_file 377 378 379OTHER OPTIONS 380 381Some of the other options and keywords are as follows: 382 383 -count={number} The command can take a count whose default is 384 {number}. The resulting count can be used 385 through the <count> keyword. 386 -bang You can use a !. If present, using <bang> will 387 result in a !. 388 -register You can specify a register. (The default is 389 the unnamed register.) 390 The register specification is available as 391 <reg> (a.k.a. <register>). 392 -complete={type} Type of command-line completion used. See 393 |:command-completion| for the list of possible 394 values. 395 -bar The command can be followed by | and another 396 command, or " and a comment. 397 -buffer The command is only available for the current 398 buffer. 399 400Finally, you have the <lt> keyword. It stands for the character <. Use this 401to escape the special meaning of the <> items mentioned. 402 403 404REDEFINING AND DELETING 405 406To redefine the same command use the ! argument: > 407 408 :command -nargs=+ Say :echo "<args>" 409 :command! -nargs=+ Say :echo <q-args> 410 411To delete a user command use ":delcommand". It takes a single argument, which 412is the name of the command. Example: > 413 414 :delcommand SaveIt 415 416To delete all the user commands: > 417 418 :comclear 419 420Careful, this can't be undone! 421 422More details about all this in the reference manual: |user-commands|. 423 424============================================================================== 425*40.3* Autocommands 426 427An autocommand is a command that is executed automatically in response to some 428event, such as a file being read or written or a buffer change. Through the 429use of autocommands you can train Vim to edit compressed files, for example. 430That is used in the |gzip| plugin. 431 Autocommands are very powerful. Use them with care and they will help you 432avoid typing many commands. Use them carelessly and they will cause a lot of 433trouble. 434 435Suppose you want to replace a datestamp on the end of a file every time it is 436written. First you define a function: > 437 438 :function DateInsert() 439 : $delete 440 : read !date 441 :endfunction 442 443You want this function to be called each time, just before a file is written. 444This will make that happen: > 445 446 :autocmd FileWritePre * call DateInsert() 447 448"FileWritePre" is the event for which this autocommand is triggered: Just 449before (pre) writing a file. The "*" is a pattern to match with the file 450name. In this case it matches all files. 451 With this command enabled, when you do a ":write", Vim checks for any 452matching FileWritePre autocommands and executes them, and then it 453performs the ":write". 454 The general form of the :autocmd command is as follows: > 455 456 :autocmd [group] {events} {file_pattern} [nested] {command} 457 458The [group] name is optional. It is used in managing and calling the commands 459(more on this later). The {events} parameter is a list of events (comma 460separated) that trigger the command. 461 {file_pattern} is a filename, usually with wildcards. For example, using 462"*.txt" makes the autocommand be used for all files whose name end in ".txt". 463The optional [nested] flag allows for nesting of autocommands (see below), and 464finally, {command} is the command to be executed. 465 466 467EVENTS 468 469One of the most useful events is BufReadPost. It is triggered after a new 470file is being edited. It is commonly used to set option values. For example, 471you know that "*.gsm" files are GNU assembly language. To get the syntax file 472right, define this autocommand: > 473 474 :autocmd BufReadPost *.gsm set filetype=asm 475 476If Vim is able to detect the type of file, it will set the 'filetype' option 477for you. This triggers the Filetype event. Use this to do something when a 478certain type of file is edited. For example, to load a list of abbreviations 479for text files: > 480 481 :autocmd Filetype text source ~/.vim/abbrevs.vim 482 483When starting to edit a new file, you could make Vim insert a skeleton: > 484 485 :autocmd BufNewFile *.[ch] 0read ~/skeletons/skel.c 486 487See |autocmd-events| for a complete list of events. 488 489 490PATTERNS 491 492The {file_pattern} argument can actually be a comma-separated list of file 493patterns. For example: "*.c,*.h" matches files ending in ".c" and ".h". 494 The usual file wildcards can be used. Here is a summary of the most often 495used ones: 496 497 * Match any character any number of times 498 ? Match any character once 499 [abc] Match the character a, b or c 500 . Matches a dot 501 a{b,c} Matches "ab" and "ac" 502 503When the pattern includes a slash (/) Vim will compare directory names. 504Without the slash only the last part of a file name is used. For example, 505"*.txt" matches "/home/biep/readme.txt". The pattern "/home/biep/*" would 506also match it. But "home/foo/*.txt" wouldn't. 507 When including a slash, Vim matches the pattern against both the full path 508of the file ("/home/biep/readme.txt") and the relative path (e.g., 509"biep/readme.txt"). 510 511 Note: 512 When working on a system that uses a backslash as file separator, such 513 as MS-Windows, you still use forward slashes in autocommands. This 514 makes it easier to write the pattern, since a backslash has a special 515 meaning. It also makes the autocommands portable. 516 517 518DELETING 519 520To delete an autocommand, use the same command as what it was defined with, 521but leave out the {command} at the end and use a !. Example: > 522 523 :autocmd! FileWritePre * 524 525This will delete all autocommands for the "FileWritePre" event that use the 526"*" pattern. 527 528 529LISTING 530 531To list all the currently defined autocommands, use this: > 532 533 :autocmd 534 535The list can be very long, especially when filetype detection is used. To 536list only part of the commands, specify the group, event and/or pattern. For 537example, to list all BufNewFile autocommands: > 538 539 :autocmd BufNewFile 540 541To list all autocommands for the pattern "*.c": > 542 543 :autocmd * *.c 544 545Using "*" for the event will list all the events. To list all autocommands 546for the cprograms group: > 547 548 :autocmd cprograms 549 550 551GROUPS 552 553The {group} item, used when defining an autocommand, groups related autocommands 554together. This can be used to delete all the autocommands in a certain group, 555for example. 556 When defining several autocommands for a certain group, use the ":augroup" 557command. For example, let's define autocommands for C programs: > 558 559 :augroup cprograms 560 : autocmd BufReadPost *.c,*.h :set sw=4 sts=4 561 : autocmd BufReadPost *.cpp :set sw=3 sts=3 562 :augroup END 563 564This will do the same as: > 565 566 :autocmd cprograms BufReadPost *.c,*.h :set sw=4 sts=4 567 :autocmd cprograms BufReadPost *.cpp :set sw=3 sts=3 568 569To delete all autocommands in the "cprograms" group: > 570 571 :autocmd! cprograms 572 573 574NESTING 575 576Generally, commands executed as the result of an autocommand event will not 577trigger any new events. If you read a file in response to a FileChangedShell 578event, it will not trigger the autocommands that would set the syntax, for 579example. To make the events triggered, add the "nested" argument: > 580 581 :autocmd FileChangedShell * nested edit 582 583 584EXECUTING AUTOCOMMANDS 585 586It is possible to trigger an autocommand by pretending an event has occurred. 587This is useful to have one autocommand trigger another one. Example: > 588 589 :autocmd BufReadPost *.new execute "doautocmd BufReadPost " . expand("<afile>:r") 590 591This defines an autocommand that is triggered when a new file has been edited. 592The file name must end in ".new". The ":execute" command uses expression 593evaluation to form a new command and execute it. When editing the file 594"tryout.c.new" the executed command will be: > 595 596 :doautocmd BufReadPost tryout.c 597 598The expand() function takes the "<afile>" argument, which stands for the file 599name the autocommand was executed for, and takes the root of the file name 600with ":r". 601 602":doautocmd" executes on the current buffer. The ":doautoall" command works 603like "doautocmd" except it executes on all the buffers. 604 605 606USING NORMAL MODE COMMANDS 607 608The commands executed by an autocommand are Command-line commands. If you 609want to use a Normal mode command, the ":normal" command can be used. 610Example: > 611 612 :autocmd BufReadPost *.log normal G 613 614This will make the cursor jump to the last line of *.log files when you start 615to edit it. 616 Using the ":normal" command is a bit tricky. First of all, make sure its 617argument is a complete command, including all the arguments. When you use "i" 618to go to Insert mode, there must also be a <Esc> to leave Insert mode again. 619If you use a "/" to start a search pattern, there must be a <CR> to execute 620it. 621 The ":normal" command uses all the text after it as commands. Thus there 622can be no | and another command following. To work around this, put the 623":normal" command inside an ":execute" command. This also makes it possible 624to pass unprintable characters in a convenient way. Example: > 625 626 :autocmd BufReadPost *.chg execute "normal ONew entry:\<Esc>" | 627 \ 1read !date 628 629This also shows the use of a backslash to break a long command into more 630lines. This can be used in Vim scripts (not at the command line). 631 632When you want the autocommand do something complicated, which involves jumping 633around in the file and then returning to the original position, you may want 634to restore the view on the file. See |restore-position| for an example. 635 636 637IGNORING EVENTS 638 639At times, you will not want to trigger an autocommand. The 'eventignore' 640option contains a list of events that will be totally ignored. For example, 641the following causes events for entering and leaving a window to be ignored: > 642 643 :set eventignore=WinEnter,WinLeave 644 645To ignore all events, use the following command: > 646 647 :set eventignore=all 648 649To set it back to the normal behavior, make 'eventignore' empty: > 650 651 :set eventignore= 652 653============================================================================== 654 655Next chapter: |usr_41.txt| Write a Vim script 656 657Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl: 658