Crate doppio 

doppio – a compiler and query library for the Ledger plain-text accounting format.

.dop binary format

The dop compile command serialises an elaborated journal to a .dop file. The file begins with an 8-byte header followed by the payload:

Offset  Length  Content
0       4       Magic: b"DOP\0"
4       2       Format version: u16 LE (currently 3)
6       1       Compression: u8  (0 = none, 1 = deflate)
7       1       Reserved (write 0, ignore on read)
8       N       Payload (protobuf, optionally deflate-compressed per byte 6)

Use write_dop / read_dop for the full header + (optional) compression + protobuf round-trip.

Pipeline

Source text is processed through four stages:

source text
  → [parser]      ast::Journal        (PEG grammar + Pratt expressions)
  → [resolution]  resolution::HIR     (dates, aliases, metadata)
  → [elaboration] elaboration::Journal (evaluation, balancing)
  → serialisation                     (protobuf + optional deflate → .dop)

The top-level entry point is compile, which runs all three in-memory stages and returns the elaborated Journal. For CLI usage see the dop binary in src/main.rs.

Modules

• frontend – the Frontend trait for pluggable file-format support.
• grammars – grammar implementations (grammars::ledger for ledger-cli, grammars::hledger for hledger, grammars::beancount for Beancount).
• resolution – alias resolution, date normalisation, metadata extraction.
• elaboration – prost-generated Protocol Buffers types (Journal, Transaction, Posting, Amount, Decimal); this is the canonical read-side public surface and the wire shape of .dop bodies.

Serialising journals as source text

Use Frontend::write_journal to serialise a resolved resolution::HIR back to source text in the frontend’s native format:

use doppio::frontend::Frontend as _;
use doppio::LedgerFrontend;
use std::path::Path;

let hir = LedgerFrontend
    .parse(
        "2024-01-15 Groceries\n    Expenses:Food  $50\n    Assets:Checking\n",
        Path::new(""),
        &|_| Ok(String::new()),
    )
    .unwrap();
let mut out = Vec::new();
LedgerFrontend.write_journal(&hir, &mut out).unwrap();
let text = String::from_utf8(out).unwrap();
assert!(text.contains("Groceries"));

The same works with HledgerFrontend and BeancountFrontend; each emits the resolved journal in its own native syntax. Cross-frontend transcoding (parse one format, write another) works on a best-effort basis: format-specific constructs that have no equivalent in the target format are emitted as ; [<source-format>] ... comment lines so they remain visible.

Deprecated: write_ledger

The older write_ledger API accepts an iterator of resolution::Transaction values and writes ledger-cli text. It is deprecated in favour of LedgerFrontend.write_journal(hir, writer), which also handles historical prices and balance assertions. write_ledger will be removed in v3.0.

Re-exports

pub use elaboration::Journal;

pub use frontend::Frontend;

pub use grammars::beancount::BeancountFrontend;

pub use grammars::hledger::HledgerFrontend;

pub use grammars::ledger::LedgerFrontend;

Modules

ast

Abstract Syntax Tree (AST) for the Ledger file format.

elaboration

Prost-generated Protocol Buffers types – canonical wire shape of .dop bodies.

frontend

The Frontend trait – the extension point for pluggable file-format support.

grammars

Grammar implementations for each supported file format.

resolution

Resolution stage: convert an ast::Journal into the Higher-level Intermediate Representation (HIR).

Structs

Amount

A multi-commodity amount: a map from commodity symbol to a Decimal value.

Enums

Compression

Compression algorithm used in the .dop payload.

ElaborationError

Errors that can occur during the elaboration stage.

EvaluationError

Error produced when evaluating a value expression (e.g., an amount or balance assertion expression) fails.

Functions

compile

Compile Ledger source text into a fully elaborated Journal.

elaborate

Run the elaboration stage on a resolved resolution::HIR under the given resolution::ElaborationConfig, producing a fully-balanced elaboration::Journal.

eval_transaction

Evaluate a single resolution::Transaction through the elaboration stage.

file_opener

Load and concatenate all files matching a glob pattern.

frontend_for_extension

Select a frontend by file extension.

read_dop

Deserialise a .dop file from reader into a Journal.

write_dop

Serialise journal to writer as a complete .dop file (8-byte header + optional deflate + protobuf body).

write_journal

Convenience wrapper: serialise a resolved resolution::HIR to writer using the given frontend’s native syntax.

write_ledgerDeprecated

Write a sequence of resolution::Transaction values to writer in canonical Ledger source text format.