Guides
Tutorials, how-tos, and in-depth feature guides for Turmeric
Advanced Control Flow
- Backtracking Guide -- Nondeterministic backtracking using the list monad in Turmeric's stdlib/backtrack.tur
- Checkpointing and Persistent Workflows -- Cloneable continuations for persistent workflows and checkpointing
- Effects System Guide -- Algebraic effects, dependency injection, custom control flow
- Logic Programming Guide -- Backtracking, logic programming, constraint solving with cloneable continuations
- Serializable Continuations Guide -- Serializable continuations for persistent workflows and cross-process computation
- tur/logic — Logic Programming Guide -- How to use and extend tur/logic for miniKanren-style relational programming in Turmeric
- Web Continuations Guide -- Compact reference:
send-form-and-wait, continuation store, routing model
Concurrency and Async
- Async/Await Guide -- Async/await with fibers and delimited continuations
- STM Guide -- Software transactional memory -- API reference and mechanics
- Software Transactional Memory (STM) Tutorial -- STM tutorial: concepts, patterns, and worked examples
- Threading and Concurrency Primitives Guide -- OS threads,
Arc<T>,Mutex<T>,Atomic<T>, channels
Concurrency and State
- Dynamic Vars Guide -- Thread-local, dynamically-scoped mutable cells with defdynamic and binding
Data & Libraries
- Frame Guide -- In-memory columnar dataframes with tur-frame -- building, querying, joining, and exporting via the Arrow C Data Interface
Data Structures
- HAMT Guide -- Persistent hash maps with structural sharing (HAMT)
Datalog
- Datalog Tutorial Pt. 1: Concepts -- Create a database and a query system to go with it
- Datalog Tutorial Pt. 2: Minimal Implementation -- Create a database and a query system to go with it
- Datalog Tutorial Pt. 3: Query API -- Create a database and a query system to go with it
- Datalog Tutorial Pt. 4: Indexing -- Create a database and a query system to go with it
Deployment
- Deploying Turmeric Services to Cloudflare -- Three approaches for deploying Turmeric-written services to Cloudflare -- Containers (simplest, works today), Interpreter-in-WASM (portable edge execution), and AOT WASM via emit-c (fastest cold starts).
Error Handling
- Contract Types Guide -- Contract types:
{ x : T | p },:pre/:postannotations, FFI contracts (planned v4) - Error Handling Guide --
Result,Option,panic, contract macros (assert!,require!,ensure!)
Getting Started
- Quickstart -- Prose introduction: expressions, functions, control flow, Option, Result, collections, closures, structs, and algebraic effects
- Releases and Installation -- How to install Turmeric from a prebuilt release or Homebrew, what's in the tarball, and how a maintainer cuts a new release.
- tur repl -- REPL Reference -- Reference guide for the
tur replinteractive read-eval-print loop, covering startup, expression evaluation, meta-commands, and configuration - Interactive REPL Tutorial -- 22-step interactive tutorial to follow at
tur replor the web REPL
Internals
- Compiler Internals -- End-to-end walkthrough of the tur compiler pipeline and source layout in src/, aimed at contributors extending the type system or adding new passes
- Type Erasure to int64_t -- Snapshot of where the tur compiler collapses higher-level types down to int64_t at the C boundary, and the three mechanisms it uses
Language Features
- Advanced Type System -- Design Rationale -- Why Turmeric chose the type system features it did, and why dependent and refinement types were correctly deferred
- Arrows and Signal Processing -- Arrow typeclass, composition operators, and building DSP signal graphs with stdlib/arrow.tur and stdlib/signal/
- C Integration Guide -- Foreign function interface (FFI) and C interop
- CLI Arguments Guide -- Passing arguments to scripts with
*args*and parsing them withstdlib/args.tur - Effects vs. Monads -- Design rationale: why effects instead of Haskell-style monads
- Existential Types -- Existential types: pack/open, typeclass constraints, hiding concrete types behind opaque boundaries
- GADTs Cookbook -- GADTs cookbook: practical patterns and recipes
- GADTs -- A Practical Guide -- GADTs:
defgadt, type refinement, equality witnesses, union types, gradual typing - Generators and Lazy Sequences Guide -- Zero-overhead generators with
gen/yield, lazySeqcombinators, and theRangetype - Higher-Kinded Types -- Higher-kinded types (functor, monad, applicative abstractions, performance/dispatch model)
- Higher-Ranked Types -- Higher-ranked types: rank-2/3 polymorphic function parameters
- Module System Guide -- Module system, namespacing, exports
- Performance Guide -- Writing fast Turmeric programs -- numerical computation, data structures, string processing, concurrency, memory, recursion, I/O, and benchmarking methodology
- Sized Types -- Tracking data-structure sizes in the type system for memory layout, stack allocation, and type-safe array operations (
-Xsized-types) - Structs -- Defining and using struct types with
defstruct - Type Annotation Syntax -- Compound type annotation syntax:
(-> a b),(vec T),forall, and more - Union and Intersection Types Guide -- Union (
A | B) and intersection (A & B) types,any, gradual typing
Package Management
- Consuming Spices Guide -- Adding, fetching, and using spice packages in a Turmeric project
- Developing Spices Guide -- Creating, testing, and publishing Turmeric spice packages
- Package Management Guide (Spice) -- Creating projects, adding spices,
build.tur,tur.lock, CLI reference - Using a Turmeric Library from CMake -- How to publish a Turmeric library for consumption by C and C++ projects via CMake or CPM using
tur emit-cmake
Reference
- Compiler Flags -- All -X feature flags and diagnostic flags: status, what each enables, dependency graph, and common combinations
- libturi -- C Embedding API Reference -- C embedding API for evaluating Turmeric expressions and calling Turmeric functions from within a C program using libturi.a
- Quickstart & Interactive REPL Tutorial Plan -- Authoring plan and step outline for the quickstart.md prose guide and repl-tutorial.md 22-step interactive tutorial
- Reader Forms Reference -- Complete reference for every syntactic form the Turmeric reader recognises -- comments, literals, collections, prefix macros, and reader extensions
- Sandboxing Guide -- Running untrusted Turmeric code safely inside a C host using turi_env_new_sandboxed, capability flags, and resource limits
- Test Runner Contract -- Test framework API and contract
Tools and IDE
- Dev Container -- Running Turmeric development in a devcontainer from VS Code or the CLI
- Formatter Guide --
tur formatCLI and web REPL Format button - Language Server (LSP) Guide -- Configuring editors to use the Turmeric language server for diagnostics
- Vim Guide -- Vim / Neovim syntax highlighting installation and configuration
- VS Code Extension -- VS Code extension installation and configuration
Tutorials and Examples
- Cellular Automata with Comonads -- Cellular automata with comonads
- Custom Effects Tutorial -- Writing custom effects
- "MiniKanren Part 1: Relations and Queries" -- Logic programming with miniKanren -- relations, composition, and bidirectional queries
- Snake Game Tutorial -- Building the snake game example
- Web Continuations Tutorial -- Multi-page web forms using serializable continuations (guestbook example)
- Building for the Web with Emscripten -- Compile a Turmeric project to WebAssembly and run it in a browser
Tutorials and Examples (Plan)
- "MiniKanren Part 2: Core Operators -- Plan" -- Plan for the second miniKanren tutorial -- implementing ==, fresh, conde, run, and constraints in Turmeric
Type Safety
- Substructural Types --
^linear,^affine,^relevanttype disciplines - Uniqueness Types --
^unique: at-most-one-reference ownership
Other
- Bibliography --
- Notebook Guide --
- Range Reader Plan --
- Session Types Guide -- Model protocols as types, whether the protocol has two participants, or more
- Sized Primitives Guide --
- State Machines Guide -- Five different approaches to modeling state machines in turmeric
- Stats Guide --
- Style Guide --