syntastic/doc/syntastic.txt

*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|
        1.1.Quick start............................|syntastic-quickstart|
    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|
        2.4.Error highlighting.....................|syntastic-highlighting|
        2.5.Aggregating errors.....................|syntastic-aggregating-errors|
        2.6.Filtering errors.......................|syntastic-filtering-errors|
    3.Commands.....................................|syntastic-commands|
    4.Global Options...............................|syntastic-global-options|
    5.Checker Options..............................|syntastic-checker-options|
        5.1.Choosing which checkers to use.........|syntastic-filetype-checkers|
        5.2.Configuring specific checkers..........|syntastic-config-makeprg|
    6.Notes........................................|syntastic-notes|
        6.1.Handling of composite filetypes........|syntastic-composite|
        6.2.Interaction with python-mode...........|syntastic-pymode|
        6.3.Interaction with the fish shell........|syntastic-fish|
    7.About........................................|syntastic-about|
    8.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. 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 at the wiki for a list of supported filetypes and checkers:

    https://github.com/scrooloose/syntastic/wiki/Syntax-Checkers

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

------------------------------------------------------------------------------
1.1. Quick start                                        *syntastic-quickstart*

Syntastic comes preconfigured with a default list of enabled checkers per
filetype. This list is kept reasonably short to prevent slowing down Vim or
trying to use conflicting checkers.

You can see the list checkers available for the current filetype with the
|:SyntasticInfo| command.

If you want to override the configured list of checkers for a filetype then
see |syntastic-checker-options| for details. You can also change the arguments
passed to a specific checker as well.

Use |:SyntasticCheck| to manually check right now. Use |:SyntasticToggleMode|
to switch between active (checking on writting the buffer) and passive (manual)
checking.

==============================================================================
2. Functionality provided                            *syntastic-functionality*

Syntax checking can be done automatically or on demand (see
|'syntastic_mode_map'| and |:SyntasticToggleMode| 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 the |+balloon_eval| feature is compiled in) can be used to
      display error messages for erroneous lines when hovering the mouse over
      them
    * Error messages from multiple checkers can be aggregated in a single list

------------------------------------------------------------------------------
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.

------------------------------------------------------------------------------
2.4. Error highlighting                               *syntastic-highlighting*

Some checkers provide enough information for syntastic to be able to highlight
errors. By default the SpellBad syntax highlight group is used to color errors,
and the SpellCap group is used for warnings. If you wish to customize the
colors for highlighting you can use the following groups:
    SyntasticError - Links to 'SpellBad' by default
    SyntasticWarning - Links to 'SpellCap' by default

Example: >
    highlight SyntasticError guibg=#2f0000
<
------------------------------------------------------------------------------
2.5. Aggregating errors                         *syntastic-aggregating-errors*

By default (namely if |'syntastic_aggregate_errors'| is unset), syntastic runs
in turn the checkers corresponding to the filetype of the current file, and
stops as soon as a checker reports any errors. It then notifies you of the
errors using the notification mechanisms above. In this mode error lists are
always produced by a single checker, and, if you open the error window, the
name of the checker that generated the errors is shown on the statusline of the
error window.

If |'syntastic_aggregate_errors'| is set, syntastic runs all checkers that
apply, then aggregates errors found by all checkers in a single list, and
notifies you. In this mode each error message is labeled with the name of
the checker that generated it, but you can disable these labels by unsetting
'|syntastic_id_checkers|'.

------------------------------------------------------------------------------
2.6 Filtering errors                              *syntastic-filtering-errors*

You can selectively disable some of the errors found by checkers either
using |'syntastic_quiet_messages'|, or by specifying a list of patterns in
|'syntastic_ignore_files'|.
'syntastic_<filetype>_<checker>_quiet_messages'

==============================================================================
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.  By default the checkers in the
|'g:syntastic_<filetype>_checkers'| or |'b:syntastic_checkers'| lists are run,
cf. |syntastic-filetype-checkers|.  If |syntastic_aggregate_errors| is unset
(which is the default), checking stops the first time a checker reports any
errors; if |syntastic_aggregate_errors| is set, all checkers that apply are run
in turn, and all errors found are aggregated in a single list.

The command may be followed by a (space separated) list of checkers.  In this
case |'g:syntastic_<filetype>_checkers'| and |'b:syntastic_checkers'| are
ignored, and the checkers named by the command's arguments are run instead, in
the order specified.  The rules of |syntastic_aggregate_errors| still apply.

Example: >
    :SyntasticCheck flake8 pylint
<
:SyntasticInfo                                               *:SyntasticInfo*

The command takes an optional argument, and outputs information about the
checkers available for the filetype named by said argument, or for the current
filetype if no argument was provided.

:SyntasticReset                                              *:SyntasticReset*

Resets the list of errors and turns off all error notifiers.

:SyntasticSetLoclist                                    *:SyntasticSetLoclist*

If |'syntastic_always_populate_loc_list'| is not set, the |location-list| is
not filled in automatically with the list of errors detected by the checkers.
This is useful if you run syntastic along with other plugins that use location
lists.  The |:SyntasticSetLoclist| command allows you to stick the errors into
the location list explicitly.

==============================================================================
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, syntastic runs all checkers that apply to the current filetype,
then aggregates errors found by all checkers and displays them. When disabled,
syntastic 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_id_checkers'*
Default: 1
When results from multiple checkers are aggregated in a single error list
(that is either when |syntastic_aggregate_errors| is enabled, or when checking
a file with a composite filetype), it might not be immediately obvious which
checker has produced a given error message. This variable instructs syntastic
to label error messages with the names of the checkers that created them. >
    let g:syntastic_id_checkers = 0
<
                                              *'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 symbols 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 |location-list|: >
    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 never check.  It's 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|
to specify case insensitive patterns.  Example: >
    let g:syntastic_ignore_files = ['\m^/usr/include/', '\m\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' }
<
Composite filetypes can also be mapped to simple types, which disables the
default behaviour of running both checkers against the input file: >
    let g:syntastic_filetype_map = { 'handlebars.html': 'handlebars' }
<
                                                        *'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_messages'*
Default: {}

Use this option to filter out some of the messages produced by checkers.  The
option should be set to something like: >

    let g:syntastic_quiet_messages = { "level": "warnings",
                                     \ "type":  "style",
                                     \ "regex": '\m\[C03\d\d\]',
                                     \ "file":  ['\m^/usr/include/', '\m\c\.h$'] }
<

Each element turns off messages matching the patterns specified by the
corresponding value. Values are lists, but if a list consist of a single
element you can omit adding the brackets (e.g. you can write "style" instead of
["style"]).

    "level" - takes one of two values, "warnings" or "errors"
    "type"  - can be either "syntax" or "style"
    "regex" - is matched against the messages' text as a case insensitive
              |regular-expression|
    "file"  - is matched against the filename the error refers to, as a case
              sensitive |regular-expression|.

There are also checker-specific variants of this option, providing finer
control. They are named |'syntastic_<filetype>_<checker>_quiet_messages'|.

                                                      *'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 to flicker, or cause ghost characters. Leaving it to the default
should be safe.

                                                 *'syntastic_delayed_redraws'*
Default: 0
On older Vims, calling redraw when a popup menu is visible can cause Vim to
segfault. If your version of Vim is affected, the solution is of course to
upgrade Vim. If upgrading is not immediately feasible however, setting this
variable to 1 might help, by delaying redraws until they are safe. Beware that
there are functional and performance penalties involved, so only enable this
if you actually need it.

                                                           *'syntastic_debug'*
Default: 0
Set this to the sum of one or more of the following flags to enable
debugging:

     1 - trace checker calls
     2 - dump location lists
     4 - trace notifiers
     8 - trace autocommands
    16 - dump options

Example: >
    let g:syntastic_debug = 1
<
Syntastic will then add debugging messages to Vim's |message-history|. You can
examine these messages with |:mes|.

                                                      *'syntastic_debug_file'*
Default: unset
When set, debugging messages are written to the file named by its value, in
addition to being added to Vim's |message-history|: >
    let g:syntastic_debug_file = '~/syntastic.log'
<

==============================================================================
5. Checker Options                                 *syntastic-checker-options*

------------------------------------------------------------------------------
5.1 Choosing which checkers to use               *syntastic-filetype-checkers*

                                           *'g:syntastic_<filetype>_checkers'*
You can tell syntastic which checkers to run for a given filetype by setting a
variable 'g:syntastic_<filetype>_checkers' to a list of checkers, e.g. >
    let g:syntastic_python_checkers = ['php', 'phpcs', 'phpmd']
<

                                                      *'b:syntastic_checkers'*
There is also a per-buffer version of this setting, 'b:syntastic_checkers'.
When set, it takes precedence over |'g:syntastic_<filetype>_checkers'|.  You can
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
<

If neither |'g:syntastic_<filetype>_checkers'| nor |'b:syntastic_checkers'|
is set, a default list of checker is used. Beware however that this list
deliberately kept minimal, for performance reasons.

Take a look at the wiki to find out what checkers and filetypes are supported
by syntastic:

    https://github.com/scrooloose/syntastic/wiki/Syntax-Checkers

Use |:SyntasticInfo| to see which checkers are available for a given filetype.

------------------------------------------------------------------------------
5.2 Configuring specific checkers                   *syntastic-config-makeprg*

Most checkers use the 'makeprgBuild()' function and provide many options by
default - in fact you can customise every part of the command that gets called.

Checkers that use 'makeprgBuild()' construct a 'makeprg' like this: >
    let makeprg = self.makeprgBuild({
                \ 'exe': self.getExec(),
                \ 'args': '-a -b -c',
                \ 'post_args': '--more --args',
                \ 'tail': '> /tmp/output' })
<

The result is a 'makeprg' of the form: >
    <exe> <args> <filename> <post_args> <tail>
<

All arguments above are optional, and can be overridden by setting global
variables 'g:syntastic_<filetype>_<checker-name>_<option-name>' - even
parameters not specified in the call to makeprgBuild().

If 'exe' is the same as the checker 'exec' attribute, it may be omitted.

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 'makeprgBuild()' 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 in the wiki:

    https://github.com/scrooloose/syntastic/wiki/Syntax-Checkers

                             *'syntastic_<filetype>_<checker>_quiet_messages'*
In the same vein, 'g:syntastic_<filetype>_<checker-name>_quiet_messages' can
be used to restrict message filters to messages produced by specific checkers.
Example: >
    let g:syntastic_python_pylama_quiet_messages = { "type":  "style",
                                                   \ "regex": '\m\[C03\d\d\]' }
<
See |syntastic_quiet_messages| for the syntax.

==============================================================================
6. Notes                                                     *syntastic-notes*

------------------------------------------------------------------------------
6.1. Handling of composite filetypes                     *syntastic-composite*

Some Vim plugins use composite filetypes, such as 'django.python' or
'handlebars.html'. Normally, syntastic deals with this situation by splitting
the filetype in its simple components, and calling all checkers that apply.
If this behaviour is not desirable, you can disable it by mapping the
composite filetypes to a simple ones using |syntastic_filetype_map|, e.g.: >
    let g:syntastic_filetype_map = { 'handlebars.html': 'handlebars' }
<

------------------------------------------------------------------------------
6.2 Interaction with python-mode                            *syntastic-pymode*

Syntastic can be used along with the 'python-mode' Vim plugin (see
https://github.com/klen/python-mode). However, they both run syntax checks by
default when you save buffers to disk, and this is probably not what you want.
To avoid both plugins opening error windows, you can either set passive mode
for python in syntastic (see |syntastic_mode_map|), or disable lint checks in
python-mode, by setting |pymode_lint_write| to 0. E.g.: >
    let g:pymode_lint_write = 0
<

------------------------------------------------------------------------------
6.3 Interaction with the fish shell                           *syntastic-fish*

At the time of this writing the 'fish' shell (see http://fishshell.com/)
doesn't support the standard UNIX syntax for file redirections, and thus it
can't be used together with syntastic. You don't need to change your login
shell to address this problem, but you do have to point Vim's 'shell' to a more
traditional shell, such as 'zsh', 'bash', 'ksh', or even the original Bourne
'sh': >
    set shell = 'bash'
<

==============================================================================
7. About                                                     *syntastic-about*

The core maintainers of syntastic are:
    Martin Grenfell (github: scrooloose)
    Gregor Uhlenheuer (github: kongo2002)
    LCD 047 (github: lcd047)

Find the latest version of syntastic at:

    http://github.com/scrooloose/syntastic

==============================================================================
8. License                                                 *syntastic-license*

Syntastic is released under the wtfpl.
See http://sam.zoy.org/wtfpl/COPYING.

 vim:tw=78:sw=4:ft=help:norl: