Regenerated docs for 0.10.0

Author: mpeterv

doc/_sources/cli.txt

@@ -5,7 +5,7 @@ Command line interface
 
 * Given a file, ``luacheck`` will check it.
 * Given ``-``, ``luacheck`` will check stdin.
-* Given a directory, ``luacheck`` will check all files with ``.lua`` extension within it. This feature requires `luafilesystem <http://keplerproject.github.io/luafilesystem/>`_ (installed automatically if LuaRocks was used to install Luacheck).
+* Given a directory, ``luacheck`` will check all files with ``.lua`` extension within it. This feature requires `LuaFileSystem <http://keplerproject.github.io/luafilesystem/>`_ (installed automatically if LuaRocks was used to install Luacheck).
 * Given a rockspec (a file with ``.rockspec`` extension), ``luacheck`` will check all files with ``.lua`` extension mentioned in the rockspec in ``build.install.lua``, ``build.install.bin`` and ``build.modules`` tables.
 
 The output of ``luacheck`` consists of separate reports for each checked file and ends with a summary::
@@ -21,6 +21,9 @@ The output of ``luacheck`` consists of separate reports for each checked file an
 
    Checking src/good_code.lua                        OK
    Checking src/python_code.lua                      Syntax error
+
+       spec/samples/python_code.lua:1:6: expected '=' near '__future__'
+
    Checking src/unused_code.lua                      Failure
 
        src/unused_code.lua:3:18: unused argument baz
@@ -55,8 +58,6 @@ Option                                Meaning
 ``-u`` | ``--no-unused``              Filter out warnings related to unused variables and values.
 ``-r`` | ``--no-redefined``           Filter out warnings related to redefined variables.
 ``-a`` | ``--no-unused-args``         Filter out warnings related to unused arguments and loop variables.
-``-v`` | ``--no-unused-values``       Filter out warnings related to unused values.
-``--no-unset``                        Filter out warnings related to unset variables.
 ``-s`` | ``--no-unused-secondaries``  Filter out warnings related to unused variables set together with used ones.
 
                                       See :ref:`secondaryvaluesandvariables`
@@ -91,21 +92,24 @@ Option                                Meaning
 ``--enable | -o <patt> [<patt>] ...`` Do not filter out warnings matching patterns.
 ``--only | -o <patt> [<patt>] ...``   Filter out warnings not matching patterns.
 ``--no-inline``                       Disable inline options.
-``-l <limit>`` | ``--limit <limit>``  Exit with 0 if there are ``<limit>`` or less warnings (default: ``0``).
 ``--config <config>``                 Path to custom configuration file (default: ``.luacheckrc``).
 ``--no-config``                       Do not look up custom configuration file.
+``--cache [<cache>]``                 Path to cache file. (default: ``.luacheckcache``). See :ref:`cache`
+``--no-cache``                        Do not use cache.
+``-j`` | ``--jobs``                   Check ``<jobs>`` files in parallel. Requires `LuaLanes <http://cmr.github.io/lanes/>`_.
 ``--formatter <formatter>``           Use custom formatter. ``<formatter>`` must be a module name or one of:
 
                                       * ``TAP`` - Test Anything Protocol formatter;
                                       * ``JUnit`` - JUnit XML formatter;
                                       * ``plain`` - simple warning-per-line formatter;
                                       * ``default`` - standard formatter.
-``--codes``                           Show warning codes.
 ``-q`` | ``--quiet``                  Suppress report output for files without warnings.
 
                                       * ``-qq`` - Suppress output of warnings.
                                       * ``-qqq`` - Only output summary.
+``--codes``                           Show warning codes.
 ``--no-color``                        Do not colorize output.
+``-v`` | ``--version``                Show version of luacheck and its dependencies and exit.
 ``-h`` | ``--help``                   Show help and exit.
 ===================================== ============================================================================
 
@@ -124,7 +128,16 @@ Pattern Matching warnings
 4.2/.*_ Shadowing declarations of arguments with ``_`` suffix or redefining them.
 ======= =========================================================================
 
+Unless already anchored, patterns matching variable names are anchored at both sides and patterns matching warning codes are anchored at their beginnings. This allows to filter warnings by category (e.g. ``--only 1`` focuses ``luacheck`` on global-related warnings).
+
 Formatters
 ----------
 
 CLI option ``--formatter`` allows selecting a custom formatter for ``luacheck`` output. A custom formatter is a Lua module returning a function with three arguments: report as returned by ``luacheck`` module (see :ref:`report`), array of file names and table of options. Options contain values assigned to ``quiet``, ``color``, ``limit``, ``codes`` and ``formatter`` options in CLI or config. Formatter function must return a string.
+
+.. _cache:
+
+Caching
+-------
+
+If LuaFileSystem is available, Luacheck can cache results of checking files. On subsequent checks, only files which have changed since the last check will be rechecked, improving run time significantly. Changing options (e.g. defining additional globals) does not invalidate cache. Caching can be enabled by using ``--cache <cache>`` option or ``cache`` config option. Using ``--cache`` without an argument or setting ``cache`` config option to ``true`` sets ``.luacheckcache`` as the cache file. Note that ``--cache`` must be used every time ``luacheck`` is run, not on the first run only.

doc/_sources/config.txt

@@ -15,13 +15,13 @@ Option                 Type                                    Default value
 ====================== ======================================= ==================
 ``color``              Boolean                                 ``true``
 ``codes``              Boolean                                 ``false``
-``limit``              Number                                  ``0``
+``formatter``          String                                  ``"default"``
+``cache``              Boolean or string                       ``false``
+``jobs``               Positive integer                        ``1``
 ``global``             Boolean                                 ``true``
 ``unused``             Boolean                                 ``true``
 ``redefined``          Boolean                                 ``true``
 ``unused_args``        Boolean                                 ``true``
-``unused_values``      Boolean                                 ``true``
-``unset``              Boolean                                 ``true``
 ``unused_secondaries`` Boolean                                 ``true``
 ``std``                String or array of strings              ``"_G"``
 ``globals``            Array of strings                        ``{}``
@@ -36,6 +36,7 @@ Option                 Type                                    Default value
 ``ignore``             Array of patterns (see :ref:`patterns`) ``{}``
 ``enable``             Array of patterns                       ``{}``
 ``only``               Array of patterns                       (Do not filter)
+``inline``             Boolean                                 ``true``
 ====================== ======================================= ==================
 
 An example of a config which makes ``luacheck`` ensure that only globals from the portable intersection of Lua 5.1, Lua 5.2, Lua 5.3 and LuaJIT 2.0 are used, as well as disables detection of unused arguments:

doc/_sources/index.txt

@@ -11,4 +11,4 @@ Contents:
    inline
    module
 
-This is documentation for `Luacheck <https://github.com/mpeterv/luacheck/>`_ 0.9.0, a static analyzer and a linter for `Lua <http://www.lua.org/>`_.
+This is documentation for `Luacheck <https://github.com/mpeterv/luacheck/>`_ 0.10.0, a static analyzer and a linter for `Lua <http://www.lua.org/>`_.

doc/_sources/inline.txt

@@ -46,3 +46,5 @@ For fine-grained control over inline option visibility use ``luacheck: push`` an
    foo() -- No warning.
    -- luacheck: pop
    foo() -- Warning is emitted.
+
+Inline options can be completely disabled using ``--no-inline`` CLI option or ``inline`` config option.

doc/_sources/module.txt

@@ -1,22 +1,25 @@
 Luacheck module
 ===============
 
-``luacheck`` module is a single function. Use ``local luacheck = require "luacheck"`` to import it.
+Use ``local luacheck = require "luacheck"`` to import ``luacheck`` module. It contains the following functions:
 
-The first argument of the function should be an array. Each element should be either a file name (string) or an open file handle, in which case ``luacheck`` will read it till EOF and close it.
+* ``luacheck.get_report(source)``: Given source string, returns analysis data (an array) or nil and syntax error table (table with fields ``line``, ``column``, ``offset``, ``msg``).
+* ``luacheck.process_reports(reports, options)``: Processes array of analysis reports and applies options. ``reports[i]`` uses ``options``, ``options[i]``, ``options[i][1]``, ``options[i][2]``, ... as options, overriding each other in that order. Options table is a table with fields similar to config options; see :ref:`options`. Analysis reports with field ``error`` are ignored. ``process_reports`` returns final report, see :ref:`report`.
+* ``luacheck.check_strings(sources, options)``: Checks array of sources using options, returns final report. Tables in ``sources`` array are ignored.
+* ``luacheck.check_files(files, options)``: Checks array of files using options, returns final report. Open file handles can passed instead of filenames, in which case they will be read till EOF and closed.
 
-The second argument, if present, should be a table of options. See :ref:`options`.
+``luacheck._VERSION`` contains Luacheck version as a string in ``MAJOR.MINOR.PATCH`` format.
 
-When checking ``n``-th file, ``luacheck`` will try to combine ``options[n]`` and entries from its array part with general options, similarly to how per file config tables overwrite main config table.
+Using ``luacheck`` as a function is equivalent to calling ``luacheck.check_files``.
 
 .. _report:
 
 Report format
 -------------
 
-The ``luacheck`` function returns a report. A report is an array of file reports plus fields ``warnings`` and ``errors`` containing total number of warnings and errors, correspondingly.
+A final report is an array of file reports plus fields ``warnings`` and ``errors`` containing total number of warnings and errors, correspondingly.
 
-A file report is an array of warnings. If an error occured while checking a file, its report will only have ``error`` field containing ``"I/O"`` or ``"syntax"``.
+A file report is an array of warnings. If an error occured while checking a file, its report will have ``error`` field containing ``"I/O"`` or ``"syntax"``. In case of syntax error, ``line`` (number), ``colunmn`` (number), ``offset`` (number) and ``msg`` (string) fields are also present.
 
 A warning is a table with field ``code`` indicating the type of warning (see :doc:`warnings`), and fields ``line`` and ``column`` pointing to the source of the warning. Absence of ``code`` field indicates that the warning is related to a broken inline configuration comment; then, ``invalid`` field marks comments with invalid syntax, and ``unpaired`` field marks unpaired push/pop comments.
 

doc/_sources/warnings.txt

@@ -29,6 +29,9 @@ Code Description
 421  Shadowing a local variable.
 422  Shadowing an argument.
 423  Shadowing a loop variable.
+431  Shadowing an upvalue.
+432  Shadowing an upvalue argument.
+433  Shadowing an upvalue loop variable.
 511  Unreachable code.
 512  Loop can be executed at most once.
 521  Unused label.
@@ -62,8 +65,8 @@ Modules
 
 Files can be marked as modules using ``-m``/``--module`` CLI option or ``module`` config option to simulate semantics of the deprecated `module <http://www.lua.org/manual/5.1/manual.html#pdf-module>`_ function. Globals implicitly defined inside a module are considired part of its interface, are not visible outside and are not reported as unused. Assignments to other globals are not allowed, even to defined ones.
 
-Unused variables and  values
-----------------------------
+Unused variables and values
+---------------------------
 
 Luacheck generates warnings for all unused local variables except one named ``_``. It also detects variables which are set but never accessed or accessed but never set.
 
@@ -109,7 +112,7 @@ Warnings related to unused secondary values and variables can be removed using `
 Shadowing declarations
 ----------------------
 
-Luacheck detects declarations of local variables shadowing previous declarations in the same closure, unless the variable is named ``_``. If the previous declaration is in the same scope as the new one, it is called redefining.
+Luacheck detects declarations of local variables shadowing previous declarations, unless the variable is named ``_``. If the previous declaration is in the same scope as the new one, it is called redefining.
 
 Note that it is **not** necessary to define a new local variable when overwriting an argument:
 
@@ -127,6 +130,8 @@ Note that it is **not** necessary to define a new local variable when overwritin
 Control flow and data flow issues
 ---------------------------------
 
+The following control flow and data flow issues are detected:
+
 * Unreachable code and loops that can be executed at most once (e.g. due to an unconditional break);
 * Unused labels;
 * Unbalanced assignments;