Tinsel Documentation Hub

Welcome to Tinsel, an expression-oriented programming language implemented in Go and purpose-built for algorithmic puzzles, competitive programming, and Advent of Code.

Tinsel pairs a fast, zero-dependency bytecode virtual machine with first-class primitives for the problems that dominate algorithmic competitions: 2D/3D spatial geometry, contiguous character grids, canonical interval set algebra, declarative graph search, periodicity detection across trillions of steps, and regex-free pattern ingestion.

Documentation Structure

Our documentation is organized around four pillars so you can quickly find what you need:

5-Minute Quickstart

1. Build the Single Binary

Tinsel is written in pure Go using only the Go standard library (zero external runtime dependencies):

# Build the standalone binary
go build -o bin/tinsel ./cmd/tinsel

# Verify the test suite
go test -v -count=1 ./...

2. Evaluate Expressions On the Fly (eval)

Use tinsel eval (or -e) for instant one-liners:

./bin/tinsel eval "vec2(10, 20) <-> vec2(15, 32)"
# Output: 17

./bin/tinsel eval '"Sensor at x=12, y=-8".ints().sum()'
# Output: 4

3. Run Tinsel Scripts (run)

Create a script or run any example in examples/:

# Run the interactive language tour script
./bin/tinsel run examples/language_tour.tin

# Run an entire directory of puzzle solutions in batch mode
./bin/tinsel examples/aoc2025/

Pass extra arguments after the script name to populate the global args array:

./bin/tinsel run examples/solve_with_file.tin examples/sample_puzzle_input.txt

4. Interactive REPL

Launch tinsel with no arguments for an interactive session with multi-line block support:

$ ./bin/tinsel
Tinsel REPL (type 'exit' or Ctrl+D to quit)
tinsel> let origin = vec2(0, 0)
tinsel> origin <-> vec2(3, 4)
7
tinsel> exit

5. Interactive Web Playground & Live Debugger (play & debug)

Launch the browser-based Tinsel Playground (with syntax-highlighted editor, bundled examples, custom input.txt pane, -O vs -O0 bytecode comparison, and runnable documentation snippets) or step through code in the Web Inspector:

# Launch the interactive Web Playground & Docs server (http://127.0.0.1:8080)
./bin/tinsel play

# Launch the browser-based Web Inspector paused at line 1 (http://127.0.0.1:4040)
./bin/tinsel debug examples/aoc2024_day16.tin

# Or use the terminal CLI debugger (tdb)
./bin/tinsel debug --cli examples/aoc2023_day1.tin

6. Static Checking, Testing & HTML Docs

# Statically verify syntax and variable mutability without executing
./bin/tinsel check examples/ tests/

# Run all .tin test suites (optionally with line/function/branch coverage)
./bin/tinsel test
./bin/tinsel test --cover --cover-func --cover-html=coverage.html

# Rebuild the static HTML documentation site in docs/html/
./bin/tinsel doc

Step-by-Step Tutorial Syllabus

New to Tinsel? Start with the 15-Minute Language Tour for a high-level overview, then work through the 8-lesson tutorial course:

Comprehensive Examples & Technical Reference

• Algorithmic Cookbook & Idioms: 10 self-contained recipes for flood fill, weighted maze search, Shoelace + Pick's theorem, Chinese Remainder Theorem, Cramer's rule, memoized recursion, Kruskal's DSU, combinatorics, lazy infinite streams, and bitwise/BigInt logic.
• Canonical AoC Walkthroughs: Deep-dive problem statements and complete runnable solutions across 6 Advent of Code problem archetypes, plus an index of all scripts in examples/.
• Syntax, Grammar & Types Reference: Formal lexical rules, operator precedence, runtime types, pattern matching, struct & __proto__ metamethods, modules, and EBNF grammar.
• Global Built-ins & Receiver Methods: Complete catalog of global functions (std/prelude and VM intrinsics) and dot-methods organized by receiver type.
• Standard Library Modules (std/*): Module-by-module API reference for all embedded pure-Tinsel libraries.
• CLI & Debugger Reference: Command-line flags, Web Inspector IDE guide, and tdb terminal commands.
• Compiler & VM Architecture: Tagged 24-byte Value representation, AST/bytecode optimizer passes, and full VM opcode tables.