Merge branch 'main' into comment-after-metadata

Author: munificent

CHANGELOG.md

@@ -1,5 +1,87 @@
 ## 3.0.0-wip
 
+This is a large change. Under the hood, the formatter was almost completely
+rewritten, with the codebase now containing both the old and new
+implementations. The old formatter exists to support the older "short" style
+and the new code implements [the new "tall" style][tall].
+
+[tall]: https://github.com/dart-lang/dart_style/issues/1253
+
+The formatter uses the language version of the formatted code to determine
+which style you get. If the language version is 3.6 or lower, the code is
+formatted with the old style. If 3.7 or later, you get the new tall style. You
+typically control the language version by [setting a min SDK constraint in your
+package's pubspec][versioning].
+
+[versioning]: https://dart.dev/guides/language/evolution
+
+In addition to the new formatting style, a number of other API and CLI changes
+are included, some of them breaking:
+
+* **Support project-wide page width configuration.** By long request, you can
+  now configure your preferred formatting page width on a project-wide basis.
+  When formatting files, the formatter will look in the file's directory and
+  any surrounding directories for an `analysis_options.yaml` file. If it finds
+  one, it looks for the following YAML:
+
+  ```yaml
+  formatter:
+    page_width: 123
+  ```
+
+  If it finds a `formatter` key containing a map with a `page_width` key whose
+  value is an integer, then that is the page width that the file is formatted
+  using. Since the formatter will walk the surrounding directories until it
+  finds an `analysis_options.yaml` file, this can be used to globally set the
+  page width for an entire directory, package, or even collection of packages.
+
+* **Support overriding the page width for a single file.** In code formatted
+  using the new tall style, you can use a special marker comment to control the
+  page width that it's formatted using:
+
+  ```dart
+  // dart format width=30
+  main() {
+    someExpression +
+        thatSplitsAt30;
+  }
+  ```
+
+  This comment must appear before any code in the file and must match that
+  format exactly. The width set by the comment overrides the width set by any
+  surrounding `analysis_options.yaml` file.
+
+  This feature is mainly for code generators that generate and immediately
+  format code but don't know about any surrounding `analysis_options.yaml`
+  that might be configuring the page width. By inserting this comment in the
+  generated code before formatting, it ensures that the code generator's
+  behavior matches the behavior of `dart format`.
+
+  End users should mostly use `analysis_options.yaml` for configuring their
+  preferred page width (or do nothing and use the default page width of 80).
+
+* **Support opting out a region of code from formatting.** In code formatted
+  using the new tall style, you can use a pair of special marker comments to
+  opt a region of code out of automated formatting:
+
+  ```dart
+  main() {
+    this.isFormatted();
+    // dart format off
+    no   +   formatting
+      +
+        here;
+    // dart format on
+    formatting.isBackOnHere();
+  }
+  ```
+
+  The comments must be exactly `// dart format off` and `// dart format on`.
+  A file may have multiple regions, but they can't overlap or nest.
+
+  This can be useful for highly structured data where custom layout can help
+  a reader understand the data, like large lists of numbers.
+
 * **Remove support for fixes and `--fix`.** The tools that come with the Dart
   SDK provide two ways to apply automated changes to code: `dart format --fix`
   and `dart fix`. The former is older and used to be faster. But it can only
@@ -16,31 +98,29 @@
 
 * **Make the language version parameter to `DartFormatter()` mandatory.** This
   way, the formatter always knows what language version the input is intended
-  to be treated as. Note that a `// @dart=` language version comment if present
-  overrides the specified language version. You can think of the version passed
-  to the `DartFormatter()` constructor as a "default" language version which
-  the file's contents may then override.
+  to be treated as. Note that a `// @dart=` language version comment, if
+  present, overrides the specified language version. You can think of the
+  version passed to the `DartFormatter()` constructor as a "default" language
+  version which the file's contents may then override.
 
   If you don't particularly care about the version of what you're formatting,
   you can pass in `DartFormatter.latestLanguageVersion` to unconditionally get
   the latest language version that the formatter supports. Note that doing so
-  means you will also implicitly opt into the new tall style when that style
-  becomes available.
+  means you will also implicitly opt into the new tall style.
 
   This change only affects the library API. When using the formatter from the
   command line, you can use `--language-version=` to specify a language version
   or pass `--language-version=latest` to use the latest supported version. If
-  omitted, the formatter will look up the surrounding directories for a package
+  omitted, the formatter will look in the surrounding directories for a package
   config file and infer the language version for the package from that, similar
   to how other Dart tools behave like `dart analyze` and `dart run`.
 
 * **Remove the old formatter executables and CLI options.** Before the
   `dart format` command was added to the core Dart SDK, users accessed the
   formatter by running a separate `dartfmt` executable that was included with
   the Dart SDK. That executable had a different CLI interface. For example, you
-  had to pass `-w` to get it to overwrite files and if you passed no arguments
-  at all, it silently sat there waiting for input on stdin. When we added
-  `dart format`, we took that opportunity to revamp the CLI options.
+  had to pass `-w` to get it to overwrite files. When we added `dart format`,
+  we took that opportunity to revamp the CLI options.
 
   However, the dart_style package still exposed an executable with the old CLI.
   If you ran `dart pub global activate dart_style`, this would give you a
@@ -64,25 +144,25 @@
   `--language-version=`, or use `--language-version=latest` to parse the input
   using the latest language version supported by the formatter.
 
-  If `--stdin-name` and `--language-version` are both omitted, then parses
-  stdin using the latest supported language version.
-
-* **Apply class modifiers to API classes.** The dart_style package exposes only
-  a few classes in its public API: `DartFormatter`, `SourceCode`,
-  `FormatterException`, and `UnexpectedOutputException`. None were ever
-  intended to be extended or implemented. They are now all marked `final` to
-  make that intention explicit.
+  If `--stdin-name` and `--language-version` are both omitted, then the
+  formatter parses stdin using the latest supported language version.
 
 * **Rename the `--line-length` option to `--page-width`.** This is consistent
   with the public API, internal implementation, and docs, which all use "page
   width" to refer to the limit that the formatter tries to fit code into.
 
   The `--line-length` name is still supported for backwards compatibility, but
   may be removed at some point in the future. You're encouraged to move to
-  `--page-width`. Use of this option (however its named) is rare, and will
+  `--page-width`. Use of this option (however it's named) is rare, and will
   likely be even rarer now that project-wide configuration is supported, so
   this shouldn't affect many users.
 
+* **Apply class modifiers to API classes.** The dart_style package exposes only
+  a few classes in its public API: `DartFormatter`, `SourceCode`,
+  `FormatterException`, and `UnexpectedOutputException`. None were ever
+  intended to be extended or implemented. They are now all marked `final` to
+  make that intention explicit.
+
 ## 2.3.7
 
 * Allow passing a language version to `DartFomatter()`. Formatted code will be

benchmark/directory.dart

@@ -7,7 +7,6 @@ import 'dart:io';
 import 'package:args/args.dart';
 import 'package:collection/collection.dart';
 import 'package:dart_style/dart_style.dart';
-import 'package:dart_style/src/constants.dart';
 import 'package:dart_style/src/profile.dart';
 import 'package:dart_style/src/testing/benchmark.dart';
 
@@ -64,8 +63,9 @@ void main(List<String> arguments) async {
 void _runFormatter(String source) {
   try {
     var formatter = DartFormatter(
-        languageVersion: DartFormatter.latestLanguageVersion,
-        experimentFlags: [if (!_isShort) tallStyleExperimentFlag]);
+        languageVersion: _isShort
+            ? DartFormatter.latestShortStyleLanguageVersion
+            : DartFormatter.latestLanguageVersion);
 
     var result = formatter.format(source);
 

benchmark/run.dart

@@ -10,7 +10,6 @@ import 'package:analyzer/dart/analysis/results.dart';
 import 'package:analyzer/dart/analysis/utilities.dart';
 import 'package:args/args.dart';
 import 'package:dart_style/dart_style.dart';
-import 'package:dart_style/src/constants.dart';
 import 'package:dart_style/src/debug.dart' as debug;
 import 'package:dart_style/src/front_end/ast_node_visitor.dart';
 import 'package:dart_style/src/profile.dart';
@@ -131,10 +130,11 @@ List<double> _runTrials(String verb, Benchmark benchmark, int trials) {
       throwIfDiagnostics: false);
 
   var formatter = DartFormatter(
-      languageVersion: DartFormatter.latestLanguageVersion,
+      languageVersion: _isShort
+          ? DartFormatter.latestShortStyleLanguageVersion
+          : DartFormatter.latestLanguageVersion,
       pageWidth: benchmark.pageWidth,
-      lineEnding: '\n',
-      experimentFlags: [if (!_isShort) tallStyleExperimentFlag]);
+      lineEnding: '\n');
 
   var measuredTimes = <double>[];
   for (var i = 1; i <= trials; i++) {

example/format.dart

@@ -3,7 +3,6 @@
 // BSD-style license that can be found in the LICENSE file.
 
 import 'package:dart_style/dart_style.dart';
-import 'package:dart_style/src/constants.dart';
 import 'package:dart_style/src/debug.dart' as debug;
 import 'package:dart_style/src/testing/test_file.dart';
 
@@ -40,9 +39,10 @@ void _runFormatter(String source, int pageWidth,
     {required bool tall, required bool isCompilationUnit}) {
   try {
     var formatter = DartFormatter(
-        languageVersion: DartFormatter.latestLanguageVersion,
-        pageWidth: pageWidth,
-        experimentFlags: [if (tall) tallStyleExperimentFlag]);
+        languageVersion: tall
+            ? DartFormatter.latestLanguageVersion
+            : DartFormatter.latestShortStyleLanguageVersion,
+        pageWidth: pageWidth);
 
     String result;
     if (isCompilationUnit) {
@@ -75,10 +75,7 @@ Future<void> _runTest(String path, int line,
   var formatter = DartFormatter(
       languageVersion: formatTest.languageVersion,
       pageWidth: testFile.pageWidth,
-      indent: formatTest.leadingIndent,
-      experimentFlags: tall
-          ? const ['inline-class', tallStyleExperimentFlag]
-          : const ['inline-class']);
+      indent: formatTest.leadingIndent);
 
   var actual = formatter.formatSource(formatTest.input);
 

lib/src/cli/format_command.dart

@@ -69,8 +69,7 @@ final class FormatCommand extends Command<int> {
         help: 'Language version of formatted code.\n'
             'Use "latest" to parse as the latest supported version.\n'
             'Omit to look for a surrounding package config.',
-        // TODO(rnystrom): Show this when the tall-style experiment ships.
-        hide: true);
+        hide: !verbose);
 
     argParser.addFlag('set-exit-if-changed',
         negatable: false,

lib/src/config_cache.dart

@@ -62,6 +62,7 @@ final class ConfigCache {
     // Otherwise, walk the file system and look for it.
     var config =
         await _findPackageConfig(file, displayPath, forLanguageVersion: true);
+
     if (config?.packageOf(file.absolute.uri)?.languageVersion
         case var languageVersion?) {
       // Store the version as pub_semver's [Version] type because that's

lib/src/constants.dart

@@ -2,15 +2,6 @@
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
-/// The in-progress "tall" formatting style is enabled by passing an experiment
-/// flag with this name.
-///
-/// Note that this isn't a real Dart SDK experiment: Only the formatter supports
-/// it. We use the [experimentFlags] API to pass this in so that support for it
-/// can be removed in a later version without it being a breaking change to the
-/// dart_style library API.
-const tallStyleExperimentFlag = 'tall-style';
-
 /// Constants for the cost heuristics used to determine which set of splits is
 /// most desirable.
 final class Cost {

lib/src/dart_formatter.dart

@@ -14,7 +14,6 @@ import 'package:analyzer/src/dart/scanner/scanner.dart';
 import 'package:analyzer/src/string_source.dart';
 import 'package:pub_semver/pub_semver.dart';
 
-import 'constants.dart';
 import 'exceptions.dart';
 import 'front_end/ast_node_visitor.dart';
 import 'short/source_visitor.dart';
@@ -30,7 +29,14 @@ final RegExp _widthCommentPattern = RegExp(r'^// dart format width=(\d+)$');
 final class DartFormatter {
   /// The latest Dart language version that can be parsed and formatted by this
   /// version of the formatter.
-  static final latestLanguageVersion = Version(3, 3, 0);
+  static final latestLanguageVersion = Version(3, 7, 0);
+
+  /// The latest Dart language version that will be formatted using the older
+  /// "short" style.
+  ///
+  /// Any Dart code at a language version later than this will be formatted
+  /// using the new "tall" style.
+  static final latestShortStyleLanguageVersion = Version(3, 6, 0);
 
   /// The page width that the formatter tries to fit code inside if no other
   /// width is specified.
@@ -125,11 +131,8 @@ final class DartFormatter {
       );
     }
 
-    // Don't pass the formatter's own experiment flag to the parser.
-    var experiments = experimentFlags.toList();
-    experiments.remove(tallStyleExperimentFlag);
     var featureSet = FeatureSet.fromEnableFlags2(
-        sdkLanguageVersion: languageVersion, flags: experiments);
+        sdkLanguageVersion: languageVersion, flags: experimentFlags);
 
     // Parse it.
     var parseResult = parseString(
@@ -185,8 +188,9 @@ final class DartFormatter {
     // Format it.
     var lineInfo = parseResult.lineInfo;
 
+    // Use language version to determine what formatting style to apply.
     SourceCode output;
-    if (experimentFlags.contains(tallStyleExperimentFlag)) {
+    if (languageVersion > latestShortStyleLanguageVersion) {
       // Look for a page width comment before the code.
       int? pageWidthFromComment;
       for (Token? comment = node.beginToken.precedingComments;
@@ -203,6 +207,7 @@ final class DartFormatter {
       var visitor = AstNodeVisitor(this, lineInfo, unitSourceCode);
       output = visitor.run(unitSourceCode, node, pageWidthFromComment);
     } else {
+      // Use the old style.
       var visitor = SourceVisitor(this, lineInfo, unitSourceCode);
       output = visitor.run(node);
     }