Module ast 

Typed AST wrappers over the lossless CST.

Phase 3 of #1262. The CST (phase 1-2) preserves every byte of the source as an untyped tree of SyntaxKind nodes and tokens. This module adds a thin typed layer on top: newtype wrappers around SyntaxNode / SyntaxToken with kind()-gated constructors (cast) and structural accessors (date(), account(), amount(), etc.).

Two traits anchor the surface:

• AstNode: typed wrapper around a SyntaxNode. Each wrapper pins its expected SyntaxKind via can_cast and offers accessors that walk direct children.
• AstToken: typed wrapper around a SyntaxToken. Provides text() for the raw bytes; specific token wrappers (Date, Account, Number, …) can layer parsing on top.

The wrappers are zero-cost — they store a SyntaxNode / SyntaxToken by value and forward to it. Cloning is cheap (rowan’s nodes/tokens are Arc-backed). All accessors return Option<_> because the CST is lossless: a malformed input still produces a tree, just one with missing children.

Round-trip

Every wrapper exposes syntax() returning the underlying SyntaxNode/SyntaxToken, whose text() reproduces the original bytes exactly. Typed-AST consumers that want to modify the source can therefore navigate via accessors and splice via raw text ranges.

Structs

Account

ACCOUNT token (e.g., Assets:Cash).

Amount

Units amount: [sign] (NUMBER | PAREN_EXPR) ([WS] op [WS] [sign] (NUMBER | PAREN_EXPR))* [WS CURRENCY], or a bare CURRENCY. Phase 2.4 extension supports arithmetic.

BalanceDirective

DATE balance ACCOUNT AMOUNT_TOKENS. Amount stays flat (phase 2.2c scopes AMOUNT wrapping to POSTING only); walk number() and currency() to read it.

BoolFalse

BOOL_FALSE token literal.

BoolTrue

BOOL_TRUE token literal.

CloseDirective

DATE close ACCOUNT.

CommodityDirective

DATE commodity CURRENCY.

CostSpec

Bracketed cost annotation: {...} (per-unit), {#...} (per-unit + total), or {{...}} (total-only). Contents stay flat (phase 2.2c); accessors scan the children.

CurrencyName

CURRENCY token (e.g., USD).

CustomDirective

DATE custom "TYPE" values.... Heterogeneous value list stays flat (phase 2.3); walk the raw token sequence via syntax().children_with_tokens().

Date

DATE token (e.g., 2024-01-15).

DocumentDirective

DATE document ACCOUNT "PATH".

ErrorNode

Wrapper for unrecognized / malformed top-level content (PR 2.4 ERROR_NODE). Typed-AST consumers can use this to surface error regions to users (e.g., LSP diagnostics).

EventDirective

DATE event "TYPE" "VALUE".

IncludeDirective

include "PATH".

Link

LINK token (e.g., ^expense-123).

MetaEntry

Metadata sub-line: WS META_KEY ... (NEWLINE | EOF). Key is the META_KEY token; value is the remaining flat content tokens. Use key() and value_*() accessors.

MetaKey

META_KEY token (e.g., note:). Note the trailing colon is part of the token; use text_without_colon() to strip it.

NoteDirective

DATE note ACCOUNT "TEXT".

Number

NUMBER token (e.g., 100.00).

OpenDirective

DATE open ACCOUNT [CURRENCY[,CURRENCY]*] ["BOOKING"].

OptionDirective

option "KEY" "VALUE".

PadDirective

DATE pad ACCOUNT_TARGET ACCOUNT_SOURCE.

PluginDirective

plugin "MODULE" ["CONFIG"].

PopmetaDirective

popmeta KEY:.

PoptagDirective

poptag #TAG.

Posting

WS [(FLAG | STAR | PENDING_KW | HASH | single-char CURRENCY) WS] ACCOUNT [AMOUNT] [COST_SPEC] [PRICE_ANNOTATION].

PostingFlag

Typed wrapper for a posting-line flag token. Same as TransactionFlag minus the TXN_KW variant (postings can’t carry the txn keyword). Use Self::classify for exhaustive match ergonomics.

PriceAnnotation

Price annotation: AT [WS AMOUNT] (per-unit) or AT_AT [WS AMOUNT] (total).

PriceDirective

DATE price CURRENCY NUMBER CURRENCY.

PushmetaDirective

pushmeta KEY: VALUE.

PushtagDirective

pushtag #TAG.

QueryDirective

DATE query "NAME" "QUERY".

Sign

Typed wrapper for an amount sign token (PLUS or MINUS).

SourceFile

Root of a parsed Beancount file. SourceFile::parse(src) is the typed-AST entry point — it wraps parse_structured.

StringLit

STRING literal (e.g., "Coffee"). text() includes the surrounding quotes; use text_unquoted() for the content.

SyntaxText

Re-export of rowan’s SyntaxText — a rope view over a SyntaxNode’s text without allocation. Returned by ErrorNode::text so consumers don’t need a direct rowan dependency.

Tag

TAG token (e.g., #trip).

Transaction

DATE FLAG ["PAYEE"] "NARRATION" #TAG... ^LINK... followed by indented POSTING lines and META_ENTRY sub-lines.

TransactionFlag

Typed wrapper for the transaction-header flag token.

Enums

Directive

Sum type over every recognized top-level directive wrapper.

PostingFlagKind

Exhaustive classification of a PostingFlag token. Same as TransactionFlagKind minus Txn (postings cannot carry the txn keyword).

TransactionFlagKind

Exhaustive classification of a TransactionFlag token.

Traits

AstNode

Typed wrapper around a SyntaxNode of a specific SyntaxKind.

AstToken

Typed wrapper around a SyntaxToken of a specific SyntaxKind. Like AstNode but for leaf tokens.