ExLedger.Parser.BalanceAssertions (ex_ledger v0.6.0)

Validates balance assertions after transactions are parsed.

Balance assertions use the syntax AMOUNT = ASSERTION_AMOUNT to verify that the running balance of an account equals a specific value after the posting is applied.

Example

2026/09/30 * Q3 Balance Check
    Assets:Bank:Checking        0 = 45000.00 CHF
    Assets:Cash                 0 = 932.20 CHF

This asserts that after the zero-amount posting, the running balance of Assets:Bank:Checking equals 45000.00 CHF.

Summary

Types

assertion_failure()

validation_result()

Functions

format_failures(failures)

Formats assertion failures as a human-readable error message.

validate_assertions(transactions, opts \\ [])

Validates all balance assertions in a list of transactions.

validate_transaction_assertions(transaction, balances, failures)

Validates assertions for a single transaction, updating running balances.

Types

assertion_failure()

@type assertion_failure() :: %{
  account: String.t(),
  expected: ExLedger.Parser.Core.amount(),
  actual: ExLedger.Parser.Core.amount(),
  transaction_date: Date.t() | nil,
  transaction_payee: String.t() | nil,
  source_file: String.t() | nil,
  source_line: non_neg_integer() | nil
}

validation_result()

@type validation_result() :: :ok | {:error, [assertion_failure()]}

Functions

format_failures(failures)

@spec format_failures([assertion_failure()]) :: String.t()

Formats assertion failures as a human-readable error message.

Example

iex> BalanceAssertions.format_failures([failure])
"Balance assertion failed for account 'Assets:Cash'\n  Expected: 100.00 CHF\n  ..."

validate_assertions(transactions, opts \\ [])

@spec validate_assertions(
  [ExLedger.Parser.Core.transaction()],
  keyword()
) :: validation_result()

Validates all balance assertions in a list of transactions.

Computes running balances per account/currency and checks assertions. Returns :ok if all assertions pass, or {:error, failures} with all failed assertions.

Options

:skip_assertions - if true, skips validation and returns :ok

Examples

iex> BalanceAssertions.validate_assertions(transactions)
:ok

iex> BalanceAssertions.validate_assertions(transactions)
{:error, [%{account: "Assets:Cash", expected: ..., actual: ...}]}

validate_transaction_assertions(transaction, balances, failures)

@spec validate_transaction_assertions(
  ExLedger.Parser.Core.transaction(),
  %{required(String.t()) => %{required(String.t()) => Decimal.t()}},
  [assertion_failure()]
) ::
  {%{required(String.t()) => %{required(String.t()) => Decimal.t()}},
   [assertion_failure()]}

Validates assertions for a single transaction, updating running balances.

Returns a tuple of {updated_balances, updated_failures}.