Lines
86.48 %
Functions
27.27 %
Branches
100 %
//! `(handler-case)` — pattern-match recovery from a raised condition
//! (Tier 3.3, ADR-0026).
//!
//! ```lisp
//! (handler-case <body>
//! (no-such-account (e) (log (error-message e)))
//! (commodity-mismatch (e) (recover))
//! (t (e) (error-code e))) ; t = catch-all (optional, last)
//! ```
//! Lowering (single-value `Catch::One`, the same shape as the Tier 3.2
//! boundary wrapper):
//! ```text
//! block $outer (result T)
//! block $handler (result (ref null $nomi_condition))
//! try_table (result T) (catch $nomi_error → $handler)
//! <body → T>
//! end
//! br $outer ; normal completion carries T out
//! end ; catch edge: condition ref on stack
//! local.set $cond
//! <flat dispatch> ; each clause an independent `if` that
//! ; `br $outer`s on match; t = uncond.;
//! ; no match → re-throw same condition
//! Result type `T` is discovered at emit time and unified across the body
//! and every reachable clause body (mirrors BLOCK's emit-time discovery);
//! a diverging arm contributes no type. Re-raise on no-match re-`throw`s a
//! fresh `$nomi_error` carrying the SAME condition struct — nomiscript
//! conditions have no observable identity, so this is equivalent to
//! re-raising the original and avoids needing an exnref.
use wasm_encoder::{BlockType, Catch, HeapType, RefType, ValType};
use crate::ast::{EntityKind, Expr, WasmType};
use crate::compiler::context::CompileContext;
use crate::compiler::emit::FunctionEmitter;
use crate::compiler::expr::{eval_value, serialize_stack_to_output};
use crate::error::{Error, Result};
use crate::runtime::{Symbol, SymbolKind, SymbolTable};
use super::arms::{Arm, OnConflict, arm_of_form, compile_arm, finish_arm, reconcile_arms};
use super::block_exits::form_diverges;
/// The body and every reachable clause must agree once literal / `nil` arms
/// reconcile; a genuine conflict stays a compile error.
const ON_CONFLICT: OnConflict = OnConflict::Reject("HANDLER-CASE");
const HANDLER_CASE: &str = "handler-case";
const CATCH_ALL: &str = "T";
/// One parsed clause: `code` is `None` for the `t` catch-all, else the
/// (reader-upcased) condition-code symbol; `var` is the condition binding;
/// `body` is the clause's body forms.
struct Clause<'a> {
code: Option<&'a str>,
var: &'a str,
body: &'a [Expr],
}
pub(super) fn eval_handler_case(symbols: &mut SymbolTable, args: &[Expr]) -> Result<Expr> {
let (body, clauses) = parse(args)?;
// If the body can't throw and folds to a constant, that's the value.
let body_val = eval_value(symbols, body)?;
let body_diverges = form_diverges(&mut symbols.clone(), body)?;
if !body_val.is_wasm_runtime() && !body_diverges {
return Ok(body_val);
// Otherwise the form has a runtime result. Its type must match what
// `compile_handler_case_for_stack` emits: the unified type of the body
// (when it can fall through) plus every reachable clause body — NOT just
// the body, which is wrong when the body always throws (e.g. an `(error)`
// body whose value comes from a clause). Callers that materialise a
// runtime value (let/defvar binding, lambda arg) trust this type to size
// the local, so a body-only type yields an invalid module.
let mut arms: Vec<Arm> = Vec::new();
if !body_diverges {
arms.push(arm_of_form(body, &body_val)?);
for clause in &clauses {
let mut clause_syms = symbols.clone();
clause_syms.define(Symbol::new(clause.var, SymbolKind::Variable).with_value(
Expr::WasmLocal(0, WasmType::EntityRef(EntityKind::Condition)),
));
let (cval, cdiverges) = eval_clause_value(&mut clause_syms, clause)?;
if !cdiverges {
let value_form = clause.body.last().unwrap_or(&EMPTY_CLAUSE_VALUE);
arms.push(arm_of_form(value_form, &cval)?);
Ok(Expr::WasmRuntime(reconcile_arms(&arms, ON_CONFLICT)?))
/// Eval-time value + divergence of a clause body, mirroring the
/// compile-side `compile_clause_body` walk (last form is the value; an
/// earlier diverging form makes the rest dead).
fn eval_clause_value(symbols: &mut SymbolTable, clause: &Clause<'_>) -> Result<(Expr, bool)> {
if clause.body.is_empty() {
return Ok((Expr::Nil, false));
let last = clause.body.len() - 1;
for (idx, form) in clause.body.iter().enumerate() {
if idx == last {
let diverges = form_diverges(&mut symbols.clone(), form)?;
return Ok((eval_value(symbols, form)?, diverges));
if form_diverges(&mut symbols.clone(), form)? {
eval_value(symbols, form)?;
return Ok((Expr::Nil, true));
Ok((Expr::Nil, false))
pub(super) fn compile_handler_case(
ctx: &mut CompileContext,
emit: &mut FunctionEmitter,
symbols: &mut SymbolTable,
args: &[Expr],
) -> Result<()> {
let ty = compile_handler_case_for_stack(ctx, emit, symbols, args)?;
serialize_stack_to_output(ctx, emit, ty)
pub(super) fn compile_handler_case_for_effect(
compile_handler_case_for_stack(ctx, emit, symbols, args)?;
emit.drop_value();
Ok(())
pub(super) fn compile_handler_case_for_stack(
) -> Result<WasmType> {
// Stash local for the caught condition, allocated before the body so the
// body's own locals stack above it (matches the boundary wrapper).
let cond_local = ctx.alloc_local(WasmType::AnyRef)?;
// --- Phase 1: compile every arm into its own scratch, collect types. ---
// Each scratch is seeded at the depth it will actually be spliced into,
// so relative `br` targets of a `(return-from)` / `(go)` inside the arm
// stay correct after splicing:
// - body: inside $outer/$handler/try_table → parent + 3.
// - a non-`t` clause: inside $outer + its own guard `if` → parent + 2.
// - the `t` clause: inside $outer only (no guard `if`) → parent + 1.
let parent_depth = emit.block_depth();
let body_depth = parent_depth + 3;
let mut body_scratch = FunctionEmitter::new_seeded(body_depth);
let body_arm = compile_arm(ctx, &mut body_scratch, symbols, body)?;
let body_diverges = body_arm.is_none();
let mut clause_arms: Vec<ClauseArm<'_>> = Vec::with_capacity(clauses.len());
let clause_depth = if clause.code.is_some() {
parent_depth + 2
} else {
parent_depth + 1
};
let mut scratch = FunctionEmitter::new_seeded(clause_depth);
Expr::WasmLocal(cond_local, WasmType::EntityRef(EntityKind::Condition)),
let (value_form, arm) = compile_clause_body(ctx, &mut scratch, &mut clause_syms, clause)?;
clause_arms.push(ClauseArm {
scratch,
symbols: clause_syms,
value_form,
arm,
});
let arms: Vec<Arm> = body_arm
.into_iter()
.chain(clause_arms.iter().filter_map(|clause| clause.arm))
.collect();
let result_ty = reconcile_arms(&arms, ON_CONFLICT)?;
if let Some(arm) = body_arm {
finish_arm(ctx, &mut body_scratch, symbols, body, arm, result_ty)?;
let mut clause_scratches: Vec<(FunctionEmitter, bool)> = Vec::with_capacity(clauses.len());
for mut clause in clause_arms {
if let Some(arm) = clause.arm {
finish_arm(
ctx,
&mut clause.scratch,
&mut clause.symbols,
clause.value_form,
result_ty,
)?;
clause_scratches.push((clause.scratch, clause.arm.is_none()));
// --- Phase 2: emit the real structure, splicing the scratch bodies. ---
let cond_ref = ValType::Ref(RefType {
nullable: true,
heap_type: HeapType::Concrete(ctx.condition_type_idx()),
let result_vt = ctx.wasm_val_type(result_ty);
let tag = ctx.nomi_error_tag();
emit.block_start_typed(BlockType::Result(result_vt)); // $outer
emit.block_start_typed(BlockType::Result(cond_ref)); // $handler
emit.try_table(
BlockType::Result(result_vt),
&[Catch::One { tag, label: 0 }],
);
emit.splice(&body_scratch.take_bytes());
if body_diverges {
// Dead tail value after a diverging body; reset to polymorphic so
// the try_table's declared result type is satisfied vacuously.
emit.unreachable();
emit.block_end(); // close try_table
emit.br(1); // normal completion → $outer, skip handler
emit.block_end(); // close $handler — catch lands here, condition on stack
emit.local_set(cond_local);
emit_dispatch(
emit,
&clauses,
&clause_scratches,
cond_local,
emit.block_end(); // close $outer
Ok(result_ty)
/// A compiled clause awaiting the unified result type: its scratch, the clause
/// scope, the value form and its arm (`None` when the clause diverges).
struct ClauseArm<'a> {
scratch: FunctionEmitter,
symbols: SymbolTable,
value_form: &'a Expr,
arm: Option<Arm>,
static EMPTY_CLAUSE_VALUE: Expr = Expr::Nil;
/// Compiles a clause body (already has `e` bound in `symbols`) into `emit`: its
/// leading forms for effect, its value form as an arm. An empty body is `nil`;
/// an earlier diverging form makes the rest dead.
fn compile_clause_body<'a>(
clause: &Clause<'a>,
) -> Result<(&'a Expr, Option<Arm>)> {
let Some((value_form, leading)) = clause.body.split_last() else {
return Ok((&EMPTY_CLAUSE_VALUE, Some(Arm::Nil)));
for form in leading {
crate::compiler::expr::compile_for_effect(ctx, emit, symbols, form)?;
if diverges {
return Ok((value_form, None));
Ok((value_form, compile_arm(ctx, emit, symbols, value_form)?))
/// Emit the flat dispatch at depth `parent+1` (only `$outer` open). Each
/// non-`t` clause is an independent `if` (Empty type) whose body, on match,
/// runs the spliced clause and `br $outer`s — so every clause body sits at
/// the same depth. A `t` clause runs unconditionally. With no `t`, a
/// fall-through re-throws the same condition.
fn emit_dispatch(
clauses: &[Clause<'_>],
scratches: &[(FunctionEmitter, bool)],
cond_local: u32,
result_ty: WasmType,
let condition_idx = ctx.condition_type_idx();
let string_eq = ctx.ids.string_eq;
for (clause, (scratch, diverges)) in clauses.iter().zip(scratches) {
match clause.code {
Some(code) => {
// condition.code == "CODE" ? → guard an Empty `if`.
emit.local_get(cond_local);
emit.ref_cast(condition_idx);
emit.struct_get(condition_idx, 0);
push_string_literal(ctx, emit, code)?;
emit.call(string_eq);
emit.if_block(BlockType::Empty);
emit.splice(scratch.bytes_ref());
// The clause value (if it didn't diverge) is on the stack;
// carry it out to `$outer` (relative depth 1 from inside the
// `if`). A diverging clause already left a polymorphic stack.
if !*diverges {
emit.br(1);
emit.block_end();
None => {
// `t` catch-all (last clause): runs unconditionally at
// `$outer`'s depth. Its value falls through to `$outer`'s
// end — no `br` needed. A diverging `t` body left a
// polymorphic stack, also fine.
let _ = (diverges, result_ty);
return Ok(());
// No `t` and nothing matched: re-throw a fresh $nomi_error carrying the
// same condition (no observable identity loss). The condition is stashed
// as `anyref`, so cast back to the concrete `$nomi_condition` (the tag
// param type) before throwing. `throw` is stack-polymorphic, satisfying
// `$outer`'s declared result type.
emit.throw(tag);
fn push_string_literal(
value: &str,
let data_idx = ctx.add_data(value.as_bytes())?;
emit.i32_const(0);
emit.i32_const(value.len() as i32);
emit.array_new_data(ctx.ids.ty_i8_array, data_idx);
/// Parse `(handler-case body clause...)`. Requires ≥1 body form; clauses
/// follow. Each clause is `(code-sym (var) body...)`; `t` is the catch-all
/// and, if present, must be the last clause.
fn parse(args: &[Expr]) -> Result<(&Expr, Vec<Clause<'_>>)> {
let (body, clause_exprs) = args.split_first().ok_or_else(|| {
Error::Compile(format!(
"{HANDLER_CASE} requires a body and zero or more clauses"
))
})?;
let mut clauses = Vec::with_capacity(clause_exprs.len());
for (i, clause) in clause_exprs.iter().enumerate() {
let elems = clause.as_list().ok_or_else(|| {
"{HANDLER_CASE}: clause must be a list, got {clause:?}"
if elems.len() < 2 {
return Err(Error::Compile(format!(
"{HANDLER_CASE}: clause needs a code symbol, a (var), and a body"
)));
let code = match &elems[0] {
// `t` reads as the `t` constant, not a symbol — it's the
// catch-all marker. A symbol head is a condition code.
Expr::T => None,
Expr::Symbol(s) if s == CATCH_ALL => None,
Expr::Symbol(s) => Some(s.as_str()),
other => {
"{HANDLER_CASE}: clause head must be a code symbol or t, got {other:?}"
if code.is_none() && i + 1 != clause_exprs.len() {
"{HANDLER_CASE}: the t catch-all clause must be last"
let var = match elems[1].as_list() {
Some([Expr::Symbol(v)]) => v.as_str(),
_ => {
"{HANDLER_CASE}: clause binding must be a single (var), got {:?}",
elems[1]
clauses.push(Clause {
code,
var,
body: &elems[2..],
Ok((body, clauses))