xforme
A blazing-fast Rust engine that streams your data through ordinary Excel templates to mass-produce pixel-perfect spreadsheets and PDFs, formatting and formulas intact.
xforme is the Rust migration of templateIt — the 2009 Java project by the same author — and its canonical Sales Receipt example.
The idea: you describe a document once — as an ordinary Excel workbook or a declarative Rust template — then stream a data file through it to render both a spreadsheet and a PDF. The original templateIt used Apache POI for Excel output and iText for PDF.
This port offers two modes:
- Declarative mode — the template is defined in Rust code. Self-contained,
no external files, PDF drawn directly with
printpdf. - Excel-template mode — the faithful templateIt workflow: the template is a
real
.xlsxworkbook designed in Excel (styles, number formats, merges and formulas). The engine fills a new tab with rendered data and removes the template tab, exactly like the original.
| Original (Java, 2009) | This port (Rust) |
|---|---|
| Apache POI (read/write Excel) | umya-spreadsheet (Excel-template mode) + rust_xlsxwriter (declarative mode) |
| iText (PDF) | LibreOffice headless convert (Excel-template mode) + printpdf (declarative mode) |
| Excel template workbook | a real .xlsx (Excel-template mode) or a declarative Template value (declarative mode) |
Pipeline
data file ──[data::parse]──▶ Sheet ─┐
├─[engine::process]──▶ Document ──┬─[render_xlsx]──▶ .xlsx
Template ────────────────────────────┘ └─[render_pdf]───▶ .pdf
data— parses the original tab-delimited stream format (#sheet… records …##end).template— the declarative model: output columns, the field names for each record label, and a band of output rows to emit per label.expr— a small arithmetic evaluator (+ - * / (), identifiers) so the template can express line totals (qty * price) and a grand total (subtotal + subtotal * taxrate) without hard-coding them.engine— walks the records, resolves${...}placeholders and expressions against each record's fields plus running accumulators (e.g.subtotal), and produces a fully-resolvedDocument.render— two backends (xlsx,pdf) that consume theDocumentand know nothing about templates or the data format.salesreceipt— the bundled example template, built on the generic engine.
Run it
The xforme binary is generic — point it at any .xlsx template and a data
file:
# e.g. with the bundled sample template + data:
It writes PREFIX.xlsx (template tab removed, formulas live) and, unless
--no-pdf, PREFIX.pdf via a headless LibreOffice when available. PREFIX
defaults to the data file's stem.
The demo example is self-contained — the Sales Receipt template and data are
embedded at compile time with include_bytes! / include_str!, so it needs no
external files (this is the pattern to copy for shipping a fixed report inside
your own binary, see examples/sales_receipt.rs):
The embedded template is the committed asset
templates/sales_receipt_template.xlsx — edit it in Excel to change the design,
or edit src/demo_template.rs and regenerate it:
Excel-template convention
The template .xlsx is designed by hand in Excel/LibreOffice. The engine reads
it (preserving all styling) via src/xlsx_template.rs:
- Column A of each row is a control tag (hidden in the output):
header/footer— emitted once, fields from the matching data record;- any other tag (
row1,row2, …) — a detail row; the contiguous run of detail rows is the detail band, emitted once per detail data record, matched by tag (so alternatingrow1/row2styles interleave in data order); - empty — a static row.
- Placeholders
${n}inject the n-th data field;${firstrow}/${lastrow}give the detail band's row range (for aggregate formulas);${row}is the current row. - Formulas are written natively in Excel. When a template row is replicated
at a new output row, the engine row-shifts its relative references, so
=B7*D7becomes=B12*D12and=SUM(E${firstrow}:E${lastrow})resolves to the actual rendered range. Absolute references ($D$7) are left untouched.
templates/sales_receipt_template.xlsx (built by the make_sample_template
binary) is a worked example — edit it in Excel to change the receipt's design
without touching any Rust.
Data format
Tab-delimited, line-oriented — identical to the original example:
#sheet SalesReceipt Sales Receipt
header 1/5/2009 22215 Jose Maria Fernandez 1010 Broadway, New York, NY 10010
row1 1 1 Introduction to Algebra 53.0
row2 2 1 Introduction to Algebra Solutions Manual 14.0
footer .0525
##end
row1/row2 are alternating (banded) line-item styles; footer's single
field is the tax rate. The engine accumulates qty * price into subtotal,
then the footer computes tax and total from it.
Library API
xforme ships as both a binary and a library (xforme = { path = "..." }).
The Excel-template engine accepts a template either by file path or as an
in-memory byte array (anything Into<TemplateSource> — &Path, &[u8],
&Vec<u8>), and can write the report to a file or hand it back as bytes:
use Path;
use ;
let sheet = &parse?;
// 1. Template from a file on disk -> write report to a file.
render_to_file?;
// 2. Template from a byte buffer (network/DB/include_bytes!) -> report as bytes.
let template_bytes: & = /* ... */;
let report_xlsx: = render_to_bytes?;
// 3. Or get the populated workbook to post-process before saving.
let workbook = render?;
# Ok::
| Function | Template in | Report out |
|---|---|---|
render |
path or bytes | umya_spreadsheet::Workbook |
render_to_file |
path or bytes | .xlsx file |
render_to_bytes |
path or bytes | Vec<u8> |
The declarative engine is library-only too:
engine::process(&template, sheet) -> Document, then
render::render_xlsx(&doc, path) / render::render_pdf(&doc, path).
PDF for the Excel-template path is left to the caller (the binary shells out to LibreOffice); the library returns the spreadsheet so you can convert it however you like.
Extending it
The declarative engine is generic — the Sales Receipt is just one Template. To
make a new document type, define a Template (columns, per-label field names,
and bands of CellSpecs using Literal / Text / Expr content) and feed it a
matching data stream. No engine changes required. For the Excel-template engine,
just design a new .xlsx — no Rust changes at all.