mirror of
https://github.com/neovim/neovim.git
synced 2024-12-26 14:11:15 -07:00
fbaee922d1
closes #9719
179 lines
7.3 KiB
Plaintext
179 lines
7.3 KiB
Plaintext
*usr_43.txt* Nvim
|
|
|
|
VIM USER MANUAL - by Bram Moolenaar
|
|
|
|
Using filetypes
|
|
|
|
|
|
When you are editing a file of a certain type, for example a C program or a
|
|
shell script, you often use the same option settings and mappings. You
|
|
quickly get tired of manually setting these each time. This chapter explains
|
|
how to do it automatically.
|
|
|
|
|43.1| Plugins for a filetype
|
|
|43.2| Adding a filetype
|
|
|
|
Next chapter: |usr_44.txt| Your own syntax highlighted
|
|
Previous chapter: |usr_42.txt| Add new menus
|
|
Table of contents: |usr_toc.txt|
|
|
|
|
==============================================================================
|
|
*43.1* Plugins for a filetype *filetype-plugin*
|
|
|
|
How to start using filetype plugins has already been discussed here:
|
|
|add-filetype-plugin|. But you probably are not satisfied with the default
|
|
settings, because they have been kept minimal. Suppose that for C files you
|
|
want to set the 'softtabstop' option to 4 and define a mapping to insert a
|
|
three-line comment. You do this with only two steps:
|
|
|
|
*your-runtime-dir*
|
|
1. Create your own runtime directory. On Unix this usually is
|
|
"~/.config/nvim". In this directory create the "ftplugin" directory: >
|
|
|
|
mkdir -p ~/.config/nvim/ftplugin
|
|
<
|
|
When you are not on Unix, check the value of the 'runtimepath' option to
|
|
see where Vim will look for the "ftplugin" directory: >
|
|
|
|
set runtimepath?
|
|
|
|
< You would normally use the first directory name (before the first comma).
|
|
You might want to prepend a directory name to the 'runtimepath' option in
|
|
your |init.vim| file if you don't like the default value.
|
|
|
|
2. Create the file "~/.config/nvim/ftplugin/c.vim", with the contents: >
|
|
|
|
setlocal softtabstop=4
|
|
noremap <buffer> <LocalLeader>c o/**************<CR><CR>/<Esc>
|
|
let b:undo_ftplugin = "setl softtabstop< | unmap <buffer> <LocalLeader>c"
|
|
|
|
Try editing a C file. You should notice that the 'softtabstop' option is set
|
|
to 4. But when you edit another file it's reset to the default zero. That is
|
|
because the ":setlocal" command was used. This sets the 'softtabstop' option
|
|
only locally to the buffer. As soon as you edit another buffer, it will be
|
|
set to the value set for that buffer. For a new buffer it will get the
|
|
default value or the value from the last ":set" command.
|
|
|
|
Likewise, the mapping for "\c" will disappear when editing another buffer.
|
|
The ":map <buffer>" command creates a mapping that is local to the current
|
|
buffer. This works with any mapping command: ":map!", ":vmap", etc. The
|
|
|<LocalLeader>| in the mapping is replaced with the value of the
|
|
"maplocalleader" variable.
|
|
|
|
The line to set b:undo_ftplugin is for when the filetype is set to another
|
|
value. In that case you will want to undo your preferences. The
|
|
b:undo_ftplugin variable is executed as a command. Watch out for characters
|
|
with a special meaning inside a string, such as a backslash.
|
|
|
|
You can find examples for filetype plugins in this directory: >
|
|
|
|
$VIMRUNTIME/ftplugin/
|
|
|
|
More details about writing a filetype plugin can be found here:
|
|
|write-plugin|.
|
|
|
|
==============================================================================
|
|
*43.2* Adding a filetype
|
|
|
|
If you are using a type of file that is not recognized by Vim, this is how to
|
|
get it recognized. You need a runtime directory of your own. See
|
|
|your-runtime-dir| above.
|
|
|
|
Create a file "filetype.vim" which contains an autocommand for your filetype.
|
|
(Autocommands were explained in section |40.3|.) Example: >
|
|
|
|
augroup filetypedetect
|
|
au BufNewFile,BufRead *.xyz setf xyz
|
|
augroup END
|
|
|
|
This will recognize all files that end in ".xyz" as the "xyz" filetype. The
|
|
":augroup" commands put this autocommand in the "filetypedetect" group. This
|
|
allows removing all autocommands for filetype detection when doing ":filetype
|
|
off". The "setf" command will set the 'filetype' option to its argument,
|
|
unless it was set already. This will make sure that 'filetype' isn't set
|
|
twice.
|
|
|
|
You can use many different patterns to match the name of your file. Directory
|
|
names can also be included. See |autocmd-pattern|. For example, the files
|
|
under "/usr/share/scripts/" are all "ruby" files, but don't have the expected
|
|
file name extension. Adding this to the example above: >
|
|
|
|
augroup filetypedetect
|
|
au BufNewFile,BufRead *.xyz setf xyz
|
|
au BufNewFile,BufRead /usr/share/scripts/* setf ruby
|
|
augroup END
|
|
|
|
However, if you now edit a file /usr/share/scripts/README.txt, this is not a
|
|
ruby file. The danger of a pattern ending in "*" is that it quickly matches
|
|
too many files. To avoid trouble with this, put the filetype.vim file in
|
|
another directory, one that is at the end of 'runtimepath'. For Unix for
|
|
example, you could use "~/.config/nvim/after/filetype.vim".
|
|
You now put the detection of text files in ~/.config/nvim/filetype.vim: >
|
|
|
|
augroup filetypedetect
|
|
au BufNewFile,BufRead *.txt setf text
|
|
augroup END
|
|
|
|
That file is found in 'runtimepath' first. Then use this in
|
|
~/.config/nvim/after/filetype.vim, which is found last: >
|
|
|
|
augroup filetypedetect
|
|
au BufNewFile,BufRead /usr/share/scripts/* setf ruby
|
|
augroup END
|
|
|
|
What will happen now is that Vim searches for "filetype.vim" files in each
|
|
directory in 'runtimepath'. First ~/.config/nvim/filetype.vim is found. The
|
|
autocommand to catch *.txt files is defined there. Then Vim finds the
|
|
filetype.vim file in $VIMRUNTIME, which is halfway 'runtimepath'. Finally
|
|
~/.config/nvim/after/filetype.vim is found and the autocommand for detecting
|
|
ruby files in /usr/share/scripts is added.
|
|
When you now edit /usr/share/scripts/README.txt, the autocommands are
|
|
checked in the order in which they were defined. The *.txt pattern matches,
|
|
thus "setf text" is executed to set the filetype to "text". The pattern for
|
|
ruby matches too, and the "setf ruby" is executed. But since 'filetype' was
|
|
already set to "text", nothing happens here.
|
|
When you edit the file /usr/share/scripts/foobar the same autocommands are
|
|
checked. Only the one for ruby matches and "setf ruby" sets 'filetype' to
|
|
ruby.
|
|
|
|
|
|
RECOGNIZING BY CONTENTS
|
|
|
|
If your file cannot be recognized by its file name, you might be able to
|
|
recognize it by its contents. For example, many script files start with a
|
|
line like:
|
|
|
|
#!/bin/xyz ~
|
|
|
|
To recognize this script create a file "scripts.vim" in your runtime directory
|
|
(same place where filetype.vim goes). It might look like this: >
|
|
|
|
if did_filetype()
|
|
finish
|
|
endif
|
|
if getline(1) =~ '^#!.*[/\\]xyz\>'
|
|
setf xyz
|
|
endif
|
|
|
|
The first check with did_filetype() is to avoid that you will check the
|
|
contents of files for which the filetype was already detected by the file
|
|
name. That avoids wasting time on checking the file when the "setf" command
|
|
won't do anything.
|
|
The scripts.vim file is sourced by an autocommand in the default
|
|
filetype.vim file. Therefore, the order of checks is:
|
|
|
|
1. filetype.vim files before $VIMRUNTIME in 'runtimepath'
|
|
2. first part of $VIMRUNTIME/filetype.vim
|
|
3. all scripts.vim files in 'runtimepath'
|
|
4. remainder of $VIMRUNTIME/filetype.vim
|
|
5. filetype.vim files after $VIMRUNTIME in 'runtimepath'
|
|
|
|
If this is not sufficient for you, add an autocommand that matches all files
|
|
and sources a script or executes a function to check the contents of the file.
|
|
|
|
==============================================================================
|
|
|
|
Next chapter: |usr_44.txt| Your own syntax highlighted
|
|
|
|
Copyright: see |manual-copyright| vim:tw=78:ts=8:noet:ft=help:norl:
|