5a47c541f064da127d6426163be86ab39c8ac2e1 - dart_style

commit	5a47c541f064da127d6426163be86ab39c8ac2e1	[log] [tgz]
author	Bob Nystrom <rnystrom@google.com>	Thu Mar 07 14:33:18 2024 -0800
committer	GitHub <noreply@github.com>	Thu Mar 07 14:33:18 2024 -0800
tree	76027cf75ef6f42bdcb727f5ef6abb290092152e
parent	df74d1f89a7dc96c97ecd279199f75e0422802fb [diff]

Preserve newlines (or lack of) in collections with line comments. (#1420)

Preserve newlines (or lack of) in collections with line comments.

Large collection literals often have some internal structure that the
author wants to highlight by having multiple elements on one line, sort
of like a matrix.

The old style has a sort of hacky but in practice useful heuristic to
enable that: if a collection literal contains a line comment, then the
newlines (or lack of) between pairs of elements are preserved:

https://github.com/dart-lang/dart_style/wiki/FAQ#why-does-the-formatter-mess-up-my-collection-literals

This implements that same heuristic in the new style. The behavior is
slightly different in the new style. In the old style, an argument list
can be split in a variety of ways:

```dart
// 1. All on one line:
f(argument1, argument2, argument3, argument4)

// 2. Split into two lines at after any particular argument:
f(argument1, argument2, argument3,
argument4)
f(argument1, argument2,
argument3, argument4)
f(argument1,
argument2, argument3, argument4)

// 3. Split every argument into its own line:
f(
argument1,
argument2,
argument3,
argument4)
```

It uses that same logic for the elements on a single line in a
collection formatted with this rule. That kicks in if the authored code
has all of the elements on one line but they don't actually fit. In that
case, the formatter will still split them to try to fit. With the old
style, it may use any of the above approaches to try to fit.

In the new style, argument lists don't support splitting between an
arbitrary pair of elements like (2) above. So you just get:

```dart
// 1. All on one line:
f(argument1, argument2, argument3, argument4)

// 3. Split every argument into its own line:
f(
argument1,
argument2,
argument3,
argument4,
)
```

Likewise for collection literals containing a line comment. If all of
the elements on a single line don't fit, it will split all of them onto
their own lines instead of trying to split just between one pair of
them.

Longer-term, I intend to support opting regions of code out of
formatting completely. I expect users will use that for large
matrix-like collections where they want to control both line splitting
and aligning things into columns. So the specific behavior of this hack
won't matter as much.

But it *is* a widely relied on rule today, so this part preserves it.

Co-authored-by: Nate Bosch <nbosch@google.com>

11 files changed

tree: 76027cf75ef6f42bdcb727f5ef6abb290092152e

README.md

The dart_style package defines an automatic, opinionated formatter for Dart code. It replaces the whitespace in your program with what it deems to be the best formatting for it. Resulting code should follow the Dart style guide but, moreso, should look nice to most human readers, most of the time.

The formatter handles indentation, inline whitespace, and (by far the most difficult) intelligent line wrapping. It has no problems with nested collections, function expressions, long argument lists, or otherwise tricky code.

The formatter turns code like this:

// BEFORE formatting
if (tag=='style'||tag=='script'&&(type==null||type == TYPE_JS
      ||type==TYPE_DART)||
  tag=='link'&&(rel=='stylesheet'||rel=='import')) {}

into:

// AFTER formatting
if (tag == 'style' ||
  tag == 'script' &&
      (type == null || type == TYPE_JS || type == TYPE_DART) ||
  tag == 'link' && (rel == 'stylesheet' || rel == 'import')) {}

The formatter will never break your code—you can safely invoke it automatically from build and presubmit scripts.

Style fixes

The formatter can also apply non-whitespace changes to make your code consistently idiomatic. You must opt into these by passing either --fix which applies all style fixes, or any of the --fix--prefixed flags to apply specific fixes.

For example, running with --fix-named-default-separator changes this:

greet(String name, {String title: "Captain"}) {
  print("Greetings, $title $name!");
}

into:

greet(String name, {String title = "Captain"}) {
  print("Greetings, $title $name!");
}

Using the formatter

The formatter is part of the unified dart developer tool included in the Dart SDK, so most users get it directly from there. That has the latest version of the formatter that was available when the SDK was released.

IDEs and editors that support Dart usually provide easy ways to run the formatter. For example, in WebStorm you can right-click a .dart file and then choose Reformat with Dart Style.

Here's a simple example of using the formatter on the command line:

$ dart format test.dart

This command formats the test.dart file and writes the result to the file.

dart format takes a list of paths, which can point to directories or files. If the path is a directory, it processes every .dart file in that directory or any of its subdirectories.

By default, it formats each file and write the formatting changes to the files. If you pass --output show, it prints the formatted code to stdout.

You may pass a -l option to control the width of the page that it wraps lines to fit within, but you're strongly encouraged to keep the default line length of 80 columns.

Validating files

If you want to use the formatter in something like a presubmit script or commit hook, you can pass flags to omit writing formatting changes to disk and to update the exit code to indicate success/failure:

$ dart format --output=none --set-exit-if-changed .

Running other versions of the formatter CLI command

If you need to run a different version of the formatter, you can globally activate the package from the dart_style package on pub.dev:

$ pub global activate dart_style
$ pub global run dart_style:format ...

Using the dart_style API

The package also exposes a single dart_style library containing a programmatic API for formatting code. Simple usage looks like this:

import 'package:dart_style/dart_style.dart';

main() {
  final formatter = DartFormatter();

  try {
    print(formatter.format("""
    library an_entire_compilation_unit;

    class SomeClass {}
    """));

    print(formatter.formatStatement("aSingle(statement);"));
  } on FormatterException catch (ex) {
    print(ex);
  }
}

Other resources

Before sending an email, see if you are asking a frequently asked question.
Before filing a bug, or if you want to understand how work on the formatter is managed, see how we track issues.