plum

# Closures (`|params| body`)

## Problem

`closure` (`|params| body`) already exists as a tree-sitter grammar rule but is unreachable from

any parse path — it's referenced only in a comment inside `expression`'s choice list. There is

also no function-value type annotation syntax at all (something like `cb: fn(v: a) -> Bool`,

as used in the aspirational `libs/std/list.plum`, doesn't parse today). Without closures, any

higher-order method (`each`, `map`, `filter`, `reduce`, `sort`, ...) on a future `List`/`Map` has

no way to accept a callback, and `list.plum`'s actual usage (`this.each() |v| { res.write(v.to_str(),

sep) }`, capturing `res`/`sep` from the enclosing method) can't be expressed at all.

## Scope

Full, capturing closures — not just non-capturing function values. `list.plum`'s real usage reads

enclosing-scope variables from inside a closure literal, so a "closures" feature that can't

capture wouldn't actually unblock the motivating use case.

**Capture semantics: snapshot by value**, not live/shared mutable capture. A captured variable's

*current value* is copied into the closure's environment at the moment the closure literal is

evaluated; a later mutation to that variable in the enclosing scope is not visible inside an

already-created closure. This is simpler (no heap-boxed shared cells needed for ordinary locals)

and matches every known real usage (reading `res`/`sep`, not reassigning them from inside the

closure). Live/shared capture is explicitly out of scope — flagged here as a real semantic choice,

not an oversight, in case a future use case needs it.

**Call syntax: ordinary-argument only**, not trailing-closure syntax. `list.plum`'s draft usage

(`this.each() |v| { ... }` — the closure attached *after* a completed call, Ruby/Kotlin-style) is a

distinct, more elaborate grammar feature (a call expression optionally followed by a closure) than

a closure used as a normal expression. Since `list.plum` itself gets rewritten to standard syntax

in a later, separate follow-up, this feature only needs to support a closure passed as an ordinary

call argument — `each(|v| ...)` — not the trailing-block form.

## Design

### 1. Grammar (`tooling/tree-sitter-plum`)

- Uncomment `$.closure` in `expression`'s choice list (the rule itself — `"|" params "|" body` —

  already exists and needs no changes).

- Add a new function-value type rule for param type annotations, using **positional types only**

  (no param names in the annotation — types don't need names, and this stays consistent with the

  existing type-list convention `List(a)`/`Pair(a, b)`): `fn(Int) -> Bool`, `fn(a) -> b`. Usable

  wherever a param type currently appears (`each(cb: fn(a))`).

### 2. AST (`plum-core`)

- New `ast::Closure { params: Vec<String>, body: Block }`, added as `Expr::Closure(Box<Closure>)`.

- New `ast::ParamType::Fn(Vec<Type>, Option<Box<Type>>)` variant (param types, param positions

  only — a class field storing a callback value is out of scope, not needed by any current

  example or by `list.plum`'s actual usage, which only ever passes closures as call arguments).

### 3. Checker (`plum-checker`)

- `PlumType::TFun(Vec<PlumType>, Box<PlumType>)` already exists and models a closure's type

  directly — no new `PlumType` variant needed.

- `infer_expr`'s new `Closure` arm: bind each closure param to a fresh `TVar` (matching this

  checker's existing permissive style — it already never really unifies generic parameters, just

  accepts them), infer the body against that environment, return `TFun(param_types, body_type)`.

- Calling a closure-typed parameter by name (`cb(x)`) already type-checks via the **existing**

  `FnCall` inference path unmodified — `lookup(env, &call.name)` resolves any `TFun`-typed binding

  in scope, regardless of whether it came from a top-level function or a local closure-typed

  param. No changes needed there.

### 4. Codegen (`plum-wasm-codegen`)

This is the substantial part — wasm has no closures natively, so it needs:

- **New wasm sections**: a function table and an elements segment. `WasmModule` needs

  `add_table`/element-segment support, which doesn't exist yet.

- **Compiling a closure literal**: every closure literal becomes its own real wasm function,

  registered as a table element, with an **implicit first parameter** — the boxed

  captured-environment pointer — exactly mirroring how a method already receives `self` as an

  implicit first parameter. Inside the closure's compiled body, each captured variable is loaded

  from a fixed offset within that env struct (same load mechanics already used for class fields).

- **Free-variable analysis**: at the point a closure literal appears in source, walk its body and

  collect every referenced name that is NOT one of the closure's own declared params, a global, or

  a function name — these are the captured variables, snapshotted by value.

- **Constructing the closure value**: at the closure literal's site, bump-allocate an env struct

  sized to hold the captured variables' current values (same bump-allocator convention as class

  instances), then bump-allocate a small `{table_index: i32, env_pointer: i32}` pair. The pointer

  to that pair **is** the closure's runtime value — a single `i32`, consistent with every other

  reference-shaped value in this compiler (class instances, payload-carrying enum variants).

- **Calling a closure value**: load `table_index` and `env_pointer` from the pointer, push

  `env_pointer` then the real call arguments, then `call_indirect`. The wasm type index for

  `call_indirect` is resolved from the **caller's** own already-concrete (monomorphized) call

  site — a closure's internal capture layout is opaque to its caller, so calling a higher-order

  function like `each` needs no new monomorphization mechanism: `each`'s own concrete

  instantiation (via the existing generics pass) already fixes what signature any closure passed

  to it must have, and the checker already enforces that at the call site.

## Testing plan

- **Grammar**: corpus tests for a closure literal parsing in expression position, and a

  `fn(...)`-typed param annotation parsing correctly (both bracket-free positional-type forms:

  `fn(Int) -> Bool`, `fn(a) -> b`).

- **Checker**: a closure's inferred `TFun` type flows correctly into a `TFun`-typed binding;

  calling a closure-typed param type-checks via the unmodified `FnCall` path.

- **Codegen** (compiled and executed via `wasmtime`, matching existing style):

  - A non-capturing closure passed to a function and called.

  - A closure capturing one enclosing local, called after that local's value has changed in the

    enclosing scope — proving the capture is a value snapshot at creation time, not a live

    reference (the closure must see the OLD value, not the new one).

  - A closure passed through an already-generic higher-order function (proving the two features

    compose — the outer function is monomorphized per its own generic param as usual, and any

    closure passed to it is called correctly via `call_indirect` regardless).

- **Examples**: a minimal, real end-to-end usage (e.g. a small `each`-like helper function taking

  a `fn(a)` callback, called with both a non-capturing and a capturing closure).

## Out of scope

- A class field storing a closure value.

- Live/shared mutable capture (a closure seeing a later mutation to a captured variable) — see

  "Capture semantics" above; this is a deliberate simplification, not a deferred requirement.

- Multiple closures with genuinely different captured-variable layouts needing different wasm

  function *signatures* at the same `call_indirect` site — not expected to arise given the design

  (the env pointer is always a single opaque `i32` regardless of what it points to), but noted as

  an edge to watch during implementation.

- Rewriting `libs/std/list.plum`/`map.plum` to actually use this — a separate, subsequent

  follow-up once closures exist.