Mercurial > vim
annotate runtime/doc/usr_43.txt @ 2969:5d1d554aba04
Added tag v7-3-256 for changeset c296c225736e
| author | Bram Moolenaar <bram@vim.org> |
|---|---|
| date | Wed, 20 Jul 2011 15:09:44 +0200 |
| parents | 073ff46fe397 |
| children | 6ec6b7ff2d43 |
| rev | line source |
|---|---|
|
2572
ee53a39d5896
Last changes for the 7.3 release!
Bram Moolenaar <bram@vim.org>
parents:
2561
diff
changeset
|
1 *usr_43.txt* For Vim version 7.3. Last change: 2008 Dec 28 |
| 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> | |
| 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 | |
|
2033
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
60 |<LocalLeader>| in the mapping is replaced with the value of the |
|
de5a43c5eedc
Update documentation files.
Bram Moolenaar <bram@zimbu.org>
parents:
1702
diff
changeset
|
61 "maplocalleader" variable. |
| 7 | 62 |
| 63 You can find examples for filetype plugins in this directory: > | |
| 64 | |
| 65 $VIMRUNTIME/ftplugin/ | |
| 66 | |
| 67 More details about writing a filetype plugin can be found here: | |
| 68 |write-plugin|. | |
| 69 | |
| 70 ============================================================================== | |
| 71 *43.2* Adding a filetype | |
| 72 | |
| 73 If you are using a type of file that is not recognized by Vim, this is how to | |
| 74 get it recognized. You need a runtime directory of your own. See | |
| 75 |your-runtime-dir| above. | |
| 76 | |
| 77 Create a file "filetype.vim" which contains an autocommand for your filetype. | |
| 78 (Autocommands were explained in section |40.3|.) Example: > | |
| 79 | |
| 80 augroup filetypedetect | |
| 81 au BufNewFile,BufRead *.xyz setf xyz | |
| 82 augroup END | |
| 83 | |
| 84 This will recognize all files that end in ".xyz" as the "xyz" filetype. The | |
| 85 ":augroup" commands put this autocommand in the "filetypedetect" group. This | |
| 86 allows removing all autocommands for filetype detection when doing ":filetype | |
| 87 off". The "setf" command will set the 'filetype' option to its argument, | |
| 88 unless it was set already. This will make sure that 'filetype' isn't set | |
| 89 twice. | |
| 90 | |
| 91 You can use many different patterns to match the name of your file. Directory | |
| 92 names can also be included. See |autocmd-patterns|. For example, the files | |
| 93 under "/usr/share/scripts/" are all "ruby" files, but don't have the expected | |
| 94 file name extension. Adding this to the example above: > | |
| 95 | |
| 96 augroup filetypedetect | |
| 97 au BufNewFile,BufRead *.xyz setf xyz | |
| 98 au BufNewFile,BufRead /usr/share/scripts/* setf ruby | |
| 99 augroup END | |
| 100 | |
| 101 However, if you now edit a file /usr/share/scripts/README.txt, this is not a | |
| 102 ruby file. The danger of a pattern ending in "*" is that it quickly matches | |
| 103 too many files. To avoid trouble with this, put the filetype.vim file in | |
| 104 another directory, one that is at the end of 'runtimepath'. For Unix for | |
| 105 example, you could use "~/.vim/after/filetype.vim". | |
| 106 You now put the detection of text files in ~/.vim/filetype.vim: > | |
| 107 | |
| 108 augroup filetypedetect | |
| 109 au BufNewFile,BufRead *.txt setf text | |
| 110 augroup END | |
| 111 | |
| 112 That file is found in 'runtimepath' first. Then use this in | |
| 113 ~/.vim/after/filetype.vim, which is found last: > | |
| 114 | |
| 115 augroup filetypedetect | |
| 116 au BufNewFile,BufRead /usr/share/scripts/* setf ruby | |
| 117 augroup END | |
| 118 | |
| 119 What will happen now is that Vim searches for "filetype.vim" files in each | |
| 120 directory in 'runtimepath'. First ~/.vim/filetype.vim is found. The | |
| 121 autocommand to catch *.txt files is defined there. Then Vim finds the | |
| 122 filetype.vim file in $VIMRUNTIME, which is halfway 'runtimepath'. Finally | |
| 123 ~/.vim/after/filetype.vim is found and the autocommand for detecting ruby | |
| 124 files in /usr/share/scripts is added. | |
| 125 When you now edit /usr/share/scripts/README.txt, the autocommands are | |
| 126 checked in the order in which they were defined. The *.txt pattern matches, | |
| 127 thus "setf text" is executed to set the filetype to "text". The pattern for | |
| 128 ruby matches too, and the "setf ruby" is executed. But since 'filetype' was | |
| 129 already set to "text", nothing happens here. | |
| 130 When you edit the file /usr/share/scripts/foobar the same autocommands are | |
| 131 checked. Only the one for ruby matches and "setf ruby" sets 'filetype' to | |
| 132 ruby. | |
| 133 | |
| 134 | |
| 135 RECOGNIZING BY CONTENTS | |
| 136 | |
| 137 If your file cannot be recognized by its file name, you might be able to | |
| 138 recognize it by its contents. For example, many script files start with a | |
| 139 line like: | |
| 140 | |
| 141 #!/bin/xyz ~ | |
| 142 | |
| 143 To recognize this script create a file "scripts.vim" in your runtime directory | |
| 144 (same place where filetype.vim goes). It might look like this: > | |
| 145 | |
| 146 if did_filetype() | |
| 147 finish | |
| 148 endif | |
| 149 if getline(1) =~ '^#!.*[/\\]xyz\>' | |
| 150 setf xyz | |
| 151 endif | |
| 152 | |
| 153 The first check with did_filetype() is to avoid that you will check the | |
| 154 contents of files for which the filetype was already detected by the file | |
| 155 name. That avoids wasting time on checking the file when the "setf" command | |
| 156 won't do anything. | |
| 157 The scripts.vim file is sourced by an autocommand in the default | |
| 158 filetype.vim file. Therefore, the order of checks is: | |
| 159 | |
| 160 1. filetype.vim files before $VIMRUNTIME in 'runtimepath' | |
| 161 2. first part of $VIMRUNTIME/filetype.vim | |
| 162 3. all scripts.vim files in 'runtimepath' | |
| 163 4. remainder of $VIMRUNTIME/filetype.vim | |
| 164 5. filetype.vim files after $VIMRUNTIME in 'runtimepath' | |
| 165 | |
| 166 If this is not sufficient for you, add an autocommand that matches all files | |
| 167 and sources a script or executes a function to check the contents of the file. | |
| 168 | |
| 169 ============================================================================== | |
| 170 | |
| 171 Next chapter: |usr_44.txt| Your own syntax highlighted | |
| 172 | |
| 173 Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl: |