|
42
|
1 *usr_40.txt* For Vim version 7.0aa. Last change: 2004 Dec 29
|
|
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
|
|
|
17 Previous chapter: |usr_31.txt| Exploiting the GUI
|
|
|
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
|
|
|
27 the function keys, except <F1>, have no predefined meaning in Vim, these are a
|
|
|
28 good choice to map. Example: >
|
|
|
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 >
|
|
|
212 :map <F8> :write <Bar> !checkin %<CR>
|
|
|
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.
|
|
|
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
|
|
|
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
|
|
|
428 event, such as a file being read or written or a buffer change. Through the
|
|
|
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
|
|
|
435 Suppose you want to replace a date stamp on the end of a file every time it is
|
|
|
436 written. First you define a function: >
|
|
|
437
|
|
|
438 :function DateInsert()
|
|
|
439 : $delete
|
|
|
440 : read !date
|
|
|
441 :endfunction
|
|
|
442
|
|
|
443 You want this function to be called each time, just before a file is written.
|
|
|
444 This will make that happen: >
|
|
|
445
|
|
|
446 :autocmd FileWritePre * call DateInsert()
|
|
|
447
|
|
|
448 "FileWritePre" is the event for which this autocommand is triggered: Just
|
|
|
449 before (pre) writing a file. The "*" is a pattern to match with the file
|
|
|
450 name. In this case it matches all files.
|
|
|
451 With this command enabled, when you do a ":write", Vim checks for any
|
|
|
452 matching FileWritePre autocommands and executes them, and then it
|
|
|
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
|
|
|
608 The commands executed by an autocommand are Command-line command. If you want
|
|
|
609 to use a Normal mode command, the ":normal" command can be used. Example: >
|
|
|
610
|
|
|
611 :autocmd BufReadPost *.log normal G
|
|
|
612
|
|
|
613 This will make the cursor jump to the last line of *.log files when you start
|
|
|
614 to edit it.
|
|
|
615 Using the ":normal" command is a bit tricky. First of all, make sure its
|
|
|
616 argument is a complete command, including all the arguments. When you use "i"
|
|
|
617 to go to Insert mode, there must also be a <Esc> to leave Insert mode again.
|
|
|
618 If you use a "/" to start a search pattern, there must be a <CR> to execute
|
|
|
619 it.
|
|
|
620 The ":normal" command uses all the text after it as commands. Thus there
|
|
|
621 can be no | and another command following. To work around this, put the
|
|
|
622 ":normal" command inside an ":execute" command. This also makes it possible
|
|
|
623 to pass unprintable characters in a convenient way. Example: >
|
|
|
624
|
|
|
625 :autocmd BufReadPost *.chg execute "normal ONew entry:\<Esc>" |
|
|
|
626 \ 1read !date
|
|
|
627
|
|
|
628 This also shows the use of a backslash to break a long command into more
|
|
|
629 lines. This can be used in Vim scripts (not at the command line).
|
|
|
630
|
|
|
631 When you want the autocommand do something complicated, which involves jumping
|
|
|
632 around in the file and then returning to the original position, you may want
|
|
|
633 to restore the view on the file. See |restore-position| for an example.
|
|
|
634
|
|
|
635
|
|
|
636 IGNORING EVENTS
|
|
|
637
|
|
|
638 At times, you will not want to trigger an autocommand. The 'eventignore'
|
|
|
639 option contains a list of events that will be totally ignored. For example,
|
|
|
640 the following causes events for entering and leaving a window to be ignored: >
|
|
|
641
|
|
|
642 :set eventignore=WinEnter,WinLeave
|
|
|
643
|
|
|
644 To ignore all events, use the following command: >
|
|
|
645
|
|
|
646 :set eventignore=all
|
|
|
647
|
|
|
648 To set it back to the normal behavior, make 'eventignore' empty: >
|
|
|
649
|
|
|
650 :set eventignore=
|
|
|
651
|
|
|
652 ==============================================================================
|
|
|
653
|
|
|
654 Next chapter: |usr_41.txt| Write a Vim script
|
|
|
655
|
|
|
656 Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl:
|
