plum

# Design: variadic parameters (`values: ...a`)

## Problem

`fn(..., values: ...a)` parses today (`ast::ParamType::Variadic(Type)`), but every

downstream stage — checker, `monomorphize.rs`, codegen — treats a `Variadic(t)`

param identically to a plain fixed-arity `Type(t)` param: arity checks require

`args.len() == params.len()` exactly, and the param is bound as a single `t`-typed

value, not a collection. There is no way to actually call a variadic function with

0, 1, or many arguments, or to do anything with the collected values inside the

body. `examples/functions.plum`'s own `sumAll(nums: ...Int) -> Int = todo` has never

been implemented because there's nothing to implement it with.

This is the second of the two remaining "Known gaps" follow-ups (the first,

field/attribute assignment, is already done); it's a prerequisite for wiring up

`libs/std/list.plum`'s `add`/`init` methods, which is explicitly **out of scope**

for this cycle — this spec covers only making variadic parameters real as a

language feature, with `examples/functions.plum`'s `sumAll` as the target sanity

check.

## Scope

In scope:

- Call-site arity: a variadic param accepts 0 or more trailing arguments.

- Type-checking: each trailing argument unifies against the variadic's declared

  element type.

- The one supported operation on a variadic param inside the function body:

  `for v in nums` (direct iteration, binding `v` to each element in call order).

- `sumAll(nums: ...Int) -> Int` (from `examples/functions.plum`) implemented and

  tested end-to-end (parse → typecheck → compile → run).

Out of scope (tracked separately):

- Indexing syntax (`values[i]`) — no grammar for `[...]` expressions exists at all

  today; not needed since direct iteration covers the target use case.

- A `.length()` builtin or any other method on a variadic param.

- `libs/std/list.plum`'s `add`/`init`/etc. — those need this feature plus separate

  work once it lands.

- Passing an existing collection where variadic args are expected (i.e. no

  "spread" call syntax); every call site must list its trailing args literally.

- Variadic params anywhere but the last position (grammar already allows only one

  `variadic_type` per param list positionally by convention; the checker will

  enforce it's declared last and that there's at most one).

## Type representation

Add one variant to `plum-checker/src/types.rs`'s `PlumType`:

```rust

pub enum PlumType {

    // ...existing variants...

    /// The type of a variadic parameter, e.g. `...Int` -> `TVariadic(TInt)`.

    /// Appears in exactly two places: as the trailing entry of a `TFun`'s

    /// param-types list (for call-site arity/type checking), and as the type

    /// bound to the param's name inside the function body. Its only legal use

    /// inside a body is as a `for` loop's iterable; using it any other way

    /// (returning it, passing it to another call, unifying it against a

    /// concrete type) is a type error by construction — no other match arm

    /// in `unify` or `infer_expr` handles it.

    TVariadic(Box<PlumType>),

}

```

`Display` renders it as `...{inner}` (e.g. `...Int`), matching the source syntax,

for error messages.

Every place that currently converts `ast::ParamType::Variadic(t)` to a `PlumType`

by unwrapping straight to `plum_type_from_ast(t)` (there are several — in

`plum-checker/src/lib.rs`'s method/function signature building, `monomorphize.rs`,

and `plum-wasm-codegen/src/lib.rs`'s param-type resolution helpers) instead wraps it:

`PlumType::TVariadic(Box::new(plum_type_from_ast(t)))`.

## Checker changes

**Call-site arity + unification** (`plum-checker/src/lib.rs`'s `infer_expr` for

`Expr::FnCall`, and the analogous `ClassCall`/method-call arms if they can ever

target a variadic-param method — in practice today only free functions and

`name<Receiver>(...)` methods can declare `...a`, both go through the same

`TFun(param_types, ret)` shape): if `param_types.last()` is `TVariadic(elem)`,

require `args.len() >= param_types.len() - 1`; unify the fixed prefix positionally

as today; unify every remaining (trailing) arg against `elem`. If `param_types` is

empty this can't happen (a variadic-only function has `param_types.len() == 1`,

the variadic entry itself, so `args.len() >= 0` always holds — any number of args

including zero is valid).

**Declaring a variadic param**: when building a function/method's `TFun` signature

from its `ast::Param` list, error if more than one param is `ParamType::Variadic`,

or if a `Variadic` param isn't the last one in the list. This is a new validation,

not currently enforced anywhere (today it's moot since variadic isn't handled

specially at all).

**`for` loop typing** (`check_stmt`'s `Stmt::For` arm, `plum-checker/src/lib.rs`):

today it unconditionally binds every loop var to `TInt` without even checking the

iterable's shape. Change it to: infer the iterable's type; if it's

`TVariadic(elem)`, require exactly one loop var (`for v, i in nums` over a variadic

is a checker error — multi-var iteration isn't defined for this type) and bind

that var to `elem`; otherwise (the existing range case, `a..b`) keep today's

behavior of binding every loop var to `TInt` unconditionally, unchanged.

## Codegen changes

**Callee side**: a variadic param compiles to a single `i32` local — a pointer,

exactly like a class-instance param — carrying the calling convention used for all

of "unmodeled/pointer" types today (`ast_type_to_wasm`'s catch-all `Some(ValType::I32)`

arm). No new callee-side representation needed beyond wherever param `PlumType`s are

resolved for local typing (those sites already need the `TVariadic` unwrap from the

Type representation section above; the *wasm width* of a `TVariadic`-typed local is

always `ValType::I32`, same as any other pointer).

**Caller side** (the call-compiling code path used for `Expr::FnCall`, e.g. around

`plum-wasm-codegen/src/lib.rs`'s call-compilation logic): when the callee's last

param is variadic, compile the fixed-prefix args normally (pushed as ordinary wasm

call args), then build a length-prefixed buffer for the trailing args:

- `count = trailing_args.len()` (known at compile time — every call site lists its

  variadic args literally per this spec's scope)

- bump-allocate `8 * (count + 1)` bytes: `result = bump_global; bump_global += 8 * (count + 1)`

  (same inline bump-and-increment pattern already used for `ClassCall`/class-literal

  construction — no new allocation helper function needed, this is a handful of

  instructions inlined at the call site, matching how class construction already

  works)

- store `count` as an `i64` at offset `0` (`emit_store`, matching the class-field

  8-byte-stride convention used everywhere else in this file)

- for each trailing arg (compile-time-known position `i`), `compile_expr` it and

  `emit_store` it at the *static* offset `8 * (i + 1)` — this part needs no dynamic

  address arithmetic, since `i` is a Rust-level loop variable over the AST at

  codegen time, not a wasm runtime value

- push the resulting pointer as the final actual wasm call argument

**`for v in nums` codegen** (new branch in `compile_stmt`'s `Stmt::For` handling,

alongside the existing `matches!(b.op, ast::BinOp::Range)` branch — selected by the

checker-computed type of `f.iter` being `TVariadic`, not by the iterable's AST

shape, since the iterable is just a `Var` reference to the param, not a literal

range expression):

- load the variadic pointer into a scratch local (`ptr`)

- load `count` from `[ptr + 0]` (`I64Load`) into a scratch local

- loop an index `i` from `0` to `count` (same loop-structure codegen already used

  for range `for`, just with a runtime bound instead of a constant/expression one —

  range `for` already supports a non-constant upper bound today, e.g. `for i in 0..n`

  where `n` is a variable, so this reuses that existing loop-bound machinery, not new

  loop-control codegen)

- each iteration, compute the element's runtime address: `addr = ptr + 8 + i * 8`

  (`i32.add`/`i32.mul` on the loop index, converted from the `i64` loop-counter

  convention used by range `for` to `i32` for pointer arithmetic — check how range

  `for`'s existing loop counter width interacts with this and keep it consistent,

  adjusting with `i32.wrap_i64` if the existing loop counter is `i64`), then load the

  element from that computed address (offset `0` in the `MemArg`, since the offset

  is now baked into `addr` itself rather than being a `MemArg` immediate — this is

  the one genuinely new pattern in this feature, since every other load/store in

  this file uses a compile-time-constant `MemArg.offset`)

- bind the loop var to the loaded element value for the body's execution, exactly

  like the existing range `for`'s loop var binding

## Testing

- Checker tests (`plum-checker/tests/checker_tests.rs`): a variadic call with 0

  args passes; with 3 args of the right type passes; with a wrong-typed trailing

  arg is an error; declaring two variadic params is an error; declaring a variadic

  param not last is an error; `for v in nums` (variadic) type-checks and binds `v`

  to the element type; `for v, i in nums` (variadic, two loop vars) is an error.

- Codegen tests (`plum-wasm-codegen/tests/codegen_tests.rs`), each compiled and run

  via `run_main`:

  - `sumAll(nums: ...Int) -> Int` (the target example) called with 0 args returns 0

  - called with 3 args returns their sum

  - a variadic function with one fixed prefix param plus variadic

    (`combine(prefix: Int, rest: ...Int) -> Int`) correctly separates the two

  - `examples/functions.plum`'s `sumAll` is updated from `todo` to a real

    implementation and covered by `plum-checker/tests/examples_test.rs` /

    `plum-wasm-codegen/tests/examples_test.rs`'s existing per-example compile

    (and, since it now has real behavior, a runtime assertion) checks.

## README

Once this lands, update the "Known gaps" bullet that currently mentions `List`'s

methods being blocked on variadic support — `List`'s methods themselves stay

`todo` (out of scope here), but the bullet's phrasing changes from "blocked on

variadic-parameter support" to reflect that variadic parameters now exist as a

language feature and `List`'s own methods are the remaining, separate work.