This page is based on Ktlint
0.49.x which has to be released. Most concepts are also applicable for
Ktlint Rule Engine¶
Ktlint Rule Engine is the central entry point for custom integrations with the
Ktlint API. See basic API Consumer for a basic example on how to invoke the
Ktlint Rule Engine. This example also explains how the logging of the
Ktlint Rule Engine can be configured to your needs.
KtLintRuleEngine instance only needs to be created once for the entire lifetime of your application. Reusing the same instance results in better performance due to caching.
KtLintRuleEngine must be configured with at least one
RuleProvider is a lambda which upon request of the
KtLintRuleEngine provides a new instance of a specific rule. You can either provide any of the standard rules provided by KtLint or with your own custom rules, or with a combination of both.
Editor config: defaults & overrides¶
When linting and formatting files, the
KtlintRuleEngine takes the
.editorconfig file(s) into account which are found on the path to the file. A property which is specified in the
editorConfigOverride property of the
KtLintRuleEngine takes precedence above the value of that same property in the
.editorconfig file. The
editorConfigDefaults property of the
KtLintRuleEngine can be used to specify the fallback values for properties in case that property is not defined in the
.editorconfig file (or in the
editorConfigOverride property takes an
EditorConfigProperty as key. KtLint defines several such properties, but they can also be defined as part of a custom rule.
editorConfigDefaults property is more cumbersome to define as it is based directly on the data format of the
ec4j library which is used for parsing the
The defaults can be loaded from a path or a directory. If a path to a file is specified, the name of the file does not necessarily have to end with
.editorconfig. If a path to a directory is specified, the directory should contain a file with name
.editorconfig. Note that the
propertyTypes have to be derived from the same collection of rule providers that are specified in the
ruleProviders property of the
EditorConfigDefaults property can also be specified programmatically as is shown below:
Lint & format¶
KtLintRuleEngine has been defined, it is ready to be invoked for each file or code snippet that has to be linted or formatted. The the
format functions take a
Code instance as parameter. Such an instance can either be created from a file
true to handle the snippet as Kotlin script):
lint function is invoked with a lambda which is called each time a
LintError is found and does not return a result.
format function is invoked with a lambda which is called each time a
LintError is found and returns the formatted code as result. Note that the
LintError should be inspected for errors that could not be autocorrected.
Ktlint uses the
io.github.microutils:kotlin-logging which is a
slf4j wrapper. As API consumer you can choose which logging framework you want to use and configure that framework to your exact needs. The basic API Consumer contains an example with
org.slf4j:slf4j-simple as logging provider and a customized configuration which shows logging at
DEBUG level for all classes except one specific class which only displays logging at