Mercurial > vim
annotate runtime/doc/usr_43.txt @ 15464:3faa7cc8207c v8.1.0740
patch 8.1.0740: Tcl test fails
commit https://github.com/vim/vim/commit/8309b0559da6e9a581a7816572594c90c2d7f942
Author: Bram Moolenaar <Bram@vim.org>
Date: Sun Jan 13 16:46:22 2019 +0100
patch 8.1.0740: Tcl test fails
Problem: Tcl test fails.
Solution: When the argument is empty don't give an error, instead rely on
the error reporting higher up.
author | Bram Moolenaar <Bram@vim.org> |
---|---|
date | Sun, 13 Jan 2019 17:00:06 +0100 |
parents | 5c5908e81e93 |
children | af69c9335223 |
rev | line source |
---|---|
13963 | 1 *usr_43.txt* For Vim version 8.1. Last change: 2015 Oct 23 |
7 | 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> | |
7183
ffad29dc7eee
commit https://github.com/vim/vim/commit/a0f849ee40cbea3c889345256786b640b0becca2
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
49 let b:undo_ftplugin = "setl softtabstop< | unmap <buffer> <LocalLeader>c" |
7 | 50 |
51 Try editing a C file. You should notice that the 'softtabstop' option is set | |
52 to 4. But when you edit another file it's reset to the default zero. That is | |
53 because the ":setlocal" command was used. This sets the 'softtabstop' option | |
54 only locally to the buffer. As soon as you edit another buffer, it will be | |
55 set to the value set for that buffer. For a new buffer it will get the | |
56 default value or the value from the last ":set" command. | |
57 | |
58 Likewise, the mapping for "\c" will disappear when editing another buffer. | |
59 The ":map <buffer>" command creates a mapping that is local to the current | |
60 buffer. This works with any mapping command: ":map!", ":vmap", etc. The | |
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
61 |<LocalLeader>| in the mapping is replaced with the value of the |
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
62 "maplocalleader" variable. |
7 | 63 |
7183
ffad29dc7eee
commit https://github.com/vim/vim/commit/a0f849ee40cbea3c889345256786b640b0becca2
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
64 The line to set b:undo_ftplugin is for when the filetype is set to another |
ffad29dc7eee
commit https://github.com/vim/vim/commit/a0f849ee40cbea3c889345256786b640b0becca2
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
65 value. In that case you will want to undo your preferences. The |
ffad29dc7eee
commit https://github.com/vim/vim/commit/a0f849ee40cbea3c889345256786b640b0becca2
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
66 b:undo_ftplugin variable is executed as a command. Watch out for characters |
ffad29dc7eee
commit https://github.com/vim/vim/commit/a0f849ee40cbea3c889345256786b640b0becca2
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
67 with a special meaning inside a string, such as a backslash. |
ffad29dc7eee
commit https://github.com/vim/vim/commit/a0f849ee40cbea3c889345256786b640b0becca2
Christian Brabandt <cb@256bit.org>
parents:
5294
diff
changeset
|
68 |
7 | 69 You can find examples for filetype plugins in this directory: > |
70 | |
71 $VIMRUNTIME/ftplugin/ | |
72 | |
73 More details about writing a filetype plugin can be found here: | |
74 |write-plugin|. | |
75 | |
76 ============================================================================== | |
77 *43.2* Adding a filetype | |
78 | |
79 If you are using a type of file that is not recognized by Vim, this is how to | |
80 get it recognized. You need a runtime directory of your own. See | |
81 |your-runtime-dir| above. | |
82 | |
83 Create a file "filetype.vim" which contains an autocommand for your filetype. | |
84 (Autocommands were explained in section |40.3|.) Example: > | |
85 | |
86 augroup filetypedetect | |
87 au BufNewFile,BufRead *.xyz setf xyz | |
88 augroup END | |
89 | |
90 This will recognize all files that end in ".xyz" as the "xyz" filetype. The | |
91 ":augroup" commands put this autocommand in the "filetypedetect" group. This | |
92 allows removing all autocommands for filetype detection when doing ":filetype | |
93 off". The "setf" command will set the 'filetype' option to its argument, | |
94 unless it was set already. This will make sure that 'filetype' isn't set | |
95 twice. | |
96 | |
97 You can use many different patterns to match the name of your file. Directory | |
98 names can also be included. See |autocmd-patterns|. For example, the files | |
99 under "/usr/share/scripts/" are all "ruby" files, but don't have the expected | |
100 file name extension. Adding this to the example above: > | |
101 | |
102 augroup filetypedetect | |
103 au BufNewFile,BufRead *.xyz setf xyz | |
104 au BufNewFile,BufRead /usr/share/scripts/* setf ruby | |
105 augroup END | |
106 | |
107 However, if you now edit a file /usr/share/scripts/README.txt, this is not a | |
108 ruby file. The danger of a pattern ending in "*" is that it quickly matches | |
109 too many files. To avoid trouble with this, put the filetype.vim file in | |
110 another directory, one that is at the end of 'runtimepath'. For Unix for | |
111 example, you could use "~/.vim/after/filetype.vim". | |
112 You now put the detection of text files in ~/.vim/filetype.vim: > | |
113 | |
114 augroup filetypedetect | |
115 au BufNewFile,BufRead *.txt setf text | |
116 augroup END | |
117 | |
118 That file is found in 'runtimepath' first. Then use this in | |
119 ~/.vim/after/filetype.vim, which is found last: > | |
120 | |
121 augroup filetypedetect | |
122 au BufNewFile,BufRead /usr/share/scripts/* setf ruby | |
123 augroup END | |
124 | |
125 What will happen now is that Vim searches for "filetype.vim" files in each | |
126 directory in 'runtimepath'. First ~/.vim/filetype.vim is found. The | |
127 autocommand to catch *.txt files is defined there. Then Vim finds the | |
128 filetype.vim file in $VIMRUNTIME, which is halfway 'runtimepath'. Finally | |
129 ~/.vim/after/filetype.vim is found and the autocommand for detecting ruby | |
130 files in /usr/share/scripts is added. | |
131 When you now edit /usr/share/scripts/README.txt, the autocommands are | |
132 checked in the order in which they were defined. The *.txt pattern matches, | |
133 thus "setf text" is executed to set the filetype to "text". The pattern for | |
134 ruby matches too, and the "setf ruby" is executed. But since 'filetype' was | |
135 already set to "text", nothing happens here. | |
136 When you edit the file /usr/share/scripts/foobar the same autocommands are | |
137 checked. Only the one for ruby matches and "setf ruby" sets 'filetype' to | |
138 ruby. | |
139 | |
140 | |
141 RECOGNIZING BY CONTENTS | |
142 | |
143 If your file cannot be recognized by its file name, you might be able to | |
144 recognize it by its contents. For example, many script files start with a | |
145 line like: | |
146 | |
147 #!/bin/xyz ~ | |
148 | |
149 To recognize this script create a file "scripts.vim" in your runtime directory | |
150 (same place where filetype.vim goes). It might look like this: > | |
151 | |
152 if did_filetype() | |
153 finish | |
154 endif | |
155 if getline(1) =~ '^#!.*[/\\]xyz\>' | |
156 setf xyz | |
157 endif | |
158 | |
159 The first check with did_filetype() is to avoid that you will check the | |
160 contents of files for which the filetype was already detected by the file | |
161 name. That avoids wasting time on checking the file when the "setf" command | |
162 won't do anything. | |
163 The scripts.vim file is sourced by an autocommand in the default | |
164 filetype.vim file. Therefore, the order of checks is: | |
165 | |
166 1. filetype.vim files before $VIMRUNTIME in 'runtimepath' | |
167 2. first part of $VIMRUNTIME/filetype.vim | |
168 3. all scripts.vim files in 'runtimepath' | |
169 4. remainder of $VIMRUNTIME/filetype.vim | |
170 5. filetype.vim files after $VIMRUNTIME in 'runtimepath' | |
171 | |
172 If this is not sufficient for you, add an autocommand that matches all files | |
173 and sources a script or executes a function to check the contents of the file. | |
174 | |
175 ============================================================================== | |
176 | |
177 Next chapter: |usr_44.txt| Your own syntax highlighted | |
178 | |
14519 | 179 Copyright: see |manual-copyright| vim:tw=78:ts=8:noet:ft=help:norl: |