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 the formatter’s SQL lowering module 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

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.

Functions

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).

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.

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.