Documentation
Build with PickleScript.
Language guides, package workflows, and reference material for version latest.
01
Getting Started
Build the toolchain, run your first program and learn the day-to-day workflow.
Editor integrationDrive your editor from pickle-cli check --json, the supported integration point.What is PickleScript?A native, garbage-collected language with C-family syntax, and an honest look at where the toolchain stands today.Installing PickleScriptDownload a prebuilt pickle-cli for Linux or Windows, or build it from source.The workspace manifestWhat picklescript.toml does today, and what it reserves for the future.QuickstartWrite, check and run your first PickleScript program.Running programsChecking, running, and testing a program with pickle-cli.Writing and running testsThe test fn declaration, the expect assertion vocabulary, grouping and hooks.
02
Language Guide
The syntax, type system and semantics of the language, as implemented today.
Builtin functionsEvery function available without importing, from print and len to files, processes and streams.ClassesReference types with fields, constructors, methods, inheritance, properties and interfaces.Lists and mapsList and map literals, built-in methods, reference semantics, and how to build an empty collection.Control flowif, while, for, ranges, break, continue and exhaustive pattern matching.EnumsSimple and payload-carrying enum cases, with exhaustive pattern matching.Error handlingOptionals, exceptions, exit codes and compile-time errors: which failure mechanism to reach for, and when each one is fatal.FunctionsDeclaring functions, return values, tuples, closures, function types and recursion.Generics and interfacesType parameters, invariance, interfaces and type tests.Modules and importsModule declarations, import forms, workspace crates and the filesystem resolution order.Language overviewThe overall design of PickleScript: a C-family, declaration-oriented, garbage-collected language.Pattern matchingmatch and case, binding patterns, exhaustiveness, and why there is no if let.StringsString literals, escapes, interpolation, and the fact that there are no string methods.StructsAggregate types with reference semantics, and how they differ from classes.Values and typesEvery primitive type PickleScript has, and the conversions that actually work.Variables and constantslet, var and const, how bindings are declared, scoped and reassigned.
03
Standard Library
Builtin functions plus the std modules for text, collections, I/O, files, JSON, processes and threads.
Collections in the standard librarySets, deques, stacks, queues, ordered maps and priority queues, all built around a prototype value.Files and pathsstd.fs and the file builtins, reading, writing, directories and streams.JSONstd.json, a recursive Json enum with a hand-written parser and serialiser, and the string-literal rule you need to use it.Standard library overviewThe modules that ship with PickleScript and what each one does.Processes and the environmentstd.process, running subprocesses with a builder API, plus argv and working-directory helpers.Threads and concurrencystd.thread, tasks, channels, mutexes, condition variables, semaphores and atomics.Text processingstd.text, padding, slicing, searching and hex conversion, because strings have no methods.
04
Advanced
Manual memory, concurrency, debugging and the self-hosted compiler.
ConcurrencyThreads, shared memory, and the synchronisation primitives.DebuggingThe commands that actually help, and how to read a diagnostic.Manual Memory and unsafeRaw pointers, the unsafe block, and the ownership rules the checker enforces.Memory ModelWhat the collector does, which values are references, and which are copied.
05
Contributors
How the toolchain is put together, and how to work on it.
BackendsThe JIT and the ahead-of-time path, and where each one puts the machine code.Contributing to the CompilerHow to work on the compiler, and what a good change looks like.PerformanceHow the x86-64 backend generates code, and where the time goes.PickleIRThe typed, block-structured IR the backend consumes, with real output.The Compilation PipelineWhat happens between a .pkl file and machine code, phase by phase.
