dart_style

Internal changes

• Allow package_config version 3 (#1876).

Internal changes

• Allow package_config version 3 (#1876).

Internal changes

• Migrate off grinder.
• Allow analyzer version 14.

Internal changes

• Migrate off grinder.
• Allow analyzer version 14.

• Show the supported language versions in dart format --version --verbose.

Bug fixes

• Don't crash if an analysis_options.yaml file has an include that points to
  a non-existent or unreadable file (#1840).

Style changes

The following minor style bug fixes are not language versioned and apply to all
formatted code:

• Fix a bug in eager splitting optimization that in rare cases would lead to a
  collection or argument list splitting unnecessarily (#1809).

• Don't add a blank line before a comment at the end of a compilation unit or
  braced body (#1644).
  If you have already formatted code using dart_style that encounters this bug,
  then reformatting it even after this fix will have no effect since the
  unneeded blank line was already added.

The following changes only apply when formatting code at language version 3.13
or higher:

• Fix a bug in an eager splitting optimization that would lead the formatter to
  prefer less desirable solutions (#1847).
  Typically, the code affected by this bug is a call chain that contains an
  argument list with a large collection literal, as in:

  // Before:
  await MethodChannelContainer()
      .onMethodChannelInvoke("reportCrash", <String, dynamic>{
        "time": nowTime,
        "errorValue": errorName,
        "reason": reason,
        "stacktrace": stacktrace,
      });
  // After:
  await MethodChannelContainer().onMethodChannelInvoke(
    "reportCrash",
    <String, dynamic>{
      "time": nowTime,
      "errorValue": errorName,
      "reason": reason,
      "stacktrace": stacktrace,
    },
  );

• Prefer to split call chains for single-element targets (#1732).
  When formatting a method call chain whose target can also split, the formatter
  must decide whether to split the target or the call chain (or both). For
  example:

  // Split target:
  function(
    argument,
  ).method().another();
  // Or split chain:
  function(argument)
      .method()
      .another();

  We've tried various heuristics for this over the years but most make some code
  look better while making other code look worse. This version introduces a
  relatively simple rule that seems to work well in practice: If the call chain
  target has only one element or argument, then prefer to split the call chain
  and keep the target together. So in the above example, if prefers the second
  output.

• Allow block formatting parameter lists (#1693). The formatter supports
  "block formatting" for most bracket-delimited constructs in the language. This
  is what enables a multi-line list literal in an assignment to look like this:

  variable = [
    some,
    list,
    elements,
  ];

  Instead of:

  variable =
      [
        some,
        list,
        elements,
      ];

  This style applies to most language constructs, but function parameter lists
  were omitted. Now they are not. This rarely shows up in real code, except for
  typedefs of large function types:

  // Before:
  typedef DataViewBuilder<T> =
      Widget Function(
        BuildContext context,
        PagingState<int, T> state,
        NextPageCallback fetchNextPage,
      );
  // After:
  typedef DataViewBuilder<T> = Widget Function(
    BuildContext context,
    PagingState<int, T> state,
    NextPageCallback fetchNextPage,
  );

• Allow as, is, and is! expressions to be block formatted (#1542).

  // Before:
  variable =
      function(
            argument,
            argument,
            argument,
          )
          as Type;
  // After:
  variable = function(
    argument,
    argument,
    argument,
  ) as Type;

• Separate imports into sections (#1120). Following the guidelines in
  "Effective Dart", the formatter inserts a blank line between
  "dart:", "package:", and other imports:

  // Before:
  import 'dart:io';
  import 'dart:math';
  import 'package:args/args.dart';
  import 'package:test/test.dart';
  import 'my_library.dart';
  // After:
  import 'dart:io';
  import 'dart:math';
  import 'package:args/args.dart';
  import 'package:test/test.dart';
  import 'my_library.dart';

• In if-case statements and elements, split the guard if the pattern
  block-splits (#1596).
  This tends to lead to code where the pattern is kept on one line and the
  guard splits:

  // Before:
  if (expression case SomeClass(
    property: var x,
  ) when guardClause(x)) {
    ...
  }
  // After:
  if (expression case SomeClass(property: var x)
      when guardClause(x)) {
    ...
  }

• When no solution fits the page width, prefer solutions where the overflowing
  lines have trailing string literals or comments (#1802, #1803, #1837).
  Sometimes the formatter is unable to split the code in a way that fits it all
  within the page width. When this happens, the formatter prefers whatever
  solution has the fewest overflowing characters.
  In practice, overflowing solutions are usually caused by long string literals
  or comments that the user should split manually. To help the user do that, the
  formatter now treats overflowing characters caused by trailing string
  literals, comments, and a few other things that often follow a string literal
  like ,, ;, () {, or () async {, as "less bad" when comparing the
  amount of overflow between two solutions.
  The effect is that when no solution fits, the formatter tends to prefer a
  solution with hanging strings or comments, which makes it clearer to the user
  which code they need to go back and manually split.
  This change has no effect on code that does fit in the page width.

• Write a trailing comma in split extension type representation clauses when in
  a library whose language version allows it (#1845).
  Prior to Dart 3.13, extension type representation clauses didn't allow
  trailing commas even though they syntactically appear like formal parameter
  lists. In Dart 3.13, that was fixed, so now the formatter formats them the
  same way as other parameter lists in primary constructors.

Internal changes

• Require analyzer: ^13.1.0.

• Show the supported language versions in dart format --version --verbose.

Bug fixes

• Don't crash if an analysis_options.yaml file has an include that points to a non-existent or unreadable file (#1840).

Style changes

The following minor style bug fixes are not language versioned and apply to all formatted code:

• Fix a bug in eager splitting optimization that in rare cases would lead to a collection or argument list splitting unnecessarily (#1809).

• Don't add a blank line before a comment at the end of a compilation unit or braced body (#1644).

  If you have already formatted code using dart_style that encounters this bug, then reformatting it even after this fix will have no effect since the unneeded blank line was already added.

The following changes only apply when formatting code at language version 3.13 or higher:

• Fix a bug in an eager splitting optimization that would lead the formatter to prefer less desirable solutions (#1847).

  Typically, the code affected by this bug is a call chain that contains an argument list with a large collection literal, as in:

  // Before:
  await MethodChannelContainer()
      .onMethodChannelInvoke("reportCrash", <String, dynamic>{
        "time": nowTime,
        "errorValue": errorName,
        "reason": reason,
        "stacktrace": stacktrace,
      });
  
  // After:
  await MethodChannelContainer().onMethodChannelInvoke(
    "reportCrash",
    <String, dynamic>{
      "time": nowTime,
      "errorValue": errorName,
      "reason": reason,
      "stacktrace": stacktrace,
    },
  );
  

• Prefer to split call chains for single-element targets (#1732).

  When formatting a method call chain whose target can also split, the formatter must decide whether to split the target or the call chain (or both). For example:

  // Split target:
  function(
    argument,
  ).method().another();
  
  // Or split chain:
  function(argument)
      .method()
      .another();
  

  We've tried various heuristics for this over the years but most make some code look better while making other code look worse. This version introduces a relatively simple rule that seems to work well in practice: If the call chain target has only one element or argument, then prefer to split the call chain and keep the target together. So in the above example, if prefers the second output.

• Allow block formatting parameter lists (#1693). The formatter supports "block formatting" for most bracket-delimited constructs in the language. This is what enables a multi-line list literal in an assignment to look like this:

  variable = [
    some,
    list,
    elements,
  ];
  

  Instead of:

  variable =
      [
        some,
        list,
        elements,
      ];
  

  This style applies to most language constructs, but function parameter lists were omitted. Now they are not. This rarely shows up in real code, except for typedefs of large function types:

  // Before:
  typedef DataViewBuilder<T> =
      Widget Function(
        BuildContext context,
        PagingState<int, T> state,
        NextPageCallback fetchNextPage,
      );
  
  // After:
  typedef DataViewBuilder<T> = Widget Function(
    BuildContext context,
    PagingState<int, T> state,
    NextPageCallback fetchNextPage,
  );
  

• Allow as, is, and is! expressions to be block formatted (#1542).

  // Before:
  variable =
      function(
            argument,
            argument,
            argument,
          )
          as Type;
  
  // After:
  variable = function(
    argument,
    argument,
    argument,
  ) as Type;
  

• Separate imports into sections (#1120). Following the guidelines in "Effective Dart", the formatter inserts a blank line between "dart:", "package:", and other imports:

  // Before:
  import 'dart:io';
  import 'dart:math';
  import 'package:args/args.dart';
  import 'package:test/test.dart';
  import 'my_library.dart';
  
  // After:
  import 'dart:io';
  import 'dart:math';
  
  import 'package:args/args.dart';
  import 'package:test/test.dart';
  
  import 'my_library.dart';
  

• In if-case statements and elements, split the guard if the pattern block-splits (#1596).

  This tends to lead to code where the pattern is kept on one line and the guard splits:

  // Before:
  if (expression case SomeClass(
    property: var x,
  ) when guardClause(x)) {
    ...
  }
  
  // After:
  if (expression case SomeClass(property: var x)
      when guardClause(x)) {
    ...
  }
  

• When no solution fits the page width, prefer solutions where the overflowing lines have trailing string literals or comments (#1802, #1803, #1837).

  Sometimes the formatter is unable to split the code in a way that fits it all within the page width. When this happens, the formatter prefers whatever solution has the fewest overflowing characters.

  In practice, overflowing solutions are usually caused by long string literals or comments that the user should split manually. To help the user do that, the formatter now treats overflowing characters caused by trailing string literals, comments, and a few other things that often follow a string literal like ,, ;, () {, or () async {, as "less bad" when comparing the amount of overflow between two solutions.

  The effect is that when no solution fits, the formatter tends to prefer a solution with hanging strings or comments, which makes it clearer to the user which code they need to go back and manually split.

  This change has no effect on code that does fit in the page width.

• Write a trailing comma in split extension type representation clauses when in a library whose language version allows it (#1845).

  Prior to Dart 3.13, extension type representation clauses didn't allow trailing commas even though they syntactically appear like formal parameter lists. In Dart 3.13, that was fixed, so now the formatter formats them the same way as other parameter lists in primary constructors.

Internal changes

• Require analyzer: ^13.1.0.

• Require analyzer: ^13.0.0

• Require analyzer: ^13.0.0.

Style changes

• Format extension type representation clauses the same way primary constructor
  formal parameter lists are formatted. This rarely makes a difference but
  produces better formatting when the representation type is long and there are
  other clauses on the extension type, as in:

  // Before:
  extension type JSExportedDartFunction._(
    JSExportedDartFunctionRepType _jsExportedDartFunction
  )
      implements JSFunction {}
  // After:
  extension type JSExportedDartFunction._(
    JSExportedDartFunctionRepType _jsExportedDartFunction
  ) implements JSFunction {}

  This change is not language versioned. (The old style is always worse, and
  continuing to support it would add complexity to the formatter.)
• Force blank lines around a mixin or extension type declaration if it doesn't
  have a ; body:

  // Before:
  int above;
  extension type Inches(int x) {}
  mixin M {}
  int below;
  // After:
  int above;
  extension type Inches(int x) {}
  mixin M {}
  int below;

  The formatter already forces blank lines around class, enum, and extension
  declarations. Mixins and extension types were overlooked. This makes them
  consistent. This style change is language versioned and only affects
  libraries at 3.13 or higher.
  Note that the formatter allows classes and extension types whose body is ;
  to not have a blank line above or below them.

Internal changes

• Support upcoming Dart language version 3.13.
• Support formatting primary constructors.
• Require analyzer: '^12.0.0'.

Style changes

• Format extension type representation clauses the same way primary constructor formal parameter lists are formatted. This rarely makes a difference but produces better formatting when the representation type is long and there are other clauses on the extension type, as in:

  // Before:
  extension type JSExportedDartFunction._(
    JSExportedDartFunctionRepType _jsExportedDartFunction
  )
      implements JSFunction {}
  
  // After:
  extension type JSExportedDartFunction._(
    JSExportedDartFunctionRepType _jsExportedDartFunction
  ) implements JSFunction {}
  

  This change is not language versioned. (The old style is always worse, and continuing to support it would add complexity to the formatter.)

• Force blank lines around a mixin or extension type declaration if it doesn't have a ; body:

  // Before:
  int above;
  extension type Inches(int x) {}
  mixin M {}
  int below;
  
  // After:
  int above;
  
  extension type Inches(int x) {}
  
  mixin M {}
  
  int below;
  

  The formatter already forces blank lines around class, enum, and extension declarations. Mixins and extension types were overlooked. This makes them consistent. This style change is language versioned and only affects libraries at 3.13 or higher.

  Note that the formatter allows classes and extension types whose body is ; to not have a blank line above or below them.

Internal changes

• Support upcoming Dart language version 3.13.
• Support formatting primary constructors.
• Require analyzer: '^12.0.0'.

• Require analyzer: '>=10.0.0 <12.0.0'.

• Require analyzer: '>=10.0.0 <12.0.0'.

Style changes

• When trailing commas are preserved, don't insert a newline before the ; in
  an enum with members unless there actually is a trailing comma.
  (Fix by @Barbirosha.)

Internal changes

• Support upcoming Dart language version 3.12.
• Stop using experiment flags for features released in 3.10.
• Require sdk: ^3.10.0.

Style changes

• When trailing commas are preserved, don't insert a newline before the ; in an enum with members unless there actually is a trailing comma. (Fix by @Barbirosha.)

Internal changes

• Support upcoming Dart language version 3.12.
• Stop using experiment flags for features released in 3.10.
• Require sdk: ^3.10.0.

• Support upcoming Dart language version 3.11.

• Support upcoming Dart language version 3.11.

• Remove dependencies on analyzer internal implementation.
• Require analyzer: '^10.0.0'.

• Remove dependencies on analyzer internal implementation.
• Require analyzer: '^10.0.0'.

• No longer format imports with configurations and a prefix in the wrong order.
  The parser used to accept this without error even though it violated the
  language spec. The parser is being fixed, so the formatter will no longer
  accept or format code like:

  import 'foo.dart' as prefix if (cond) 'bar.dart';

• Don't force a space between ? and . if a null-aware element contains a
  dot shorthand.
• Require analyzer: '>=8.2.0 <10.0.0'.
• Require args: ^2.5.0.
• Require sdk: ^3.9.0.

Bug fixes

• Respect @dart= version comments when determining which >3.7 style to apply.
  The formatter correctly used those comments to switch between the old short
  and new tall style, but ignored them for language versioned style rule changes
  after 3.7. Now the language version of the file is consistently respected for
  all style rules (#1762).

• No longer format imports with configurations and a prefix in the wrong order. The parser used to accept this without error even though it violated the language spec. The parser is being fixed, so the formatter will no longer accept or format code like:

  import 'foo.dart' as prefix if (cond) 'bar.dart';
  

• Don't force a space between ? and . if a null-aware element contains a dot shorthand.

• Require analyzer: '>=8.2.0 <10.0.0'.

• Require args: ^2.5.0.

• Require sdk: ^3.9.0.

Bug fixes

• Respect @dart= version comments when determining which >3.7 style to apply. The formatter correctly used those comments to switch between the old short and new tall style, but ignored them for language versioned style rule changes after 3.7. Now the language version of the file is consistently respected for all style rules (#1762).

• Support dot shorthand syntax.
• Update to the latest package:analyzer.
• Enable language version 3.10.

Bug fixes

• Preserved trailing commas (trailing_commas: preserve) applies to record type annotations too (#1721).

Style changes

This change only applies to code whose language version is 3.10 or higher:

• When trailing_commas is preserve, preserve a trailing comma after the last enum constant when members are present (#1678, #1729).

  // Before formatting:
  enum { constant, ; member() {} }
  
  // After formatting at language version 3.9 or lower:
  enum {
    constant;
  
    member() {}
  }
  
  // After formatting at language version 3.10 or higher:
  enum {
    constant,
    ;
  
    member() {}
  }
  

  (Thanks to jellynoone@ for this change.)

• Update to latest analyzer and enable language version 3.9.

This release contains a fairly large number of style changes in response to feedback we got from shipping the new tall style formatter.

Features

• Allow preserving trailing commas and forcing the surrounding construct to split even when it would otherwise fit on one line. This is off by default (because it breaks reversibility among other reasons) but can be enabled by adding this to a surrounding analysis_options.yaml file:

  formatter:
    trailing_commas: preserve
  

  This is similar to how trailing commas work in the old short style formatter applied to code before language version 3.7.

Bug fixes

• Don't add a trailing comma in lists that don't allow it, even when there is a trailing comment (#1639).

Style changes

The following style changes are language versioned and only affect code whose language version is 3.8 or later. Dart code at 3.7 or earlier is formatted the same as it was before.

• Allow more code on the same line as a named argument or => (#1536, #1545, #1668, #1679).

  // Before:
  function(
    name:
        (param, another) =>
            veryLongBody,
  );
  
  function(
    name:
        (param) => another(
          argument1,
          argument2,
          argument3,
        ),
  );
  
  // After:
  function(
    name: (param, another) =>
        veryLongBody,
  );
  
  function(
    name: (param) => another(
      argument1,
      argument2,
      argument3,
    ),
  );
  

• Avoid splitting chains containing only properties.

  // Before:
  variable = target
      .property
      .another;
  
  // After:
  variable =
      target.property.another;
  

  Note that this only applies to . chains that are only properties. If there are method calls in the chain, then it prefers to split the chain instead of splitting at =, :, or =>.

• Allow the target or property chain part of a split method chain on the RHS of =, :, and => (#1466).

  // Before:
  variable =
      target.property
          .method()
          .another();
  
  // After:
  variable = target.property
      .method()
      .another();
  

• Allow the condition part of a split conditional expression on the RHS of =, :, and => (#1465).

  // Before:
  variable =
      condition
      ? longThenBranch
      : longElseBranch;
  
  // After:
  variable = condition
      ? longThenBranch
      : longElseBranch;
  

• Don't indent conditional branches redundantly after =, :, and =>.

  // Before:
  function(
    argument:
        condition
            ? thenBranch
            : elseBranch,
  )
  
  // After:
  function(
    argument:
        condition
        ? thenBranch
        : elseBranch,
  )
  

• Indent conditional branches past the operators (#1534).

  // Before:
  condition
      ? thenBranch +
          anotherOperand
      : elseBranch(
        argument,
      );
  
  // After:
  condition
      ? thenBranch +
            anotherOperand
      : elseBranch(
          argument,
        );
  

• Block format record types in typedefs (#1651):

  // Before:
  typedef ExampleRecordTypedef =
      (
        String firstParameter,
        int secondParameter,
        String thirdParameter,
        String fourthParameter,
      );
  
  // After:
  typedef ExampleRecordTypedef = (
    String firstParameter,
    int secondParameter,
    String thirdParameter,
    String fourthParameter,
  );
  

• Eagerly split argument lists whose contents are complex enough to be easier to read spread across multiple lines even if they would otherwise fit on a single line (#1660). The rules are basically:

  • If an argument list contains at least three named arguments, at least one of which must be directly in the argument list and at least one of which must be nested in an inner argument list, then force the outer one to split. We make an exception where a named argument whose expression is a simple number, Boolean, or null literal doesn't count as a named argument.

  • If a list, set, or map literal is the immediate expression in a named argument and contains any argument lists with a named argument, then force the collection to split.

  // Before:
  TabBar(tabs: [Tab(text: 'A'), Tab(text: 'B')], labelColor: Colors.white70);
  
  // After:
  TabBar(
    tabs: [
      Tab(text: 'A'),
      Tab(text: 'B'),
    ],
    labelColor: Colors.white70,
  );
  

• Handle trailing commas in for-loop updaters (#1354).
• Format || patterns like fallthrough cases in switch expressions (#1602).
• Handle comments and metadata before variables more gracefully (#1604).
• Ensure comment formatting is idempotent (#1606).
• Better indentation of leading comments on property accesses in binary operator operands (#1611).
• Don't crash on doc comments in local variable declarations (#1621).

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.

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.

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:

  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 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:

  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 apply a few fixes and hasn't been maintained in many years. The dart fix command is actively maintained, can apply all of the fixes that dart format --fix could apply and many many more.

  In order to avoid duplicate engineering effort, we decided to consolidate on dart fix as the one way to make automated changes that go beyond the simple formatting and style changes that dart format applies.

  The ability to apply fixes is also removed from the DartFormatter() library API.

• 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.

  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.

  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 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. 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 dartfmt (and dartformat) executable with the old CLI options. Now that almost everyone is using dart format, we have removed the old CLI and the old package executables.

  You can still run the formatter on the CLI through the package (for example, if you want to use a particular version of dart_style instead of the one bundled with your Dart SDK). But it now uses the exact same CLI options and arguments as the dart format command. You can invoke it with dart run dart_style:format <args...>.

• Treat the --stdin-name name as a path when inferring language version. When reading input on stdin, the formatter still needs to know what language version to parse the code as. If the --stdin-name option is set, then that is treated as a file path and the formatter looks for a package config surrounding that file path to infer the language version from.

  If you don't want that behavior, pass in an explicit language version using --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 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 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.

• Require package:analyzer >=6.5.0 <8.0.0.

• Allow passing a language version to DartFomatter(). Formatted code will be parsed at that version. If omitted, defaults to the latest version. In a future release, this parameter will become required.
• Allow opting out of formatting for a region of code using // dart format off and // dart format on comments. Note: This only works using the new tall style and requires passing the --enable-experiment=tall-style experiment flag (#361).
• Preserve type parameters on old-style function-typed formals that also use this. or super. (#1321).
• Correctly format imports with both as and if clauses (#1544).
• Remove temporary work around for analyzer 6.2.0 from dart_style 2.3.6.
• Require package:analyzer >=6.5.0 <7.0.0.

• Fix compile error when using dart_style with analyzer 6.2.0.

• Ensure switch expressions containing line comments split (#1404).
• Use language version 3.3 to parse so that code with extension types can be formatted.
• Support formatting the macro modifier when the macros experiment flag is passed.

• Add tall-style experiment flag to enable the in-progress unstable new formatting style (#1253).
• Format extension types.
• Normalize ignored whitespace and "escaped whitespace" on first line of multiline string literals (#1235).

• Always split enum declarations containing a line comment (#1254).
• Fix regression in splitting type annotations with library prefixes (#1249).
• Remove support for inline class since that syntax has changed.
• Add --enable-experiment command-line option to enable language experiments. The library API also supports this with DartFormatter.experimentFlags.

• Don't indent parameters that have metadata annotations. Instead, align them with the metadata and other parameters.
• Allow metadata annotations on parameters to split independently of annotations on other parameters (#1212).
• Don't split before . following a record literal (#1213).
• Don't force split on a line comment before a switch expression case (#1215).
• Require package:analyzer >=5.12.0 <7.0.0.
• Preserve ? on nullable empty record types (#1224).

• Hide --fix and related options in --help. The options are still there and supported, but are no longer shown by default. Eventually, we would like all users to move to using dart fix instead of dart format --fix.
• Don't indent || pattern operands in switch expression cases.
• Don't format sealed, interface, and final keywords on mixin declarations. The proposal was updated to no longer support them.
• Don't split before a single-section cascade following a record literal.
• Give records block-like formatting in argument lists (#1205).

New language features

• Format patterns and related features.
• Format record expressions and record type annotations.
• Format class modifiers base, final, interface, mixin, and sealed.
• Format inline class declarations.
• Format unnamed libraries.

Bug fixes and style changes

• Handle sync* and async* functions with => bodies.
• Fix bug where parameter metadata wouldn't always split when it should.
• Don't split after < in collection literals.
• Better indentation of multiline function types inside type argument lists.

Internal changes

• Use typed _visitFunctionOrMethodDeclaration instead of dynamically typed.
• Fix metadata test to not fail when record syntax makes whitespace between metadata annotation names and ( significant (sdk#50769).
• Require Dart 2.19.
• Require package:analyzer ^5.7.0.

• Format unnamed libraries.
• Require Dart 2.17.

• Unify how brace-delimited syntax is formatted. This is mostly an internal refactoring, but slightly changes how a type body containing only an inline block comment is formatted.
• Refactor Chunk to store split before text instead of after. This mostly does not affect the visible behavior of the formatter, but a few edge cases are handled slightly differently. These are all bug fixes where the previous behavior was unintentional. The changes are:
• Consistently discard blank lines between a { or [ and a subsequent comment. It used to do this before the { in type bodies, but not switch bodies, optional parameter sections, or named parameter sections.
• Don't allow splitting an empty class body.
• Allow splitting after an inline block comment in some places where it makes sense.
• Don't allow a line comment in an argument list to cause preceding arguments to be misformatted.
• Remove blank lines after a line comment at the end of a body.
• Require package:analyzer >=4.4.0 <6.0.0.

• Allow the latest version of package:analyzer.

• Format named arguments anywhere (#1072).
• Format enhanced enums (#1075).
• Format "super." parameters (#1091).

• Require package:analyzer version 2.6.0.
• Use NamedType instead of TypeName.

• Fix analyzer dependency constraint (#1051).

• Republish 2.0.3 as 2.1.1 in order to avoid users getting 2.1.0, which has a bad dependency constraint (#1051).

• Support generic function references and constructor tear-offs (#1028).

• Fix hang when reading from stdin (https://github.com/dart-lang/sdk/issues/46600).

• Don't unnecessarily split argument lists with /* */ comments (#837).
• Return correct exit code from FormatCommand when formatting stdin (#1035).
• Always split cascades with multiple sections (#1006).
• Don't indent cascades farther than their receiver method chains.
• Optimize line splitting cascades (#811).
• Split empty catch blocks with finally clauses (#1029).
• Split empty catch blocks with catches after them.
• Allow the latest version of package:analyzer.

• Support triple-shift >>> and >>>= operators (#992).
• Support non-function type aliases (#993).
• Correct constructor initializer indentation after required (#1010).

• Migrate to null safety.

• Add support for generic annotations.
• FormatCommand.run() now returns the value set in exitCode during formatting.

• Allow the latest version of package:analyzer.

• Allow the latest versions of package:args and package:pub_semver.

• Remove use of deprecated analyzer API and List constructor.
• Fix performance issue with constructors that have no initializer list.

• Allow analyzer version 0.41.x.

• Don't duplicate comments on chained if elements (#966).

• Preserve ? in initializing formal function-typed parameters (#960).

• Split help into verbose and non-verbose lists (#938).
• Don't crash when non-ASCII whitespace is trimmed (#901).
• Split all conditional expressions (?:) when they are nested (#927).
• Handle external and abstract fields and variables (#946).

• Change the path used in error messages when reading from stdin from "<stdin>" to "stdin". The former crashes on Windows since it is not a valid Windows pathname. To get the old behavior, pass --stdin-name=<stdin>.

• Restore command line output accidentally removed in 1.3.4.

• Add --fix-single-cascade-statements.
• Correctly handle var in --fix-function-typedefs (#826).
• Preserve leading indentation in fixed doc comments (#821).
• Split outer nested control flow elements (#869).
• Always place a blank line after script tags (#782).
• Don't add unneeded splits on if elements near comments (#888).
• Indent blocks in initializers of multiple-variable declarations.
• Update the null-aware subscript syntax from ?.[] to ?[].

• Support package:analyzer 0.39.0.

• Restore the code that publishes the dart-style npm package.
• Preserve comma after nullable function-typed parameters (#862).

• Fix crash in formatting complex method chains (#855).

• Add support for formatting extension methods (#830).
• Format ? in types.
• Format the late modifier.
• Format the required modifier.
• Better formatting of empty spread collections (#831).
• Don't force split before . when the target is parenthesized (#704).

• Format null assertion operators.
• Better formatting for invocation expressions inside method call chains.
• Support package:analyzer 0.38.0.

• Support package:analyzer 0.37.0.

• Better indentation of function expressions inside trailing comma argument lists. (Thanks a14@!)
• Avoid needless indentation on chained if-else elements (#813).

• Improve indentation of adjacent strings inside => functions.

• Properly format trailing commas in assertions.

• Improve indentation of adjacent strings. This fixes a regression introduced in 1.2.5 and hopefully makes adjacent strings generally look better.

  Adjacent strings in argument lists now format the same regardless of whether the argument list contains a trailing comma. The rule is that if the argument list contains no other strings, then the adjacent strings do not get extra indentation. This keeps them lined up when doing so is unlikely to be confused as showing separate independent string arguments.

  Previously, adjacent strings were never indented in argument lists without a trailing comma and always in argument lists that did. With this change, adjacent strings are still always indented in collection literals because readers are likely to interpret a series of unindented lines there as showing separate collection elements.

• Add support for spreads inside collections (#778).
• Add support for if and for elements inside collections (#779).
• Require at least Dart 2.1.0.
• Require analyzer 0.36.0.

• Update to latest analyzer package AST API.
• Tweak set literal formatting to follow other collection literals.