| commit | 585fc7798fbe07ab1a4caca1a5ea3570f9d3aef9 | [log] [tgz] |
|---|---|---|
| author | Bob Nystrom <rnystrom@google.com> | Fri Apr 26 16:04:08 2024 -0700 |
| committer | GitHub <noreply@github.com> | Fri Apr 26 16:04:08 2024 -0700 |
| tree | b9be95e44912c88ba305c1bc301d4f181f303192 | |
| parent | bf9a269d6e21646392c47953572bd72433b80379 [diff] |
Take leading indentation into account when constraining by page width. (#1447) There's an important optimization where if a piece can tell that it's contents will never fit the given page with without splitting, it can eagerly bind to a specific state. This optimization is really important for forcing large outermost function calls and collections to split so the solver doesn't waste tons of time pointlessly trying to not split them. Before this change, that optimization only looked at the total page width when determining how much "room" a piece has. That's nice because it means the answer is context free. Thus we can directly pin the piece because no matter the indentation, it's never going to fit. But it means that when a piece is separately formatted and deeply nested, we don't take that leading indentation into account. Doing so can let us tell that the piece isn't going to fit more often because the remaining space is narrower. This change does that. Instead of pinning, it binds the piece in the solution when it doesn't fit and takes the leading indentation into account. Binding instead of pinning is slightly slower (though I have some ideas how to optimize that), so this has a constant time performance regression. But being able to eagerly split pieces more often on deeply nested code has a huge performance improvement on large code when it kicks in: ``` Benchmark (tall) fastest baseline ----------------------------- -------- -------- block 0.091 132.5% chain 2.489 99.6% collection 0.187 159.3% collection_large 1.203 73.8% flutter_popup_menu_test 0.552 869.2% flutter_scrollbar_test 0.235 91.1% function_call 2.018 68.7% infix_large 1.723 86.9% infix_small 0.370 83.1% large 5.702 90.7% top_level 0.271 97.0% ``` Most benchmarks get a little slower but a few get way faster. On real world code, I think this optimization overall pays its way. (And, again, I think we can improve the cost of binding too.)
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!"); }
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.
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 .
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 ...
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); } }
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.