5a93630468998fde0c2786dd7f0e25e58819a73e - dart_style

commit	5a93630468998fde0c2786dd7f0e25e58819a73e	[log] [tgz]
author	Bob Nystrom <rnystrom@google.com>	Tue Feb 27 13:02:13 2024 -0800
committer	GitHub <noreply@github.com>	Tue Feb 27 13:02:13 2024 -0800
tree	3024bcae87c16b115f430948d049558590609768
parent	6b2b31e55b6a50f4d6ff356b0e085ef2e4345de4 [diff]

Tweak the heuristics on which expressions allow block formatting. (#1408)

Tweak the heuristics on which expressions allow block formatting.

I was trying out the new formatting on Flutter and noticed a few issues:

1. Immediately-invoked functions in asserts are common.

Prior to this change, these were not block format candidates, giving
you:

```dart
assert(
  () {
    // Some slow computation...
  }(),
  'Message.',
);
```

With this change, they're treated like (uninvoked) function expressions:

```dart
assert(() {
  // Some slow computation...
}(), 'Message.');
```

2. Formatting large deep widget trees looks weird.

Prior to this change, a function call inside an argument list can be
treated like a block argument even if there are other arguments. That
tends to pack things in strangely in widget code, like:

```dart
SizedBox(height: 1000.0, width: double.infinity, child: Column(
  children: <Widget>[Scrollbar(key: key1, child: SizedBox(
    height: 300.0,
    width: double.infinity,
    child: SingleChildScrollView(key: innerKey, child: const SizedBox(key: Key(
      'Inner scrollable',
    ), height: 1000.0, width: double.infinity)),
  ))],
));
```

With this change, a function or method call inside an argument list is
only block formatted if there are no other arguments. In other words,
you can block format a function call if the outer call is a pure wrapper
around the call, but not otherwise. That leads to:

```dart
SizedBox(
  height: 1000.0,
  width: double.infinity,
  child: Column(children: <Widget>[Scrollbar(
    key: key1,
    child: SizedBox(
      height: 300.0,
      width: double.infinity,
      child: SingleChildScrollView(
        key: innerKey,
        child: const SizedBox(
          key: Key('Inner scrollable'),
          height: 1000.0,
          width: double.infinity,
        ),
      ),
    ),
  )]),
);
```

I think that looks a lot nicer.

3. Deep, complex argument lists are combinatorially slow.

We have an optimization to eagerly force an argument list to split if
its contents clearly won't fit. But that optimization ignores the size
of a potential block argument since the contents of that can be wrapped
across multiple lines without forcing the outer argument list to split.

A consequence of that is that big deeply nested function calls end up
slow if it happens that each one only has a single block-formattable
call. That turns out to be very common in Flutter code where you have a
deep chain of nested widgets along with a bunch of other arguments.

The above change to disallow block formatting function calls if there
are any other arguments conveniently fixes that performance issue in
most cases. (Though I expect we will want to do more work here to handle
pathological cases.)

12 files changed

tree: 3024bcae87c16b115f430948d049558590609768

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.