/**
* 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 type { AvailablePerLine, PageWidth } from "./PageWidth.js";
/**
* @since 1.0.0
* @category symbol
*/
export declare const DocTypeId: unique symbol;
/**
* @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
*/
interface Variance extends Equal, Pipeable {
readonly [DocTypeId]: {
readonly _A: () => A;
};
}
/**
* @since 1.0.0
*/
type TypeLambda = DocTypeLambda;
/**
* @since 1.0.0
* @category model
*/
type RenderConfig = Compact | Pretty | Smart;
/**
* @since 1.0.0
* @category model
*/
interface Compact {
readonly style: "compact";
}
/**
* @since 1.0.0
* @category model
*/
interface Pretty {
readonly style: "pretty";
readonly options?: Partial>;
}
/**
* @since 1.0.0
* @category model
*/
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;
}
/**
* Returns `true` if the specified value is a `Doc`, `false` otherwise.
*
* @since 1.0.0
* @category refinements
*/
export declare const isDoc: (u: unknown) => u is Doc;
/**
* Returns `true` if the specified `Doc` is a `Fail`, `false` otherwise.
*
* @since 1.0.0
* @category refinements
*/
export declare const isFail: (self: Doc) => self is Fail;
/**
* Returns `true` if the specified `Doc` is an `Empty`, `false` otherwise.
*
* @since 1.0.0
* @category refinements
*/
export declare const isEmpty: (self: Doc) => self is Empty;
/**
* Returns `true` if the specified `Doc` is a `Char`, `false` otherwise.
*
* @since 1.0.0
* @category refinements
*/
export declare const isChar: (self: Doc) => self is Char;
/**
* Returns `true` if the specified `Doc` is a `Text`, `false` otherwise.
*
* @since 1.0.0
* @category refinements
*/
export declare const isText: (self: Doc) => self is Text;
/**
* Returns `true` if the specified `Doc` is a `Line`, `false` otherwise.
*
* @since 1.0.0
* @category refinements
*/
export declare const isLine: (self: Doc) => self is Line;
/**
* Returns `true` if the specified `Doc` is a `FlatAlt`, `false` otherwise.
*
* @since 1.0.0
* @category refinements
*/
export declare const isFlatAlt: (self: Doc) => self is FlatAlt;
/**
* Returns `true` if the specified `Doc` is a `Cat`, `false` otherwise.
*
* @since 1.0.0
* @category refinements
*/
export declare const isCat: (self: Doc) => self is Cat;
/**
* Returns `true` if the specified `Doc` is a `Nest`, `false` otherwise.
*
* @since 1.0.0
* @category refinements
*/
export declare const isNest: (self: Doc) => self is Nest;
/**
* Returns `true` if the specified `Doc` is a `Union`, `false` otherwise.
*
* @since 1.0.0
* @category refinements
*/
export declare const isUnion: (self: Doc) => self is Union;
/**
* Returns `true` if the specified `Doc` is a `Column`, `false` otherwise.
*
* @since 1.0.0
* @category refinements
*/
export declare const isColumn: (self: Doc) => self is Column;
/**
* Returns `true` if the specified `Doc` is a `WithPageWidth`, `false` otherwise.
*
* @since 1.0.0
* @category refinements
*/
export declare const isWithPageWidth: (self: Doc) => self is WithPageWidth;
/**
* Returns `true` if the specified `Doc` is a `Nesting`, `false` otherwise.
*
* @since 1.0.0
* @category refinements
*/
export declare const isNesting: (self: Doc) => self is Nesting;
/**
* Returns `true` if the specified `Doc` is a `Annotated`, `false` otherwise.
*
* @since 1.0.0
* @category refinements
*/
export declare const isAnnotated: (self: Doc) => self is Annotated;
/**
* 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 declare const char: (char: string) => Doc;
/**
* 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 declare const text: (text: string) => Doc;
/**
* 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 declare const string: (str: string) => Doc;
/**
* 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 declare const empty: Doc;
/**
* 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 declare const fail: Doc;
/**
* 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 declare const line: Doc;
/**
* 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 declare const lineBreak: Doc;
/**
* 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 declare const softLine: Doc;
/**
* 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 declare const softLineBreak: Doc;
/**
* 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 declare const hardLine: Doc;
/**
* A document containing a single `\` character.
*
* @since 1.0.0
* @category primitives
*/
export declare const backslash: Doc;
/**
* A document containing a single `:` character.
*
* @since 1.0.0
* @category primitives
*/
export declare const colon: Doc;
/**
* A document containing a single `,` character.
*
* @since 1.0.0
* @category primitives
*/
export declare const comma: Doc;
/**
* A document containing a single `.` character.
*
* @since 1.0.0
* @category primitives
*/
export declare const dot: Doc;
/**
* A document containing a single `"` character.
*
* @since 1.0.0
* @category primitives
*/
export declare const dquote: Doc;
/**
* A document containing a single `=` character.
*
* @since 1.0.0
* @category primitives
*/
export declare const equalSign: Doc;
/**
* A document containing a single `<` character.
*
* @since 1.0.0
* @category primitives
*/
export declare const langle: Doc;
/**
* A document containing a single `{` character.
*
* @since 1.0.0
* @category primitives
*/
export declare const lbrace: Doc;
/**
* A document containing a single `[` character.
*
* @since 1.0.0
* @category primitives
*/
export declare const lbracket: Doc;
/**
* A document containing a single `(` character.
*
* @since 1.0.0
* @category primitives
*/
export declare const lparen: Doc;
/**
* A document containing a single `>` character.
*
* @since 1.0.0
* @category primitives
*/
export declare const rangle: Doc;
/**
* A document containing a single `}` character.
*
* @since 1.0.0
* @category primitives
*/
export declare const rbrace: Doc;
/**
* A document containing a single `]` character.
*
* @since 1.0.0
* @category primitives
*/
export declare const rbracket: Doc;
/**
* A document containing a single `)` character.
*
* @since 1.0.0
* @category primitives
*/
export declare const rparen: Doc;
/**
* A document containing a single `;` character.
*
* @since 1.0.0
* @category primitives
*/
export declare const semi: Doc;
/**
* A document containing a single `/` character.
*
* @since 1.0.0
* @category primitives
*/
export declare const slash: Doc;
/**
* A document containing a single `"` character.
*
* @since 1.0.0
* @category primitives
*/
export declare const squote: Doc;
/**
* A document containing a single ` ` character.
*
* @since 1.0.0
* @category primitives
*/
export declare const space: Doc;
/**
* A document containing a single `|` character.
*
* @since 1.0.0
* @category primitives
*/
export declare const vbar: Doc;
/**
* The `cat` combinator lays out two documents separated by nothing.
*
* @since 1.0.0
* @category concatenation
*/
export declare const cat: {
/**
* The `cat` combinator lays out two documents separated by nothing.
*
* @since 1.0.0
* @category concatenation
*/
(that: Doc): (self: Doc) => Doc;
/**
* The `cat` combinator lays out two documents separated by nothing.
*
* @since 1.0.0
* @category concatenation
*/
(self: Doc, that: Doc): Doc;
};
/**
* 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 declare const cats: (docs: Iterable>) => 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
*/
export declare 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;
};
/**
* 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 declare 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;
};
/**
* 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 declare 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;
};
/**
* 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 declare 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;
};
/**
* 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 declare 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;
};
/**
* 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 declare 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;
};
/**
* 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 declare const vcat: (docs: Iterable>) => Doc;
/**
* 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 declare const hcat: (docs: Iterable>) => Doc;
/**
* 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 declare const fillCat: (docs: Iterable>) => Doc;
/**
* 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 declare const hsep: (docs: Iterable>) => Doc;
/**
* 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 declare const vsep: (docs: Iterable>) => Doc;
/**
* 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 declare const fillSep: (docs: Iterable>) => Doc;
/**
* 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 declare const seps: (docs: Iterable>) => Doc;
/**
* 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 declare const flatAlt: {
/**
* 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;
/**
* 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;
};
/**
* @since 1.0.0
* @category alternative layouts
*/
export declare 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;
};
/**
* 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 declare const group: (self: Doc) => Doc;
/**
* 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 declare const column: (react: (position: number) => Doc) => Doc;
/**
* 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 declare const nesting: (react: (level: number) => 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
*/
export declare 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;
};
/**
* 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 declare const pageWidth: (react: (pageWidth: PageWidth) => Doc) => Doc;
/**
* 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 declare const nest: {
/**
* 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;
/**
* 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;
};
/**
* 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 declare const align: (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
*/
export declare 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;
};
/**
* 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 declare 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;
};
/**
* 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 declare 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;
};
/**
* 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 declare const list: (docs: Iterable>) => Doc;
/**
* 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 declare const tupled: (docs: Iterable>) => Doc;
/**
* 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 declare const fill: {
/**
* 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;
/**
* 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;
};
/**
* 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 declare 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;
};
/**
* Flattens a document but does not report changes.
*
* @since 1.0.0
* @category flattening
*/
export declare const flatten: (self: Doc) => Doc;
/**
* 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 declare const changesUponFlattening: (self: Doc) => Flatten>;
/**
* 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 declare const annotate: {
/**
* 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;
/**
* 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;
};
/**
* 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 declare 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;
};
/**
* 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 declare 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;
};
/**
* 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 declare const unAnnotate: (self: Doc) => Doc;
/**
* @since 1.0.0
* @category folding
*/
export declare const match: {
/**
* @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;
/**
* @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;
};
/**
* @since 1.0.0
* @category rendering
*/
export declare const render: {
/**
* @since 1.0.0
* @category rendering
*/
(config: Doc.RenderConfig): (self: Doc) => string;
/**
* @since 1.0.0
* @category rendering
*/
(self: Doc, config: Doc.RenderConfig): string;
};
/**
* @since 1.0.0
* @category rendering
*/
export declare const renderStream: (self: DocStream) => string;
/**
* @since 1.0.0
* @category combinators
*/
export declare const map: {
/**
* @since 1.0.0
* @category combinators
*/
(f: (a: A) => B): (self: Doc) => Doc;
/**
* @since 1.0.0
* @category combinators
*/
(self: Doc, f: (a: A) => B): Doc;
};
/**
* @since 1.0.0
* @category instances
*/
export declare const getSemigroup: (_: void) => Semigroup>;
/**
* @since 1.0.0
* @category instances
*/
export declare const getMonoid: (_: void) => Monoid>;
/**
* @since 1.0.0
* @category instances
*/
export declare const Covariant: covariant.Covariant;
/**
* @since 1.0.0
* @category instances
*/
export declare const Invariant: invariant.Invariant;
/**
* 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 declare const sanitize: (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
*/
export declare 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;
};
/**
* Encloses the input document in single quotes (`""`).
*
* @since 1.0.0
* @category utilities
*/
export declare const singleQuoted: (self: Doc) => Doc;
/**
* Encloses the input document in double quotes (`""`).
*
* @since 1.0.0
* @category utilities
*/
export declare const doubleQuoted: (self: Doc) => Doc;
/**
* Encloses the input document in parentheses (`()`).
*
* @since 1.0.0
* @category utilities
*/
export declare const parenthesized: (self: Doc) => Doc;
/**
* Encloses the input document in angle brackets (`<>`).
*
* @since 1.0.0
* @category utilities
*/
export declare const angleBracketed: (self: Doc) => Doc;
/**
* Encloses the input document in square brackets (`[]`).
*
* @since 1.0.0
* @category utilities
*/
export declare const squareBracketed: (self: Doc) => Doc;
/**
* Encloses the input document in curly braces (`{}`).
*
* @since 1.0.0
* @category utilities
*/
export declare const curlyBraced: (self: Doc) => Doc;
/**
* 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 declare const spaces: (n: number) => Doc;
/**
* @since 1.0.0
* @category utilities
*/
export declare const textSpaces: (n: number) => string;
/**
* 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 declare const words: (s: string, char?: string) => ReadonlyArray>;
/**
* 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 declare const reflow: (s: string, char?: string) => Doc;
/**
* 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 declare 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>;
};
//# sourceMappingURL=Doc.d.ts.map