Peon

A statically typed programming language with generational references, generics, generators, an async/structured-concurrency surface, and a native C backend.

Peon compiles to C and produces standalone executables. It uses generational references for memory safety without a garbage collector, and provides deterministic destruction via lifecycle hooks.

Quick look

# Generators produce values lazily
generator fn range(start: int64, stop: int64): Generator[int64, void, void] {
    var i = start;
    while i < stop {
        yield i;
        i = i + 1;
    }
}

for i in range(0, 5) {
    print(i);
}

# Enums are tagged unions with pattern matching
type Shape = enum {
    Circle { radius: float64; },
    Rect { width: float64; height: float64; },
    Point
}

fn area(s: Shape): float64 {
    return match s {
        case Circle(radius = r) { 3.14159 * r * r }
        case Rect(width = w, height = h) { w * h }
        case Point { 0.0 }
    };
}

# Managed references with deterministic destruction
type Node = ref object {
    value: int64;
    label: string;
}

fn `destroy=`(n: mut lent Node) {
    print(f"destroying {n.label}");
    defaultDestroy();
}

fn run() {
    let a = Node(value = 1, label = "first");
    let b = Node(value = 2, label = "second");
    # a and b are destroyed here when they go out of scope
}

# Generics with interface constraints
iface Show {
    fn show(self): string;
}

fn printAll[T: Show](items: seq[T]) {
    for item in items {
        print(show(item[]));
    }
}

# Closures are first-class values
fn makeAdder(base: int64): fn(x: int64): int64 {
    return lambda(x: int64): int64 {
        return x + base;
    };
}

let add5 = makeAdder(5);
print(add5(10));   # 15

# Structured concurrency uses async functions, nurseries, spawn, and await
async fn parallelSum(a: string, b: string): int64 {
    nursery tasks {
        let left = spawn fetchCount(a);
        let right = spawn fetchCount(b);
        return await left + await right;
    }
}

Features

• Types: integers (8/16/32/64-bit signed and unsigned), floats (32/64-bit), booleans, strings, plain objects, ref objects, enums (tagged unions), static arrays, dynamic sequences
• Generics: parametric polymorphism with interface constraints and const generics
• Interfaces: static conformance checking, intersection constraints (T: Copy & Show)
• Memory model: generational references with deterministic destruction, lifecycle hooks (destroy=, clone=, move=), borrows (lent, mut lent)
• Generators: suspendable functions with yield, yield from, and the next() iterator protocol
• Structured concurrency surface: async fn, await, nursery, and spawn, with compiler-enforced scoped task handles
• Closures: lambdas with captured variables, three frame placement levels (inline, stack, heap)
• Pattern matching: match/case with variant destructuring, or-patterns, and borrowed bindings
• Control flow expressions: if, when, match, and blocks as expressions
• Compile-time: when/defined(...) conditionals, const evaluation, configurable safety checks
• C interop: importc/exportc pragmas, C-compatible types, explicit type converters
• Raw pointers: ptr T, pointer, alloc/create/realloc/dealloc, copyMem, cast
• Modules: import/export with visibility control (* suffix)
• No implicit conversions: all type conversions are explicit

Documentation

• Language Manual -- complete reference for implemented features
• Compiler Architecture -- end-to-end pipeline documentation
• Grammar -- formal grammar specification
• Bootstrap TODO -- roadmap toward self-hosting
• Redesign Draft -- LSP-first architecture notes for the rewrite

Build

Requires Nim 2.x and a C compiler (clang by default).

nimble build

This grabs dependencies, runs the test suite, and produces a peon binary.

Usage

# Compile and run
peon run examples/hello.pn

# Compile only
peon compile examples/hello.pn -o hello

# Release build
peon compile examples/hello.pn -o hello --release

# Show generated C
peon compile examples/hello.pn --showGenerated

Tests

nimble test

Examples

See src/examples/ for runnable programs demonstrating:

• hello.pn -- hello world
• generators.pn -- generators and for-loops
• generics.pn -- generic functions and const generics
• enums_and_match.pn -- tagged unions and pattern matching
• ref_objects.pn -- managed references and destructors
• closures.pn -- closures and higher-order functions
• sequences.pn -- dynamic arrays
• raw_pointers.pn -- unmanaged memory
• optionals.pn -- Option types
• blocks.pn -- named blocks
• simple_closure.pn -- borrowed closures
• structured_concurrency.pn -- events, nurseries, cancellation, shielding, and auto-join
• bench/ -- performance benchmarks (fibonacci, sieve, tree)

Editor support

A VS Code syntax highlighting extension is available under peon-syntax-highlighting/. Install the .vsix file or copy the folder into your VS Code extensions directory.

For Gitea/Chroma-based highlighting, a lexer definition is provided at peon-syntax-highlighting/peon.xml.

License

Apache 2.0