]> git.r.bdr.sh - rbdr/dotfiles/blob - vim/doc/syntastic.txt
f0cede366edee80682cfec7ea60830969c700be6
[rbdr/dotfiles] / vim / doc / syntastic.txt
1 *syntastic.txt* Syntax checking on the fly has never been so pimp.
2 *syntastic*
3
4
5 It's a bird! It's a plane! ZOMG It's ... ~
6
7 _____ __ __ _ ~
8 / ___/__ ______ / /_____ ______/ /_(_)____ ~
9 \__ \/ / / / __ \/ __/ __ `/ ___/ __/ / ___/ ~
10 ___/ / /_/ / / / / /_/ /_/ (__ ) /_/ / /__ ~
11 /____/\__, /_/ /_/\__/\__,_/____/\__/_/\___/ ~
12 /____/ ~
13
14
15
16 Reference Manual~
17
18
19 ==============================================================================
20 CONTENTS *syntastic-contents*
21
22 1.Intro...................................|syntastic-intro|
23 2.Functionality provided..................|syntastic-functionality|
24 2.1.The statusline flag...............|syntastic-statusline-flag|
25 2.2.Error signs.......................|syntastic-error-signs|
26 2.3.Error window......................|syntastic-error-window|
27 3.Commands................................|syntastic-commands|
28 4.Options.................................|syntastic-options|
29 5.Writing syntax checkers.................|syntastic-syntax-checkers|
30 6.About...................................|syntastic-about|
31 7.Changelog...............................|syntastic-changelog|
32 8.Credits.................................|syntastic-credits|
33 9.License.................................|syntastic-license|
34
35
36 ==============================================================================
37 1. Intro *syntastic-intro*
38
39 Syntastic is a syntax checking plugin that runs files through external syntax
40 checkers. This can be done on demand, or automatically as files are saved and
41 opened. If syntax errors are detected, the user is notified and is happy
42 because they didn't have to compile their code or execute their script to find
43 them.
44
45 Syntastic comes in two parts: the syntax checker plugins, and the core script
46 (i.e. syntastic.vim). The syntax checker plugins are defined on a per-filetype
47 basis where each one wraps up an external syntax checking program. The core
48 script delegates off to these plugins and uses their output to provide the
49 syntastic functionality. At the time of this writing, syntax checking plugins
50 exist for c, coffee, cpp, css, cucumber, cuda, docbk, erlang, eruby, fortran,
51 go, haml, haskell, html, javascript, less, lua, matlab, perl, php, puppet,
52 python, ruby, sass/scss, sh, tcl, tex, vala, xhtml, xml, xslt, zpt
53
54 Take a look in the syntax_checkers directory for the most up to date list.
55
56 If your language is not supported then see |syntastic-syntax-checkers| for
57 details on how to implement a syntax checking plugin, and be sure to send me a
58 patch ;-)
59
60 This plugin is currently only recommended for *nix users. It is functional on
61 Windows, but since the syntax checking plugins shell out, the command window
62 briefly appears whenever one is executed.
63
64
65 ==============================================================================
66 2. Functionality provided *syntastic-functionality*
67
68 Syntax checking can be done automatically or on demand (see
69 |'syntastic_mode_map'| for configuring this).
70
71 When syntax checking is done, the features below can be used to notify the
72 user of errors. See |syntastic-options| for how to configure and
73 activate/deactivate these features.
74
75 * A configurable statusline flag
76 * Lines with errors can have |signs| placed beside them - where a different
77 sign is used for errors and warnings.
78 * A |location-list| can be displayed with error messages for erroneous
79 buffers.
80 * Offending parts of lines can be highlighted (this functionality is only
81 provided by some syntax checkers).
82 * Balloons (if compiled in) can be used to display error messages for
83 erroneous lines when hovering the mouse over them.
84
85
86 Note: This functionality is only available if a syntax checker plugin is
87 present for the filetype of the buffer in question. See
88 |syntastic-syntax-checkers| for details.
89
90 ------------------------------------------------------------------------------
91 2.1. The statusline flag *syntastic-statusline-flag*
92
93 To use the statusline flag, this must appear in your |'statusline'| setting >
94 %{SyntasticStatuslineFlag()}
95 <
96 Something like this could be more useful: >
97 set statusline+=%#warningmsg#
98 set statusline+=%{SyntasticStatuslineFlag()}
99 set statusline+=%*
100 <
101 When syntax errors are detected a flag will be shown. The content of the flag
102 is derived from the |syntastic_stl_format| option
103 ------------------------------------------------------------------------------
104 2.2. Error signs *syntastic-error-signs*
105
106 Syntastic uses the |:sign| commands to mark lines with errors and warnings in
107 the sign column. To enable this feature, use the |'syntastic_enable_signs'|
108 option.
109
110 ------------------------------------------------------------------------------
111 2.3. The error window *:Errors* *syntastic-error-window*
112
113 You can use the :Errors command to display the errors for the current buffer
114 in the |location-list|.
115
116 Note that when you use :Errors, the current location list is overwritten with
117 Syntastic's own location list.
118
119
120 ==============================================================================
121 3. Commands *syntastic-commands*
122
123 :Errors *:SyntasticErrors*
124
125 When errors have been detected, use this command to pop up the |location-list|
126 and display the error messages.
127
128
129 :SyntasticToggleMode *:SyntasticToggleMode*
130
131 Toggles syntastic between active and passive mode. See |'syntastic_mode_map'|
132 for more info.
133
134
135 :SyntasticCheck *:SyntasticCheck*
136
137 Manually cause a syntax check to be done. Useful in passive mode, or if the
138 current filetype is set to passive. See |'syntastic_mode_map'| for more info.
139
140
141 ==============================================================================
142 4. Options *syntastic-options*
143
144
145 *'syntastic_check_on_open'*
146 Default: 0
147 If enabled, syntastic will do syntax checks when buffers are first loaded as
148 well as on saving >
149 let g:syntastic_check_on_open=1
150 <
151
152 *'syntastic_echo_current_error'*
153 Default: 1
154 If enabled, syntastic will error message associated with the current line to
155 the command window. If multiple errors are found, the first will be used. >
156 let g:syntastic_echo_current_error=1
157 <
158
159 *'syntastic_enable_signs'*
160 Default: 1
161 Use this option to tell syntastic whether to use the |:sign| interface to mark
162 syntax errors: >
163 let g:syntastic_enable_signs=1
164 <
165
166 *'syntastic_enable_balloons'*
167 Default: 1
168 Use this option to tell syntastic whether to display error messages in balloons
169 when the mouse is hovered over erroneous lines: >
170 let g:syntastic_enable_balloons = 1
171 <
172 Note that vim must be compiled with |+balloon_eval|.
173
174 *'syntastic_enable_highlighting'*
175 Default: 1
176 Use this option to tell syntastic whether to use syntax highlighting to mark
177 errors (where possible). Highlighting can be turned off with the following >
178 let g:syntastic_enable_highlighting = 0
179 <
180
181 *'syntastic_auto_jump'*
182 Default: 0
183 Enable this option if you want the cursor to jump to the first detected error
184 when saving or opening a file: >
185 let g:syntastic_auto_jump=1
186 <
187
188 *'syntastic_auto_loc_list'*
189 Default: 2
190 Use this option to tell syntastic to automatically open and/or close the
191 |location-list| (see |syntastic-error-window|).
192
193 When set to 0 the error window will not be opened or closed automatically. >
194 let g:syntastic_auto_loc_list=0
195 <
196
197 When set to 1 the error window will be automatically opened when errors are
198 detected, and closed when none are detected. >
199 let g:syntastic_auto_loc_list=1
200 <
201 When set to 2 the error window will be automatically closed when no errors are
202 detected, but not opened automatically. >
203 let g:syntastic_auto_loc_list=2
204 <
205
206 *'syntastic_loc_list_height'*
207 Default: 10
208 Use this option to specify the height of the location lists that syntastic
209 opens. >
210 let g:syntastic_loc_list_height=5
211 <
212
213
214 *'syntastic_mode_map'*
215 Default: { "mode": "active",
216 "active_filetypes": [],
217 "passive_filetypes": [] }
218
219 Use this option to fine tune when automatic syntax checking is done (or not
220 done).
221
222 The option should be set to something like: >
223
224 let g:syntastic_mode_map = { 'mode': 'active',
225 \ 'active_filetypes': ['ruby', 'php'],
226 \ 'passive_filetypes': ['puppet'] }
227 <
228
229 "mode" can be mapped to one of two values - "active" or "passive". When set to
230 active, syntastic does automatic checking whenever a buffer is saved or
231 initially opened. When set to "passive" syntastic only checks when the user
232 calls :SyntasticCheck.
233
234 The exceptions to these rules are defined with "active_filetypes" and
235 "passive_filetypes". In passive mode, automatic checks are still done
236 for all filetypes in the "active_filetypes" array. In active mode,
237 automatic checks are not done for any filetypes in the
238 "passive_filetypes" array.
239
240 At runtime, the |:SyntasticToggleMode| command can be used to switch between
241 active and passive mode.
242
243 If any of "mode", "active_filetypes", or "passive_filetypes" are not specified
244 then they will default to their default value as above.
245
246 *'syntastic_quiet_warnings'*
247
248 Use this option if you only care about syntax errors, not warnings. When set,
249 this option has the following effects:
250 * no |signs| appear unless there is at least one error, whereupon both
251 errors and warnings are displayed
252 * the |'syntastic_auto_loc_list'| option only pops up the error window if
253 there's at least one error, whereupon both errors and warnings are
254 displayed
255 >
256 let g:syntastic_quiet_warnings=1
257 <
258
259 *'syntastic_stl_format'*
260
261 Default: [Syntax: line:%F (%t)]
262 Use this option to control what the syntastic statusline text contains. Several
263 magic flags are availble to insert information:
264 %e - number of errors
265 %w - number of warnings
266 %t - total number of warnings and errors
267 %fe - line number of first error
268 %fw - line number of first warning
269 %F - line number of first warning or error
270
271 Several additional flags are available to hide text under certain conditions:
272 %E{...} - hide the text in the brackets unless there are errors
273 %W{...} - hide the text in the brackets unless there are warnings
274 %B{...} - hide the text in the brackets unless there are both warnings AND
275 errors
276 These flags cant be nested.
277
278 Example: >
279 let g:syntastic_stl_format = '[%E{Err: %fe #%e}%B{, }%W{Warn: %fw #%w}]'
280 <
281 If this format is used and the current buffer has 5 errors and 1 warning
282 starting on lines 20 and 10 respectively then this would appear on the
283 statusline: >
284 [Err: 20 #5, Warn: 10 #1]
285 <
286 If the buffer had 2 warnings, starting on line 5 then this would appear: >
287 [Warn: 5 #2]
288 <
289
290
291 ==============================================================================
292 5. Writing syntax checkers *syntastic-syntax-checkers*
293
294
295 A syntax checker plugin is really nothing more than a single function. You
296 should define them in ~/.vim/syntax_checkers/<filetype>.vim, but this is
297 purely for convenience; Syntastic doesn't actually care where these functions
298 are defined.
299
300 A syntax checker plugin must define a function of the form:
301 >
302 SyntaxCheckers_<filetype>_GetLocList()
303 <
304 The output of this function must be of the same format as that returned by
305 the |getloclist()| function. See |getloclist()| and |getqflist()| for
306 details.
307
308 To achieve this, the function should call |SyntasticMake()| or shell out to a
309 syntax checker, parse the output and munge it into the format.
310
311 There are several syntax checker plugins provided with this plugin. The ruby
312 one is a good example of |SyntasticMake()|, while the haml one is a good
313 example of how to create the data structure manually.
314
315
316 SyntasticMake({options}) *SyntasticMake()*
317 {options} must be a dictionary. It can contain "makeprg" and "errorformat"
318 as keys (both optional).
319
320 SyntasticMake will run |:lmake| with the given |'makeprg'| and
321 |'errorformat'| (using the current settings if none are supplied). It will
322 store the resulting error list and use it to provide all of the
323 |syntastic-functionality|. The previous makeprg and errorformat settings
324 will then be restored, as well as the location list for the window. From
325 the user's perspective, it will be as though |:lmake| was never run.
326
327 Note that the given "makeprg" and "errorformat" will be set using |:let-&|,
328 so you should not escape spaces.
329
330
331 ==============================================================================
332 6. About *syntastic-about*
333
334 The author of syntastic is a mighty wild stallion, hear him roar! >
335 _ _ _____ _____ ___ ___ ___ ____ _ _ _
336 | \ | | ____| ____|_ _|_ _|_ _/ ___| | | | |
337 | \| | _| | _| | | | | | | | _| |_| | |
338 | |\ | |___| |___ | | | | | | |_| | _ |_|
339 |_| \_|_____|_____|___|___|___\____|_| |_(_)
340
341 <
342 He likes to trot around in the back yard reading his emails and sipping a
343 scolding hot cup of Earl Grey. Email him at martin.grenfell at gmail dot com.
344 He can also be found trolling the #vim channel on the freenode IRC network as
345 scrooloose.
346
347 Bug reports, feedback, suggestions etc are welcomed.
348
349
350 The latest official releases will be on vim.org at some point.
351
352 The latest dev versions are on github
353 http://github.com/scrooloose/syntastic
354
355 ==============================================================================
356 7. Changelog *syntastic-changelog*
357
358 2.3.0
359 - Add syntastic_loc_list_height option
360 - Allow errors to have a "subtype" that is signed differently to standard
361 errors. Currently geared towards differentiating style errors from
362 syntax errors. Currently implemented for phpcs (technosophos).
363 - New checkers for:
364 - yaml
365 - haxe (davidB)
366 - ocaml (edwintorok)
367 - pylint (parantapa)
368 - rust (cjab)
369
370 - Updates to existing checkers:
371 - jslint
372 - jshint (gillesruppert)
373 - fortran (bmattern)
374 - sass
375 - html (darcyparker)
376 - coffee (darcyparker)
377 - docbk (darcyparker)
378 - xml
379 - xslt
380 - less (irrationalfab)
381 - php (AD7six, technosophos)
382 - cuda
383 - python (mitchellh, pneff)
384 - perl (Anthony Carapetis)
385 - c (naoina, zsprackett)
386 - puppet (frimik)
387
388 2.2.0
389 - only do syntax checks when files are saved (not when first opened) - add
390 g:syntastic_check_on_open option to get the old behavior back
391 - bug fix with echoing error messages; fixes incompatability with cmd-t (datanoise)
392 - dont allow warnings to mask errors when signing/echoing errors (ashikase)
393 - auto close location list when leaving buffer. (millermedeiros)
394 - update errors appropriately when :SyntasticToggleMode is called
395 - updates/fixes to existing checkers:
396 - javascript/jshint (millermedeiros)
397 - javascript/jslint
398 - c (kongo2002)
399 - Support for new filetypes:
400 - JSON (millermedeiros, tocer)
401 - rst (reStructuredText files) (JNRowe)
402 - gentoo-metadata (JNRowe)
403
404
405 2.1.0
406 - when the cursor is on a line containing an error, echo the
407 error msg (kevinw)
408 - various bug fixes and refactoring
409 - updates/fixes to existing checkers:
410 - html (millermedeiros)
411 - erlang
412 - coffeescript
413 - javascript
414 - sh
415 - php (add support for phpcs - technosophos)
416 - add an applescript checker (Zhai Cai)
417 - add support for hyphenated filetypes (JNRowe)
418
419 2.0.0
420 - Add support for highlighting the erroneous parts of lines (kstep)
421 - Add support for displaying errors via balloons (kstep)
422 - Add syntastic_mode_map option to give more control over when checking
423 should be done.
424 - Add :SyntasticCheck command to force a syntax check - useful in passive
425 mode (justone).
426 - Add the option to automatically close the location list, but not
427 automatically open it (milkypostman)
428 - Add syntastic_auto_jump option to automatically jump to the first
429 error (milkypostman)
430 - Only source syntax checkers as needed - instead of loading all of them
431 when vim starts
432
433 - Support for new filetypes:
434 - less (julienXX)
435 - docbook (tpope)
436 - matlab (jasongraham)
437 - go (dtjm)
438 - puppet (uggedal, roman, zsprackett)
439 - haskell (baldo, roman)
440 - tcl (et)
441 - vala (kstep)
442 - cuda (temporaer)
443 - css (oryband, sitedyno)
444 - fortran (Karl Yngve Lervåg)
445 - xml (kusnier)
446 - xslt (kusnier)
447 - erlang (kTT)
448 - zpt (claytron)
449
450 - updates to existing checkers:
451 - javascript (mogren, bryanforbes, cjab, ajduncan)
452 - sass/scss (tmm1, atourino, dlee, epeli)
453 - ruby (changa)
454 - perl (harleypig)
455 - haml (bmihelac)
456 - php (kstep, docteurklein)
457 - python (kstep, soli)
458 - lua (kstep)
459 - html (kstep)
460 - xhtml (kstep)
461 - c (kongo2002, brandonw)
462 - cpp (kongo2002)
463 - coffee (industrial)
464 - eruby (sergevm)
465
466 1.2.0
467 - New syntax checkers from github:kongo2002
468 - c (thanks also to github:jperras)
469 - cpp
470 - lua
471 - sh (thanks also to github:jmcantrell)
472 - add coffee syntax checked by github:lstoll
473 - add tex syntax checker
474 - make html checker play nicer with html5, thanks to github:enaeseth
475 - escape filenames properly when invoking syntax checkers, thanks to
476 github:jmcantrell
477 - adjust the ruby syntax checker to avoid some common annoying warnings,
478 thanks to github:robertwahler
479
480 1.1.0 [codenamed: tpimp]
481 - Dont load rubygems for ruby/eruby syntax checkers. Thanks tpope.
482 - Improve the javascript syntax checker to catch some warnings that were
483 getting missed. Thanks tpope.
484 - Dont automatically focus the error window. Thanks tpope.
485 - Add support for cucumber [tpope], haskell & perl [Anthony Carapetis],
486 and xhtml
487 - Add commands to enable/disable syntax checking at runtime. See :help
488 syntastic-commands.
489 - Add an option to specifiy syntax checkers that should be disabled by
490 default. See :help syntastic_disabled_filetypes.
491 - Dont use :signs if vim wasnt compiled with support for them.
492 )
493
494 ==============================================================================
495 8. Credits *syntastic-credits*
496
497 Thanks to the following people for testing, bug reports, patches etc. They own,
498 hard.
499
500 Mikael Fridh (frimik)
501 Patrice Neff (pneff )
502 Gilles Ruppert (gillesruppert)
503 Naoya INADA (naoina)
504 Mitchell Hashimoto (mitchellh)
505 irrationalfab
506 Andy Dawson (AD7six)
507 Parantapa Bhattacharya (parantapa)
508 edwintorok
509 Darcy Parker (darcyparker)
510 bmattern
511 David Bernard (davidB)
512 Aleksey V. Zapparov (ixti)
513 Benji Fisher (benjifisher)
514 Lance Fetters (ashikase)
515 datanoise
516 Giuseppe Rota (grota)
517 tocer
518 James Rowe (JNRowe)
519 Zhai Cai
520 Matt Butcher (technosophos)
521 Kevin Watters (kevinw)
522 Miller Medeiros (millermedeiros)
523 Pawel Salata (kTT)
524 Fjölnir Ásgeirsson (aptiva)
525 Clayton Parker (claytron)
526 S. Zachariah Sprackett (zsprackett)
527 Sylvain Soliman (soli)
528 Ricardo Catalinas Jiménez (jimenezrick)
529 kusnier
530 Klein Florian (docteurklein)
531 sitedyno
532 Matthew Batema (mlb-)
533 Nate Jones (justone)
534 sergevm
535 Karl Yngve Lervåg
536 Pavel Argentov (argent-smith)
537 Andy Duncan (ajduncan)
538 Antonio Touriño (atourino)
539 Chad Jablonski (cjab)
540 Roman Gonzalez (roman)
541 Tom Wieland (industrial)
542 Ory Band (oryband)
543 Esa-Matti Suuronen (epeli)
544 Brandon Waskiewicz (brandonw)
545 dlee
546 temporaer
547 Jason Graham (jasongraham)
548 Sam Nguyen (dtjm)
549 Claes Mogren (mogren)
550 Eivind Uggedal (uggedal)
551 kstep
552 Andreas Baldeau (baldo)
553 Eric Thomas (et)
554 Brian Donovan (eventualbuddha)
555 Bryan Forbes (bryanforbes)
556 Aman Gupta (tmm1)
557 Donald Ephraim Curtis (milkypostman)
558 Dominique Rose-Rosette (changa)
559 Harley Pig (harleypig)
560 bmihelac
561 Julien Blanchard (julienXX)
562 Gregor Uhlenheuer (kongo2002)
563 Lincoln Stoll
564 Tim Carey-Smith (halorgium)
565 Tim Pope (tpope)
566 Travis Jeffery
567 Anthony Carapetis
568
569
570 ==============================================================================
571 9. License *syntastic-license*
572
573 Syntastic is released under the wtfpl.
574 See http://sam.zoy.org/wtfpl/COPYING.