Linter Attributes¶
All linter plugins must be subclasses of SublimeLinter.lint.Linter
.
The Linter class provides the attributes and methods necessary to make linters
work within SublimeLinter.
The Linter class is designed to allow interfacing with most linter executables/libraries through the configuration of class attributes. Some linters, however, will need to do more work to set up the environment for the linter executable, or may do the linting directly in the linter plugin itself. In that case, refer to the linter method documentation.
cmd (mandatory)¶
A tuple or callable that returns a tuple, containing the command line (with arguments) used to lint.
- If
cmd
isNone
, it is assumed the plugin overrides therun
method. - A
${file}
argument will be replaced with the full filename, which allows you to guarantee that certain arguments will be passed after the filename. - When tempfile_suffix is set, the filename will be the temp filename.
- A
${args}
argument will be replaced with the arguments built from the linter settings, which allows you to guarantee that certain arguments will be passed at the end of the argument list.
default_type¶
Usually the error
and warning
named capture groups in the regex (mandatory)
classify the problems.
If the linter output does not provide information which can be captured with those groups,
this attribute is used to determine how to classify the linter error.
The value should be SublimeLinter.lint.ERROR
or SublimeLinter.lint.WARNING
.
The default value is SublimeLinter.lint.ERROR
.
defaults¶
Set this attribute to a dict of setting names and values to provide defaults for the linter’s settings.
The most important setting is "selector"
, which specifies the scopes for which the linter is run.
If a setting will be passed as an argument to the linter executable, you may specify the format of the argument here and the setting will automatically be passed as an argument to the executable. The format specification is as follows:
<prefix><name><joiner>[<sep>[+]]
- prefix – Either
@
,-
or--
. - name – The name of the setting.
- joiner – Either
=
or:
. Ifprefix
is@
, this attribute is ignored (but may not be omitted). Otherwise, if this is=
, the setting value is joined withname
by=
and passed as a single argument. If:
,name
and the value are passed as separate arguments. - sep – If the argument accepts a list of values,
sep
specifies the character used to delimit the list (usually,
). - + – If the setting can be a list of values,
but each value must be passed as a separate argument,
terminate the setting with
+
.
After the format is parsed, the prefix and suffix are removed and the setting key is replaced with name
.
Note
When building the list of arguments to pass to the linter,
if the setting value is falsy
(None
, zero, False
, or an empty sequence),
the argument is not passed to the linter.
error_stream¶
Some linters report problem on stdout
, some on stderr
.
By default SublimeLinter listens for both. If that’s wrong you can set this
to SublimeLinter.lint.STREAM_STDOUT
or SublimeLinter.lint.STREAM_STDERR
.
Note however, it’s important to capture errors generated by the linter itself,
for example a bad command line argument or some internal error.
Usually linters will report their own errors on stderr
.
To ensure you capture both regular linter output and internal linter errors,
you need to determine on which stream the linter writes reports and errors.
line_col_base¶
This attribute is a tuple that defines the number base used by linters in reporting line and column numbers.
In general, most linters use one-based line numbers and column numbers, so the default value is (1, 1)
.
If a linter uses zero-based line numbers or column numbers,
the linter class should define this attribute accordingly.
Note
For example, if the linter reports one-based line numbers but zero-based column numbers,
the value of this attribute should be (1, 0)
.
multiline¶
This attribute determines whether the regex (mandatory) attribute parses multiple lines.
The linter may output multiline error messages, but if regex
only parses single lines,
this attribute should be False
(the default).
- If
multiline
isFalse
, the linter output is split into lines (usingstr.splitlines
and each line is matched againstregex
pattern. - If
multiline
isTrue
, the linter output is iterated over usingre.finditer
until no more matches are found.
Note
It is important that you set this attribute correctly; it does more than just
add the re.MULTILINE
flag when it compiles the regex
pattern.
name¶
Usually the name of the linter is derived from the name of the class. If that doesn’t work out, you can also set it explicitly with this attribute.
re_flags¶
If you wish to add custom re flags
that are used when compiling the regex (mandatory) pattern,
you may specify them here.
For example, if you want the pattern to be case-insensitive, you could do this:
re_flags = re.IGNORECASE
Note
These flags can also be included within the regex
pattern itself.
It’s up to you which technique you prefer.
regex (mandatory)¶
A python regular expression pattern used to extract information from the linter’s output. The pattern must contain at least the following named capture groups:
Name | Description |
---|---|
line | The line number on which the problem occurred |
message | The description of the problem |
If your pattern doesn’t have these groups you must override the split_match method to provide those values yourself.
In addition to the above capture groups, the pattern should contain the following named capture groups when possible:
Name | Description |
---|---|
col | The column number where the error occurred, or a string whose length provides the column number |
error | If this is not empty, the error will be marked as an error by SublimeLinter |
warning | If this is not empty, the error will be marked as a warning by SublimeLinter |
near | If the linter does not provide a column number but mentions a name, match the name with this capture group and SublimeLinter will attempt to highlight that name. Enclosing single or double quotes will be stripped, you may include them in the capture group. If the linter provides a column number, you may still use this capture group and SublimeLinter will highlight that text (stripped of quotes) exactly. |
code | The corresponding error code given by the linter, if supported. |
tempfile_suffix¶
This attribute configures the behaviour of linter executables that cannot receive input from stdin
.
If the linter executable require input from a file,
SublimeLinter can automatically create a temp file from the current code
and pass that file to the linter executable.
To enable automatic temp file creation,
set this attribute to the suffix of the temp file name (with or without a leading .
).
File-only linters¶
Some linters can only work from an actual disk file, because they rely on an
entire directory structure that cannot be realistically be copied to a temp directory.
In such cases, you can mark a linter as file-only by setting tempfile_suffix to -
.
File-only linters will only run on files that have not been modified since their last save, ensuring that what the user sees and what the linter executable sees is in sync.
word_re¶
If a linter reports a column position, SublimeLinter highlights the nearest word at that point.
By default, SublimeLinter uses the regex pattern r'^([-\w]+)'
to determine what is a word.
You can customize the regex used to highlight words by setting this attribute to a pattern string or a compiled regex.