|
7
|
1 *usr_43.txt* For Vim version 7.0aa. Last change: 2002 Jul 14
|
|
|
2
|
|
|
3 VIM USER MANUAL - by Bram Moolenaar
|
|
|
4
|
|
|
5 Using filetypes
|
|
|
6
|
|
|
7
|
|
|
8 When you are editing a file of a certain type, for example a C program or a
|
|
|
9 shell script, you often use the same option settings and mappings. You
|
|
|
10 quickly get tired of manually setting these each time. This chapter explains
|
|
|
11 how to do it automatically.
|
|
|
12
|
|
|
13 |43.1| Plugins for a filetype
|
|
|
14 |43.2| Adding a filetype
|
|
|
15
|
|
|
16 Next chapter: |usr_44.txt| Your own syntax highlighted
|
|
|
17 Previous chapter: |usr_42.txt| Add new menus
|
|
|
18 Table of contents: |usr_toc.txt|
|
|
|
19
|
|
|
20 ==============================================================================
|
|
|
21 *43.1* Plugins for a filetype *filetype-plugin*
|
|
|
22
|
|
|
23 How to start using filetype plugins has already been discussed here:
|
|
|
24 |add-filetype-plugin|. But you probably are not satisfied with the default
|
|
|
25 settings, because they have been kept minimal. Suppose that for C files you
|
|
|
26 want to set the 'softtabstop' option to 4 and define a mapping to insert a
|
|
|
27 three-line comment. You do this with only two steps:
|
|
|
28
|
|
|
29 *your-runtime-dir*
|
|
|
30 1. Create your own runtime directory. On Unix this usually is "~/.vim". In
|
|
|
31 this directory create the "ftplugin" directory: >
|
|
|
32
|
|
|
33 mkdir ~/.vim
|
|
|
34 mkdir ~/.vim/ftplugin
|
|
|
35 <
|
|
|
36 When you are not on Unix, check the value of the 'runtimepath' option to
|
|
|
37 see where Vim will look for the "ftplugin" directory: >
|
|
|
38
|
|
|
39 set runtimepath
|
|
|
40
|
|
|
41 < You would normally use the first directory name (before the first comma).
|
|
|
42 You might want to prepend a directory name to the 'runtimepath' option in
|
|
|
43 your |vimrc| file if you don't like the default value.
|
|
|
44
|
|
|
45 2. Create the file "~/.vim/ftplugin/c.vim", with the contents: >
|
|
|
46
|
|
|
47 setlocal softtabstop=4
|
|
|
48 noremap <buffer> <LocalLeader>c o/**************<CR><CR>/<Esc>
|
|
|
49
|
|
|
50 Try editing a C file. You should notice that the 'softtabstop' option is set
|
|
|
51 to 4. But when you edit another file it's reset to the default zero. That is
|
|
|
52 because the ":setlocal" command was used. This sets the 'softtabstop' option
|
|
|
53 only locally to the buffer. As soon as you edit another buffer, it will be
|
|
|
54 set to the value set for that buffer. For a new buffer it will get the
|
|
|
55 default value or the value from the last ":set" command.
|
|
|
56
|
|
|
57 Likewise, the mapping for "\c" will disappear when editing another buffer.
|
|
|
58 The ":map <buffer>" command creates a mapping that is local to the current
|
|
|
59 buffer. This works with any mapping command: ":map!", ":vmap", etc. The
|
|
|
60 |<LocalLeader>| in the mapping is replaced with the value of "maplocalleader".
|
|
|
61
|
|
|
62 You can find examples for filetype plugins in this directory: >
|
|
|
63
|
|
|
64 $VIMRUNTIME/ftplugin/
|
|
|
65
|
|
|
66 More details about writing a filetype plugin can be found here:
|
|
|
67 |write-plugin|.
|
|
|
68
|
|
|
69 ==============================================================================
|
|
|
70 *43.2* Adding a filetype
|
|
|
71
|
|
|
72 If you are using a type of file that is not recognized by Vim, this is how to
|
|
|
73 get it recognized. You need a runtime directory of your own. See
|
|
|
74 |your-runtime-dir| above.
|
|
|
75
|
|
|
76 Create a file "filetype.vim" which contains an autocommand for your filetype.
|
|
|
77 (Autocommands were explained in section |40.3|.) Example: >
|
|
|
78
|
|
|
79 augroup filetypedetect
|
|
|
80 au BufNewFile,BufRead *.xyz setf xyz
|
|
|
81 augroup END
|
|
|
82
|
|
|
83 This will recognize all files that end in ".xyz" as the "xyz" filetype. The
|
|
|
84 ":augroup" commands put this autocommand in the "filetypedetect" group. This
|
|
|
85 allows removing all autocommands for filetype detection when doing ":filetype
|
|
|
86 off". The "setf" command will set the 'filetype' option to its argument,
|
|
|
87 unless it was set already. This will make sure that 'filetype' isn't set
|
|
|
88 twice.
|
|
|
89
|
|
|
90 You can use many different patterns to match the name of your file. Directory
|
|
|
91 names can also be included. See |autocmd-patterns|. For example, the files
|
|
|
92 under "/usr/share/scripts/" are all "ruby" files, but don't have the expected
|
|
|
93 file name extension. Adding this to the example above: >
|
|
|
94
|
|
|
95 augroup filetypedetect
|
|
|
96 au BufNewFile,BufRead *.xyz setf xyz
|
|
|
97 au BufNewFile,BufRead /usr/share/scripts/* setf ruby
|
|
|
98 augroup END
|
|
|
99
|
|
|
100 However, if you now edit a file /usr/share/scripts/README.txt, this is not a
|
|
|
101 ruby file. The danger of a pattern ending in "*" is that it quickly matches
|
|
|
102 too many files. To avoid trouble with this, put the filetype.vim file in
|
|
|
103 another directory, one that is at the end of 'runtimepath'. For Unix for
|
|
|
104 example, you could use "~/.vim/after/filetype.vim".
|
|
|
105 You now put the detection of text files in ~/.vim/filetype.vim: >
|
|
|
106
|
|
|
107 augroup filetypedetect
|
|
|
108 au BufNewFile,BufRead *.txt setf text
|
|
|
109 augroup END
|
|
|
110
|
|
|
111 That file is found in 'runtimepath' first. Then use this in
|
|
|
112 ~/.vim/after/filetype.vim, which is found last: >
|
|
|
113
|
|
|
114 augroup filetypedetect
|
|
|
115 au BufNewFile,BufRead /usr/share/scripts/* setf ruby
|
|
|
116 augroup END
|
|
|
117
|
|
|
118 What will happen now is that Vim searches for "filetype.vim" files in each
|
|
|
119 directory in 'runtimepath'. First ~/.vim/filetype.vim is found. The
|
|
|
120 autocommand to catch *.txt files is defined there. Then Vim finds the
|
|
|
121 filetype.vim file in $VIMRUNTIME, which is halfway 'runtimepath'. Finally
|
|
|
122 ~/.vim/after/filetype.vim is found and the autocommand for detecting ruby
|
|
|
123 files in /usr/share/scripts is added.
|
|
|
124 When you now edit /usr/share/scripts/README.txt, the autocommands are
|
|
|
125 checked in the order in which they were defined. The *.txt pattern matches,
|
|
|
126 thus "setf text" is executed to set the filetype to "text". The pattern for
|
|
|
127 ruby matches too, and the "setf ruby" is executed. But since 'filetype' was
|
|
|
128 already set to "text", nothing happens here.
|
|
|
129 When you edit the file /usr/share/scripts/foobar the same autocommands are
|
|
|
130 checked. Only the one for ruby matches and "setf ruby" sets 'filetype' to
|
|
|
131 ruby.
|
|
|
132
|
|
|
133
|
|
|
134 RECOGNIZING BY CONTENTS
|
|
|
135
|
|
|
136 If your file cannot be recognized by its file name, you might be able to
|
|
|
137 recognize it by its contents. For example, many script files start with a
|
|
|
138 line like:
|
|
|
139
|
|
|
140 #!/bin/xyz ~
|
|
|
141
|
|
|
142 To recognize this script create a file "scripts.vim" in your runtime directory
|
|
|
143 (same place where filetype.vim goes). It might look like this: >
|
|
|
144
|
|
|
145 if did_filetype()
|
|
|
146 finish
|
|
|
147 endif
|
|
|
148 if getline(1) =~ '^#!.*[/\\]xyz\>'
|
|
|
149 setf xyz
|
|
|
150 endif
|
|
|
151
|
|
|
152 The first check with did_filetype() is to avoid that you will check the
|
|
|
153 contents of files for which the filetype was already detected by the file
|
|
|
154 name. That avoids wasting time on checking the file when the "setf" command
|
|
|
155 won't do anything.
|
|
|
156 The scripts.vim file is sourced by an autocommand in the default
|
|
|
157 filetype.vim file. Therefore, the order of checks is:
|
|
|
158
|
|
|
159 1. filetype.vim files before $VIMRUNTIME in 'runtimepath'
|
|
|
160 2. first part of $VIMRUNTIME/filetype.vim
|
|
|
161 3. all scripts.vim files in 'runtimepath'
|
|
|
162 4. remainder of $VIMRUNTIME/filetype.vim
|
|
|
163 5. filetype.vim files after $VIMRUNTIME in 'runtimepath'
|
|
|
164
|
|
|
165 If this is not sufficient for you, add an autocommand that matches all files
|
|
|
166 and sources a script or executes a function to check the contents of the file.
|
|
|
167
|
|
|
168 ==============================================================================
|
|
|
169
|
|
|
170 Next chapter: |usr_44.txt| Your own syntax highlighted
|
|
|
171
|
|
|
172 Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl:
|
