prettier-printer)

A pretty printing library for text documents that can be rendered to a desired
maximum width. Basic features:

* Interactive documentation (the ▶ links)
* Functional API:
* Referentially transparent functions
* Curried functions
* Supports tree-shaking
* TypeScript typings
* Contract checking in non-production builds
* MIT license

As an example, the evaluation output in this live
CodeSandbox example is formatted using
this library.

![npm version](http://badge.fury.io/js/prettier-printer)
![Bower version](https://badge.fury.io/bo/prettier-printer)
![Build Status](https://travis-ci.org/polytypic/prettier-printer)
![Code Coverage](https://codecov.io/github/polytypic/prettier-printer?branch=master)
![](https://david-dm.org/polytypic/prettier-printer) ![](https://david-dm.org/polytypic/prettier-printer?type=dev)

≡ ▶ Contents

* Tutorial
* Reference
* Rendering documents
* PP.render(maxCols, doc) ~> string ^v1.0.0
* PP.renderWith({text: (state, string) => state, line: state => state}, state, maxCols, doc) ~> state ^v1.0.0
* Document constants
* PP.line ~> doc ^v1.0.0
* PP.lineBreak ~> doc ^v1.0.0
* PP.softLine ~> doc ^v1.0.0
* PP.softBreak ~> doc ^v1.0.0
* Concatenating documents
* PP.append(rhsDoc, lhsDoc) ~> doc ^v1.0.0
* PP.prepend(lhsDoc, rhsDoc) ~> doc ^v1.0.0
* Lists of documents
* [PP.intersperse(doc, [...docs]) ~> [...docs]](#PP-intersperse) ^v1.0.0
* [PP.punctuate(sepDoc, [...docs]) ~> [...docs]](#PP-punctuate) ^v1.0.0
* Lazy documents
* PP.lazy(() => doc) ~> doc ^v1.0.0
* Enclosing documents
* [PP.enclose([lhsDoc, rhsDoc], doc) ~> doc](#PP-enclose) ^v1.0.0
* Document pair constants
* [PP.angles ~> ['<', '>']](#PP-angles) ^v1.0.0
* [PP.braces ~> ['{', '}']](#PP-braces) ^v1.0.0
* PP.brackets ~> ['[', ']'] ^v1.0.0
* [PP.dquotes ~> ['"', '"']](#PP-dquotes) ^v1.0.0
* [PP.lineBreaks ~> [PP.lineBreak, PP.lineBreak]](#PP-lineBreaks) ^v1.1.0
* [PP.lines ~> [PP.line, PP.line]](#PP-lines) ^v1.1.0
* [PP.parens ~> ['(', ')']](#PP-parens) ^v1.0.0
* [PP.spaces ~> [' ', ' ']](#PP-spaces) ^v1.0.0
* [PP.squotes ~> ["'", "'"]](#PP-squotes) ^v1.0.0
* Alternative documents
* PP.choice(wideDoc, narrowDoc) ~> doc ^v1.0.0
* PP.group(doc) ~> doc ^v1.0.0
* Nested documents
* PP.nest(string | number, doc) ~> doc ^v1.0.0
* Layout dependent documents
* PP.column(column => doc) ~> doc ^v1.0.0
* PP.nesting(nesting => doc) ~> doc ^v1.0.0
* Aligned documents
* PP.align(doc) ~> doc ^v1.0.0
* PP.hang(string | number, doc) ~> doc ^v1.0.0
* PP.indent(string | number, doc) ~> doc ^v1.0.0
* Related Work

≡ ▶ Tutorial

To be done.

In the meanwhile, read Philip Wadler's paper A prettier
printer.

≡ ▶ Reference

Typically one imports the library as:

``jsx import * as PP from 'prettier-printer'`

The examples also utilize Ramda, bound as R.

`$3`

#### ≡ ▶ PP.render(maxCols, doc) ~> string ^v1.0.0

PP.renderrenders the document to a string trying to keep the width of the document within the specified maximum. A width of0means that there is no maximum. See alsoPP.renderWith.

For example:

`js PP.render( 10, PP.indent('-- ', PP.group(PP.intersperse(PP.line, ['Hello,', 'world!']))) ) // -- Hello, // -- world!`

#### ≡ ▶ PP.renderWith({text: (state, string) => state, line: state => state}, state, maxCols, doc) ~> state ^v1.0.0

PP.renderWith renders the document with the given actions text and line. You can use this function to output the document without creating an intermediate string of the whole document. See alsoPP.render.

`$3`

Any string that doesn't contain '\n' or '\r'characters is considered as an atomic document. For example,'' is an empty document and ' ' is a space.

#### ≡ ▶ PP.line ~> doc ^v1.0.0

PP.line renders as a new line unless undone by PP.groupin which casePP.line renders as a space.

For example:

`js PP.render(20, ['Hello,', PP.line, 'world!']) // Hello, // world!`

`js PP.render(20, PP.group(['Hello,', PP.line, 'world!'])) // Hello, world!`

#### ≡ ▶ PP.lineBreak ~> doc ^v1.0.0

PP.lineBreak renders as a new line unless undone by PP.groupin which casePP.lineBreak renders as empty.

For example:

`js PP.render(20, ['Lol', PP.lineBreak, 'Bal']) // Lol // Bal`

`js PP.render(20, PP.group(['Lol', PP.lineBreak, 'Bal'])) // LolBal`

#### ≡ ▶ PP.softLine ~> doc ^v1.0.0

PP.softLine renders as a space if the output fits and otherwise as a new line.

For example:

`js PP.render( 20, PP.intersperse( PP.softLine, R.split( /\s+/, 'Here is a paragraph of text that we will format to a desired width.' ) ) ) // Here is a paragraph // of text that we will // format to a desired // width.`

#### ≡ ▶ PP.softBreak ~> doc ^v1.0.0

PP.softBreak renders as empty if the output fits and otherwise as a new line.

For example:

`js PP.render(10, PP.intersperse(PP.softBreak, R.split(/\b/, 'this.method(rocks)'))) // this. // method( // rocks)`

`$3`

An array of documents is considered as a concatenation of documents. For example,[] is an empty document and ['foo', 'bar']is equivalent to'foobar'.

#### ≡ ▶ PP.append(rhsDoc, lhsDoc) ~> doc ^v1.0.0

PP.append reverse concatenates the documents.

For example:

`js PP.render(0, PP.append('bar', 'foo')) // foobar`

#### ≡ ▶ PP.prepend(lhsDoc, rhsDoc) ~> doc ^v1.0.0

PP.prepend concatenates the documents.

For example:

`js PP.render(0, PP.prepend('foo', 'bar')) // foobar`

`$3`

#### ≡ ▶ [PP.intersperse(doc, [...docs]) ~> [...docs]](#PP-intersperse) ^v1.0.0

PP.intersperseputs the given separator document between each document in the given list of documents.

For example:

`js PP.intersperse(',', ['a', 'b', 'c']) // ['a', ',', 'b', ',', 'c']`

#### ≡ ▶ [PP.punctuate(sepDoc, [...docs]) ~> [...docs]](#PP-punctuate) ^v1.0.0

PP.punctuateconcatenates the given separator after each document in the given list of documents except the last.

For example:

`js PP.punctuate(',', ['a', 'b', 'c']) // [ [ 'a', ',' ], [ 'b', ',' ], 'c' ]`

`$3`

#### ≡ ▶ PP.lazy(() => doc) ~> doc ^v1.0.0

PP.lazycreates a lazy document. The given thunk is only invoked as needed to compute the document.

`$3`

#### ≡ ▶ [PP.enclose([lhsDoc, rhsDoc], doc) ~> doc](#PP-enclose) ^v1.0.0

PP.enclose encloses the given document between the given pair of documents.

For example:

`js PP.render(0, PP.enclose(PP.parens, 'foo')) // (foo)`

#### ≡ ▶ Document pair constants

##### ≡ ▶ [PP.angles ~> ['<', '>']](#PP-angles) ^v1.0.0

##### ≡ ▶ [PP.braces ~> ['{', '}']](#PP-braces) ^v1.0.0

##### ≡ ▶ PP.brackets ~> ['[', ']'] ^v1.0.0

##### ≡ ▶ [PP.dquotes ~> ['"', '"']](#PP-dquotes) ^v1.0.0

##### ≡ ▶ [PP.lineBreaks ~> [PP.lineBreak, PP.lineBreak]](#PP-lineBreaks) ^v1.1.0

##### ≡ ▶ [PP.lines ~> [PP.line, PP.line]](#PP-lines) ^v1.1.0

##### ≡ ▶ [PP.parens ~> ['(', ')']](#PP-parens) ^v1.0.0

##### ≡ ▶ [PP.spaces ~> [' ', ' ']](#PP-spaces) ^v1.0.0

##### ≡ ▶ [PP.squotes ~> ["'", "'"]](#PP-squotes) ^v1.0.0

`$3`

#### ≡ ▶ PP.choice(wideDoc, narrowDoc) ~> doc ^v1.0.0

PP.choice(wideDoc, narrowDoc) renders as the given wideDocon a line if it fits within the maximum width and otherwise as thenarrowDoc.PP.lines and PP.lineBreaks within the wideDocare undone like withPP.group.

For example:

`js PP.render(5, PP.choice('wide', 'narrow')) // 'wide'`

`js PP.render(3, PP.choice('wide', 'narrow')) // 'narrow'`

Note that usually the idea is that the narrow version can indeed be rendered more narrowly.

For example:

`js const hyphen = PP.choice('', ['-', PP.lineBreak])

PP.render(5, PP.intersperse(hyphen, ['hy', 'phen', 'at', 'ed'])) // hy- // phen- // ated`

#### ≡ ▶ PP.group(doc) ~> doc ^v1.0.0

PP.group allows PP.lines and PP.lineBreaks within the given document to be undone if the result fits within the maximum width.PP.group(doc) is equivalent to PP.choice(doc, doc).

`$3`

#### ≡ ▶ PP.nest(string | number, doc) ~> doc ^v1.0.0

PP.nestincreases the nesting after next new line by the given string or by the given number of spaces.

For example:

`js PP.render(6, PP.nest(2, PP.group(PP.intersperse(PP.line, ['foo', 'bar'])))) // foo // bar`

`$3`

#### ≡ ▶ PP.column(column => doc) ~> doc ^v1.0.0

PP.columnallows a document to depend on the column at which the document starts.

#### ≡ ▶ PP.nesting(nesting => doc) ~> doc ^v1.0.0

PP.nesting allows a document to depend on the nesting after the next new line.

`$3`

#### ≡ ▶ PP.align(doc) ~> doc ^v1.0.0

PP.aligncreates a document such that the nesting of the document is aligned to the current column.

For example:

`js PP.render(10, PP.group(['foo(', PP.align(['bar,', PP.line, 'baz']), ')'])) // foo(bar, // baz)`

#### ≡ ▶ PP.hang(string | number, doc) ~> doc ^v1.0.0

PP.hangcreates a document such that the document is nested by the given string or number of spaces starting from the current column.

For example:

`js PP.render(10, PP.group(['foo(', PP.hang(2, ['bar,', PP.line, 'baz']), ')'])) // foo(bar, // baz)`

#### ≡ ▶ PP.indent(string | number, doc) ~> doc ^v1.0.0

PP.indentcreates a document such that the document is indented by the given prefix or number of spaces starting from the current column.

`js PP.render( 20, PP.nest( 2, PP.group([ 'A comment:', PP.line, PP.line, PP.indent( '-- ', PP.intersperse( PP.softLine, R.split(/\s+/, 'This is the comment that you are looking for.') ) ) ]) ) ) // A comment: // // -- This is the // -- comment that // -- you are looking // -- for.``

≡ ▶ Related Work

* Philip Wadler's paper A prettier
printer
describes the basic ideas and implementation.
* Text.PrettyPrint.Leijen
is Daan Leijen's implementation with some extensions.
* Other prettier printer implementations by the author of this library:
* prettier
* PPrint
* text.pretty-printing
another JS implementation based on Wadler's paper. Marked as
"[Unmaintained]".
* Prettier uses a similar pretty printing library
underneath.

≡ ▶ Prettier Printer · ![GitHub stars](https://github.com/polytypic/prettier-printer) ![npm](https://www.npmjs.com/package/prettier-printer)

A pretty printing library for text documents that can be rendered to a desired
maximum width. Basic features:

As an example, the evaluation output in this live
CodeSandbox example is formatted using
this library.

≡ ▶ Contents

≡ ▶ Tutorial

To be done.

In the meanwhile, read Philip Wadler's paper A prettier
printer.

≡ ▶ Reference

Typically one imports the library as:

``jsx import * as PP from 'prettier-printer'`

The examples also utilize Ramda, bound as R.

`$3`

#### ≡ ▶ PP.render(maxCols, doc) ~> string ^v1.0.0

PP.renderrenders the document to a string trying to keep the width of the document within the specified maximum. A width of0means that there is no maximum. See alsoPP.renderWith.

For example:

`js PP.render( 10, PP.indent('-- ', PP.group(PP.intersperse(PP.line, ['Hello,', 'world!']))) ) // -- Hello, // -- world!`

#### ≡ ▶ PP.renderWith({text: (state, string) => state, line: state => state}, state, maxCols, doc) ~> state ^v1.0.0

`$3`

Any string that doesn't contain '\n' or '\r'characters is considered as an atomic document. For example,'' is an empty document and ' ' is a space.

#### ≡ ▶ PP.line ~> doc ^v1.0.0

PP.line renders as a new line unless undone by PP.groupin which casePP.line renders as a space.

For example:

`js PP.render(20, ['Hello,', PP.line, 'world!']) // Hello, // world!`

`js PP.render(20, PP.group(['Hello,', PP.line, 'world!'])) // Hello, world!`

#### ≡ ▶ PP.lineBreak ~> doc ^v1.0.0

PP.lineBreak renders as a new line unless undone by PP.groupin which casePP.lineBreak renders as empty.

For example:

`js PP.render(20, ['Lol', PP.lineBreak, 'Bal']) // Lol // Bal`

`js PP.render(20, PP.group(['Lol', PP.lineBreak, 'Bal'])) // LolBal`

#### ≡ ▶ PP.softLine ~> doc ^v1.0.0

PP.softLine renders as a space if the output fits and otherwise as a new line.

For example:

#### ≡ ▶ PP.softBreak ~> doc ^v1.0.0

PP.softBreak renders as empty if the output fits and otherwise as a new line.

For example:

`js PP.render(10, PP.intersperse(PP.softBreak, R.split(/\b/, 'this.method(rocks)'))) // this. // method( // rocks)`

`$3`

An array of documents is considered as a concatenation of documents. For example,[] is an empty document and ['foo', 'bar']is equivalent to'foobar'.

#### ≡ ▶ PP.append(rhsDoc, lhsDoc) ~> doc ^v1.0.0

PP.append reverse concatenates the documents.

For example:

`js PP.render(0, PP.append('bar', 'foo')) // foobar`

#### ≡ ▶ PP.prepend(lhsDoc, rhsDoc) ~> doc ^v1.0.0

PP.prepend concatenates the documents.

For example:

`js PP.render(0, PP.prepend('foo', 'bar')) // foobar`

`$3`

#### ≡ ▶ [PP.intersperse(doc, [...docs]) ~> [...docs]](#PP-intersperse) ^v1.0.0

PP.intersperseputs the given separator document between each document in the given list of documents.

For example:

`js PP.intersperse(',', ['a', 'b', 'c']) // ['a', ',', 'b', ',', 'c']`

#### ≡ ▶ [PP.punctuate(sepDoc, [...docs]) ~> [...docs]](#PP-punctuate) ^v1.0.0

PP.punctuateconcatenates the given separator after each document in the given list of documents except the last.

For example:

`js PP.punctuate(',', ['a', 'b', 'c']) // [ [ 'a', ',' ], [ 'b', ',' ], 'c' ]`

`$3`

#### ≡ ▶ PP.lazy(() => doc) ~> doc ^v1.0.0

PP.lazycreates a lazy document. The given thunk is only invoked as needed to compute the document.

`$3`

#### ≡ ▶ [PP.enclose([lhsDoc, rhsDoc], doc) ~> doc](#PP-enclose) ^v1.0.0

PP.enclose encloses the given document between the given pair of documents.

For example:

`js PP.render(0, PP.enclose(PP.parens, 'foo')) // (foo)`

#### ≡ ▶ Document pair constants

##### ≡ ▶ [PP.angles ~> ['<', '>']](#PP-angles) ^v1.0.0

##### ≡ ▶ [PP.braces ~> ['{', '}']](#PP-braces) ^v1.0.0

##### ≡ ▶ PP.brackets ~> ['[', ']'] ^v1.0.0

##### ≡ ▶ [PP.dquotes ~> ['"', '"']](#PP-dquotes) ^v1.0.0

##### ≡ ▶ [PP.lineBreaks ~> [PP.lineBreak, PP.lineBreak]](#PP-lineBreaks) ^v1.1.0

##### ≡ ▶ [PP.lines ~> [PP.line, PP.line]](#PP-lines) ^v1.1.0

##### ≡ ▶ [PP.parens ~> ['(', ')']](#PP-parens) ^v1.0.0

##### ≡ ▶ [PP.spaces ~> [' ', ' ']](#PP-spaces) ^v1.0.0

##### ≡ ▶ [PP.squotes ~> ["'", "'"]](#PP-squotes) ^v1.0.0

`$3`

#### ≡ ▶ PP.choice(wideDoc, narrowDoc) ~> doc ^v1.0.0

For example:

`js PP.render(5, PP.choice('wide', 'narrow')) // 'wide'`

`js PP.render(3, PP.choice('wide', 'narrow')) // 'narrow'`

Note that usually the idea is that the narrow version can indeed be rendered more narrowly.

For example:

`js const hyphen = PP.choice('', ['-', PP.lineBreak])

PP.render(5, PP.intersperse(hyphen, ['hy', 'phen', 'at', 'ed'])) // hy- // phen- // ated`

#### ≡ ▶ PP.group(doc) ~> doc ^v1.0.0

PP.group allows PP.lines and PP.lineBreaks within the given document to be undone if the result fits within the maximum width.PP.group(doc) is equivalent to PP.choice(doc, doc).

`$3`

#### ≡ ▶ PP.nest(string | number, doc) ~> doc ^v1.0.0

PP.nestincreases the nesting after next new line by the given string or by the given number of spaces.

For example:

`js PP.render(6, PP.nest(2, PP.group(PP.intersperse(PP.line, ['foo', 'bar'])))) // foo // bar`

`$3`

#### ≡ ▶ PP.column(column => doc) ~> doc ^v1.0.0

PP.columnallows a document to depend on the column at which the document starts.

#### ≡ ▶ PP.nesting(nesting => doc) ~> doc ^v1.0.0

PP.nesting allows a document to depend on the nesting after the next new line.

`$3`

#### ≡ ▶ PP.align(doc) ~> doc ^v1.0.0

PP.aligncreates a document such that the nesting of the document is aligned to the current column.

For example:

`js PP.render(10, PP.group(['foo(', PP.align(['bar,', PP.line, 'baz']), ')'])) // foo(bar, // baz)`

#### ≡ ▶ PP.hang(string | number, doc) ~> doc ^v1.0.0

PP.hangcreates a document such that the document is nested by the given string or number of spaces starting from the current column.

For example:

`js PP.render(10, PP.group(['foo(', PP.hang(2, ['bar,', PP.line, 'baz']), ')'])) // foo(bar, // baz)`

#### ≡ ▶ PP.indent(string | number, doc) ~> doc ^v1.0.0

PP.indentcreates a document such that the document is indented by the given prefix or number of spaces starting from the current column.