plum

# 👾 Plum Programming Language

- A statically typed, imperative programming language with ADT's (Algebraic Data Types) inspired by rust, gleam

- The compiler is built upon the tree-sitter parser so has out of the box syntax highlighting support for helix and zed editor

- Plans to be compiled to amd64,arm64, and riscv64 using QBE maintaining C-ABI compatibility

## Requirements

```sh

node >= 23.1.0

npm >= 10.9.0

qbe >= 1.2

clang >= 16.0.0

```

## Language Syntax

This section documents the syntax currently implemented by the [tree-sitter grammar](tooling/tree-sitter-plum/grammar.js), [`plum-checker`](plum-checker), and [`plum-wasm-codegen`](plum-wasm-codegen). Every construct below has a runnable, verified example in [`examples/`](examples) — the two test suites [`plum-checker/tests/examples_test.rs`](plum-checker/tests/examples_test.rs) and [`plum-wasm-codegen/tests/examples_test.rs`](plum-wasm-codegen/tests/examples_test.rs) parse, type-check, and (where noted) compile-and-execute every file in that directory, so this documentation can't silently drift out of sync with what actually works.

> The [docs website](website/src/content/docs) describes a considerably more elaborate *future* syntax (`fn`, `record`, arrow return types, `{}` blocks, generic `[T]` params). That syntax isn't implemented yet — everything below is what the compiler accepts **today**.

### Table of contents

- [Layout and comments](#layout-and-comments)

- [Naming conventions](#naming-conventions)

- [Modules and imports](#modules-and-imports)

- [Constants](#constants)

- [Literals](#literals)

- [Operators](#operators)

- [Variables and assignment](#variables-and-assignment)

- [Control flow](#control-flow)

- [Functions](#functions)

- [Types: records, traits, enums](#types-records-traits-enums)

- [Generics](#generics)

- [`self`, field access, and methods](#self-field-access-and-methods)

- [Constructing values](#constructing-values)

- [`match`](#match)

- [String interpolation](#string-interpolation)

- [`extern` functions and printing](#extern-functions-and-printing)

- [Known gaps](#known-gaps)

### Layout and comments

Blocks are indentation-sensitive (2 spaces), like Python — there's no `{ }` for grouping statements. A `#` starts a line comment.

```plum

# this is a comment

fun main() =

  x = 1

  if x > 0

    x = x + 1

```

### Naming conventions

The lexer enforces case by construct — using the wrong case for a position is a parse error, not just a style nit:

| Token | Case | Used for |

|---|---|---|

| `type_identifier` | `PascalCase` | type/trait/enum names, generic bounds |

| `fn_identifier` | `camelCase` | function/method names, `.field`/`.method()` member names |

| `var_identifier` | `snake_case` | variables, params, fields (also accepts camelCase — see below) |

| `const_identifier` | `SCREAMING_SNAKE_CASE` | top-level constants |

| `mod_identifier` | `snake_case`, single word | `module` declarations only (no `/`) |

`var_identifier`'s regex is deliberately a superset of `fn_identifier`'s (it allows both `_` and mixed case) so that a bare function call like `factorial(x)` — an all-lowercase, no-underscore name — isn't ambiguous between "a variable" and "a function" at the lexer level.

### Modules and imports

```plum

module basics

import std/io

```

`module` takes exactly one identifier (no path segments). `import` takes a `/`-separated path; there's no module resolution yet — it's parsed but not loaded.

### Constants

```plum

MAX_RETRIES = 3

PI = 3.14159

GREETING = "hello"

```

Top-level only, `SCREAMING_SNAKE_CASE`, one expression.

### Literals

```plum

dec = 42

hex = 0xFF

bin = 0b1010

big = 1_000_000       # underscores allowed as digit separators

flt = 3.14

flt2 = 12.0f          # trailing f/F suffix

exp = 6.022e23

name = "plum"

empty = ""

escaped = "line one\nline two\ttabbed \"quoted\""

yes = True

no = False

```

`True`/`False` are built into the type checker/codegen as `Bool`'s two variants — you don't need to declare `enum Bool` yourself to use them.

Full example: [`examples/basics.plum`](examples/basics.plum), [`examples/strings.plum`](examples/strings.plum).

### Operators

From tightest to loosest binding:

| Precedence | Operators | Notes |

|---|---|---|

| highest | `.` | attribute access / method call |

| | unary `+` `-` | |

| | `*` `/` `%` | |

| | `+` `-` | |

| | `<<` `>>` | |

| | `^` | |

| | `&` | |

| | `\|` | |

| | `<` `<=` `==` `!=` `>=` `>` `<>` | comparisons |

| | `!` | boolean not |

| | `&&` | |

| | `\|\|` | |

| | `..` | range (e.g. `for i in 0..5`) |

| lowest | `? :` | ternary |

`!` binds **looser** than comparisons — `!a == b` means `!(a == b)`, not `(!a) == b`. Whenever you mix categories (especially with `!`), group explicitly rather than relying on memorized precedence:

```plum

grouped = {1 + 2} * {3 - 1}    # {expr} groups, like (expr) in most languages

picked = cmp ? sum : bits

negated = -sum

inverted = !cmp

```

Note: this language uses `{ }` for grouping a sub-expression, not `( )` — parens are reserved for call/constructor argument lists.

Full example: [`examples/basics.plum`](examples/basics.plum).

### Variables and assignment

```plum

x = 1

a, b = 1, 2          # multiple targets, positionally paired with multiple values

```

Assignment introduces a binding if `x` isn't already in scope, or updates it otherwise — there's no separate `let`/`var` keyword.

### Control flow

```plum

if n < 0

  return "negative"

else if n == 0

  return "zero"

else

  return "positive"

while i > 0

  i = i - 1

for i in 0..limit

  if i == 3

    continue

  if i == 8

    break

  total = total + i

assert n > 0    # traps at runtime if false

todo            # traps at runtime — marks a body as not yet implemented

```

`for x in <range>` only accepts a range expression (`a..b`) or another primary expression on the right — there's no iterator protocol yet.

Full example: [`examples/control_flow.plum`](examples/control_flow.plum).

### Functions

```plum

fun addInts(a: Int, b: Int) -> Int =

  a + b

fun greet() =                        # no return type => Unit

  todo

fun withDefault(a: Int, step: Int = 1) -> Int =

  a + step

fun sumAll(nums: ...Int) -> Int =    # variadic param

  todo

```

The body always follows `=` on the next, indented line (`= expr` on the same line is grammatically accepted too, but every example and test in this repo uses the indented form — prefer it for consistency).

Full example: [`examples/functions.plum`](examples/functions.plum).

### Types: records, traits, enums

```plum

type Point =

  x: Int

  y: Int

type Named(Stringable) =    # implements Stringable

  name: Str

trait Shape =

  area() -> Float

  perimeter() -> Float

enum Color =

  | Red

  | Green

  | Blue

enum Option =

  | Some(Int)              # variant with payload

  | None

```

Full example: [`examples/types.plum`](examples/types.plum).

### Generics

Generic type parameters are single letters only: `a`, `b`, `c`, `d`.

```plum

type Box(a) =

  value: a

trait Comparable(a: Ord) =    # bounded generic param

  compareTo(other: a) -> Int

fun wrap(value: a) -> Bool =      # generic param type

  True

```

Generic **arguments** (instantiating a generic type) accept either bracket or paren syntax: `List[Int]` and `List(Int)` both parse. User-defined generics (classes, their methods, free functions, and enums) are monomorphized: each concrete-type-argument combination actually used in the program gets its own specialized, fully-concrete copy, which then type-checks and compiles to wasm through the normal, unmodified pipeline. See `useWrap`/`usePair` in [`examples/functions.plum`](examples/functions.plum) and `makeIntBox`/`makeStrBox` in [`examples/types.plum`](examples/types.plum) for real instantiation sites. Generic enums support any number of concrete instantiations coexisting in one program (variant names are mangled per instantiation, e.g. `Some` -> `Some$Int`/`Some$Str`, internally — invisible to user code). One narrower residual limitation: a payload-free variant (e.g. `None`) used as a bare value *outside* of a `match` pattern can't be disambiguated between multiple concrete instantiations of its enum from that expression alone; constructing via a payload-carrying sibling (`Some(5)`) and matching (`Some(v) => ...`, `None => ...`) is fully supported and is the overwhelmingly common usage pattern.

Full example: [`examples/types.plum`](examples/types.plum), [`examples/functions.plum`](examples/functions.plum).

### Closures

```plum

fun each(cb: fn(Int) -> Int) -> Int =

  cb(5)

fun useCapturingClosure() -> Int =

  offset = 100

  cb = |v|

    v + offset

  cb(5)

fun main() -> Int =

  each(|v| v * 3) + useCapturingClosure()

```

A closure literal is `|params| body`: zero or more bare parameter names between pipes, followed by an expression or an indented block body. A parameter's type is inferred from context (e.g. the declared type of the `fn(...)` slot it's passed into) rather than annotated inline.

A `fn(...)` / `fn(...) -> T` type annotates a closure-typed parameter or field: `fn(Int) -> Int` is a function from one `Int` to an `Int`; parameter types are positional only (no names). Closures compile to a `{table_index, env_pointer}` pair and are called via `call_indirect` through a function table, so a `fn(...)`-typed value can hold a closure literal, a plain top-level named function (`each(double)` — compiled as a zero-capture "trampoline" closure), or a closure nested inside another closure's body.

Capture is **snapshot-by-value**: any outer variable a closure body references is copied into the closure's environment at the moment the closure literal is evaluated, not re-read live later. Reassigning the captured variable afterward does not change what the closure sees.

Closures parse and compile in two shapes: passed directly as a call argument (`each(|v| v * 3)`), or assigned to a local first and called or passed on later (`cb = |v|\n  v + offset` followed by `cb(5)` or `each(cb)`). Both support a multi-line indented body.

Full example: [`examples/closures.plum`](examples/closures.plum).

### `self`, field access, and methods

A `fun` declared indented directly inside a `type`/`enum` body is a method on that type, with an implicit `self`:

```plum

type Cat =

  name: Str

  age: Int

  fun getAge(self) -> Int =

    self.age

  fun birthday(self) -> Int =

    self.age + 1

fun main() -> Int =

  c = Cat(name: "Whiskers", age: 3)

  a = c.getAge()        # method call

  w = Wrapper(inner: c, tag: 1)

  w.inner.age            # chained field access

```

Methods are dispatched by declared receiver type, not by name alone — two types can each define a method with the same name without colliding.

Full example: [`examples/methods.plum`](examples/methods.plum).

### Constructing values

```plum

Cat(name: "Whiskers", age: 3)

```

Construct a `type` value by calling its name with `field: value` pairs (any order; every field must be provided).

### `match`

```plum

match n

  0 => "zero"       # inline body

  1 =>

    "one"           # indented block body — both forms are accepted

  _ =>

    "many"

match b

  True =>

    1

  False =>

    0

match opt

  Some(v) =>

    v

  None =>

    0

```

A case body can be a single inline expression right after `=>`, or an indented block — pick whichever reads better for that arm. Patterns can be: integer/float/string literals, a bare identifier (binds a new local to the subject's value), a bare capitalized tag (`True`, `False`, or any declared `enum` variant with no payload — compared, not bound), a constructor pattern (`Some(v)`, binding its argument — sub-patterns can themselves be constructor patterns, e.g. `Wrap(Some(v))`), or `_` (wildcard). `match a, b, ...` against multiple comma-separated subjects is also supported — each case supplies one pattern per subject, and every position must match for that case to apply.

Full example: [`examples/match.plum`](examples/match.plum).

### String interpolation

```plum

fun greet(name: Str) -> Str =

  "Hello, {name}!"

```

`{expr}` inside a string interpolates a single primary expression (a variable, literal, attribute access, etc). Parses, type-checks, and compiles for `Str`, `Int`, and `Bool` values; interpolating a `Float` reports a clear error (see below).

Full example: [`examples/strings.plum`](examples/strings.plum).

### `extern` functions and printing

```plum

extern fun printLn(s: Str)

```

`extern fun` declares a function with no Plum body at all — no `=`, no `todo` — backed instead by a host-provided wasm import. wasm has no built-in notion of stdout, so this is how `printLn` exists: `plum-checker` requires an `extern` fn to have no body and no receiver (it can't be a method), and `plum-wasm-codegen` compiles it to a genuine wasm import (`plum::printLn`) instead of a normal function body. Both `plum run` (JIT-executes immediately under an embedded `wasmtime`) and `plum build` (AOT-compiles to wasm and links it into a standalone executable via the `plum-runtime` crate) supply this import; a bare `.wasm` file run through an unmodified `wasmtime` CLI will fail to instantiate for lack of it. `libs/std/os.plum` declares `printLn` for use via `import std/os`; [`examples/io.plum`](examples/io.plum) declares an equivalent local copy (avoiding the import, so it stays runnable by the single-file test harnesses in `plum-checker`/`plum-wasm-codegen`) and is the smallest example to run for a smoke test:

```

$ plum run examples/io.plum

hello from plum

hello, world!

```

### Known gaps

Some things parse and type-check but don't compile to wasm yet — `plum-wasm-codegen` reports a clear error rather than silently producing wrong code:

- interpolating a `Float` value in a string (`Str`/`Int`/`Bool` interpolation, and plain non-interpolated literals, all compile) — correct decimal formatting of a float is a substantial separate undertaking (something like Grisu/Ryu), scoped out for now

- `libs/std`'s actual `List`/`Map` still don't compile — `List`'s methods (`get`/`length`/`add`/`set`/`removeAt`/`remove`/`clear`/`reverse`/`each`/`map`) are all implemented now, but a class or enum-variant field declared with a concrete instantiation of another generic type (`Node.next: Option[Node]`, needed by `List`/`Node`'s own linked-list shape) doesn't survive monomorphization — `plumTypeFromAst` drops generic type arguments when building field types, so once the referenced generic type is specialized (and its unspecialized original removed), the field is left pointing at a name that no longer exists. This is a `plum-checker` generics gap, not a codegen one — the underlying wasm-gc struct/array machinery it would need is fully implemented and tested (see `plum-wasm-codegen/tests/codegen_tests.rs`'s `listAddSetRemoveAtRemoveClearReverseAllWorkCorrectly` and `removingEveryNodeInALoopLeavesAnEmptyCorrectlyFunctioningList`, which port `List`'s methods onto an equivalent non-generic shape to prove it). Separately, `List`'s own `join` method (and `Map`) reference a `Buffer` type and trait-bounded dispatch (`Stringable`) that don't exist yet — `plum-checker` doesn't process trait declarations at all currently