Layout overview
Added in v1.0.0
Table of contents
constructors
defaultOptions
The default layout options, which are suitable when you want to obtain output but do not care about the details.
Signature
export declare const defaultOptions: Layout.Options
Added in v1.0.0
options
Signature
export declare const options: (pageWidth: PageWidth) => Layout.Options
Added in v1.0.0
layout algorithms
compact
A layout algorithm which will lay out a document without adding any indentation and without preserving annotations.
Since no pretty-printing is involved, this layout algorithm is very fast. The resulting output contains fewer characters than a pretty-printed version and can be used for output that is read by other programs.
Signature
export declare const compact: <A>(self: Doc<A>) => DocStream<A>
Example
import * as Doc from "@effect/printer/Doc"
import { pipe } from "effect/Function"
import * as String from "effect/String"
const doc = pipe(
Doc.vsep([Doc.text("lorem"), Doc.text("ipsum"), pipe(Doc.vsep([Doc.text("dolor"), Doc.text("sit")]), Doc.hang(4))]),
Doc.hang(4)
)
assert.strictEqual(
Doc.render(doc, { style: "pretty" }),
String.stripMargin(
`|lorem
| ipsum
| dolor
| sit`
)
)
assert.strictEqual(
Doc.render(doc, { style: "compact" }),
String.stripMargin(
`|lorem
|ipsum
|dolor
|sit`
)
)
Added in v1.0.0
pretty
The pretty
layout algorithm is the default algorithm for rendering documents.
pretty
commits to rendering something in a certain way if the next element fits the layout constrants. In other words, it has one DocStream
element lookahead when rendering.
Consider using the smarter, but slightly less performant smart
algorithm if the results seem to run off to the right before having lots of line breaks.
Signature
export declare const pretty: {
(options: Layout.Options): <A>(self: Doc<A>) => DocStream<A>
<A>(self: Doc<A>, options: Layout.Options): DocStream<A>
}
Added in v1.0.0
smart
A layout algorithm with more look ahead than pretty
, which will introduce line breaks into a document earlier if the content does not, or will not, fit onto one line.
Signature
export declare const smart: {
(options: Layout.Options): <A>(self: Doc<A>) => DocStream<A>
<A>(self: Doc<A>, options: Layout.Options): DocStream<A>
}
Example
import * as Doc from "@effect/printer/Doc"
import type * as DocStream from "@effect/printer/DocStream"
import * as Layout from "@effect/printer/Layout"
import * as PageWidth from "@effect/printer/PageWidth"
import { pipe } from "effect/Function"
import * as String from "effect/String"
// Consider the following python-ish document:
const fun = <A>(doc: Doc.Doc<A>): Doc.Doc<A> =>
Doc.hcat([pipe(Doc.hcat([Doc.text("fun("), Doc.softLineBreak, doc]), Doc.hang(2)), Doc.text(")")])
const funs = <A>(doc: Doc.Doc<A>): Doc.Doc<A> => pipe(doc, fun, fun, fun, fun, fun)
const doc = funs(Doc.align(Doc.list(Doc.words("abcdef ghijklm"))))
// The document will be rendered using the following pipeline, where the choice
// of layout algorithm has been left open:
const pageWidth = PageWidth.availablePerLine(26, 1)
const layoutOptions = Layout.options(pageWidth)
const dashes = Doc.text(Array.from({ length: 26 - 2 }, () => "-").join(""))
const hr = Doc.hcat([Doc.vbar, dashes, Doc.vbar])
const render =
<A>(doc: Doc.Doc<A>) =>
(layoutAlgorithm: (options: Layout.Layout.Options) => (doc: Doc.Doc<A>) => DocStream.DocStream<A>): string =>
pipe(Doc.vsep([hr, doc, hr]), layoutAlgorithm(layoutOptions), Doc.renderStream)
// If rendered using `Layout.pretty`, with a page width of `26` characters per line,
// all the calls to `fun` will fit into the first line. However, this exceeds the
// desired `26` character page width.
assert.strictEqual(
render(doc)(Layout.pretty),
String.stripMargin(
`||------------------------|
|fun(fun(fun(fun(fun(
| [ abcdef
| , ghijklm ])))))
||------------------------|`
)
)
// The same document, rendered with `Layout.smart`, fits the layout contstraints:
assert.strictEqual(
render(doc)(Layout.smart),
String.stripMargin(
`||------------------------|
|fun(
| fun(
| fun(
| fun(
| fun(
| [ abcdef
| , ghijklm ])))))
||------------------------|`
)
)
// The key difference between `Layout.pretty` and `Layout.smart` is that the
// latter will check the potential document until it encounters a line with the
// same indentation or less than the start of the document. Any line encountered
// earlier is assumed to belong to the same syntactic structure. In contrast,
// `Layout.pretty` checks only the first line.
// Consider for example the question of whether the `A`s fit into the document
// below:
// > 1 A
// > 2 A
// > 3 A
// > 4 B
// > 5 B
// `pretty` will check only the first line, ignoring whether the second line
// may already be too wide. In contrast, `Layout.smart` stops only once it reaches
// the fourth line 4, where the `B` has the same indentation as the first `A`.
Added in v1.0.0
unbounded
The unbounded
layout algorithm will lay out a document an Unbounded
page width.
Signature
export declare const unbounded: <A>(self: Doc<A>) => DocStream<A>
Added in v1.0.0
wadlerLeijen
Signature
export declare const wadlerLeijen: {
<A>(fits: Layout.FittingPredicate<A>, options: Layout.Options): (self: Doc<A>) => DocStream<A>
<A>(self: Doc<A>, fits: Layout.FittingPredicate<A>, options: Layout.Options): DocStream<A>
}
Added in v1.0.0
model
Layout (interface)
Signature
export interface Layout<A> {
(options: Layout.Options): DocStream<A>
}
Added in v1.0.0
utils
Layout (namespace)
Added in v1.0.0
FittingPredicate (interface)
Decides whether a DocStream
fits the given constraints, namely:
- original indentation of the current column
- initial indentation of the alternative
DocStream
if it starts with a line break (used bylayoutSmart
) - width in which to fit the first line
Signature
export interface FittingPredicate<A> {
(stream: DocStream<A>, indentation: number, currentColumn: number, comparator: LazyArg<DocStream<A>>): boolean
}
Added in v1.0.0
Options (interface)
Represents the options that will influence the layout algorithms.
Signature
export interface Options {
readonly pageWidth: PageWidth
}
Added in v1.0.0