.\" Man page generated from reStructuredText.
.
.TH "LUACHECK" "1" "Dec 22, 2016" "0.17.1" "luacheck"
.SH NAME
luacheck \- luacheck Documentation
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.sp
Contents:
.SH LIST OF WARNINGS
.sp
Warnings produced by Luacheck are categorized using three\-digit warning codes. Warning codes can be displayed in CLI output using \fB\-\-codes\fP CLI option or \fBcodes\fP config option. Errors also have codes starting with zero.
.TS
center;
|l|l|.
_
T{
Code
T}	T{
Description
T}
_
T{
011
T}	T{
A syntax error.
T}
_
T{
021
T}	T{
An invalid inline option.
T}
_
T{
022
T}	T{
An unpaired inline push directive.
T}
_
T{
023
T}	T{
An unpaired inline pop directive.
T}
_
T{
111
T}	T{
Setting an undefined global variable.
T}
_
T{
112
T}	T{
Mutating an undefined global variable.
T}
_
T{
113
T}	T{
Accessing an undefined global variable.
T}
_
T{
121
T}	T{
Setting a read\-only global variable.
T}
_
T{
122
T}	T{
Mutating a read\-only global variable.
T}
_
T{
131
T}	T{
Unused implicitly defined global variable.
T}
_
T{
211
T}	T{
Unused local variable.
T}
_
T{
212
T}	T{
Unused argument.
T}
_
T{
213
T}	T{
Unused loop variable.
T}
_
T{
221
T}	T{
Local variable is accessed but never set.
T}
_
T{
231
T}	T{
Local variable is set but never accessed.
T}
_
T{
232
T}	T{
An argument is set but never accessed.
T}
_
T{
233
T}	T{
Loop variable is set but never accessed.
T}
_
T{
241
T}	T{
Local variable is mutated but never accessed.
T}
_
T{
311
T}	T{
Value assigned to a local variable is unused.
T}
_
T{
312
T}	T{
Value of an argument is unused.
T}
_
T{
313
T}	T{
Value of a loop variable is unused.
T}
_
T{
314
T}	T{
Value of a field in a table literal is unused.
T}
_
T{
321
T}	T{
Accessing uninitialized local variable.
T}
_
T{
331
T}	T{
Value assigned to a local variable is mutated but never accessed.
T}
_
T{
341
T}	T{
Mutating uninitialized local variable.
T}
_
T{
411
T}	T{
Redefining a local variable.
T}
_
T{
412
T}	T{
Redefining an argument.
T}
_
T{
413
T}	T{
Redefining a loop variable.
T}
_
T{
421
T}	T{
Shadowing a local variable.
T}
_
T{
422
T}	T{
Shadowing an argument.
T}
_
T{
423
T}	T{
Shadowing a loop variable.
T}
_
T{
431
T}	T{
Shadowing an upvalue.
T}
_
T{
432
T}	T{
Shadowing an upvalue argument.
T}
_
T{
433
T}	T{
Shadowing an upvalue loop variable.
T}
_
T{
511
T}	T{
Unreachable code.
T}
_
T{
512
T}	T{
Loop can be executed at most once.
T}
_
T{
521
T}	T{
Unused label.
T}
_
T{
531
T}	T{
Left\-hand side of an assignment is too short.
T}
_
T{
532
T}	T{
Left\-hand side of an assignment is too long.
T}
_
T{
541
T}	T{
An empty \fBdo\fP \fBend\fP block.
T}
_
T{
542
T}	T{
An empty \fBif\fP branch.
T}
_
T{
551
T}	T{
An empty statement.
T}
_
T{
611
T}	T{
A line consists of nothing but whitespace.
T}
_
T{
612
T}	T{
A line contains trailing whitespace.
T}
_
T{
621
T}	T{
Inconsistent indentation (\fBSPACE\fP followed by \fBTAB\fP).
T}
_
.TE
.SS Global variables
.sp
For each file, Luacheck builds list of defined globals which can be used there. By default only globals from Lua standard library are defined; custom globals can be added using \fB\-\-globals\fP CLI option or \fBglobals\fP config option, and version of standard library can be selected using \fB\-\-std\fP CLI option or \fBstd\fP config option. When an undefined global is set, mutated or accessed, Luacheck produces a warning.
.SS Read\-only globals
.sp
By default, all standard globals except \fB_G\fP and \fBpackage\fP are marked as read\-only, so that setting or mutating them produces a warning. Custom read\-only globals can be added using \fB\-\-read\-globals\fP CLI option or \fBread_globals\fP config option.
.SS Implicitly defined globals
.sp
Luacheck can be configured to consider globals assigned under some conditions to be defined implicitly. When \fB\-d\fP/\fB\-\-allow_defined\fP CLI option or \fBallow_defined\fP config option is used, all assignments to globals define them; when \fB\-t\fP/\fB\-\-allow_defined_top\fP CLI option or \fBallow_defined_top\fP 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.
.SS Modules
.sp
Files can be marked as modules using \fB\-m\fP/\fB\-\-module\fP CLI option or \fBmodule\fP config option to simulate semantics of the deprecated \fI\%module\fP 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.
.SS Unused variables and values
.sp
Luacheck generates warnings for all unused local variables except one named \fB_\fP\&. It also detects variables which are set but never accessed or accessed but never set.
.SS Unused values and uninitialized variables
.sp
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\(aqt be used anywhere) and for accessing uninitialized variables (when no values can reach an expression). E.g. in the following snippet value assigned to \fBfoo\fP on line 1 is unused, and variable \fBbar\fP is uninitialized on line 9:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
local foo = expr1()
local bar

if condition() then
   foo = expr2()
   bar = expr3()
else
   foo = expr4()
   print(bar)
end

return foo, bar
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Secondary values and variables
.sp
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 \fBb\fP is secondary, value assigned to \fBc\fP is used, and value assigned to \fBa\fP is simply unused:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
local a, b, c = f(), g()

return c
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A variable is secondary if all values assigned to it are secondary. In the snippet above, \fBb\fP is a secondary variable.
.sp
Warnings related to unused secondary values and variables can be removed using \fB\-s\fP/\fB\-\-no\-unused\-secondaries\fP CLI option or \fBunused_secondaries\fP config option.
.SS Shadowing declarations
.sp
Luacheck detects declarations of local variables shadowing previous declarations, unless the variable is named \fB_\fP\&. If the previous declaration is in the same scope as the new one, it is called redefining.
.sp
Note that it is \fBnot\fP necessary to define a new local variable when overwriting an argument:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
local function f(x)
   local x = x or "default" \-\- bad
end

local function f(x)
   x = x or "default" \-\- good
end
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Control flow and data flow issues
.sp
The following control flow and data flow issues are detected:
.INDENT 0.0
.IP \(bu 2
Unreachable code and loops that can be executed at most once (e.g. due to an unconditional break);
.IP \(bu 2
Unused labels;
.IP \(bu 2
Unbalanced assignments;
.IP \(bu 2
Empty blocks.
.IP \(bu 2
Empty statements (semicolons without preceding statements).
.UNINDENT
.SS Whitespace issues
.sp
Luacheck detects some common whitespace issues, such as trailing whitespace.
.SH COMMAND LINE INTERFACE
.sp
\fBluacheck\fP program accepts files, directories and \fI\%rockspecs\fP as arguments. They can be filtered using \fB\-\-include\-files\fP and \fB\-\-exclude\-files\fP options, see below.
.INDENT 0.0
.IP \(bu 2
Given a file, \fBluacheck\fP will check it.
.IP \(bu 2
Given \fB\-\fP, \fBluacheck\fP will check stdin.
.IP \(bu 2
Given a directory, \fBluacheck\fP will check all files within it, selecting only files with \fB\&.lua\fP extension unless \fB\-\-include\-files\fP option is used. This feature requires \fI\%LuaFileSystem\fP (installed automatically if LuaRocks was used to install Luacheck).
.IP \(bu 2
Given a rockspec (a file with \fB\&.rockspec\fP extension), \fBluacheck\fP will check all files with \fB\&.lua\fP extension mentioned in the rockspec in \fBbuild.install.lua\fP, \fBbuild.install.bin\fP and \fBbuild.modules\fP tables.
.UNINDENT
.sp
The output of \fBluacheck\fP consists of separate reports for each checked file and ends with a summary:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ 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 \(aq=\(aq near \(aq__future__\(aq

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
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBluacheck\fP exits with 0 if no warnings or errors occurred and with a positive number otherwise.
.SS Command line options
.sp
Short options that do not take an argument can be combined into one, so that \fB\-qqu\fP is equivalent to \fB\-q \-q \-u\fP\&. For long options, both \fB\-\-option value\fP or \fB\-\-option=value\fP can be used.
.sp
Options taking several arguments can be used several times; \fB\-\-ignore foo \-\-ignore bar\fP is equivalent to \fB\-\-ignore foo bar\fP\&.
.sp
Note that options that may take several arguments, such as \fB\-\-globals\fP, should not be used immediately before positional arguments; given \fB\-\-globals foo bar file.lua\fP, \fBluacheck\fP will consider all \fBfoo\fP, \fBbar\fP and \fBfile.lua\fP global and then panic as there are no file names left.
.TS
center;
|l|l|.
_
T{
Option
T}	T{
Meaning
T}
_
T{
\fB\-g | \-\-no\-global\fP
T}	T{
Filter out warnings related to global variables.
T}
_
T{
\fB\-u | \-\-no\-unused\fP
T}	T{
Filter out warnings related to unused variables and values.
T}
_
T{
\fB\-r | \-\-no\-redefined\fP
T}	T{
Filter out warnings related to redefined variables.
T}
_
T{
\fB\-a | \-\-no\-unused\-args\fP
T}	T{
Filter out warnings related to unused arguments and loop variables.
T}
_
T{
\fB\-s | \-\-no\-unused\-secondaries\fP
T}	T{
Filter out warnings related to unused variables set together with used ones.
.sp
See secondaryvaluesandvariables
T}
_
T{
\fB\-\-no\-self\fP
T}	T{
Filter out warnings related to implicit \fBself\fP argument.
T}
_
T{
\fB\-\-std <std>\fP
T}	T{
Set standard globals. \fB<std>\fP can be one of:
.INDENT 0.0
.IP \(bu 2
\fB_G\fP \- globals of the Lua interpreter \fBluacheck\fP runs on (default);
.IP \(bu 2
\fBlua51\fP \- globals of Lua 5.1;
.IP \(bu 2
\fBlua52\fP \- globals of Lua 5.2;
.IP \(bu 2
\fBlua52c\fP \- globals of Lua 5.2 compiled with LUA_COMPAT_ALL;
.IP \(bu 2
\fBlua53\fP \- globals of Lua 5.3;
.IP \(bu 2
\fBlua53c\fP \- globals of Lua 5.3 compiled with LUA_COMPAT_5_2;
.IP \(bu 2
\fBluajit\fP \- globals of LuaJIT 2.0;
.IP \(bu 2
\fBngx_lua\fP \- globals of Openresty \fI\%lua\-nginx\-module\fP with LuaJIT 2.0;
.IP \(bu 2
\fBrockspec\fP \- globals allowed in rockspecs;
.IP \(bu 2
\fBmin\fP \- intersection of globals of Lua 5.1, Lua 5.2, Lua 5.3 and LuaJIT 2.0;
.IP \(bu 2
\fBmax\fP \- union of globals of Lua 5.1, Lua 5.2, Lua 5.3 and LuaJIT 2.0;
.IP \(bu 2
\fBbusted\fP \- globals added by Busted 2.0;
.IP \(bu 2
\fBnone\fP \- no standard globals.
.UNINDENT
.sp
See \fI\%Sets of standard globals\fP
T}
_
T{
\fB\-\-globals [<global>] ...\fP
T}	T{
Add custom globals on top of standard ones.
T}
_
T{
\fB\-\-read\-globals [<global>] ...\fP
T}	T{
Add read\-only globals.
T}
_
T{
\fB\-\-new\-globals [<global>] ...\fP
T}	T{
Set custom globals. Removes custom globals added previously.
T}
_
T{
\fB\-\-new\-read\-globals [<global>] ...\fP
T}	T{
Set read\-only globals. Removes read\-only globals added previously.
T}
_
T{
\fB\-c | \-\-compat\fP
T}	T{
Equivalent to \fB\-\-std max\fP\&.
T}
_
T{
\fB\-d | \-\-allow\-defined\fP
T}	T{
Allow defining globals implicitly by setting them.
.sp
See implicitlydefinedglobals
T}
_
T{
\fB\-t | \-\-allow\-defined\-top\fP
T}	T{
Allow defining globals implicitly by setting them in the top level scope.
.sp
See implicitlydefinedglobals
T}
_
T{
\fB\-m | \-\-module\fP
T}	T{
Limit visibility of implicitly defined globals to their files.
.sp
See modules
T}
_
T{
\fB\-\-ignore | \-i <patt> [<patt>] ...\fP
T}	T{
Filter out warnings matching patterns.
T}
_
T{
\fB\-\-enable | \-e <patt> [<patt>] ...\fP
T}	T{
Do not filter out warnings matching patterns.
T}
_
T{
\fB\-\-only | \-o <patt> [<patt>] ...\fP
T}	T{
Filter out warnings not matching patterns.
T}
_
T{
\fB\-\-no\-inline\fP
T}	T{
Disable inline options.
T}
_
T{
\fB\-\-config <config>\fP
T}	T{
Path to custom configuration file (default: \fB\&.luacheckrc\fP).
T}
_
T{
\fB\-\-no\-config\fP
T}	T{
Do not look up custom configuration file.
T}
_
T{
\fB\-\-filename <filename>\fP
T}	T{
Use another filename in output, for selecting
configuration overrides and for file filtering.
T}
_
T{
\fB\-\-exclude\-files <glob> [<glob>] ...\fP
T}	T{
Do not check files matching these globbing patterns. Recursive globs such as \fB**/*.lua\fP are supported.
T}
_
T{
\fB\-\-include\-files <glob> [<glob>] ...\fP
T}	T{
Do not check files not matching these globbing patterns.
T}
_
T{
\fB\-\-cache [<cache>]\fP
T}	T{
Path to cache file. (default: \fB\&.luacheckcache\fP). See \fI\%Caching\fP
T}
_
T{
\fB\-\-no\-cache\fP
T}	T{
Do not use cache.
T}
_
T{
\fB\-j | \-\-jobs\fP
T}	T{
Check \fB<jobs>\fP files in parallel. Requires \fI\%LuaLanes\fP\&.
Default number of jobs is set to number of available processing units.
T}
_
T{
\fB\-\-formatter <formatter>\fP
T}	T{
Use custom formatter. \fB<formatter>\fP must be a module name or one of:
.INDENT 0.0
.IP \(bu 2
\fBTAP\fP \- Test Anything Protocol formatter;
.IP \(bu 2
\fBJUnit\fP \- JUnit XML formatter;
.IP \(bu 2
\fBplain\fP \- simple warning\-per\-line formatter;
.IP \(bu 2
\fBdefault\fP \- standard formatter.
.UNINDENT
T}
_
T{
\fB\-q | \-\-quiet\fP
T}	T{
Suppress report output for files without warnings.
.INDENT 0.0
.IP \(bu 2
\fB\-qq\fP \- Suppress output of warnings.
.IP \(bu 2
\fB\-qqq\fP \- Only output summary.
.UNINDENT
T}
_
T{
\fB\-\-codes\fP
T}	T{
Show warning codes.
T}
_
T{
\fB\-\-ranges\fP
T}	T{
Show ranges of columns related to warnings.
T}
_
T{
\fB\-\-no\-color\fP
T}	T{
Do not colorize output.
T}
_
T{
\fB\-v | \-\-version\fP
T}	T{
Show version of Luacheck and its dependencies and exit.
T}
_
T{
\fB\-h | \-\-help\fP
T}	T{
Show help and exit.
T}
_
.TE
.SS Patterns
.sp
CLI options \fB\-\-ignore\fP, \fB\-\-enable\fP and \fB\-\-only\fP 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.:
.TS
center;
|l|l|.
_
T{
Pattern
T}	T{
Matching warnings
T}
_
T{
4.2
T}	T{
Shadowing declarations of arguments or redefining them.
T}
_
T{
\&.*_
T}	T{
Warnings related to variables with \fB_\fP suffix.
T}
_
T{
4.2/.*_
T}	T{
Shadowing declarations of arguments with \fB_\fP suffix or redefining them.
T}
_
.TE
.sp
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. \fB\-\-only 1\fP focuses \fBluacheck\fP on global\-related warnings).
.SS Sets of standard globals
.sp
CLI option \fB\-\-stds\fP allows combining built\-in sets described above using \fB+\fP\&. For example, \fB\-\-std max\fP is equivalent to \fB\-\-std=lua51+lua52+lua53\fP\&. Leading plus sign adds new sets to default one instead of replacing it. For instance, \fB\-\-std +busted\fP is suitable for checking test files that use \fI\%Busted\fP testing framework. Custom sets of globals can be defined by mutating global variable \fBstds\fP in config. See custom_stds
.SS Formatters
.sp
CLI option \fB\-\-formatter\fP allows selecting a custom formatter for \fBluacheck\fP output. A custom formatter is a Lua module returning a function with three arguments: report as returned by \fBluacheck\fP module (see report), array of file names and table of options. Options contain values assigned to \fBquiet\fP, \fBcolor\fP, \fBlimit\fP, \fBcodes\fP, \fBranges\fP and \fBformatter\fP options in CLI or config. Formatter function must return a string.
.SS Caching
.sp
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 \fB\-\-cache <cache>\fP option or \fBcache\fP config option. Using \fB\-\-cache\fP without an argument or setting \fBcache\fP config option to \fBtrue\fP sets \fB\&.luacheckcache\fP as the cache file. Note that \fB\-\-cache\fP must be used every time \fBluacheck\fP is run, not on the first run only.
.SS Stable interface for editor plugins and tools
.sp
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.
.INDENT 0.0
.IP \(bu 2
Luacheck should be started from the directory containing the checked file.
.IP \(bu 2
File can be passed through stdin using \fB\-\fP as argument or using a temporary file. Real filename should be passed using \fB\-\-filename\fP option.
.IP \(bu 2
Plain formatter should be used. It outputs one issue (warning or error) per line.
.IP \(bu 2
To get precise error location, \fB\-\-ranges\fP option can be used. Each line starts with real filename (passed using \fB\-\-filename\fP), followed by \fB:<line>:<start_column>\-<end_column>:\fP, where \fB<line>\fP is line number on which issue occurred and \fB<start_column>\-<end_column>\fP is inclusive range of columns of token related to issue. Numbering starts from 1. If \fB\-\-ranges\fP is not used, end column and dash is not printed.
.IP \(bu 2
To get warning and error codes, \fB\-\-codes\fP option can be used. For each line, substring between parentheses contains three digit issue code, prefixed with \fBE\fP for errors and \fBW\fP for warnings. Lack of such substring indicates a fatal error (e.g. I/O error).
.IP \(bu 2
The rest of the line is warning message.
.UNINDENT
.sp
If compatibility with older Luacheck version is desired, output of \fBluacheck \-\-help\fP can be used to get its version. If it contains string \fB0.<minor>.<patch>\fP, where \fB<minor>\fP is at least 11 and \fBpatch\fP is any number, interface described above should be used.
.SH CONFIGURATION FILE
.sp
\fBluacheck\fP tries to load configuration from \fB\&.luacheckrc\fP 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 \fB\-\-config\fP option, in which case it will be used during recursive loading. Config loading can be disabled using \fB\-\-no\-config\fP flag.
.sp
Config is simply a Lua script executed by \fBluacheck\fP\&. It may set various options by assigning to globals or by returning a table with option names as keys.
.SS Config options
.TS
center;
|l|l|l|.
_
T{
Option
T}	T{
Type
T}	T{
Default value
T}
_
T{
\fBcolor\fP
T}	T{
Boolean
T}	T{
\fBtrue\fP
T}
_
T{
\fBcodes\fP
T}	T{
Boolean
T}	T{
\fBfalse\fP
T}
_
T{
\fBformatter\fP
T}	T{
String or function
T}	T{
\fB"default"\fP
T}
_
T{
\fBcache\fP
T}	T{
Boolean or string
T}	T{
\fBfalse\fP
T}
_
T{
\fBjobs\fP
T}	T{
Positive integer
T}	T{
\fB1\fP
T}
_
T{
\fBexclude_files\fP
T}	T{
Array of strings
T}	T{
\fB{}\fP
T}
_
T{
\fBinclude_files\fP
T}	T{
Array of strings
T}	T{
(Include all files)
T}
_
T{
\fBglobal\fP
T}	T{
Boolean
T}	T{
\fBtrue\fP
T}
_
T{
\fBunused\fP
T}	T{
Boolean
T}	T{
\fBtrue\fP
T}
_
T{
\fBredefined\fP
T}	T{
Boolean
T}	T{
\fBtrue\fP
T}
_
T{
\fBunused_args\fP
T}	T{
Boolean
T}	T{
\fBtrue\fP
T}
_
T{
\fBunused_secondaries\fP
T}	T{
Boolean
T}	T{
\fBtrue\fP
T}
_
T{
\fBself\fP
T}	T{
Boolean
T}	T{
\fBtrue\fP
T}
_
T{
\fBstd\fP
T}	T{
String or set of standard globals
T}	T{
\fB"_G"\fP
T}
_
T{
\fBglobals\fP
T}	T{
Array of strings
T}	T{
\fB{}\fP
T}
_
T{
\fBnew_globals\fP
T}	T{
Array of strings
T}	T{
(Do not overwrite)
T}
_
T{
\fBread_globals\fP
T}	T{
Array of strings
T}	T{
\fB{}\fP
T}
_
T{
\fBnew_read_globals\fP
T}	T{
Array of strings
T}	T{
(Do not overwrite)
T}
_
T{
\fBcompat\fP
T}	T{
Boolean
T}	T{
\fBfalse\fP
T}
_
T{
\fBallow_defined\fP
T}	T{
Boolean
T}	T{
\fBfalse\fP
T}
_
T{
\fBallow_defined_top\fP
T}	T{
Boolean
T}	T{
\fBfalse\fP
T}
_
T{
\fBmodule\fP
T}	T{
Boolean
T}	T{
\fBfalse\fP
T}
_
T{
\fBignore\fP
T}	T{
Array of patterns (see patterns)
T}	T{
\fB{}\fP
T}
_
T{
\fBenable\fP
T}	T{
Array of patterns
T}	T{
\fB{}\fP
T}
_
T{
\fBonly\fP
T}	T{
Array of patterns
T}	T{
(Do not filter)
T}
_
T{
\fBinline\fP
T}	T{
Boolean
T}	T{
\fBtrue\fP
T}
_
.TE
.sp
An example of a config which makes \fBluacheck\fP 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:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
std = "min"
ignore = {"212"}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Custom sets of globals
.sp
\fBstd\fP option allows setting a custom standard set of globals using a table. In that table, string keys are globals, and string in array part are read\-only globals.
.sp
Additionally, custom sets can be given names by mutating global \fBstds\fP variable. For example, when using \fI\%LPEG\fP 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:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
stds.lpeg = require "lpeg"
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
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
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Per\-file and per\-path overrides
.sp
The environment in which \fBluacheck\fP loads the config contains a special global \fBfiles\fP\&. When checking a file \fB<path>\fP, \fBluacheck\fP will override options from the main config with entries from \fBfiles[<glob>]\fP if \fB<glob>\fP matches \fB<path>\fP, applying entries for more general globs first. For example, the following config re\-enables detection of unused arguments only for files in \fBsrc/dir\fP, but not for files ending with \fB_special.lua\fP, and allows using \fI\%Busted\fP globals within \fBspec/\fP:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
std = "min"
ignore = {"212"}
files["src/dir"] = {enable = {"212"}}
files["src/dir/**/*_special.lua"] = {ignore = {"212"}}
files["spec"] = {std = "+busted"}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note that \fBfiles\fP table supports autovivification, so that
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
files["src/dir"].enable = {"212"}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
and
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
files["src/dir"] = {enable = {"212"}}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
are equivalent.
.SH INLINE OPTIONS
.sp
Luacheck supports setting some options directly in the checked files using inline configuration comments. An inline configuration comment starts with \fBluacheck:\fP 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:
.TS
center;
|l|l|.
_
T{
Option
T}	T{
Number of arguments
T}
_
T{
global
T}	T{
0
T}
_
T{
unused
T}	T{
0
T}
_
T{
redefined
T}	T{
0
T}
_
T{
unused args
T}	T{
0
T}
_
T{
unused secondaries
T}	T{
0
T}
_
T{
self
T}	T{
0
T}
_
T{
compat
T}	T{
0
T}
_
T{
module
T}	T{
0
T}
_
T{
allow defined
T}	T{
0
T}
_
T{
allow defined top
T}	T{
0
T}
_
T{
std
T}	T{
1
T}
_
T{
globals
T}	T{
0+
T}
_
T{
new globals
T}	T{
0+
T}
_
T{
read globals
T}	T{
0+
T}
_
T{
new read globals
T}	T{
0+
T}
_
T{
ignore
T}	T{
0+ (without arguments everything is ignored)
T}
_
T{
enable
T}	T{
1+
T}
_
T{
only
T}	T{
1+
T}
_
.TE
.sp
Options that take no arguments can be prefixed with \fBno\fP to invert their meaning. E.g. \fB\-\-luacheck: no unused args\fP disables unused argument warnings.
.sp
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:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\-\- 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.
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For fine\-grained control over inline option visibility use \fBluacheck: push\fP and \fBluacheck: pop\fP directives:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\-\- luacheck: push ignore foo
foo() \-\- No warning.
\-\- luacheck: pop
foo() \-\- Warning is emitted.
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Inline options can be completely disabled using \fB\-\-no\-inline\fP CLI option or \fBinline\fP config option.
.SH LUACHECK MODULE
.sp
Use \fBlocal luacheck = require "luacheck"\fP to import \fBluacheck\fP module. It contains the following functions:
.INDENT 0.0
.IP \(bu 2
\fBluacheck.get_report(source)\fP: Given source string, returns analysis data (a table).
.IP \(bu 2
\fBluacheck.process_reports(reports, options)\fP: Processes array of analysis reports and applies options. \fBreports[i]\fP uses \fBoptions\fP, \fBoptions[i]\fP, \fBoptions[i][1]\fP, \fBoptions[i][2]\fP, ... 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 \fBfatal\fP are ignored. \fBprocess_reports\fP returns final report, see \fI\%Report format\fP\&.
.IP \(bu 2
\fBluacheck.check_strings(sources, options)\fP: Checks array of sources using options, returns final report. Tables with field \fBfatal\fP within \fBsources\fP array are ignored.
.IP \(bu 2
\fBluacheck.check_files(files, options)\fP: 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.
.IP \(bu 2
\fBluacheck.get_message(issue)\fP: Returns a string message for an issue, see \fI\%Report format\fP\&.
.UNINDENT
.sp
\fBluacheck._VERSION\fP contains Luacheck version as a string in \fBMAJOR.MINOR.PATCH\fP format.
.sp
Using \fBluacheck\fP as a function is equivalent to calling \fBluacheck.check_files\fP\&.
.SS Report format
.sp
A final report is an array of file reports plus fields \fBwarnings\fP, \fBerrors\fP and \fBfatals\fP containing total number of warnings, errors and fatal errors, correspondingly.
.sp
A file report is an array of issues (warnings or errors). If a fatal error occurred while checking a file, its report will have \fBfatal\fP field containing error type and \fBmsg\fP field containing error message.
.sp
An issue is a table with field \fBcode\fP indicating its type (see warnings), and fields \fBline\fP, \fBcolumn\fP and \fBend_column\fP pointing to the source of the warning. \fBname\fP field may contain name of related variable. Issues of some types can also have additional fields:
.TS
center;
|l|l|.
_
T{
Codes
T}	T{
Additional fields
T}
_
T{
011
T}	T{
\fBmsg\fP field contains syntax error message.
T}
_
T{
111
T}	T{
\fBmodule\fP field indicates that assignment is to a non\-module global variable.
T}
_
T{
211
T}	T{
\fBfunc\fP field indicates that unused variable is a function.
T}
_
T{
211
T}	T{
\fBrecursive\fP field indicates that unused function is recursive.
T}
_
T{
211
T}	T{
\fBmutually_recursive\fP field is set for unused mutually recursive functions.
T}
_
T{
314
T}	T{
\fBfield\fP field contains string representation of ununsed field or index.
T}
_
T{
4..
T}	T{
\fBprev_line\fP and \fBprev_column\fP fields contain location of the overwritten definition.
T}
_
T{
521
T}	T{
\fBlabel\fP field contains label name.
T}
_
.TE
.sp
Other fields may be present for internal reasons.
.sp
This is documentation for 0.17.1 version of \fI\%Luacheck\fP, a linter for \fI\%Lua\fP\&.
.SH AUTHOR
Peter Melnichenko
.SH COPYRIGHT
2016 - 2016, Peter Melnichenko
.\" Generated by docutils manpage writer.
.