PtcRunner.Lisp.Eval (PtcRunner v0.14.0)

Copy Markdown View Source

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.

Expected evaluation exits use one context-bearing protocol owned by Eval.Outcome: success, recoverable error, or return/fail/recur control. Host callbacks that cannot return an outcome use the private Eval.Abort carrier. Eval.HostContext installs the active evaluator context around those callbacks so validation and runtime helpers can abort without introducing parallel exception transports.

Eval.Context owns the normalized cumulative Eval.Effects. Eval.Capture is the single callback capture stack; it records the authoritative effect delta and replaces only an outcome context's effects during normalization. Eval.HostContext is the one adapter for plain host callbacks. Callable dispatch remains responsible for restoring lexical, namespace, and prelude-authority state before an outcome crosses a boundary.

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.Outcome / Eval.Abort - Expected outcomes and the private callback carrier
  • Eval.HostContext - Active evaluator context for host callbacks
  • Eval.Effects / Eval.Capture - Effect algebra and callback capture
  • Eval.Parallel - pmap/pcalls evaluation and worker-result semantics
  • Eval.ParallelRunner - Parallel scheduling and process lifecycle
  • Eval.Helpers - Type errors and utilities

Summary

Types

env()
outcome()
runtime_error()
tool_executor()
value()

Functions

eval(ast, ctx, memory, env, tool_executor, turn_history \\ [], opts \\ [])
eval_with_context(ast, ctx, memory, env, tool_executor, turn_history \\ [], opts \\ [])

Types

env()

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

outcome()

@type outcome() ::
  {:ok, term(), PtcRunner.Lisp.Eval.Context.t()}
  | {:error, term(), PtcRunner.Lisp.Eval.Context.t()}
  | {:control, :return | :fail | :recur, term(),
     PtcRunner.Lisp.Eval.Context.t()}

runtime_error()

@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()}
  | {:transitive_call_unauthorized, String.t(), String.t(), [String.t()]}

tool_executor()

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

value()

@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()}

Functions

eval(ast, ctx, memory, env, tool_executor, turn_history \\ [], opts \\ [])

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

eval_with_context(ast, ctx, memory, env, tool_executor, turn_history \\ [], opts \\ [])

@spec eval_with_context(
  PtcRunner.Lisp.CoreAST.t(),
  map(),
  map(),
  env(),
  tool_executor(),
  list(),
  keyword()
) :: outcome()