Global variables¶

Read-only globals¶

Implicitly defined globals¶

Modules¶

Unused variables and values¶

Unused values and uninitialized variables¶

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¶

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¶

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¶

Whitespace issues¶

Command line options¶

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.

Patterns¶

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

Sets of standard globals¶

Formatters¶

Caching¶

Stable interface for editor plugins and tools¶

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.

Config options¶

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¶

Additionally, custom sets can be given names by mutating global stds variable. For example, when using LPEG library, it makes sense to access its functions tersely using globals. In that case, the following config allows removing false positives related to global access easily:

stds.lpeg = require "lpeg"

local lpeg = require "lpeg"
local function parse1(...)
   -- This function only uses lpeg functions as globals.
   local _ENV = lpeg
   -- luacheck: std lpeg
   local digit, space = R "09", S " "
   -- ...
end
local function parse2(...)
   -- This function uses lpeg functions as well as standard globals.
   local _ENV = setmetatable({}, {__index = function(_, k) return _ENV[k] or lpeg[k] end})
   -- luacheck: std +lpeg
   local digit, space = R "09", S " "
   local number = C(digit^1) / tonumber
   -- ...
end

Per-file and per-path overrides¶

std = "min"
ignore = {"212"}
files["src/dir"] = {enable = {"212"}}
files["src/dir/**/*_special.lua"] = {ignore = {"212"}}
files["spec"] = {std = "+busted"}

Note that files table supports autovivification, so that

files["src/dir"].enable = {"212"}

and

files["src/dir"] = {enable = {"212"}}

are equivalent.

Report format¶

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:

Other fields may be present for internal reasons.

This is documentation for 0.17.1 version of Luacheck, a linter for Lua.