82ced5a7522c95a29e0367b4763cfdca851a31ec - dart_style

commit	82ced5a7522c95a29e0367b4763cfdca851a31ec	[log] [tgz]
author	Bob Nystrom <rnystrom@google.com>	Mon Mar 18 09:56:52 2024 -0700
committer	GitHub <noreply@github.com>	Mon Mar 18 09:56:52 2024 -0700
tree	a45bca59b7a0f878e1492a32c9864ba83fc0b128
parent	4d037b332c30df2b0f1bb718ca98ef9c29c6bed8 [diff]

Update tool/test_updater.dart to handle the tall style and test changes. (#1426)

Update tool/test_updater.dart to handle the tall style and test changes.

This internal tool is used to automatically update the expectations for
test files based on the current behavior of the formatter. This PR gets
it working with all of the changes that have happened since the new
style. Those are:

- Use the tall style when updating a tall/ test.

- Enable the inline-class and macros experiments generating the output.
  The format test runner itself always enables those.

- Preserve `###` comments. This is tricky if we allow those comments to
  appear anywhere in a test since it might not be clear where they
  should be reinserted in an updated test expectation. To avoid that,
  this change now only allows `###` comments to appear at the top of the
  test file, or at the beginning of an actual or expected section. All
  of the existing comments already fit that restriction, except for one
  which was never supposed to be committed. I'll fix that in a later
  commit.

- Handle skipping new tall style tests that contain selections or
  Unicode escapes. The test updater doesn't know how to update those
  tests.

Also, I generally made the output a little nicer.

* Normalize newlines at the end of the tests.

Most test files don't end with a newline. That's admittedly unusual for
text files, but I did it that way to avoid confusion about whether the
last test in the file is itself required to output a trailing newline.

In practice, it seems to work fine whether or not there is a trailing
newline now? Anyway, for consistency's sake, remove all the trailing
newlines. That way, the test updater doesn't produce spurious diffs on
these files when it tries to remove them.

* Fix a typo in a test expectation.

This should have always been ">>>", but the TestFile parser happens to
always treat the first line of the test file (after the "|" or "###"
lines) as the beginning of a test, even if it doesn't start with ">>>".

Running this file through the test updater normalized it to the correct
syntax.

Also, clean up a TODO.

The strangely-located "### TODO: Clean up." in the middle of this file
was supposed to be a reminder to me to clean up the test descriptions
in this file before I sent it out for review but I guess I forgot. :)

Doing it now to make the test cleaner and because the "###" comment is
in a place where comments are no longer allowed.

33 files changed

tree: a45bca59b7a0f878e1492a32c9864ba83fc0b128

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.