← Back to home

Categories

Language

Ecosystem

Community

Guides

Tutorials, how-tos, and in-depth feature guides for Turmeric

Advanced Control Flow

Advanced Types

  • Advanced Type System -- Design Rationale -- Why Turmeric chose the type system features it did, and why dependent and refinement types were correctly deferred
  • 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
  • Opaque Types (defopaque) -- Named nominal newtypes over a representation type -- what they are, what they're for, and how to construct, unwrap, and combine them with substructural disciplines

CLI Tools

  • Autodoc Guide -- Writing ;;; docstrings and generating API docs with tools/gendocs.py
  • Compiler Flags -- Diagnostic and debug flags accepted by tur; list of removed -X feature flags
  • Experimental Feature Flags -- The --enable=<name> surface for genuinely in-flight compiler features, the two lifecycles, the TUR-W006x warnings, and the tur experiments command.
  • Application Image Dumps -- Warm-start a Turmeric program by saving and restoring a post-init continuation, Lisp/Smalltalk/pdumper style.
  • Test Runner Contract -- Test framework API and contract
  • Tur New Guide -- Scaffold a new Turmeric spice (library or binary) with standard layout, build manifest, tests, and optional CI
  • Tur Run Guide -- Built-in Justfile-compatible task runner for building, testing, and managing Turmeric projects without installing just
  • tur-watch Guide -- Cross-platform filesystem watching with debounce and coalescing for CLI tools
  • Turmeric Version Manager (tvm) -- Install, switch between, and pin Turmeric compiler releases the same way nvm does for Node -- per-user, no root, no system package manager.

Compiler 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
  • Garbage Collection -- How memory is managed in Turmeric -- reference counting, the Bacon-Rajan cycle collector, arenas, and what is (and isn't) GC-managed in the compiled and interpreted paths
  • Name Mangling Guide -- How Turmeric turns source names into valid C identifiers -- the injective scheme, the legacy fold, and when each applies.
  • turi <-> tur Parity Guide -- Feature-by-feature parity matrix between the compiled Turmeric path (tur) and the tree-walking interpreter (turi), the documented carve-outs, and how to check whether a given feature is interpretable.
  • 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
  • Typeclass Dictionary Internals -- How definstance lowers to a C dictionary struct + singleton, how method-field C types are resolved, and the closure-handle convention for methods whose return type is itself a function.

Concurrency and Async

Contributor

Data Structures and Libraries

  • ECS Guide -- Building games and simulations with tur-ecs and the tur-ecs-raylib companion -- components, queries, systems, the row-typed Query value, and the standard 2D rendering loop.
  • ECS Storage Guide -- Dense, Sparse, Tag -- How tur-ecs's three component-storage backends -- Dense, Sparse, Tag -- differ in layout, cost, and ergonomics; when to pick each; how StorageOps unifies them; and how the Sized* variants thread a capacity through the type.
  • ECS -- tur-ecs vs apecs vs aztecs -- A side-by-side walk through a small game in apecs (Haskell), aztecs (Haskell), and tur-ecs (Turmeric), tabulating what each system catches at compile time vs. runtime, what each gives up to get there, and where the trade-offs actually land.
  • Frame Guide -- In-memory columnar dataframes with tur-frame -- building, querying, joining, and exporting via the Arrow C Data Interface
  • HAMT Guide -- Persistent hash maps with structural sharing (HAMT)
  • JSON Guide -- Compile-time #json(...) reader macro and runtime tur/json library for parsing and serializing JSON
  • Runtime Schema Validation -- Validate untyped boundary data (HTTP bodies, config, IPC) with composable schema values using stdlib/schema.tur, with accumulating, path-tagged errors.
  • tur-stats Guide -- Statistics spice for Turmeric -- descriptive stats, probability distributions, hypothesis tests, OLS regression, and resampling on dataframes

Editor and IDE

  • AI Assistant Integration Guide -- Using the Turmeric MCP server and LSP with Copilot CLI, Claude CLI, OpenCode, and VS Code Copilot
  • Dev Container -- Running Turmeric development in a devcontainer from VS Code or the CLI
  • Formatter Guide -- tur format CLI and web REPL Format button
  • Language Server (LSP) Guide -- Configuring editors to use the Turmeric language server for diagnostics
  • Notebook Guide -- Literate-programming .tur.md notebooks with tur-notebook -- TUI interface, HTML export, and scripted exec mode
  • Vim Guide -- Vim / Neovim syntax highlighting installation and configuration
  • VS Code Extension -- VS Code extension installation and configuration

Error Handling

Functional Patterns

Getting Started

  • Quickstart -- Prose introduction: expressions, functions, control flow, Option, Result, collections, closures, structs, and algebraic effects
  • Quickstart & Interactive REPL Tutorial Plan -- Authoring plan and step outline for the quickstart.md prose guide and repl-tutorial.md 22-step interactive tutorial
  • 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 repl interactive read-eval-print loop, covering startup, expression evaluation, meta-commands, and configuration
  • Interactive REPL Tutorial -- 22-step interactive tutorial to follow at tur repl or the web REPL
  • Syntax Guide -- How to read and write Turmeric -- s-expression and sweet-expression syntax

Integration / Godot

Interoperability

  • C Integration Guide -- Foreign function interface (FFI) and C interop
  • libturi -- C Embedding API Reference -- C embedding API for evaluating Turmeric expressions and calling Turmeric functions from within a C program using libturi.a
  • Returning Result / Option from Inline-C -- Build typed Result/Option values inside inline-C bodies with the preamble helpers (tur_ok_ptr, tur_err_int, tur_some_ptr, tur_none, ...) instead of hand-rolling the struct or returning a magic-sentinel :int
  • Sandboxing Guide -- Running untrusted Turmeric code safely inside a C host using turi_env_new_sandboxed, capability flags, and resource limits

Language Basics

  • Binding Forms Guide -- Internal define, letrec, and named-let -- the three local binding idioms that complement let and defn
  • CLI Arguments Guide -- Passing arguments to scripts with *args* and parsing them with stdlib/args.tur
  • Currying Guide -- Haskell-style partial application and over-application of Turmeric functions
  • Data Literals Guide -- Compact literal syntax for maps, vecs, and sets using #map{...}, #set{...}, and [...]
  • Fat-Closure Annotation Guide (^fat) -- When and why to mark function-typed parameters and return positions ^fat, and what breaks without it
  • Function Arity Style Guide -- When to use positional parameters, defstruct options, and variadic rest parameters -- plus the rules governing each
  • Module System Guide -- Module system, namespacing, exports
  • Range Reader Shorthand Plan -- Plan for #r{...} reader-level range shorthand (RR0-RR4) -- desugars to Range constructor calls at read time
  • Reader Forms Reference -- Complete reference for every syntactic form the Turmeric reader recognises -- comments, literals, collections, prefix macros, and reader extensions
  • Structs -- Defining and using struct types with defstruct
  • Sum Types and Either -- Declaring binary and n-ary sum types with defdata, pattern matching with match, exhaustiveness behaviour and the #fx{NonExhaustive} opt-out, the FFI layout, and the stdlib Either module.
  • Symbols Guide -- First-class runtime symbols (:Sym type) with compile-time interning and optional dynamic str->sym table
  • Typing Handles, Callbacks, and Results -- Avoiding :int Stand-Ins -- How to type opaque handles, callbacks, and option/result values properly in Turmeric. Concrete patterns and fix recipes drawn from the 2026-06-14 spice ecosystem audit.

Networking and Web

  • 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).
  • HTTPD Async Guide -- Run handlers as fibers on a reactor thread -- non-blocking I/O, await primitives, in-flight cap, and middleware interop
  • HTTP Server with stdlib/httpd -- Build HTTP/1.1 servers with stdlib/httpd -- handlers, routing, middleware, and keep-alive
  • HTTP Middleware Catalog (stdlib/httpd) -- Reference for the shipped httpd middleware -- logging, CORS, basic auth, JSON, cookies, multipart, body-size, rate-limit, static files -- plus the request-attribute side channel and the composition helpers.
  • HTTPS with stdlib/httpd + tur-tls -- How to terminate TLS on an httpd-new server using the tur-tls spice
  • Tourist Routing Composition -- Compose tur-tourist HTTP sub-apps with mount and prefix combinators for larger applications
  • Tourist Session Middleware -- Cookie-backed sessions for tur-tourist with swappable storage backends (memory, file)
  • Web Stack Guide -- Building HTTP servers with tur-httpd, tur-template, and tur-tourist -- the composable web stack for Turmeric
  • WebSockets -- Build RFC 6455 WebSocket clients and servers in Turmeric with the tur-ws-client and tur-ws-server spices

Package Management

Performance

  • Monomorphization ABI Guide -- How Turmeric's end-to-end monomorphization ABI works, why the by-value path replaced the int64 carrier, how to read __spec_* symbols in error messages, and what the small residual ABI bridge does.
  • Performance Guide -- Writing fast Turmeric programs -- numerical computation, data structures, string processing, concurrency, memory, recursion, I/O, and benchmarking methodology

Reference

  • Bibliography -- Academic papers, theses, and technical references cited across Turmeric design documents and guides
  • Turmeric Style Guide -- Canonical idioms and formatting conventions for Turmeric code -- function arity, indentation, naming, and inline-C style

Standard Library

  • Lens Guide -- First-class functional lenses (view / set / over) via stdlib/lens.tur, the profunctor-by-record encoding shipped by default, and the van Laarhoven form -- now always-on, no experiment flags required.

Tutorials

Type Safety

Type System

  • 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
  • Approaches to Polymorphism -- A tour of the polymorphism mechanisms Turmeric provides -- parametric, ad-hoc, structural, row, kind, rank, and substructural -- with guidance on which one to reach for
  • Sized Primitive Types -- Fixed-width numeric types (int8/i8 through uint64/u64, float32/f32) -- literal syntax, coercion rules, and casting
  • Sized Types -- Tracking data-structure sizes in the type system for memory layout, stack allocation, and type-safe array operations
  • Type Annotation Syntax -- Compound type annotation syntax: (-> a b), (vec T), forall, and more
  • Typeclass Guide -- Comprehensive guide to Turmeric's typeclass system -- defining typeclasses with defclass, implementing instances with definstance, constraints, associated types, functional dependencies, and default implementations.
  • Union and Intersection Types Guide -- Union (A | B) and intersection (A & B) types, any, gradual typing