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