dart_style 1.1.3

  • README.md
  • CHANGELOG.md
  • Installing
  • Versions
  • 96

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.

Style fixes

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!");
}

Getting dartfmt

Dartfmt is included in the Dart SDK, so most users get it directly from there. That has the latest version of dartfmt that was available when the SDK was released.

If you want to make sure you are running the latest version of dartfmt, you can globally activate the package from the dart_style package on pub.dartlang.org:

$ pub global activate dart_style
$ dartfmt ...

For this to work, you need to put pub's bin directory on your PATH before the Dart SDL directory. Otherwise, the SDK's dartfmt will shadow this one.

If you don't want pub to put dartfmt on your PATH, you can run it explicitly:

$ pub global activate dart_style --no-executables
$ pub global run dart_style:format ...

Using dartfmt

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 dartfmt on the command line:

$ dartfmt test.dart

This command formats the test.dart file and writes the result to standard output.

Dartfmt 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. If no file or directory is specified, dartfmt reads from standard input.

By default, it formats each file and just prints the resulting code to stdout. If you pass -w, it overwrites your existing files with the formatted results.

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.

Validating files

If you want to use the formatter in something like a presubmit script or commit hook, you can use the -n dry run option. If you specify -n, the formatter prints the paths of the files whose contents would change if the formatter were run normally. If it prints no output, then everything is already correctly formatted.

Using the dart_style API

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() {
  var formatter = new DartFormatter();

  try {
    print(formatter.format("""
    library an_entire_compilation_unit;

    class SomeClass {}
    """));

    print(formatter.formatStatement("aSingle(statement);"));
  } on FormatterException catch (ex) {
    print(ex);
  }
}

Other resources

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

1.1.3

  • Preserve whitespace in multi-line strings inside string interpolations (#711). Note! This bug means that dart_style 1.1.2 may make semantics changes to your strings. You should avoid that version and use 1.1.3.

  • Set max SDK version to <3.0.0, and adjusted other dependencies.

1.1.2

  • Don't split inside string interpolations.

1.1.1

  • Format expressions in string interpolations (#226).
  • Apply fixes inside string interpolations (#707).

1.1.0

  • Add support for "style fixes", opt-in non-whitespace changes.
  • Add fix to convert : to = as the named parameter default value separator.
  • Add fix to remove new keywords.
  • Add fix to remove unneeded const keywords.
  • Uniformly format constructor invocations and other static method calls.
  • Don't crash when showing parse errors in Dart 2 mode (#697).

1.0.14

  • Support metadata on enum cases (#688).

1.0.13

  • Support the latest release of package:analyzer.

1.0.12

  • Fix another failure when running in Dart 2.

1.0.11

  • Fix cast failure when running in Dart 2.
  • Updated SDK version to 2.0.0-dev.17.0.
  • Force split in empty then block in if with an else (#680).

1.0.10

  • Don't split before . if the target expression is an argument list with a trailing comma (#548, #665).
  • Preserve metadata on for-in variables (#648).
  • Support optional new/const (#652).
  • Better formatting of initialization lists after trailing commas (#658).

1.0.9

  • Updated tests. No user-facing changes.

1.0.8

  • Support v1 of pkg/args.

1.0.7

  • Format multiline strings as block arguments (#570).
  • Fix call to analyzer API.
  • Support assert in initializer list experimental syntax (#522).

1.0.6

  • Support URIs in part-of directives (#615).

1.0.5

  • Support the latest version of pkg/analyzer.

1.0.4

  • Ensure formatter throws an exception instead of introducing non-whitespace changes. This sanity check ensures the formatter does not erase user code when the formatter itself contains a bug.
  • Preserve type arguments in generic typedefs (#619).
  • Preserve type arguments in function expression invocations (#621).

1.0.3

  • Preserve type arguments in generic function-typed parameters (#613).

1.0.2

  • Support new generic function typedef syntax (#563).

1.0.1

  • Ensure space between - and -- (#170).
  • Preserve a blank line between enum cases (#606).

1.0.0

  • Handle mixed block and arrow bodied function arguments uniformly (#500).
  • Don't add a spurious space after "native" (#541).
  • Handle parenthesized and immediately invoked functions in argument lists like other function literals (#566).
  • Preserve a blank line between an annotation and the first directive (#571).
  • Fix splitting in generic methods with => bodies (#584).
  • Allow splitting between a parameter name and type (#585).
  • Don't split after < when a collection is in statement position (#589).
  • Force a split if the cascade target has non-obvious precedence (#590).
  • Split more often if a cascade target contains a split (#591).
  • Correctly report unchanged formatting when reading from stdin.

0.2.16

  • Don't discard type arguments on method calls with closure arguments (#582).

0.2.15

  • Support covariant modifier on methods.

0.2.14

  • Update to analyzer 0.29.3. This should make dart_style a little more resilient to breaking changes in analyzer that add support for new syntax that dart_style can't format yet.

0.2.13

  • Support generic method parameters as well as arguments.

0.2.12

  • Add support for assert() in constructor initializers.
  • Correctly indent the right-hand side of is and as expressions.
  • Avoid splitting in index operators when possible.
  • Support generic methods (#556).

0.2.11+1

  • Fix test to not depend on analyzer error message.

0.2.11

  • Widen dependency on analyzer to allow 0.29.x.

0.2.10

  • Handle metadata annotations before parameters with trailing commas (#520).
  • Always split enum declarations if they end in a trailing comma (#529).
  • Add --set-exit-if-changed to set the exit code on a change (#365).

0.2.9

  • Require analyzer 0.27.4, which makes trailing commas on by default.

0.2.8

  • Format parameter lists with trailing commas like argument lists (#447).

0.2.7

  • Make it strong mode clean.
  • Put labels on their own line (#43).
  • Gracefully handle IO errors when failing to overwrite a file (#473).
  • Add a blank line after local functions, to match top level ones (#488).
  • Improve indentation in non-block-bodied control flow statements (#494).
  • Better indentation on very long return types (#503).
  • When calling from JS, guess at which error to show when the code cannot be parsed (#504).
  • Force a conditional operator to split if the condition does (#506).
  • Preserve trailing commas in argument and parameter lists (#509).
  • Split arguments preceded by comments (#511).
  • Remove newlines after script tags (#513).
  • Split before a single named argument if the argument itself splits (#514).
  • Indent initializers in multiple variable declarations.
  • Avoid passing an invalid Windows file URI to analyzer.
  • Always split comma-separated sequences that contain a trailing comma.

0.2.6

  • Support deploying an npm package exporting a formatCode method.

0.2.4

  • Better handling for long collections with comments (#484).

0.2.3

  • Support messages in assert() (#411).
  • Don't put spaces around magic generic method annotation comments (#477).
  • Always put member metadata annotations on their own line (#483).
  • Indent functions in named argument lists with non-functions (#478).
  • Force the parameter list to split if a split occurs inside a function-typed parameter.
  • Don't force a split for before a single named argument if the argument itself splits.

0.2.2

  • Upgrade to analyzer 0.27.0.
  • Format configured imports and exports.

0.2.1

  • --version command line argument (#240).
  • Split the first . in a method chain if the target splits (#255).
  • Don't collapse states that differ by unbound rule constraints (#424).
  • Better handling for functions in method chains (#367, #398).
  • Better handling of large parameter metadata annotations (#387, #444).
  • Smarter splitting around collections in named parameters (#394).
  • Split calls if properties in a chain split (#399).
  • Don't allow splitting inside empty functions (#404).
  • Consider a rule live if it constrains a rule in the overflow line (#407).
  • Allow splitting in prefix expressions (#410).
  • Correctly constrain collections in argument lists (#420, #463, #465).
  • Better indentation of collection literals (#421, #469).
  • Only show a hidden directory once in the output (#428).
  • Allow splitting between type and variable name (#429, #439, #454).
  • Better indentation for binary operators in => bodies (#434.
  • Tweak splitting around assignment (#436, #437).
  • Indent multi-line collections in default values (#441).
  • Don't drop metadata on part directives (#443).
  • Handle if statements without curly bodies better (#448).
  • Handle loop statements without curly bodies better (#449).
  • Allow splitting before get and set (#462).
  • Add --indent to specify leading indent (#464).
  • Ensure collection elements line split separately (#474).
  • Allow redirecting constructors to wrap (#475).
  • Handle index expressions in the middle of call chains.
  • Optimize splitting lines with many rules.

0.2.0

  • Treat functions nested inside function calls like block arguments (#366).

0.2.0-rc.4

  • Smarter indentation for function arguments (#369).

0.2.0-rc.3

  • Optimize splitting complex lines (#391).

0.2.0-rc.2

  • Allow splitting between adjacent strings (#201).
  • Force multi-line comments to the next line (#241).
  • Better splitting in metadata annotations in parameter lists (#247).
  • New optimized line splitter (#360, #380).
  • Allow splitting after argument name (#368).
  • Parsing a statement fails if there is unconsumed input (#372).
  • Don't force for fully split if initializers or updaters do (#375, #377).
  • Split before deferred (#381).
  • Allow splitting on as and is expressions (#384).
  • Support null-aware operators (?., ??, and ??=) (#385).
  • Allow splitting before default parameter values (#389).

0.2.0-rc.1

  • BREAKING: The indent argument to new DartFormatter() is now a number of spaces, not indentation levels.

  • This version introduces a new n-way constraint system replacing the previous binary constraints. It's mostly an internal change, but allows us to fix a number of bugs that the old solver couldn't express solutions to.

    In particular, it forces argument and parameter lists to go one-per-line if they don't all fit in two lines. And it allows function and collection literals inside expressions to indent like expressions in some contexts. (#78, #97, #101, #123, #139, #141, #142, #143, et. al.)

  • Indent cascades more deeply when the receiver is a method call (#137).

  • Preserve newlines in collections containing line comments (#139).

  • Allow multiple variable declarations on one line if they fit (#155).

  • Prefer splitting at "." on non-identifier method targets (#161).

  • Enforce a blank line before and after classes (#168).

  • More precisely control newlines between declarations (#173).

  • Preserve mandatory newlines in inline block comments (#178).

  • Splitting inside type parameter and type argument lists (#184).

  • Nest blocks deeper inside a wrapped conditional operator (#186).

  • Split named arguments if the positional arguments split (#189).

  • Re-indent line doc comments even if they are flush left (#192).

  • Nest cascades like expressions (#200, #203, #205, #221, #236).

  • Prefer splitting after => over other options (#217).

  • Nested non-empty collections force surrounding ones to split (#223).

  • Allow splitting inside with and implements clauses (#228, #259).

  • Allow splitting after = in a constructor initializer (#242).

  • If a => function's parameters split, split after the => too (#250).

  • Allow splitting between successive index operators (#256).

  • Correctly indent wrapped constructor initializers (#257).

  • Set failure exit code for malformed input when reading from stdin (#359).

  • Do not nest blocks inside single-argument function and method calls.

  • Do nest blocks inside => functions.

0.1.8+2

  • Allow using analyzer 0.26.0-alpha.0.

0.1.8+1

  • Use the new test package runner internally.

0.1.8

  • Update to latest analyzer and args packages.
  • Allow cascades with repeated method names to be one line.

0.1.7

  • Update to latest analyzer (#177).
  • Don't discard annotations on initializing formals (#197).
  • Optimize formatting deeply nested expressions (#108).
  • Discard unused nesting level to improve performance (#108).
  • Discard unused spans to improve performance (#108).
  • Harden splits that contain too much nesting (#108).
  • Try to avoid splitting single-element lists (#211).
  • Avoid splitting when the first argument is a function expression (#211).

0.1.6

  • Allow passing in selection to preserve through command line (#194).

0.1.5+1, 0.1.5+2, 0.1.5+3

  • Fix test files to work in main Dart repo test runner.

0.1.5

  • Change executable name from dartformat to dartfmt.

0.1.4

  • Don't mangle comma after function-typed initializing formal (#156).
  • Add --dry-run option to show files that need formatting (#67).
  • Try to avoid splitting in before index argument (#158, #160).
  • Support await for statements (#154).
  • Don't delete commas between enum values with doc comments (#171).
  • Put a space between nested unary - calls (#170).
  • Allow -t flag to preserve compatibility with old formatter (#166).
  • Support --machine flag for machine-readable output (#164).
  • If no paths are provided, read source from stdin (#165).

0.1.3

  • Split different operators with the same precedence equally (#130).
  • No spaces for empty for loop clauses (#132).
  • Don't touch files whose contents did not change (#127).
  • Skip formatting files in hidden directories (#125).
  • Don't include trailing whitespace when preserving selection (#124).
  • Force constructor initialization lists to their own line if the parameter list is split across multiple lines (#151).
  • Allow splitting in index operator calls (#140).
  • Handle sync* and async* syntax (#151).
  • Indent the parameter list more if the body is a wrapped "=>" (#144).

0.1.2

  • Move split conditional operators to the beginning of the next line.

0.1.1

  • Support formatting enums (#120).
  • Handle Windows line endings in multiline strings (#126).
  • Increase nesting for conditional operators (#122).

Use this package as an executable

1. Install it

You can install the package from the command line:


$ pub global activate dart_style

2. Use it

The package has the following executables:


$ dartfmt
$ dartformat

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  dart_style: "^1.1.3"

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter packages get

Alternatively, your editor might support pub get or flutter packages get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


      import 'package:dart_style/dart_style.dart';
  
Version Uploaded Documentation Archive
1.1.3 Jul 17, 2018 Go to the documentation of dart_style 1.1.3 Download dart_style 1.1.3 archive
1.1.2 Jul 6, 2018 Go to the documentation of dart_style 1.1.2 Download dart_style 1.1.2 archive
1.1.1 Jun 27, 2018 Go to the documentation of dart_style 1.1.1 Download dart_style 1.1.1 archive
1.1.0 Jun 18, 2018 Go to the documentation of dart_style 1.1.0 Download dart_style 1.1.0 archive
1.0.14 May 15, 2018 Go to the documentation of dart_style 1.0.14 Download dart_style 1.0.14 archive
1.0.13 May 14, 2018 Go to the documentation of dart_style 1.0.13 Download dart_style 1.0.13 archive
1.0.12 Apr 30, 2018 Go to the documentation of dart_style 1.0.12 Download dart_style 1.0.12 archive
1.0.11 Apr 24, 2018 Go to the documentation of dart_style 1.0.11 Download dart_style 1.0.11 archive
1.0.10 Feb 22, 2018 Go to the documentation of dart_style 1.0.10 Download dart_style 1.0.10 archive
1.0.9+1 Feb 2, 2018 Go to the documentation of dart_style 1.0.9+1 Download dart_style 1.0.9+1 archive

All 55 versions...

Analysis

We analyzed this package on Jul 17, 2018, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.0.0-dev.63.0
  • pana: 0.11.3

Scores

Popularity:
Describes how popular the package is relative to other packages. [more]
92 / 100
Health:
Code health derived from static analysis. [more]
100 / 100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100 / 100
Overall score:
Weighted score of the above. [more]
96
Learn more about scoring.

Platforms

Detected platforms: Flutter, web, other

No platform restriction found in primary library package:dart_style/dart_style.dart.

Suggestions

  • The description is too short.

    Add more detail about the package, what it does and what is its target use case. Try to write at least 60 characters.

  • Fix analysis and formatting issues.

    Analysis or formatting checks reported 8 hints.

    Strong-mode analysis of lib/src/debug.dart gave the following hint:

    line: 39 col: 7
    The top level variable '_cyan' isn't used.

    Strong-mode analysis of lib/src/fast_hash.dart gave the following hint:

    line: 20 col: 11
    Always override hashCode if overriding ==.

    Similar analysis of the following files failed:

    • lib/src/source_visitor.dart (hint)
  • Maintain an example.

    None of the files in your example/ directory matches a known example patterns. Common file name patterns include: main.dart, example.dart or you could also use dart_style.dart.

  • Enable strong mode analysis.

    Strong mode helps you to detect bugs and potential issues earlier.Start your analysis_options.yaml file with the following:

    analyzer:
      strong-mode: true
    

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.0.0-dev.62.0 <3.0.0
analyzer >0.31.2-alpha.0 <0.33.0 0.32.3
args >=0.12.1 <2.0.0 1.4.3
path ^1.0.0 1.6.1
source_span ^1.4.0 1.4.0
Transitive dependencies
charcode 1.1.2
collection 1.14.10
convert 2.0.1
crypto 2.0.6
csslib 0.14.4+1
front_end 0.1.3
glob 1.1.6
html 0.13.3+1
kernel 0.3.3
logging 0.11.3+1
meta 1.1.5
package_config 1.0.3
plugin 0.2.0+2
string_scanner 1.0.2
typed_data 1.1.5
utf 0.9.0+5
watcher 0.9.7+9
Dev dependencies
async >=1.0.0 <=3.0.0 2.0.7
browser ^0.10.0
grinder ^0.8.0
js ^0.6.0
node_preamble ^1.0.0
pub_semver ^1.2.3
test ^1.2.0
test_descriptor ^1.0.0
test_process ^1.0.0
yaml ^2.0.0 2.1.14