Provided by: lua-check_0.25.0-1_all 
NAME
luacheck - luacheck Documentation
Contents:
LIST OF WARNINGS
Warnings produced by Luacheck are categorized using three-digit warning codes. Warning
codes can be displayed in CLI output using --codes CLI option or codes config option.
Errors also have codes starting with zero; unlike warnings, they can not be ignored.
┌─────┬──────────────────────────────────┐
│Code │ Description │
├─────┼──────────────────────────────────┤
│011 │ A syntax error. │
├─────┼──────────────────────────────────┤
│021 │ An invalid inline option. │
├─────┼──────────────────────────────────┤
│022 │ An unpaired inline push │
│ │ directive. │
├─────┼──────────────────────────────────┤
│023 │ An unpaired inline pop │
│ │ directive. │
├─────┼──────────────────────────────────┤
│111 │ Setting an undefined global │
│ │ variable. │
├─────┼──────────────────────────────────┤
│112 │ Mutating an undefined global │
│ │ variable. │
├─────┼──────────────────────────────────┤
│113 │ Accessing an undefined global │
│ │ variable. │
├─────┼──────────────────────────────────┤
│121 │ Setting a read-only global │
│ │ variable. │
├─────┼──────────────────────────────────┤
│122 │ Setting a read-only field of a │
│ │ global variable. │
├─────┼──────────────────────────────────┤
│131 │ Unused implicitly defined global │
│ │ variable. │
├─────┼──────────────────────────────────┤
│142 │ Setting an undefined field of a │
│ │ global variable. │
├─────┼──────────────────────────────────┤
│143 │ Accessing an undefined field of │
│ │ a global variable. │
├─────┼──────────────────────────────────┤
│211 │ Unused local variable. │
├─────┼──────────────────────────────────┤
│212 │ Unused argument. │
├─────┼──────────────────────────────────┤
│213 │ Unused loop variable. │
├─────┼──────────────────────────────────┤
│221 │ Local variable is accessed but │
│ │ never set. │
├─────┼──────────────────────────────────┤
│231 │ Local variable is set but never │
│ │ accessed. │
└─────┴──────────────────────────────────┘
│232 │ An argument is set but never │
│ │ accessed. │
├─────┼──────────────────────────────────┤
│233 │ Loop variable is set but never │
│ │ accessed. │
├─────┼──────────────────────────────────┤
│241 │ Local variable is mutated but │
│ │ never accessed. │
├─────┼──────────────────────────────────┤
│311 │ Value assigned to a local │
│ │ variable is unused. │
├─────┼──────────────────────────────────┤
│312 │ Value of an argument is unused. │
├─────┼──────────────────────────────────┤
│313 │ Value of a loop variable is │
│ │ unused. │
├─────┼──────────────────────────────────┤
│314 │ Value of a field in a table │
│ │ literal is unused. │
├─────┼──────────────────────────────────┤
│321 │ Accessing uninitialized local │
│ │ variable. │
├─────┼──────────────────────────────────┤
│331 │ Value assigned to a local │
│ │ variable is mutated but never │
│ │ accessed. │
├─────┼──────────────────────────────────┤
│341 │ Mutating uninitialized local │
│ │ variable. │
├─────┼──────────────────────────────────┤
│411 │ Redefining a local variable. │
├─────┼──────────────────────────────────┤
│412 │ Redefining an argument. │
├─────┼──────────────────────────────────┤
│413 │ Redefining a loop variable. │
├─────┼──────────────────────────────────┤
│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. │
├─────┼──────────────────────────────────┤
│531 │ Left-hand side of an assignment │
│ │ is too short. │
├─────┼──────────────────────────────────┤
│532 │ Left-hand side of an assignment │
│ │ is too long. │
├─────┼──────────────────────────────────┤
│541 │ An empty do end block. │
└─────┴──────────────────────────────────┘
│542 │ An empty if branch. │
├─────┼──────────────────────────────────┤
│551 │ An empty statement. │
├─────┼──────────────────────────────────┤
│561 │ Cyclomatic complexity of a │
│ │ function is too high. │
├─────┼──────────────────────────────────┤
│571 │ A numeric for loop goes from │
│ │ #(expr) down to 1 or less │
│ │ without negative step. │
├─────┼──────────────────────────────────┤
│611 │ A line consists of nothing but │
│ │ whitespace. │
├─────┼──────────────────────────────────┤
│612 │ A line contains trailing │
│ │ whitespace. │
├─────┼──────────────────────────────────┤
│613 │ Trailing whitespace in a string. │
├─────┼──────────────────────────────────┤
│614 │ Trailing whitespace in a │
│ │ comment. │
├─────┼──────────────────────────────────┤
│621 │ Inconsistent indentation (SPACE │
│ │ followed by TAB). │
├─────┼──────────────────────────────────┤
│631 │ Line is too long. │
└─────┴──────────────────────────────────┘
Global variables (1xx)
For each file, Luacheck builds list of defined globals and fields which can be used there.
By default only globals from Lua standard library are defined; custom globals can be added
using --globals CLI option or globals config option, and version of standard library can
be selected using --std CLI option or std config option. When an undefined global or field
is set, mutated or accessed, Luacheck produces a warning.
Read-only globals
By default, most standard globals and fields are marked as read-only, so that setting them
produces a warning. Custom read-only globals and fields can be added using --read-globals
CLI option or read_globals config option, or using a custom set of globals. See
custom_stds
Globals and fields that are not read-only by default:
• _G
• _ENV (treated as a global by Luacheck)
• package.path
• package.cpath
• package.loaded
• package.preload
• package.loaders
• package.searchers
Implicitly defined globals
Luacheck can be configured to consider globals assigned under some conditions to be
defined implicitly. When -d/--allow_defined CLI option or allow_defined config option is
used, all assignments to globals define them; when -t/--allow_defined_top CLI option or
allow_defined_top config option is used, assignments to globals in the top level function
scope (also known as main chunk) define them. A warning is produced when an implicitly
defined global is not accessed anywhere.
Modules
Files can be marked as modules using -m/--module CLI option or module config option to
simulate semantics of the deprecated 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 (2xx) and values (3xx)
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.
Unused values and uninitialized variables
For each value assigned to a local variable, Luacheck computes set of expressions where it
could be used. Warnings are produced for unused values (when a value can't be used
anywhere) and for accessing uninitialized variables (when no values can reach an
expression). E.g. in the following snippet value assigned to foo on line 1 is unused, and
variable bar is uninitialized on line 9:
local foo = expr1()
local bar
if condition() then
foo = expr2()
bar = expr3()
else
foo = expr4()
print(bar)
end
return foo, bar
Secondary values and variables
Unused value assigned to a local variable is secondary if its origin is the last item on
the RHS of assignment, and another value from that item is used. Secondary values
typically appear when result of a function call is put into locals, and only some of them
are later used. For example, here value assigned to b is secondary, value assigned to c is
used, and value assigned to a is simply unused:
local a, b, c = f(), g()
return c
A variable is secondary if all values assigned to it are secondary. In the snippet above,
b is a secondary variable.
Warnings related to unused secondary values and variables can be removed using
-s/--no-unused-secondaries CLI option or unused_secondaries config option.
Shadowing declarations (4xx)
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:
local function f(x)
local x = x or "default" -- bad
end
local function f(x)
x = x or "default" -- good
end
Control flow and data flow issues (5xx)
Unreachable code
Luacheck detects unreachable code. It also detects it if end of a loop block is
unreachable, which means that the loop can be executed at most once:
for i = 1, 100 do
-- Break statement is outside the `if` block,
-- so that the loop always stops after the first iteration.
if cond(i) then f() end break
end
Unused labels
Labels that are not used by any goto statements are reported as unused.
Unbalanced assignments
If an assignment has left side and right side with different lengths, the assignment is
unbalanced and Luacheck warns about it.
An exception is initializing several local variables in a single statement while leaving
some uninitialized:
local a, b, c = nil -- Effectively sets `a`, `b`, and `c` to nil, no warning.
Empty blocks
Luacheck warns about empty do end blocks and empty if branches (then else, then elseif,
and then end).
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.
Reversed numeric for loops
Iterating a table in reverse using a numeric for loop going from #t to 1 requires a
negative loop step. Luacheck warns about loops going from #(some expression) to 1 or a
smaller constant when the loop step is not negative:
-- Warning for this loop:
-- numeric for loop goes from #(expr) down to 1 but loop step is not negative
for i = #t, 1 do
print(t[i])
end
-- This loop is okay.
for i = #t, 1, -1 do
print(t[i])
end
Formatting issues (6xx)
Whitespace issues
Luacheck warns about trailing whitespace and inconsistent indentation (SPACE followed by
TAB).
Some examples of trailing whitespace Luacheck finds:
-- Whitespace example.
print("Hello")
print("World")
Here:
• Any tabs or spaces after either ) would be considered trailing.
• Any tabs or spaces after the . in the comment would be considered trailing
• Any tabs or spaces on the empty line between the two print statements would also be
considered a form of trailing whitespace.
Trailing whitespace in any of these forms is useless, can be a nuisance to developers
navigating around a file, and is forbidden in many formatting styles.
Line length limits
Luacheck warns about lines that are longer then some limit. Default limit is 120
characters. It's possible to change this limit using --max-line-length CLI option or
disable the check completely with --no-max-line-length; there are similar config and
inline options.
Additionally, separate limits can be set for three different type of lines:
• "String" lines have their line ending inside a string, typically a long string using
[[...]] syntax.
• "Comment" lines have their line ending inside a long comment (--[[...]]), or end with a
short comment using normal --... syntax.
• "Code" lines are all other lines.
These types of lines are limited using CLI options named --[no-]max-string-line-length,
--[no-]max-comment-line-length, and --[no-]max-code-line-length, with similar config and
inline options.
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.
• Given a file, luacheck will check it.
• Given -, luacheck will check stdin.
• Given a directory, luacheck will check all files within it, selecting only files with
.lua extension unless --include-files option is used. This feature requires
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:
$ luacheck src
Checking src/bad_code.lua 5 warnings
src/bad_code.lua:3:16: unused variable helper
src/bad_code.lua:3:23: unused variable length argument
src/bad_code.lua:7:10: setting non-standard global variable embrace
src/bad_code.lua:8:10: variable opt was previously defined as an argument on line 7
src/bad_code.lua:9:11: accessing undefined variable hepler
Checking src/good_code.lua OK
Checking src/python_code.lua 1 error
src/python_code.lua:1:6: expected '=' near '__future__'
Checking src/unused_code.lua 9 warnings
src/unused_code.lua:3:18: unused argument baz
src/unused_code.lua:4:8: unused loop variable i
src/unused_code.lua:5:13: unused variable q
src/unused_code.lua:7:11: unused loop variable a
src/unused_code.lua:7:14: unused loop variable b
src/unused_code.lua:7:17: unused loop variable c
src/unused_code.lua:13:7: value assigned to variable x is unused
src/unused_code.lua:14:1: value assigned to variable x is unused
src/unused_code.lua:22:1: value assigned to variable z is unused
Total: 14 warnings / 1 error in 4 files
luacheck chooses exit code as follows:
• Exit code is 0 if no warnings or errors occurred.
• Exit code is 1 if some warnings occurred but there were no syntax errors or invalid
inline options.
• Exit code is 2 if there were some syntax errors or invalid inline options.
• Exit code is 3 if some files couldn't be checked, typically due to an incorrect file
name.
• Exit code is 4 if there was a critical error (invalid CLI arguments, config, or cache
file).
Command line options
Short options that do not take an argument can be combined into one, so that -qqu is
equivalent to -q -q -u. For long options, both --option value or --option=value can be
used.
Options taking several arguments can be used several times; --ignore foo --ignore bar is
equivalent to --ignore foo bar.
Note that options that may take several arguments, such as --globals, should not be used
immediately before positional arguments; given --globals foo bar file.lua, luacheck will
consider all foo, bar and file.lua global and then panic as there are no file names left.
┌─────────────────────────────────┬────────────────────────────────────────────────┐
│Option │ Meaning │
├─────────────────────────────────┼────────────────────────────────────────────────┤
│-g | --no-global │ Filter out warnings related to │
│ │ global variables. │
├─────────────────────────────────┼────────────────────────────────────────────────┤
│-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. │
├─────────────────────────────────┼────────────────────────────────────────────────┤
│-s | --no-unused-secondaries │ Filter out warnings related to │
│ │ unused variables set together │
│ │ with used ones. │
│ │ │
│ │ See secondaryvaluesandvariables │
├─────────────────────────────────┼────────────────────────────────────────────────┤
│--no-self │ Filter out warnings related to │
│ │ implicit self argument. │
└─────────────────────────────────┴────────────────────────────────────────────────┘
--std <std> Set standard globals, default is
max. <std> can be one of:
• max - union of globals
of Lua 5.1, Lua 5.2,
Lua 5.3 and LuaJIT 2.x;
• min - intersection of
globals of Lua 5.1, Lua
5.2, Lua 5.3 and LuaJIT
2.x;
• lua51 - globals of Lua
5.1 without deprecated
ones;
• lua51c - globals of Lua
5.1;
• lua52 - globals of Lua
5.2;
• lua52c - globals of Lua
5.2 compiled with
LUA_COMPAT_ALL;
• lua53 - globals of Lua
5.3;
• lua53c - globals of Lua
5.3 compiled with
LUA_COMPAT_5_2;
• lua54 - globals of Lua
5.4;
• lua54c - globals of Lua
5.4 compiled with
LUA_COMPAT_5_3;
• luajit - globals of
LuaJIT 2.x;
• ngx_lua - globals of
Openresty
lua-nginx-module
0.10.10, including
standard LuaJIT 2.x
globals;
• love - globals added by
LÖVE;
• busted - globals added
by Busted 2.0, by
default added for files
ending with _spec.lua
within spec, test, and
tests subdirectories;
• rockspec - globals
allowed in rockspecs,
by default added for
files ending with
.rockspec;
• luacheckrc - globals
allowed in Luacheck
configs, by default
added for files ending
with .luacheckrc;
• none - no standard
globals.
See Sets of standard
globals
├─────────────────────────────────┼────────────────────────────────────────────────┤
│--globals [<name>] ... │ Add custom global variables or │
│ │ fields on top of standard ones. │
│ │ See Defining extra globals and │
│ │ fields │
├─────────────────────────────────┼────────────────────────────────────────────────┤
│--read-globals [<name>] ... │ Add read-only global variables │
│ │ or fields. │
├─────────────────────────────────┼────────────────────────────────────────────────┤
│--new-globals [<name>] ... │ Set custom global variables or │
│ │ fields. Removes custom globals │
│ │ added previously. │
├─────────────────────────────────┼────────────────────────────────────────────────┤
│--new-read-globals [<name>] ... │ Set read-only global variables │
│ │ or fields. Removes read-only │
│ │ globals added previously. │
├─────────────────────────────────┼────────────────────────────────────────────────┤
│--not-globals [<name>] ... │ Remove custom and standard │
│ │ global variables or fields. │
├─────────────────────────────────┼────────────────────────────────────────────────┤
│-c | --compat │ Equivalent to --std max. │
├─────────────────────────────────┼────────────────────────────────────────────────┤
│-d | --allow-defined │ Allow defining globals │
│ │ implicitly by setting them. │
│ │ │
│ │ See implicitlydefinedglobals │
├─────────────────────────────────┼────────────────────────────────────────────────┤
│-t | --allow-defined-top │ Allow defining globals │
│ │ implicitly by setting them in │
│ │ the top level scope. │
│ │ │
│ │ See implicitlydefinedglobals │
├─────────────────────────────────┼────────────────────────────────────────────────┤
│-m | --module │ Limit visibility of implicitly │
│ │ defined globals to their files. │
│ │ │
│ │ See modules │
├─────────────────────────────────┼────────────────────────────────────────────────┤
│--max-line-length <length> │ Set maximum allowed line length │
│ │ (default: 120). │
├─────────────────────────────────┼────────────────────────────────────────────────┤
│--no-max-line-length │ Do not limit line length. │
├─────────────────────────────────┼────────────────────────────────────────────────┤
│--max-code-line-length <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 │
│<length> │ 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 │
│<length> │ comment lines (default: 120). │
├─────────────────────────────────┼────────────────────────────────────────────────┤
│--no-max-comment-line-length │ Do not limit comment line │
│ │ length. │
├─────────────────────────────────┼────────────────────────────────────────────────┤
│--max-cyclomatic-complexity │ Set maximum cyclomatic │
│<limit> │ complexity for functions. │
├─────────────────────────────────┼────────────────────────────────────────────────┤
│--no-max-cyclomatic-complexity │ Do not limit function cyclomatic │
│ │ complexity (default). │
└─────────────────────────────────┴────────────────────────────────────────────────┘
│--ignore | -i <patt> [<patt>] │ Filter out warnings matching │
│... │ patterns. │
├─────────────────────────────────┼────────────────────────────────────────────────┤
│--enable | -e <patt> [<patt>] │ Do not filter out warnings │
│... │ matching patterns. │
├─────────────────────────────────┼────────────────────────────────────────────────┤
│--only | -o <patt> [<patt>] ... │ Filter out warnings not matching │
│ │ patterns. │
├─────────────────────────────────┼────────────────────────────────────────────────┤
│--config <config> │ Path to custom configuration │
│ │ file (default: .luacheckrc). │
├─────────────────────────────────┼────────────────────────────────────────────────┤
│--no-config │ Do not look up custom │
│ │ configuration file. │
├─────────────────────────────────┼────────────────────────────────────────────────┤
│--default-config <config> │ Default path to custom │
│ │ configuration file, to be used │
│ │ if --[no-]config is not used and │
│ │ .luacheckrc is not found. │
│ │ │
│ │ Default global location is: │
│ │ │
│ │ • %LOCALAPPDATA%\Luacheck\.luacheckrc │
│ │ on Windows; │
│ │ │
│ │ • ~/Library/Application │
│ │ Support/Luacheck/.luacheckrc │
│ │ on OS X/macOS; │
│ │ │
│ │ • $XDG_CONFIG_HOME/luacheck/.luacheckrc │
│ │ or │
│ │ ~/.config/luacheck/.luacheckrc │
│ │ on other systems. │
├─────────────────────────────────┼────────────────────────────────────────────────┤
│--no-default-config │ Do not use fallback configuration file. │
├─────────────────────────────────┼────────────────────────────────────────────────┤
│--filename <filename> │ Use another filename in output, for selecting │
│ │ configuration overrides and for file │
│ │ filtering. │
├─────────────────────────────────┼────────────────────────────────────────────────┤
│--exclude-files <glob> [<glob>] │ Do not check files matching these globbing │
│... │ patterns. Recursive globs such as **/*.lua are │
│ │ supported. │
├─────────────────────────────────┼────────────────────────────────────────────────┤
│--include-files <glob> [<glob>] │ Do not check files not matching these globbing │
│... │ patterns. │
├─────────────────────────────────┼────────────────────────────────────────────────┤
│--cache [<cache>] │ Path to cache file. (default: .luacheckcache). │
│ │ See Caching │
├─────────────────────────────────┼────────────────────────────────────────────────┤
│--no-cache │ Do not use cache. │
├─────────────────────────────────┼────────────────────────────────────────────────┤
│-j | --jobs │ Check <jobs> files in parallel. Requires │
│ │ LuaLanes. Default number of jobs is set to │
│ │ number of available processing units. │
└─────────────────────────────────┴────────────────────────────────────────────────┘
│--formatter <formatter> │ Use custom formatter. <formatter> must be a │
│ │ module name or one of: │
│ │ │
│ │ • 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. │
│ │ │
│ │ • -qq - Suppress output of warnings. │
│ │ │
│ │ • -qqq - Only output summary. │
├─────────────────────────────────┼────────────────────────────────────────────────┤
│--codes │ Show warning codes. │
├─────────────────────────────────┼────────────────────────────────────────────────┤
│--ranges │ Show ranges of columns related to warnings. │
├─────────────────────────────────┼────────────────────────────────────────────────┤
│--no-color │ Do not colorize output. │
├─────────────────────────────────┼────────────────────────────────────────────────┤
│-v | --version │ Show version of Luacheck and its dependencies │
│ │ and exit. │
├─────────────────────────────────┼────────────────────────────────────────────────┤
│-h | --help │ Show help and exit. │
└─────────────────────────────────┴────────────────────────────────────────────────┘
Patterns
CLI options --ignore, --enable and --only and corresponding config options allow filtering
warnings using pattern matching on warning codes, variable names or both. If a pattern
contains a slash, the part before slash matches warning code and the part after matches
variable name. Otherwise, if a pattern contains a letter or underscore, it matches
variable name. Otherwise, it matches warning code. E.g.:
┌────────┬──────────────────────────────────┐
│Pattern │ Matching warnings │
├────────┼──────────────────────────────────┤
│4.2 │ Shadowing declarations of │
│ │ arguments or redefining them. │
├────────┼──────────────────────────────────┤
│.*_ │ Warnings related to variables │
│ │ with _ suffix. │
├────────┼──────────────────────────────────┤
│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 one to
filter warnings by category (e.g. --only 1 focuses luacheck on global-related warnings).
Defining extra globals and fields
CLI options --globals, --new-globals, --read-globals, --new-read-globals, and
corresponding config options add new allowed globals or fields. E.g. --read-globals foo
--globals foo.bar allows accessing foo global and mutating its bar field. --not-globals
also operates on globals and fields and removes definitions of both standard and custom
globals.
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 current one instead of replacing it. For instance, --std +love is suitable for
checking files using LÖVE framework. Custom sets of globals can be defined by mutating
global variable stds in config. See custom_stds
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 report), array of file names and table of options. Options contain
values assigned to quiet, color, limit, codes, ranges and formatter options in CLI or
config. Formatter function must return a string.
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.
Stable interface for editor plugins and tools
Command-line interface of Luacheck can change between minor releases. Starting from 0.11.0
version, the following interface is guaranteed at least till 1.0.0 version, and should be
used by tools using Luacheck output, e.g. editor plugins.
• Luacheck should be started from the directory containing the checked file.
• File can be passed through stdin using - as argument or using a temporary file. Real
filename should be passed using --filename option.
• Plain formatter should be used. It outputs one issue (warning or error) per line.
• To get precise error location, --ranges option can be used. Each line starts with real
filename (passed using --filename), followed by :<line>:<start_column>-<end_column>:,
where <line> is line number on which issue occurred and <start_column>-<end_column> is
inclusive range of columns of token related to issue. Numbering starts from 1. If
--ranges is not used, end column and dash is not printed.
• To get warning and error codes, --codes option can be used. For each line, substring
between parentheses contains three digit issue code, prefixed with E for errors and W
for warnings. Lack of such substring indicates a fatal error (e.g. I/O error).
• The rest of the line is warning message.
If compatibility with older Luacheck version is desired, output of luacheck --help can be
used to get its version. If it contains string 0.<minor>.<patch>, where <minor> is at
least 11 and patch is any number, interface described above should be used.
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. 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. 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.
Options loaded from config have the lowest priority: it's possible to overwrite them with
CLI options or inline options.
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 │
├──────────────────────────┼──────────────────────────┼─────────────────────┤
│exclude_files │ Array of strings │ {} │
├──────────────────────────┼──────────────────────────┼─────────────────────┤
│include_files │ Array of strings │ (Include all files) │
├──────────────────────────┼──────────────────────────┼─────────────────────┤
│global │ Boolean │ true │
├──────────────────────────┼──────────────────────────┼─────────────────────┤
│unused │ Boolean │ true │
├──────────────────────────┼──────────────────────────┼─────────────────────┤
│redefined │ Boolean │ true │
├──────────────────────────┼──────────────────────────┼─────────────────────┤
│unused_args │ Boolean │ true │
├──────────────────────────┼──────────────────────────┼─────────────────────┤
│unused_secondaries │ Boolean │ true │
├──────────────────────────┼──────────────────────────┼─────────────────────┤
│self │ Boolean │ true │
├──────────────────────────┼──────────────────────────┼─────────────────────┤
│std │ String or set of │ "max" │
│ │ standard globals │ │
├──────────────────────────┼──────────────────────────┼─────────────────────┤
│globals │ Array of strings or │ {} │
│ │ field definition map │ │
├──────────────────────────┼──────────────────────────┼─────────────────────┤
│new_globals │ Array of strings or │ (Do not overwrite) │
│ │ field definition map │ │
├──────────────────────────┼──────────────────────────┼─────────────────────┤
│read_globals │ Array of strings or │ {} │
│ │ field definition map │ │
├──────────────────────────┼──────────────────────────┼─────────────────────┤
│new_read_globals │ Array of strings or │ (Do not overwrite) │
│ │ field definition map │ │
├──────────────────────────┼──────────────────────────┼─────────────────────┤
│not_globals │ Array of strings │ {} │
├──────────────────────────┼──────────────────────────┼─────────────────────┤
│compat │ Boolean │ false │
├──────────────────────────┼──────────────────────────┼─────────────────────┤
│allow_defined │ Boolean │ false │
├──────────────────────────┼──────────────────────────┼─────────────────────┤
│allow_defined_top │ Boolean │ false │
├──────────────────────────┼──────────────────────────┼─────────────────────┤
│module │ Boolean │ false │
├──────────────────────────┼──────────────────────────┼─────────────────────┤
│max_line_length │ Number or false │ 120 │
├──────────────────────────┼──────────────────────────┼─────────────────────┤
│max_code_line_length │ Number or false │ 120 │
├──────────────────────────┼──────────────────────────┼─────────────────────┤
│max_string_line_length │ Number or false │ 120 │
├──────────────────────────┼──────────────────────────┼─────────────────────┤
│max_comment_line_length │ Number or false │ 120 │
├──────────────────────────┼──────────────────────────┼─────────────────────┤
│max_cyclomatic_complexity │ Number or false │ false │
└──────────────────────────┴──────────────────────────┴─────────────────────┘
│ignore │ Array of patterns (see │ {} │
│ │ patterns) │ │
├──────────────────────────┼──────────────────────────┼─────────────────────┤
│enable │ Array of patterns │ {} │
├──────────────────────────┼──────────────────────────┼─────────────────────┤
│only │ Array of patterns │ (Do not filter) │
└──────────────────────────┴──────────────────────────┴─────────────────────┘
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:
std = "min"
ignore = {"212"}
Custom sets of globals
std option allows setting a custom standard set of globals using a table. This table can
have two fields: globals and read_globals. Both of them should contain a field definition
map defining some globals. The simplest way to define globals is to list their names:
std = {
globals = {"foo", "bar"}, -- these globals can be set and accessed.
read_globals = {"baz", "quux"} -- these globals can only be accessed.
}
For globals defined like this Luacheck will additionally consider any fields within them
defined. To define a global with a restricted set of fields, use global name as key and a
table as value. In that table, fields subtable can contain the fields in the same format:
std = {
read_globals = {
foo = { -- Defining read-only global `foo`...
fields = {
field1 = { -- `foo.field1` is now defined...
fields = {
nested_field = {} -- `foo.field1.nested_field` is now defined...
}
},
field2 = {} -- `foo.field2` is defined.
}
}
}
}
Globals and fields can be marked read-only or not using read_only property with a boolean
value. Property other_fields controls whether the global or field can also contain other
unspecified fields:
std = {
read_globals = {
foo = { -- `foo` and its fields are read-only by default (because they are within `read_globals` table).
fields = {
bar = {
read_only = false, -- `foo.bar` is not read-only, can be set.
other_fields = true, -- `foo.bar[anything]` is defined and can be set or mutated (inherited from `foo.bar`).
fields = {
baz = {read_only = true}, -- `foo.bar.baz` is read-only as an exception.
}
}
}
}
}
}
Custom sets can be given names by mutating global stds variable, so that they can then be
used in --std CLI option and std inline and config option.
stds.some_lib = {...}
std = "min+some_lib"
In config, globals, new_globals, read_globals, and new_read_globals can also contain
definitions in same format:
read_globals = {
server = {
fields = {
-- Allow mutating `server.sessions` with any keys...
sessions = {read_only = false, other_fields = true},
-- other fields...
}
},
--- other globals...
}
Per-file and per-path overrides
The environment in which luacheck loads the config contains a special global files. When
checking a file <path>, luacheck will override options from the main config with entries
from files[<glob>] if <glob> matches <path>, applying entries for more general globs
first. For example, the following config re-enables detection of unused arguments only for
files in src/dir, but not for files ending with _special.lua:
std = "min"
ignore = {"212"}
files["src/dir"] = {enable = {"212"}}
files["src/dir/**/*_special.lua"] = {ignore = {"212"}}
Note that files table supports autovivification, so that
files["src/dir"].enable = {"212"}
and
files["src/dir"] = {enable = {"212"}}
are equivalent.
Default per-path std overrides
luacheck uses a set of default per-path overrides:
files["**/spec/**/*_spec.lua"].std = "+busted"
files["**/test/**/*_spec.lua"].std = "+busted"
files["**/tests/**/*_spec.lua"].std = "+busted"
files["**/*.rockspec"].std = "+rockspec"
files["**/*.luacheckrc"].std = "+luacheckrc"
Each of these can be overriden by setting a different std value for the corresponding key
in files.
INLINE OPTIONS
Luacheck supports setting some options directly in the checked files using inline
configuration comments. These inline options have the highest priority, overwriting both
config options and CLI options.
An inline configuration comment is a short comment starting with luacheck: label, possibly
after some whitespace. The body of the comment should contain comma separated options,
where option invocation consists of its name plus space separated arguments. It can also
contain notes enclosed in balanced parentheses, which are ignored. The following options
are supported:
┌────────────────────────┬──────────────────────────────────┐
│Option │ Number of arguments │
├────────────────────────┼──────────────────────────────────┤
│global │ 0 │
├────────────────────────┼──────────────────────────────────┤
│unused │ 0 │
├────────────────────────┼──────────────────────────────────┤
│redefined │ 0 │
└────────────────────────┴──────────────────────────────────┘
│unused args │ 0 │
├────────────────────────┼──────────────────────────────────┤
│unused secondaries │ 0 │
├────────────────────────┼──────────────────────────────────┤
│self │ 0 │
├────────────────────────┼──────────────────────────────────┤
│compat │ 0 │
├────────────────────────┼──────────────────────────────────┤
│module │ 0 │
├────────────────────────┼──────────────────────────────────┤
│allow defined │ 0 │
├────────────────────────┼──────────────────────────────────┤
│allow defined top │ 0 │
├────────────────────────┼──────────────────────────────────┤
│max line length │ 1 (with no and no arguments │
│ │ disables line length checks) │
├────────────────────────┼──────────────────────────────────┤
│max code line length │ 1 (with no and no arguments │
│ │ disables code line length │
│ │ checks) │
├────────────────────────┼──────────────────────────────────┤
│max string line length │ 1 (with no and no arguments │
│ │ disables string line length │
│ │ checks) │
├────────────────────────┼──────────────────────────────────┤
│max comment line length │ 1 (with no and no arguments │
│ │ disables comment line length │
│ │ checks) │
├────────────────────────┼──────────────────────────────────┤
│std │ 1 │
├────────────────────────┼──────────────────────────────────┤
│globals │ 0+ │
├────────────────────────┼──────────────────────────────────┤
│new globals │ 0+ │
├────────────────────────┼──────────────────────────────────┤
│read globals │ 0+ │
├────────────────────────┼──────────────────────────────────┤
│new read globals │ 0+ │
├────────────────────────┼──────────────────────────────────┤
│not globals │ 0+ │
├────────────────────────┼──────────────────────────────────┤
│ignore │ 0+ (without arguments everything │
│ │ is ignored) │
├────────────────────────┼──────────────────────────────────┤
│enable │ 1+ │
├────────────────────────┼──────────────────────────────────┤
│only │ 1+ │
└────────────────────────┴──────────────────────────────────┘
Options that take no arguments can be prefixed with no to invert their meaning. E.g.
--luacheck: no unused args disables unused argument warnings.
Part of the file affected by inline option dependes on where it is placed. If there is any
code on the line with the option, only that line is affected; otherwise, everything till
the end of the current closure is. In particular, inline options at the top of the file
affect all of it:
-- luacheck: globals g1 g2, ignore foo
local foo = g1(g2) -- No warnings emitted.
-- The following unused function is not reported.
local function f() -- luacheck: ignore
-- luacheck: globals g3
g3() -- No warning.
end
g3() -- Warning is emitted as the inline option defining g3 only affected function f.
For fine-grained control over inline option visibility use luacheck: push and luacheck:
pop directives:
-- luacheck: push ignore foo
foo() -- No warning.
-- luacheck: pop
foo() -- Warning is emitted.
LUACHECK MODULE
Use local luacheck = require "luacheck" to import luacheck module. It contains the
following functions:
• luacheck.get_report(source): Given source string, returns analysis data (a table).
• 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 options. Analysis reports with field fatal are ignored.
process_reports returns final report, see Report format.
• luacheck.check_strings(sources, options): Checks array of sources using options, returns
final report. Tables with field fatal within 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.
• luacheck.get_message(issue): Returns a string message for an issue, see Report format.
luacheck._VERSION contains Luacheck version as a string in MAJOR.MINOR.PATCH format.
Using luacheck as a function is equivalent to calling luacheck.check_files.
Report format
A final report is an array of file reports plus fields warnings, errors and fatals
containing total number of warnings, errors and fatal errors, correspondingly.
A file report is an array of issues (warnings or errors). If a fatal error occurred while
checking a file, its report will have fatal field containing error type and msg field
containing error message.
An issue is a table with field code indicating its type (see 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. │
├──────────────┼──────────────────────────────────┤
│122, 142, 143 │ field field contains string │
│ │ representation of related global │
│ │ field. │
├──────────────┼──────────────────────────────────┤
│211 │ func field indicates that unused │
│ │ variable is a function. │
├──────────────┼──────────────────────────────────┤
│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. │
├──────────────┼──────────────────────────────────┤
│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.
This is documentation for 0.25.0 version of Luacheck, a linter for Lua.
AUTHOR
Peter Melnichenko
COPYRIGHT
2021 - 2018, Peter Melnichenko