git.r.bdr.sh - rbdr/dotfiles/blob - 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.