plum

# 👾 Plum

A statically typed, imperative programming language with algebraic data types, inspired by Rust and Gleam.

- Built on a [tree-sitter](plum-tooling/tree-sitter-plum) grammar, with syntax highlighting for Helix and VSCode out of the box (`plum editor helix` / `plum editor vscode`)

- Compiles to WebAssembly today, with plans to target amd64, arm64, and riscv64 via QBE (C-ABI compatible)

## Requirements

```sh

node >= 23.1.0

npm >= 10.9.0

qbe >= 1.2

clang >= 16.0.0

```

## Installing the `plum` CLI

```sh

cargo install --path plum-cli

```

Installs a release build as `plum` in `~/.cargo/bin`, which `cargo` puts on your `PATH` for you — no `sudo`/`/usr/local/bin` needed. Re-run this after pulling changes to the compiler; it doesn't auto-update. Use `cargo run -p plum-cli --` instead while actively developing the compiler itself.

## Layout and comments

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

```plum

# this is a comment

fun main() =

  x = 1

  if x > 0

    x = x + 1

```

## Naming conventions

| Case | Used for |

|---|---|

| `PascalCase` | types, traits, enums |

| `camelCase` | functions, methods, fields |

| `snake_case` | variables, params |

| `SCREAMING_SNAKE_CASE` | top-level constants |

| single uppercase letter (`T`, `K`, `V`) | generic type parameters |

## Modules and imports

```plum

module basics

import std/io

```

## Constants

```plum

MAX_RETRIES = 3

PI = 3.14159

GREETING = "hello"

```

## Literals

```plum

dec = 42

hex = 0xFF

bin = 0b1010

big = 1_000_000

flt = 3.14

flt2 = 12.0f

exp = 6.022e23

name = "plum"

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

yes = True

no = False

```

## Operators

From tightest to loosest binding:

| Precedence | Operators | Notes |

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

| highest | `.` `?.` | attribute access / method call, safe navigation |

| | `+` `-` | unary |

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

| | `+` `-` | |

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

| | `^` | |

| | `&` | |

| | `\|` | |

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

| | `!` | boolean not |

| | `&&` | |

| | `\|\|` | |

| lowest | `? :` | ternary |

There's no range operator — `for i := range n` is the only way to iterate a numeric range. `{ }` is used to group a sub-expression (not `( )`, which is reserved for calls):

```plum

grouped = {1 + 2} * {3 - 1}

picked = cmp ? sum : bits

negated = -sum

inverted = !cmp

```

## Variables and assignment

```plum

x := 1

# declares a new binding — errors if `x` is already in scope

a, b := 1, 2

# multiple targets, positionally paired with multiple values

x = 2

# reassigns an existing binding — type-checked against x's declared type

```

## Control flow

```plum

if n < 0

  return "negative"

else if n == 0

  return "zero"

else

  return "positive"

i := start

while i > 0

  i = i - 1

for i := range 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

```

## 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

```

## Testing

Zig-style `test` blocks are a native language feature, compiled and run only by `plum test`:

```plum

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

  a + b

test "add works"

  assert add(1, 2) == 3

```

```sh

$ plum test plum-examples/testing.plum

└─ add works ✔

1 passed, 0 failed

```

## Types: records, traits, enums

There's a single declaration form, `enum` — a record type is just a single-variant enum whose one variant shares the enum's own name:

```plum

enum Point =

  | Point(x: Int, y: Int)

enum Named(ToStr) = # implements ToStr

  | Named(name: Str)

trait Shape =

  area() -> Float

  perimeter() -> Float

enum Color =

  | Red

  | Green

  | Blue

enum Option =

  | Some(Int) # unnamed positional payload — Some(5)

  | None

enum Shape =

  | Circle(radius: Int) # named payload fields — Circle(radius: 5) or Circle(5)

  | Square(x: Int, y: Int)

enum Step(n: Int) = # a shared field on every variant ...

  | ReadMin(10) # ... each variant supplies its own value for it

  | ReadMax(20)

```

## Generics

```plum

enum Box[T] =

  | Box(value: T)

trait Comparable[T: Ord] = # bounded generic param

  compareTo(other: T) -> Int

fun wrap(value: T) -> Bool =

  True

```

Generic types, methods, and free functions are monomorphized: each concrete instantiation used in the program gets its own specialized copy. `List[Int]` and `List(Int)` both parse as generic arguments.

## 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`. Capture is snapshot-by-value: a closure copies the outer variables it references at creation time, not re-read live later. A `fn(...) -> T` type annotates a closure-typed parameter or field.

## `self`, field access, and methods

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

```plum

enum Cat =

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

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

  w.inner.age # chained field access

```

## Constructing values

```plum

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

```

Construct a record-shaped enum value by calling its name with `field: value` pairs (any order; every field required).

Fields are mutable (`c.age = c.age + 1`), and a Gleam-style spread updates a copy from an existing value, overriding just the fields you name:

```plum

older := Cat(..c, age: c.age + 1)

```

## `match`

```plum

match n

  0 => 1

  x =>

    if x < 0

      -1

    else

      2

match opt

  Some(v) => v

  None => 0

match book

  FantasyBook(title, _, hasMythicalCreatures) when hasMythicalCreatures =>

    "Fantasy book \"{title}\" features mythical creatures"

  FantasyBook(title, _, _) => "Fantasy book \"{title}\" has no mythical creatures"

```

Patterns can be literals, a bare identifier (binds), a bare capitalized tag (compared), a constructor pattern (`Some(v)`, binding its argument), or `_` (wildcard). `match a, b, ...` supports multiple subjects, and a case can carry a `when <expr>` guard.

## String interpolation

```plum

fun greet(name: Str) -> Str =

  "Hello, {name}!"

```

`{expr}` interpolates a variable, literal, attribute access, `&&`/`||`/comparison, ternary, or a closure-taking method call.

## `extern` functions and printing

```plum

extern fun printLn(s: Str)

```

`extern fun` declares a function backed by a host-provided wasm import, with no Plum body. `plum-std/Os.plum` declares `printLn` for use via `import std/os`.

```sh

$ plum run plum-examples/io.plum

hello from plum

```

## Error propagation

`expr?` unwraps a `Result`'s `Ok` or an `Option`'s `Some`, or exits the enclosing function early with the `Err`/`None` value as-is otherwise — Rust's `?`:

```plum

fun sumTwo(a: Str, b: Str) -> Result[Int, Str] =

  x := parsePositive(a)?

  y := parsePositive(b)?

  return Ok(x + y)

```

`left ?: right` (elvis) is the plain-expression counterpart — no early return, just a fallback value if `left` is `Err`/`None`:

```plum

fun sumOrZero(a: Str, b: Str) -> Int =

  x := parsePositive(a) ?: 0

  y := parsePositive(b) ?: 0

  x + y

```

`obj?.field` / `obj?.method(args)` (safe navigation, Groovy/Kotlin-style) reaches into a `Result`/`Option` value without unwrapping it — `Some`/`Ok` maps the field or method access over the inner value and re-wraps it, `None`/`Err` passes through untouched:

```plum

fun cityName(person: Option[Person]) -> Option[Str] =

  person?.city?.name

```

It's sugar for `obj.map(|v| v.field)` — nothing more than that; chain it as many times as needed.

## Standard library highlights

- **`Bool`** (`import std/Bool`) — ordinary `enum Bool = | True | False`

- **`Str`** (`import std/Str`) — a byte array with a codepoint-aware layer for Unicode correctness: `runeLength`, `runeAt`, `codePointAt`, `codePointToStr`

- **`Byte`** / **`[]Byte`** (`import std/Byte`) — a scalar unsigned 8-bit value and a fixed-length mutable byte slice

- **`Buffer`** (`import std/Buffer`) — a growable, mutable byte sequence for building up a `Str`, amortized O(n) writes

- **`Array[T]`** (`import std/Array`) — a generic, growable array (reference types only)

- **`Map[K: Hashable, V]`** (`import std/Map`) — a real bucketed hash table

- **`List[T]`** (`import std/List`) — a singly-linked list with `get`/`add`/`set`/`removeAt`/`remove`/`each`/`map`/`reduce`/`sort`/`join`/`chunk`/`partition`

See [`plum-examples/`](plum-examples) for a runnable file per feature above, and [`plum-std/`](plum-std) for the standard library source.