94f81dd4ecfb2e9d10b71a7a41f209c58ab21473 - dart_style

commit	94f81dd4ecfb2e9d10b71a7a41f209c58ab21473	[log] [tgz]
author	Bob Nystrom <rnystrom@google.com>	Mon Jan 22 19:32:41 2024 -0800
committer	GitHub <noreply@github.com>	Mon Jan 22 19:32:41 2024 -0800
tree	7c06ad8ca849326c8c4d7807163776d3670cf839
parent	b1b0481129cc322da76d40de849294f0722e6155 [diff]

Format multi-line strings and string interpolation. (#1362)

Format multi-line strings and string interpolation.

In the old style, the formatter has some special code to discard line
splits that occur inside string interpolation expressions. That's
largely for historical reasons because the formatter initially didn't
support formatting of string interpolation expressions *at all* and I
didn't want too much churn when adding support for formatting them.

In the new style here, we don't do that: The contents of a string
interpolation expression are split like any other expression. In
practice, it doesn't matter much since users generally reorganize their
code to avoid long strings and splits in string interpolation. This way
leads to less special case code in the formatter.

This change is somewhat large because I also reorganized how newlines
inside lexemes are handled in general. Previously, TextPiece stored a
list of "lines" to handle things like line comments preceding or
following a token. But it was also possible for a single "line" string
in that list to internally contain newline characters because of
multi-line strings or block comments.

But those internal newlines also need to force surrounding code to
split, so there was this "_containsNewline" bit that had to be plumbed
through and tracked. Even so, there were latent bugs where the column
calculation in CodeWriter would be incorrect if a line contained
internal newlines because it just used to the length of the entire
"line" string.

With this change, the "_lines" list in TextPiece really is a list of
lines. We eagerly split any incoming lexeme into multiple lines before
writing it to the TextPiece. I think the resulting code is simpler, it
fixes the column calculation in CodeWriter, and it means the formatter
will correctly normalize line endings even when they occur inside block
comments or multiline strings.

This was a good time to test the line ending code, so I copied those
existing tests over from short_format_test.dart. I went ahead and
copied all of the unit tests from that file, even the ones not related
to line endings, since they're all working and passing now.

This PR does *not* handle adjacent strings. Those have a decent amount
of special handling not related to what's going on here, so I'll do
those separately.

12 files changed

tree: 7c06ad8ca849326c8c4d7807163776d3670cf839

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.