468 lines
18 KiB
Text
468 lines
18 KiB
Text
*syntastic.txt* Syntax checking on the fly has never been so pimp.
|
|
*syntastic*
|
|
|
|
|
|
It's a bird! It's a plane! ZOMG It's ... ~
|
|
|
|
_____ __ __ _ ~
|
|
/ ___/__ ______ / /_____ ______/ /_(_)____ ~
|
|
\__ \/ / / / __ \/ __/ __ `/ ___/ __/ / ___/ ~
|
|
___/ / /_/ / / / / /_/ /_/ (__ ) /_/ / /__ ~
|
|
/____/\__, /_/ /_/\__/\__,_/____/\__/_/\___/ ~
|
|
/____/ ~
|
|
|
|
|
|
|
|
Reference Manual~
|
|
|
|
|
|
==============================================================================
|
|
CONTENTS *syntastic-contents*
|
|
|
|
1.Intro...................................|syntastic-intro|
|
|
2.Functionality provided..................|syntastic-functionality|
|
|
2.1.The statusline flag...............|syntastic-statusline-flag|
|
|
2.2.Error signs.......................|syntastic-error-signs|
|
|
2.3.Error window......................|syntastic-error-window|
|
|
3.Commands................................|syntastic-commands|
|
|
4.Global Options..........................|syntastic-global-options|
|
|
5.Checker Options.........................|syntastic-checker-options|
|
|
6.About...................................|syntastic-about|
|
|
7.License.................................|syntastic-license|
|
|
|
|
|
|
==============================================================================
|
|
1. Intro *syntastic-intro*
|
|
|
|
Note: This doc only deals with using syntastic. To learn how to write syntax
|
|
checker integrations, see the guide on the github wiki:
|
|
|
|
https://github.com/scrooloose/syntastic/wiki/Syntax-Checker-Guide
|
|
|
|
Syntastic is a syntax checking plugin that runs files through external syntax
|
|
checkers. This can be done on demand, or automatically as files are saved and
|
|
opened. If syntax errors are detected, the user is notified and is happy
|
|
because they didn't have to compile their code or execute their script to find
|
|
them.
|
|
|
|
Syntastic comes in two parts: the syntax checker plugins, and the core. The
|
|
syntax checker plugins are defined on a per-filetype basis where each one wraps
|
|
up an external syntax checking program. The core script delegates off to these
|
|
plugins and uses their output to provide the syntastic functionality.
|
|
|
|
Take a look in the syntax_checkers directory for a list of supported filetypes
|
|
and checkers.
|
|
|
|
|
|
==============================================================================
|
|
2. Functionality provided *syntastic-functionality*
|
|
|
|
Syntax checking can be done automatically or on demand (see
|
|
|'syntastic_mode_map'| for configuring this).
|
|
|
|
When syntax checking is done, the features below can be used to notify the
|
|
user of errors. See |syntastic-options| for how to configure and
|
|
activate/deactivate these features.
|
|
|
|
* A statusline flag
|
|
* Signs beside lines with errors
|
|
* The |location-list| can be populated with the errors for the associated
|
|
buffer.
|
|
* Erroneous parts of lines can be highlighted (this functionality is only
|
|
provided by some syntax checkers).
|
|
* Balloons (if compiled in) can be used to display error messages for
|
|
erroneous lines when hovering the mouse over them.
|
|
|
|
|
|
------------------------------------------------------------------------------
|
|
2.1. The statusline flag *syntastic-statusline-flag*
|
|
|
|
To use the statusline flag, this must appear in your |'statusline'| setting >
|
|
%{SyntasticStatuslineFlag()}
|
|
<
|
|
Something like this could be more useful: >
|
|
set statusline+=%#warningmsg#
|
|
set statusline+=%{SyntasticStatuslineFlag()}
|
|
set statusline+=%*
|
|
<
|
|
When syntax errors are detected a flag will be shown. The content of the flag
|
|
is derived from the |syntastic_stl_format| option
|
|
------------------------------------------------------------------------------
|
|
2.2. Error signs *syntastic-error-signs*
|
|
|
|
Syntastic uses the |:sign| commands to mark lines with errors and warnings in
|
|
the sign column. To enable this feature, use the |'syntastic_enable_signs'|
|
|
option.
|
|
|
|
Signs are colored using the Error and Todo syntax highlight groups by default.
|
|
If you wish to customize the colors for the signs, you can use the following
|
|
groups:
|
|
SyntasticErrorSign - For syntax errors, links to 'error' by default
|
|
SyntasticWarningSign - For syntax warnings, links to 'todo' by default
|
|
SyntasticStyleErrorSign - For style errors, links to 'SyntasticErrorSign'
|
|
by default
|
|
SyntasticStyleWarningSign - For style warnings, links to
|
|
'SyntasticWarningSign' by default
|
|
|
|
Example: >
|
|
highlight SyntasticErrorSign guifg=white guibg=red
|
|
<
|
|
To set up highlighting for the line where a sign resides, you can use the
|
|
following highlight groups:
|
|
SyntasticErrorLine
|
|
SyntasticWarningLine
|
|
SyntasticStyleErrorLine - Links to 'SyntasticErrorLine' by default
|
|
SyntasticStyleWarningLine - Links to 'SyntasticWarningLine' by default
|
|
|
|
Example: >
|
|
highlight SyntasticErrorLine guibg=#2f0000
|
|
<
|
|
|
|
------------------------------------------------------------------------------
|
|
2.3. The error window *:Errors* *syntastic-error-window*
|
|
|
|
You can use the :Errors command to display the errors for the current buffer
|
|
in the |location-list|.
|
|
|
|
Note that when you use :Errors, the current location list is overwritten with
|
|
Syntastic's own location list.
|
|
|
|
|
|
==============================================================================
|
|
3. Commands *syntastic-commands*
|
|
|
|
:Errors *:SyntasticErrors*
|
|
|
|
When errors have been detected, use this command to pop up the |location-list|
|
|
and display the error messages.
|
|
|
|
|
|
:SyntasticToggleMode *:SyntasticToggleMode*
|
|
|
|
Toggles syntastic between active and passive mode. See |'syntastic_mode_map'|
|
|
for more info.
|
|
|
|
|
|
:SyntasticCheck *:SyntasticCheck*
|
|
|
|
Manually cause a syntax check to be done. Useful in passive mode, or if the
|
|
current filetype is set to passive. See |'syntastic_mode_map'| for more info.
|
|
|
|
:SyntasticInfo *:SyntasticInfo*
|
|
|
|
Output info about what checkers are available and in use for the current
|
|
filetype.
|
|
|
|
:SyntasticReset *:SyntasticReset*
|
|
|
|
Resets the list of errors and turns off all error notifiers.
|
|
|
|
|
|
==============================================================================
|
|
4. Global Options *syntastic-global-options*
|
|
|
|
|
|
*'syntastic_check_on_open'*
|
|
Default: 0
|
|
If enabled, syntastic will do syntax checks when buffers are first loaded as
|
|
well as on saving >
|
|
let g:syntastic_check_on_open=1
|
|
<
|
|
|
|
*'syntastic_check_on_wq'*
|
|
Default: 1
|
|
Normally syntastic runs syntax checks whenever buffers are written to disk.
|
|
If you want to skip these checks when you issue |:wq|, |:x|, and |:ZZ|, set this
|
|
variable to 0. >
|
|
let g:syntastic_check_on_wq=0
|
|
<
|
|
|
|
*'syntastic_aggregate_errors'*
|
|
Default: 0
|
|
When enabled, |:SyntasticCheck| runs all checkers that apply, then aggregates
|
|
errors found by all checkers and displays them. When disabled,
|
|
|:SyntasticCheck| runs each checker in turn, and stops to display the results
|
|
the first time a checker finds any errors. >
|
|
let g:syntastic_aggregate_errors=1
|
|
<
|
|
|
|
*'syntastic_echo_current_error'*
|
|
Default: 1
|
|
If enabled, syntastic will echo the error associated with the current line to
|
|
the command window. If multiple errors are found, the first will be used. >
|
|
let g:syntastic_echo_current_error=1
|
|
<
|
|
|
|
*'syntastic_enable_signs'*
|
|
Default: 1
|
|
Use this option to tell syntastic whether to use the |:sign| interface to mark
|
|
syntax errors: >
|
|
let g:syntastic_enable_signs=1
|
|
<
|
|
|
|
*'syntastic_error_symbol'* *'syntastic_style_error_symbol'*
|
|
*'syntastic_warning_symbol'* *'syntastic_style_warning_symbol'*
|
|
Use this option to control what the syntastic |:sign| text contains. Several
|
|
error symobls can be customized:
|
|
syntastic_error_symbol - For syntax errors, defaults to '>>'
|
|
syntastic_style_error_symbol - For style errors, defaults to 'S>'
|
|
syntastic_warning_symbol - For syntax warnings, defaults to '>>'
|
|
syntastic_style_warning_symbol - For style warnings, defaults to 'S>'
|
|
|
|
Example: >
|
|
let g:syntastic_error_symbol='✗'
|
|
let g:syntastic_warning_symbol='⚠'
|
|
<
|
|
|
|
*'syntastic_enable_balloons'*
|
|
Default: 1
|
|
Use this option to tell syntastic whether to display error messages in balloons
|
|
when the mouse is hovered over erroneous lines: >
|
|
let g:syntastic_enable_balloons = 1
|
|
<
|
|
Note that vim must be compiled with |+balloon_eval|.
|
|
|
|
*'syntastic_enable_highlighting'*
|
|
Default: 1
|
|
Use this option to tell syntastic whether to use syntax highlighting to mark
|
|
errors (where possible). Highlighting can be turned off with the following >
|
|
let g:syntastic_enable_highlighting = 0
|
|
<
|
|
|
|
*'syntastic_always_populate_loc_list'*
|
|
Default: 0
|
|
Enable this option to tell syntastic to always stick any detected errors into
|
|
the loclist: >
|
|
let g:syntastic_always_populate_loc_list=1
|
|
<
|
|
*'syntastic_auto_jump'*
|
|
Default: 0
|
|
Enable this option if you want the cursor to jump to the first detected error
|
|
when saving or opening a file: >
|
|
let g:syntastic_auto_jump=1
|
|
<
|
|
|
|
*'syntastic_auto_loc_list'*
|
|
Default: 2
|
|
Use this option to tell syntastic to automatically open and/or close the
|
|
|location-list| (see |syntastic-error-window|).
|
|
|
|
When set to 0 the error window will not be opened or closed automatically. >
|
|
let g:syntastic_auto_loc_list=0
|
|
<
|
|
|
|
When set to 1 the error window will be automatically opened when errors are
|
|
detected, and closed when none are detected. >
|
|
let g:syntastic_auto_loc_list=1
|
|
<
|
|
When set to 2 the error window will be automatically closed when no errors are
|
|
detected, but not opened automatically. >
|
|
let g:syntastic_auto_loc_list=2
|
|
<
|
|
|
|
*'syntastic_loc_list_height'*
|
|
Default: 10
|
|
Use this option to specify the height of the location lists that syntastic
|
|
opens. >
|
|
let g:syntastic_loc_list_height=5
|
|
<
|
|
|
|
*'syntastic_ignore_files'*
|
|
Default: []
|
|
Use this option to specify files that syntastic should neither check, nor
|
|
include in error lists. It has to be a list of |regular-expression| patterns.
|
|
The full paths of files (see |::p|) are matched against these patterns, and
|
|
the matches are case sensitive. Use |\c| if you need case insensitive
|
|
patterns. >
|
|
let g:syntastic_ignore_files=['^/usr/include/', '\c\.h$']
|
|
<
|
|
|
|
*'syntastic_filetype_map'*
|
|
Default: {}
|
|
Use this option to map non-standard filetypes to standard ones. Corresponding
|
|
checkers are mapped accordingly, which allows syntastic to check files with
|
|
non-standard filetypes: >
|
|
let g:syntastic_filetype_map = { 'latex': 'tex',
|
|
\ 'gentoo-metadata': 'xml' }
|
|
<
|
|
|
|
*'syntastic_mode_map'*
|
|
Default: { "mode": "active",
|
|
"active_filetypes": [],
|
|
"passive_filetypes": [] }
|
|
|
|
Use this option to fine tune when automatic syntax checking is done (or not
|
|
done).
|
|
|
|
The option should be set to something like: >
|
|
|
|
let g:syntastic_mode_map = { 'mode': 'active',
|
|
\ 'active_filetypes': ['ruby', 'php'],
|
|
\ 'passive_filetypes': ['puppet'] }
|
|
<
|
|
|
|
"mode" can be mapped to one of two values - "active" or "passive". When set to
|
|
active, syntastic does automatic checking whenever a buffer is saved or
|
|
initially opened. When set to "passive" syntastic only checks when the user
|
|
calls |:SyntasticCheck|.
|
|
|
|
The exceptions to these rules are defined with "active_filetypes" and
|
|
"passive_filetypes". In passive mode, automatic checks are still done
|
|
for all filetypes in the "active_filetypes" array. In active mode,
|
|
automatic checks are not done for any filetypes in the
|
|
"passive_filetypes" array.
|
|
|
|
At runtime, the |:SyntasticToggleMode| command can be used to switch between
|
|
active and passive mode.
|
|
|
|
If any of "mode", "active_filetypes", or "passive_filetypes" are not specified
|
|
then they will default to their default value as above.
|
|
|
|
*'syntastic_quiet_warnings'*
|
|
|
|
Use this option if you only care about syntax errors, not warnings. When set,
|
|
this option has the following effects:
|
|
* no |signs| appear unless there is at least one error, whereupon both
|
|
errors and warnings are displayed
|
|
* the |'syntastic_auto_loc_list'| option only pops up the error window if
|
|
there's at least one error, whereupon both errors and warnings are
|
|
displayed
|
|
>
|
|
let g:syntastic_quiet_warnings=1
|
|
<
|
|
|
|
*'syntastic_stl_format'*
|
|
|
|
Default: [Syntax: line:%F (%t)]
|
|
Use this option to control what the syntastic statusline text contains. Several
|
|
magic flags are available to insert information:
|
|
%e - number of errors
|
|
%w - number of warnings
|
|
%t - total number of warnings and errors
|
|
%fe - line number of first error
|
|
%fw - line number of first warning
|
|
%F - line number of first warning or error
|
|
|
|
Several additional flags are available to hide text under certain conditions:
|
|
%E{...} - hide the text in the brackets unless there are errors
|
|
%W{...} - hide the text in the brackets unless there are warnings
|
|
%B{...} - hide the text in the brackets unless there are both warnings AND
|
|
errors
|
|
These flags cant be nested.
|
|
|
|
Example: >
|
|
let g:syntastic_stl_format = '[%E{Err: %fe #%e}%B{, }%W{Warn: %fw #%w}]'
|
|
<
|
|
If this format is used and the current buffer has 5 errors and 1 warning
|
|
starting on lines 20 and 10 respectively then this would appear on the
|
|
statusline: >
|
|
[Err: 20 #5, Warn: 10 #1]
|
|
<
|
|
If the buffer had 2 warnings, starting on line 5 then this would appear: >
|
|
[Warn: 5 #2]
|
|
<
|
|
*'syntastic_full_redraws'*
|
|
Default: 0 in GUI Vim and MacVim, 1 otherwise
|
|
Controls whether syntastic calls |:redraw| or |:redraw!| for screen redraws.
|
|
Changing it can in principle make screen redraws smoother, but it can also
|
|
cause screen flicker, or ghost characters. Leaving it to the default should
|
|
be safe.
|
|
|
|
*'syntastic_debug'*
|
|
Default: 0
|
|
Set this to 1 to enable debugging: >
|
|
let g:syntastic_debug = 1
|
|
<
|
|
Checkers will then add debugging messages to Vim's |message-history|. You can
|
|
examine these messages with |:mes|.
|
|
|
|
|
|
==============================================================================
|
|
5. Checker Options *syntastic-checker-options*
|
|
|
|
------------------------------------------------------------------------------
|
|
5.1 Telling syntastic which checker to use.
|
|
|
|
Stick a line like this in your vimrc: >
|
|
let g:syntastic_<filetype>_checkers = ['<checker-name>']
|
|
<
|
|
e.g. >
|
|
let g:syntastic_python_checkers = ['flake8']
|
|
<
|
|
|
|
There's also a per-buffer version of this setting, b:syntastic_checkers. Use
|
|
this in an autocmd to configure specific checkers for particular paths: >
|
|
autocmd FileType python if stridx(expand('%:p'), '/some/path/') == 0 |
|
|
\ let b:syntastic_checkers = ['pylint'] | endif
|
|
<
|
|
|
|
To see the list of available checkers for your filetype, look in
|
|
`syntax_checkers/<filetype>/`. The names of the files here correspond to
|
|
'<checker-name>' above.
|
|
|
|
e.g. Python has the following checkers: flake8, pyflakes, pylint and a
|
|
native python checker.
|
|
|
|
Some filetypes, like PHP, have style checkers as well as syntax checkers. These
|
|
can be chained together like this: >
|
|
let g:syntastic_php_checkers=['php', 'phpcs', 'phpmd']`
|
|
<
|
|
This is telling syntastic to run the 'php' checker first, and if no errors are
|
|
found, run 'phpcs', and then 'phpmd'.
|
|
|
|
------------------------------------------------------------------------------
|
|
5.2 Configuring specific checkers *syntastic-config-makeprg*
|
|
|
|
Most checkers use the 'syntastic#makeprg#build()' function and provide many
|
|
options by default - in fact you can customise every part of the command
|
|
that gets called.
|
|
|
|
Checkers that use 'syntastic#makeprg#build()' look like this: >
|
|
let makeprg = syntastic#makeprg#build({
|
|
\ 'exe': 'ruby',
|
|
\ 'args': '-a -b -c',
|
|
\ 'post_args': '--more --args',
|
|
\ 'tail': '> /tmp/output',
|
|
\ 'filetype': 'ruby',
|
|
\ 'subchecker': 'mri' })
|
|
<
|
|
|
|
The 'filetype' and 'subchecker' parameters are mandatory. All of the other
|
|
parameters above are optional (well, you probably need at least 'exe'), and
|
|
can be overriden by setting global variables - even parameters not specified
|
|
in the call to syntastic#makeprg#build().
|
|
|
|
E.g. To override the checker exe above, you could do this: >
|
|
let g:syntastic_ruby_mri_exe="another_ruby_checker_exe.rb"
|
|
<
|
|
To override the args and the tail: >
|
|
let g:syntastic_ruby_mri_args="--my --args --here"
|
|
let g:syntastic_ruby_mri_tail="> /tmp/my-output-file-biatch"
|
|
<
|
|
|
|
The general form of the override options is: >
|
|
syntastic_[filetype]_[subchecker]_[option-name]
|
|
<
|
|
|
|
For checkers that do not use the 'syntastic#makeprg#build()' function you
|
|
will have to look at the source code of the checker in question. If there are
|
|
specific options that can be set, these are usually documented at the top of
|
|
the script.
|
|
|
|
==============================================================================
|
|
6. About *syntastic-about*
|
|
|
|
The core maintainers of syntastic are:
|
|
Martin Grenfell (github: scrooloose)
|
|
Gregor Uhlenheuer (github: kongo2002)
|
|
|
|
Find the latest version of syntastic here:
|
|
http://github.com/scrooloose/syntastic
|
|
|
|
==============================================================================
|
|
7. License *syntastic-license*
|
|
|
|
Syntastic is released under the wtfpl.
|
|
See http://sam.zoy.org/wtfpl/COPYING.
|
|
|
|
vim:tw=78:sw=4:ft=help:norl:
|