/**
* The abstract data type `Doc` represents prettified documents that have
* been annotated with data of type `A`.
*
* More specifically, a value of type `Doc` represents a non-empty set of
* possible layouts for a given document. The layout algorithms select one of
* these possibilities, taking into account variables such as the width of the
* document.
*
* The annotation is an arbitrary piece of data associated with (part of) a
* document. Annotations may be used by rendering algorithms to display
* documents differently by providing information such as:
* - color information (e.g., when rendering to the terminal)
* - mouseover text (e.g., when rendering to rich HTML)
* - whether to show something or not (to allow simple or detailed versions)
*
* @since 1.0.0
*/
import type * as covariant from "@effect/typeclass/Covariant"
import type * as invariant from "@effect/typeclass/Invariant"
import type { Monoid } from "@effect/typeclass/Monoid"
import type { Semigroup } from "@effect/typeclass/Semigroup"
import type { Equal } from "effect/Equal"
import type { TypeLambda } from "effect/HKT"
import type { Pipeable } from "effect/Pipeable"
import type { DocStream } from "./DocStream.js"
import type { Flatten } from "./Flatten.js"
import * as internal from "./internal/doc.js"
import * as InternalRender from "./internal/render.js"
import type { AvailablePerLine, PageWidth } from "./PageWidth.js"
// -----------------------------------------------------------------------------
// Models
// -----------------------------------------------------------------------------
/**
* @since 1.0.0
* @category symbol
*/
export const DocTypeId: unique symbol = internal.DocTypeId as DocTypeId
/**
* @since 1.0.0
* @category symbol
*/
export type DocTypeId = typeof DocTypeId
/**
* Represents a prettified document that has been annotated with data of type
* `A`.
*
* @since 1.0.0
* @category model
*/
export type Doc =
| Fail
| Empty
| Char
| Text
| Line
| FlatAlt
| Cat
| Nest
| Union
| Column
| WithPageWidth
| Nesting
| Annotated
/**
* @since 1.0.0
*/
export declare namespace Doc {
/**
* @since 1.0.0
* @category model
*/
export interface Variance extends Equal, Pipeable {
readonly [DocTypeId]: {
readonly _A: () => A
}
}
/**
* @since 1.0.0
*/
export type TypeLambda = DocTypeLambda
/**
* @since 1.0.0
* @category model
*/
export type RenderConfig = Compact | Pretty | Smart
/**
* @since 1.0.0
* @category model
*/
export interface Compact {
readonly style: "compact"
}
/**
* @since 1.0.0
* @category model
*/
export interface Pretty {
readonly style: "pretty"
readonly options?: Partial>
}
/**
* @since 1.0.0
* @category model
*/
export interface Smart {
readonly style: "smart"
readonly options?: Partial>
}
}
/**
* @since 1.0.0
* @category model
*/
export interface DocTypeLambda extends TypeLambda {
readonly type: Doc
}
/**
* Represents a document that cannot be rendered. Generally occurs when
* flattening a line. The layout algorithms will reject this document and choose
* a more suitable rendering.
*
* @since 1.0.0
* @category model
*/
export interface Fail extends Doc.Variance {
readonly _tag: "Fail"
}
/**
* Represents the empty document.
*
* Conceptually, the `Empty` document can be thought of as the unit of `Cat`.
*
* @since 1.0.0
* @category model
*/
export interface Empty extends Doc.Variance {
readonly _tag: "Empty"
}
/**
* Represents a document containing a single character.
*
* **Invariants**
* - Cannot be the newline (`"\n"`) character
*
* @since 1.0.0
* @category model
*/
export interface Char extends Doc.Variance {
readonly _tag: "Char"
readonly char: string
}
/**
* Represents a document containing a string of text.
*
* **Invariants**
* - Text cannot be less than two characters long
* - Text cannot contain a newline (`"\n"`) character
*
* @since 1.0.0
* @category model
*/
export interface Text extends Doc.Variance {
readonly _tag: "Text"
readonly text: string
}
/**
* Represents a document that contains a hard line break.
*
* @since 1.0.0
* @category model
*/
export interface Line extends Doc.Variance {
readonly _tag: "Line"
}
/**
* Represents a flattened alternative of two documents. The layout algorithms
* will choose the first document, but when flattened (via `group`) the second
* document will be preferreinternal.
*
* The layout algorithms operate under the assumption that the first alternative
* is less wide than the flattened second alternative.
*
* @since 1.0.0
* @category model
*/
export interface FlatAlt extends Doc.Variance {
readonly _tag: "FlatAlt"
readonly left: Doc
readonly right: Doc
}
/**
* Represents the concatenation of two documents.
*
* @since 1.0.0
* @category model
*/
export interface Cat extends Doc.Variance {
readonly _tag: "Cat"
readonly left: Doc
readonly right: Doc
}
/**
* Represents a document that is indented by a certain number of columns.
*
* @since 1.0.0
* @category model
*/
export interface Nest extends Doc.Variance {
readonly _tag: "Nest"
readonly indent: number
readonly doc: Doc
}
/**
* Represents the union of two documents. Used to implement layout alternatives
* for `group`.
*
* **Invariants**
* - The first lines of the first document should be longer than the first lines
* of the second document so that the layout algorithm can pick the document
* with the best fit.
*
* @since 1.0.0
* @category model
*/
export interface Union extends Doc.Variance {
readonly _tag: "Union"
readonly left: Doc
readonly right: Doc
}
/**
* Represents a document that reacts to the current cursor position.
*
* @since 1.0.0
* @category model
*/
export interface Column extends Doc.Variance {
readonly _tag: "Column"
readonly react: (position: number) => Doc
}
/**
* Represents a document that reacts to the current page width.
*
* @since 1.0.0
* @category model
*/
export interface WithPageWidth extends Doc.Variance {
readonly _tag: "WithPageWidth"
readonly react: (pageWidth: PageWidth) => Doc
}
/**
* Represents a document that reacts to the current page width.
*
* @since 1.0.0
* @category model
*/
export interface WithPageWidth extends Doc.Variance {
readonly _tag: "WithPageWidth"
readonly react: (pageWidth: PageWidth) => Doc
}
/**
* Represents a document that reacts to the current nesting level.
*
* @since 1.0.0
* @category model
*/
export interface Nesting extends Doc.Variance {
readonly _tag: "Nesting"
readonly react: (level: number) => Doc
}
/**
* Represents a document with an associated annotation.
*
* @since 1.0.0
* @category model
*/
export interface Annotated extends Doc.Variance {
readonly _tag: "Annotated"
readonly annotation: A
readonly doc: Doc
}
// -----------------------------------------------------------------------------
// Refinements
// -----------------------------------------------------------------------------
/**
* Returns `true` if the specified value is a `Doc`, `false` otherwise.
*
* @since 1.0.0
* @category refinements
*/
export const isDoc: (u: unknown) => u is Doc = internal.isDoc
/**
* Returns `true` if the specified `Doc` is a `Fail`, `false` otherwise.
*
* @since 1.0.0
* @category refinements
*/
export const isFail: (self: Doc) => self is Fail = internal.isFail
/**
* Returns `true` if the specified `Doc` is an `Empty`, `false` otherwise.
*
* @since 1.0.0
* @category refinements
*/
export const isEmpty: (self: Doc) => self is Empty = internal.isEmpty
/**
* Returns `true` if the specified `Doc` is a `Char`, `false` otherwise.
*
* @since 1.0.0
* @category refinements
*/
export const isChar: (self: Doc) => self is Char = internal.isChar
/**
* Returns `true` if the specified `Doc` is a `Text`, `false` otherwise.
*
* @since 1.0.0
* @category refinements
*/
export const isText: (self: Doc) => self is Text = internal.isText
/**
* Returns `true` if the specified `Doc` is a `Line`, `false` otherwise.
*
* @since 1.0.0
* @category refinements
*/
export const isLine: (self: Doc) => self is Line = internal.isLine
/**
* Returns `true` if the specified `Doc` is a `FlatAlt`, `false` otherwise.
*
* @since 1.0.0
* @category refinements
*/
export const isFlatAlt: (self: Doc) => self is FlatAlt = internal.isFlatAlt
/**
* Returns `true` if the specified `Doc` is a `Cat`, `false` otherwise.
*
* @since 1.0.0
* @category refinements
*/
export const isCat: (self: Doc) => self is Cat = internal.isCat
/**
* Returns `true` if the specified `Doc` is a `Nest`, `false` otherwise.
*
* @since 1.0.0
* @category refinements
*/
export const isNest: (self: Doc) => self is Nest = internal.isNest
/**
* Returns `true` if the specified `Doc` is a `Union`, `false` otherwise.
*
* @since 1.0.0
* @category refinements
*/
export const isUnion: (self: Doc) => self is Union = internal.isUnion
/**
* Returns `true` if the specified `Doc` is a `Column`, `false` otherwise.
*
* @since 1.0.0
* @category refinements
*/
export const isColumn: (self: Doc) => self is Column = internal.isColumn
/**
* Returns `true` if the specified `Doc` is a `WithPageWidth`, `false` otherwise.
*
* @since 1.0.0
* @category refinements
*/
export const isWithPageWidth = internal.isWithPageWidth
/**
* Returns `true` if the specified `Doc` is a `Nesting`, `false` otherwise.
*
* @since 1.0.0
* @category refinements
*/
export const isNesting: (self: Doc) => self is Nesting = internal.isNesting
/**
* Returns `true` if the specified `Doc` is a `Annotated`, `false` otherwise.
*
* @since 1.0.0
* @category refinements
*/
export const isAnnotated: (self: Doc) => self is Annotated = internal.isAnnotated
// -----------------------------------------------------------------------------
// Constructors
// -----------------------------------------------------------------------------
/**
* A document containing a single character.
*
* **Invariants**
* - Cannot be the newline (`"\n"`) character
*
* Control characters are preserved verbatim. Apply `sanitize` before rendering
* a document containing untrusted text to a terminal.
*
* @since 1.0.0
* @category constructors
*/
export const char: (char: string) => Doc = internal.char
/**
* A document containing a string of text.
*
* **Invariants**
* - Text cannot be less than two characters long
* - Text cannot contain a newline (`"\n"`) character
*
* Control characters are preserved verbatim. Apply `sanitize` before rendering
* a document containing untrusted text to a terminal.
*
* @since 1.0.0
* @category constructors
*/
export const text: (text: string) => Doc = internal.text
/**
* Constructs a document containing a string of text.
*
* **Note**: newline characters (`\n`) contained in the provided string will be
* disregarded (i.e. not rendered) in the output document.
*
* Control characters are preserved verbatim. Apply `sanitize` before rendering
* a document containing untrusted text to a terminal.
*
* @since 1.0.0
* @category constructors
*/
export const string: (str: string) => Doc = internal.string
// -----------------------------------------------------------------------------
// Primitives
// -----------------------------------------------------------------------------
/**
* The `empty` document behaves like a document containing the empty string
* (`""`), so it has a height of `1`.
*
* This may lead to surprising behavior if the empty document is expected to
* bear no weight inside certain layout functions, such as`vcat`, where it will
* render an empty line of output.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import * as String from "effect/String"
*
* const doc = Doc.vsep([
* Doc.text("hello"),
* // `parentheses` for visibility purposes only
* Doc.parenthesized(Doc.empty),
* Doc.text("world")
* ])
*
* const expected = `|hello
* |()
* |world`
*
* assert.strictEqual(
* Doc.render(doc, { style: "pretty" }),
* String.stripMargin(expected)
* )
* ```
*
* @since 1.0.0
* @category primitives
*/
export const empty: Doc = internal.empty
/**
* The `fail` document is a document that cannot be rendered.
*
* Generally occurs when flattening a line. The layout algorithms will reject
* this document and choose a more suitable rendering.
*
* @since 1.0.0
* @category primitives
*/
export const fail: Doc = internal.fail
/**
* The `line` document advances to the next line and indents to the current
* nesting level. However, `line` will behave like `space` if the line break is
* undone by `group`.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import * as String from "effect/String"
*
* const doc: Doc.Doc = Doc.hcat([
* Doc.text("lorem ipsum"),
* Doc.line,
* Doc.text("dolor sit amet")
* ])
*
* assert.strictEqual(
* Doc.render(doc, { style: "pretty" }),
* String.stripMargin(
* `|lorem ipsum
* |dolor sit amet`
* )
* )
* assert.strictEqual(
* Doc.render(Doc.group(doc), { style: "pretty" }),
* "lorem ipsum dolor sit amet"
* )
* ```
*
* @since 1.0.0
* @category primitives
*/
export const line: Doc = internal.line
/**
* The `lineBreak` document is like `line` but behaves like `empty` if the line
* break is undone by `group` (instead of `space`).
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import * as String from "effect/String"
*
* const doc: Doc.Doc = Doc.hcat([
* Doc.text("lorem ipsum"),
* Doc.lineBreak,
* Doc.text("dolor sit amet")
* ])
*
* assert.strictEqual(
* Doc.render(doc, { style: "pretty" }),
* String.stripMargin(
* `|lorem ipsum
* |dolor sit amet`
* )
* )
* assert.strictEqual(
* Doc.render(Doc.group(doc), { style: "pretty" }),
* "lorem ipsumdolor sit amet"
* )
* ```
*
* @since 1.0.0
* @category primitives
*/
export const lineBreak: Doc = internal.lineBreak
/**
* The `softLine` document behaves like `space` if the resulting output fits
* onto the page, otherwise it behaves like `line`.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import * as String from "effect/String"
*
* const doc: Doc.Doc = Doc.hcat([
* Doc.text("lorem ipsum"),
* Doc.softLine,
* Doc.text("dolor sit amet")
* ])
*
* // Here we have enough space to put everything onto one line
* assert.strictEqual(
* Doc.render(doc, {
* style: "pretty",
* options: { lineWidth: 80 }
* }),
* "lorem ipsum dolor sit amet"
* )
*
* // If the page width is narrowed to `10`, the layout algorithm will
* // introduce a line break
* assert.strictEqual(
* Doc.render(Doc.group(doc), {
* style: "pretty",
* options: { lineWidth: 10 }
* }),
* String.stripMargin(
* `|lorem ipsum
* |dolor sit amet`
* )
* )
* ```
*
* @since 1.0.0
* @category primitives
*/
export const softLine: Doc = internal.softLine
/**
* The `softLineBreak` document is similar to `softLine`, but behaves like
* `empty` if the resulting output does not fit onto the page (instead of
* `space`).
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import * as String from "effect/String"
*
* const doc: Doc.Doc = Doc.hcat([
* Doc.text("ThisText"),
* Doc.softLineBreak,
* Doc.text("IsWayTooLong")
* ])
*
* // With enough space, we get direct concatenation of documents:
* assert.strictEqual(
* Doc.render(doc, {
* style: "pretty",
* options: { lineWidth: 80 }
* }),
* "ThisTextIsWayTooLong"
* )
*
* // If the page width is narrowed to `10`, the layout algorithm will
* // introduce a line break
* assert.strictEqual(
* Doc.render(Doc.group(doc), {
* style: "pretty",
* options: { lineWidth: 10 }
* }),
* String.stripMargin(
* `|ThisText
* |IsWayTooLong`
* )
* )
* ```
*
* @since 1.0.0
* @category primitives
*/
export const softLineBreak: Doc = internal.softLineBreak
/**
* The `hardLine` document is always laid out as a line break, regardless of
* space or whether or not the document was `group`"ed.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import * as String from "effect/String"
*
* const doc: Doc.Doc = Doc.hcat([
* Doc.text("lorem ipsum"),
* Doc.hardLine,
* Doc.text("dolor sit amet")
* ])
*
* // Even with enough space, a line break is introduced
* assert.strictEqual(
* Doc.render(doc, {
* style: "pretty",
* options: { lineWidth: 1000 }
* }),
* String.stripMargin(
* `|lorem ipsum
* |dolor sit amet`
* )
* )
* ```
*
* @since 1.0.0
* @category primitives
*/
export const hardLine: Doc = internal.hardLine
/**
* A document containing a single `\` character.
*
* @since 1.0.0
* @category primitives
*/
export const backslash: Doc = internal.backslash
/**
* A document containing a single `:` character.
*
* @since 1.0.0
* @category primitives
*/
export const colon: Doc = internal.colon
/**
* A document containing a single `,` character.
*
* @since 1.0.0
* @category primitives
*/
export const comma: Doc = internal.comma
/**
* A document containing a single `.` character.
*
* @since 1.0.0
* @category primitives
*/
export const dot: Doc = internal.dot
/**
* A document containing a single `"` character.
*
* @since 1.0.0
* @category primitives
*/
export const dquote: Doc = internal.dquote
/**
* A document containing a single `=` character.
*
* @since 1.0.0
* @category primitives
*/
export const equalSign: Doc = internal.equalSign
/**
* A document containing a single `<` character.
*
* @since 1.0.0
* @category primitives
*/
export const langle: Doc = internal.langle
/**
* A document containing a single `{` character.
*
* @since 1.0.0
* @category primitives
*/
export const lbrace: Doc = internal.lbrace
/**
* A document containing a single `[` character.
*
* @since 1.0.0
* @category primitives
*/
export const lbracket: Doc = internal.lbracket
/**
* A document containing a single `(` character.
*
* @since 1.0.0
* @category primitives
*/
export const lparen: Doc = internal.lparen
/**
* A document containing a single `>` character.
*
* @since 1.0.0
* @category primitives
*/
export const rangle: Doc = internal.rangle
/**
* A document containing a single `}` character.
*
* @since 1.0.0
* @category primitives
*/
export const rbrace: Doc = internal.rbrace
/**
* A document containing a single `]` character.
*
* @since 1.0.0
* @category primitives
*/
export const rbracket: Doc = internal.rbracket
/**
* A document containing a single `)` character.
*
* @since 1.0.0
* @category primitives
*/
export const rparen: Doc = internal.rparen
/**
* A document containing a single `;` character.
*
* @since 1.0.0
* @category primitives
*/
export const semi: Doc = internal.semi
/**
* A document containing a single `/` character.
*
* @since 1.0.0
* @category primitives
*/
export const slash: Doc = internal.slash
/**
* A document containing a single `"` character.
*
* @since 1.0.0
* @category primitives
*/
export const squote: Doc = internal.squote
/**
* A document containing a single ` ` character.
*
* @since 1.0.0
* @category primitives
*/
export const space: Doc = internal.space
/**
* A document containing a single `|` character.
*
* @since 1.0.0
* @category primitives
*/
export const vbar: Doc = internal.vbar
// -----------------------------------------------------------------------------
// Concatenation
// -----------------------------------------------------------------------------
/**
* The `cat` combinator lays out two documents separated by nothing.
*
* @since 1.0.0
* @category concatenation
*/
export const cat: {
// -----------------------------------------------------------------------------
// Concatenation
// -----------------------------------------------------------------------------
/**
* The `cat` combinator lays out two documents separated by nothing.
*
* @since 1.0.0
* @category concatenation
*/
(that: Doc): (self: Doc) => Doc
// -----------------------------------------------------------------------------
// Concatenation
// -----------------------------------------------------------------------------
/**
* The `cat` combinator lays out two documents separated by nothing.
*
* @since 1.0.0
* @category concatenation
*/
(self: Doc, that: Doc): Doc
} = internal.cat
/**
* The `cats` combinator will attempt to lay out a collection of documents
* separated by nothing. If the output does not fit the page, then the documents
* will be separated by newlines. This is what differentiates it from `vcat`,
* which always lays out documents beneath one another.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import * as String from "effect/String"
*
* const doc: Doc.Doc = Doc.hsep([
* Doc.text("Docs:"),
* Doc.cats(Doc.words("lorem ipsum dolor"))
* ])
*
* assert.strictEqual(
* Doc.render(doc, { style: "pretty" }),
* "Docs: loremipsumdolor"
* )
*
* // If the document exceeds the width of the page, the documents are rendered
* // one above another
* assert.strictEqual(
* Doc.render(doc, {
* style: "pretty",
* options: { lineWidth: 10 }
* }),
* String.stripMargin(
* `|Docs: lorem
* |ipsum
* |dolor`
* )
* )
* ```
*
* @since 1.0.0
* @category concatenation
*/
export const cats: (docs: Iterable>) => Doc = internal.cats
/**
* The `catWithLine` combinator concatenates two documents by placing a `line`
* document between them.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import { pipe } from "effect/Function"
* import * as String from "effect/String"
*
* const doc: Doc.Doc = pipe(
* Doc.char("a"),
* Doc.catWithLine(Doc.char("b"))
* )
*
* assert.strictEqual(
* Doc.render(doc, { style: "pretty" }),
* String.stripMargin(
* `|a
* |b`
* )
* )
* ```
*
* @since 1.0.0
* @category concatenation
*/
export const catWithLine: {
/**
* The `catWithLine` combinator concatenates two documents by placing a `line`
* document between them.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import { pipe } from "effect/Function"
* import * as String from "effect/String"
*
* const doc: Doc.Doc = pipe(
* Doc.char("a"),
* Doc.catWithLine(Doc.char("b"))
* )
*
* assert.strictEqual(
* Doc.render(doc, { style: "pretty" }),
* String.stripMargin(
* `|a
* |b`
* )
* )
* ```
*
* @since 1.0.0
* @category concatenation
*/
(that: Doc): (self: Doc) => Doc
/**
* The `catWithLine` combinator concatenates two documents by placing a `line`
* document between them.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import { pipe } from "effect/Function"
* import * as String from "effect/String"
*
* const doc: Doc.Doc = pipe(
* Doc.char("a"),
* Doc.catWithLine(Doc.char("b"))
* )
*
* assert.strictEqual(
* Doc.render(doc, { style: "pretty" }),
* String.stripMargin(
* `|a
* |b`
* )
* )
* ```
*
* @since 1.0.0
* @category concatenation
*/
(self: Doc, that: Doc): Doc
} = internal.catWithLine
/**
* The `catWithLineBreak` combinator concatenates two documents by placing a
* `lineBreak` document between them.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import { pipe } from "effect/Function"
* import * as String from "effect/String"
*
* const doc: Doc.Doc = pipe(
* Doc.char("a"),
* Doc.catWithLineBreak(Doc.char("b"))
* )
*
* assert.strictEqual(
* Doc.render(doc, { style: "pretty" }),
* String.stripMargin(
* `|a
* |b`
* )
* )
*
* assert.strictEqual(
* Doc.render(Doc.group(doc), { style: "pretty" }),
* "ab"
* )
* ```
*
* @since 1.0.0
* @category concatenation
*/
export const catWithLineBreak: {
/**
* The `catWithLineBreak` combinator concatenates two documents by placing a
* `lineBreak` document between them.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import { pipe } from "effect/Function"
* import * as String from "effect/String"
*
* const doc: Doc.Doc = pipe(
* Doc.char("a"),
* Doc.catWithLineBreak(Doc.char("b"))
* )
*
* assert.strictEqual(
* Doc.render(doc, { style: "pretty" }),
* String.stripMargin(
* `|a
* |b`
* )
* )
*
* assert.strictEqual(
* Doc.render(Doc.group(doc), { style: "pretty" }),
* "ab"
* )
* ```
*
* @since 1.0.0
* @category concatenation
*/
(that: Doc): (self: Doc) => Doc
/**
* The `catWithLineBreak` combinator concatenates two documents by placing a
* `lineBreak` document between them.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import { pipe } from "effect/Function"
* import * as String from "effect/String"
*
* const doc: Doc.Doc = pipe(
* Doc.char("a"),
* Doc.catWithLineBreak(Doc.char("b"))
* )
*
* assert.strictEqual(
* Doc.render(doc, { style: "pretty" }),
* String.stripMargin(
* `|a
* |b`
* )
* )
*
* assert.strictEqual(
* Doc.render(Doc.group(doc), { style: "pretty" }),
* "ab"
* )
* ```
*
* @since 1.0.0
* @category concatenation
*/
(self: Doc, that: Doc): Doc
} = internal.catWithLineBreak
/**
* The `catWithSoftLine` combinator concatenates two documents by placing a
* `softLine` document between them.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import { pipe } from "effect/Function"
* import * as String from "effect/String"
*
* const doc: Doc.Doc = pipe(
* Doc.char("a"),
* Doc.catWithSoftLine(Doc.char("b"))
* )
*
* assert.strictEqual(
* Doc.render(doc, { style: "pretty" }),
* "a b"
* )
*
* assert.strictEqual(
* Doc.render(doc, {
* style: "pretty",
* options: { lineWidth: 1 }
* }),
* String.stripMargin(
* `|a
* |b`
* )
* )
* ```
*
* @since 1.0.0
* @category concatenation
*/
export const catWithSoftLine: {
/**
* The `catWithSoftLine` combinator concatenates two documents by placing a
* `softLine` document between them.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import { pipe } from "effect/Function"
* import * as String from "effect/String"
*
* const doc: Doc.Doc = pipe(
* Doc.char("a"),
* Doc.catWithSoftLine(Doc.char("b"))
* )
*
* assert.strictEqual(
* Doc.render(doc, { style: "pretty" }),
* "a b"
* )
*
* assert.strictEqual(
* Doc.render(doc, {
* style: "pretty",
* options: { lineWidth: 1 }
* }),
* String.stripMargin(
* `|a
* |b`
* )
* )
* ```
*
* @since 1.0.0
* @category concatenation
*/
(that: Doc): (self: Doc) => Doc
/**
* The `catWithSoftLine` combinator concatenates two documents by placing a
* `softLine` document between them.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import { pipe } from "effect/Function"
* import * as String from "effect/String"
*
* const doc: Doc.Doc = pipe(
* Doc.char("a"),
* Doc.catWithSoftLine(Doc.char("b"))
* )
*
* assert.strictEqual(
* Doc.render(doc, { style: "pretty" }),
* "a b"
* )
*
* assert.strictEqual(
* Doc.render(doc, {
* style: "pretty",
* options: { lineWidth: 1 }
* }),
* String.stripMargin(
* `|a
* |b`
* )
* )
* ```
*
* @since 1.0.0
* @category concatenation
*/
(self: Doc, that: Doc): Doc
} = internal.catWithSoftLine
/**
* The `catWithSoftLineBreak` combinator concatenates two documents by
* placing a `softLineBreak` document between them.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import { pipe } from "effect/Function"
* import * as String from "effect/String"
*
* const doc: Doc.Doc = pipe(
* Doc.char("a"),
* Doc.catWithSoftLineBreak(Doc.char("b"))
* )
*
* assert.strictEqual(
* Doc.render(doc, { style: "pretty" }),
* "ab"
* )
*
* assert.strictEqual(
* Doc.render(doc, {
* style: "pretty",
* options: { lineWidth: 1 }
* }),
* String.stripMargin(
* `|a
* |b`
* )
* )
* ```
*
* @since 1.0.0
* @category concatenation
*/
export const catWithSoftLineBreak: {
/**
* The `catWithSoftLineBreak` combinator concatenates two documents by
* placing a `softLineBreak` document between them.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import { pipe } from "effect/Function"
* import * as String from "effect/String"
*
* const doc: Doc.Doc = pipe(
* Doc.char("a"),
* Doc.catWithSoftLineBreak(Doc.char("b"))
* )
*
* assert.strictEqual(
* Doc.render(doc, { style: "pretty" }),
* "ab"
* )
*
* assert.strictEqual(
* Doc.render(doc, {
* style: "pretty",
* options: { lineWidth: 1 }
* }),
* String.stripMargin(
* `|a
* |b`
* )
* )
* ```
*
* @since 1.0.0
* @category concatenation
*/
(that: Doc): (self: Doc) => Doc
/**
* The `catWithSoftLineBreak` combinator concatenates two documents by
* placing a `softLineBreak` document between them.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import { pipe } from "effect/Function"
* import * as String from "effect/String"
*
* const doc: Doc.Doc = pipe(
* Doc.char("a"),
* Doc.catWithSoftLineBreak(Doc.char("b"))
* )
*
* assert.strictEqual(
* Doc.render(doc, { style: "pretty" }),
* "ab"
* )
*
* assert.strictEqual(
* Doc.render(doc, {
* style: "pretty",
* options: { lineWidth: 1 }
* }),
* String.stripMargin(
* `|a
* |b`
* )
* )
* ```
*
* @since 1.0.0
* @category concatenation
*/
(self: Doc, that: Doc): Doc
} = internal.catWithSoftLineBreak
/**
* The `catWithSpace` combinator concatenates two documents by placing a
* `space` document between them.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import { pipe } from "effect/Function"
*
* const doc: Doc.Doc = pipe(
* Doc.char("a"),
* Doc.catWithSpace(Doc.char("b"))
* )
*
* assert.strictEqual(
* Doc.render(doc, { style: "pretty" }),
* "a b"
* )
* ```
*
* @since 1.0.0
* @category concatenation
*/
export const catWithSpace: {
/**
* The `catWithSpace` combinator concatenates two documents by placing a
* `space` document between them.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import { pipe } from "effect/Function"
*
* const doc: Doc.Doc = pipe(
* Doc.char("a"),
* Doc.catWithSpace(Doc.char("b"))
* )
*
* assert.strictEqual(
* Doc.render(doc, { style: "pretty" }),
* "a b"
* )
* ```
*
* @since 1.0.0
* @category concatenation
*/
(that: Doc): (self: Doc) => Doc
/**
* The `catWithSpace` combinator concatenates two documents by placing a
* `space` document between them.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import { pipe } from "effect/Function"
*
* const doc: Doc.Doc = pipe(
* Doc.char("a"),
* Doc.catWithSpace(Doc.char("b"))
* )
*
* assert.strictEqual(
* Doc.render(doc, { style: "pretty" }),
* "a b"
* )
* ```
*
* @since 1.0.0
* @category concatenation
*/
(self: Doc, that: Doc): Doc
} = internal.catWithSpace
/**
* The `concatWith` combinator concatenates all documents in a collection
* element-wise with the specified binary function.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import { pipe } from "effect/Function"
*
* const doc: Doc.Doc = pipe(
* [Doc.char("a"), Doc.char("b")],
* Doc.concatWith((x, y) => Doc.catWithSpace(y)(x))
* )
*
* assert.strictEqual(
* Doc.render(doc, { style: "pretty" }),
* "a b"
* )
* ```
*
* @since 1.0.0
* @category concatenation
*/
export const concatWith: {
/**
* The `concatWith` combinator concatenates all documents in a collection
* element-wise with the specified binary function.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import { pipe } from "effect/Function"
*
* const doc: Doc.Doc = pipe(
* [Doc.char("a"), Doc.char("b")],
* Doc.concatWith((x, y) => Doc.catWithSpace(y)(x))
* )
*
* assert.strictEqual(
* Doc.render(doc, { style: "pretty" }),
* "a b"
* )
* ```
*
* @since 1.0.0
* @category concatenation
*/
(f: (left: Doc, right: Doc) => Doc): (docs: Iterable>) => Doc
/**
* The `concatWith` combinator concatenates all documents in a collection
* element-wise with the specified binary function.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import { pipe } from "effect/Function"
*
* const doc: Doc.Doc = pipe(
* [Doc.char("a"), Doc.char("b")],
* Doc.concatWith((x, y) => Doc.catWithSpace(y)(x))
* )
*
* assert.strictEqual(
* Doc.render(doc, { style: "pretty" }),
* "a b"
* )
* ```
*
* @since 1.0.0
* @category concatenation
*/
(docs: Iterable>, f: (left: Doc, right: Doc) => Doc): Doc
} = internal.concatWith
/**
* The `vcat` combinator concatenates all documents in a collection vertically.
* If the output is grouped then the line breaks are removed.
*
* In other words `vcat` is like `vsep`, with newlines removed instead of
* replaced by spaces.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import * as String from "effect/String"
*
* const doc: Doc.Doc = Doc.vcat(Doc.words("lorem ipsum dolor"))
*
* assert.strictEqual(
* Doc.render(doc, { style: "pretty" }),
* String.stripMargin(
* `|lorem
* |ipsum
* |dolor`
* )
* )
* ```
*
* @since 1.0.0
* @category concatenation
*/
export const vcat: (docs: Iterable>) => Doc = internal.vcat
/**
* The `hcat` combinator concatenates all documents in a collection horizontally
* without any spacing.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import * as String from "effect/String"
*
* const doc: Doc.Doc = Doc.hcat(Doc.words("lorem ipsum dolor"))
*
* assert.strictEqual(
* Doc.render(doc, { style: "pretty" }),
* "loremipsumdolor"
* )
* ```
*
* @since 1.0.0
* @category concatenation
*/
export const hcat: (docs: Iterable>) => Doc = internal.hcat
/**
* The `fillCat` combinator concatenates all documents in a collection
* horizontally by placing a `empty` between each pair of documents as long as
* they fit the page. Once the page width is exceeded, a `lineBreak` is inserted
* and the process is repeated for all documents in the collection.
*
* **Note**: the use of `lineBreak` means that if `group`ed, the documents will
* be separated with `empty` instead of newlines. See `fillSep` if you want a
* `space` instead.
*
* @since 1.0.0
* @category concatenation
*/
export const fillCat: (docs: Iterable>) => Doc = internal.fillCat
// -----------------------------------------------------------------------------
// Separation
// -----------------------------------------------------------------------------
/**
* The `hsep` combinator concatenates all documents in a collection horizontally
* by placing a `space` between each pair of documents.
*
* For automatic line breaks, consider using `fillSep`.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
*
* const doc: Doc.Doc = Doc.hsep(Doc.words("lorem ipsum dolor sit amet"))
*
* assert.strictEqual(
* Doc.render(doc, {
* style: "pretty",
* options: { lineWidth: 80 }
* }),
* "lorem ipsum dolor sit amet"
* )
*
* // The `hsep` combinator will not introduce line breaks on its own, even when
* // the page is too narrow
* assert.strictEqual(
* Doc.render(doc, {
* style: "pretty",
* options: { lineWidth: 5 }
* }),
* "lorem ipsum dolor sit amet"
* )
* ```
*
* @since 1.0.0
* @category separation
*/
export const hsep: (docs: Iterable>) => Doc = internal.hsep
/**
* The `vsep` combinator concatenates all documents in a collection vertically.
* If a `group` undoes the line breaks inserted by `vsep`, the documents are
* separated with a space instead.
*
* When a `vsep` is `group`ed, the documents are separated with a `space` if the
* layoutfits the page, otherwise nothing is done. See the `sep` convenience
* function for this use case.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import * as String from "effect/String"
*
* const unaligned = Doc.hsep([
* Doc.text("prefix"),
* Doc.vsep(Doc.words("text to lay out"))
* ])
*
* assert.strictEqual(
* Doc.render(unaligned, { style: "pretty" }),
* String.stripMargin(
* `|prefix text
* |to
* |lay
* |out`
* )
* )
*
* // The `align` function can be used to align the documents under their first
* // element
* const aligned = Doc.hsep([
* Doc.text("prefix"),
* Doc.align(Doc.vsep(Doc.words("text to lay out")))
* ])
*
* assert.strictEqual(
* Doc.render(aligned, { style: "pretty" }),
* String.stripMargin(
* `|prefix text
* | to
* | lay
* | out`
* )
* )
* ```
*
* @since 1.0.0
* @category separation
*/
export const vsep: (docs: Iterable>) => Doc = internal.vsep
/**
* The `fillSep` combinator concatenates all documents in a collection
* horizontally by placing a `space` between each pair of documents as long as
* they fit the page. Once the page width is exceeded, a `line` is inserted and
* the process is repeated for all documents in the collection.
*
* **Note**: the use of `line` means that if `group`ed, the documents will be
* separated with a `space` instead of newlines. See `fillCat` if you do not
* want a `space`.
*
* @since 1.0.0
* @category separation
*/
export const fillSep: (docs: Iterable>) => Doc = internal.fillSep
/**
* The `seps` combinator will attempt to lay out a collection of documents
* separated by `space`s. If the output does not fit the page, then the
* documents will be separated by newlines. This is what differentiates it from
* `vsep`, which always lays out documents beneath one another.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import * as String from "effect/String"
*
* const doc: Doc.Doc = Doc.hsep([
* Doc.text("prefix"),
* Doc.seps(Doc.words("text to lay out"))
* ])
*
* assert.strictEqual(
* Doc.render(doc, { style: "pretty" }),
* "prefix text to lay out"
* )
*
* // If the page width is too narrow, documents are separated by newlines
* assert.strictEqual(
* Doc.render(doc, {
* style: "pretty",
* options: { lineWidth: 20 }
* }),
* String.stripMargin(
* `|prefix text
* |to
* |lay
* |out`
* )
* )
* ```
*
* @since 1.0.0
* @category separation
*/
export const seps: (docs: Iterable>) => Doc = internal.seps
// -----------------------------------------------------------------------------
// Alternative Layouts
// -----------------------------------------------------------------------------
/**
* The `flatAlt` document will render `left` by default. However, when
* `group`ed, `y` will be preferred with `left` as the fallback for cases where
* `y` does not fit onto the page.
*
* **NOTE**:
* Users should be careful to ensure that `left` is less wide than `right`.
* Otherwise, if `right` ends up not fitting the page, then the layout
* algorithms will fall back to an even wider layout.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import { pipe } from "effect/Function"
* import * as String from "effect/String"
*
* const open = pipe(Doc.empty, Doc.flatAlt(Doc.text("{ ")))
* const close = pipe(Doc.empty, Doc.flatAlt(Doc.text(" }")))
* const separator = pipe(Doc.empty, Doc.flatAlt(Doc.text("; ")))
*
* const prettyDo = (documents: Array>): Doc.Doc => {
* return pipe(
* Doc.hsep([
* Doc.text("do"),
* pipe(
* documents,
* Doc.encloseSep(open, close, separator),
* Doc.align
* )
* ]),
* Doc.group
* )
* }
*
* const statements = [
* Doc.text("name:_ <- getArgs"),
* Doc.text("let greet = \"Hello, \" <> name"),
* Doc.text("putStrLn greet")
* ]
*
* // If it fits, then the content is put onto a single line with the `{;}` style
* assert.strictEqual(
* pipe(
* prettyDo(statements),
* Doc.render({
* style: "pretty",
* options: { lineWidth: 80 }
* })
* ),
* "do { name:_ <- getArgs; let greet = \"Hello, \" <> name; putStrLn greet }"
* )
*
* // When there is not enough space, the content is broken up onto multiple lines
* assert.strictEqual(
* pipe(
* prettyDo(statements),
* Doc.render({
* style: "pretty",
* options: { lineWidth: 10 }
* })
* ),
* String.stripMargin(
* `|do name:_ <- getArgs
* | let greet = "Hello, " <> name
* | putStrLn greet`
* )
* )
* ```
*
* @since 1.0.0
* @category alternative layouts
*/
export const flatAlt: {
// -----------------------------------------------------------------------------
// Alternative Layouts
// -----------------------------------------------------------------------------
/**
* The `flatAlt` document will render `left` by default. However, when
* `group`ed, `y` will be preferred with `left` as the fallback for cases where
* `y` does not fit onto the page.
*
* **NOTE**:
* Users should be careful to ensure that `left` is less wide than `right`.
* Otherwise, if `right` ends up not fitting the page, then the layout
* algorithms will fall back to an even wider layout.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import { pipe } from "effect/Function"
* import * as String from "effect/String"
*
* const open = pipe(Doc.empty, Doc.flatAlt(Doc.text("{ ")))
* const close = pipe(Doc.empty, Doc.flatAlt(Doc.text(" }")))
* const separator = pipe(Doc.empty, Doc.flatAlt(Doc.text("; ")))
*
* const prettyDo = (documents: Array>): Doc.Doc => {
* return pipe(
* Doc.hsep([
* Doc.text("do"),
* pipe(
* documents,
* Doc.encloseSep(open, close, separator),
* Doc.align
* )
* ]),
* Doc.group
* )
* }
*
* const statements = [
* Doc.text("name:_ <- getArgs"),
* Doc.text("let greet = \"Hello, \" <> name"),
* Doc.text("putStrLn greet")
* ]
*
* // If it fits, then the content is put onto a single line with the `{;}` style
* assert.strictEqual(
* pipe(
* prettyDo(statements),
* Doc.render({
* style: "pretty",
* options: { lineWidth: 80 }
* })
* ),
* "do { name:_ <- getArgs; let greet = \"Hello, \" <> name; putStrLn greet }"
* )
*
* // When there is not enough space, the content is broken up onto multiple lines
* assert.strictEqual(
* pipe(
* prettyDo(statements),
* Doc.render({
* style: "pretty",
* options: { lineWidth: 10 }
* })
* ),
* String.stripMargin(
* `|do name:_ <- getArgs
* | let greet = "Hello, " <> name
* | putStrLn greet`
* )
* )
* ```
*
* @since 1.0.0
* @category alternative layouts
*/
(that: Doc): (self: Doc) => Doc
// -----------------------------------------------------------------------------
// Alternative Layouts
// -----------------------------------------------------------------------------
/**
* The `flatAlt` document will render `left` by default. However, when
* `group`ed, `y` will be preferred with `left` as the fallback for cases where
* `y` does not fit onto the page.
*
* **NOTE**:
* Users should be careful to ensure that `left` is less wide than `right`.
* Otherwise, if `right` ends up not fitting the page, then the layout
* algorithms will fall back to an even wider layout.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import { pipe } from "effect/Function"
* import * as String from "effect/String"
*
* const open = pipe(Doc.empty, Doc.flatAlt(Doc.text("{ ")))
* const close = pipe(Doc.empty, Doc.flatAlt(Doc.text(" }")))
* const separator = pipe(Doc.empty, Doc.flatAlt(Doc.text("; ")))
*
* const prettyDo = (documents: Array>): Doc.Doc => {
* return pipe(
* Doc.hsep([
* Doc.text("do"),
* pipe(
* documents,
* Doc.encloseSep(open, close, separator),
* Doc.align
* )
* ]),
* Doc.group
* )
* }
*
* const statements = [
* Doc.text("name:_ <- getArgs"),
* Doc.text("let greet = \"Hello, \" <> name"),
* Doc.text("putStrLn greet")
* ]
*
* // If it fits, then the content is put onto a single line with the `{;}` style
* assert.strictEqual(
* pipe(
* prettyDo(statements),
* Doc.render({
* style: "pretty",
* options: { lineWidth: 80 }
* })
* ),
* "do { name:_ <- getArgs; let greet = \"Hello, \" <> name; putStrLn greet }"
* )
*
* // When there is not enough space, the content is broken up onto multiple lines
* assert.strictEqual(
* pipe(
* prettyDo(statements),
* Doc.render({
* style: "pretty",
* options: { lineWidth: 10 }
* })
* ),
* String.stripMargin(
* `|do name:_ <- getArgs
* | let greet = "Hello, " <> name
* | putStrLn greet`
* )
* )
* ```
*
* @since 1.0.0
* @category alternative layouts
*/
(self: Doc, that: Doc): Doc
} = internal.flatAlt
/**
* @since 1.0.0
* @category alternative layouts
*/
export const union: {
/**
* @since 1.0.0
* @category alternative layouts
*/
(that: Doc): (self: Doc) => Doc
/**
* @since 1.0.0
* @category alternative layouts
*/
(self: Doc, that: Doc): Doc
} = internal.union
/**
* The `group` combinator attempts to lay out a document onto a single line by
* removing the contained line breaks. If the result does not fit the page, or
* if a `hardLine` prevents flattening the document, `x` is laid out without
* any changes.
*
* The `group` function is key to layouts that adapt to available space nicely.
*
* @since 1.0.0
* @category alternative layouts
*/
export const group: (self: Doc) => Doc = internal.group
// -----------------------------------------------------------------------------
// Reactive Layouts
// -----------------------------------------------------------------------------
/**
* Lays out a document depending upon the column at which the document starts.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import * as String from "effect/String"
*
* // Example 1:
* const example1 = Doc.column((l) =>
* Doc.hsep([Doc.text("Columns are"), Doc.text(`${l}-based`)])
* )
*
* assert.strictEqual(
* Doc.render(example1, { style: "pretty" }),
* "Columns are 0-based"
* )
*
* // Example 2:
* const doc = Doc.hsep([
* Doc.text("prefix"),
* Doc.column((l) => Doc.text(`| <- column ${l}`))
* ])
*
* const example2 = Doc.vsep([0, 4, 8].map((n) => Doc.indent(n)(doc)))
*
* assert.strictEqual(
* Doc.render(example2, { style: "pretty" }),
* String.stripMargin(
* `|prefix | <- column 7
* | prefix | <- column 11
* | prefix | <- column 15`
* )
* )
* ```
*
* @since 1.0.0
* @category reactive layouts
*/
export const column: (react: (position: number) => Doc) => Doc = internal.column
/**
* Lays out a document depending upon the current nesting level (i.e., the
* current indentation of the document).
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import * as String from "effect/String"
*
* const doc = Doc.hsep([
* Doc.text("prefix"),
* Doc.nesting((l) => Doc.squareBracketed(Doc.text(`Nested: ${l}`)))
* ])
*
* const example = Doc.vsep([0, 4, 8].map((n) => Doc.indent(n)(doc)))
*
* assert.strictEqual(
* Doc.render(example, { style: "pretty" }),
* String.stripMargin(
* `|prefix [Nested: 0]
* | prefix [Nested: 4]
* | prefix [Nested: 8]`
* )
* )
* ```
*
* @since 1.0.0
* @category reactive layouts
*/
export const nesting: (react: (level: number) => Doc) => Doc = internal.nesting
/**
* The `width` combinator makes the column width of a document available to the
* document while rendering.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import { pipe } from "effect/Function"
* import * as String from "effect/String"
*
* const annotate = (doc: Doc.Doc): Doc.Doc =>
* pipe(
* Doc.squareBracketed(doc),
* Doc.width((w) => Doc.text(` <- width: ${w}`))
* )
*
* const docs = [
* Doc.text("---"),
* Doc.text("------"),
* Doc.indent(Doc.text("---"), 3),
* Doc.vsep([Doc.text("---"), Doc.indent(Doc.text("---"), 4)])
* ]
*
* const doc = Doc.align(Doc.vsep(docs.map(annotate)))
*
* assert.strictEqual(
* Doc.render(doc, { style: "pretty" }),
* String.stripMargin(
* `|[---] <- width: 5
* |[------] <- width: 8
* |[ ---] <- width: 8
* |[---
* | ---] <- width: 8`
* )
* )
* ```
*
* @since 1.0.0
* @category reactive layouts
*/
export const width: {
/**
* The `width` combinator makes the column width of a document available to the
* document while rendering.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import { pipe } from "effect/Function"
* import * as String from "effect/String"
*
* const annotate = (doc: Doc.Doc): Doc.Doc =>
* pipe(
* Doc.squareBracketed(doc),
* Doc.width((w) => Doc.text(` <- width: ${w}`))
* )
*
* const docs = [
* Doc.text("---"),
* Doc.text("------"),
* Doc.indent(Doc.text("---"), 3),
* Doc.vsep([Doc.text("---"), Doc.indent(Doc.text("---"), 4)])
* ]
*
* const doc = Doc.align(Doc.vsep(docs.map(annotate)))
*
* assert.strictEqual(
* Doc.render(doc, { style: "pretty" }),
* String.stripMargin(
* `|[---] <- width: 5
* |[------] <- width: 8
* |[ ---] <- width: 8
* |[---
* | ---] <- width: 8`
* )
* )
* ```
*
* @since 1.0.0
* @category reactive layouts
*/
(react: (width: number) => Doc): (self: Doc) => Doc
/**
* The `width` combinator makes the column width of a document available to the
* document while rendering.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import { pipe } from "effect/Function"
* import * as String from "effect/String"
*
* const annotate = (doc: Doc.Doc): Doc.Doc =>
* pipe(
* Doc.squareBracketed(doc),
* Doc.width((w) => Doc.text(` <- width: ${w}`))
* )
*
* const docs = [
* Doc.text("---"),
* Doc.text("------"),
* Doc.indent(Doc.text("---"), 3),
* Doc.vsep([Doc.text("---"), Doc.indent(Doc.text("---"), 4)])
* ]
*
* const doc = Doc.align(Doc.vsep(docs.map(annotate)))
*
* assert.strictEqual(
* Doc.render(doc, { style: "pretty" }),
* String.stripMargin(
* `|[---] <- width: 5
* |[------] <- width: 8
* |[ ---] <- width: 8
* |[---
* | ---] <- width: 8`
* )
* )
* ```
*
* @since 1.0.0
* @category reactive layouts
*/
(self: Doc, react: (width: number) => Doc): Doc
} = internal.width
/**
* Lays out a document according to the document"s`PageWidth`.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import * as String from "effect/String"
*
* const doc = Doc.hsep([
* Doc.text("prefix"),
* Doc.pageWidth((pageWidth) => {
* switch (pageWidth._tag) {
* case "AvailablePerLine": {
* const { lineWidth, ribbonFraction } = pageWidth
* return Doc.squareBracketed(
* Doc.text(`Width: ${lineWidth}, Ribbon Fraction: ${ribbonFraction}`)
* )
* }
* case "Unbounded": {
* return Doc.empty
* }
* }
* })
* ])
*
* const example = Doc.vsep([0, 4, 8].map((n) => Doc.indent(n)(doc)))
*
* assert.strictEqual(
* Doc.render(example, {
* style: "pretty",
* options: { lineWidth: 32 }
* }),
* String.stripMargin(
* `|prefix [Width: 32, Ribbon Fraction: 1]
* | prefix [Width: 32, Ribbon Fraction: 1]
* | prefix [Width: 32, Ribbon Fraction: 1]`
* )
* )
* ```
*
* @since 1.0.0
* @category constructors
*/
export const pageWidth: (react: (pageWidth: PageWidth) => Doc) => Doc = internal.pageWidth
// -----------------------------------------------------------------------------
// Alignment
// -----------------------------------------------------------------------------
/**
* Lays out a document with the current nesting level (indentation
* of the following lines) increased by the specified `indent`.
* Negative values are allowed and will decrease the nesting level
* accordingly.
*
* See also:
* * `hang`: nest a document relative to the current cursor
* position instead of the current nesting level
* * `align`: set the nesting level to the current cursor
* position
* * `indent`: increase the indentation on the spot, padding
* any empty space with spaces
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import { pipe } from "effect/Function"
* import * as String from "effect/String"
*
* const doc = Doc.vsep([
* pipe(Doc.vsep(Doc.words("lorem ipsum dolor")), Doc.nest(4)),
* Doc.text("sit"),
* Doc.text("amet")
* ])
*
* assert.strictEqual(
* Doc.render(doc, { style: "pretty" }),
* String.stripMargin(
* `|lorem
* | ipsum
* | dolor
* |sit
* |amet`
* )
* )
* ```
*
* @since 1.0.0
* @category alignment
*/
export const nest: {
// -----------------------------------------------------------------------------
// Alignment
// -----------------------------------------------------------------------------
/**
* Lays out a document with the current nesting level (indentation
* of the following lines) increased by the specified `indent`.
* Negative values are allowed and will decrease the nesting level
* accordingly.
*
* See also:
* * `hang`: nest a document relative to the current cursor
* position instead of the current nesting level
* * `align`: set the nesting level to the current cursor
* position
* * `indent`: increase the indentation on the spot, padding
* any empty space with spaces
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import { pipe } from "effect/Function"
* import * as String from "effect/String"
*
* const doc = Doc.vsep([
* pipe(Doc.vsep(Doc.words("lorem ipsum dolor")), Doc.nest(4)),
* Doc.text("sit"),
* Doc.text("amet")
* ])
*
* assert.strictEqual(
* Doc.render(doc, { style: "pretty" }),
* String.stripMargin(
* `|lorem
* | ipsum
* | dolor
* |sit
* |amet`
* )
* )
* ```
*
* @since 1.0.0
* @category alignment
*/
(indent: number): (self: Doc) => Doc
// -----------------------------------------------------------------------------
// Alignment
// -----------------------------------------------------------------------------
/**
* Lays out a document with the current nesting level (indentation
* of the following lines) increased by the specified `indent`.
* Negative values are allowed and will decrease the nesting level
* accordingly.
*
* See also:
* * `hang`: nest a document relative to the current cursor
* position instead of the current nesting level
* * `align`: set the nesting level to the current cursor
* position
* * `indent`: increase the indentation on the spot, padding
* any empty space with spaces
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import { pipe } from "effect/Function"
* import * as String from "effect/String"
*
* const doc = Doc.vsep([
* pipe(Doc.vsep(Doc.words("lorem ipsum dolor")), Doc.nest(4)),
* Doc.text("sit"),
* Doc.text("amet")
* ])
*
* assert.strictEqual(
* Doc.render(doc, { style: "pretty" }),
* String.stripMargin(
* `|lorem
* | ipsum
* | dolor
* |sit
* |amet`
* )
* )
* ```
*
* @since 1.0.0
* @category alignment
*/
(self: Doc, indent: number): Doc
} = internal.nest
/**
* The `align` combinator lays out a document with the nesting level set to the
* current column.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import * as String from "effect/String"
*
* // As an example, the documents below will be placed one above the other
* // regardless of the current nesting level
*
* // Without `align`ment, the second line is simply placed below everything
* // that has been laid out so far
* const unaligned = Doc.hsep([
* Doc.text("lorem"),
* Doc.vsep([Doc.text("ipsum"), Doc.text("dolor")])
* ])
*
* assert.strictEqual(
* Doc.render(unaligned, { style: "pretty" }),
* String.stripMargin(
* `|lorem ipsum
* |dolor`
* )
* )
*
* // With `align`ment, the `vsep`ed documents all start at the same column
* const aligned = Doc.hsep([
* Doc.text("lorem"),
* Doc.align(Doc.vsep([Doc.text("ipsum"), Doc.text("dolor")]))
* ])
*
* assert.strictEqual(
* Doc.render(aligned, { style: "pretty" }),
* String.stripMargin(
* `|lorem ipsum
* | dolor`
* )
* )
* ```
*
* @since 1.0.0
* @category alignment
*/
export const align: (self: Doc) => Doc = internal.align
/**
* The `hang` combinator lays out a document with the nesting level set to
* the *current column* plus the specified `indent`. Negative values for
* `indent` are allowed and decrease the nesting level accordingly.
*
* This differs from the `nest` combinator, which is based on the *current
* nesting level* plus the specified `indent`. When you"re not sure, try the
* more efficient combinator (`nest`) first.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import { pipe } from "effect/Function"
* import * as String from "effect/String"
*
* const doc = Doc.hsep([
* Doc.text("prefix"),
* pipe(Doc.reflow("Indenting these words with hang"), Doc.hang(4))
* ])
*
* assert.strictEqual(
* Doc.render(doc, {
* style: "pretty",
* options: { lineWidth: 24 }
* }),
* String.stripMargin(
* `|prefix Indenting these
* | words with
* | hang`
* )
* )
* ```
*
* @since 1.0.0
* @category alignment
*/
export const hang: {
/**
* The `hang` combinator lays out a document with the nesting level set to
* the *current column* plus the specified `indent`. Negative values for
* `indent` are allowed and decrease the nesting level accordingly.
*
* This differs from the `nest` combinator, which is based on the *current
* nesting level* plus the specified `indent`. When you"re not sure, try the
* more efficient combinator (`nest`) first.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import { pipe } from "effect/Function"
* import * as String from "effect/String"
*
* const doc = Doc.hsep([
* Doc.text("prefix"),
* pipe(Doc.reflow("Indenting these words with hang"), Doc.hang(4))
* ])
*
* assert.strictEqual(
* Doc.render(doc, {
* style: "pretty",
* options: { lineWidth: 24 }
* }),
* String.stripMargin(
* `|prefix Indenting these
* | words with
* | hang`
* )
* )
* ```
*
* @since 1.0.0
* @category alignment
*/
(indent: number): (self: Doc) => Doc
/**
* The `hang` combinator lays out a document with the nesting level set to
* the *current column* plus the specified `indent`. Negative values for
* `indent` are allowed and decrease the nesting level accordingly.
*
* This differs from the `nest` combinator, which is based on the *current
* nesting level* plus the specified `indent`. When you"re not sure, try the
* more efficient combinator (`nest`) first.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import { pipe } from "effect/Function"
* import * as String from "effect/String"
*
* const doc = Doc.hsep([
* Doc.text("prefix"),
* pipe(Doc.reflow("Indenting these words with hang"), Doc.hang(4))
* ])
*
* assert.strictEqual(
* Doc.render(doc, {
* style: "pretty",
* options: { lineWidth: 24 }
* }),
* String.stripMargin(
* `|prefix Indenting these
* | words with
* | hang`
* )
* )
* ```
*
* @since 1.0.0
* @category alignment
*/
(self: Doc, indent: number): Doc
} = internal.hang
/**
* The `indent` combinator indents a document by the specified `indent`
* beginning from the current cursor position.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import { pipe } from "effect/Function"
* import * as String from "effect/String"
*
* const doc = Doc.hcat([
* Doc.text("prefix"),
* pipe(Doc.reflow("The indent function indents these words!"), Doc.indent(4))
* ])
*
* assert.strictEqual(
* Doc.render(doc, {
* style: "pretty",
* options: { lineWidth: 24 }
* }),
* String.stripMargin(
* `|prefix The indent
* | function
* | indents these
* | words!`
* )
* )
* ```
*
* @since 1.0.0
* @category alignment
*/
export const indent: {
/**
* The `indent` combinator indents a document by the specified `indent`
* beginning from the current cursor position.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import { pipe } from "effect/Function"
* import * as String from "effect/String"
*
* const doc = Doc.hcat([
* Doc.text("prefix"),
* pipe(Doc.reflow("The indent function indents these words!"), Doc.indent(4))
* ])
*
* assert.strictEqual(
* Doc.render(doc, {
* style: "pretty",
* options: { lineWidth: 24 }
* }),
* String.stripMargin(
* `|prefix The indent
* | function
* | indents these
* | words!`
* )
* )
* ```
*
* @since 1.0.0
* @category alignment
*/
(indent: number): (self: Doc) => Doc
/**
* The `indent` combinator indents a document by the specified `indent`
* beginning from the current cursor position.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import { pipe } from "effect/Function"
* import * as String from "effect/String"
*
* const doc = Doc.hcat([
* Doc.text("prefix"),
* pipe(Doc.reflow("The indent function indents these words!"), Doc.indent(4))
* ])
*
* assert.strictEqual(
* Doc.render(doc, {
* style: "pretty",
* options: { lineWidth: 24 }
* }),
* String.stripMargin(
* `|prefix The indent
* | function
* | indents these
* | words!`
* )
* )
* ```
*
* @since 1.0.0
* @category alignment
*/
(self: Doc, indent: number): Doc
} = internal.indent
/**
* The `encloseSep` combinator concatenates a collection of documents,
* separating each document in the collection using the specified `sep`
* document. After concatenation, the resulting document is enclosed by the
* specified `left` and `right` documents.
*
* To place the `sep` document at the end of each entry, see the `punctuate`
* combinator.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import { pipe } from "effect/Function"
* import * as String from "effect/String"
*
* const doc = Doc.hsep([
* Doc.text("list"),
* Doc.align(
* pipe(
* ["1", "20", "300", "4000"].map(
* (n) => n.length === 1 ? Doc.char(n) : Doc.text(n)
* ),
* Doc.encloseSep(Doc.lbracket, Doc.rbracket, Doc.comma)
* )
* )
* ])
*
* // The documents are laid out horizontally if the document fits the page
* assert.strictEqual(
* Doc.render(doc, { style: "pretty" }),
* "list [1,20,300,4000]"
* )
*
* // Otherwise they are laid out vertically, with separators put in the front
* assert.strictEqual(
* Doc.render(doc, {
* style: "pretty",
* options: { lineWidth: 10 }
* }),
* String.stripMargin(
* `|list [1
* | ,20
* | ,300
* | ,4000]`
* )
* )
* ```
*
* @since 1.0.0
* @category alignment
*/
export const encloseSep: {
/**
* The `encloseSep` combinator concatenates a collection of documents,
* separating each document in the collection using the specified `sep`
* document. After concatenation, the resulting document is enclosed by the
* specified `left` and `right` documents.
*
* To place the `sep` document at the end of each entry, see the `punctuate`
* combinator.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import { pipe } from "effect/Function"
* import * as String from "effect/String"
*
* const doc = Doc.hsep([
* Doc.text("list"),
* Doc.align(
* pipe(
* ["1", "20", "300", "4000"].map(
* (n) => n.length === 1 ? Doc.char(n) : Doc.text(n)
* ),
* Doc.encloseSep(Doc.lbracket, Doc.rbracket, Doc.comma)
* )
* )
* ])
*
* // The documents are laid out horizontally if the document fits the page
* assert.strictEqual(
* Doc.render(doc, { style: "pretty" }),
* "list [1,20,300,4000]"
* )
*
* // Otherwise they are laid out vertically, with separators put in the front
* assert.strictEqual(
* Doc.render(doc, {
* style: "pretty",
* options: { lineWidth: 10 }
* }),
* String.stripMargin(
* `|list [1
* | ,20
* | ,300
* | ,4000]`
* )
* )
* ```
*
* @since 1.0.0
* @category alignment
*/
(left: Doc, right: Doc, sep: Doc): (docs: Iterable>) => Doc
/**
* The `encloseSep` combinator concatenates a collection of documents,
* separating each document in the collection using the specified `sep`
* document. After concatenation, the resulting document is enclosed by the
* specified `left` and `right` documents.
*
* To place the `sep` document at the end of each entry, see the `punctuate`
* combinator.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import { pipe } from "effect/Function"
* import * as String from "effect/String"
*
* const doc = Doc.hsep([
* Doc.text("list"),
* Doc.align(
* pipe(
* ["1", "20", "300", "4000"].map(
* (n) => n.length === 1 ? Doc.char(n) : Doc.text(n)
* ),
* Doc.encloseSep(Doc.lbracket, Doc.rbracket, Doc.comma)
* )
* )
* ])
*
* // The documents are laid out horizontally if the document fits the page
* assert.strictEqual(
* Doc.render(doc, { style: "pretty" }),
* "list [1,20,300,4000]"
* )
*
* // Otherwise they are laid out vertically, with separators put in the front
* assert.strictEqual(
* Doc.render(doc, {
* style: "pretty",
* options: { lineWidth: 10 }
* }),
* String.stripMargin(
* `|list [1
* | ,20
* | ,300
* | ,4000]`
* )
* )
* ```
*
* @since 1.0.0
* @category alignment
*/
(docs: Iterable>, left: Doc, right: Doc, sep: Doc): Doc
} = internal.encloseSep
/**
* A Haskell-inspired variant of `encloseSep` that uses a comma as the separator
* and braces as the enclosure for a collection of documents.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
*
* const doc = Doc.list(
* ["1", "20", "300", "4000"].map(
* (n) => (n.length === 1 ? Doc.char(n) : Doc.text(n))
* )
* )
*
* assert.strictEqual(
* Doc.render(doc, { style: "pretty" }),
* "[1, 20, 300, 4000]"
* )
* ```
*
* @since 1.0.0
* @category alignment
*/
export const list: (docs: Iterable>) => Doc = internal.list
/**
* A Haskell-inspired variant of `encloseSep` that uses a comma as the separator
* and parentheses as the enclosure for a collection of documents.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
*
* const doc = Doc.tupled(
* ["1", "20", "300", "4000"].map(
* (n) => (n.length === 1 ? Doc.char(n) : Doc.text(n))
* )
* )
*
* assert.strictEqual(
* Doc.render(doc, { style: "pretty" }),
* "(1, 20, 300, 4000)"
* )
* ```
*
* @since 1.0.0
* @category alignment
*/
export const tupled: (docs: Iterable>) => Doc = internal.tupled
// -----------------------------------------------------------------------------
// Filling
// -----------------------------------------------------------------------------
/**
* The `fill` combinator first lays out the document `x` and then appends
* `space`s until the width of the document is equal to the specified `width`.
* If the width of `x` is already larger than the specified `width`, nothing is
* appended.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import { pipe } from "effect/Function"
* import * as String from "effect/String"
*
* type Signature = [name: string, type: string]
*
* const signatures: Array = [
* ["empty", "Doc"],
* ["nest", "Int -> Doc -> Doc"],
* ["fillSep", "[Doc] -> Doc"]
* ]
*
* const prettySignature = ([name, type]: Signature): Doc.Doc =>
* Doc.hsep([
* pipe(Doc.text(name), Doc.fill(5)),
* Doc.text("::"),
* Doc.text(type)
* ])
*
* const doc = Doc.hsep([
* Doc.text("let"),
* Doc.align(Doc.vcat(signatures.map(prettySignature)))
* ])
*
* assert.strictEqual(
* Doc.render(doc, { style: "pretty" }),
* String.stripMargin(
* `|let empty :: Doc
* | nest :: Int -> Doc -> Doc
* | fillSep :: [Doc] -> Doc`
* )
* )
* ```
*
* @since 1.0.0
* @category filling
*/
export const fill: {
// -----------------------------------------------------------------------------
// Filling
// -----------------------------------------------------------------------------
/**
* The `fill` combinator first lays out the document `x` and then appends
* `space`s until the width of the document is equal to the specified `width`.
* If the width of `x` is already larger than the specified `width`, nothing is
* appended.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import { pipe } from "effect/Function"
* import * as String from "effect/String"
*
* type Signature = [name: string, type: string]
*
* const signatures: Array = [
* ["empty", "Doc"],
* ["nest", "Int -> Doc -> Doc"],
* ["fillSep", "[Doc] -> Doc"]
* ]
*
* const prettySignature = ([name, type]: Signature): Doc.Doc =>
* Doc.hsep([
* pipe(Doc.text(name), Doc.fill(5)),
* Doc.text("::"),
* Doc.text(type)
* ])
*
* const doc = Doc.hsep([
* Doc.text("let"),
* Doc.align(Doc.vcat(signatures.map(prettySignature)))
* ])
*
* assert.strictEqual(
* Doc.render(doc, { style: "pretty" }),
* String.stripMargin(
* `|let empty :: Doc
* | nest :: Int -> Doc -> Doc
* | fillSep :: [Doc] -> Doc`
* )
* )
* ```
*
* @since 1.0.0
* @category filling
*/
(w: number): (self: Doc) => Doc
// -----------------------------------------------------------------------------
// Filling
// -----------------------------------------------------------------------------
/**
* The `fill` combinator first lays out the document `x` and then appends
* `space`s until the width of the document is equal to the specified `width`.
* If the width of `x` is already larger than the specified `width`, nothing is
* appended.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import { pipe } from "effect/Function"
* import * as String from "effect/String"
*
* type Signature = [name: string, type: string]
*
* const signatures: Array = [
* ["empty", "Doc"],
* ["nest", "Int -> Doc -> Doc"],
* ["fillSep", "[Doc] -> Doc"]
* ]
*
* const prettySignature = ([name, type]: Signature): Doc.Doc =>
* Doc.hsep([
* pipe(Doc.text(name), Doc.fill(5)),
* Doc.text("::"),
* Doc.text(type)
* ])
*
* const doc = Doc.hsep([
* Doc.text("let"),
* Doc.align(Doc.vcat(signatures.map(prettySignature)))
* ])
*
* assert.strictEqual(
* Doc.render(doc, { style: "pretty" }),
* String.stripMargin(
* `|let empty :: Doc
* | nest :: Int -> Doc -> Doc
* | fillSep :: [Doc] -> Doc`
* )
* )
* ```
*
* @since 1.0.0
* @category filling
*/
(self: Doc, w: number): Doc
} = internal.fill
/**
* The `fillBreak` combinator first lays out the document `x` and then appends
* `space`s until the width of the document is equal to the specified `width`.
* If the width of `x` is already larger than the specified `width`, the nesting
* level is increased by the specified `width` and a `line` is appended.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import { pipe } from "effect/Function"
* import * as String from "effect/String"
*
* type Signature = [name: string, type: string]
*
* const signatures: Array = [
* ["empty", "Doc"],
* ["nest", "Int -> Doc -> Doc"],
* ["fillSep", "[Doc] -> Doc"]
* ]
*
* const prettySignature = ([name, type]: Signature): Doc.Doc =>
* Doc.hsep([
* pipe(Doc.text(name), Doc.fillBreak(5)),
* Doc.text("::"),
* Doc.text(type)
* ])
*
* const doc = Doc.hsep([
* Doc.text("let"),
* Doc.align(Doc.vcat(signatures.map(prettySignature)))
* ])
*
* assert.strictEqual(
* Doc.render(doc, { style: "pretty" }),
* String.stripMargin(
* `|let empty :: Doc
* | nest :: Int -> Doc -> Doc
* | fillSep
* | :: [Doc] -> Doc`
* )
* )
* ```
*
* @since 1.0.0
* @category filling
*/
export const fillBreak: {
/**
* The `fillBreak` combinator first lays out the document `x` and then appends
* `space`s until the width of the document is equal to the specified `width`.
* If the width of `x` is already larger than the specified `width`, the nesting
* level is increased by the specified `width` and a `line` is appended.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import { pipe } from "effect/Function"
* import * as String from "effect/String"
*
* type Signature = [name: string, type: string]
*
* const signatures: Array = [
* ["empty", "Doc"],
* ["nest", "Int -> Doc -> Doc"],
* ["fillSep", "[Doc] -> Doc"]
* ]
*
* const prettySignature = ([name, type]: Signature): Doc.Doc =>
* Doc.hsep([
* pipe(Doc.text(name), Doc.fillBreak(5)),
* Doc.text("::"),
* Doc.text(type)
* ])
*
* const doc = Doc.hsep([
* Doc.text("let"),
* Doc.align(Doc.vcat(signatures.map(prettySignature)))
* ])
*
* assert.strictEqual(
* Doc.render(doc, { style: "pretty" }),
* String.stripMargin(
* `|let empty :: Doc
* | nest :: Int -> Doc -> Doc
* | fillSep
* | :: [Doc] -> Doc`
* )
* )
* ```
*
* @since 1.0.0
* @category filling
*/
(w: number): (self: Doc) => Doc
/**
* The `fillBreak` combinator first lays out the document `x` and then appends
* `space`s until the width of the document is equal to the specified `width`.
* If the width of `x` is already larger than the specified `width`, the nesting
* level is increased by the specified `width` and a `line` is appended.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import { pipe } from "effect/Function"
* import * as String from "effect/String"
*
* type Signature = [name: string, type: string]
*
* const signatures: Array = [
* ["empty", "Doc"],
* ["nest", "Int -> Doc -> Doc"],
* ["fillSep", "[Doc] -> Doc"]
* ]
*
* const prettySignature = ([name, type]: Signature): Doc.Doc =>
* Doc.hsep([
* pipe(Doc.text(name), Doc.fillBreak(5)),
* Doc.text("::"),
* Doc.text(type)
* ])
*
* const doc = Doc.hsep([
* Doc.text("let"),
* Doc.align(Doc.vcat(signatures.map(prettySignature)))
* ])
*
* assert.strictEqual(
* Doc.render(doc, { style: "pretty" }),
* String.stripMargin(
* `|let empty :: Doc
* | nest :: Int -> Doc -> Doc
* | fillSep
* | :: [Doc] -> Doc`
* )
* )
* ```
*
* @since 1.0.0
* @category filling
*/
(self: Doc, w: number): Doc
} = internal.fillBreak
// -----------------------------------------------------------------------------
// Flattening
// -----------------------------------------------------------------------------
/**
* Flattens a document but does not report changes.
*
* @since 1.0.0
* @category flattening
*/
export const flatten: (self: Doc) => Doc = internal.flatten
/**
* Select the first element of each `Union` and discard the first element of
* each `FlatAlt` to produce a "flattened" version of the input document.
*
* The result is `Flattened` if the element might change depending on the chosen
* layout algorithm (i.e., the resulting document contains sub-documents that
* may be rendered differently).
*
* The result is `AlreadyFlat` if the document is static (i.e., the resulting
* document contains only a plain `Empty` node).
*
* `NeverFlat` is returned when the document cannot be flattened because it
* contains either a hard `Line` or a `Fail`.
*
* @since 1.0.0
* @category flattening
*/
export const changesUponFlattening: (self: Doc) => Flatten> = internal.changesUponFlattening
// -----------------------------------------------------------------------------
// Annotations
// -----------------------------------------------------------------------------
/**
* Adds an annotation to a `Doc`. The annotation can then be used by the rendering
* algorithm to, for example, add color to certain parts of the output.
*
* **Note** This function is relevant only for custom formats with their own annotations,
* and is not relevant for basic pretty printing.
*
* @since 1.0.0
* @category annotations
*/
export const annotate: {
// -----------------------------------------------------------------------------
// Annotations
// -----------------------------------------------------------------------------
/**
* Adds an annotation to a `Doc`. The annotation can then be used by the rendering
* algorithm to, for example, add color to certain parts of the output.
*
* **Note** This function is relevant only for custom formats with their own annotations,
* and is not relevant for basic pretty printing.
*
* @since 1.0.0
* @category annotations
*/
(annotation: A): (self: Doc) => Doc
// -----------------------------------------------------------------------------
// Annotations
// -----------------------------------------------------------------------------
/**
* Adds an annotation to a `Doc`. The annotation can then be used by the rendering
* algorithm to, for example, add color to certain parts of the output.
*
* **Note** This function is relevant only for custom formats with their own annotations,
* and is not relevant for basic pretty printing.
*
* @since 1.0.0
* @category annotations
*/
(self: Doc, annotation: A): Doc
} = internal.annotate
/**
* Change the annotations of a document. Individual annotations can be removed,
* changed, or replaced by multiple ones.
*
* This is a general function that combines `unAnnotate` and `reAnnotate`, and
* is useful for mapping semantic annotations (such as »this is a keyword«) to
* display annotations (such as »this is red and underlined«) because some
* backends may not care about certain annotations while others may.
*
* Annotations earlier in the new list will be applied earlier, so returning
* `[Bold, Green]` will result in a bold document that contains green text, and
* not vice versa.
*
* Since this traverses the entire document tree, including the parts that are
* not rendered (due to other layouts having better fit), it is preferable to
* reannotate a document **after** producing the layout by using
* `alterAnnotations` from the `SimpleDocStream` module.
*
* @since 1.0.0
* @category annotations
*/
export const alterAnnotations: {
/**
* Change the annotations of a document. Individual annotations can be removed,
* changed, or replaced by multiple ones.
*
* This is a general function that combines `unAnnotate` and `reAnnotate`, and
* is useful for mapping semantic annotations (such as »this is a keyword«) to
* display annotations (such as »this is red and underlined«) because some
* backends may not care about certain annotations while others may.
*
* Annotations earlier in the new list will be applied earlier, so returning
* `[Bold, Green]` will result in a bold document that contains green text, and
* not vice versa.
*
* Since this traverses the entire document tree, including the parts that are
* not rendered (due to other layouts having better fit), it is preferable to
* reannotate a document **after** producing the layout by using
* `alterAnnotations` from the `SimpleDocStream` module.
*
* @since 1.0.0
* @category annotations
*/
(f: (a: A) => Iterable): (self: Doc) => Doc
/**
* Change the annotations of a document. Individual annotations can be removed,
* changed, or replaced by multiple ones.
*
* This is a general function that combines `unAnnotate` and `reAnnotate`, and
* is useful for mapping semantic annotations (such as »this is a keyword«) to
* display annotations (such as »this is red and underlined«) because some
* backends may not care about certain annotations while others may.
*
* Annotations earlier in the new list will be applied earlier, so returning
* `[Bold, Green]` will result in a bold document that contains green text, and
* not vice versa.
*
* Since this traverses the entire document tree, including the parts that are
* not rendered (due to other layouts having better fit), it is preferable to
* reannotate a document **after** producing the layout by using
* `alterAnnotations` from the `SimpleDocStream` module.
*
* @since 1.0.0
* @category annotations
*/
(self: Doc, f: (a: A) => Iterable): Doc
} = internal.alterAnnotations
/**
* Changes the annotation of a document. Useful for modifying documents embedded
* with one form of annotation with a more general annotation.
*
* **Note** that with each invocation, the entire document tree is traversed.
* If possible, it is preferable to reannotate a document after producing the
* layout using `reAnnotateS`.
*
* @since 1.0.0
* @category annotations
*/
export const reAnnotate: {
/**
* Changes the annotation of a document. Useful for modifying documents embedded
* with one form of annotation with a more general annotation.
*
* **Note** that with each invocation, the entire document tree is traversed.
* If possible, it is preferable to reannotate a document after producing the
* layout using `reAnnotateS`.
*
* @since 1.0.0
* @category annotations
*/
(f: (a: A) => B): (self: Doc) => Doc
/**
* Changes the annotation of a document. Useful for modifying documents embedded
* with one form of annotation with a more general annotation.
*
* **Note** that with each invocation, the entire document tree is traversed.
* If possible, it is preferable to reannotate a document after producing the
* layout using `reAnnotateS`.
*
* @since 1.0.0
* @category annotations
*/
(self: Doc, f: (a: A) => B): Doc
} = internal.reAnnotate
/**
* Removes all annotations from a document.
*
* **Note**: with each invocation, the entire document tree is traversed.
* If possible, it is preferable to unannotate a document after producing the
* layout using `unAnnotateS`.
*
* @since 1.0.0
* @category annotations
*/
export const unAnnotate: (self: Doc) => Doc = internal.unAnnotate
// -----------------------------------------------------------------------------
// Folding
// -----------------------------------------------------------------------------
/**
* @since 1.0.0
* @category folding
*/
export const match: {
// -----------------------------------------------------------------------------
// Folding
// -----------------------------------------------------------------------------
/**
* @since 1.0.0
* @category folding
*/
(
patterns: {
readonly Fail: () => R
readonly Empty: () => R
readonly Char: (char: string) => R
readonly Text: (text: string) => R
readonly Line: () => R
readonly FlatAlt: (x: Doc, y: Doc) => R
readonly Cat: (x: Doc, y: Doc) => R
readonly Nest: (indent: number, doc: Doc) => R
readonly Union: (x: Doc, y: Doc) => R
readonly Column: (react: (position: number) => Doc) => R
readonly WithPageWidth: (react: (pageWidth: PageWidth) => Doc) => R
readonly Nesting: (react: (level: number) => Doc) => R
readonly Annotated: (annotation: A, doc: Doc) => R
}
): (self: Doc) => R
// -----------------------------------------------------------------------------
// Folding
// -----------------------------------------------------------------------------
/**
* @since 1.0.0
* @category folding
*/
(
self: Doc,
patterns: {
readonly Fail: () => R
readonly Empty: () => R
readonly Char: (char: string) => R
readonly Text: (text: string) => R
readonly Line: () => R
readonly FlatAlt: (x: Doc, y: Doc) => R
readonly Cat: (x: Doc, y: Doc) => R
readonly Nest: (indent: number, doc: Doc) => R
readonly Union: (x: Doc, y: Doc) => R
readonly Column: (react: (position: number) => Doc) => R
readonly WithPageWidth: (react: (pageWidth: PageWidth) => Doc) => R
readonly Nesting: (react: (level: number) => Doc) => R
readonly Annotated: (annotation: A, doc: Doc) => R
}
): R
} = internal.match
// -----------------------------------------------------------------------------
// Instances
// -----------------------------------------------------------------------------
/**
* @since 1.0.0
* @category rendering
*/
export const render: {
// -----------------------------------------------------------------------------
// Instances
// -----------------------------------------------------------------------------
/**
* @since 1.0.0
* @category rendering
*/
(config: Doc.RenderConfig): (self: Doc) => string
// -----------------------------------------------------------------------------
// Instances
// -----------------------------------------------------------------------------
/**
* @since 1.0.0
* @category rendering
*/
(self: Doc, config: Doc.RenderConfig): string
} = InternalRender.render
/**
* @since 1.0.0
* @category rendering
*/
export const renderStream: (
self: DocStream
) => string = InternalRender.renderStream
// -----------------------------------------------------------------------------
// Instances
// -----------------------------------------------------------------------------
/**
* @since 1.0.0
* @category combinators
*/
export const map: {
// -----------------------------------------------------------------------------
// Instances
// -----------------------------------------------------------------------------
/**
* @since 1.0.0
* @category combinators
*/
(f: (a: A) => B): (self: Doc) => Doc
// -----------------------------------------------------------------------------
// Instances
// -----------------------------------------------------------------------------
/**
* @since 1.0.0
* @category combinators
*/
(self: Doc, f: (a: A) => B): Doc
} = internal.map
/**
* @since 1.0.0
* @category instances
*/
export const getSemigroup: (_: void) => Semigroup> = internal.getSemigroup
/**
* @since 1.0.0
* @category instances
*/
export const getMonoid: (_: void) => Monoid> = internal.getMonoid
/**
* @since 1.0.0
* @category instances
*/
export const Covariant: covariant.Covariant = internal.Covariant
/**
* @since 1.0.0
* @category instances
*/
export const Invariant: invariant.Invariant = internal.Invariant
// -----------------------------------------------------------------------------
// Utilities
// -----------------------------------------------------------------------------
/**
* Removes control characters from the text leaves of a document while
* preserving its structure and annotations.
*
* Horizontal tabs (`U+0009`) and line feeds (`U+000A`) are preserved. Other C0
* controls, DEL (`U+007F`), and C1 controls (`U+0080` through `U+009F`) are
* removed.
*
* Use this at the boundary where untrusted text enters a document that will be
* rendered to a terminal. Existing constructors and renderers remain suitable
* for trusted text containing intentional terminal sequences, such as OSC 8
* hyperlinks.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
*
* const doc = Doc.sanitize(Doc.text("hello\u001bworld"))
*
* assert.strictEqual(
* Doc.render(doc, { style: "pretty" }),
* "helloworld"
* )
* ```
*
* @since 1.0.0
* @category utilities
*/
export const sanitize: (self: Doc) => Doc = internal.sanitize
/**
* The `surround` combinator encloses a document in between `left` and `right`
* documents.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import { pipe } from "effect/Function"
*
* const doc = pipe(
* Doc.char("-"),
* Doc.surround(Doc.char("A"), Doc.char("Z"))
* )
*
* assert.strictEqual(
* Doc.render(doc, { style: "pretty" }),
* "A-Z"
* )
* ```
*
* @since 1.0.0
* @category utilities
*/
export const surround: {
/**
* The `surround` combinator encloses a document in between `left` and `right`
* documents.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import { pipe } from "effect/Function"
*
* const doc = pipe(
* Doc.char("-"),
* Doc.surround(Doc.char("A"), Doc.char("Z"))
* )
*
* assert.strictEqual(
* Doc.render(doc, { style: "pretty" }),
* "A-Z"
* )
* ```
*
* @since 1.0.0
* @category utilities
*/
(left: Doc, right: Doc): (self: Doc) => Doc
/**
* The `surround` combinator encloses a document in between `left` and `right`
* documents.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import { pipe } from "effect/Function"
*
* const doc = pipe(
* Doc.char("-"),
* Doc.surround(Doc.char("A"), Doc.char("Z"))
* )
*
* assert.strictEqual(
* Doc.render(doc, { style: "pretty" }),
* "A-Z"
* )
* ```
*
* @since 1.0.0
* @category utilities
*/
(self: Doc, left: Doc, right: Doc): Doc
} = internal.surround
/**
* Encloses the input document in single quotes (`""`).
*
* @since 1.0.0
* @category utilities
*/
export const singleQuoted: (self: Doc) => Doc = internal.singleQuoted
/**
* Encloses the input document in double quotes (`""`).
*
* @since 1.0.0
* @category utilities
*/
export const doubleQuoted: (self: Doc) => Doc = internal.doubleQuoted
/**
* Encloses the input document in parentheses (`()`).
*
* @since 1.0.0
* @category utilities
*/
export const parenthesized: (self: Doc) => Doc = internal.parenthesized
/**
* Encloses the input document in angle brackets (`<>`).
*
* @since 1.0.0
* @category utilities
*/
export const angleBracketed: (self: Doc) => Doc = internal.angleBracketed
/**
* Encloses the input document in square brackets (`[]`).
*
* @since 1.0.0
* @category utilities
*/
export const squareBracketed: (self: Doc) => Doc = internal.squareBracketed
/**
* Encloses the input document in curly braces (`{}`).
*
* @since 1.0.0
* @category utilities
*/
export const curlyBraced: (self: Doc) => Doc = internal.curlyBraced
/**
* The `spaces` combinator lays out a document containing `n` spaces. Negative
* values for `n` count as `0` spaces.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
*
* const doc = Doc.squareBracketed(Doc.doubleQuoted(Doc.spaces(5)))
*
* assert.strictEqual(
* Doc.render(doc, { style: "pretty" }),
* "[\" \"]"
* )
* ```
*
* @since 1.0.0
* @category utilities
*/
export const spaces: (n: number) => Doc = internal.spaces
/**
* @since 1.0.0
* @category utilities
*/
export const textSpaces: (n: number) => string = internal.textSpaces
/**
* Splits a string of words into individual `Text` documents using the
* specified `char` to split on (defaults to `" "`).
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
*
* const doc = Doc.tupled(Doc.words("lorem ipsum dolor"))
*
* assert.strictEqual(
* Doc.render(doc, { style: "pretty" }),
* "(lorem, ipsum, dolor)"
* )
* ```
*
* @since 1.0.0
* @category utilities
*/
export const words: (s: string, char?: string) => ReadonlyArray> = internal.words
/**
* Splits a string of words into individual `Text` documents using the specified
* `char` to split on (defaults to `" "`). In addition, a `softLine` is inserted
* in between each word so that if the text exceeds the available width it will
* be broken into multiple lines.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import * as String from "effect/String"
*
* const doc = Doc.reflow(
* "Lorem ipsum dolor sit amet, consectetur adipisicing elit, " +
* "sed do eiusmod tempor incididunt ut labore et dolore magna aliqua."
* )
*
* assert.strictEqual(
* Doc.render(doc, {
* style: "pretty",
* options: { lineWidth: 32 }
* }),
* String.stripMargin(
* `|Lorem ipsum dolor sit amet,
* |consectetur adipisicing elit,
* |sed do eiusmod tempor incididunt
* |ut labore et dolore magna
* |aliqua.`
* )
* )
* ```
*
* @since 1.0.0
* @category utilities
*/
export const reflow: (s: string, char?: string) => Doc = internal.reflow
/**
* The `punctuate` combinator appends the `punctuator` document to all but the
* last document in a collection of documents. The separators are places after
* the document entries, which can be observed if the result is oriented
* vertically.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import { pipe } from "effect/Function"
* import * as String from "effect/String"
*
* const docs = pipe(
* Doc.words("lorem ipsum dolor sit amet"),
* Doc.punctuate(Doc.comma)
* )
*
* assert.strictEqual(
* Doc.render(Doc.hsep(docs), { style: "pretty" }),
* "lorem, ipsum, dolor, sit, amet"
* )
*
* // The separators are put at the end of the entries, which can be better
* // visualzied if the documents are rendered vertically
* assert.strictEqual(
* Doc.render(Doc.vsep(docs), { style: "pretty" }),
* String.stripMargin(
* `|lorem,
* |ipsum,
* |dolor,
* |sit,
* |amet`
* )
* )
* ```
*
* @since 1.0.0
* @category utilities
*/
export const punctuate: {
/**
* The `punctuate` combinator appends the `punctuator` document to all but the
* last document in a collection of documents. The separators are places after
* the document entries, which can be observed if the result is oriented
* vertically.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import { pipe } from "effect/Function"
* import * as String from "effect/String"
*
* const docs = pipe(
* Doc.words("lorem ipsum dolor sit amet"),
* Doc.punctuate(Doc.comma)
* )
*
* assert.strictEqual(
* Doc.render(Doc.hsep(docs), { style: "pretty" }),
* "lorem, ipsum, dolor, sit, amet"
* )
*
* // The separators are put at the end of the entries, which can be better
* // visualzied if the documents are rendered vertically
* assert.strictEqual(
* Doc.render(Doc.vsep(docs), { style: "pretty" }),
* String.stripMargin(
* `|lorem,
* |ipsum,
* |dolor,
* |sit,
* |amet`
* )
* )
* ```
*
* @since 1.0.0
* @category utilities
*/
(punctuator: Doc): (docs: Iterable>) => ReadonlyArray>
/**
* The `punctuate` combinator appends the `punctuator` document to all but the
* last document in a collection of documents. The separators are places after
* the document entries, which can be observed if the result is oriented
* vertically.
*
* @example
* ```ts
* import * as assert from "node:assert"
* import * as Doc from "@effect/printer/Doc"
* import { pipe } from "effect/Function"
* import * as String from "effect/String"
*
* const docs = pipe(
* Doc.words("lorem ipsum dolor sit amet"),
* Doc.punctuate(Doc.comma)
* )
*
* assert.strictEqual(
* Doc.render(Doc.hsep(docs), { style: "pretty" }),
* "lorem, ipsum, dolor, sit, amet"
* )
*
* // The separators are put at the end of the entries, which can be better
* // visualzied if the documents are rendered vertically
* assert.strictEqual(
* Doc.render(Doc.vsep(docs), { style: "pretty" }),
* String.stripMargin(
* `|lorem,
* |ipsum,
* |dolor,
* |sit,
* |amet`
* )
* )
* ```
*
* @since 1.0.0
* @category utilities
*/
(docs: Iterable>, punctuator: Doc): ReadonlyArray>
} = internal.punctuate