Mercurial > vim
annotate runtime/doc/usr_40.txt @ 18415:52eb1bbf7690
Added tag v8.1.2201 for changeset 6b8508ea90d798b96e29aaa21d6f8021c43128a7
author | Bram Moolenaar <Bram@vim.org> |
---|---|
date | Wed, 23 Oct 2019 21:45:04 +0200 |
parents | 5c5908e81e93 |
children | af69c9335223 |
rev | line source |
---|---|
13963 | 1 *usr_40.txt* For Vim version 8.1. Last change: 2013 Aug 05 |
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 | |
23 A simple mapping was explained in section |05.3|. The principle is that one | |
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 | |
456 :autocmd [group] {events} {file_pattern} [nested] {command} | |
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. | |
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". | |
463 The optional [nested] flag allows for nesting of autocommands (see below), and | |
464 finally, {command} is the command to be executed. | |
465 | |
466 | |
467 EVENTS | |
468 | |
469 One of the most useful events is BufReadPost. It is triggered after a new | |
470 file is being edited. It is commonly used to set option values. For example, | |
471 you know that "*.gsm" files are GNU assembly language. To get the syntax file | |
472 right, define this autocommand: > | |
473 | |
474 :autocmd BufReadPost *.gsm set filetype=asm | |
475 | |
476 If Vim is able to detect the type of file, it will set the 'filetype' option | |
477 for you. This triggers the Filetype event. Use this to do something when a | |
478 certain type of file is edited. For example, to load a list of abbreviations | |
479 for text files: > | |
480 | |
481 :autocmd Filetype text source ~/.vim/abbrevs.vim | |
482 | |
483 When starting to edit a new file, you could make Vim insert a skeleton: > | |
484 | |
485 :autocmd BufNewFile *.[ch] 0read ~/skeletons/skel.c | |
486 | |
487 See |autocmd-events| for a complete list of events. | |
488 | |
489 | |
490 PATTERNS | |
491 | |
492 The {file_pattern} argument can actually be a comma-separated list of file | |
493 patterns. 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 | |
495 used 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 | |
503 When the pattern includes a slash (/) Vim will compare directory names. | |
504 Without 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 | |
506 also match it. But "home/foo/*.txt" wouldn't. | |
507 When including a slash, Vim matches the pattern against both the full path | |
508 of 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 | |
518 DELETING | |
519 | |
520 To delete an autocommand, use the same command as what it was defined with, | |
521 but leave out the {command} at the end and use a !. Example: > | |
522 | |
523 :autocmd! FileWritePre * | |
524 | |
525 This will delete all autocommands for the "FileWritePre" event that use the | |
526 "*" pattern. | |
527 | |
528 | |
529 LISTING | |
530 | |
531 To list all the currently defined autocommands, use this: > | |
532 | |
533 :autocmd | |
534 | |
535 The list can be very long, especially when filetype detection is used. To | |
536 list only part of the commands, specify the group, event and/or pattern. For | |
537 example, to list all BufNewFile autocommands: > | |
538 | |
539 :autocmd BufNewFile | |
540 | |
541 To list all autocommands for the pattern "*.c": > | |
542 | |
543 :autocmd * *.c | |
544 | |
545 Using "*" for the event will list all the events. To list all autocommands | |
546 for the cprograms group: > | |
547 | |
548 :autocmd cprograms | |
549 | |
550 | |
551 GROUPS | |
552 | |
553 The {group} item, used when defining an autocommand, groups related autocommands | |
554 together. This can be used to delete all the autocommands in a certain group, | |
555 for example. | |
556 When defining several autocommands for a certain group, use the ":augroup" | |
557 command. 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 | |
564 This 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 | |
569 To delete all autocommands in the "cprograms" group: > | |
570 | |
571 :autocmd! cprograms | |
572 | |
573 | |
574 NESTING | |
575 | |
576 Generally, commands executed as the result of an autocommand event will not | |
577 trigger any new events. If you read a file in response to a FileChangedShell | |
578 event, it will not trigger the autocommands that would set the syntax, for | |
579 example. To make the events triggered, add the "nested" argument: > | |
580 | |
581 :autocmd FileChangedShell * nested edit | |
582 | |
583 | |
584 EXECUTING AUTOCOMMANDS | |
585 | |
586 It is possible to trigger an autocommand by pretending an event has occurred. | |
587 This is useful to have one autocommand trigger another one. Example: > | |
588 | |
589 :autocmd BufReadPost *.new execute "doautocmd BufReadPost " . expand("<afile>:r") | |
590 | |
591 This defines an autocommand that is triggered when a new file has been edited. | |
592 The file name must end in ".new". The ":execute" command uses expression | |
593 evaluation 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 | |
598 The expand() function takes the "<afile>" argument, which stands for the file | |
599 name the autocommand was executed for, and takes the root of the file name | |
600 with ":r". | |
601 | |
602 ":doautocmd" executes on the current buffer. The ":doautoall" command works | |
603 like "doautocmd" except it executes on all the buffers. | |
604 | |
605 | |
606 USING NORMAL MODE COMMANDS | |
607 | |
1125 | 608 The commands executed by an autocommand are Command-line commands. If you |
609 want to use a Normal mode command, the ":normal" command can be used. | |
610 Example: > | |
7 | 611 |
612 :autocmd BufReadPost *.log normal G | |
613 | |
614 This will make the cursor jump to the last line of *.log files when you start | |
615 to edit it. | |
616 Using the ":normal" command is a bit tricky. First of all, make sure its | |
617 argument is a complete command, including all the arguments. When you use "i" | |
618 to go to Insert mode, there must also be a <Esc> to leave Insert mode again. | |
619 If you use a "/" to start a search pattern, there must be a <CR> to execute | |
620 it. | |
621 The ":normal" command uses all the text after it as commands. Thus there | |
622 can be no | and another command following. To work around this, put the | |
623 ":normal" command inside an ":execute" command. This also makes it possible | |
624 to pass unprintable characters in a convenient way. Example: > | |
625 | |
626 :autocmd BufReadPost *.chg execute "normal ONew entry:\<Esc>" | | |
627 \ 1read !date | |
628 | |
629 This also shows the use of a backslash to break a long command into more | |
630 lines. This can be used in Vim scripts (not at the command line). | |
631 | |
632 When you want the autocommand do something complicated, which involves jumping | |
633 around in the file and then returning to the original position, you may want | |
634 to restore the view on the file. See |restore-position| for an example. | |
635 | |
636 | |
637 IGNORING EVENTS | |
638 | |
639 At times, you will not want to trigger an autocommand. The 'eventignore' | |
640 option contains a list of events that will be totally ignored. For example, | |
641 the following causes events for entering and leaving a window to be ignored: > | |
642 | |
643 :set eventignore=WinEnter,WinLeave | |
644 | |
645 To ignore all events, use the following command: > | |
646 | |
647 :set eventignore=all | |
648 | |
649 To set it back to the normal behavior, make 'eventignore' empty: > | |
650 | |
651 :set eventignore= | |
652 | |
653 ============================================================================== | |
654 | |
655 Next chapter: |usr_41.txt| Write a Vim script | |
656 | |
14519 | 657 Copyright: see |manual-copyright| vim:tw=78:ts=8:noet:ft=help:norl: |