Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Support partial formatting #2631

Merged
merged 4 commits into from
Apr 23, 2024
Merged

Support partial formatting #2631

merged 4 commits into from
Apr 23, 2024

Conversation

paul-dingemans
Copy link
Collaborator

Description

Allows API consumers like the 'ktlint-intellij-plugin' to format a block of code inside the given code (for example a file) without autocorrect the given code entirely.

The start offset of the node on which a rule can detect a lint violation should be inside the range which is to be formatted. This has some unexpected side effects for some rules. In most cases it is to be expected that the user won't notice those side effects. And if it happens, the most likely way the user responds is widening the range which is to be formatted, and try to format again.

For example, the given code might contain the when-statement below:

   // code with lint violations

    when(foobar) {
        FOO -> "Single line"
        BAR ->
            """
            Multi line
            """.trimIndent()
        else -> null
    }

   // more code with lint violations

The blank-line-between-when-conditions rule requires blank lines to be added between the conditions. If the when-keyword above is included in the range which is to be formatted then the blank lines before the conditions are added. If only the when-conditions itself are selected, but not the when-keyword, then the blank lines are not added.

This unexpected behavior is a side effect of the way the partial formatting is implemented currently. The side effects can be prevented by delaying the decision to autocorrect as late as possible and the exact offset of the error is known. This however would cause a breaking change, and needs to wait until Ktlint V2.x.

Closes #2629

Checklist

Before submitting the PR, please check following (checks which are not relevant may be ignored):

  • Commit message are well written. In addition to a short title, the commit message also explain why a change is made.
  • At least one commit message contains a reference Closes #<xxx> or Fixes #<xxx> (replace<xxx> with issue number)
  • Tests are added
  • KtLint format has been applied on source code itself and violations are fixed
  • PR title is short and clear (it is used as description in the release changelog)
  • PR description added (background information)

Documentation is updated. See difference between snapshot and release documentation

  • Snapshot documentation in case documentation is to be released together with a code change
  • Release documentation in case documentation is related to a released version of ktlint and has to be published as soon as the change is merged to master

Allows API consumers like the 'ktlint-intellij-plugin' to format a block of code inside the given code (for example a file) without autocorrect the given code entirely.

The start offset of the node on which a rule can detect a lint violation should be inside the range which is to be formatted. This has some unexpected side effects for some rules. In most cases it is to be expected that the user won't notice those side effects. And if it happens, the most likely way the user responds is widening the range which is to be formatted, and try to format again.

For example, the given code might contain the when-statement below:
```
   // code with lint violations

    when(foobar) {
        FOO -> "Single line"
        BAR ->
            """
            Multi line
            """.trimIndent()
        else -> null
    }

   // more code with lint violations
```
The `blank-line-between-when-conditions` rule requires blank lines to be added between the conditions. If the when-keyword above is included in the range which is to be formatted then the blank lines before the conditions are added. If only the when-conditions itself are selected, but not the when-keyword, then the blank lines are not added.

This unexpected behavior is a side effect of the way the partial formatting is implemented currently. The side effects can be prevented by delaying the decision to autocorrect as late as possible and the exact offset of the error is known. This however would cause a breaking change, and needs to wait until Ktlint V2.x.
Allows API consumers like the 'ktlint-intellij-plugin' to format a block of code inside the given code (for example a file) without autocorrect the given code entirely.

The start offset of the node on which a rule can detect a lint violation should be inside the range which is to be formatted. This has some unexpected side effects for some rules. In most cases it is to be expected that the user won't notice those side effects. And if it happens, the most likely way the user responds is widening the range which is to be formatted, and try to format again.

For example, the given code might contain the when-statement below:
```
   // code with lint violations

    when(foobar) {
        FOO -> "Single line"
        BAR ->
            """
            Multi line
            """.trimIndent()
        else -> null
    }

   // more code with lint violations
```
The `blank-line-between-when-conditions` rule requires blank lines to be added between the conditions. If the when-keyword above is included in the range which is to be formatted then the blank lines before the conditions are added. If only the when-conditions itself are selected, but not the when-keyword, then the blank lines are not added.

This unexpected behavior is a side effect of the way the partial formatting is implemented currently. The side effects can be prevented by delaying the decision to autocorrect as late as possible and the exact offset of the error is known. This however would cause a breaking change, and needs to wait until Ktlint V2.x.

Closes #2629
@paul-dingemans paul-dingemans added this to the 1.3.0 milestone Apr 11, 2024
@paul-dingemans paul-dingemans modified the milestones: 1.4.0, 1.3.0 Apr 23, 2024
@paul-dingemans paul-dingemans changed the title 2629 partial format Support partial formatting Apr 23, 2024
@paul-dingemans paul-dingemans merged commit fd083b6 into master Apr 23, 2024
22 checks passed
@paul-dingemans paul-dingemans deleted the 2629-partial-format branch April 23, 2024 09:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Suport partial formatting of code
1 participant