# `Beancount.Parser`
[🔗](https://github.com/thanos/beancount_ex/blob/v0.6.0/lib/beancount/parser.ex#L1)

Parse Beancount `.bean` text into typed directive structs.

The parser covers the full Beancount grammar: transactions with cost and
price annotations, balance assertions with tolerance, metadata, comments,
tags, links, and all standard directives including `pad`, `include`,
`option`, `query`, `plugin`, `pushtag`, and `poptag`.

Parse failures return `{:error, %Beancount.Parser.Error{}}` with line and
column information.

# `parse`

```elixir
@spec parse([Beancount.directive()] | binary()) ::
  {:ok, [Beancount.directive()]} | {:error, Beancount.Parser.Error.t()}
```

Parse a directive list or `.bean` text.

Lists pass through unchanged; binaries are parsed.

## Examples

    iex> {:ok, [open]} = Beancount.Parser.parse([Beancount.open(~D[2026-01-01], "Assets:Bank", ["USD"])])
    iex> open.account
    "Assets:Bank"

    iex> {:ok, [open]} = Beancount.Parser.parse("2026-01-01 open Assets:Bank USD\n")
    iex> open.account
    "Assets:Bank"

# `parse!`

```elixir
@spec parse!(binary()) :: [Beancount.directive()]
```

Parse `.bean` text, raising `Beancount.Parser.Error` on failure.

## Examples

    iex> Beancount.Parser.parse!("2026-01-01 open Assets:Bank USD\n")
    ...> |> hd()
    ...> |> Map.get(:account)
    "Assets:Bank"

# `parse_file`

```elixir
@spec parse_file(Path.t()) :: {:ok, [Beancount.directive()]} | {:error, term()}
```

Read and parse a `.bean` file from disk.

## Examples

    path = Path.join(System.tmp_dir!(), "parser_example.bean")
    File.write!(path, "2026-01-01 commodity USD\n")

    {:ok, [%Beancount.Directives.Commodity{currency: "USD"}]} =
      Beancount.Parser.parse_file(path)

# `parse_text`

```elixir
@spec parse_text(binary()) ::
  {:ok, [Beancount.directive()]} | {:error, Beancount.Parser.Error.t()}
```

Parse `.bean` text into a directive list.

## Examples

    iex> {:ok, [open | _]} = Beancount.Parser.parse_text("2026-01-01 open Assets:Bank USD\n")
    iex> open.account
    "Assets:Bank"

---

*Consult [api-reference.md](api-reference.md) for complete listing*