diff --git a/README.md b/README.md index 50e3f485..9c5d9614 100644 --- a/README.md +++ b/README.md @@ -43,7 +43,7 @@ For Windows there is single-file 64-bit binary distribution, bundling Lua 5.3.4, ## Basic usage -After Luacheck is installed, run `luacheck` program from the command line. Pass a list of files, [rockspecs](https://github.com/keplerproject/luarocks/wiki/Rockspec-format) or directories (requires LuaFileSystem) to be checked: +After Luacheck is installed, run `luacheck` program from the command line. Pass a list of files, [rockspecs](https://github.com/luarocks/luarocks/wiki/Rockspec-format) or directories (requires LuaFileSystem) to be checked: ``` luacheck src extra_file.lua another_file.lua diff --git a/docsrc/cli.rst b/docsrc/cli.rst index 8401b01f..55496c6f 100644 --- a/docsrc/cli.rst +++ b/docsrc/cli.rst @@ -1,7 +1,7 @@ Command line interface ====================== -``luacheck`` program accepts files, directories and `rockspecs `_ as arguments. They can be filtered using ``--include-files`` and ``--exclude-files`` options, see below. +``luacheck`` program accepts files, directories and `rockspecs `_ as arguments. They can be filtered using ``--include-files`` and ``--exclude-files`` options, see below. * Given a file, ``luacheck`` will check it. * Given ``-``, ``luacheck`` will check stdin. @@ -103,14 +103,16 @@ Option Meaning ``-m | --module`` Limit visibility of implicitly defined globals to their files. See :ref:`modules` -``--max-line-length `` Set maximum allowed line length (default: 120). ``--no-max-line-length`` Do not limit line length. -``--max-code-line-length `` Set maximum allowed length for lines ending with code (default: 120). ``--no-max-code-line-length`` Do not limit code line length. -``--max-string-line-length `` Set maximum allowed length for lines within a string (default: 120). ``--no-max-string-line-length`` Do not limit string line length. -``--max-comment-line-length `` Set maximum allowed length for comment lines (default: 120). ``--no-max-comment-line-length`` Do not limit comment line length. +``--max-cyclomatic-complexity `` Set maximum cyclomatic complexity for functions. +``--no-max-cyclomatic-complexity`` Do not limit function cyclomatic complexity (default). ``--ignore | -i [] ...`` Filter out warnings matching patterns. ``--enable | -e [] ...`` Do not filter out warnings matching patterns. ``--only | -o [] ...`` Filter out warnings not matching patterns. @@ -137,6 +139,7 @@ Option Meaning * ``TAP`` - Test Anything Protocol formatter; * ``JUnit`` - JUnit XML formatter; + * ``visual_studio`` - MSBuild/Visual Studio aware formatter; * ``plain`` - simple warning-per-line formatter; * ``default`` - standard formatter. ``-q | --quiet`` Suppress report output for files without warnings. @@ -179,7 +182,7 @@ CLI options ``--globals``, ``--new-globals``, ``--read-globals``, ``--new-read-g Sets of standard globals ------------------------ -CLI option ``--stds`` allows combining built-in sets described above using ``+``. For example, ``--std max`` is equivalent to ``--std=lua51c+lua52c+lua53c+luajit``. Leading plus sign adds new sets to default one instead of replacing it. For instance, ``--std +busted`` is suitable for checking test files that use `Busted `_ testing framework. Custom sets of globals can be defined by mutating global variable ``stds`` in config. See :ref:`custom_stds` +CLI option ``--stds`` allows combining built-in sets described above using ``+``. For example, ``--std max`` is equivalent to ``--std=lua51c+lua52c+lua53c+luajit``. Leading plus sign adds new sets to current one instead of replacing it. For instance, ``--std +busted`` is suitable for checking test files that use `Busted `_ testing framework. Custom sets of globals can be defined by mutating global variable ``stds`` in config. See :ref:`custom_stds` Formatters ---------- diff --git a/docsrc/conf.py b/docsrc/conf.py index 6454647a..4c187899 100644 --- a/docsrc/conf.py +++ b/docsrc/conf.py @@ -48,9 +48,9 @@ # built documents. # # The short X.Y version. -version = '0.21.2' +version = '0.22.0' # The full version, including alpha/beta/rc tags. -release = '0.21.2' +release = '0.22.0' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/docsrc/config.rst b/docsrc/config.rst index 5d9527ab..dd9dd422 100644 --- a/docsrc/config.rst +++ b/docsrc/config.rst @@ -1,11 +1,13 @@ Configuration file ================== -``luacheck`` tries to load configuration from ``.luacheckrc`` file in the current directory. If not found, it will look for it in the parent directory and so on, going up until it reaches file system root. Path to config can be set using ``--config`` option, in which case it will be used during recursive loading. Config loading can be disabled using ``--no-config`` flag. +``luacheck`` tries to load configuration from ``.luacheckrc`` file in the current directory. If not found, it will look for it in the parent directory and so on, going up until it reaches file system root. Path to config can be set using ``--config`` option, in which case it will be used during recursive loading. Paths within config are interpreted relatively to the directory from which it was loaded. + +Config loading can be disabled using ``--no-config`` flag. If neither of ``--config``, ``--no-config``, and ``--no-default-config`` options are used, ``luacheck`` will attempt to load configuration from value of ``--default-config`` option, or ``%LOCALAPPDATA%\Luacheck\.luacheckrc`` on Windows, ``~/Library/Application Support/Luacheck/.luacheckrc`` on OS X/macOS, and ``$XDG_CONFIG_HOME/luacheck/.luacheckrc`` -or ``~/.config/luacheck/.luacheckrc`` on other systems by default. +or ``~/.config/luacheck/.luacheckrc`` on other systems by default. Paths within default config are interpreted relatively to the current directory. Config is simply a Lua script executed by ``luacheck``. It may set various options by assigning to globals or by returning a table with option names as keys. @@ -19,8 +21,10 @@ Config options ============================= ======================================== =================== Option Type Default value ============================= ======================================== =================== +``quiet`` Integer in range 0..3 ``0`` ``color`` Boolean ``true`` ``codes`` Boolean ``false`` +``ranges`` Boolean ``false`` ``formatter`` String or function ``"default"`` ``cache`` Boolean or string ``false`` ``jobs`` Positive integer ``1`` diff --git a/docsrc/index.rst b/docsrc/index.rst index 9af394db..b85c39e2 100644 --- a/docsrc/index.rst +++ b/docsrc/index.rst @@ -11,4 +11,4 @@ Contents: inline module -This is documentation for 0.21.2 version of `Luacheck `_, a linter for `Lua `_. +This is documentation for 0.22.0 version of `Luacheck `_, a linter for `Lua `_. diff --git a/docsrc/module.rst b/docsrc/module.rst index 71415c88..3697df1e 100644 --- a/docsrc/module.rst +++ b/docsrc/module.rst @@ -24,9 +24,9 @@ A file report is an array of issues (warnings or errors). If a fatal error occur An issue is a table with field ``code`` indicating its type (see :doc:`warnings`), and fields ``line``, ``column`` and ``end_column`` pointing to the source of the warning. ``name`` field may contain name of related variable. Issues of some types can also have additional fields: -============= ============================================================================================================ +============= ============================================================================================================== Codes Additional fields -============= ============================================================================================================ +============= ============================================================================================================== 011 ``msg`` field contains syntax error message. 111 ``module`` field indicates that assignment is to a non-module global variable. 122, 142, 143 ``indirect`` field indicates that the global field was accessed using a local alias. @@ -35,10 +35,12 @@ Codes Additional fields 211 ``recursive`` field indicates that unused function is recursive. 211 ``mutually_recursive`` field is set for unused mutually recursive functions. 314 ``field`` field contains string representation of ununsed field or index. -4.. ``prev_line`` and ``prev_column`` fields contain location of the overwritten definition. +011 ``prev_line``, ``prev_column``, and ``prev_end_column`` fields may point to an extra relevant location, + such as the opening unpaired bracket. +4.. ``prev_line``, ``prev_column``, and ``prev_end_column`` fields contain location of the overwritten definition. 521 ``label`` field contains label name. 631 ``line_ending`` field contains ``"comment"`` or ``"string"`` if line ending is within a comment or a string. 631 ``max_length`` field contains maximum allowed line length. -============= ============================================================================================================ +============= ============================================================================================================== Other fields may be present for internal reasons. diff --git a/docsrc/warnings.rst b/docsrc/warnings.rst index b8f5d791..71cef9b4 100644 --- a/docsrc/warnings.rst +++ b/docsrc/warnings.rst @@ -50,6 +50,7 @@ Code Description 541 An empty ``do`` ``end`` block. 542 An empty ``if`` branch. 551 An empty statement. +561 Cyclomatic complexity of a function is too high. 611 A line consists of nothing but whitespace. 612 A line contains trailing whitespace. 613 Trailing whitespace in a string. @@ -200,6 +201,12 @@ Empty statements In Lua 5.2+ semicolons are considered statements and can appear even when not following normal statements. Such semicolons produce Luacheck warnings as they are completely useless. +Cyclomatic complexity +^^^^^^^^^^^^^^^^^^^^^ + +If a limit is set using ``--max-cyclomatic-complexity`` CLI option or corresponding config or inline options, Luacheck warns about functions +with too high cyclomatic complexity. + Formatting issues (6xx) -----------------------