Custom integration¶
Ktlint Rule Engine¶
The 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.
The 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.
val ktLintRuleEngine =
KtLintRuleEngine(
ruleProviders = KTLINT_API_CONSUMER_RULE_PROVIDERS,
)
Rule provider¶
The KtLintRuleEngine
must be configured with at least one RuleProvider
. A 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.
val KTLINT_API_CONSUMER_RULE_PROVIDERS =
setOf(
// Can provide custom rules
RuleProvider { NoVarRule() },
// but also reuse rules from KtLint rulesets
RuleProvider { IndentationRule() },
)
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).
val ktLintRuleEngine =
KtLintRuleEngine(
ruleProviders = KTLINT_API_CONSUMER_RULE_PROVIDERS,
editorConfigOverride = EditorConfigOverride.from(
INDENT_STYLE_PROPERTY to IndentConfig.IndentStyle.SPACE,
INDENT_SIZE_PROPERTY to 4
)
)
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.
The 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 .editorconfig
file.
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 KtLintRuleEngine
.
val ktLintRuleEngine =
KtLintRuleEngine(
ruleProviders = KTLINT_API_CONSUMER_RULE_PROVIDERS,
editorConfigDefaults = EditorConfigDefaults.load(
path = Paths.get("/some/path/to/editorconfig/file/or/directory"),
propertyTypes = KTLINT_API_CONSUMER_RULE_PROVIDERS.propertyTypes(),
)
)
StandardRuleSetProvider().getRuleProviders()
.
The EditorConfigDefaults
property can also be specified programmatically as is shown below:
val ktLintRuleEngine =
KtLintRuleEngine(
ruleProviders = KTLINT_API_CONSUMER_RULE_PROVIDERS,
editorConfigDefaults = EditorConfigDefaults(
org.ec4j.core.model.EditorConfig
.builder()
// .. add relevant properties
.build()
)
)
Lint & format¶
Once the 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 lint
and format
functions take a Code
instance as parameter. Such an instance can either be created from a file
script
to true
to handle the snippet as Kotlin script):
The lint
function is invoked with a lambda which is called each time a LintError
is found and does not return a result.
ktLintRuleEngine
.lint(codeFile) { lintError ->
// handle
}
The 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.
val formattedCode =
ktLintRuleEngine
.format(codeFile) { lintError ->
// handle
}
Logging¶
Ktlint uses the io.github.oshai: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 WARN
level.