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 |