@callback check(binary()) :: {:ok, Beancount.Result.t()} | {:error, Beancount.Result.t()}

Check a .bean document, returning a normalized Beancount.Result.

Examples

Requires bean-check on PATH, or use Beancount.Engine.Elixir.check/1:

text = "2026-01-01 open Assets:Bank USD\n"

if Beancount.Checker.available?() do
  {:ok, %Beancount.Result{}} = Beancount.Engine.CLI.check(text)
end

@callback check_file(Path.t()) ::
  {:ok, Beancount.Result.t()} | {:error, Beancount.Result.t()}

Check a .bean file on disk, returning a normalized Beancount.Result.

Engines that shell out to CLI tools should preserve the file path so include directives resolve relative to the ledger file.

Examples

path = Path.join(System.tmp_dir!(), "engine_check.bean")
File.write!(path, "2026-01-01 open Assets:Bank USD\n")

if Beancount.Checker.available?() do
  {:ok, _} = Beancount.Engine.CLI.check_file(path)
end

@callback query(binary(), binary()) ::
  {:ok, Beancount.Query.Result.t()} | {:error, Beancount.Result.t()}

Run a BQL query against a .bean document.

The first argument is the ledger text, the second is a Beancount Query Language (BQL) string. Returns a neutral, engine-independent Beancount.Query.Result on success, or a Beancount.Result describing the failure otherwise.

Examples

text = """
2026-01-01 open Assets:Bank USD
2026-01-01 open Income:Salary USD
2026-01-01 open Equity:Opening USD

2026-01-31 * "Employer" "Salary"
  Assets:Bank     100 USD
  Income:Salary  -100 USD
"""

{:ok, %Beancount.Query.Result{columns: cols}} =
  Beancount.Engine.Elixir.query(text, "SELECT account, sum(position) AS balance GROUP BY account ORDER BY account")

cols
# => ["account", "balance"]

@callback render(term()) :: binary()

Render a directive stream into .bean text.

Examples

iex> Beancount.Engine.CLI.render([Beancount.open(~D[2026-01-01], "Assets:Bank", ["USD"])])
"2026-01-01 open Assets:Bank USD\n"