1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
|
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.
.. _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 standard globals ``"max"``
``globals`` Array of strings or field definition map ``{}``
``new_globals`` Array of strings or field definition map (Do not overwrite)
``read_globals`` Array of strings or field definition map ``{}``
``new_read_globals`` Array of strings or field definition map (Do not overwrite)
``not_globals`` Array of strings ``{}``
``operators`` 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 :ref:`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:
.. code-block:: lua
:linenos:
std = "min"
ignore = {"212"}
.. _custom_stds:
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:
.. code-block:: lua
:linenos:
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:
.. code-block:: lua
:linenos:
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:
.. code-block:: lua
:linenos:
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.
.. code-block:: lua
:linenos:
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:
.. code-block:: lua
:linenos:
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``:
.. code-block:: lua
:linenos:
std = "min"
ignore = {"212"}
files["src/dir"] = {enable = {"212"}}
files["src/dir/**/*_special.lua"] = {ignore = {"212"}}
Note that ``files`` table supports autovivification, so that
.. code-block:: lua
files["src/dir"].enable = {"212"}
and
.. code-block:: lua
files["src/dir"] = {enable = {"212"}}
are equivalent.
The configs are processed in order of increasing specificity. ``globals`` and ``read_globals`` will add to the set of allowed globals. ``not_globals`` can be used to remove previously allowed globals; ``new_globals`` and ``new_read_globals`` can be used to override the set of globals, wiping all previously allowed ``globals`` or ``read_globals`` respectively, and replacing them with new entries.
Default per-path std overrides
------------------------------
``luacheck`` uses a set of default per-path overrides:
.. code-block:: lua
:linenos:
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"
files["**/config.ld"].std = "+ldoc"
These are added to the global ``std`` specified in the config file.
Each of these can be overriden by setting a different ``std`` value for the corresponding key in ``files``.
Setting ``std`` on the commandline removes these default overrides.
|
