testea/test-repo
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: revise commands.md (#10181)

Browse Source 
Co-authored-by: fisker Cheung <lionkay@gmail.com>
This commit is contained in:
Georgii Dolzhykovandfisker Cheung authored and GitHub committed 2021-02-02 22:43:43 +02:00
1 parent e024ec2d3f
commit 58173be8b8
1 file changed
+89 -65
Download Patch File Download Diff File Expand all files Collapse all files
commands.md
+89 -65
View File
@@ -1,20 +1,30 @@
The core of the algorithm is implemented in `doc-{printer,builders,utils,debug}.js`. The printer should use the basic formatting abstractions provided to construct a format when printing a node. Parts of the API only exist to be compatible with recast's previous API to ease migration, but over time we can clean it up.
The core of the algorithm is implemented in `src/document/doc-{printer,builders,utils}.js`. The printer uses the basic formatting abstractions provided to construct a format when printing a node.
The following commands are available:
## Prettier's intermediate representation: `Doc`
### group
A doc can be a string, an array of docs, or a command.
```ts
type GroupOpts = {
type Doc = string | Doc[] | DocCommand;
```
- _strings_ are printed directly as is (however for the algorithm to work properly they shouldn't contain line break characters)
- _arrays_ are used to concatenate a list of docs to be printed sequentially into a single doc
- `DocCommand` is any of the following:
### `group`
```ts
type GroupOptions = {
shouldBreak?: boolean;
expandedStates?: Doc[];
id?: symbol;
};
declare function group(doc: Doc, opts?: GroupOpts): Doc;
declare function group(doc: Doc, options?: GroupOptions): Doc;
```
Mark a group of items which the printer should try to fit on one line. This is the basic command to tell the printer when to break. Groups are usually nested, and the printer will try to fit everything on one line, but if it doesn't fit it will break the outermost group first and try again. It will continue breaking groups until everything fits (or there are no more groups to break).
A document can force parent groups to break by including `breakParent` (see below). A hard and literal line automatically include this so they always break parent groups. Breaks are propagated to all parent groups, so if a deeply nested expression has a hard break, everything will break. This only matters for "hard" breaks, i.e. newlines that are printed no matter what and can be statically analyzed.
A group is forced to break if it's created with the `shouldBreak` option set to `true` or if it includes [`breakParent`](#breakParent). A [hard](#hardline) and [literal](#literalline) line breaks automatically include this so they always break parent groups. Breaks are propagated to all parent groups, so if a deeply nested expression has a hard break, everything will break. This only matters for "hard" breaks, i.e. newlines that are printed no matter what and can be statically analyzed.
For example, an array will try to fit on one line:
@@ -36,17 +46,16 @@ However, if any of the items inside the array have a hard break, the array will
Functions always break after the opening curly brace no matter what, so the array breaks as well for consistent formatting. See [the implementation of `ArrayExpression`](#example) for an example.
### conditionalGroup
The `id` option can be used in [`ifBreak`](#ifBreak) checks.
### `conditionalGroup`
This should be used as **last resort** as it triggers an exponential complexity when nested.
```ts
type ConditionalGroupOpts = {
shouldBreak?: boolean;
};
declare function conditionalGroup(
alternatives: Doc[],
opts?: ConditionalGroupOpts
options?: GroupOptions
): Doc;
```
@@ -56,89 +65,97 @@ This will try to print the first argument, if it fit use it, otherwise go to the
conditionalGroup([a, b, c]);
```
### fill
### `fill`
```ts
declare function fill(docs: Doc[]): Doc;
```
This is an alternative type of group which behaves like text layout: it's going to add a break whenever the next element doesn't fit in the line anymore. The difference with a typical group is that it's not going to break all the separators, just the ones that are at the end of lines.
This is an alternative type of group which behaves like text layout: it's going to add a break whenever the next element doesn't fit in the line anymore. The difference with [`group`](#group) is that it's not going to break all the separators, just the ones that are at the end of lines.
```js
fill(["I", line, "love", line, "prettier"]);
fill(["I", line, "love", line, "Prettier"]);
```
### ifBreak
Expects the `docs` argument to be an array of alternating content and line breaks. In other words, elements with odd indices must be line breaks (e.g., [`softline`](#softline)).
### `ifBreak`
```ts
declare function ifBreak(ifBreak: Doc, noBreak: Doc): Doc;
declare function ifBreak(
ifBreak: Doc,
noBreak?: Doc,
options?: { groupId?: symbol }
): Doc;
```
Prints something if the current group breaks and something else if it doesn't.
Print something if the current `group` or the current element of `fill` breaks and something else if it doesn't.
```js
ifBreak(";", " ");
```
### breakParent
`groupId` can be used to check another _already printed_ group instead of the current group.
### `breakParent`
```ts
declare var breakParent: Doc;
declare const breakParent: Doc;
```
Include this anywhere to force all parent groups to break. See `group` for more info. Example:
Include this anywhere to force all parent groups to break. See [`group`](#group) for more info. Example:
```js
group([" ", expr, " ", breakParent]);
```
### join
### `join`
```ts
declare function join(sep: Doc, docs: Doc[]): Doc;
```
Join an array of items with a separator.
Join an array of docs with a separator.
### line
### `line`
```ts
declare var line: Doc;
declare const line: Doc;
```
Specify a line break. If an expression fits on one line, the line break will be replaced with a space. Line breaks always indent the next line with the current level of indentation.
### softline
### `softline`
```ts
declare var softline: Doc;
declare const softline: Doc;
```
Specify a line break. The difference from `line` is that if the expression fits on one line, it will be replaced with nothing.
### hardline
### `hardline`
```ts
declare var hardline: Doc;
declare const hardline: Doc;
```
Specify a line break that is **always** included in the output, no matter if the expression fits on one line or not.
### literalline
### `literalline`
```ts
declare var literalline: Doc;
declare const literalline: Doc;
```
Specify a line break that is **always** included in the output, and don't indent the next line. This is used for template literals.
Specify a line break that is **always** included in the output and doesn't indent the next line. Also, unlike `hardline`, this kind of line break preserves trailing whitespace on the line it ends. This is used for template literals.
### lineSuffix
### `lineSuffix`
```ts
declare function lineSuffix(suffix: Doc): Doc;
```
This is used to implement trailing comments. In practice, it is not practical to find where the line ends and you don't want to accidentally print some code at the end of the comment. `lineSuffix` will buffer the output and flush it before any new line.
This is used to implement trailing comments. It's not practical to constantly check where the line ends to avoid accidentally printing some code at the end of a comment. `lineSuffix` buffers docs passed to it and flushes them before any new line.
```js
["a", lineSuffix(" // comment"), ";", hardline];
@@ -150,13 +167,13 @@ will output
a; // comment
```
### lineSuffixBoundary
### `lineSuffixBoundary`
```ts
declare var lineSuffixBoundary: Doc;
declare const lineSuffixBoundary: Doc;
```
In cases where you embed code inside of templates, comments shouldn't be able to leave the code part. lineSuffixBoundary is an explicit marker you can use to flush code in addition to newlines.
In cases where you embed code inside of templates, comments shouldn't be able to leave the code part. `lineSuffixBoundary` is an explicit marker you can use to flush the [`lineSuffix`](#lineSuffix) buffer in addition to line breaks.
```js
["{", lineSuffix(" // comment"), lineSuffixBoundary, "}", hardline];
@@ -177,7 +194,7 @@ and **not**
{} // comment
```
### indent
### `indent`
```ts
declare function indent(doc: Doc): Doc;
@@ -185,7 +202,7 @@ declare function indent(doc: Doc): Doc;
Increase the level of indentation.
### dedent
### `dedent`
```ts
declare function dedent(doc: Doc): Doc;
@@ -193,15 +210,15 @@ declare function dedent(doc: Doc): Doc;
Decrease the level of indentation. (Each `align` is considered one level of indentation.)
### align
### `align`
```ts
declare function align(n: number | string, doc: Doc): Doc;
```
This is similar to indent but it increases the level of indentation by a fixed number or a string.
Trailing alignments in indentation are still spaces, but middle ones are transformed into one tab per `align` when `useTabs` enabled.
If it's using in a whitespace-sensitive language, e.g. markdown, you should use `n` with string value to force print it.
Increase the indentation by a fixed number of spaces or a string. A variant of [`indent`](#indent).
When `useTabs` is enabled, trailing alignments in indentation are still spaces, but middle ones are transformed one tab per `align`. In a whitespace-sensitive context (e.g., Markdown), you should pass spaces to `align` as strings to prevent their replacement with tabs.
For example:
@@ -213,47 +230,64 @@ For example:
- `<indent><align 2><indent><align 2>` -> `<tab><tab><tab><2 space>`
- `<indent><align 4><indent><align 2>` -> `<tab><tab><tab><2 space>`
### markAsRoot
### `markAsRoot`
```ts
declare function markAsRoot(doc: Doc): Doc;
```
This marks the current indentation as root for `dedentToRoot` and `literalline`s.
Mark the current indentation as root for [`dedentToRoot`](#dedentToRoot) and [`literalline`](#literalline)s.
### dedentToRoot
### `dedentToRoot`
```ts
declare function dedentToRoot(doc: Doc): Doc;
```
This will dedent the current indentation to the root marked by `markAsRoot`.
Decrease the current indentation to the root marked by [`markAsRoot`](#markAsRoot).
### trim
### `trim`
```ts
declare var trim: Doc;
declare const trim: Doc;
```
This will trim any whitespace or tab character on the current line. This is used for preprocessor directives.
Trim all the indentation on the current line. This can be used for preprocessor directives. Should be placed after a line break.
### hardlineWithoutBreakParent and literallineWithoutBreakParent
### `hardlineWithoutBreakParent` and `literallineWithoutBreakParent`
These are used very rarely, for advanced formatting tricks.
_Added in v2.3.0_
```ts
declare const hardlineWithoutBreakParent: Doc;
declare const literallineWithoutBreakParent: Doc;
```
These are used very rarely, for advanced formatting tricks. Unlike their "normal" counterparts, they don't include an implicit (`breakParent`)[#breakParent].
Examples:
- `hardlineWithoutBreakParent` is used for printing tables in Prettier's Markdown printer. With `proseWrap` set to `never`, the columns are aligned only if none of the rows exceeds `printWidth`.
- `literallineWithoutBreakParent` (called `literalLineNoBreak` [there](https://github.com/prettier/plugin-ruby/blob/9e658db13d3f0524d816528e060b1381e0431559/src/ruby/nodes/heredocs.js)) is used in the [Ruby plugin](https://github.com/prettier/plugin-ruby) for printing heredoc syntax.
- `literallineWithoutBreakParent` is used in the [Ruby plugin](https://github.com/prettier/plugin-ruby) for [printing heredoc syntax](https://github.com/prettier/plugin-ruby/blob/b6e7bd6bc3f70de8f146aa58ad0c8310518bf467/src/ruby/nodes/heredocs.js).
### cursor
### `cursor`
```ts
declare var cursor: Doc;
declare const cursor: Doc;
```
This is a placeholder value where the cursor is in the original input in order to find where it would be printed.
### [Deprecated] `concat`
_This command has been deprecated in v2.3.0, use `Doc[]` instead_
```ts
declare function concat(docs: Doc[]): Doc;
```
Combine an array into a single doc.
## Example
For an example, here's the implementation of the `ArrayExpression` node type:
@@ -279,13 +313,3 @@ group(
```
This is a group with opening and closing brackets, and possibly indented contents. Because it's a `group` it will always be broken up if any of the sub-expressions are broken.
### [Deprecated] concat
> This command is deprecated, use `Doc[]` instead.
```ts
declare function concat(docs: Doc[]): Doc;
```
Combine an array into a single string.