Plain Text Accounting Formats — Documentation

Comparison of plain text accounting (PTA) formats, each with a tree-sitter grammar for parsing and syntax highlighting.

The Formats

Format Style Details
Beancount Transaction with postings (debit/credit implicit) overview, beancount.github.io
Goluca Directed movements with -> arrows overview, accounts, datetime, parameters, tree-sitter-goluca
PTA Directed movements (goluca-compatible, simplified) overview, tree-sitter-pta
Coin Ledger-cli model in Go mkobetic/coin

The first three formats have tree-sitter grammars with ABNF, grammar.js, and parser demos on their detail pages. Coin is included as a comparison — a Go PTA tool with a different take on the ledger format.

Key Differences

Beancount uses the traditional ledger model: a transaction header followed by two or more posting lines, each naming an account and optionally an amount. Amounts balance implicitly across postings.

Goluca (go-luca) replaces implicit balancing with explicit directional movements. Each line names a from-account -> to-account pair with an amount, making the flow of money visible. Inspired by Pacioli's double-entry notation.

PTA shares goluca's directional style but with a simplified grammar. Both use the same arrow operators (->, //, >) and linked-movement syntax.

Same Transaction in Three Formats

Beancount:

2024-01-15 * "Tesco" "Weekly groceries"
  Expenses:Groceries   45.50 GBP
  Assets:Bank:Current

Goluca:

2024-01-15 * Tesco
  Assets:Bank:Current -> Expenses:Groceries "Weekly groceries" 45.50 GBP

PTA:

2024-01-15 * Tesco
  Assets:Bank:Current -> Expenses:Groceries Weekly groceries 45.50 GBP

Research

Topic Summary
Repeating Transactions How PTA formats handle recurring transactions; readability vs information density trade-offs

Grammar Build Pipeline

Each format is defined by a grammar.js file in its own tree-sitter repository. The pipeline from grammar source to usable Go parser runs through three stages:

graph TD
    subgraph "Stage 1: Grammar Source"
        A["grammar.js"] -->|tree-sitter generate| B["src/parser.c"]
        A -->|tree-sitter generate| C["src/grammar.json"]
        A -->|tree-sitter generate| D["src/node-types.json"]
    end

    subgraph "Stage 2: Go Integration (ts2go)"
        B -->|ts2go extract| E["grammar_blobs/name.bin
(gob + gzip)"]
        B -->|ts2go extract| F["grammars/name_gen.go"]
    end

    subgraph "Stage 3: Runtime & Docs"
        E -->|gotreesitter| G["Parse + Highlight"]
        C -->|tree-sitter2abnf| H["ABNF grammar text"]
        I["highlights.scm"] -->|query compiler| J["Syntax colouring"]
    end

Key files in each grammar repo (e.g. tree-sitter-goluca):

File Role
grammar.js Source of truth — the grammar definition
queries/highlights.scm Syntax highlighting capture rules
test/corpus/*.txt Parser validation test cases
tree-sitter.json Metadata (name, file extensions, bindings)
src/parser.c Generated — LR parse tables (committed for downstream)
src/grammar.json Generated — grammar metadata export

All src/ files are regenerated by tree-sitter generate but committed so that downstream tools (ts2go, CI) can consume them without running the generator.

ABNF Grammar Summaries

Each format has a formal grammar defined in ABNF, generated from the tree-sitter grammar.json by tree-sitter2abnf. See the individual format pages for full definitions.

See ABNF Standards and Extensions for details on the ABNF variants and tree-sitter extensions used in these grammars.

ABNF highlighting in the docs uses a tree-sitter grammar from gotreesitter.

For background on ABNF in accounting contexts, see ABNF and Plain Text Accounting on bytestone.uk.

Repositories

Repo Purpose
plain-text-accounting-formats Go library and CLI for parsing/highlighting/converting PTA formats
gotreesitter Pure-Go tree-sitter runtime (206 embedded grammars)
tree-sitter-goluca Tree-sitter grammar for the Goluca format
tree-sitter-pta Tree-sitter grammar for the PTA format
tree-sitter-beancount Tree-sitter grammar for Beancount (upstream: polarmutex)
tree-sitter2abnf Converts grammar.json to ABNF and back
pta2svg Renders Goluca/PTA movements as SVG flow diagrams
Documentation https://h3-pta-formats.statichost.page/
Source (Codeberg) https://codeberg.org/hum3/plain-text-accounting-formats
Mirror (GitHub) https://github.com/drummonds/plain-text-accounting-formats