laidout
Laidout is a standalone pretty-printing kernel with deterministic layout,
application-owned annotations, and reusable allocation control. Build an
immutable Doc<A>, prepare it once, then render with a fast column-accurate
strategy or an exact cost-minimizing strategy.
Laidout 0.3 supports Rust 1.85 and newer, has no unsafe code, and does not
require annotations to implement Eq, Hash, Clone, or Debug.
Quick start
For occasional rendering, use the owned API:
use NonZeroU32;
use ;
let doc = group;
let options = new;
let output = render?;
assert_eq!;
# Ok::
For repeated rendering, retain a Renderer. It reuses its workspace and can
render owned output or write a prepared document directly to fmt::Write and
io::Write sinks:
use NonZeroU32;
use ;
let prepared = group.prepare?;
let options = new;
let mut renderer = new;
let first = renderer.render_prepared?;
assert_eq!;
let mut sink = Stringnew;
renderer.write_fmt?;
assert_eq!;
# Ok::
Integration choices
| Need | API |
|---|---|
| Render once to owned text and spans | render(&Doc, options) |
| Reuse allocations across calls | Renderer |
| Prepare once, render at many widths | Doc::prepare + Renderer::render_prepared |
| Write without cloning owned output | Renderer::write_fmt or write_io |
| Full allocation control | render_into with RenderWorkspace |
| Custom output protocol | solve_into with LayoutVisitor |
| Custom annotation model | Doc<A> or Doc::map_annotations |
| Ingest and classify unstructured text | from_text_with_annotations |
| Override display width from a host system | Doc::text_with_columns |
The prelude module exports the most common document and renderer types.
Application-owned annotations
Annotations are retained by shared identity, not deduplicated by value. Dynamic and foreign annotation models require no comparison or hashing traits:
use ;
let doc = from_text_with_annotations?;
let prepared = doc.prepare?;
assert!;
# Ok::
Doc::text measures Unicode width when the run is constructed. If a terminal,
editor, or protocol supplies its own width, use Doc::text_with_columns to
store that authoritative measurement.
Fast, exact, and fixed rendering
LayoutStrategy::Fast uses prepared first-stop summaries and makes
constant-time fit decisions. LayoutStrategy::Exact uses stable Pareto
frontiers to minimize Laidout's checked overflow-and-burden cost. Exact is the
default; choose Fast when latency and linear work matter more than global cost
optimality.
RenderWorkspace::growable() expands named buffers as needed. To guarantee
zero allocator calls during rendering, warm the exact prepared
document/width/strategy combination, retain workspace.capacity(), and switch
to WorkspaceMode::Fixed. Insufficient storage returns a typed error; Laidout
never silently changes strategy or publishes an approximate result.
Correctness and scope
- Text is validated and measured once; line breaks are structural nodes.
- Preparation rejects documents whose complete candidate output or cost domain cannot be represented.
- The
researchfeature exposes arbitrary-precision oracle engines and footprint inspection used by the verification suite. - Tables compile to ordinary document nodes and support the same generic annotation type as their cells.
- Laidout owns no terminal styling or downstream application vocabulary.
See the API documentation, 0.3 migration
guide, table contract, and
cost proof. Runnable integrations live in
examples/standalone.rs and
examples/flexible.rs.
Contributing and security
The contribution process is defined in CONTRIBUTING.md. Report vulnerabilities through SECURITY.md, never through a public issue. Community participation is governed by CODE_OF_CONDUCT.md.
Laidout is available under the MIT license.