PickleScript .pkl

A statically typed language, written in itself.

PickleScript has pattern matching, generics, classes and a garbage collected heap. Newlines end statements, so there are no semicolons to keep track of. The compiler that reads all of it, the x86-64 backend it emits through and the linker that produces the executable are themselves written in PickleScript.

  • Compiler written in PickleScript
  • Native executable, no runtime beside it
  • Garbage collected by default
  • Built-in test runner
hello.pkl
module hello

fn main() {
    let name = "world"
    print("Hello, {name}!")
}

$ pickle run hello.pkl

Hello, world!

The language

Everything the language gives you, in one page

PickleScript takes ideas that already work in other languages and re-derives them for its own grammar, so the same rule holds everywhere you look.

Types that stay out of the way

int, string, bool, List<T>, Map<K, V>, tuples, function types and T? are all resolved before a single instruction is emitted. A type error arrives as a diagnostic with a line and a column, not as a surprise at runtime.

match instead of null checks

Options, tuples and enum payloads come apart with match. Case some(v), case (a, b), literal alternatives, guards and a catch-all when the type says one is needed. Comparing an option against none is not the pattern to reach for.

Classes, structs, enums, interfaces

A class has reference semantics and single inheritance, a struct copies on assignment, an enum is a closed sum whose payload is only readable inside match, and an interface is a nominal contract you test with is, as and as?.

Generics that compile down

Generic functions and interfaces are monomorphized per concrete type list. Type arguments are inferred when the arguments pin them, and you write fn<int> when the generic is used as a value.

Memory you can actually see

Most code never mentions memory. Mark a class #[manualAlloc] and it frees its own owned fields, or step into an unsafe block when you want alloc, free and raw pointer access on purpose.

One binary for the whole job

pickle run, build, test, lex and explain. The test runner picks up every *_test.pkl file in the project, and explain looks up any diagnostic code, including the ones that tell you a shape is not lowered yet.

Examples

Whole files you can read in a minute

Each one saves as a file and runs as written. Nothing here is a sketch: it is the syntax the checker accepts today.

Options and pattern matching

An optional is none or some(value), and match is how you take it apart. The same form destructures tuples, and the compiler asks for a catch-all when a type can fail to match.

// an option is none or some(value)
fn describe(token: string?) -> string {
    match (token) {
        case some(value) -> "found {value}"
        case none -> "no token"
    }
}

// tuples destructure the same way
fn label(pair: (int, string)) -> string {
    match (pair) {
        case (count, name) -> "{count} {name}"
    }
}

fn main() {
    print(describe(some("abc123")))
    print(describe(none))
    print(label((3, "apples")))
}

Output

$ pickle run options.pklfound abc123no token3 apples

What to notice

2
T? is none or some(value), never null
3-6
one case per shape, and only some(value) binds a name
12
Tuples come apart the same way

The toolchain

The compiler is written in the language it compiles

PickleScript did not begin with a self-hosted compiler. It began with one written in another language, and that is the part being retired. The lexer, the parser, the type checker, the emitter, the x86-64 backend and the linker are PickleScript source files now, and the battery checks them against the reference build byte for byte.
files in the compiler port
37
lines of .pkl
38,051
verification gates
11
self sources byte compared
13

Written in PickleScript

  • Front end — lexer, token, parser, ast
  • Types — ty, resolve, check, diag, error
  • Emitter — emit, ir, front, history
  • x86-64 backend — opcode, ModRM, SIB and REX encoding
  • Object and PE layer — coff, objread, linker, pelink

Still to be retired

  • The switchover — The shipped CLI still runs the reference build. Changing that is the step that retires it.
  • The memory core — The collector, arena and raw allocator are native. The self-hosted runtime owns the contract for now, and the core is the seam it has not closed yet.
  • A narrower backend — The x86-64 backend takes four parameters per call and Windows x64 only, so it is not yet the whole target story.

Where it stands

An honest look at the project

PickleScript is young and open source. Here is what works, what is being finished, and what is missing, so you can decide whether it is useful to you today.

Working today

  • Modules, imports and a file layout that mirrors the module path
  • Classes, structs, enums, interfaces, generics and inheritance
  • Options, match, casts and the collections you expect: List, Map, string, bytes
  • Iterators with for in, buffered streams, and file system calls
  • A checker that reports coded diagnostics, with a JIT for fast runs
  • Ahead of time codegen into a native executable
  • A built-in test runner with describe, expect, --filter and --tag

Being finished

  • The self-hosted compiler: lexer, parser, types, checker, emitter, x86-64 backend and PE linker, all written in PickleScript
  • It has to agree with the reference build byte for byte, and the verification battery was green across all eleven gates at commit 3046166
  • What is left is the switchover: the CLI runs the self-hosted compiler and the reference build comes out

Not there yet

  • No packaged installer, so the workspace is built from source for now
  • await and async are designed but not lowered yet
  • A few shapes type check and then report E0900, "not lowered yet", instead of emitting code

Libraries are published through the PickleScript package registry on this site, with a security scan on every submission. It is a useful tool, and the language itself does not depend on it.

Browse packages

Questions

The things people ask first

Is PickleScript compiled or interpreted?

Both paths end up as machine code. pickle run uses a JIT so you can iterate quickly, and pickle build compiles ahead of time into a native executable. The test battery checks that the two paths agree on every tracked program. The backend that replaces the current one is already written in PickleScript.

Do I have to install a runtime?

No. A PickleScript program builds into a normal executable that runs on its own. The runtime is linked into the binary rather than installed next to it.

How do I handle memory?

The collector handles nearly everything. When you want to own lifetimes yourself, #[manualAlloc] on a class frees its owned fields recursively, and an unsafe block gives you alloc, free and pointer access when you ask for it explicitly.

Is the compiler written in PickleScript?

Yes. The compiler, its x86-64 backend and its PE linker are written in PickleScript. The one thing still to change is which build you get: the shipped CLI runs the reference build until the switchover lands, and that reference build is what goes away when it does.

How do I get PickleScript?

There is no packaged installer yet, so build the workspace from source for now. The documentation walks you through checking, running and building your first file.

Written in the open

Read it, run it, tell us what broke

The compiler, the runtime and this site live on GitHub. Issues, diagnostics that do not make sense and patches are all welcome.

Written in itself

The compiler, the x86-64 backend and the linker are PickleScript.

.pkl

The extension on every PickleScript source file.

pickle test

The built-in runner finds every *_test.pkl in the project.