Skip to content

Latest commit

 

History

History
220 lines (162 loc) · 9.5 KB

linter_attributes.rst

File metadata and controls

220 lines (162 loc) · 9.5 KB
Raw

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 :doc:`linter method documentation <linter_methods>`.

cmd (mandatory)

A tuple or callable that returns a tuple, containing the command line (with arguments) used to lint.

  • If cmd is None, it is assumed the plugin overrides the run 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 :ref:`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 :ref:`regex` 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 :. If prefix is @, this attribute is ignored (but may not be omitted). Otherwise, if this is =, the setting value is joined with name 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 :ref:`regex` 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 is False, the linter output is split into lines (using str.splitlines and each line is matched against regex pattern.
  • If multiline is True, the linter output is iterated over using re.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 :ref:`regex` 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 :ref:`split_match <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 :ref:`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.