vitalif
/
prettier
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Clarify when original styling is significant (#1620) 

* Clarify when original styling is significant

* add superscript "1" as footnote link

* use "*" instead of "1" to denote a caveat
master
Shaun LeBron 2017-05-17 23:03:52 -05:00 committed by Christopher Chedeau
parent 4e9cdc413c
commit 2fd7199c11
2 changed files with 20 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
README.md
View File

@ -33,7 +33,7 @@
Prettier is an opinionated JavaScript formatter inspired by
[refmt](https://facebook.github.io/reason/tools.html) with advanced
support for language features from [ES2017](https://github.com/tc39/proposals/blob/master/finished-proposals.md), [JSX](https://facebook.github.io/jsx/), and [Flow](https://flow.org/). It removes
all original styling and ensures that all outputted JavaScript
all original styling[\*](#styling-footnote) and ensures that all outputted JavaScript
conforms to a consistent style. (See this [blog post](http://jlongster.com/A-Prettier-Formatter))
If you are interested in the details, you can watch those two conference talks:
@ -49,7 +49,7 @@ formatted JavaScript as output.
In technical terms: Prettier parses your JavaScript into an AST (Abstract Syntax Tree) and
pretty-prints the AST, completely ignoring any of the original
formatting. Say hello to completely consistent syntax!
formatting[\*](#styling-footnote). Say hello to completely consistent syntax!
There's an extremely important piece missing from existing styling
tools: **the maximum line length**. Sure, you can tell ESLint to warn
@ -108,10 +108,17 @@ foo(
)
```
Prettier bans all custom styling by parsing it away and re-printing
Prettier bans all custom styling[\*](#styling-footnote) by parsing it away and re-printing
the parsed AST with its own rules that take the maximum line width
into account, wrapping code when necessary.
<a href="#styling-footnote" name="styling-footnote">\*</a>_Well actually, some
original styling is preserved when practical—see [empty lines] and [multi-line
objects]._
[empty lines]:Rationale.md#empty-lines
[multi-line objects]:Rationale.md#multi-line-objects
## Usage
Install:

10
Rationale.md
View File

@ -44,6 +44,16 @@ Prettier outputs the minimum number of parentheses required to ensure that the b
It turns out that empty lines are very hard to automatically generate. The approach that prettier takes is to preserve empty lines the way they were in the original source code. The only constraint is that prettier disallows several empty lines in a row. They are collapsed to a single one.
### Multi-line objects
It is tempting to collapse an object to a single line if it fits, but there are times when it is better for sibling/cousin keys to stay vertically aligned—see [object lists], [nested configs], [stylesheets], and [keyed methods]. To avoid unfavorable collapsing, prettier simply formats any object as multi-line if it appears as such in the original source code. This is the same strategy used by [elm-format] for multi-line records.
[object lists]:https://github.com/prettier/prettier/issues/74#issue-199965534
[nested configs]:https://github.com/prettier/prettier/issues/88#issuecomment-275448346
[stylesheets]:https://github.com/prettier/prettier/issues/74#issuecomment-275262094
[keyed methods]:https://github.com/prettier/prettier/pull/495#issuecomment-275745434
[elm-format]:https://github.com/prettier/prettier/issues/74#issuecomment-275621526
## What prettier is _not_ concerned about
Here are a few examples of things that are out of scope for prettier: