| commit | 30dce1c53d543e456a4f0fa0301e84b0750bb139 | [log] [tgz] |
|---|---|---|
| author | Bob Nystrom <rnystrom@google.com> | Fri Sep 06 14:21:35 2024 -0700 |
| committer | GitHub <noreply@github.com> | Fri Sep 06 14:21:35 2024 -0700 |
| tree | 9ac5b905bc39d476bc9d6e2099d899fe7d38383f | |
| parent | ab9cbefa5c7bedb5e93426e44d8e586dd4c0ff7c [diff] |
Don't allow a block argument to be named. (#1561) There are three ways an argument list can be formatted: ```dart // 1. All inline: function(argument, another); // 2. Block formatted: function(argument, [ element, element, ]); // 3. Tall style: function( argument, another, ); ``` One of the trickiest parts of the formatter is deciding the heuristics to choose between 2 and 3. Prior to this PR, there is a fairly subtle rule: Arguments before the block argument can be named or not, the block argument can be named or not, and the argument after the block argument can be named or not, but only one of those three sections can have a named argument. The intent of that rule is to allow named block arguments and named non-block arguments, while avoiding multiple argument names on the same line when block formatted. Also, it allows an argument list containing only a named argument to be block formatted: ```dart function(name: [ element, ]); ``` From looking at how contributors to Flutter have hand-formatted their code, it doesn't look like this level of complexity is well motivated. And allowing a single named argument to be block formatted but not if there are other named arguments means that adding a second named argument to a function can cause the entire argument list to be reformatted and indented differently. That can be a lot of churn if the block argument is itself a large nested widget tree. This PR tweaks that rule to something simpler: 1. The block argument must be positional. 2. Other non-block arguments have no restrictions on whether they can be named or not. This reduces diff churn and means that widget trees (which almost always use named arguments) have a more consistent (but taller) style across the entire tree. From talking to Michael Goderbauer, this seems like a reasonable trade-off to me.
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.