# `PtcRunner.Lisp.Eval`
[🔗](https://github.com/andreasronge/ptc_runner/blob/main/lib/ptc_runner/lisp/eval.ex#L1)

Evaluates CoreAST into values.

The eval layer recursively interprets CoreAST nodes, resolving variables
from lexical environments, applying builtins and user functions, and
handling control flow.

## Module Structure

This module delegates to specialized submodules:
- `Eval.Context` - Evaluation context struct
- `Eval.Patterns` - Pattern matching for let bindings
- `Eval.Apply` - Function application dispatch
- `Eval.Helpers` - Type errors and utilities

# `env`

```elixir
@type env() :: %{required(atom()) => term()}
```

# `runtime_error`

```elixir
@type runtime_error() ::
  {:unbound_var, atom()}
  | {:not_callable, term()}
  | {:arity_mismatch, expected :: integer(), got :: integer()}
  | {:type_error, expected :: String.t(), got :: term()}
  | {:tool_error, tool_name :: String.t(), reason :: term()}
  | {:invalid_keyword_call, atom(), [term()]}
  | {:arity_error, String.t()}
  | {:destructure_error, String.t()}
```

# `tool_executor`

```elixir
@type tool_executor() ::
  (String.t(), map() -> term()) | (String.t(), map(), map() | nil -> term())
```

# `value`

```elixir
@type value() ::
  nil
  | boolean()
  | number()
  | String.t()
  | atom()
  | list()
  | map()
  | MapSet.t()
  | function()
  | {:closure, [PtcRunner.Lisp.CoreAST.pattern()], PtcRunner.Lisp.CoreAST.t(),
     env(), list(), map()}
```

# `eval`

```elixir
@spec eval(
  PtcRunner.Lisp.CoreAST.t(),
  map(),
  map(),
  env(),
  tool_executor(),
  list(),
  keyword()
) ::
  {:ok, value(), map()} | {:error, runtime_error()}
```

# `eval_with_context`

```elixir
@spec eval_with_context(
  PtcRunner.Lisp.CoreAST.t(),
  map(),
  map(),
  env(),
  tool_executor(),
  list(),
  keyword()
) :: {:ok, value(), PtcRunner.Lisp.Eval.Context.t()} | {:error, runtime_error()}
```

---

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