Crate typeset

Typeset: A DSL for Pretty Printing

Typeset is a powerful embedded domain-specific language (DSL) for defining source code pretty printers. It provides a clean, compositional approach to formatting structured data with automatic line breaking, indentation, and layout optimization.

Quick Start

use typeset::{compile, render, text, comp, nest, grp};

// Create a simple layout
let layout = comp(
    text("function".to_string()),
    nest(comp(
        text("name()".to_string()),
        text("{ body }".to_string()),
        true, false
    )),
    true, false
);

// Compile and render
let doc = compile(layout);
let output = render(doc, 2, 40);
println!("{}", output);

Core Concepts

Layout Constructors

Typeset provides several fundamental constructors for building layouts:

• text() - Text literals that form the visible content
• comp() - Compositions that can break into multiple lines
• line() - Forced line breaks
• nest() - Indentation for nested content
• pack() - Alignment to first element position
• grp() - Groups that break together
• seq() - Sequences where if one breaks, all break
• fix() - Fixed content that never breaks

Compilation Pipeline

The library uses a sophisticated multi-pass compiler that transforms layouts through several intermediate representations:

Layout → Edsl → Serial → LinearDoc → FixedDoc → RebuildDoc →
DenullDoc → FinalDoc → Doc → String

This pipeline ensures optimal layout decisions and efficient memory usage.

Architecture Overview

The typeset library is organized into several key modules:

• Constructors - Functions for building layout trees (text(), comp(), nest(), etc.)
• Compiler - Multi-pass compilation pipeline that optimizes layouts
• Types - Core data structures for layouts and intermediate representations
• Render - Final rendering engine that produces formatted strings
• Memory - Efficient bump allocation for zero-copy transformations

Error Handling

The library provides both safe and unsafe compilation modes:

• compile() - Fast compilation (may panic on stack overflow)
• compile_safe() - Safe compilation with error handling
• compile_safe_with_depth() - Safe compilation with custom recursion limits

Performance

Typeset is designed for high performance:

• Zero-copy transformations using bump allocation
• Optimal line breaking algorithms
• Efficient memory management with controlled recursion
• Support for large documents without stack overflow

Examples

Basic Usage

use typeset::*;

let layout = join_with_spaces(vec![
    text("Hello".to_string()),
    text("world!".to_string()),
]);

let result = format_layout(layout, 2, 80);
assert_eq!(result, "Hello world!");

Complex Formatting

use typeset::*;

let json_object = braces(
    join_with_commas(vec![
        comp(text("\"name\"".to_string()), text("\"John\"".to_string()), true, false),
        comp(text("\"age\"".to_string()), text("30".to_string()), true, false),
    ])
);

let result = format_layout(json_object, 2, 40);
// Output will adapt to width constraints automatically

With Parser (Optional)

For more concise syntax, use the optional parser crate:

use typeset_parser::layout;

let my_layout = layout! {
    nest ("function" + "name()")
    pack ("{ body }")
};

Rust Version Compatibility

This crate works on stable Rust (MSRV: 1.89.0). The test suite includes some components that use unstable features like box_patterns, but the core library and procedural macro work perfectly on stable Rust.

Version 2.0 Changes

Version 2.0 introduced a major architectural refactoring:

• Modular compiler passes - Each compilation phase is now separate and testable
• Improved error handling - Better stack overflow protection and error reporting
• Enhanced performance - More efficient memory management and faster compilation
• Better testing - Comprehensive test suite with integration and performance tests

The public API remains unchanged, ensuring seamless migration from v1.x.

Modules

render

Structs

TwoBufferBumpAllocator

Two-buffer bump allocator system for safe multi-pass compilation

Enums

CompilerError

Errors that can occur during compilation

Doc

Final document representation - output of the compiler

Layout

Layout AST - the input language for the compiler

Functions

blank_line

Creates a blank line (double line break).

braces

Wraps a layout in curly braces.

brackets

Wraps a layout in square brackets.

comma

Creates a comma character layout.

comp

Creates a composition that may break across lines based on width constraints.

compile

Compiles a layout into an optimized document (fast path)

compile_safe

Compiles a layout into an optimized document with error handling (safe path)

compile_safe_with_depth

Compiles a layout with custom recursion depth limit and error handling (configurable safe path)

fix

Wraps a layout to prevent it from breaking across lines.

fix_pad

Creates a fixed, padded composition between two layouts.

fix_unpad

Creates a fixed, unpadded composition between two layouts.

format_layout

Compiles and renders a layout to a formatted string in one step.

grp

Wraps a layout to control group breaking behavior.

join_with

Joins a collection of layouts with a custom separator.

join_with_commas

Joins a collection of layouts with comma separators.

join_with_lines

Joins a collection of layouts with line breaks.

join_with_spaces

Joins a collection of layouts with space separators.

line

Creates a forced line break between two layouts.

nest

Wraps a layout to add fixed-width indentation.

newline

Creates a simple line break.

null

Creates an empty layout node.

pack

Wraps a layout to add alignment-based indentation.

pad

Creates a padded composition between two layouts.

parens

Wraps a layout in parentheses.

render

Renders a compiled document to a formatted string

semicolon

Creates a semicolon character layout.

seq

Wraps a layout for sequential breaking behavior.

space

Creates a single space character layout.

text

Creates a text layout containing the given string.

text_str

Creates a text layout from a string slice.

unpad

Creates an unpadded composition between two layouts.