Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(718)

Side by Side Diff: README.md

Issue 845443002: Get ready to publish 0.1.0. (Closed) Base URL: https://github.com/dart-lang/dart_style.git@master
Patch Set: Created 5 years, 11 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View unified diff | Download patch
« no previous file with comments | « no previous file | notes.txt » ('j') | notes.txt » ('J')
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
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
OLDNEW
« no previous file with comments | « no previous file | notes.txt » ('j') | notes.txt » ('J')

Powered by Google App Engine
This is Rietveld 408576698