Configuration

Configuring the tool through a configuration file allows you to specify paths to directories containing rule files and to define styles from these files.

Configuration File

The configuration file is expected to be named .lins.cfg or lins.cfg and uses a syntax similar to Windows’ .ini files. The tool determines which configuration file to use through a search that follows these parameters:

• The path to the current working directory is traversed in ascending order until a configuration file is found or the root directory is reached. Additionally, the search algorithm descends into any directory named .lins/ on its way to the root.

• If the directory traversal yields no results, the tool determines the path to the user’s configuration directory which defaults to

  • $XDG_CONFIG_HOME—if defined, otherwise /home/<user>/.config on Unix systems and

  • C:\Users\<user>\.config on Windows systems.

  The lins/ subdirectory is appended to the path and searched for a configuration file.

Upon finding a configuration file, the search is aborted and the file contents are parsed.

You are also able to explicitly specify a configuration file by setting the LINS_CFG environment variable to the full path of the configuration file. This method takes precedence over any file found through the search outlined above.

Note

The absolute path of the selected configuration file is reported at runtime.

Note

You can disable the use of a configuration file by specifying the option --no-cfg.

Below is an example of a configuration file. The following sections break down and explain its contents.

[RuleDirs]
"/path/to/rules/foo"
baz="/path/to/rules/bar"

[Style]
name = mainstyle
default = true

rule = foo
[Except]
FooRule1
FooRule2

rule = baz

[Style]
name = secondarystyle

rule = baz
[Only]
BazRule

Rule Directories

[RuleDirs]
"/path/to/rules/foo"
baz="/path/to/rules/bar"

Rule directories are specified in the RuleDirs section. The directories are not traversed recursively so only rule files residing on the top level are added. Entries are separated by line breaks and may explicitly be assigned a label by using the = character. Entries without an explicit label will use the name of their lowest-level directory.

Note

Relative paths are computed w.r.t. the path of the configuration file.

Styles

Rule files may be grouped together to form a style. Styles are important for a few reasons:

• Flexibility—by adding an abstraction layer between the rule files and the user, you gain flexibility.

• File structure—since you explicitly select which rule files should be included in a particular style, the tool imposes no requirements on how the rule files are organized.

• Ease of use—when linting, the user only specifies a style and is not affected by the style’s maintainer removing and adding rule files.

Perhaps Marketing uses a different style than R&D when writing documents. For example, two styles may share the same core rule set but one may enforce the passive voice while the other enforces the active voice.

Defining a Style

Each style is defined in its own Style section. Immediately following the section title, the style’s name is expected. Additionally, the default keyword may be used to select this as the default style. Unless another style is specified using the --style option, the default style will automatically be selected when invoking the tool. Additionally, you are able to overwrite the default specifier and assign this property to another style by setting the LINS_DEFAULT_STYLE environment variable.

[Style]
name = mainstyle
default = true

To assign rules to a style the rule keyword is used together with a target label (defined in the RuleDirs section). This will include all rules defined in the label’s target directory (unless the Except or Only sections are used).

rule = baz

Except and Only

The Except and Only sections applies to the latest rule keyword and are mutually exclusive, i.e. a rule can make use of either the Except section or the Only section, but not both.

The purpose of each section is straight-forward:

• The Except section includes all rule files except the ones listed in the section.

rule = foo
[Except]
FooRule1
FooRule2

• The Only section only includes the rule files listed in the section.

rule = baz
[Only]
BazRule

In both cases, the lists consist of filenames (case sensitive and without the extension) with one entry per line.

Environment Variables

Environment variables offer yet another way of configuring the tool in a persistent manner.

• LINS_CFG—full path to a configuration file. Provided the specified file exists, this file takes precedence over any file located through the regular search method described in Configuration File.

• LINS_DEFAULT_STYLE—name of the default style. This name is case sensitive and must match a style defined in the active configuration file. If these criteria are met, this takes precedence over any other default style.