Update dependency dart_style to v3 #26

renovate · 2024-12-03T08:57:24Z

This PR contains the following updates:

Package	Type	Update	Change
dart_style	dependencies	major	`^1.3.3` -> `^3.0.0`

Release Notes

dart-lang/dart_style (dart_style)

`v3.0.0`

Compare Source

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.

`v2.3.7`

Compare Source

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.

`v2.3.6`

Compare Source

Fix compile error when using dart_style with analyzer 6.2.0.

`v2.3.5`

Compare Source

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.

`v2.3.4`

Compare Source

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

`v2.3.3`

Compare Source

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.

`v2.3.2`

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

`v2.3.1`

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

`v2.3.0`

Compare Source

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.

`v2.2.5`

Compare Source

Format unnamed libraries.
Require Dart 2.17.

`v2.2.4`

Compare Source

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.