Mercurial > vim

comparison runtime/doc/autocmd.txt @ 40:f1d2a58883b9 v7.0024

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
updated for version 7.0024
author vimboss
date Fri, 24 Dec 2004 14:35:23 +0000
parents 410fa1a31baf
children 8ecb0db93e9a
comparison
equal deleted inserted replaced
39:410fa1a31baf 40:f1d2a58883b9
1 *autocmd.txt* For Vim version 7.0aa. Last change: 2004 Dec 16 1 *autocmd.txt* For Vim version 7.0aa. Last change: 2004 Dec 24
2 2
3 3
4 VIM REFERENCE MANUAL by Bram Moolenaar 4 VIM REFERENCE MANUAL by Bram Moolenaar
5 5
6 6
12 2. Defining autocommands |autocmd-define| 12 2. Defining autocommands |autocmd-define|
13 3. Removing autocommands |autocmd-remove| 13 3. Removing autocommands |autocmd-remove|
14 4. Listing autocommands |autocmd-list| 14 4. Listing autocommands |autocmd-list|
15 5. Events |autocmd-events| 15 5. Events |autocmd-events|
16 6. Patterns |autocmd-patterns| 16 6. Patterns |autocmd-patterns|
17 7. Groups |autocmd-groups| 17 7. Buffer-local autocommands |autocmd-buflocal|
18 8. Executing autocommands |autocmd-execute| 18 8. Groups |autocmd-groups|
19 9. Using autocommands |autocmd-use| 19 9. Executing autocommands |autocmd-execute|
20 10. Using autocommands |autocmd-use|
20 21
21 {Vi does not have any of these commands} 22 {Vi does not have any of these commands}
22 {only when the |+autocmd| feature has not been disabled at compile time} 23 {only when the |+autocmd| feature has not been disabled at compile time}
23 24
24 ============================================================================== 25 ==============================================================================
60 {pat}. Vim always adds the {cmd} after existing 61 {pat}. Vim always adds the {cmd} after existing
61 autocommands, so that the autocommands execute in the 62 autocommands, so that the autocommands execute in the
62 order in which they were given. See |autocmd-nested| 63 order in which they were given. See |autocmd-nested|
63 for [nested]. 64 for [nested].
64 65
66 The special pattern <buffer> or <buffer=N> defines a buffer-local autocommand.
67 See |autocmd-buflocal|.
68
65 Note that special characters (e.g., "%", "<cword>") in the ":autocmd" 69 Note that special characters (e.g., "%", "<cword>") in the ":autocmd"
66 arguments are not expanded when the autocommand is defined. These will be 70 arguments are not expanded when the autocommand is defined. These will be
67 expanded when the Event is recognized, and the {cmd} is executed. The only 71 expanded when the Event is recognized, and the {cmd} is executed. The only
68 exception is that "<sfile>" is expanded when the autocmd is defined. Example: 72 exception is that "<sfile>" is expanded when the autocmd is defined. Example:
69 > 73 >
145 :au[tocmd] [group] Show all autocommands. 149 :au[tocmd] [group] Show all autocommands.
146 150
147 If you provide the [group] argument, Vim lists only the autocommands for 151 If you provide the [group] argument, Vim lists only the autocommands for
148 [group]; otherwise, Vim lists the autocommands for ALL groups. Note that this 152 [group]; otherwise, Vim lists the autocommands for ALL groups. Note that this
149 argument behavior differs from that for defining and removing autocommands. 153 argument behavior differs from that for defining and removing autocommands.
154
155 In order to list buffer-local autocommands, use a pattern in the form <buffer>
156 or <buffer=N>. See |autocmd-buflocal|.
150 157
151 ============================================================================== 158 ==============================================================================
152 5. Events *autocmd-events* *E215* *E216* 159 5. Events *autocmd-events* *E215* *E216*
153 160
154 *autocommand-events* *{event}* 161 *autocommand-events* *{event}*
551 the tail part of the file name (without its leading directory path). 558 the tail part of the file name (without its leading directory path).
552 2. When there is a '/' in the pattern, Vim checks for a match against the 559 2. When there is a '/' in the pattern, Vim checks for a match against the
553 both short file name (as you typed it) and the full file name (after 560 both short file name (as you typed it) and the full file name (after
554 expanding it to a full path and resolving symbolic links). 561 expanding it to a full path and resolving symbolic links).
555 562
563 The special pattern <buffer> or <buffer=N> is used for buffer-local
564 autocommands |autocmd-buflocal|. This pattern is not matched against the name
565 of a buffer.
566
556 Examples: > 567 Examples: >
557 :autocmd BufRead *.txt set et 568 :autocmd BufRead *.txt set et
558 Set the 'et' option for all text files. > 569 Set the 'et' option for all text files. >
559 570
560 :autocmd BufRead /vim/src/*.c set cindent 571 :autocmd BufRead /vim/src/*.c set cindent
606 617
607 Note that for all systems the '/' character is used for path separator (even 618 Note that for all systems the '/' character is used for path separator (even
608 MS-DOS and OS/2). This was done because the backslash is difficult to use 619 MS-DOS and OS/2). This was done because the backslash is difficult to use
609 in a pattern and to make the autocommands portable across different systems. 620 in a pattern and to make the autocommands portable across different systems.
610 621
611 622 *autocmd-changes*
612 Matching with the pattern is done when an event is triggered. Changing the 623 Matching with the pattern is done when an event is triggered. Changing the
613 buffer name in one of the autocommands, or even deleting the buffer, does not 624 buffer name in one of the autocommands, or even deleting the buffer, does not
614 change which autocommands will be executed. Example: > 625 change which autocommands will be executed. Example: >
615 626
616 au BufEnter *.foo bdel 627 au BufEnter *.foo bdel
619 This will delete the current buffer and then set 'modified' in what has become 630 This will delete the current buffer and then set 'modified' in what has become
620 the current buffer instead. Vim doesn't take into account that "*.foo" 631 the current buffer instead. Vim doesn't take into account that "*.foo"
621 doesn't match with that buffer name. It matches "*.foo" with the name of the 632 doesn't match with that buffer name. It matches "*.foo" with the name of the
622 buffer at the moment the event was triggered. 633 buffer at the moment the event was triggered.
623 634
635 However, buffer-local autocommands will not be executed for a buffer that has
636 been wiped out with |:bwipe|. After deleting the buffer with |:bdel| the
637 buffer actually still exists (it becomes unlisted), thus the autocommands are
638 still executed.
639
624 ============================================================================== 640 ==============================================================================
625 7. Groups *autocmd-groups* 641 7. Buffer-local autocommands *autocmd-buflocal* *autocmd-buffer-local*
642 *<buffer=N>* *<buffer=abuf>* *E680*
643
644 Buffer-local autocommands are attached to a specific buffer. They are useful
645 if the buffer does not have a name and when the name does not match a specific
646 pattern. But it also means they must be explicitly added to each buffer.
647
648 Instead of a pattern buffer-local autocommands use one of these forms:
649 <buffer> current buffer
650 <buffer=99> buffer number 99
651 <buffer=abuf> using <abuf> (only when executing autocommands)
652 |<abuf>|
653
654 Examples: >
655 :au CursorHold <buffer> echo 'hold'
656 :au CursorHold <buffer=33> echo 'hold'
657 :au CursorHold <buffer=abuf> echo 'hold'
658
659 All the commands for autocommands also work with buffer-local autocommands,
660 simply use the special string instead of the pattern. Examples: >
661 :au! * <buffer> " remove buffer-local autotommands for
662 " current buffer
663 :au! * <buffer=33> " remove buffer-local autotommands for
664 " buffer #33
665 :dobuf :au! CursorHold <buffer> " remove autocmd for given event for all
666 " buffers
667 :au * <buffer> " list buffer-local autocommands for
668 " current buffer
669
670 Note that when an autocommand is defined for the current buffer, it is stored
671 with the buffer number. Thus it uses the form "<buffer=12>", where 12 is the
672 number of the current buffer. You will see this when listing autocommands,
673 for example.
674
675 To test for presence of buffer-local autocommands use the |exists()| function
676 as follows: >
677 :if exists("#CursorHold#<buffer=12>") | ... | endif
678 :if exists("#CursorHold#<buffer>") | ... | endif " for current buffer
679
680 When a buffer is wiped out its buffer-local autocommands are also gone, of
681 course. Note that when deleting a buffer, e.g., with ":bdel", it is only
682 unlisted, the autocommands are still present. In order to see the removal of
683 buffer-local autocommands: >
684 :set verbose=6
685
686 It is not possible to define buffer-local autocommands for a non-existent
687 buffer.
688
689 ==============================================================================
690 8. Groups *autocmd-groups*
626 691
627 Autocommands can be put together in a group. This is useful for removing or 692 Autocommands can be put together in a group. This is useful for removing or
628 executing a group of autocommands. For example, all the autocommands for 693 executing a group of autocommands. For example, all the autocommands for
629 syntax highlighting are put in the "highlight" group, to be able to execute 694 syntax highlighting are put in the "highlight" group, to be able to execute
630 ":doautoall highlight BufRead" when the GUI starts. 695 ":doautoall highlight BufRead" when the GUI starts.
668 733
669 This prevents having the autocommands defined twice (e.g., after sourcing the 734 This prevents having the autocommands defined twice (e.g., after sourcing the
670 .vimrc file again). 735 .vimrc file again).
671 736
672 ============================================================================== 737 ==============================================================================
673 8. Executing autocommands *autocmd-execute* 738 9. Executing autocommands *autocmd-execute*
674 739
675 Vim can also execute Autocommands non-automatically. This is useful if you 740 Vim can also execute Autocommands non-automatically. This is useful if you
676 have changed autocommands, or when Vim has executed the wrong autocommands 741 have changed autocommands, or when Vim has executed the wrong autocommands
677 (e.g., the file pattern match was wrong). 742 (e.g., the file pattern match was wrong).
678 743
711 contents of a buffer; the result is unpredictable. 776 contents of a buffer; the result is unpredictable.
712 This command is intended for autocommands that set 777 This command is intended for autocommands that set
713 options, change highlighting, and things like that. 778 options, change highlighting, and things like that.
714 779
715 ============================================================================== 780 ==============================================================================
716 9. Using autocommands *autocmd-use* 781 10. Using autocommands *autocmd-use*
717 782
718 For WRITING FILES there are four possible sets of events. Vim uses only one 783 For WRITING FILES there are four possible sets of events. Vim uses only one
719 of these sets for a write command: 784 of these sets for a write command:
720 785
721 BufWriteCmd BufWritePre BufWritePost writing the whole buffer 786 BufWriteCmd BufWritePre BufWritePost writing the whole buffer
924 effective. These should be used for the command that reads/writes the file. 989 effective. These should be used for the command that reads/writes the file.
925 The |v:cmdbang| variable is one when "!" was used, zero otherwise. 990 The |v:cmdbang| variable is one when "!" was used, zero otherwise.
926 991
927 See the $VIMRUNTIME/plugin/netrw.vim for examples. 992 See the $VIMRUNTIME/plugin/netrw.vim for examples.
928 993
994
929 vim:tw=78:ts=8:ft=help:norl: 995 vim:tw=78:ts=8:ft=help:norl: