| OLD | NEW |
| 1 The dart_style package defines an automatic, opinionated formatter for Dart | 1 The dart_style package defines an automatic, opinionated formatter for Dart |
| 2 code. It replaces the whitespace in your program with what it deems to be the | 2 code. It replaces the whitespace in your program with what it deems to be the |
| 3 best formatting for it. Resulting code should following the [Dart style guide][] | 3 best formatting for it. Resulting code should following the [Dart style guide][] |
| 4 but, moreso, should look nice to most human readers, most of the time. | 4 but, moreso, should look nice to most human readers, most of the time. |
| 5 | 5 |
| 6 It handles indentation, inline whitespace and (by far the most difficult), | 6 It handles indentation, inline whitespace and (by far the most difficult), |
| 7 intelligent line wrapping. It has no problems with nested collections, function | 7 intelligent line wrapping. It has no problems with nested collections, function |
| 8 expressions, long argument lists, or otherwise tricky code. | 8 expressions, long argument lists, or otherwise tricky code. |
| 9 | 9 |
| 10 **The formatter is at an alpha state right now. It does a good job on most code, | 10 **The formatter is at a beta state right now. It does a good job on most code, |
| 11 and I'd love to have you try it and report bugs, but it has known issues and its | 11 and I'd love to have you try it and [report bugs][bugs], but its output may |
| 12 output will change over time.** | 12 change over time.** |
| 13 | 13 |
| 14 ## Running it | 14 ## Running it |
| 15 | 15 |
| 16 The package exposes a simple command-line wrapper around the core formatting | 16 The package exposes a simple command-line wrapper around the core formatting |
| 17 library. The easiest way to invoke it is to [globally activate][] the package | 17 library. The easiest way to invoke it is to [globally activate][] the package |
| 18 and let pub put its executable on your path: | 18 and let pub put its executable on your path: |
| 19 | 19 |
| 20 $ pub global activate dart_style | 20 $ pub global activate dart_style |
| 21 $ dartformat ... | 21 $ dartformat ... |
| 22 | 22 |
| 23 If you don't want `dartformat` on your path, you can run it explicitly: | 23 If you don't want `dartformat` on your path, you can run it explicitly: |
| 24 | 24 |
| 25 $ pub global activate dart_style --no-executables | 25 $ pub global activate dart_style --no-executables |
| 26 $ pub global run dart_style:format ... | 26 $ pub global run dart_style:format ... |
| 27 | 27 |
| 28 The formatter takes a list of paths, which can point to directories or files. | 28 The formatter takes a list of paths, which can point to directories or files. |
| 29 If the path is a directory, it processes every `.dart` file in that directory | 29 If the path is a directory, it processes every `.dart` file in that directory |
| 30 or any of its subdirectories. | 30 or any of its subdirectories. |
| 31 | 31 |
| 32 By default, it formats each file and just prints the resulting code to stdout. | 32 By default, it formats each file and just prints the resulting code to stdout. |
| 33 If you pass `-w`, it will instead overwrite your existing files with the | 33 If you pass `-w`, it will instead overwrite your existing files with the |
| 34 formatted results. | 34 formatted results. |
| 35 | 35 |
| 36 You may pass an `--line-length` option to control the width of the page that it | 36 You may pass a `--line-length` option to control the width of the page that it |
| 37 wraps lines to fit within, but you're strongly encouraged to keep the default | 37 wraps lines to fit within, but you're strongly encouraged to keep the default |
| 38 line length of 80 columns. | 38 line length of 80 columns. |
| 39 | 39 |
| 40 ## Using it programmatically | 40 ## Using it programmatically |
| 41 | 41 |
| 42 The package also exposes a single dart_style library containing a programmatic | 42 The package also exposes a single dart_style library containing a programmatic |
| 43 API for formatting code. Simple usage looks like this: | 43 API for formatting code. Simple usage looks like this: |
| 44 | 44 |
| 45 import 'package:dart_style/dart_style.dart'; | 45 import 'package:dart_style/dart_style.dart'; |
| 46 | 46 |
| 47 main() { | 47 main() { |
| 48 var formatter = new DartFormatter(); | 48 var formatter = new DartFormatter(); |
| 49 | 49 |
| 50 try { | 50 try { |
| 51 formatter.format(""" | 51 print(formatter.format(""" |
| 52 library an_entire_compilation_unit; | 52 library an_entire_compilation_unit; |
| 53 | 53 |
| 54 class SomeClass {} | 54 class SomeClass {} |
| 55 """); | 55 """)); |
| 56 | 56 |
| 57 formatter.formatStatement("aSingle(statement);"); | 57 print(formatter.formatStatement("aSingle(statement);")); |
| 58 } on FormatterException catch (ex) { | 58 } on FormatterException catch (ex) { |
| 59 print(ex); | 59 print(ex); |
| 60 } | 60 } |
| 61 } | 61 } |
| 62 | 62 |
| 63 [dart style guide]: https://www.dartlang.org/articles/style-guide/ | |
| 64 [globally activate]: https://www.dartlang.org/tools/pub/cmd/pub-global.html | |
| 65 | |
| 66 ## Stability | 63 ## Stability |
| 67 | 64 |
| 68 You can rely on the formatter to not break your code or change its semantics. | 65 You can rely on the formatter to not break your code or change its semantics. |
| 69 If it does do so, this is a critical bug and we'll fix it quickly. | 66 If it does do so, this is a critical bug and we'll fix it quickly. |
| 70 | 67 |
| 71 The heuristics the formatter uses to determine the "best" way to split a line | 68 The rules the formatter uses to determine the "best" way to split a line may |
| 72 are still being developed and may change over time. The ones today cover most | 69 change over time. We don't promise that code produced by the formatter today |
| 73 common uses, but there's room for more refinement. We don't promise that code | 70 will be identical to the same code run through a later version of the formatter. |
| 74 produced by the formatter today will be identical to the same code run through | 71 We do hope that you'll like the output of the later version more. |
| 75 a later version of the formatter. We do hope that you'll like the output of the | 72 |
| 76 later version more. | 73 [bugs]: https://github.com/dart-lang/dart_style/issues |
| 74 [dart style guide]: https://www.dartlang.org/articles/style-guide/ |
| 75 [globally activate]: https://www.dartlang.org/tools/pub/cmd/pub-global.html |
| OLD | NEW |