| commit | d8523412cde905e3e7566fa1c7d0d483fade21d2 | [log] [tgz] |
|---|---|---|
| author | Bob Nystrom <robert@stuffwithstuff.com> | Wed Jun 13 17:22:39 2018 -0700 |
| committer | GitHub <noreply@github.com> | Wed Jun 13 17:22:39 2018 -0700 |
| tree | 7c3585b0bc60f91d17711fb641a848999781b316 | |
| parent | b4c40cf941461403d51415059997708fde847b73 [diff] |
Attempt to uniformly format code with or without "new"/"const". (#698)
* Attempt to uniformly format code with or without "new"/"const".
One problem with optional new is that dartfmt can no longer reliably
tell what's a constructor call versus some other kind of invocation
(usually a static method on a class). In particular, named constructor
calls do not get formatted as part of a method chain. You get this:
new Foo().named()
.method()
.method()
.method();
Not:
new Foo()
.named()
.method()
.method()
.method();
But if that were a static method call, you *would* get:
Foo()
.named()
.method()
.method()
.method();
This means that removing the "new"/"const" keywords from your code can
change how its formatted (beyond just the changes caused by the lines
being shorter). In particular, it means if you run:
dartfmt --fix -w .
dartfmt -w .
The second invocation may produce changes, even though it should be
strictly redundant. That's because the first call *does* know which
calls are constructors because the keywords are still there when it's
parsed, but the second does not.
That violates an expectation that dartfmt is idempotent.
This addresses that by having a uniform set of formatting rules for
constructors and other invocations. To avoid ugly cases where a named
constructor would get slurped into a method chain, it pulls out all
static calls from method chains. So with this change you *would* get:
Foo().named()
.method()
.method()
.method();
It does this for all static calls, not just constructors. That makes
this a fairly large change. I've run it on a large corpus, and I
actually think it looks pretty good with that style.
There is no fully reliably way to identify a "static" call just from
syntax. Instead, it uses the heuristic that class names are capitalized
(but not all caps). This seems to work correctly on all but the weirdest
code I've seen in the wild.
* Update CHANGELOG.
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.
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!"); }
Dartfmt is included in the Dart SDK, so you might want to add the SDK's bin directory to your system path.
If you want to make sure you are running the latest version of dartfmt, you can globally activate the package from the dart_style package on pub.dartlang.org, and let pub put its executable on your path:
$ pub global activate dart_style $ dartfmt ...
If you don't want dartfmt on your path, you can run it explicitly:
$ pub global activate dart_style --no-executables $ pub global run dart_style:format ...
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 dartfmt on the command line:
$ dartfmt test.dart
This command formats the test.dart file and writes the result to standard output.
Dartfmt 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. If no file or directory is specified, dartfmt reads from standard input.
By default, it formats each file and just prints the resulting code to stdout. If you pass -w, it overwrites your existing files with the formatted results.
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.
If you want to use the formatter in something like a presubmit script or commit hook, you can use the -n dry run option. If you specify -n, the formatter prints the paths of the files whose contents would change if the formatter were run normally. If it prints no output, then everything is already correctly formatted.
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() { var formatter = new DartFormatter(); try { print(formatter.format(""" library an_entire_compilation_unit; class SomeClass {} """)); print(formatter.formatStatement("aSingle(statement);")); } on FormatterException catch (ex) { print(ex); } }
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.