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