Ktlint

https://pinterest.github.io/ktlint/latest/
Admin
Ktlint is an opinionated Kotlin linter and formatter that enforces Kotlin coding conventions with...
Tokens:46,199
Snippets:615
Trust Score:8.3
Update:6 months ago
Show doc for...
Tokens:
Raw
### Ktlint Import Layout Configuration Examples

Source: https://pinterest.github.io/ktlint/latest/rules/standard?q=

Provides examples of configuring the `ij_kotlin_imports_layout` setting for different import ordering strategies in Ktlint.

```plaintext
ij_kotlin_imports_layout=* # alphabetical with capital letters before lower case letters (e.g. Z before a), no blank lines
```

```plaintext
ij_kotlin_imports_layout=*,java.**,javax.**,kotlin.**,^ # default IntelliJ IDEA style, same as alphabetical, but with "java", "javax", "kotlin" and alias imports in the end of the imports list
```

```plaintext
ij_kotlin_imports_layout=android.**,|,^org.junit.**,kotlin.io.Closeable.*,|,*,^ # custom imports layout
```

--------------------------------

### Install git pre-push hook

Source: https://pinterest.github.io/ktlint/latest/install/cli

Installs the predefined git pre-push hook to automatically validate lint errors before a push.

```bash
ktlint installGitPrePushHook
```

--------------------------------

### Install Ktlint with Homebrew

Source: https://pinterest.github.io/ktlint/latest/quick-start

Use this command to install the latest ktlint release via Homebrew. Ensure Homebrew is installed on your system.

```bash
brew install ktlint
```

--------------------------------

### Install ktlint with MacPorts

Source: https://pinterest.github.io/ktlint/latest/install/cli

Installs ktlint on macOS using the MacPorts package manager.

```bash
port install ktlint
```

--------------------------------

### Install git pre-commit hook

Source: https://pinterest.github.io/ktlint/latest/install/cli

Installs the predefined git pre-commit hook to automatically validate lint errors before a commit.

```bash
ktlint installGitPreCommitHook
```

--------------------------------

### Download ktlint with curl

Source: https://pinterest.github.io/ktlint/latest/install/cli

Downloads a specific version of ktlint, makes it executable, and moves it to /usr/local/bin. Ensure you have curl installed.

```bash
curl -sSLO https://github.com/pinterest/ktlint/releases/download/1.8.0/ktlint && chmod a+x ktlint && sudo mv ktlint /usr/local/bin/
```

--------------------------------

### Ktlint Property Naming Examples

Source: https://pinterest.github.io/ktlint/latest/rules/standard?q=

Shows examples of correct and incorrect property naming in Kotlin, including constants, mutable properties, and class properties. It highlights naming conventions for immutability and the use of backticks for keywords.

```kotlin
val foo1 = Foo() // In case developers want to tell that Foo is mutable
val FOO1 = Foo() // In case developers want to tell that Foo is deeply immutable

const val FOO_BAR = "FOO-BAR" // By definition deeply immutable

var foo2: Foo = Foo() // By definition not immutable

class Bar {
    val foo1 = "foo1" // Class properties always start with lowercase, const is not allowed

    const val FOO_BAR = "FOO-BAR" // By definition deeply immutable

    var foo2: Foo = Foo() // By definition not immutable

    // Backing property
    private val _elementList = mutableListOf<Element>()
    val elementList:
        get() = _elementList

    companion object {
        val foo1 = Foo() // In case developer want to communicate that Foo is mutable
        val FOO1 = Foo() // In case developer want to communicate that Foo is deeply immutable
    }
}

var `package` = "foo" // Any keyword is allowed when wrapped between backticks
```

```kotlin
const val fooBar = "FOO-BAR" // By definition deeply immutable

var FOO2: Foo = Foo() // By definition not immutable

class Bar {
    val FOO_BAR = "FOO-BAR" // Class properties always start with lowercase, const is not allowed

    // Incomplete backing property as public property 'elementList1' is missing
    private val _elementList1 = mutableListOf<Element>()

    // Invalid backing property as '_elementList2' is not a private property
    val _elementList2 = mutableListOf<Element>()
    val elementList2:
        get() = _elementList2
}
```

--------------------------------

### Clear Comment Placement Example

Source: https://pinterest.github.io/ktlint/latest/faq?q=

Shows a clear comment placement within an else block, removing ambiguity.

```kotlin
if (someCondition) {
    doTrue()
} else {
    // comment
    doFalse()
}

```

--------------------------------

### Unclear Comment Placement Example

Source: https://pinterest.github.io/ktlint/latest/faq?q=

Demonstrates an ambiguous comment placement after a closing brace, making it unclear which block it applies to.

```kotlin
if (someCondition) {
    doTrue()
}
else {
    doFalse()
}

```

--------------------------------

### Function Literal Formatting Examples

Source: https://pinterest.github.io/ktlint/latest/rules/standard?q=

Demonstrates various valid and disallowed function literal formats according to Ktlint rules, including single-line and multi-line parameter arrangements.

```kotlin
val foobar1 = { foo + bar }
```

```kotlin
val foobar2 =
    {
        foo + bar
    }
```

```kotlin
val foobar3 =
    {
        foo: Foo ->
        foo.repeat(2)
    }
```

```kotlin
val foobar4 =
    {
        foo: Foo, bar: Bar ->
        foo + bar
    }
```

```kotlin
val foobar5 = { foo: Foo, bar: Bar -> foo + bar }
```

```kotlin
val foobar6 =
    {
        foo: Foo,
        bar: Bar,
        ->
        foo + bar
    }
```

```kotlin
// Assume that the last allowed character is
// at the X character on the right           X
val foobar7 =
    barrrrrrrrrrrrrr {
        fooooooooooooooo: Foo
        ->
        foo.repeat(2)
    }
```

--------------------------------

### Mixed Function Literal Formatting

Source: https://pinterest.github.io/ktlint/latest/rules/standard?q=

Presents mixed function literal formatting examples, combining single-line parameters with multi-line bodies and demonstrating alignment.

```kotlin
val foobar3 =
    {
        foo: Foo ->
        foo.repeat(2)
    }
```

```kotlin
val foobar6 =
    { foo: Foo,
      bar: Bar ->
        foo + bar
    }
```

```kotlin
// Assume that the last allowed character is
// at the X character on the right           X
val foobar7 =
    barrrrrrrrrrrrrr { fooooooooooooooo: Foo ->
        foo.repeat(2)
    }
```

--------------------------------

### Ktlint Function Naming Examples

Source: https://pinterest.github.io/ktlint/latest/rules/standard?q=

Demonstrates allowed and disallowed function naming conventions in Kotlin, including the use of backticks for keywords and special characters.

```kotlin
fun foo() {}

fun fooBar() {}

fun `fun`() {} // Any keyword is allowed when wrapped between backticks
```

```kotlin
@Test
fun `Some name`() {}

@Test
fun do_something() {}
```

```kotlin
fun Foo() {}
fun Foo_Bar() {}
fun `Some name`() {}
fun do_something() {}
```

--------------------------------

### Unclear Comment Placement Example

Source: https://pinterest.github.io/ktlint/latest/faq

Demonstrates a comment placed ambiguously after a closing brace, making it unclear which block it applies to.

```kotlin
if (someCondition) {
    doTrue()
} // comment
else {
    doFalse()
}

```

--------------------------------

### Import Ordering in Ktlint

Source: https://pinterest.github.io/ktlint/latest/rules/standard?q=

Ktlint ensures consistent import ordering. This example shows disallowed import arrangements.

```kotlin
import com.bar.Bar
import com.foo.Foo
import org.foo.bar.FooBar
import java.util.concurrent.ConcurrentHashMap
```

```kotlin
import com.bar.Bar
import java.util.concurrent.ConcurrentHashMap
import org.foo.bar.FooBar
import com.foo.Foo
```

--------------------------------

### Ktlint Allowed Chain Method Formatting

Source: https://pinterest.github.io/ktlint/latest/rules/standard?q=

Examples of method chains that adhere to Ktlint's formatting rules for alignment and continuation.

```kotlin
val foo1 =
    listOf(1, 2, 3).
        filter { it > 2 }!!.
        takeIf { it > 2 }.
        map {
            it * it
        }?.
        map {
            it * it
        }
val foo2 =
    listOf(1, 2, 3)
        .filter {
            it > 2
        }
        .map {
            2 * it
        }
        ?.map {
            2 * it
        }
val foo3 = 
    foo()
    .bar().map {
        it.foobar()
    }
val foo4 =
    """
    Some text
    """.trimIndent().foo()
        .bar()
```

--------------------------------

### Ktlint Rule Dependency Example

Source: https://pinterest.github.io/ktlint/latest/faq?q=

Illustrates a scenario where one rule depends on another. The 'string-template-indent' rule requires 'multiline-expression-wrapping' to be loaded.

```java
java.lang.IllegalStateException: Skipping rule(s) which are depending on a rule which is not loaded. Please check if you need to add additional rule sets before creating an issue.
  - Rule with id 'RuleId(value=standard:string-template-indent)' requires rule with id 'RuleId(value=standard:multiline-expression-wrapping)' to be loaded

```

--------------------------------

### Function Start of Body Spacing in Kotlin

Source: https://pinterest.github.io/ktlint/latest/rules/standard?q=

Maintains consistent spacing before the start of a function body in Kotlin. This rule is dependent on the `ktlint_function_signature_body_expression_wrapping` setting.

```kotlin
// In case `ktlint_function_signature_body_expression_wrapping` is set to `default` or `multiline`
fun foo1() = "some-result"

// In case `ktlint_function_signature_body_expression_wrapping` is set to `always`
fun foo2() =
    "some-result"

fun foo3() {
    // do something
}

// In case `ktlint_function_signature_body_expression_wrapping` is set to `default` or `multiline`
fun bar1(): String = "some-result"

// In case `ktlint_function_signature_body_expression_wrapping` is set to `always`
fun bar2(): String =
    "some-result"

fun bar3(): String {
    doSomething()
    return "some-result"
}

```

```kotlin
fun foo1()= "some-result"

fun foo2()
    = "some-result"

fun foo3()
{
    // do something
}

fun bar1(): String= "some-result"

fun bar2(): String
    = "some-result"

fun bar3(): String
{
    return "some-result"
}

```

--------------------------------

### Ktlint String Template Indentation

Source: https://pinterest.github.io/ktlint/latest/faq?q=

Example of a string template that benefits from multiline expression wrapping for correct indentation.

```kotlin
val foo = """
    some text
   """.trimIndent()

```

--------------------------------

### Ktlint Package Naming Examples

Source: https://pinterest.github.io/ktlint/latest/rules/standard?q=

Illustrates valid and invalid package naming conventions according to Ktlint rules. Package names must follow a specific pattern of lowercase letters and digits separated by dots.

```kotlin
package foo
package foo.bar
```

```kotlin
package Foo
package foo.Foo
package `foo bar`
package foo.`foo bar`
```

--------------------------------

### Verify ktlint releases (0.32.0+)

Source: https://pinterest.github.io/ktlint/latest/install/cli

Verifies the PGP signature of ktlint releases starting from version 0.32.0. Imports the public key from Ubuntu Key Server.

```bash
curl -sS "https://keyserver.ubuntu.com/pks/lookup?op=get&search=0xadbc987d1a7b91db6b0aaa81995efbf4a3d20beb" | gpg --import && gpg --verify ktlint.asc
```

--------------------------------

### Class Signature Formatting with Max Line Length

Source: https://pinterest.github.io/ktlint/latest/rules/standard?q=

Illustrates how Ktlint wraps class signatures when they exceed the `max_line_length`. This example assumes a specific line length limit is in effect.

```kotlin
// Assume that the last allowed character is
// at the X character on the right           X
class Foo0

// Entire class signature does not fit on single line
class Foo1(
    aVeryLonggggggggggggggggggggggg: Any
)

// Entire class signature does fit on single line
class Foo2(a: Any)

// Entire class signature does not fit on single line
class Foo3(
    aVeryLonggggggggggggggg: Any,
    b: Any
)

// Entire class signature does fit on single line
class Foo4(a: Any, b: Any)

// Entire class signature does fit on single line
class Foo5(@Foo a: Any, b: Any, c: Any)

// Entire class signature does fit on single line
class Foo6(a: Any, b: Any, c: Any) :
    FooBar(a, c)

// Entire class signature (without constructor invocation) does fit on single line
class Foo7 :
    FooBar(
        "bar1",
        "bar2"
    ) {
    // body
}

// Entire class signature (without constructor invocation) does fit on single line
class Foo8(val bar1: Bar, val bar2: Bar) :
    FooBar(
        bar1,
        bar2
    ) {
    // body
}

// Entire class signature (without constructor invocation) does not fit on single line
class Foo9(
    val aVeryLonggggggggggggggg: Bar,
    val bar2: Bar
) : FooBar(
    bar1,
    bar2
) {
    // body
}

class Foo10(val bar1: Bar, val bar2: Bar) :
    FooBar(
        bar1,
        bar2
    ),
    BarFoo1,
    BarFoo2 {
    // body
}

class Foo11
constructor(
    val bar1: Bar,
    val bar2: Bar
) : FooBar(bar1, bar2),
    BarFoo1,
    BarFoo2 {
    // body
}
```

--------------------------------

### Ktlint CLI Output with Custom Rule Violation

Source: https://pinterest.github.io/ktlint/latest/api/custom-rule-set

Example output from the Ktlint CLI when a custom rule is violated. This shows the file, line, column, and the specific violation message.

```text
18:13:21.026 [main] DEBUG com.pinterest.ktlint.internal.RuleSetsLoader - JAR ruleset provided with path "/../ktlint/ktlint-ruleset-template/build/libs/ktlint-ruleset-template.jar"
18:13:21.241 [main] DEBUG com.pinterest.ktlint.Main - Discovered reporter with "baseline" id.
18:13:21.241 [main] DEBUG com.pinterest.ktlint.Main - Discovered reporter with "checkstyle" id.
18:13:21.241 [main] DEBUG com.pinterest.ktlint.Main - Discovered reporter with "json" id.
18:13:21.242 [main] DEBUG com.pinterest.ktlint.Main - Discovered reporter with "html" id.
18:13:21.242 [main] DEBUG com.pinterest.ktlint.Main - Discovered reporter with "plain" id.
18:13:21.242 [main] DEBUG com.pinterest.ktlint.Main - Discovered reporter with "sarif" id.
18:13:21.242 [main] DEBUG com.pinterest.ktlint.Main - Initializing "plain" reporter with {verbose=false, color=false, color_name=DARK_GRAY}
[DEBUG] Rule with id 'standard:max-line-length' should run after the rule with id 'trailing-comma'. However, the latter rule is not loaded and is allowed to be ignored. For best results, it is advised load the rule.
[DEBUG] Rules will be executed in order below (unless disabled):
           - standard:filename, 
           - standard:final-newline, 
           - standard:chain-wrapping, 
           - standard:colon-spacing, 
           - standard:comma-spacing, 
           - standard:comment-spacing, 
           - standard:curly-spacing, 
           - standard:dot-spacing, 
           - standard:import-ordering, 
           - standard:keyword-spacing, 
           - standard:modifier-order, 
           - standard:no-blank-line-before-rbrace, 
           - standard:no-consecutive-blank-lines, 
           - standard:no-empty-class-body, 
           - standard:no-line-break-after-else, 
           - standard:no-line-break-before-assignment, 
           - standard:no-multi-spaces, 
           - standard:no-semi, 
           - standard:no-trailing-spaces, 
           - standard:no-unit-return, 
           - standard:no-unused-imports, 
           - standard:no-wildcard-imports, 
           - standard:op-spacing, 
           - standard:parameter-list-wrapping, 
           - standard:paren-spacing, 
           - standard:range-spacing, 
           - standard:string-template, 
           - custom:no-var, 
           - standard:indent, 
           - standard:max-line-length
`text test.kt:1:1: Unexpected var, use val instead (cannot be auto-corrected)`
18:13:21.893 [main] DEBUG com.pinterest.ktlint.Main - 872ms / 1 file(s) / 1 error(s)
```

--------------------------------

### Configure EditorConfig Overrides

Source: https://pinterest.github.io/ktlint/latest/api/custom-integration

Specify editorConfigOverride to set properties that take precedence over .editorconfig files. This example sets indentation style to spaces and size to 4.

```kotlin
val ktLintRuleEngine =
  KtLintRuleEngine(
    ruleProviders = KTLINT_API_CONSUMER_RULE_PROVIDERS,
    editorConfigOverride = EditorConfigOverride.from(
      INDENT_STYLE_PROPERTY to IndentConfig.IndentStyle.SPACE,
      INDENT_SIZE_PROPERTY to 4
    )
  )

```

--------------------------------

### Block Comment Star Alignment in Kotlin

Source: https://pinterest.github.io/ktlint/latest/rules/standard?q=

Ensures that lines in a block comment starting with a '*' are aligned with the '*' in the opening comment delimiter.

```kotlin
/*
 * This comment is formatted well.
 */

```

```kotlin
/*
      * This comment is not formatted well.
    */

```

--------------------------------

### Format Block Comments Correctly

Source: https://pinterest.github.io/ktlint/latest/rules/standard?q=

Requires block comments to start and end on lines that contain no other code elements. This rule prevents comments from being on the same line as code or other comments.

```kotlin
// Some comment 1
val foo1 = "foo1"
val foo2 = "foo" // Some comment
val foo3 = { /* no-op */ }
```

```kotlin
/* Some comment 1 */ val foo1 = "foo1"
val foo2 = "foo" /* Block comment instead of end-of-line comment */
val foo3 = "foo" /* Some comment
                  * with a newline
                  */
```

--------------------------------

### Disallow leading empty lines in method blocks

Source: https://pinterest.github.io/ktlint/latest/rules/standard?q=

This rule enforces that method blocks do not start with an empty line. Ensure the first line of code follows the opening brace immediately.

```kotlin
fun bar() {
   val a = 2
}

```

```kotlin
fun bar() {

   val a = 2
}

```

--------------------------------

### Wrapping: Multi-line Function Call Arguments

Source: https://pinterest.github.io/ktlint/latest/rules/standard

When arguments in a function call span multiple lines, each argument should be on a new line, and the closing parenthesis should align with the start of the line containing the function call.

```kotlin
val foo = 
    foo(
        a,
        b,
        c,
    )
```

```kotlin
val foo = foo(
    a,
    b,
    c)
```

--------------------------------

### Ktlint Function Signature with Multiline Body Expression Wrapping

Source: https://pinterest.github.io/ktlint/latest/rules/standard?q=

Illustrates function signatures when `ktlint_function_signature_body_expression_wrapping` is set to `multiline`. The body expression starts on a new line if it's multiline, or if it doesn't fit on the signature line.

```kotlin
// Given that the function signature has to be written as a single line
// function signature and that the function has a single line body expression
// that fits on the same line as the function signature.
fun someFunction(a: Any, b: Any): String = "some-result".uppercase()

// Given that the function signature has to be written as a multiline
// function signature and that the function has a single line body expression
// that fits on the same line as the function signature.
fun someFunction(
    a: Any,
    b: Any
): String = "some-result".uppercase()

// Given that the function signature has to be written as a single line
// function signature and that the function has a multiline body expression
fun someFunction(a: Any, b: Any): String =
    "some-result"
         .uppercase()

// Given that the function signature has to be written as a multiline
// function signature and that the function has a multiline body expression
fun someFunction(
    a: Any,
    b: Any
): String =
    "some-result"
       .uppercase()


```

--------------------------------

### Create Code instance from file

Source: https://pinterest.github.io/ktlint/latest/api/custom-integration

Use this to create a Code instance from an existing file path. Ensure the file exists.

```kotlin
val code = Code.fromFile(
    File("/some/path/to/file")
)
```

--------------------------------

### Create KtLintRuleEngine Instance

Source: https://pinterest.github.io/ktlint/latest/api/custom-integration?q=

Instantiate the KtLintRuleEngine, which is the central entry point for custom integrations. It's recommended to create a single instance for the application's lifetime for performance benefits due to caching.

```kotlin
val ktLintRuleEngine = 
  KtLintRuleEngine(
    ruleProviders = KTLINT_API_CONSUMER_RULE_PROVIDERS,
  )
```

--------------------------------

### Build Custom Ruleset with Gradle

Source: https://pinterest.github.io/ktlint/latest/api/custom-rule-set

Use this Gradle command to build your custom ruleset JAR. Ensure you are in the `ktlint-ruleset-template` directory.

```bash
cd ktlint-ruleset-template/
../gradlew build
```

--------------------------------

### Clone and Build Ktlint Project

Source: https://pinterest.github.io/ktlint/latest/contributing/overview

Clone the Ktlint repository and build the project locally. The `./gradlew tasks` command displays available build, test, and run options.

```bash
git clone https://github.com/pinterest/ktlint && cd ktlint
./gradlew tasks # shows how to build, test, run, etc. project
```

--------------------------------

### Clone and Build Ktlint Project

Source: https://pinterest.github.io/ktlint/latest/contributing/overview?q=

Clone the Ktlint repository and build the project locally. The `./gradlew tasks` command displays available build, test, and run options.

```bash
git clone https://github.com/pinterest/ktlint && cd ktlint
./gradlew tasks # shows how to build, test, run, etc. project

```

--------------------------------

### Emitting a LintError That Cannot Be Autocorrected

Source: https://pinterest.github.io/ktlint/latest/api/custom-integration

Example of how to emit a LintError when it cannot be autocorrected. This is done by setting the canBeAutoCorrected parameter to false.

```kotlin
emit(node.startOffset, "some detail message", false)
```

--------------------------------

### Build Ktlint Ruleset Project with Gradle

Source: https://pinterest.github.io/ktlint/latest/api/custom-rule-set?q=

Builds the ktlint-ruleset-template project using Gradle. Ensure you are in the ktlint-ruleset-template directory.

```bash
$ cd ktlint-ruleset-template/
$ ../gradlew build
```

--------------------------------

### Load EditorConfig Defaults from File

Source: https://pinterest.github.io/ktlint/latest/api/custom-integration

Configure editorConfigDefaults by loading from a specified path to an .editorconfig file or directory. Ensure propertyTypes are derived from the same rule providers.

```kotlin
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(),
    )
  )

```

--------------------------------

### Run Ktlint CLI with Custom Ruleset

Source: https://pinterest.github.io/ktlint/latest/api/custom-rule-set

Execute Ktlint from the command line, specifying the path to your custom ruleset JAR and the file to analyze. Use `--log-level=debug` for detailed output.

```bash
ktlint -R build/libs/ktlint-ruleset-template.jar --log-level=debug --relative test.kt
```

--------------------------------

### Create a Kotlin file violating a custom rule

Source: https://pinterest.github.io/ktlint/latest/api/custom-rule-set

Create a `test.kt` file with code that violates your custom rule (e.g., `custom:no-var`) to test its functionality.

```bash
echo 'var v = 0' > test.kt
```

--------------------------------

### RuleAutocorrectApproveHandler Interface

Source: https://pinterest.github.io/ktlint/latest/api/custom-integration

Details the `RuleAutocorrectApproveHandler` interface for custom rule autocorrection, including new method signatures and usage examples.

```APIDOC
## RuleAutocorrectApproveHandler

### Description
Providers of custom rules are encouraged to implement the `RuleAutocorrectApproveHandler` interface to enable fine-grained control over autocorrection of individual `LintErrors`.

### Method
`beforeVisitChildNodes` (and `afterVisitChildNodes`)

### Endpoint
N/A (Interface definition)

### Parameters
#### Request Parameters (for `emit` lambda)
- **offset** (Int) - The starting offset of the lint error.
- **errorMessage** (String) - The detailed error message.
- **canBeAutoCorrected** (Boolean) - Indicates if the error can potentially be autocorrected.

### Request Example (Autocorrect Allowed)
```java
emit(node.startOffset, "some detail message", true)
   .ifAutocorrectAllowed {
       // Autocorrect the LintError
   }
```

### Request Example (Autocorrect Not Allowed)
```java
emit(node.startOffset, "some detail message", false)
```

### Response
#### AutocorrectDecision
- **ALLOW_AUTOCORRECT**: Indicates that autocorrection is permitted.
- **NO_AUTOCORRECT**: Indicates that autocorrection should not be performed.
```

--------------------------------

### Proxy configuration for curl/wget

Source: https://pinterest.github.io/ktlint/latest/install/cli

If you are behind a proxy, configure the http_proxy and https_proxy environment variables before running the download command.

```bash
http_proxy=http://proxy-server:port https_proxy=http://proxy-server:port curl -sL ...
```

--------------------------------

### Ktlint Disallowed Chain Method Formatting

Source: https://pinterest.github.io/ktlint/latest/rules/standard?q=

Examples of method chains that violate Ktlint's formatting rules for alignment and continuation.

```kotlin
val foo1 =
    listOf(1, 2, 3)
        .filter { it > 2 }!!
        .takeIf { it > 2 }
        .map {
            it * it
        }?.map {
            it * it
        }
val foo2 =
    listOf(1, 2, 3)
        .filter {
            it > 2
        }.map {
            2 * it
        }?.map {
            2 * it
        }
val foo3 =
    foo().bar().map {
        it.foobar()
    }
val foo4 =
    """
    Some text
    """.trimIndent().foo().bar()
```

--------------------------------

### Disable All Rules in a Rule Set

Source: https://pinterest.github.io/ktlint/latest/rules/configuration-ktlint

Disable all rules within a specific rule set. For example, to disable all rules from the 'standard' rule set.

```properties
[*.{kt,kts}]
ktlint_standard = disabled

```

--------------------------------

### Opt-in to Experimental Rules in Ktlint

Source: https://pinterest.github.io/ktlint/latest/contributing/guidelines?q=

New rules must implement `Rule.Experimental` to be opt-in. Remove the marker when the rule is stable.

```java
New rules have to implement the `Rule.Experimental` interface so that the rule will only be run for user who have opted in to use experimental rules. Once the rule is stable, the marker interface `Rule.Experimental` can be removed.
```

--------------------------------

### KDoc Wrapping in Kotlin

Source: https://pinterest.github.io/ktlint/latest/rules/standard?q=

Ensures KDoc comments start and end on lines that do not contain other code elements. This promotes readability for documentation comments.

```kotlin
/** Some KDoc comment 1 */
val foo1 = "foo1"

```

```kotlin
/** Some KDoc comment 1 */ val foo1 = "foo1"
val foo2 = "foo2" /** Some KDoc comment
                   * with a newline
                   */

```

--------------------------------

### Class Signature Formatting with Max Line Length (Simplified)

Source: https://pinterest.github.io/ktlint/latest/rules/standard?q=

Presents a simplified view of class signature formatting concerning `max_line_length`, focusing on cases where the signature fits or does not fit on a single line.

```kotlin
// Assume that the last allowed character is
// at the X character on the right           X
class Foo0()

class Foo6(a: Any, b: Any, c: Any) : FooBar(a, c)

// Entire class signature (without constructor invocation) does fit on single line
class Foo7 : FooBar(
    "bar1",
    "bar2",
) {
    // body
}
```

--------------------------------

### Function Type Modifier Spacing in Ktlint

Source: https://pinterest.github.io/ktlint/latest/rules/standard?q=

Ktlint enforces a single whitespace between the modifier list and the function type. This example shows disallowed formatting.

```kotlin
val foo: suspend () -> Unit = {}

suspend fun bar(baz: suspend () -> Unit) = baz()
```

```kotlin
val foo: suspend() -> Unit = {}

suspend fun bar(baz: suspend   () -> Unit) = baz()
```

--------------------------------

### Enable Kotlin Development Versions

Source: https://pinterest.github.io/ktlint/latest/contributing/guidelines?q=

Use the `-PkotlinDev` flag to enable development versions of Kotlin. This is useful for testing against the latest Kotlin features.

```bash
-PkotlinDev
```

--------------------------------

### Autocorrecting a LintError in Ktlint

Source: https://pinterest.github.io/ktlint/latest/api/custom-integration

Example of how to emit a LintError and allow autocorrection if the emit lambda returns AutocorrectDecision.ALLOW_AUTOCORRECT. This code should be used when a LintError is detected and can be autocorrected.

```kotlin
emit(node.startOffset, "some detail message", true)
   .ifAutocorrectAllowed {
       // Autocorrect the LintError
   }
```

--------------------------------

### Function Signature and Body Wrapping in Ktlint

Source: https://pinterest.github.io/ktlint/latest/rules/standard?q=

Demonstrates how Ktlint handles wrapping for function signatures and single-line body expressions. Use 'always' for consistent formatting.

```kotlin
fun someFunction(a: Any, b: Any): String =
    "some-result".uppercase()
```

```kotlin
fun functionWithAVeryLongName(
    a: Any,
    b: Any
): String =
    "some-result"
        .uppercase()
```

--------------------------------

### Ktlint Disallowed Function Signatures

Source: https://pinterest.github.io/ktlint/latest/rules/standard?q=

Examples of function signatures that violate Ktlint's formatting rules, particularly concerning line length and parameter wrapping.

```kotlin
// Assume that the last allowed character is
// at the X character on the right           X
fun foooooooo(
    a: Any,
    b: Any,
    c: Any,
): String {
    // body
}

// Assume that the last allowed character is
// at the X character on the right           X
fun bar(a: Any, b: Any, c: Any): String {
    // body
}

// When wrapping of body is set to 'default'.
// Assume that the last allowed character is
// at the X character on the right           X
fun f(a: Any, b: Any): String = "some-result"
    .uppercase()

// When wrapping of body is set to 'multiline'
// or 'always'.
// Assume that the last allowed character is
// at the X character on the right           X
fun f(a: Any, b: Any): String =
    "some-result"
        .uppercase()


```

```kotlin
// Assume that the last allowed character is
// at the X character on the right           X
fun foooooooo(a: Any, b: Any, c: Any): String {
    // body
}

// Assume that the last allowed character is
// at the X character on the right           X
fun bar(
    a: Any,
    b: Any,
    c: Any
): String {
    // body
}

// When wrapping of body is set to 'default'.
// Assume that the last allowed character is
// at the X character on the right           X
fun f(a: Any, b: Any): String =
    "some-result"
        .uppercase()

// When wrapping of body is set to 'multiline'
// or 'always'.
// Assume that the last allowed character is
// at the X character on the right           X
fun f(a: Any, b: Any): String = "some-result"
    .uppercase()


```

--------------------------------

### Create KtLintRuleEngine Instance

Source: https://pinterest.github.io/ktlint/latest/api/custom-integration

Instantiate the KtLintRuleEngine once for your application's lifetime to benefit from caching and improved performance. Ensure ruleProviders are configured.

```kotlin
val ktLintRuleEngine =
  KtLintRuleEngine(
    ruleProviders = KTLINT_API_CONSUMER_RULE_PROVIDERS,
  )

```

--------------------------------

### Create Code instance from snippet

Source: https://pinterest.github.io/ktlint/latest/api/custom-integration

Use this to create a Code instance from a string snippet. Set `script` to `true` if the snippet should be treated as a Kotlin script.

```kotlin
val code = Code.fromSnippet(
    """
    val code = "some-code"
    """.trimIndent()
)
```

--------------------------------

### If-Else Bracing Style in Ktlint

Source: https://pinterest.github.io/ktlint/latest/rules/standard?q=

Ktlint requires all branches of an if-else statement to be wrapped in curly braces if at least one branch is. This example shows disallowed formatting.

```kotlin
fun foo(value: Int) {
    if (value > 0) {
        doSomething()
    } else if (value < 0) {
        doSomethingElse()
    } else {
        doSomethingElse2()
    }
}
```

```kotlin
fun foo(value: Int) {
    if (value > 0)
        doSomething()
    else if (value < 0) {
        doSomethingElse()
    } else
        doSomethingElse2()
}
```

--------------------------------

### Create a file violating a custom rule

Source: https://pinterest.github.io/ktlint/latest/api/custom-rule-set?q=

Creates a simple Kotlin file 'test.kt' that violates the custom 'custom:no-var' rule, which is intended to disallow the use of 'var'.

```bash
$ echo 'var v = 0' > test.kt
```

--------------------------------

### Set Ktlint Code Style in .editorconfig

Source: https://pinterest.github.io/ktlint/latest/rules/code-styles

Configure the desired Ktlint code style by setting the `ktlint_code_style` property in your `.editorconfig` file. This example shows how to set the style to `intellij_idea`.

```properties
[*.{kt,kts}]
ktlint_code_style = intellij_idea # or android_studio or ktlint_official (default)

```

--------------------------------

### Define Rule Providers

Source: https://pinterest.github.io/ktlint/latest/api/custom-integration?q=

Configure the KtLintRuleEngine with a set of RuleProviders. Each provider is a lambda that supplies instances of specific rules, allowing for custom rules or reuse of standard KtLint rules.

```kotlin
val KTLINT_API_CONSUMER_RULE_PROVIDERS = 
  setOf(
    // Can provide custom rules
    RuleProvider { NoVarRule() },
    // but also reuse rules from KtLint rulesets
    RuleProvider { IndentationRule() },
  )
```

--------------------------------

### Verify ktlint releases (up to 0.31.0)

Source: https://pinterest.github.io/ktlint/latest/install/cli

Verifies the PGP signature of ktlint releases up to version 0.31.0. Imports the public key from keybase.io.

```bash
curl -sS https://keybase.io/shyiko/pgp_keys.asc | gpg --import && gpg --verify ktlint.asc
```

--------------------------------

### Run Ktlint CLI with a Custom Ruleset

Source: https://pinterest.github.io/ktlint/latest/api/custom-rule-set?q=

Executes the Ktlint CLI, specifying a custom ruleset JAR and applying it to a Kotlin file. This command will report violations found by both standard and custom rules.

```bash
$ ktlint -R build/libs/ktlint-ruleset-template.jar --log-level=debug --relative test.kt
```

--------------------------------

### Disallowed multiline expression wrapping

Source: https://pinterest.github.io/ktlint/latest/rules/standard?q=

Ktlint enforces that multiline expressions on the right-hand side of an assignment must start on a new line. Expressions within return statements are an exception.

```kotlin
val foo =
    foo(
        parameterName =
            "The quick brown fox "
                .plus("jumps ")
                .plus("over the lazy dog"),
    )
```

```kotlin
val foo = foo(
    parameterName = "The quick brown fox "
        .plus("jumps ")
        .plus("over the lazy dog"),
)
```

--------------------------------

### Load EditorConfig Defaults from File

Source: https://pinterest.github.io/ktlint/latest/api/custom-integration?q=

Specify editorConfigDefaults for KtLintRuleEngine by loading them from an .editorconfig file or directory. Ensure propertyTypes are derived from the same rule providers used by the engine.

```kotlin
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(),
    )
  )
```

--------------------------------

### Invoke format function (Ktlint 1.3+)

Source: https://pinterest.github.io/ktlint/latest/api/custom-integration?q=

The preferred format function starting from Ktlint 1.3. It allows deciding which LintErrors to autocorrect via a lambda. Rules must implement `RuleAutocorrectApproveHandler` for this to work.

```kotlin
val formattedCode = 
    ktLintRuleEngine
      .format(code) { lintError ->
          if (lintError.canBeAutoCorrected) {
              // Return AutocorrectDecision.ALLOW_AUTOCORRECT to execute the autocorrect of this lintError if this is supported by the rule.
              // Return AutocorrectDecision.NO_AUTOCORRECT if the LintError should not be corrected even if is supported by the rule.
          } else {
              // In case the LintError can not be autocorrected, the return value of the lambda will be ignored.
              // For clarity reasons it is advised to return AutocorrectDecision.NO_AUTOCORRECT in case the LintError can not be autocorrected.
              AutocorrectDecision.NO_AUTOCORRECT
          }
      }
```

--------------------------------

### Logging Configuration

Source: https://pinterest.github.io/ktlint/latest/api/custom-integration?q=

Information on Ktlint's logging mechanism, which uses `io.github.oshai:kotlin-logging`.

```APIDOC
## Logging

### Description
Ktlint utilizes the `io.github.oshai:kotlin-logging` library, which acts as a wrapper for `slf4j`. This allows API consumers to integrate their preferred logging framework and configure it as needed.

### Configuration Example
The basic API consumer includes an example using `org.slf4j:slf4j-simple` as the logging provider. This configuration demonstrates how to set logging levels, such as displaying `DEBUG` level logs for all classes except for a specific class that only shows `WARN` level logs.
```

--------------------------------

### Multiple reporters with output file

Source: https://pinterest.github.io/ktlint/latest/install/cli

Specifies multiple reporters, writing the plain reporter output to the console and the checkstyle reporter output to a specified XML file.

```bash
ktlint --reporter=plain --reporter=checkstyle,output=ktlint-report-in-checkstyle-format.xml
```

--------------------------------

### Disallowed Backing Property Naming in Ktlint

Source: https://pinterest.github.io/ktlint/latest/rules/standard?q=

Ktlint enforces specific naming conventions for backing properties. Private backing properties should typically start with an underscore, and the corresponding public property/function must be defined.

```kotlin
class Bar {
    // Backing property as normal class member
    private val _elementList = mutableListOf<Element>()
    val elementList: List<Element>
        get() = _elementList

    // Backing property defined in companion object
    val elementList2: List<Element>
        get() = _elementList2

    companion object {
        private val _elementList2 = mutableListOf<Element>()
    }
}

```

```kotlin
class Bar {
    // Incomplete backing property as public property 'elementList1' is missing
    private val _elementList1 = mutableListOf<Element>()

    // Invalid backing property as '_elementList2' is not a private property
    val _elementList2 = mutableListOf<Element>()
    val elementList2: List<Element>
        get() = _elementList2
}

```

--------------------------------

### ktlint with file globs

Source: https://pinterest.github.io/ktlint/latest/install/cli?q=

Specifies files and directories to validate using .gitignore pattern syntax. Globs are processed left-to-right, and '!' negates a pattern. Hidden folders are skipped.

```bash
# Check all '.kt' files in 'src/' directory, but ignore files ending with 'Test.kt':
ktlint 'src/**/*.kt' '!src/**/*Test.kt'

# Check all '.kt' files in 'src/' directory, but ignore 'generated' directory and its subdirectories:
ktlint 'src/**/*.kt' '!src/**/generated/**'
```

--------------------------------

### Ktlint Logging Configuration

Source: https://pinterest.github.io/ktlint/latest/api/custom-integration

Information on Ktlint's logging mechanism, which uses `io.github.oshai:kotlin-logging` (an SLF4J wrapper), and how API consumers can configure their preferred logging framework.

```APIDOC
## Logging

### Description
Ktlint utilizes `io.github.oshai:kotlin-logging`, a wrapper for SLF4J, for its logging needs. API consumers have the flexibility to choose and configure their preferred logging framework.

### Configuration Example
An example is provided with `org.slf4j:slf4j-simple` as the logging provider, demonstrating a customized configuration that sets the logging level to `DEBUG` for all classes except for one specific class, which is configured to log only at the `WARN` level.
```

--------------------------------

### Disable Ktlint for Generated Code

Source: https://pinterest.github.io/ktlint/latest/faq

Add this glob pattern to your .editorconfig file to disable Ktlint for specific directories containing generated code. Note potential issues with globs starting with '**' followed by multiple directories.

```editorconfig
[some/path/to/generated/code/**/*]
ktlint = disabled


```

--------------------------------

### Disable Ktlint for Generated Code

Source: https://pinterest.github.io/ktlint/latest/faq?q=

Prevent Ktlint from running on generated code by adding a glob pattern to your .editorconfig file and setting `ktlint = disabled`. Note potential issues with globs starting with `**` followed by multiple directories.

```properties
[some/path/to/generated/code/**/*]
ktlint = disabled

```

--------------------------------

### Enable Ktlint Experimental Rules

Source: https://pinterest.github.io/ktlint/latest/rules/experimental?q=

To enable all experimental rules from all rule sets, set 'ktlint_experimental=enabled' in your .editorconfig file for Kotlin files.

```properties
[*.{kt,kts}]
ktlint_experimental=enabled

```

--------------------------------

### Binary Expression Wrapping in Kotlin

Source: https://pinterest.github.io/ktlint/latest/rules/standard?q=

Demonstrates how binary expressions are wrapped at the operator when they exceed line length. Inner expressions are wrapped if they still do not fit after outer wrapping.

```kotlin
fun foo() {
    // Assume that the last allowed character is
    // at the X character on the right                       X
    if ((leftHandSideExpression && rightHandSideExpression) ||
        (
            leftHandSideLongExpression &&
                rightHandSideExpression
        )
    ) {
        // do something
    }
}

```

```kotlin
fun foo() {
    // Assume that the last allowed character is
    // at the X character on the right                       X
    if ((leftHandSideExpression && rightHandSideExpression) ||
        (leftHandSideLongExpression && rightHandSideExpression)
    ) {
        // do something
    }
}

```

--------------------------------

### Class Signature Formatting with Force Multiline

Source: https://pinterest.github.io/ktlint/latest/rules/standard

Shows class signature formatting when `ktlint_class_signature_rule_force_multiline_when_parameter_count_greater_or_equal_than` is set, forcing multiline even if the signature fits on a single line.

```kotlin
class Foo0()

class Foo6(a: Any, b: Any, c: Any) : FooBar(a, c)

// Entire class signature (without constructor invocation) does fit on single line
class Foo7 : FooBar(
    "bar1",
    "bar2",
) {
    // body
}

```

--------------------------------

### Enable All Rules in a Rule Set

Source: https://pinterest.github.io/ktlint/latest/rules/configuration-ktlint

Enable all rules within a specific rule set. This is useful for enabling experimental rules.

```properties
[*.{kt,kts}]
ktlint_experimental = enabled

```

```properties
[*.{kt,kts}]
ktlint_custom-rule-set = enabled

```

--------------------------------

### Ktlint Class Signature Formatting (ktlint_official)

Source: https://pinterest.github.io/ktlint/latest/rules/standard?q=

Demonstrates default Ktlint formatting for class signatures, where parameters are wrapped by default. Assumes `max_line_length` is not exceeded.

```kotlin
class Foo0

class Foo1(
    a: Any,
)

class Foo2(
    a: Any,
    b: Any,
)

class Foo3(
    @Foo a: Any,
    b: Any,
    c: Any,
)

class Foo4(
    a: Any,
    b: Any,
    c: Any,
) : FooBar(a, c)

class Foo5 :
    FooBar(
        "bar1",
        "bar2",
    ) {
    // body
}

class Foo6(
    val bar1: Bar,
    val bar2: Bar,
) : FooBar(
        bar1,
        bar2,
    ) {
    // body
}

class Foo7(
    val bar1: Bar,
    val bar2: Bar,
) : FooBar(
        bar1,
        bar2,
    ),
    BarFoo1,
    BarFoo2 {
    // body
}

class Foo8
    constructor(
        val bar1: Bar,
        val bar2: Bar,
    ) : FooBar(bar1, bar2),
        BarFoo1,
        BarFoo2 {
        // body
    }
```

--------------------------------

### File path from stdin-path

Source: https://pinterest.github.io/ktlint/latest/install/cli

When reading from stdin, this option supplies the file path. This path is made available for rules to use, and the --format option will not modify this file.

```bash
ktlint --stdin --stdin-path /path/to/file/Foo.kt
```

--------------------------------

### Define Ktlint Rule Providers

Source: https://pinterest.github.io/ktlint/latest/api/custom-integration

Configure the KtLintRuleEngine with a set of RuleProviders. This can include custom rules or standard rules provided by KtLint.

```kotlin
val KTLINT_API_CONSUMER_RULE_PROVIDERS =
  setOf(
    // Can provide custom rules
    RuleProvider { NoVarRule() },
    // but also reuse rules from KtLint rulesets
    RuleProvider { IndentationRule() },
  )

```

--------------------------------

### Specify files with globs

Source: https://pinterest.github.io/ktlint/latest/install/cli

Uses .gitignore pattern syntax to specify which files and directories to validate. Globs are processed left to right, and '!' negates a pattern.

```bash
# Check all '.kt' files in 'src/' directory, but ignore files ending with 'Test.kt':
ktlint 'src/**/*.kt' '!src/**/*Test.kt'
```

```bash
# Check all '.kt' files in 'src/' directory, but ignore 'generated' directory and its subdirectories:
ktlint 'src/**/*.kt' '!src/**/generated/**'
```

--------------------------------

### Wrap Context Receiver List - Ktlint Disallowed

Source: https://pinterest.github.io/ktlint/latest/rules/standard?q=

Demonstrates Ktlint's disallowed formatting for context receivers, showing cases where wrapping is always applied or applied when line length is exceeded.

```kotlin
// Always wrap regardless of whether max line length is set
context(Foo)
fun fooBar()

// Wrap each context receiver to a separate line when the
// entire context receiver list does not fit on a single line
context(
    Fooooooooooooooooooo1,
    Foooooooooooooooooooooooooooooo2
)
fun fooBar()

// Wrap each context receiver to a separate line when the
// entire context receiver list does not fit on a single line.
// Also, wrap each of it projection types in case a context
// receiver does not fit on a single line after it has been
// wrapped.
context(
    Foooooooooooooooo<
        Foo,
        Bar,
        >
)
fun fooBar()

```

```kotlin
// Should be wrapped regardless of whether max line length is set
context(Foo) fun fooBar()

// Should be wrapped when the entire context receiver list does not
// fit on a single line
context(Fooooooooooooooooooo1, Foooooooooooooooooooooooooooooo2)
fun fooBar()

// Should be wrapped when the entire context receiver list does not
// fit on a single line. Also, it should wrap each of it projection
// type in case a context receiver does not fit on a single line 
after it has been wrapped.
context(Foooooooooooooooo<Foo, Bar>)
fun fooBar()

```

--------------------------------

### Format from stdin and write to stdout

Source: https://pinterest.github.io/ktlint/latest/install/cli

Reads input from stdin, formats it, and writes the formatted code to stdout. Violations are printed to stderr.

```bash
ktlint --stdin -F
```
Tokens:
Raw