The default cost factory.

Parameters:

• pageWidth -- the page width limit. Text extending past this column incurs badness cost.
• computationWidth -- optional computation width limit. Defaults to floor(1.2 * pageWidth). When the current column or indentation level exceeds this during rendering, the result is marked Tainted and the printer stops maintaining the full candidate set.

Cost ordering: Costs are compared lexicographically -- badness is minimized first, then columnOverflow, then height. The printer will always prefer a layout that fits within the page width (even at the cost of more newlines), and among equally bad layouts it prefers fewer column overflows, then fewer newlines.

twoColumnsOverflow: Charges columnOverflow = w and height = 1 when a left cell overshoots the separator by w columns. The extra height penalty discourages the printer from choosing a separator so narrow that every left cell overflows.

twoColumnsBias: Returns zero for all inputs in the default factory. The preference for leftmost separators is achieved by the order in which loopLimit tries candidates, not by a non-zero bias cost.

Attach an extra cost c to document d without changing its layout.

The additional cost is combined with d's ordinary layout cost using CostFactory.combine. This lets you nudge the optimizer toward or away from specific layouts when the default cost model does not capture your preferences precisely.

addCost on DocFail returns DocFail unchanged, since a failing document produces no layout to charge.

Set the indentation level to the current column position for d.

This "pins" d so that its internal newlines indent back to the column where d starts, regardless of the surrounding nest context. It is the key combinator for hanging indentation and argument-list alignment.

Pass-through cases are the same as nest: DocFail, DocAlign, DocReset, DocText, and DocAddCost (floated outward).

Aligned concatenation: append b to a with b anchored to the column where a ends.

Equivalent to concat a (align b). Also known as box concatenation -- b is treated as a rigid box whose left edge is pinned to a's end column.

-- `b` is anchored to column 8 (end of "Languages") and its
-- internal newlines indent back to that column:
alignedConcat (P.text "Languages: ")
    (P.vcat [ P.text "Gren", P.text "Elm", P.text "Haskell" ])

-- Languages: Gren
--            Elm
--            Haskell

A newline that flattens to an empty string.

Use this when adjacent tokens should touch with no separator in the flat form, but may be placed on separate lines in the broken form. It produces an empty string only when it appears inside group (or an explicit flatten).

Choose between two document layouts; the printer picks the cheaper one.

Both branches are fully evaluated by the resolver. The resulting measure sets are merged with Pareto-dominance filtering: a layout from one branch is discarded if the other branch has a layout that is both cheaper and ends no further right.

If either branch is failDoc it is dropped and the other is returned unconditionally, without creating a DocChoice node.

A comma. Equivalent to text ",".

Unaligned concatenation of two documents.

concat a b renders a followed immediately by b. The right document is not treated as a rigid box: it does not inherit any special alignment from where a ended. This "unaligned" semantics makes it straightforward to format C-style code where braces, brackets, and parentheses should flow freely.

The smart constructor applies several normalization rules at build time to keep the document tree compact:

• Either operand being DocFail short-circuits to DocFail.
• Either operand being DocText { width = 0 } (i.e. empty) is dropped.
• Two adjacent DocText nodes are fused into one.
• A DocAddCost on either operand is floated outward, keeping cost annotations above structural nodes. This normalizes the tree shape so the resolver sees consistent node forms.

Concatenate an array of documents in left-to-right order.

A handy shorthand when you have an array of docs to glue together without any separator. Left-folds via concat, so for [a, b, c, d] the result is structurally concat (concat (concat a b) c) d — but since concat is associative the rendered output is the same as any other concatenation order.

concat_array [ P.text "foo", P.text "bar", P.text "baz" ]
-- renders as "foobarbaz"

For separator-delimited concatenation use foldDoc directly:

items =
    [ P.text "x", P.text "y", P.text "z" ]

P.foldDoc (\a b -> P.concat a (P.concat (P.text ", ") b)) items
-- renders as "x, y, z"

A double-quote character. Equivalent to text "\"".

The empty document. Equivalent to text "".

empty is the identity element of concat: concat empty d == d and concat d empty == d. These equalities are enforced structurally in the concat smart constructor, so no extra node is allocated.

A document that always fails to render.

On its own, rendering a failDoc returns Nothing. Its power comes from pairing it with choice: the printer prunes any branch that contains a failDoc, automatically falling back to the other branch.

Flatten a, then concatenate with b aligned to a's end column.

Equivalent to alignedConcat (flatten a) b. Useful when you want aligned (box) concatenation but want to guarantee that the left operand never spans multiple lines -- if flatten a fails, the whole expression fails and a surrounding choice can select an alternative layout.

-- Force the label onto one line, then anchor the value beside it:
flattenAlignedConcat
    (P.text "type" |> P.concat P.nl |> P.concat (P.text "alias:"))
    (P.text "Doc cost")
-- type alias: Doc cost

Fold an array of documents with a binary combinator.

The fold is left-associative: foldDoc f [a, b, c] is f (f a b) c. Returns empty for an empty array.

-- Comma-separated list:
foldDoc (\a b -> P.concat a (P.concat (P.text ", ") b))
    [ P.text "x", P.text "y", P.text "z" ]
-- x, y, z

Try the document as-is; fall back to its flattened form if that is cheaper.

group d is shorthand for choice d (flatten d). It is the standard combinator for "break this if necessary, otherwise keep it on one line" -- the core idiom of most pretty printers.

Because choice drops failDoc branches, if flatten d fails (e.g. because d contains a hardNl) then group d is equivalent to d alone.

A small example. With a wide page, nl flattens to a space and the whole group renders on one line; with a narrow page, the soft newline breaks and the group renders on two lines:

d = group (P.text "foo" |> P.concat P.nl |> P.concat (P.text "bar"))

-- page width 80 → "foo bar"
-- page width  5 → "foo\nbar"

A newline that cannot be flattened.

flatten hardNl yields failDoc, causing any layout that tried to flatten across a hardNl to be pruned. Use this wherever a line break is mandatory regardless of available width -- for instance between top-level definitions.

Concatenate a and b with a mandatory line break between them.

Equivalent to concat a (concat hardNl b). Used by vcat to stack documents vertically.

hardNlConcat (P.text "first") (P.text "second")
-- first
-- second

Concatenate documents horizontally with flatten-aligned concatenation.

hcat [a, b, c] places each document to the right of the previous one, aligned to the column where the previous document ended, with each left operand flattened first. If any left operand fails to flatten, the surrounding choice can select an alternative.

Returns empty for an empty array.

-- Each prefix is flattened so the next piece can be anchored to a
-- known column. Useful for left-to-right tabular text:
hcat
    [ P.text "ok: "
    , P.vcat [ P.text "line1", P.text "line2" ]
    , P.text " <end>"
    ]
-- ok: line1
--     line2 <end>

A left curly brace. Equivalent to text "{".

A left square bracket. Equivalent to text "[".

A left parenthesis. Equivalent to text "(".

Increase the indentation level by n spaces for the duration of d.

nest only affects where newlines land -- it does not insert any spaces immediately. If multiple nest calls are nested, their amounts accumulate.

The smart constructor has several pass-through cases where wrapping in DocNest would have no effect:

• DocFail -- propagate failure.
• DocAlign -- align has already fixed the indentation to the current column; an outer nest cannot override that.
• DocReset -- reset fixes indentation to 0; same reasoning.
• DocText -- plain text carries no newlines, so indentation is irrelevant.
• DocAddCost -- float the cost annotation outward (same normalization as in concat).

The general newline primitive. All other newline combinators are built from this one.

• newline Nothing -- a hard newline: flatten turns it into failDoc.
• newline (Just s) -- a soft newline: flatten turns it into text s.

After the newline is emitted, indentation spaces are inserted according to the current indentation level (as set by nest, align, and reset).

A newline that flattens to a single space.

This is the most common newline in practice: it means "break the line here if necessary; otherwise substitute a space". It is the building block of group.

A right curly brace. Equivalent to text "}".

A right square bracket. Equivalent to text "]".

Reset the indentation level to 0 for d.

Any newlines inside d will indent to column 0, regardless of the surrounding nest or align context. Useful for top-level declarations or other constructs that must always begin at the left margin.

Pass-through cases match nest and align.

A right parenthesis. Equivalent to text ")".

Mark a document for memoization across multiple references.

share d returns a Builder (Doc cost) that, when run, produces a DocShared node wrapping d with a unique share id. Each reference to the resulting shared value participates in the renderer's memo cache: the first time the shared node is resolved at a given (column, indent) position, the answer is cached; subsequent references at the same position hit the cache instead of re-evaluating the subtree.

This is how the library realises the DAG semantics described in the pretty-expressive paper. Without share, multiple references to the same Gren Doc value are operationally indistinguishable from independent copies — Gren has no physical identity to leverage. With share, the common subtree is computed once per (c, i).

Sharing pays off when the same subtree is reachable through two layout branches that the renderer must both explore — for example, the exit(); sub-document in:

P.share (P.text "exit();")
    |> Builder.map (\exitD ->
        P.choice
            (P.concat P.space exitD)
            (P.nest 4 (P.concat P.nl exitD))
    )

Without sharing the renderer would resolve exit(); separately under each branch; with sharing it resolves once. For trivial leaves the win is small, but it grows with the size of the shared subtree and the depth of the choice structure around it.

Sharing sub-documents that come right after a newline

There is a second, less obvious case where share pays off — one that applies even when the shared sub-document appears only once in the tree.

A newline (hardNl, nl, or breakDoc) resets the renderer's column to the current indentation i in its broken form. Whenever a document has the shape concat newline body, the renderer's column when it starts working on body is always i, no matter what was on the line before.

The renderer's concat handler processConcat keeps a Pareto-optimal set of layouts for the left operand and re-resolves the right operand once for each of those layouts. With many layouts to consider — say, inside a wide block whose header line could break at several points — the right operand is resolved many times. If the right operand starts with a newline, every single one of those resolutions starts working on body at the same (column, indent) = (i, i). They all produce the same answer.

Wrapping body in share lets the renderer notice this: the first resolution stores its answer in the memo cache, and every subsequent resolution at the same (i, i) looks the answer up instead of recomputing. Concretely, anywhere you write

concat header (concat hardNl body)

consider switching to

share body
    |> Builder.map (\sharedBody ->
        concat header (concat hardNl sharedBody)
    )

This pattern arises naturally in block-structured layouts: indented function bodies, vertical lists, the body of any if/when/case arm whose content is laid out after a newline. The bigger body is, and the more layouts the renderer is considering for the surrounding context, the more sharing it saves you.

The nlCnt of the inner document is computed at share time and cached on the DocShared node, so the resolver's branch-order heuristic in DocChoice does not need to re-walk the shared subtree on every visit.

A single space character. Equivalent to text " ".

A document for literal text content. The string must not contain a newline character; use nl, hardNl, or newline for line breaks.

Unicode width caveat: The width field is currently set to String.count s, which counts Unicode scalar values (code points). This is incorrect for scripts such as Hindi or Thai where multiple code points combine into a single rendered character cell (a grapheme cluster). Once a Gren Unicode grapheme-cluster package is available this should be replaced with a function that counts rendered column widths.

Two-column table layout for an array of { a, b } document pairs.

The printer searches for the optimal column separator -- the column at which the right (b) cells begin -- and picks the position that minimizes total cost across all rows simultaneously.

Each row is rendered as:

concat left_cell (concat padding right_cell)

where padding is either blank spaces (if the left cell ended before the separator) or a twoColumnsOverflow cost charge (if the left cell overshot the separator).

Degenerate cases:

• Empty array -> empty.
• Single pair -> align (concat a b) (no separator search needed).
• Any pair where a or b is failDoc -> failDoc.

Cost-factory hooks:

• twoColumnsOverflow w -- charged when a left cell overshoots the separator by w columns. Setting this higher than the normal page-overflow cost makes the printer prefer exceeding the page width over clobbering the right column.
• twoColumnsBias w -- a small penalty proportional to w, the distance of the separator from the left edge. This breaks ties in favour of the leftmost (tightest) valid separator.

Why this returns a Builder: the separator search reconstructs the table once per candidate separator column, embedding every row's right cell b in the resulting DocChoice tree. Without sharing, the renderer would re-walk each b from scratch for every candidate. Wrapping each non-trivial b in share lets the renderer's memo cache short-circuit repeated visits at the same (c, i). Trivial right cells (text, newline, fail) skip the share since the wrap costs more than the leaf measure.

Stack documents vertically with hard newlines between them.

vcat [a, b, c] is equivalent to hardNlConcat a (hardNlConcat b c). Returns empty for an empty array.

vcat
    [ P.text "module Foo exposing (..)"
    , P.text ""
    , P.text "import Bar"
    ]
-- module Foo exposing (..)
--
-- import Bar

Render a document to a string, starting at column 0.

Returns Nothing if the document fails to render.

The argument is a Builder (Doc cost) rather than a Doc cost directly so that documents with shared sub-trees (built via share) carry along the id-counter state. For documents that do not use share, lift the pure Doc cost value with PrettyExpressive.Builder.return.

Like prettyFormat, but printing begins at column initC.

Use this when the rendered output will be placed after content that is already initC columns wide — for example, when the document follows a label or prompt on the same line and you want subsequent line breaks to consider that prefix.

P.prettyFormatAt cf 8 (B.return doc)
-- renders as if the doc started at column 8 (after "Output: ").

Render a document to a string with debug information appended.

The debug output includes a column ruler, the rendered content with a | marker at the page width, and the isTainted flag and cost of the chosen layout. The exact format is determined by CostFactory.debugFormat; the default implementation is makeDebugFormat.

With defaultCostFactory at page width 10, rendering Hello!\nWorld produces:

1234567890
Hello!    |
World     |

is_tainted: false
cost: (0 0 1)

The first line is the modulo-10 column ruler. Each rendered line is padded to the page width and capped with |; lines that overflow have the marker inserted at the overflow column with the excess to its right. The cost-line format depends on the cost type (here DefaultCostTuple = { badness, columnOverflow, height }).

See makeDebugFormat for the authoritative format definition.

Returns Nothing if the document fails to render.

Like prettyFormatDebug, but printing begins at column initC.

Use this when the rendered output is being shown alongside content that's already initC columns wide and you want the debug ruler to reflect that starting position.

Render a document to a string, starting at column 0, and return both the rendered string and layout metadata.

Returns Nothing if the document fails to render (e.g. it is failDoc or every layout branch fails).

Use prettyFormatInfoAt if the output will be appended after existing content that starts at a non-zero column.

Like prettyFormatInfo, but printing begins at column initC.

Use this when the rendered output will be placed after content that is already initC columns wide -- for example, when the document follows a label or prompt on the same line.

Replace all newlines in a document with their "flat" alternative. That is, convert the document to a one-line version.

Most callers use group rather than calling flatten directly. group d (= choice d (flatten d)) lets the printer pick between the original and the flattened form based on what fits, which is almost always what you want. Direct use of flatten is for the rare case where you want to force a sub-document onto one line regardless of context — flattenAlignedConcat and hcat are the canonical examples. See "Terminology > flattening" in the module header for the wider picture.

The mapping for each newline variant is:

• nl -> text " " (was DocNewline (Just " "))
• breakDoc -> text "" (was DocNewline (Just ""))
• hardNl -> failDoc (was DocNewline Nothing)
• newline (Just s) -> text s
• newline Nothing -> failDoc

For structural nodes, flatten recurses into the children:

• DocConcat, DocChoice -- recurse into both children.
• DocNest, DocAlign, DocReset -- these only affect indentation; in a flat document there are no newlines to indent to, so the wrapper is dropped and only the inner document is flattened.
• DocAddCost -- cost annotation is preserved; inner doc is flattened.
• DocTwoColumns -- a two-column layout always has at least two rows and therefore contains mandatory newlines between rows. Returns failDoc.
• DocContext, DocEvaled -- internal nodes that should not appear in user-constructed documents. Return failDoc defensively.

Produce a debug string from a rendered document.

The output has four parts:

1. A column ruler: the digits 1-9, 0, 1-9, 0, ... up to pageWidth columns.
2. The rendered content, with each line padded (or truncated) to pageWidth and a | marker appended. Lines longer than pageWidth have the marker inserted at the overflow point, with the overflow shown to the right.
3. is_tainted: true or is_tainted: false.
4. cost: <stringOfCost output>.

Example for pageWidth = 10:

1234567890
Hello!    |
World     |

is_tainted: false
cost: (0 0 1)

This function is used as the debugFormat field of defaultCostFactory but can also be called directly or adapted for custom cost factories.