/** * @since 1.0.0 */ import type * as covariant from "@effect/typeclass/Covariant" import type * as invariant from "@effect/typeclass/Invariant" import type * as monoid from "@effect/typeclass/Monoid" import type * as semigroup from "@effect/typeclass/Semigroup" import type { Equal } from "effect/Equal" import type { TypeLambda } from "effect/HKT" import type * as DocStream from "./DocStream.js" import * as internal from "./internal/docTree.js" // ----------------------------------------------------------------------------- // Models // ----------------------------------------------------------------------------- /** * @since 1.0.0 * @category symbol */ export const DocTreeTypeId: unique symbol = internal.DocTreeTypeId as DocTreeTypeId /** * @since 1.0.0 * @category symbol */ export type DocTreeTypeId = typeof DocTreeTypeId /** * Represents a document that has been laid out into a tree-like structure. * * A `DocStream` is a linked list of different annotated cons cells (i.e. * `TextStream` and then some further `DocStream`, `LineStream` and then some * further `DocStream`, etc.). The `DocStream` format is quite suitable as a * target for a layout engine, but is not suitable for rendering to a more * structured format, such as HTML, where we do not want to perform a lookahead * until the end of some pre-defined markup. These formats would benefit more * from a tree-like structure that explicitly marks its contents as annotated. * A `DocTree` is therefore much more suitable for this use case. * * @since 1.0.0 * @category model */ export type DocTree = | EmptyTree | CharTree | TextTree | LineTree | AnnotationTree | ConcatTree /** * @since 1.0.0 */ export declare namespace DocTree { /** * @since 1.0.0 */ export interface Variance extends Equal { readonly [DocTreeTypeId]: { readonly _A: (_: never) => A } } /** * @since 1.0.0 */ export type TypeLambda = DocTreeTypeLambda } /** * @since 1.0.0 * @category model */ export interface DocTreeTypeLambda extends TypeLambda { readonly type: DocTree } /** * @since 1.0.0 * @category model */ export interface EmptyTree extends DocTree.Variance { readonly _tag: "EmptyTree" } /** * @since 1.0.0 * @category model */ export interface CharTree extends DocTree.Variance { readonly _tag: "CharTree" readonly char: string } /** * @since 1.0.0 * @category model */ export interface TextTree extends DocTree.Variance { readonly _tag: "TextTree" readonly text: string } /** * @since 1.0.0 * @category model */ export interface LineTree extends DocTree.Variance { readonly _tag: "LineTree" readonly indentation: number } /** * @since 1.0.0 * @category model */ export interface AnnotationTree extends DocTree.Variance { readonly _tag: "AnnotationTree" readonly annotation: A readonly tree: DocTree } /** * @since 1.0.0 * @category model */ export interface ConcatTree extends DocTree.Variance { readonly _tag: "ConcatTree" readonly trees: ReadonlyArray> } // ----------------------------------------------------------------------------- // Refinements // ----------------------------------------------------------------------------- /** * Returns `true` if the specified value is a `DocTree`, `false` otherwise. * * @since 1.0.0 * @category refinements */ export const isDocTree: (u: unknown) => u is DocTree = internal.isDocTree /** * Returns `true` if the specified `DocTree` is an `EmptyTree`, `false` otherwise. * * @since 1.0.0 * @category refinements */ export const isEmptyTree: (self: DocTree) => self is EmptyTree = internal.isEmptyTree /** * Returns `true` if the specified `DocTree` is an `CharTree`, `false` otherwise. * * @since 1.0.0 * @category refinements */ export const isCharTree: (self: DocTree) => self is CharTree = internal.isCharTree /** * Returns `true` if the specified `DocTree` is an `TextTree`, `false` otherwise. * * @since 1.0.0 * @category refinements */ export const isTextTree: (self: DocTree) => self is TextTree = internal.isTextTree /** * Returns `true` if the specified `DocTree` is an `LineTree`, `false` otherwise. * * @since 1.0.0 * @category refinements */ export const isLineTree: (self: DocTree) => self is LineTree = internal.isLineTree /** * Returns `true` if the specified `DocTree` is an `AnnotationTree`, `false` otherwise. * * @since 1.0.0 * @category refinements */ export const isAnnotationTree: (self: DocTree) => self is AnnotationTree = internal.isAnnotationTree /** * Returns `true` if the specified `DocTree` is an `ConcatTree`, `false` otherwise. * * @since 1.0.0 * @category refinements */ export const isConcatTree: (self: DocTree) => self is ConcatTree = internal.isConcatTree // ----------------------------------------------------------------------------- // Constructors // ----------------------------------------------------------------------------- /** * @since 1.0.0 * @category constructors */ export const empty: DocTree = internal.empty /** * @since 1.0.0 * @category constructors */ export const char: (char: string) => DocTree = internal.char /** * @since 1.0.0 * @category constructors */ export const text: (text: string) => DocTree = internal.text /** * @since 1.0.0 * @category constructors */ export const line: (indentation: number) => DocTree = internal.line /** * Annotate the specified `DocTree` with an annotation of type `A`. * * @since 1.0.0 * @category constructors */ export const annotation: { /** * Annotate the specified `DocTree` with an annotation of type `A`. * * @since 1.0.0 * @category constructors */ (annotation: A): (self: DocTree) => DocTree /** * Annotate the specified `DocTree` with an annotation of type `A`. * * @since 1.0.0 * @category constructors */ (self: DocTree, annotation: B): DocTree } = internal.annotation /** * Horizontally concatenates multiple `DocTree`s. * * @since 1.0.0 * @category constructors */ export const concat: (trees: ReadonlyArray>) => DocTree = internal.concat // ----------------------------------------------------------------------------- // Annotations // ----------------------------------------------------------------------------- /** * Change the annotation of a document to a different annotation, or none at * all. * * @since 1.0.0 * @category annotations */ export const alterAnnotations: { // ----------------------------------------------------------------------------- // Annotations // ----------------------------------------------------------------------------- /** * Change the annotation of a document to a different annotation, or none at * all. * * @since 1.0.0 * @category annotations */ (f: (a: A) => Iterable): (self: DocTree) => DocTree // ----------------------------------------------------------------------------- // Annotations // ----------------------------------------------------------------------------- /** * Change the annotation of a document to a different annotation, or none at * all. * * @since 1.0.0 * @category annotations */ (self: DocTree, f: (a: A) => Iterable): DocTree } = internal.alterAnnotations /** * Change the annotation of a `DocTree`. * * @since 1.0.0 * @category annotations */ export const reAnnotate: { /** * Change the annotation of a `DocTree`. * * @since 1.0.0 * @category annotations */ (f: (a: A) => B): (self: DocTree) => DocTree /** * Change the annotation of a `DocTree`. * * @since 1.0.0 * @category annotations */ (self: DocTree, f: (a: A) => B): DocTree } = internal.reAnnotate /** * Remove all annotations from a `DocTree`. * * @since 1.0.0 * @category annotations */ export const unAnnotate: (self: DocTree) => DocTree = internal.unAnnotate // ----------------------------------------------------------------------------- // Folding // ----------------------------------------------------------------------------- /** * @since 1.0.0 * @category folding */ export const foldMap: { // ----------------------------------------------------------------------------- // Folding // ----------------------------------------------------------------------------- /** * @since 1.0.0 * @category folding */ (M: monoid.Monoid, f: (a: A) => M): (self: DocTree) => M // ----------------------------------------------------------------------------- // Folding // ----------------------------------------------------------------------------- /** * @since 1.0.0 * @category folding */ (self: DocTree, M: monoid.Monoid, f: (a: A) => M): M } = internal.foldMap // ----------------------------------------------------------------------------- // Instances // ----------------------------------------------------------------------------- /** * The simplest possible tree-based renderer. * * For example, here is a document annotated with `void` and thee behavior is * to surround annotated regions with »>>>« and »<<<«. * * @example * ```ts * import * as assert from "node:assert" * import * as Doc from "@effect/printer/Doc" * import * as DocTree from "@effect/printer/DocTree" * import * as Layout from "@effect/printer/Layout" * import { identity, pipe } from "effect/Function" * import * as String from "@effect/typeclass/data/String" * * const doc: Doc.Doc = Doc.hsep([ * Doc.text("hello"), * pipe( * Doc.text("world"), * Doc.annotate(undefined), * Doc.cat(Doc.char("!")) * ) * ]) * * const tree = DocTree.treeForm(Layout.pretty(Layout.defaultOptions)(doc)) * * const rendered = pipe( * tree, * DocTree.renderSimplyDecorated(String.Monoid, identity, (_, x) => `>>>${x}<<<`) * ) * * assert.strictEqual( * rendered, * "hello >>>world<<>>« and »<<<«. * * @example * ```ts * import * as assert from "node:assert" * import * as Doc from "@effect/printer/Doc" * import * as DocTree from "@effect/printer/DocTree" * import * as Layout from "@effect/printer/Layout" * import { identity, pipe } from "effect/Function" * import * as String from "@effect/typeclass/data/String" * * const doc: Doc.Doc = Doc.hsep([ * Doc.text("hello"), * pipe( * Doc.text("world"), * Doc.annotate(undefined), * Doc.cat(Doc.char("!")) * ) * ]) * * const tree = DocTree.treeForm(Layout.pretty(Layout.defaultOptions)(doc)) * * const rendered = pipe( * tree, * DocTree.renderSimplyDecorated(String.Monoid, identity, (_, x) => `>>>${x}<<<`) * ) * * assert.strictEqual( * rendered, * "hello >>>world<<( M: monoid.Monoid, renderText: (text: string) => M, renderAnnotation: (annotation: A, out: M) => M ): (self: DocTree) => M // ----------------------------------------------------------------------------- // Instances // ----------------------------------------------------------------------------- /** * The simplest possible tree-based renderer. * * For example, here is a document annotated with `void` and thee behavior is * to surround annotated regions with »>>>« and »<<<«. * * @example * ```ts * import * as assert from "node:assert" * import * as Doc from "@effect/printer/Doc" * import * as DocTree from "@effect/printer/DocTree" * import * as Layout from "@effect/printer/Layout" * import { identity, pipe } from "effect/Function" * import * as String from "@effect/typeclass/data/String" * * const doc: Doc.Doc = Doc.hsep([ * Doc.text("hello"), * pipe( * Doc.text("world"), * Doc.annotate(undefined), * Doc.cat(Doc.char("!")) * ) * ]) * * const tree = DocTree.treeForm(Layout.pretty(Layout.defaultOptions)(doc)) * * const rendered = pipe( * tree, * DocTree.renderSimplyDecorated(String.Monoid, identity, (_, x) => `>>>${x}<<<`) * ) * * assert.strictEqual( * rendered, * "hello >>>world<<( self: DocTree, M: monoid.Monoid, renderText: (text: string) => M, renderAnnotation: (annotation: A, out: M) => M ): M } = internal.renderSimplyDecorated // ----------------------------------------------------------------------------- // Conversions // ----------------------------------------------------------------------------- /** * Converts a `DocStream` into a `DocTree`. * * @since 1.0.0 * @category conversions */ export const treeForm: (stream: DocStream.DocStream) => DocTree = internal.treeForm // ----------------------------------------------------------------------------- // Instances // ----------------------------------------------------------------------------- /** * @since 1.0.0 * @category instances */ export const getSemigroup: (_: void) => semigroup.Semigroup> = internal.getSemigroup /** * @since 1.0.0 * @category instances */ export const getMonoid: (_: void) => monoid.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