*checksyntax.txt*   checksyntax -- Check syntax when saving a file (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.

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

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

By default, |:CheckSyntax| is mapped to <F5> (if not mapped already), 
and automatically executed when saving the buffer. :CheckSyntax! or <C-F5> will 
run all syntax checkers for a given filetype if multiple alternatives are 
defined and installed on your computer.

The |:CheckSyntax| command takes one optional argument: the mode (default: 
&filetype).

As the plugin doesn't provide syntax checks by its own. This is done by 
an external syntax checker that has to be installed on your computer.

Pre-defined syntax checkers (the respective syntax checker has to 
be installed):

  c, cpp       ... Requires splint
  html         ... Requires tidy
  java         ... Requires
                    jlint (http://jlint.sourceforge.net),
                    checkstyle (http://checkstyle.sourceforge.net),
                    pmd (http://pmd.sourceforge.net)
  javascript   ... Syntax check; requires jshint, esprima, 
                   gjslint, jslint, jsl, pmd
  lua          ... Requires luac (run luac -p)
  php          ... Syntax check; requires php (run php -l)
  python       ... Requires pyflakes or pylint
  r            ... Requires codetools::checkUsage, lint::lint, or 
                   svTools::lint
  ruby         ... Requires ruby (run ruby -c)
  tex, latex   ... Requires chktex (run chktex -q -v0)
  viki         ... Requires deplate
  xhtml        ... Requires tidy
  xml, docbk   ... Requires xmllint, pmd

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')

This plugin was originally based on Klaus Horsten's php_console 
(vimscript #779) and it is the successor of php_check_syntax.vim 
(vimscript #1272).


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

Optional enhancements:
    quickfixsigns (vimscript #2584) ... Use signs
    AsyncCommand (vimscript #3431) ... Run commands asynchronously


========================================================================
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_enable_rx ......... |g:checksyntax#auto_enable_rx|
        g:checksyntax#auto_disable_rx ........ |g:checksyntax#auto_disable_rx|
        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#windows ................ |g:checksyntax#windows|
        g:checksyntax#null ................... |g:checksyntax#null|
        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()|
        g:checksyntax#prototypes ............. |g:checksyntax#prototypes|
        checksyntax#AddChecker ............... |checksyntax#AddChecker()|
        checksyntax#GetChecker ............... |checksyntax#GetChecker()|
        checksyntax#Check .................... |checksyntax#Check()|
        checksyntax#AddJob ................... |checksyntax#AddJob()|
        checksyntax#RemoveJob ................ |checksyntax#RemoveJob()|
        checksyntax#Status ................... |checksyntax#Status()|
        checksyntax#GetList .................. |checksyntax#GetList()|
        checksyntax#NullOutput ............... |checksyntax#NullOutput()|
        checksyntax#MaybeUseCygpath .......... |checksyntax#MaybeUseCygpath()|
        g:checksyntax#pmd#cmd ................ |g:checksyntax#pmd#cmd|
        g:checksyntax#pmd#args ............... |g:checksyntax#pmd#args|
        checksyntax#pmd#Cmd .................. |checksyntax#pmd#Cmd()|


========================================================================
plugin/checksyntax.vim~

                                                    *:CheckSyntax*
CheckSyntax[!] [NAME]
    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_enable_rx*
g:checksyntax#auto_enable_rx   (default: '')
    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#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: has('clientserver') && !empty(v:servername) && 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#windows*
g:checksyntax#windows          (default: &shell !~ 'sh' && (has('win16') || has('win32') || has('win64')))

                                                    *g:checksyntax#null*
g:checksyntax#null             (default: g:checksyntax#windows ? 'nul' : (filereadable('/dev/null') ? '/dev/null' : ''))

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

                                                    *g:checksyntax#prototypes*
g:checksyntax#prototypes       (default: {'loc': {}, 'qfl': {}})
    Contains prototype definitions for syntax checkers that use the 
    |location-list| ("loc") or the |quixfix|-list.

                                                    *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
      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.
      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#GetChecker()*
checksyntax#GetChecker(filetype, ...)

                                                    *checksyntax#Check()*
checksyntax#Check(manually, ?bang='', ?filetype=&ft, ?background=1)
    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#AddJob()*
checksyntax#AddJob(make_def)

                                                    *checksyntax#RemoveJob()*
checksyntax#RemoveJob(job_id)

                                                    *checksyntax#Status()*
checksyntax#Status()

                                                    *checksyntax#GetList()*
checksyntax#GetList(name, make_def, type)

                                                    *checksyntax#NullOutput()*
checksyntax#NullOutput(flag)

                                                    *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/pmd.vim~

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

                                                    *g:checksyntax#pmd#args*
g:checksyntax#pmd#args         (default: '-f text')

                                                    *checksyntax#pmd#Cmd()*
checksyntax#pmd#Cmd(language, args, rulesets)



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