From d27db7246784d6c49ac1873928ee2d3c4963b5d6 Mon Sep 17 00:00:00 2001 From: Paul Dingemans Date: Thu, 24 Oct 2024 19:30:37 +0200 Subject: [PATCH] Updated refs to latest (1.4.0) release (#2846) Co-authored-by: Ktlint Release Workflow --- .../release-latest/docs/install/cli.md | 13 ++- .../docs/install/integrations.md | 6 +- .../release-latest/docs/rules/experimental.md | 73 +++++++++++++ .../release-latest/docs/rules/standard.md | 101 +++++++++++++++--- documentation/snapshot/docs/install/cli.md | 4 +- .../snapshot/docs/install/integrations.md | 6 +- 6 files changed, 177 insertions(+), 26 deletions(-) diff --git a/documentation/release-latest/docs/install/cli.md b/documentation/release-latest/docs/install/cli.md index 726b3bcd15..4adc475974 100644 --- a/documentation/release-latest/docs/install/cli.md +++ b/documentation/release-latest/docs/install/cli.md @@ -12,7 +12,7 @@ All releases of `ktlint` can be downloaded from the [releases](https://github.co A particular version of `ktlint` can be downloaded with next command which also changes the file to an executable in directory `/usr/local/bin`: ```sh title="Download" -curl -sSLO https://github.com/pinterest/ktlint/releases/download/1.3.1/ktlint && chmod a+x ktlint && sudo mv ktlint /usr/local/bin/ +curl -sSLO https://github.com/pinterest/ktlint/releases/download/1.4.0/ktlint && chmod a+x ktlint && sudo mv ktlint /usr/local/bin/ ``` !!! tip "Curl not installed or behind proxy" @@ -168,9 +168,14 @@ ktlint --stdin -F ``` !!! tip "Suppress logging and error output" - Logging output printed to `stdout` can be suppressed by setting `--log-level=none` (see [logging](#logging)). - Output printed to `stderr` can be suppressed in different ways. To ignore all error output, add `2> /dev/null` to the end of the command line. Otherwise, specify a [reporter](#violation-reporting) to write the error output to a file. +Logging output printed to `stdout` can be suppressed by setting `--log-level=none` (see [logging](#logging)). +Output printed to `stderr` can be suppressed in different ways. To ignore all error output, add `2> /dev/null` to the end of the command line. Otherwise, specify a [reporter](#violation-reporting) to write the error output to a file. +If input from `stdin` represents the contents of a file, the file path can be supplied with `stdin-path`. This path is made available for rules to use, the `--format` option will not modify this file. + +```shell title="file path from stdin-path" +ktlint --stdin --stdin-path /path/to/file/Foo.kt +``` ### Git hooks @@ -204,6 +209,6 @@ Options `--stdin` and `--patterns-from-stdin` are mutually exclusive, only one o Microsoft Windows is not able to run the `ktlint` command directly. Ktlint can be run in following ways on Microsoft Windows: -1. Use the `ktlint.bat` batch file provided as part of the [release](https://github.com/pinterest/ktlint/releases/tag/1.3.1). Add the batch file to your `%PATH%` environment variable for easy access +1. Use the `ktlint.bat` batch file provided as part of the [release](https://github.com/pinterest/ktlint/releases/tag/1.4.0). Add the batch file to your `%PATH%` environment variable for easy access 2. Run `ktlint` using Git Bash 3. Run as `java -jar ktlint` diff --git a/documentation/release-latest/docs/install/integrations.md b/documentation/release-latest/docs/install/integrations.md index 688baff975..0fe5ac77ac 100644 --- a/documentation/release-latest/docs/install/integrations.md +++ b/documentation/release-latest/docs/install/integrations.md @@ -56,7 +56,7 @@ See [cli usage](../cli) for arguments that can be supplied to `ktlint`. com.pinterest.ktlint ktlint-cli - 1.3.1 + 1.4.0 @@ -117,7 +117,7 @@ configurations { } dependencies { - ktlint("com.pinterest.ktlint:ktlint-cli:1.3.1") { + ktlint("com.pinterest.ktlint:ktlint-cli:1.4.0") { attributes { attribute(Bundling.BUNDLING_ATTRIBUTE, getObjects().named(Bundling, Bundling.EXTERNAL)) } @@ -167,7 +167,7 @@ The configuration below, defines following task: val ktlint by configurations.creating dependencies { - ktlint("com.pinterest.ktlint:ktlint-cli:1.3.1") { + ktlint("com.pinterest.ktlint:ktlint-cli:1.4.0") { attributes { attribute(Bundling.BUNDLING_ATTRIBUTE, objects.named(Bundling.EXTERNAL)) } diff --git a/documentation/release-latest/docs/rules/experimental.md b/documentation/release-latest/docs/rules/experimental.md index 5c13e752a3..fffb10205d 100644 --- a/documentation/release-latest/docs/rules/experimental.md +++ b/documentation/release-latest/docs/rules/experimental.md @@ -285,3 +285,76 @@ Suppress or disable rule (1) ktlint_standard_square-brackets-spacing = disabled ``` +## When-entry bracing + +Enforce consistent usages of braces inside the when-statement. All when-entries in the when-statement should use braces around their bodies in case at least one when-entry has a multiline body, or when the body is surrounded by braces. + +Braces are helpful for following reasons: + +- Bodies of the when-conditions are all aligned at same column position +- Closing braces helps in separating the when-conditions + +This rule is not incorporated in the Kotlin Coding conventions, nor in the Android Kotlin Styleguide. It is based on similar behavior in enforcing consistent use of braces in if-else statements. As of that the rule is only enabled automatically for code style `ktlint_official`. It can be enabled explicitly for other code styles. + +=== "[:material-heart:](#) Ktlint" + + ```kotlin + val foo1 = + when (bar) { + BAR1 -> "bar1" + BAR2 -> "bar2" + else -> null + } + + val foo2 = + when (bar) { + BAR1 -> { + "bar1" + } + BAR2 -> { + "bar2" + } + else -> { + null + } + } + ``` + +=== "[:material-heart-off-outline:](#) Disallowed" + + ```kotlin + val foo3 = + when (bar) { + BAR1 -> "bar1" + BAR2 -> { + "bar2" + } + else -> null + } + + val foo4 = + when (bar) { + BAR1 -> "bar1" + BAR2 -> + "bar2" + else -> null + } + ``` + +Rule id: `standard:when-entry-spacing` + +Suppress or disable rule (1) +{ .annotate } + +1. Suppress rule in code with annotation below: + ```kotlin + @Suppress("ktlint:standard:when-entry-spacing") + ``` + Enable rule via `.editorconfig` + ```editorconfig + ktlint_standard_when-entry-spacing = enabled + ``` + Disable rule via `.editorconfig` + ```editorconfig + ktlint_standard_when-entry-spacing = disabled + ``` diff --git a/documentation/release-latest/docs/rules/standard.md b/documentation/release-latest/docs/rules/standard.md index dff1aa6858..ceacd1f131 100644 --- a/documentation/release-latest/docs/rules/standard.md +++ b/documentation/release-latest/docs/rules/standard.md @@ -103,6 +103,10 @@ Wraps binary expression at the operator reference whenever the binary expression } ``` +| Configuration setting | ktlint_official | intellij_idea | android_studio | +|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------:|:-------------:|:--------------:| +| `max_line_length`
Maximum length of a (regular) line. This property is ignored in case the `max-line-length` rule is disabled, or when using Ktlint via a third party integration that does not provide this rule. | 140 | `off` | `100` | + Rule id: `standard:binary-expression-wrapping` Suppress or disable rule (1) @@ -306,6 +310,7 @@ The `.` in `java.class` is ignored when wrapping on chain operators. | Configuration setting | ktlint_official | intellij_idea | android_studio | |:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------:|:-------------:|:--------------:| | `ktlint_chain_method_rule_force_multiline_when_chain_operator_count_greater_or_equal_than`
Force wrapping of chained methods in case an expression contains at least the specified number of chain operators. If a chained method contains nested expressions, the chain operators of the inner expression are not taken into account. Use value `unset` (default) to disable this setting. | 4 | 4 | 4 | +| `max_line_length`
Maximum length of a (regular) line. This property is ignored in case the `max-line-length` rule is disabled, or when using Ktlint via a third party integration that does not provide this rule. | 140 | `off` | `100` | Rule id: `standard:chain-method-continuation` @@ -559,6 +564,7 @@ The other code styles allow an infinite amount of parameters on the same line (a | Configuration setting | ktlint_official | intellij_idea | android_studio | |:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------:|:-------------:|:--------------:| | `ktlint_class_signature_rule_force_multiline_when_parameter_count_greater_or_equal_than`
Force wrapping of the parameters of the class signature in case it contains at least the specified number of parameters, even in case the entire class signature would fit on a single line. Use value `unset` to disable this setting. | 1 | `unset` | `unset` | +| `max_line_length`
Maximum length of a (regular) line. This property is ignored in case the `max-line-length` rule is disabled, or when using Ktlint via a third party integration that does not provide this rule. | 140 | `off` | `100` | Rule id: `standard:class-signature` @@ -605,6 +611,10 @@ Enum entry names should be uppercase underscore-separated or upper camel-case se } ``` +| Configuration setting | ktlint_official | intellij_idea | android_studio | +|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------:|:-------------:|:--------------:| +| `ktlint_enum_entry_name_casing`
Choose any of `upper_cases` (an enum entry may only contain uppercases, and underscores, and digits, and dicritics on letters and strokes), `camel_cases` (an enum entry may only contain CamelCase values, including digits, and dicritics on letters and strokes), or `upper_or_camel_case` (allows mixing of uppercase and CamelCase entries as per Kotlin Coding Conventions). | `upper_or_camel_cases` | `upper_or_camel_cases` | `upper_or_camel_cases` | + Rule id: `standard:enum-entry-name-case` Suppress or disable rule (1) @@ -752,7 +762,7 @@ Enforces the parameters of a function literal and the arrow to be written on the If the function literal contains multiple parameters and at least one parameter other than the first parameter starts on a new line than all parameters and the arrow are wrapped to separate lines. -=== "[:material-heart:](#) Ktlint" +=== "[:material-heart:](#) Ktlint (ktlint_official)" ```kotlin val foobar1 = { foo + bar } @@ -769,6 +779,27 @@ If the function literal contains multiple parameters and at least one parameter foo + bar } val foobar5 = { foo: Foo, bar: Bar -> foo + bar } + val foobar6 = + { + foo: Foo, + bar: Bar, + -> + foo + bar + } + + // Assume that the last allowed character is + // at the X character on the right X + val foobar7 = + barrrrrrrrrrrrrr { + fooooooooooooooo: Foo + -> + foo.repeat(2) + } + ``` + +=== "[:material-heart:](#) Ktlint (non ktlint_official)" + + ```kotlin val foobar6 = { foo: Foo, @@ -781,7 +812,7 @@ If the function literal contains multiple parameters and at least one parameter // at the X character on the right X val foobar7 = barrrrrrrrrrrrrr { - fooooooooooooooo: Foo + fooooooooooooooo: Foo -> foo.repeat(2) } @@ -808,6 +839,10 @@ If the function literal contains multiple parameters and at least one parameter } ``` +| Configuration setting | ktlint_official | intellij_idea | android_studio | +|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------:|:-------------:|:--------------:| +| `max_line_length`
Maximum length of a (regular) line. This property is ignored in case the `max-line-length` rule is disabled, or when using Ktlint via a third party integration that does not provide this rule. | 140 | `off` | `100` | + Rule id: `standard:function-literal` Suppress or disable rule (1) @@ -978,6 +1013,10 @@ Rewrites the function signature to a single line when possible (e.g. when not ex .uppercase() ``` +| Configuration setting | ktlint_official | intellij_idea | android_studio | +|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------:|:-------------:|:--------------:| +| `max_line_length`
Maximum length of a (regular) line. This property is ignored in case the `max-line-length` rule is disabled, or when using Ktlint via a third party integration that does not provide this rule. | 140 | `off` | `100` | + Rule id: `standard:function-signature` Suppress or disable rule (1) @@ -1155,10 +1194,11 @@ Indentation formatting - respects `.editorconfig` `indent_size` with no continua !!! note This rule handles indentation for many different language constructs which can not be summarized with a few examples. See the [unit tests](https://github.com/pinterest/ktlint/blob/master/ktlint-ruleset-standard/src/test/kotlin/com/pinterest/ktlint/ruleset/standard/rules/IndentationRuleTest.kt) for more details. -| Configuration setting | ktlint_official | intellij_idea | android_studio | -|:------------------------------------------------------------------------------------------------------------------------------------------|:---------------:|:-------------:|:--------------:| -| `indent_size`
The size of an indentation level when `indent_style` is set to `space`. Use value `unset` to ignore indentation. | 4 | 4 | 4 | -| `indent_style`
Style of indentation. Set this value to `space` or `tab`. | `space` | `space` | `space` | +| Configuration setting | ktlint_official | intellij_idea | android_studio | +|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------:|:-------------:|:--------------:| +| `indent_size`
The size of an indentation level when `indent_style` is set to `space`. Use value `unset` to ignore indentation. | 4 | 4 | 4 | +| `indent_style`
Style of indentation. Set this value to `space` or `tab`. | `space` | `space` | `space` | +| `ij_kotlin_indent_before_arrow_on_new_line`
Indent the arrow in a when-entry if the arrow starts on a new line. Set this value to `true` or `false`. Starting from IDEA version `2024.2` or above this value needs to be set to `true` to maintain compatibility with IDEA formatting. | `false` | `false` | `false` | Rule id: `standard:indent` @@ -1854,7 +1894,9 @@ Rule id: `standard:ktlint-suppression` ## Max line length -Ensures that lines do not exceed the maximum length of a line. This rule does not apply in a number of situations. The `.editorconfig` property `ktlint_ignore_back_ticked_identifier` can be set to ignore identifiers which are enclosed in backticks, which for example is very useful when you want to allow longer names for unit tests. +Ensures that lines do not exceed the maximum length of a line as specified in `.editorconfig` property `max_line_length`. + +This rule does not apply in a number of situations. The `.editorconfig` property `ktlint_ignore_back_ticked_identifier` can be set to ignore identifiers which are enclosed in backticks, which for example is very useful when you want to allow longer names for unit tests. === "[:material-heart:](#) Ktlint" @@ -1889,10 +1931,10 @@ Ensures that lines do not exceed the maximum length of a line. This rule does no ``` -| Configuration setting | ktlint_official | intellij_idea | android_studio | -|:--------------------------------------------------------------------------------------------------------------------|:---------------:|:-------------:|:--------------:| -| `ktlint_ignore_back_ticked_identifier`
Defines whether the backticked identifier (``) should be ignored. | `false` | `false` | `false` | -| `max_line_length`
Maximum length of a (regular) line. | 140 | `off` | `100` | +| Configuration setting | ktlint_official | intellij_idea | android_studio | +|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------:|:-------------:|:--------------:| +| `ktlint_ignore_back_ticked_identifier`
Defines whether the backticked identifier (``) should be ignored. | `false` | `false` | `false` | +| `max_line_length`
Maximum length of a (regular) line. This property is ignored in case the `max-line-length` rule is disabled, or when using Ktlint via a third party integration that does not provide this rule. | 140 | `off` | `100` | Rule id: `standard:max-line-length` @@ -2968,6 +3010,10 @@ Consistent spacing around the function return type. String = "some-result" ``` +| Configuration setting | ktlint_official | intellij_idea | android_studio | +|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------:|:-------------:|:--------------:| +| `max_line_length`
Maximum length of a (regular) line. This property is ignored in case the `max-line-length` rule is disabled, or when using Ktlint via a third party integration that does not provide this rule. | 140 | `off` | `100` | + Rule id: `standard:function-return-type-spacing` Suppress or disable rule (1) @@ -3346,6 +3392,10 @@ Consistent spacing inside the parameter list. ) = "some-result" ``` +| Configuration setting | ktlint_official | intellij_idea | android_studio | +|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------:|:-------------:|:--------------:| +| `max_line_length`
Maximum length of a (regular) line. This property is ignored in case the `max-line-length` rule is disabled, or when using Ktlint via a third party integration that does not provide this rule. | 140 | `off` | `100` | + Rule id: `standard:parameter-list-spacing` Suppress or disable rule (1) @@ -4124,9 +4174,10 @@ All arguments should be on the same line, or every argument should be on a separ ) ``` -| Configuration setting | ktlint_official | intellij_idea | android_studio | -|:----------------------------------------------------------------------------------|:---------------:|:-------------:|:--------------:| -| `ktlint_argument_list_wrapping_ignore_when_parameter_count_greater_or_equal_than` | `unset` | 8 | 8 | +| Configuration setting | ktlint_official | intellij_idea | android_studio | +|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------:|:-------------:|:--------------:| +| `ktlint_argument_list_wrapping_ignore_when_parameter_count_greater_or_equal_than` | `unset` | 8 | 8 | +| `max_line_length`
Maximum length of a (regular) line. This property is ignored in case the `max-line-length` rule is disabled, or when using Ktlint via a third party integration that does not provide this rule. | 140 | `off` | `100` | Rule id: `standard:argument-list-wrapping` @@ -4334,6 +4385,10 @@ Wraps the content receiver list to a separate line regardless of maximum line le fun fooBar() ``` +| Configuration setting | ktlint_official | intellij_idea | android_studio | +|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------:|:-------------:|:--------------:| +| `max_line_length`
Maximum length of a (regular) line. This property is ignored in case the `max-line-length` rule is disabled, or when using Ktlint via a third party integration that does not provide this rule. | 140 | `off` | `100` | + Rule id: `standard:context-receiver-wrapping` Suppress or disable rule (1) @@ -4454,6 +4509,8 @@ Suppress or disable rule (1) Multiline expression on the right hand side of an expression are forced to start on a separate line. Expressions in return statement are excluded as that would result in a compilation error. +Setting `ktlint_function_signature_body_expression_wrapping` of the `function-signature` rule takes precedence when set to `default`. This setting keeps the first line of a multiline expression body on the same line as the end of function signature as long as the max line length is not exceeded. In that case, this rule does not wrap the multiline expression. + === "[:material-heart:](#) Ktlint" ```kotlin @@ -4560,6 +4617,10 @@ When class/function signature doesn't fit on a single line, each parameter must ) ``` +| Configuration setting | ktlint_official | intellij_idea | android_studio | +|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------:|:-------------:|:--------------:| +| `max_line_length`
Maximum length of a (regular) line. This property is ignored in case the `max-line-length` rule is disabled, or when using Ktlint via a third party integration that does not provide this rule. | 140 | `off` | `100` | + Rule id: `standard:parameter-list-wrapping` Suppress or disable rule (1) @@ -4626,6 +4687,10 @@ When a function or class parameter doesn't fit on a single line, wrap the type o ) ``` +| Configuration setting | ktlint_official | intellij_idea | android_studio | +|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------:|:-------------:|:--------------:| +| `max_line_length`
Maximum length of a (regular) line. This property is ignored in case the `max-line-length` rule is disabled, or when using Ktlint via a third party integration that does not provide this rule. | 140 | `off` | `100` | + Rule id: `standard:parameter-wrapping` Suppress or disable rule (1) @@ -4664,6 +4729,10 @@ When a property doesn't fit on a single line, wrap the type or value to a separa val aVariableWithALooooooooooooongName: String ``` +| Configuration setting | ktlint_official | intellij_idea | android_studio | +|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------:|:-------------:|:--------------:| +| `max_line_length`
Maximum length of a (regular) line. This property is ignored in case the `max-line-length` rule is disabled, or when using Ktlint via a third party integration that does not provide this rule. | 140 | `off` | `100` | + Rule id: `standard:property-wrapping` Suppress or disable rule (1) @@ -4762,6 +4831,10 @@ Inserts missing newlines (for example between parentheses of a multi-line functi c) ``` +| Configuration setting | ktlint_official | intellij_idea | android_studio | +|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------:|:-------------:|:--------------:| +| `max_line_length`
Maximum length of a (regular) line. This property is ignored in case the `max-line-length` rule is disabled, or when using Ktlint via a third party integration that does not provide this rule. | 140 | `off` | `100` | + Rule id: `standard:wrapping` Suppress or disable rule (1) diff --git a/documentation/snapshot/docs/install/cli.md b/documentation/snapshot/docs/install/cli.md index 926af784f9..4adc475974 100644 --- a/documentation/snapshot/docs/install/cli.md +++ b/documentation/snapshot/docs/install/cli.md @@ -12,7 +12,7 @@ All releases of `ktlint` can be downloaded from the [releases](https://github.co A particular version of `ktlint` can be downloaded with next command which also changes the file to an executable in directory `/usr/local/bin`: ```sh title="Download" -curl -sSLO https://github.com/pinterest/ktlint/releases/download/1.3.1/ktlint && chmod a+x ktlint && sudo mv ktlint /usr/local/bin/ +curl -sSLO https://github.com/pinterest/ktlint/releases/download/1.4.0/ktlint && chmod a+x ktlint && sudo mv ktlint /usr/local/bin/ ``` !!! tip "Curl not installed or behind proxy" @@ -209,6 +209,6 @@ Options `--stdin` and `--patterns-from-stdin` are mutually exclusive, only one o Microsoft Windows is not able to run the `ktlint` command directly. Ktlint can be run in following ways on Microsoft Windows: -1. Use the `ktlint.bat` batch file provided as part of the [release](https://github.com/pinterest/ktlint/releases/tag/1.3.1). Add the batch file to your `%PATH%` environment variable for easy access +1. Use the `ktlint.bat` batch file provided as part of the [release](https://github.com/pinterest/ktlint/releases/tag/1.4.0). Add the batch file to your `%PATH%` environment variable for easy access 2. Run `ktlint` using Git Bash 3. Run as `java -jar ktlint` diff --git a/documentation/snapshot/docs/install/integrations.md b/documentation/snapshot/docs/install/integrations.md index 688baff975..0fe5ac77ac 100644 --- a/documentation/snapshot/docs/install/integrations.md +++ b/documentation/snapshot/docs/install/integrations.md @@ -56,7 +56,7 @@ See [cli usage](../cli) for arguments that can be supplied to `ktlint`. com.pinterest.ktlint ktlint-cli - 1.3.1 + 1.4.0 @@ -117,7 +117,7 @@ configurations { } dependencies { - ktlint("com.pinterest.ktlint:ktlint-cli:1.3.1") { + ktlint("com.pinterest.ktlint:ktlint-cli:1.4.0") { attributes { attribute(Bundling.BUNDLING_ATTRIBUTE, getObjects().named(Bundling, Bundling.EXTERNAL)) } @@ -167,7 +167,7 @@ The configuration below, defines following task: val ktlint by configurations.creating dependencies { - ktlint("com.pinterest.ktlint:ktlint-cli:1.3.1") { + ktlint("com.pinterest.ktlint:ktlint-cli:1.4.0") { attributes { attribute(Bundling.BUNDLING_ATTRIBUTE, objects.named(Bundling.EXTERNAL)) }