A pretty printing library
npm install prettier-printerA 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.




 
* 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
To be done.
In the meanwhile, read Philip Wadler's paper A prettier
printer.
Typically one imports the library as:
``jsx`
import * as PP from 'prettier-printer'
The examples also utilize Ramda, bound as R.
#### ≡ ▶ PP.render(maxCols, doc) ~> string v1.0.0
PP.render renders the document to a string trying to keep the width of the0
document within the specified maximum. A width of means that there is noPP.renderWith
maximum. See also .
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.PP.render
You can use this function to output the document without creating an
intermediate string of the whole document. See also .
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.group inPP.line
which case 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.group inPP.lineBreak
which case 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)
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
#### ≡ ▶ [PP.intersperse(doc, [...docs]) ~> [...docs]](#PP-intersperse) v1.0.0
PP.intersperse puts 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.punctuate concatenates 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' ]
#### ≡ ▶ PP.lazy(() => doc) ~> doc v1.0.0
PP.lazy creates a lazy document. The given thunk is only invoked as needed to
compute the document.
#### ≡ ▶ [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
#### ≡ ▶ PP.choice(wideDoc, narrowDoc) ~> doc v1.0.0
PP.choice(wideDoc, narrowDoc) renders as the given wideDoc on a line if itnarrowDoc
fits within the maximum width and otherwise as the .PP.lines and PP.lineBreaks within the wideDocPP.group
are undone like with .
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.lineBreaksPP.group(doc)
within the given document to be undone if the result fits within the maximum
width. is equivalent to PP.choice(doc, doc).
#### ≡ ▶ PP.nest(string | number, doc) ~> doc v1.0.0
PP.nest increases 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
#### ≡ ▶ PP.column(column => doc) ~> doc v1.0.0
PP.column allows 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.
#### ≡ ▶ PP.align(doc) ~> doc v1.0.0
PP.align creates 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.hang creates 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.indent creates 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.
* 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.