493 lines
19 KiB
Plaintext
493 lines
19 KiB
Plaintext
*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.Options.................................|syntastic-options|
|
|
5.Writing syntax checkers.................|syntastic-syntax-checkers|
|
|
6.About...................................|syntastic-about|
|
|
7.Changelog...............................|syntastic-changelog|
|
|
8.Credits.................................|syntastic-credits|
|
|
9.License.................................|syntastic-license|
|
|
|
|
|
|
==============================================================================
|
|
1. Intro *syntastic-intro*
|
|
|
|
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 script
|
|
(i.e. syntastic.vim). 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. At the time of this writing, syntax checking plugins
|
|
exist for c, coffee, cpp, css, cucumber, cuda, docbk, erlang, eruby, fortran,
|
|
go, haml, haskell, html, javascript, less, lua, matlab, perl, php, puppet,
|
|
python, ruby, sass/scss, sh, tcl, tex, vala, xhtml, xml, xslt, zpt
|
|
|
|
Take a look in the syntax_checkers directory for the most up to date list.
|
|
|
|
If your language is not supported then see |syntastic-syntax-checkers| for
|
|
details on how to implement a syntax checking plugin, and be sure to send me a
|
|
patch ;-)
|
|
|
|
This plugin is currently only recommended for *nix users. It is functional on
|
|
Windows, but since the syntax checking plugins shell out, the command window
|
|
briefly appears whenever one is executed.
|
|
|
|
|
|
==============================================================================
|
|
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 configurable statusline flag
|
|
* Lines with errors can have |signs| placed beside them - where a different
|
|
sign is used for errors and warnings.
|
|
* A |location-list| can be displayed with error messages for erroneous
|
|
buffers.
|
|
* Offending 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.
|
|
|
|
|
|
Note: This functionality is only available if a syntax checker plugin is
|
|
present for the filetype of the buffer in question. See
|
|
|syntastic-syntax-checkers| for details.
|
|
|
|
------------------------------------------------------------------------------
|
|
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.
|
|
|
|
------------------------------------------------------------------------------
|
|
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.
|
|
|
|
|
|
==============================================================================
|
|
4. Options *syntastic-options*
|
|
|
|
|
|
*'syntastic_echo_current_error'*
|
|
Default: 1
|
|
If enabled, syntastic will error message 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_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_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_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 availble 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]
|
|
<
|
|
|
|
|
|
==============================================================================
|
|
5. Writing syntax checkers *syntastic-syntax-checkers*
|
|
|
|
|
|
A syntax checker plugin is really nothing more than a single function. You
|
|
should define them in ~/.vim/syntax_checkers/<filetype>.vim, but this is
|
|
purely for convenience; Syntastic doesn't actually care where these functions
|
|
are defined.
|
|
|
|
A syntax checker plugin must define a function of the form:
|
|
>
|
|
SyntaxCheckers_<filetype>_GetLocList()
|
|
<
|
|
The output of this function must be of the same format as that returned by
|
|
the |getloclist()| function. See |getloclist()| and |getqflist()| for
|
|
details.
|
|
|
|
To achieve this, the function should call |SyntasticMake()| or shell out to a
|
|
syntax checker, parse the output and munge it into the format.
|
|
|
|
There are several syntax checker plugins provided with this plugin. The ruby
|
|
one is a good example of |SyntasticMake()|, while the haml one is a good
|
|
example of how to create the data structure manually.
|
|
|
|
|
|
SyntasticMake({options}) *SyntasticMake()*
|
|
{options} must be a dictionary. It can contain "makeprg" and "errorformat"
|
|
as keys (both optional).
|
|
|
|
SyntasticMake will run |:lmake| with the given |'makeprg'| and
|
|
|'errorformat'| (using the current settings if none are supplied). It will
|
|
store the resulting error list and use it to provide all of the
|
|
|syntastic-functionality|. The previous makeprg and errorformat settings
|
|
will then be restored, as well as the location list for the window. From
|
|
the user's perspective, it will be as though |:lmake| was never run.
|
|
|
|
Note that the given "makeprg" and "errorformat" will be set using |:let-&|,
|
|
so you should not escape spaces.
|
|
|
|
|
|
==============================================================================
|
|
6. About *syntastic-about*
|
|
|
|
The author of syntastic is a mighty wild stallion, hear him roar! >
|
|
_ _ _____ _____ ___ ___ ___ ____ _ _ _
|
|
| \ | | ____| ____|_ _|_ _|_ _/ ___| | | | |
|
|
| \| | _| | _| | | | | | | | _| |_| | |
|
|
| |\ | |___| |___ | | | | | | |_| | _ |_|
|
|
|_| \_|_____|_____|___|___|___\____|_| |_(_)
|
|
|
|
<
|
|
He likes to trot around in the back yard reading his emails and sipping a
|
|
scolding hot cup of Earl Grey. Email him at martin.grenfell at gmail dot com.
|
|
He can also be found trolling the #vim channel on the freenode IRC network as
|
|
scrooloose.
|
|
|
|
Bug reports, feedback, suggestions etc are welcomed.
|
|
|
|
|
|
The latest official releases will be on vim.org at some point.
|
|
|
|
The latest dev versions are on github
|
|
http://github.com/scrooloose/syntastic
|
|
|
|
==============================================================================
|
|
7. Changelog *syntastic-changelog*
|
|
|
|
Next version
|
|
- when the cursor is on a line containing an error, echo the
|
|
error msg (kevinw)
|
|
- various bug fixes and refactoring
|
|
- updates/fixes to existing checkers:
|
|
- html (millermedeiros)
|
|
- erlang
|
|
- coffeescript
|
|
- javascript
|
|
- sh
|
|
- php (add support for phpcs - technosophos)
|
|
- add an applescript checker (Zhai Cai)
|
|
|
|
2.0.0
|
|
- Add support for highlighting the erroneous parts of lines (kstep)
|
|
- Add support for displaying errors via balloons (kstep)
|
|
- Add syntastic_mode_map option to give more control over when checking
|
|
should be done.
|
|
- Add :SyntasticCheck command to force a syntax check - useful in passive
|
|
mode (justone).
|
|
- Add the option to automatically close the location list, but not
|
|
automatically open it (milkypostman)
|
|
- Add syntastic_auto_jump option to automatically jump to the first
|
|
error (milkypostman)
|
|
- Only source syntax checkers as needed - instead of loading all of them
|
|
when vim starts
|
|
|
|
- Support for new filetypes:
|
|
- less (julienXX)
|
|
- docbook (tpope)
|
|
- matlab (jasongraham)
|
|
- go (dtjm)
|
|
- puppet (uggedal, roman, zsprackett)
|
|
- haskell (baldo, roman)
|
|
- tcl (et)
|
|
- vala (kstep)
|
|
- cuda (temporaer)
|
|
- css (oryband, sitedyno)
|
|
- fortran (Karl Yngve Lervåg)
|
|
- xml (kusnier)
|
|
- xslt (kusnier)
|
|
- erlang (kTT)
|
|
- zpt (claytron)
|
|
|
|
- updates to existing checkers:
|
|
- javascript (mogren, bryanforbes, cjab, ajduncan)
|
|
- sass/scss (tmm1, atourino, dlee, epeli)
|
|
- ruby (changa)
|
|
- perl (harleypig)
|
|
- haml (bmihelac)
|
|
- php (kstep, docteurklein)
|
|
- python (kstep, soli)
|
|
- lua (kstep)
|
|
- html (kstep)
|
|
- xhtml (kstep)
|
|
- c (kongo2002, brandonw)
|
|
- cpp (kongo2002)
|
|
- coffee (industrial)
|
|
- eruby (sergevm)
|
|
|
|
1.2.0
|
|
- New syntax checkers from github:kongo2002
|
|
- c (thanks also to github:jperras)
|
|
- cpp
|
|
- lua
|
|
- sh (thanks also to github:jmcantrell)
|
|
- add coffee syntax checked by github:lstoll
|
|
- add tex syntax checker
|
|
- make html checker play nicer with html5, thanks to github:enaeseth
|
|
- escape filenames properly when invoking syntax checkers, thanks to
|
|
github:jmcantrell
|
|
- adjust the ruby syntax checker to avoid some common annoying warnings,
|
|
thanks to github:robertwahler
|
|
|
|
1.1.0 [codenamed: tpimp]
|
|
- Dont load rubygems for ruby/eruby syntax checkers. Thanks tpope.
|
|
- Improve the javascript syntax checker to catch some warnings that were
|
|
getting missed. Thanks tpope.
|
|
- Dont automatically focus the error window. Thanks tpope.
|
|
- Add support for cucumber [tpope], haskell & perl [Anthony Carapetis],
|
|
and xhtml
|
|
- Add commands to enable/disable syntax checking at runtime. See :help
|
|
syntastic-commands.
|
|
- Add an option to specifiy syntax checkers that should be disabled by
|
|
default. See :help syntastic_disabled_filetypes.
|
|
- Dont use :signs if vim wasnt compiled with support for them.
|
|
)
|
|
|
|
==============================================================================
|
|
8. Credits *syntastic-credits*
|
|
|
|
Thanks to the following people for testing, bug reports, patches etc. They own,
|
|
hard.
|
|
|
|
Zhai Cai
|
|
Matt Butcher (technosophos)
|
|
Kevin Watters (kevinw)
|
|
Miller Medeiros (millermedeiros)
|
|
Pawel Salata (kTT)
|
|
Fjölnir Ásgeirsson (aptiva)
|
|
Clayton Parker (claytron)
|
|
S. Zachariah Sprackett (zsprackett)
|
|
Sylvain Soliman (soli)
|
|
Ricardo Catalinas Jiménez (jimenezrick)
|
|
kusnier
|
|
Klein Florian (docteurklein)
|
|
sitedyno
|
|
Matthew Batema (mlb-)
|
|
Nate Jones (justone)
|
|
sergevm
|
|
Karl Yngve Lervåg
|
|
Pavel Argentov (argent-smith)
|
|
Andy Duncan (ajduncan)
|
|
Antonio Touriño (atourino)
|
|
Chad Jablonski (cjab)
|
|
Roman Gonzalez (roman)
|
|
Tom Wieland (industrial)
|
|
Ory Band (oryband)
|
|
Esa-Matti Suuronen (epeli)
|
|
Brandon Waskiewicz (brandonw)
|
|
dlee
|
|
temporaer
|
|
Jason Graham (jasongraham)
|
|
Sam Nguyen (dtjm)
|
|
Claes Mogren (mogren)
|
|
Eivind Uggedal (uggedal)
|
|
kstep
|
|
Andreas Baldeau (baldo)
|
|
Eric Thomas (et)
|
|
Brian Donovan (eventualbuddha)
|
|
Bryan Forbes (bryanforbes)
|
|
Aman Gupta (tmm1)
|
|
Donald Ephraim Curtis (milkypostman)
|
|
Dominique Rose-Rosette (changa)
|
|
Harley Pig (harleypig)
|
|
bmihelac
|
|
Julien Blanchard (julienXX)
|
|
Gregor Uhlenheuer (kongo2002)
|
|
Lincoln Stoll
|
|
Tim Carey-Smith (halorgium)
|
|
Tim Pope (tpope)
|
|
Travis Jeffery
|
|
Anthony Carapetis
|
|
|
|
|
|
==============================================================================
|
|
9. License *syntastic-license*
|
|
|
|
Syntastic is released under the wtfpl.
|
|
See http://sam.zoy.org/wtfpl/COPYING.
|