Module doc 

A small, self-contained pretty-printing engine in the Wadler → Prettier → rome/biome → ruff lineage. The grammar-agnostic core is a Doc intermediate representation plus a width-aware [print]er; SQL-specific rules live in [crate::sql] and only ever build Docs.

The model has three moving parts:

• Builders (text, [concat], group, indent, [line], soft_line, hard_line, space, join) construct the IR.
• Groups are the unit of layout choice: a group is printed flat (its soft lines become spaces or nothing) when it fits within the remaining width, otherwise it breaks (its soft lines become newlines + indentation).
• A hard line forces every group that contains it to break — the classic breakParent propagation — so caller-mandated line breaks are never silently collapsed.

See docs/research/prior-art.md for the design rationale and references.

Macros

doc_write

Push a comma-bracketed list of Format elements into a DocBuffer, in order.

Structs

DocBuffer

A growable sink of Doc elements, the target of the doc_write! macro and of Format implementors.

PrintOptions

Knobs for the printer. Opinionated by design: just a target width and an indent step.

Enums

Doc

The pretty-printer intermediate representation.

LineKind

How a Doc::Line renders, as a function of the enclosing group’s mode.

Traits

Format

A value that knows how to render itself into a DocBuffer.

FormatRule

Formatting logic for a T kept outside T, matching the biome/ruff rule pattern.

Functions

best_fitting

Try the candidate documents in order, printing the first that fits in the remaining width and falling back to the last candidate when none fit. Empty candidates render as empty.

block_indent

A hard-line-delimited, indented block: inner is placed on its own indented line(s), framed by a hard line before and after (Prettier/biome’s block_indent).

break_parent

Force enclosing groups to break without emitting a newline here.

concat

Lay out the parts one after another.

empty

The empty document (renders to nothing).

format_value

Run a single Format value to completion, returning its assembled Doc.

group

A layout-choice group: flat when it fits on the line, broken otherwise.

group_expanded

A group forced to break (its soft lines always become newlines), without forcing enclosing groups to break. The building block for magic-trailing-comma “keep this exploded”.

hard_line

Always a newline; forces enclosing groups to break.

if_group_breaks

Choose broken when the enclosing group breaks and flat when it stays flat (Prettier’s ifBreak). Neither arm emits a newline by itself; this only selects which content appears.

indent

Indent every line break that occurs inside inner by one more level.

join

Interleave sep between items (no separator before the first or after the last).

line

A space when flat, a newline when broken.

line_suffix

Defer inner to just before the next newline (used for trailing line comments).

print

Render doc to a string. Trailing whitespace is trimmed from every line and the result ends with exactly one newline (or is empty), so the output is stable under re-formatting.

soft_line

Nothing when flat, a newline when broken.

source_code_slice

A verbatim slice of source that may span multiple lines. Use this — not text — for fallback regions that can contain embedded newlines: it re-bases the column at each newline so the slice stays aligned under indentation, and caches its last line’s display width for fit decisions.

space

A literal, non-collapsible space.

text

Verbatim text (a borrowed &'static str or an owned String). The display width is measured once here and cached on the node, so the printer’s fit/break measurement never re-scans it.