*checksyntax.txt*   checksyntax -- Check files for syntax errors (r, javascript, php, ruby, tex ...)
                    Author: Tom Link, micathom at gmail com

The checksyntax plugin runs an external syntax checker for the current buffer 
whenever the buffer is saved (by calling the |:CheckSyntax| command). Syntax 
errors are managed as location or quickfix lists. If any syntax error occurs, 
the |location-list| is opened (users can redefine |CheckSyntaxFail()| to change 
this behaviour). You can use any |location-list| related command to navigate 
the list of syntax errors.

Most syntax checks can be run asynchronously (from Vim 8 onwards or, for 
Vim 7, if the AsyncCommand plugin is installed).


Invocation~

Manual invocation:
By default, |:CheckSyntax| is mapped to <F5> (if not mapped already), and 
automatically executed when saving the buffer. If multiple syntax checkers are 
defined for the given filetype, this will by default invoke the preferred (see 
|g:checksyntax#preferred|) or first good (i.e. installed) syntax checker for a 
given filetype.

:CheckSyntax! (with the optional <bang>) or <C-F5> will run all supported 
syntax checkers for a given filetype if multiple syntax checkers are defined 
for a given filetype and if the software is installed on your computer.

Automatic invocation:
In order to automatically run a syntax check when saving a file, please set 
|g:checksyntax#auto_filetypes| or |g:checksyntax#auto_enable_rx| to an 
appropriate value. If |g:checksyntax#auto_enable_rx| is set to '.', which 
matches all filetypes, automatic syntax checks are enabled for all supported 
filetypes. Automatic checks are equivalent to running |:CheckSyntax| with no 
<bang>.


Supported filetypes~

The syntax checks are performed by external syntax checker. This software has 
to be installed on your computer. Pre-defined syntax checkers are:

  bash         ... shellcheck, bash -n
  c, cpp       ... splint
  haskell      ... hlint, ghc-mod-check
  html         ... tidy
  java         ... jlint, checkstyle, pmd
  javascript   ... jshint, esprima, gjslint, jslint, jsl, pmd
  lua          ... luac (run luac -p)
  perl         ... perl (run perl -Wc)
  php          ... php (run php -l)
  python       ... pyflakes or pylint
  r            ... lintr
  ruby         ... ruby (run ruby -c)
  tex, latex   ... chktex (run chktex -q -v0)
  typescript   ... tsc
  viki         ... deplate
  vim          ... vint
  xhtml        ... tidy
  xml, docbk   ... xmllint, pmd

Checkers with support for many filetypes:

  coala        ... c, cpp, csharp, cmake, coffeescript, css, dart, fortran, go, 
                   haskell, html, java, javascript, jsp, tex, lua, markdown, 
                   perl, php, python, r, rst, ruby, scala, scss, sh, sql, 
                   swift, typescript, verilog, vhdl, vim, xml, yaml and maybe 
                   others

Syntax checker definitions are kept in:
autoload/checksyntax/defs/{&filetype}.vim

Run this command to find out, which filetypes are supported: >

  :echo globpath(&rtp, 'autoload/checksyntax/defs/*.vim')


Trouble shooting~

It's possible that a newer version of a linter changes its command-line 
arguments or the output format in a way that breaks the checksyntax plugin. 
Since I personally use only a small subset of the provided checkers, it's 
likely that I won't notice the problem. If the checksyntax plugin doesn't seem 
to work, please proceed as follows:

1. Check if the errorformat is correctly defined. Look at either:
    - `autoload/checksyntax/defs/LINTER.vim` or
    - `compiler/checksyntax/LINTER.vim`.
   If the linter is defined as a compiler, you can try to invoke the compiler 
   manually: >
     compiler checksyntax/LINTER
     lmake

2. Use `:let g:checksyntax#debug = 2` to get a high level view of what is going 
   on when you invoke |:CheckSyntax|.

3. Install the tlib plugin (vimscript #1863 or 
   https://github.com/tomtom/tlib_vim) and try: >
     :Tlibtraceset --file=checksyntax.log +checksyntax
<   Invoke |:CheckSyntax| and send me the resulting log file per e-mail. You 
   can use `:CheckSyntax FILETYPE LINTER` to invoke a specific syntax checker.


-----------------------------------------------------------------------
Install~

Edit the vba file and type: >

    :so %

See :help vimball for details. If you have difficulties or use vim 7.0, 
please make sure, you have the current version of vimball (vimscript 
#1502) installed or update your runtime.

Also available via git: http://github.com/tomtom/checksyntax_vim/


Optional enhancements~

If the quickfixsigns plugin (vimscript #2584) is installed, lines containing 
syntax errors will be marked with signs.

The tinykeymap plugin (vimscript #4199) can be used to quickly move from one 
issue to the next by using it's quickfix or location-list maps (see 
|g:tinykeymap#map#qfl#map| and |g:tinykeymap#map#loc#map|).

For vim8+: Checks will be run asynchronously by default.

For vim7: If AsyncCommand (vimscript #3431) is installed, syntax checks can 
be peformed asynchronously -- see also |g:checksyntax#run_alternatives|, 
|g:checksyntax#run_all_alternatives| and |g:checksyntax#async_runner|. This 
requires a version of vim with |clientserver| support and |v:servername| to be 
set (for vim see also |--servername|).


========================================================================
Contents~

        :CheckSyntax .............................................. |:CheckSyntax|
        g:checksyntax_key_single .................................. |g:checksyntax_key_single|
        g:checksyntax_key_all ..................................... |g:checksyntax_key_all|
        g:checksyntax_auto ........................................ |g:checksyntax_auto|
        g:checksyntax#auto_filetypes .............................. |g:checksyntax#auto_filetypes|
        g:checksyntax#auto_enable_rx .............................. |g:checksyntax#auto_enable_rx|
        g:checksyntax#auto_disable_rx ............................. |g:checksyntax#auto_disable_rx|
        g:checksyntax#enable_syntax ............................... |g:checksyntax#enable_syntax|
        g:checksyntax#enable_syntax_ .............................. |g:checksyntax#enable_syntax_|
        g:checksyntax#show_cmd .................................... |g:checksyntax#show_cmd|
        g:checksyntax#lines_expr .................................. |g:checksyntax#lines_expr|
        g:checksyntax#background .................................. |g:checksyntax#background|
        g:checksyntax#preferred ................................... |g:checksyntax#preferred|
        g:checksyntax#async_runner ................................ |g:checksyntax#async_runner|
        :CheckSyntaxStatus ........................................ |:CheckSyntaxStatus|
        g:checksyntax#run_alternatives ............................ |g:checksyntax#run_alternatives|
        g:checksyntax#run_all_alternatives ........................ |g:checksyntax#run_all_alternatives|
        g:checksyntax#cygwin_path_rx .............................. |g:checksyntax#cygwin_path_rx|
        g:checksyntax#cygwin_expr ................................. |g:checksyntax#cygwin_expr|
        g:checksyntax#check_cygpath ............................... |g:checksyntax#check_cygpath|
        CheckSyntaxSucceed ........................................ |CheckSyntaxSucceed()|
        CheckSyntaxFail ........................................... |CheckSyntaxFail()|
        checksyntax#AddChecker .................................... |checksyntax#AddChecker()|
        checksyntax#Check ......................................... |checksyntax#Check()|
        checksyntax#MaybeUseCygpath ............................... |checksyntax#MaybeUseCygpath()|
        g:checksyntax#defs#haxe#haxe .............................. |g:checksyntax#defs#haxe#haxe|
        g:checksyntax#defs#haxe#use_checkstyle .................... |g:checksyntax#defs#haxe#use_checkstyle|
        g:checksyntax#defs#haxe#checkstyle_args ................... |g:checksyntax#defs#haxe#checkstyle_args|
        g:checksyntax#defs#javascript#closure ..................... |g:checksyntax#defs#javascript#closure|
        g:checksyntax#pmd#cmd ..................................... |g:checksyntax#pmd#cmd|
        g:checksyntax_fsc_lint_stop_after ......................... |g:checksyntax_fsc_lint_stop_after|
        g:checksyntax_php_lint_args ............................... |g:checksyntax_php_lint_args|
        g:checksyntax_phpcs_cmd ................................... |g:checksyntax_phpcs_cmd|
        g:checksyntax_phpcs_args .................................. |g:checksyntax_phpcs_args|
        g:checksyntax_scalastyle_cmd .............................. |g:checksyntax_scalastyle_cmd|


------------------------------------------------------------------------
                                                    *plugin/checksyntax.vim*
                                                    *:CheckSyntax*
CheckSyntax[!] [NAME] [PREFERRED_RX]
    Check the current buffer's syntax (type defaults to &filetype).
    Or use NAME instead of &filetype.

    With the bang !, run all alternatives (see 
    |g:checksyntax#run_alternatives|).

                                                    *g:checksyntax_key_single*
g:checksyntax_key_single       (default: '<F5>')
    Map for running the preferred syntax checkers on the current 
    buffer.

                                                    *g:checksyntax_key_all*
g:checksyntax_key_all          (default: '<C-F5>')
    Map for running all suitable syntax checkers on the current 
    buffer.

                                                    *g:checksyntax_auto*
g:checksyntax_auto             (default: 1)
    If 1, enable automatic syntax checks after saving a file.
    If 2, enable automatic syntax checks when saving and loading a 
    file.
    NOTE: This variable must be customized in vimrc before loading 
    this plugin.

    See also |g:checksyntax|, |g:checksyntax#auto_enable_rx| and 
    |g:checksyntax#auto_disable_rx|.


------------------------------------------------------------------------
                                                    *autoload/checksyntax.vim*
                                                    *g:checksyntax#auto_filetypes*
g:checksyntax#auto_filetypes   (default: [])
    Enable automatic checking for these filetypes.

                                                    *g:checksyntax#auto_enable_rx*
g:checksyntax#auto_enable_rx   (default: empty(g:checksyntax#auto_filetypes) ? '' : printf('\(%s\)', join(g:checksyntax#auto_filetypes, '\|')))
    Enable automatic checking for filetypes matching this rx.
    Set to "." to enable for all filetypes.
    This requires |g:checksyntax_auto| to be > 0.
    This variable overrules any filetype-specific settings in 
    |g:checksyntax|.

                                                    *g:checksyntax#auto_disable_rx*
g:checksyntax#auto_disable_rx  (default: '')
    Disable automatic checking for filetypes matching this rx.
    Set to "." to disable for all filetypes.
    This requires |g:checksyntax_auto| to be > 0.
    This variable overrules any filetype-specific settings in 
    |g:checksyntax|.

                                                    *g:checksyntax#enable_syntax*
g:checksyntax#enable_syntax    (default: ['vim'])
    A list of filetypes for which frequent beginner errors will be 
    highlighted by matching lines against |regexp|s defined in the 
    file `autoload/checksyntax/syntax/{FILETYPE}.vim`.

    See :echo globpath(&rtp, 'autoload/checksyntax/syntax/*.vim') for 
    supported filetypes/checks.

    The variable can also be buffer-local. In this case all named 
    types will be loaded.

                                                      *b:checksyntax_enable_syntax*
    E.g. in order to enable highlighting trailing whitespace, use: >

      let b:checksyntax_enable_syntax = ['trailing_whitespace']

<   If you want to enable this for all file of filetype X, add this 
    line to in `after/syntax/X.vim` or use >

      let g:checksyntax#enable_syntax_X = ['trailing_whitespace']
<

                                                    *g:checksyntax#enable_syntax_*
g:checksyntax#enable_syntax_   (default: ['inconsistent_whitespace', 'trailing_whitespace'])
    A list of syntax checks (see |g:checksyntax#enable_syntax|) that 
    should be enabled by default.

                                                    *g:checksyntax#show_cmd*
g:checksyntax#show_cmd         (default: {'qfl': 'copen '. g:checksyntax#list_height, 'loc': 'lopen '. g:checksyntax#list_height})
    A dictionary of VIM commands that are used to display the qf/loc 
    lists.
    If empty, do nothing.

                                                    *g:checksyntax#lines_expr*
g:checksyntax#lines_expr       (default: '')
    A vim expression that determines the number of lines of the 
    qfl/loc window. If empty, don't set the size.
    A useful value is: >
      let g:checksyntax#lines_expr = 'min([&previewheight, &lines / 2, len(getloclist(0))])'
<

                                                    *g:checksyntax#background*
g:checksyntax#background       (default: 1)
    If true, the current window will keep the focus when displaying 
    the issues list.

                                                    *g:checksyntax#preferred*
g:checksyntax#preferred        (default: {'xml': '.'})
    A dictionary of 'filetype' => |regexp|.
    If only one alternative should be run (see 
    |g:checksyntax#run_alternatives|), check only those syntax 
    checkers whose names matches |regexp|.

                                                    *g:checksyntax#async_runner*
g:checksyntax#async_runner     (default: exists(':AsyncMake') ? 'asynccommand' : '')
    Supported values:
      asynccommand ... Use the AsyncCommand plugin

                                                    *:CheckSyntaxStatus*
:CheckSyntaxStatus
    Show status information (pending async tasks).

                                                    *g:checksyntax#run_alternatives*
g:checksyntax#run_alternatives (default: 'first' . (!empty(g:checksyntax#async_runner) ? ' async' : ''))
    How to handle alternatives. Possible values:

        first ... Use the first valid entry
        all   ... Run all valid alternatives one after another

    Alternatively, the following flag can be added in order to change 
    how the alternatives are run:

        async ... Run alternatives asynchronously (see also 
                  |g:checksyntax#async_runner|)

                                                    *g:checksyntax#run_all_alternatives*
g:checksyntax#run_all_alternatives (default: 'all' . (!empty(g:checksyntax#async_runner) ? ' async' : ''))
    How to run "all" alternatives -- e.g., when calling the 
    |:CheckSyntax| command with a bang.

                                                    *g:checksyntax#cygwin_path_rx*
g:checksyntax#cygwin_path_rx   (default: '/cygwin/')
    If a full windows filename (with slashes instead of backslashes) 
    matches this |regexp|, it is assumed to be a cygwin executable.

                                                    *g:checksyntax#cygwin_expr*
g:checksyntax#cygwin_expr      (default: '"bash -c ''". escape(%s, "''\\") ."''"')
    For cygwin binaries, convert command calls using this vim 
    expression.

                                                    *g:checksyntax#check_cygpath*
g:checksyntax#check_cygpath    (default: g:checksyntax#windows && s:Executable('cygpath'))
    If true, check whether we have to convert a path via cyppath -- 
    see |checksyntax#MaybeUseCygpath|

                                                    *CheckSyntaxSucceed()*
CheckSyntaxSucceed(type, manually)
    This function is called when no syntax errors were found.

                                                    *CheckSyntaxFail()*
CheckSyntaxFail(type, manually, bg)
    This function is called when a syntax error was found.

                                                    *checksyntax#AddChecker()*
checksyntax#AddChecker(filetype, ...)
    Define a syntax checker definition for a given filetype.
    If filetype ends with "?", add only if no checker with the given name 
    is defined.

    A checker definition is a dictionary with the following fields:

    Mandatory (either one of the following):

      cmd ........ A shell command used as 'makeprg' to check the file.
      cmdexpr .... A vim expression that returns the cmd
      checkergen . A vim function, which takes its definition as argument 
                   and returns a dictionary of {NAME => CHECKER}
      compiler ... A vim compiler that is used to check the file.
      exec ....... A vim command used to check the file (deprecated; use 
                   cmdexpr & process_list instead)

    Optional:

      efm  ....... An 'errorformat' string.
      prepare .... An ex command that is run before doing anything.
      ignore_nr .. A list of error numbers that should be ignored.
      ignore_rx .. A regexp of messages that should be ignored.
      listtype ... Either loc (default) or qfl
      include .... Include another definition
      process_list .. Process a list of issues
      if ......... An expression to test *once* whether a syntax checker 
                   should be used.
      if_executable .. Test whether an application is executable.
      buffers .... Keep results only for either "current", "listed", or 
                   "all" buffers
      compiler_args .. Internal use
      cmd_args ... Internal use

    Optional top-level fields:

      auto ....... Run automatically when saving a file (see also 
                   |g:checksyntax#auto_enable_rx| and 
                   |g:checksyntax#auto_disable_rx|)
      modified ... The name of a pseudo-filetype that should be used if 
                   the buffer was modified
      run_alternatives ... A string that defines how to run 
                   alternatives (overrides 
                   |g:checksyntax#run_alternatives|).

    Top-level fields affect how syntax checkers for a filetype are run.

                                                    *checksyntax#Check()*
checksyntax#Check(manually, ?bang='', ?filetype=&ft, ?preferred_rx='')
    Perform a syntax check.
    If bang is not empty, run all alternatives (see 
    |g:checksyntax#run_alternatives|).
    If filetype is empty, the current buffer's 'filetype' will be used.
    If background is true, display the list of issues in the background, 
    i.e. the active window will keep the focus.

                                                    *checksyntax#MaybeUseCygpath()*
checksyntax#MaybeUseCygpath(cmd)
    If cmd seems to be a cygwin executable, use cygpath to convert 
    filenames. This assumes that cygwin's which command returns full 
    filenames for non-cygwin executables.


------------------------------------------------------------------------
                                                    *autoload/checksyntax/defs/haxe.vim*
                                                    *g:checksyntax#defs#haxe#haxe*
g:checksyntax#defs#haxe#haxe   (default: executable('haxe') ? 'haxe' : '')
    Filename of the haxe executable.

                                                    *g:checksyntax#defs#haxe#use_checkstyle*
g:checksyntax#defs#haxe#use_checkstyle (default: 0)
    If true, use checkstyle (https://github.com/adireddy/haxe-checkstyle).

                                                    *g:checksyntax#defs#haxe#checkstyle_args*
g:checksyntax#defs#haxe#checkstyle_args (default: '')
    Additional arguments to checkstyle.
    Can also be buffer-local as b:checksyntax_defs_haxe_checkstyle_args.


------------------------------------------------------------------------
                                                    *autoload/checksyntax/defs/javascript.vim*
                                                    *g:checksyntax#defs#javascript#closure*
g:checksyntax#defs#javascript#closure (default: '')
    If non-empty, enable some checks via closure compiler.


------------------------------------------------------------------------
                                                    *autoload/checksyntax/defs/r.vim*

Syntax checkers for R:
- lintr


------------------------------------------------------------------------
                                                    *autoload/checksyntax/defs/rmd.vim*

Syntax checkers for Rmd:
- See r


------------------------------------------------------------------------
                                                    *autoload/checksyntax/pmd.vim*
                                                    *g:checksyntax#pmd#cmd*
g:checksyntax#pmd#cmd          (default: '')
    The command to run pmd.


------------------------------------------------------------------------
                                                    *autoload/checksyntax/syntax/vim.vim*

                                                    *checksyntax_enable_syntax-vim*
Simple syntax checks for the vim 'filetype'~

Setting |g:checksyntax_enable_syntax| enables the following checks:

- `else if` instead of |:elseif|
- Propably wrong arguments for |bufnr()| or |winnr()|
- Don't ignore/simplify the return value of |exists()| for cmdnames
- Calls like exists('fnname()')
- Don't write exists('foo'). If it's a variable, make the scope explicit 
  (like `g:foo`). Otherwise it was an error anyway.
- Variables with scope (|g:|, |l:|, |a:var| etc.) in function 
  argument position


------------------------------------------------------------------------
                                                    *compiler/checksyntax/fsc_lint.vim*
                                                    *g:checksyntax_fsc_lint_stop_after*
g:checksyntax_fsc_lint_stop_after (default: 'cleanup')
    See `scalac -Xshow-phases` for possible values.


------------------------------------------------------------------------
                                                    *compiler/checksyntax/php_lint.vim*
                                                    *g:checksyntax_php_lint_args*
g:checksyntax_php_lint_args    (default: '-l -n -d display_errors=1 -d error_log= -d error_reporting=E_ALL')
    Displaying errors for php files is surprisingly fragile since it 
    depends on the php version and the php.ini file. If you get 
    duplicate errors or no errors at all, change the command-line 
    arguments defined with this variable. Please consider the 
    information kindly collected by Björn Oelke:

      Somehow the values in the php.ini and those passed via '--define' 
      seem to be independent, so either value in checksyntax' def file 
      seems to be a problem with one of the possible values in the 
      php.ini:

      | cmd | php.ini | Errors |
      +-----+---------+--------+
      | 1   | On      | 2      |
      | 0   | On      | 1      |
      | 1   | Off     | 1      |
      | 0   | Off     | 0      |

      There's an additional flag in the manpage called '--no-php-ini', 
      that could solve the problem.

    You can run `php -i | grep display_errors` to find out if 
    display_errors is On because of the php.ini. By default, the 
    setting in php.ini is ignored ("-n" command-line flag).


------------------------------------------------------------------------
                                                    *compiler/checksyntax/phpcs.vim*
                                                    *g:checksyntax_phpcs_cmd*
g:checksyntax_phpcs_cmd        (default: 'phpcs')
    The phpcs command.

                                                    *g:checksyntax_phpcs_args*
g:checksyntax_phpcs_args       (default: '')
    For passing arguments into phpcs. Can be used to set options such 
    as '--standard=PSR2 --ignore=foo.php'


------------------------------------------------------------------------
                                                    *compiler/checksyntax/scalastyle.vim*
                                                    *g:checksyntax_scalastyle_cmd*
g:checksyntax_scalastyle_cmd   (default: '')
    The command to invoke scalastyle -- see http://www.scalastyle.org 
    and especially http://www.scalastyle.org/command-line.html



vim:tw=78:fo=w2croql:isk=!-~,^*,^|,^":ts=8:ft=help:norl:
