Technical documentation for the .rpt format and the rpt-rs library.
The format documents are programming-language-agnostic: they describe the on-disk .rpt structure itself. Read them in
order — each builds on the previous one.
- Format overview — the big picture: what a
.rptfile is and the full decode pipeline from bytes to a typed report. - The container — the CFB/OLE compound file and the streams inside it.
- Stream decoding — the stream header, the cipher, decompression, and how raw bytes become a flat sequence of records.
- The record tree — how records nest, the per-record masking, and the lossless record substrate.
- The semantic model — how the record tree is projected into the typed report model.
- Saved data — how a report's cached rows (saved with data) are laid out and decoded.
- Block catalog — every record (block) type the library decodes: what it means, its byte layout, and the blocks that are recognized but not yet decoded.
- Support matrix — which format features and record types are supported.
- Endianness — the format mixes big- and little-endian; this is the map.
- The codebase — the crates and modules, what each contains, and why the boundaries are where they are.
- Rendering — the render pipeline (data → layout → Page IR → backends), the public API for driving
a render, the coordinate model, locale/format resolution, and the
rpt-renderCLI. - Render examples — copy-paste recipes for driving the renderer: saved data, live DB, a
custom
RowSource, and WASM. - Usage — the CLI tools and the library API, with examples.
The crystal-formula crate — the Crystal/Basic formula language (lexer, parser, AST, type system, bytecode VM) —
is documented in formula-engine/:
- Architecture & VM — the pipeline, the value model, variables/scopes, references, the per-record cache, and error handling.
- Language reference — both dialects (Crystal & Basic): lexis, operators, expressions, statement bodies, with an EBNF sketch.
- Builtin functions — the builtin library by family, with signatures and semantics.
- Validation — the semantic diagnostics pass behind the Crystal LSP.