Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 658 lines (451 sloc) 23.16 kb
810bd03 Last changes for the 7.3 release!
Bram Moolenaar authored
1 *usr_40.txt* For Vim version 7.3. Last change: 2006 Jun 21
e5c6ef7 updated for version 7.0001
vimboss authored
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
16d8075 updated for version 7.0b
vimboss authored
17 Previous chapter: |usr_32.txt| The undo tree
e5c6ef7 updated for version 7.0001
vimboss authored
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
c882513 Add the settabvar() and gettabvar() functions.
Bram Moolenaar authored
27 the function keys, except <F1>, have no predefined meaning in Vim, these are
28 good choices to map. Example: >
e5c6ef7 updated for version 7.0001
vimboss authored
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
a2a1b9c updated for version 7.0026
vimboss authored
63 mode. If you want it to continue in Insert mode, append an "a" to the
64 mapping.
e5c6ef7 updated for version 7.0001
vimboss authored
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.
937a4c7 updated for version 7.0066
vimboss authored
386 -bang You can use a !. If present, using <bang> will
e5c6ef7 updated for version 7.0001
vimboss authored
387 result in a !.
937a4c7 updated for version 7.0066
vimboss authored
388 -register You can specify a register. (The default is
e5c6ef7 updated for version 7.0001
vimboss authored
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
937a4c7 updated for version 7.0066
vimboss authored
428 event, such as a file being read or written or a buffer change. Through the
e5c6ef7 updated for version 7.0001
vimboss authored
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
937a4c7 updated for version 7.0066
vimboss authored
435 Suppose you want to replace a datestamp on the end of a file every time it is
e5c6ef7 updated for version 7.0001
vimboss authored
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
49b03a5 updated for version 7.1a
vimboss authored
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: >
e5c6ef7 updated for version 7.0001
vimboss authored
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
657 Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl:
Something went wrong with that request. Please try again.