]> git.r.bdr.sh - rbdr/dotfiles/blame_incremental - vim/doc/syntastic.txt
Adds the custom status for tmux
[rbdr/dotfiles] / vim / doc / syntastic.txt
... / ...
CommitLineData
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==============================================================================
20CONTENTS *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==============================================================================
371. Intro *syntastic-intro*
38
39Syntastic is a syntax checking plugin that runs files through external syntax
40checkers. This can be done on demand, or automatically as files are saved and
41opened. If syntax errors are detected, the user is notified and is happy
42because they didn't have to compile their code or execute their script to find
43them.
44
45Syntastic 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
47basis where each one wraps up an external syntax checking program. The core
48script delegates off to these plugins and uses their output to provide the
49syntastic functionality. At the time of this writing, syntax checking plugins
50exist for c, coffee, cpp, css, cucumber, cuda, docbk, erlang, eruby, fortran,
51go, haml, haskell, html, javascript, less, lua, matlab, perl, php, puppet,
52python, ruby, sass/scss, sh, tcl, tex, vala, xhtml, xml, xslt, zpt
53
54Take a look in the syntax_checkers directory for the most up to date list.
55
56If your language is not supported then see |syntastic-syntax-checkers| for
57details on how to implement a syntax checking plugin, and be sure to send me a
58patch ;-)
59
60This plugin is currently only recommended for *nix users. It is functional on
61Windows, but since the syntax checking plugins shell out, the command window
62briefly appears whenever one is executed.
63
64
65==============================================================================
662. Functionality provided *syntastic-functionality*
67
68Syntax checking can be done automatically or on demand (see
69|'syntastic_mode_map'| for configuring this).
70
71When syntax checking is done, the features below can be used to notify the
72user of errors. See |syntastic-options| for how to configure and
73activate/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
86Note: This functionality is only available if a syntax checker plugin is
87present for the filetype of the buffer in question. See
88|syntastic-syntax-checkers| for details.
89
90------------------------------------------------------------------------------
912.1. The statusline flag *syntastic-statusline-flag*
92
93To use the statusline flag, this must appear in your |'statusline'| setting >
94 %{SyntasticStatuslineFlag()}
95<
96Something like this could be more useful: >
97 set statusline+=%#warningmsg#
98 set statusline+=%{SyntasticStatuslineFlag()}
99 set statusline+=%*
100<
101When syntax errors are detected a flag will be shown. The content of the flag
102is derived from the |syntastic_stl_format| option
103------------------------------------------------------------------------------
1042.2. Error signs *syntastic-error-signs*
105
106Syntastic uses the |:sign| commands to mark lines with errors and warnings in
107the sign column. To enable this feature, use the |'syntastic_enable_signs'|
108option.
109
110------------------------------------------------------------------------------
1112.3. The error window *:Errors* *syntastic-error-window*
112
113You can use the :Errors command to display the errors for the current buffer
114in the |location-list|.
115
116Note that when you use :Errors, the current location list is overwritten with
117Syntastic's own location list.
118
119
120==============================================================================
1213. Commands *syntastic-commands*
122
123:Errors *:SyntasticErrors*
124
125When errors have been detected, use this command to pop up the |location-list|
126and display the error messages.
127
128
129:SyntasticToggleMode *:SyntasticToggleMode*
130
131Toggles syntastic between active and passive mode. See |'syntastic_mode_map'|
132for more info.
133
134
135:SyntasticCheck *:SyntasticCheck*
136
137Manually cause a syntax check to be done. Useful in passive mode, or if the
138current filetype is set to passive. See |'syntastic_mode_map'| for more info.
139
140
141==============================================================================
1424. Options *syntastic-options*
143
144
145 *'syntastic_check_on_open'*
146Default: 0
147If enabled, syntastic will do syntax checks when buffers are first loaded as
148well as on saving >
149 let g:syntastic_check_on_open=1
150<
151
152 *'syntastic_echo_current_error'*
153Default: 1
154If enabled, syntastic will error message associated with the current line to
155the 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'*
160Default: 1
161Use this option to tell syntastic whether to use the |:sign| interface to mark
162syntax errors: >
163 let g:syntastic_enable_signs=1
164<
165
166 *'syntastic_enable_balloons'*
167Default: 1
168Use this option to tell syntastic whether to display error messages in balloons
169when the mouse is hovered over erroneous lines: >
170 let g:syntastic_enable_balloons = 1
171<
172Note that vim must be compiled with |+balloon_eval|.
173
174 *'syntastic_enable_highlighting'*
175Default: 1
176Use this option to tell syntastic whether to use syntax highlighting to mark
177errors (where possible). Highlighting can be turned off with the following >
178 let g:syntastic_enable_highlighting = 0
179<
180
181 *'syntastic_auto_jump'*
182Default: 0
183Enable this option if you want the cursor to jump to the first detected error
184when saving or opening a file: >
185 let g:syntastic_auto_jump=1
186<
187
188 *'syntastic_auto_loc_list'*
189Default: 2
190Use this option to tell syntastic to automatically open and/or close the
191|location-list| (see |syntastic-error-window|).
192
193When set to 0 the error window will not be opened or closed automatically. >
194 let g:syntastic_auto_loc_list=0
195<
196
197When set to 1 the error window will be automatically opened when errors are
198detected, and closed when none are detected. >
199 let g:syntastic_auto_loc_list=1
200<
201When set to 2 the error window will be automatically closed when no errors are
202detected, but not opened automatically. >
203 let g:syntastic_auto_loc_list=2
204<
205
206 *'syntastic_loc_list_height'*
207Default: 10
208Use this option to specify the height of the location lists that syntastic
209opens. >
210 let g:syntastic_loc_list_height=5
211<
212
213
214 *'syntastic_mode_map'*
215Default: { "mode": "active",
216 "active_filetypes": [],
217 "passive_filetypes": [] }
218
219Use this option to fine tune when automatic syntax checking is done (or not
220done).
221
222The 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
230active, syntastic does automatic checking whenever a buffer is saved or
231initially opened. When set to "passive" syntastic only checks when the user
232calls :SyntasticCheck.
233
234The exceptions to these rules are defined with "active_filetypes" and
235"passive_filetypes". In passive mode, automatic checks are still done
236for all filetypes in the "active_filetypes" array. In active mode,
237automatic checks are not done for any filetypes in the
238"passive_filetypes" array.
239
240At runtime, the |:SyntasticToggleMode| command can be used to switch between
241active and passive mode.
242
243If any of "mode", "active_filetypes", or "passive_filetypes" are not specified
244then they will default to their default value as above.
245
246 *'syntastic_quiet_warnings'*
247
248Use this option if you only care about syntax errors, not warnings. When set,
249this 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
261Default: [Syntax: line:%F (%t)]
262Use this option to control what the syntastic statusline text contains. Several
263magic 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
271Several 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
276These flags cant be nested.
277
278Example: >
279 let g:syntastic_stl_format = '[%E{Err: %fe #%e}%B{, }%W{Warn: %fw #%w}]'
280<
281If this format is used and the current buffer has 5 errors and 1 warning
282starting on lines 20 and 10 respectively then this would appear on the
283statusline: >
284 [Err: 20 #5, Warn: 10 #1]
285<
286If the buffer had 2 warnings, starting on line 5 then this would appear: >
287 [Warn: 5 #2]
288<
289
290
291==============================================================================
2925. Writing syntax checkers *syntastic-syntax-checkers*
293
294
295A syntax checker plugin is really nothing more than a single function. You
296should define them in ~/.vim/syntax_checkers/<filetype>.vim, but this is
297purely for convenience; Syntastic doesn't actually care where these functions
298are defined.
299
300A syntax checker plugin must define a function of the form:
301>
302 SyntaxCheckers_<filetype>_GetLocList()
303<
304The output of this function must be of the same format as that returned by
305the |getloclist()| function. See |getloclist()| and |getqflist()| for
306details.
307
308To achieve this, the function should call |SyntasticMake()| or shell out to a
309syntax checker, parse the output and munge it into the format.
310
311There are several syntax checker plugins provided with this plugin. The ruby
312one is a good example of |SyntasticMake()|, while the haml one is a good
313example of how to create the data structure manually.
314
315
316SyntasticMake({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==============================================================================
3326. About *syntastic-about*
333
334The author of syntastic is a mighty wild stallion, hear him roar! >
335 _ _ _____ _____ ___ ___ ___ ____ _ _ _
336 | \ | | ____| ____|_ _|_ _|_ _/ ___| | | | |
337 | \| | _| | _| | | | | | | | _| |_| | |
338 | |\ | |___| |___ | | | | | | |_| | _ |_|
339 |_| \_|_____|_____|___|___|___\____|_| |_(_)
340
341<
342He likes to trot around in the back yard reading his emails and sipping a
343scolding hot cup of Earl Grey. Email him at martin.grenfell at gmail dot com.
344He can also be found trolling the #vim channel on the freenode IRC network as
345scrooloose.
346
347Bug reports, feedback, suggestions etc are welcomed.
348
349
350The latest official releases will be on vim.org at some point.
351
352The latest dev versions are on github
353 http://github.com/scrooloose/syntastic
354
355==============================================================================
3567. Changelog *syntastic-changelog*
357
3582.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
3882.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
4052.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
4192.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
4661.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
4801.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==============================================================================
4958. Credits *syntastic-credits*
496
497Thanks to the following people for testing, bug reports, patches etc. They own,
498hard.
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==============================================================================
5719. License *syntastic-license*
572
573Syntastic is released under the wtfpl.
574See http://sam.zoy.org/wtfpl/COPYING.