Google Git
Sign in
dart / dart_style / 95ba395cd8bb4c936cf208e86656ecbdf43ea0f3
commit95ba395cd8bb4c936cf208e86656ecbdf43ea0f3[log] [tgz]
authorBob Nystrom <rnystrom@google.com>Mon Mar 18 13:53:23 2024 -0700
committerGitHub <noreply@github.com>Mon Mar 18 13:53:23 2024 -0700
tree21cf99f04b966b28fb04b72f0acd6ec84d8aef87
parentfdc36a31d461c1825cfebade669d82caa50dfd98 [diff]
Tweak the call chain splitting rules. (#1428)

Tweak the call chain splitting rules.

Some of the most complex formatting rules are around call chains. This
is because argument lists themselves are fairly complex to format, and
a call chain can contain many of them. Also, method and property
accesses and argument lists make up the majority of Dart code, so the
ways it can appear are varied and users expect nice formatting for all
of the different ways chains and calls can be combined.

I've been migrating regression tests and looking at the results to see
what rules we want to tweak. One thing I noticed is that I believe the
current call chain rule tries too hard to block format a trailing call.

Block formatted calls are very often important in chains like:

    thing.someStuff.forEach((element) {
      ...
    });

But in some cases, it's better to just split the whole chain even if we
could block format the last call if we really wanted to as in:

    var overlapping = _directories.keys.where(
        (directory) =>
            path.isWithin(directory, rootDirectory) ||
            path.isWithin(rootDirectory, directory),
        ).toList();

That output isn't horrific, but I think it's better if we split the
chain and emphasize that:

    var overlapping = _directories.keys
        .where((directory) =>
            path.isWithin(directory, rootDirectory) ||
            path.isWithin(rootDirectory, directory))
        .toList();

(That's also much closer to how the short style formats this code.)

This commit tweaks the rule to determine whether a call in a chain can
block format or not. The basic change is that we only allow the trailing
(or next to last) call to be a block call if either:

- All of the preceding calls are either properties or zero-argument
  functions.

- The trailing block call is an actual block argument list, and not
  just an argument list that splits.

In other words, if the leading calls have any argument lists that can
split, and the last call has a regular (non-block) argument list, then
we don't allow the last call to be a block call and the whole chain
splits:

    // Before this PR:
    target.property.leading(argument1).trailing(
      argument3,
      argument4,
    );

    // With this PR:
    target.property
        .leading(argument1)
        .trailing(argument3, argument4);

Also, only allow a trailing property or zero-argument call after a block call
if the call is actually block-formatted and not just a split argument
list.
4 files changed
tree: 21cf99f04b966b28fb04b72f0acd6ec84d8aef87
  1. .github/
  2. benchmark/
  3. bin/
  4. dist/
  5. example/
  6. lib/
  7. test/
  8. tool/
  9. .gitignore
  10. analysis_options.yaml
  11. AUTHORS
  12. CHANGELOG.md
  13. LICENSE
  14. pubspec.yaml
  15. README.md
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.