11.10.1. vim Is Charityware

11.10.2. C and C++ Programming Features

11.10.3. Autocommands

The facility is complicated and detailed. In this section we outline its general capabilities, and provide an example to give you a sense of its flavor.

:au event filepat command

The event is the kind of event to which this command applies, for example, before and after reading a file (FileReadPre and FileReadPost), before and after writing a file (FileWritePre and FileWritePost), and upon entering or leaving a window (WinEnter and Winleave). There are more defined events, and case in the event name does not matter.

The filepat is a shell-style wildcard pattern that vim applies to filenames. If they match, then the autocommand will be applied for this file.

The command is any ex mode command. vim has a special syntax for retrieving the different parts of filenames, such as the file's extension, or the name without the extension. These can be used in any ex command, but are very useful with autocommands.

Multiple autocommands for the same events and file patterns add commands onto the list. Autocommands can be removed for a particular combination of events and file patterns by appending ! to the :autocmd command.

A particularly elegant example allows you to edit files compressed with the gzip program. The file is automatically decompressed when editing starts, and then recompressed when the file is written out (the fourth line is broken for readability):

:autocmd! BufReadPre,FileReadPre        *.gz set bin
:autocmd! BufReadPost,FileReadPost      *.gz '[,']!gunzip
:autocmd  BufReadPost,FileReadPost      *.gz set nobin
:autocmd  BufReadPost,FileReadPost      *.gz \
          execute ":doautocmd BufReadPost " . expand("%:r")

:autocmd! BufWritePost,FileWritePost    *.gz !mv <afile> <afile>:r
:autocmd  BufWritePost,FileWritePost    *.gz !gzip <afile>:r

:autocmd! FileAppendPre                 *.gz !gunzip <afile>
:autocmd  FileAppendPre                 *.gz !mv <afile>:r <afile>

:autocmd! FileAppendPost                *.gz !mv <afile> <afile>:r
:autocmd  FileAppendPost                *.gz !gzip <afile>:r

The first four commands are for reading compressed files. The first two in this set use ! to remove any previously defined autocommands for compressed files (*.gz). The compressed file is read into the buffer as a binary file, so the first command turns on the bin (short for binary) option.

vim sets the marks '[ and '] to the first and last lines of the just read text. The second command uses this to uncompress the just read file in the buffer.

The next two lines unset the binary option, and then apply any autocommands that apply to the uncompressed version of the file (e.g., syntax highlighting). The %:r is the current filename without the extension.

The next two lines are for writing the compressed file. The first one in this set first removes any previously defined autocommands for compressed files (*.gz), with these events. The commands invoke a shell to rename the file to not have the .gz extension, and then run gzip to compress the file. The <afile>:r is the filename without the extension. (The use of <afile>:r is restricted to autocommands.) vim writes the uncompressed buffer to the file with the .gz extension, thus the need for the renaming.

The second line in this set runs gzip to compress the file. gzip automatically renames the file, adding the .gz extension.

The last four lines handle the case of appending to a compressed file. The first two of these lines uncompress the file and rename it before appending the contents to the file.

Finally, the last two lines recompress the file after writing to it, so that the uncompressed file is not left laying around.