git clone --recurse-submodules https://github.com/ormastes/simple.git
cd simple
export PATH="$PWD/bin:$PATH"
simple --version

git submodule sync --recursive
git submodule update --init --recursive

scripts/setup/setup.shs
bin/simple build bootstrap

src/compiler_rust/target/bootstrap/simple --version
bin/simple build bootstrap
sha256sum bootstrap/simple_stage2 bootstrap/simple_stage3

simple build --release --features=vulkan

# hello.spl
>>> fn main() -> i64:
...     0  # Entry point, returns exit code

# Run it
simple hello.spl
echo $?  # Prints: 0

Usage:
  simple                      Start interactive REPL
  simple <file.spl>           Run source file
  simple <file.smf>           Run compiled binary
  simple -c "code"            Run code string; statement snippets print only program output
  simple compile <src> [-o <out>]  Compile to SMF
  simple watch <file.spl>     Watch and auto-recompile

Build System (Self-Hosting):
  simple build                Build the project (debug)
  simple build --release      Release build (optimized)
  simple build --bootstrap    Bootstrap build (minimal 9.3MB)
  simple build test           Run all tests
  simple build coverage       Generate coverage reports
  simple build lint           Run linter (clippy)
  simple build fmt            Format code (rustfmt)
  simple build check          Run all quality checks
  simple build clean          Clean build artifacts
  simple build --help         Show all build options

Options:
  -h, --help     Show help
  -v, --version  Show version
  -c <code>      Run code string
  --gc-log       Enable verbose GC logging
  --gc=off       Disable garbage collection

# Interactive REPL
simple
>>> 1 + 2
3
>>> x = 10
>>> x * 5
50
>>> exit

# Run a program
echo "main = 42" > hello.spl
simple hello.spl
echo $?  # Exit code: 42

# Compile to binary
simple compile hello.spl
simple hello.smf  # Run the compiled binary

# Watch mode (auto-recompile on changes)
simple watch app.spl

# Variables - immutable by default, mutable with var
>>> x = 10
>>> x
10
>>> var y = 20
>>> y
20
>>> PI = 3.14159
>>> PI
3.14159

# Type inference works automatically
>>> count = 100
>>> count
100

# Basic types inferred
>>> a = 42
>>> a
42
>>> pi = 3.14159
>>> flag = true
>>> flag
true

# String interpolation default
>>> name = "world"
>>> msg = "Hello, {name}!"
>>> print msg
Hello, world!

# If/else with indentation
>>> var x = 5
>>> if x > 0:
...     print "positive"
... elif x < 0:
...     print "negative"
... else:
...     print "zero"
positive

# Loops
>>> for i in 0..3:
...     print i
0
1
2

>>> while x > 3:
...     x = x - 1
>>> x
3

>>> fn add(a: i64, b: i64) -> i64:
...     a + b  # Implicit return

>>> fn greet(greeting: text):
...     print "Hello, {greeting}!"

# Function calls
>>> sum = add(1, 2)
>>> sum
3
>>> greet("Alice")
Hello, Alice!

# Lambdas with backslash
>>> double = \x: x * 2
>>> nums = [1, 2, 3, 4, 5]
>>> evens = nums.filter(\x: x % 2 == 0)
>>> evens
[2, 4]

# Structs (value types)
struct Point:
    x: f64
    y: f64

p = Point(x: 1.0, y: 2.0)

# Classes (reference types)
class Person:
    name: text
    age: i64

    fn greet():
        print "Hi, {self.name}!"

alice = Person(name: "Alice", age: 30)
alice.greet()

# Arrays - short form (no val)
>>> nums = [1, 2, 3, 4, 5]
>>> first = nums[0]
>>> first
1

# Collection methods
>>> count = nums.len()
>>> count
5

# Dictionary (short form)
>>> scores = {"alice": 100, "bob": 85}
>>> alice_score = scores["alice"]
>>> alice_score
100

# Filter with lambda
>>> odds = nums.filter(\x: x % 2 == 1)
>>> odds
[1, 3, 5]
>>> big_nums = nums.filter(\x: x > 3)
>>> big_nums
[4, 5]

# Tuples
>>> pair = (1, "hello")
>>> num = pair.0
>>> num
1
>>> msg = pair.1
>>> msg
"hello"

# List comprehensions
>>> squared = [x * x for x in 0..5]
>>> squared
[0, 1, 4, 9, 16]
>>> evens = [x for x in nums if x % 2 == 0]
>>> evens
[2, 4]

# Define measurement unit families with postfix syntax
unit length(base: f64):
    mm = 0.001, cm = 0.01, m = 1.0, km = 1000.0

unit velocity(base: f64) = length / time:
    mps = 1.0, kmph = 0.2777777777777778, mph = 0.44704
# The standards-backed catalog records km/h canonically as kilometre / hour
# with exact factor 5/18 relative to m/s.

# Define nominal wrappers with postfix syntax
newunit UserId: i64 as uid
newunit OrderId: i64 as oid

# Usage with postfix literals
height = 175_cm              # Length type
width = 10_cm + 5_mm         # Auto-converts to same base
speed = 200_kmph             # Velocity type
distance = 42_km             # Length type

# Type safety - compile error:
# bad = height + speed       # Error: can't add Length + Velocity

# Semantic IDs prevent mix-ups
user = 42_uid                # UserId
order = 100_oid              # OrderId
# wrong: UserId = 100_oid    # Error: OrderId ≠ UserId

# Computed units
travel_time = distance / speed    # Returns Time type
print("ETA: {travel_time.to_min()} minutes")

enum Shape:
    Circle(radius: f64)
    Rectangle(width: f64, height: f64)
    Square(side: f64)
    Triangle(base: f64, height: f64)

# Pattern matching with case syntax
fn area(s: Shape) -> f64:
    match s:
        case Circle(r):
            3.14159 * r * r  # Implicit return
        case Rectangle(w, h):
            w * h
        case Square(side):
            side * side
        case Triangle(b, h):
            0.5 * b * h

# Preferred arrow syntax (shorter)
fn perimeter(s: Shape) -> f64:
    match s:
        | Circle(r) -> 2.0 * 3.14159 * r
        | Rectangle(w, h) -> 2.0 * (w + h)
        | Square(side) -> 4.0 * side
        | Triangle(a, b, c) -> a + b + c

# Pattern matching with nil (not None)
fn get_radius(opt: Option<f64>) -> f64:
    match opt:
        | Some(r) -> r
        | nil -> 0.0  # Use nil instead of None

# Macro declares what it introduces in the contract header
macro define_counter(NAME: Str const) -> (
  returns result: (init: Int, step: Int),
  intro counter_fn: enclosing.class.fn "{NAME}Counter"(start: Int) -> Int
):
  const_eval:
    const init = 0
    const step = 1

  emit counter_fn:
    fn "{NAME}Counter"(start: Int) -> Int:
      start + step

# Usage - IDE knows about UserCounter before expansion
class Demo:
  define_counter!("User")

  fn run() -> Int:
    self.UserCounter(10)  # Autocomplete works!

# Print with formatting
println!("Hello, {name}!")           # Print with newline
print!("Value: {x}")                 # Print without newline

# Debug output with source location
dbg!(expression)                     # Prints: [file:line] expression = value

# Assertions
assert!(condition)                   # Panic if false
assert_eq!(a, b)                     # Panic if a != b
assert_ne!(a, b)                     # Panic if a == b

# Collections
nums = vec![1, 2, 3, 4, 5]           # Create vector
formatted = format!("x={x}")         # Format string without printing

# Panic with message
panic!("Something went wrong: {err}")

# Generate accessor functions for each axis
macro gen_axes(BASE: Str const, N: Int const) -> (
  intro axes:
    for i in 0 .. N:
      enclosing.class.fn "{BASE}{i}"(v: Vec[N]) -> Int
):
  emit axes:
    for i in 0 .. N:
      fn "{BASE}{i}"(v: Vec[N]) -> Int:
        v[i]

# Usage: generates x(), y(), z() accessors
class Point3D:
  gen_axes!("axis_", 3)  # Creates axis_0, axis_1, axis_2

# Before advice — runs before matching functions
on pc{ execution(* handle_request(..)) } use log_entry before priority 10

# After advice — runs after successful return
on pc{ execution(* save(..)) & attr(audited) } use audit_write after_success priority 20

# Around advice — wraps function with proceed() contract
on pc{ within(services.*) } use trace_around around priority 50

# Architecture rules — enforce layer dependencies at compile time
forbid pc{ within(hal.*) } "HAL cannot depend on services"
allow  pc{ within(services.*) } "Services can use HAL"

# app.sdn - Application configuration
app:
    name: MyService
    version: 2.1.0

server:
    host: 0.0.0.0
    port: 8080
    workers: 4

# Inline arrays and dicts
features = [auth, logging, metrics]
database = {driver: postgres, host: localhost, port: 5432}

# Named tables - compact tabular data
rate_limits |endpoint, requests, window|
    /api/login, 5, 60
    /api/search, 100, 60
    /api/upload, 10, 300

config = sdn::load("app.sdn")
print("Server port: {config.server.port}")

>>> factorial(5)
120
>>> factorial(0)
1

## Stack data structure with LIFO semantics
struct Stack:
    items: [i64]

var s = Stack(items: [])
s.items.push(1)
s.items.push(2)
print s.items.len()  # 2

simple test --sdoctest README.md      # Run verified examples in Markdown/docs
simple test --spl-doctest src/math.spl # Run file-local source-comment doctests
simple test --sdoctest --tag slow     # Filter by tag

# The -> operator calls a method and assigns result back
var data = load_data()
data->normalize()        # data = data.normalize()
data->filter(min: 0)     # data = data.filter(min: 0)

# Chaining
data->normalize()->filter(min: 0)->save("out.txt")

import std.gpu

# GPU kernel style 1: #[gpu] with explicit bounds check
#[gpu]
fn vector_add_kernel(a: []f32, b: []f32, result: []f32):
    idx = gpu.global_id(0)           # Global thread index
    if idx < len(result):
        result[idx] = a[idx] + b[idx]

# GPU kernel style 2: @simd with auto bounds handling
@simd
fn vector_scale(data: []f32, scale: f32):
    val i = this.index()             # Global linear index (same as gpu.global_id())
    data[i] = data[i] * scale        # Bounds auto-handled

# Host function - runs on CPU
fn main():
    device = gpu.Device()

    # Allocate and upload data
    a = [1.0, 2.0, 3.0, 4.0]
    b = [5.0, 6.0, 7.0, 8.0]

    buf_a = device.alloc_buffer(a)
    buf_b = device.alloc_buffer(b)
    buf_result = device.alloc_buffer<f32>(4)

    # Launch kernel
    device.launch_1d(vector_add_kernel, [buf_a, buf_b, buf_result], 4)

    # Download results
    device.sync()
    result = device.download(buf_result)
    # result = [6.0, 8.0, 10.0, 12.0]

#[gpu]
fn matrix_multiply(A: []f32, B: []f32, C: []f32, N: u32):
    # Multi-dimensional indexing
    val row = gpu.global_id(0)       # First dimension
    val col = gpu.global_id(1)       # Second dimension

    # Thread group (workgroup) info
    val local_row = gpu.local_id(0)  # Index within workgroup
    val group_row = gpu.group_id(0)  # Workgroup index

    # Alternative @simd style
    # val(row, col) = this.index()  # Tuple for 2D
    # vallocal_idx = this.thread_index()
    # valgroup_idx = this.group_index()

    if row < N and col < N:
        var sum = 0.0_f32
        for k in 0..N:
            sum += A[row * N + k] * B[k * N + col]
        C[row * N + col] = sum

# XOR neural network training
bin/simple examples/pure_nn/xor_training_example.spl

# Linear regression (learns y = 2x + 1)
bin/simple examples/pure_nn/simple_regression.spl

# Iris flower classification
bin/simple examples/pure_nn/iris_classification.spl

# Progressive LoRA training to prevent catastrophic forgetting
bin/simple examples/medgemma_korean/run_all.spl

# Direct CUDA C API - multi-GPU, streams, events
bin/simple examples/cuda/basic.spl

bin/simple examples/cli_demo.spl

use std.spec.{describe, expect, it, step}

describe "Code action picker":
  it "selects and applies the requested repair":
    # @req REQ-EDITOR-CODE-ACTION-001
    val actions = [
      ["First fix", "Rename first now"],
      ["Second fix", "Rename second now"]
    ]
    step("Open the Code Actions menu")
    step("Select \"Second fix\"")
    val selected_index = 1
    step("Press Enter to apply the selected action")
    expect(actions[selected_index][0]).to_equal("Second fix")
    expect(actions[selected_index][1]).to_equal("Rename second now")

1. Open the Code Actions menu
2. Select "Second fix"
3. Press Enter to apply the selected action

use std.spec.{describe, expect, it, step}
use app.dashboard.render.table.{render_html_table}

describe "Artifact verification table":
  it "renders each artifact result as a table row":
    val headers = ["Artifact", "Integrity", "Status"]
    val rows = [
      ["firmware.bin", "sha256", "passed"],
      ["policy.sdn", "signature", "blocked"]
    ]
    step("Render the artifact verification table")
    val html = render_html_table(headers, rows)
    step("Verify the blocked policy result remains visible")
    expect(html).to_contain("policy.sdn")
    expect(html).to_contain("blocked")

Artifact     | Integrity | Status
firmware.bin | sha256    | passed
policy.sdn   | signature | blocked

# Top-level
program ::= statement*

# Statements
statement ::= function_def | class_def | struct_def | enum_def
            | import_stmt | export_stmt | expr_stmt

# Expressions (Pratt parser)
expr ::= literal | identifier | binary_op | unary_op
       | call | index | field_access | lambda
       | if_expr | match_expr | block

# Types
type ::= identifier | array_type | tuple_type | fn_type
       | optional_type | result_type | generic_type

# Literals
literal ::= integer | float | string | bool | array | dict | tuple

simple/
├── bin/                      # CLI wrappers and admitted binaries
│   ├── simple                # Main CLI
│   └── release/              # Release binaries by target
│
├── src/                      # Product source
│   ├── app/                  # CLI, build, MCP, LSP, test runner, tools
│   ├── compiler/             # Numbered compiler layers
│   │   ├── 00.common/        # Shared compiler contracts and cache keys
│   │   ├── 10.frontend/      # Lexer, parser, AST, desugaring
│   │   ├── 50.mir/           # Lowered intermediate representation
│   │   ├── 70.backend/       # Native, LLVM, C, WASM, and linker backends
│   │   ├── 80.driver/        # Build driver and incremental cache
│   │   │   └── cache/reference/ # Reverse-reference scheduling and receipts
│   │   ├── 95.interp/        # Interpreter execution layer
│   │   └── 99.loader/        # Module resolution, loading, and JIT instantiation
│   ├── compiler_rust/        # Rust seed bootstrap compiler
│   ├── lib/                  # Standard library, imported as use std.X
│   ├── runtime/              # Native runtime and support libraries
│   └── verification/         # Formal verification
│
├── test/                     # Executable specifications
│   ├── 01_unit/              # Unit tests
│   ├── 02_integration/       # Integration tests
│   ├── 03_system/            # System and feature tests
│   ├── 04_smoke/             # Fast product smoke tests
│   └── 05_perf/              # Performance tests
│
├── doc/                      # Numbered lifecycle documentation
│   ├── 01_research/          # Research
│   ├── 02_requirements/      # Requirements
│   ├── 03_plan/              # Plans
│   ├── 04_architecture/      # Architecture
│   ├── 05_design/            # Detail design
│   ├── 06_spec/              # Generated/manual SSpec documents
│   └── 07_guide/             # User and contributor guides
│
├── .scv/quarantine/          # Ignored local SCV/JIT/root artifacts
└── build/                    # Ignored output, bootstrap artifacts, and scratchpad probes

# Debug build
simple build

# Release build
simple build --release

# With GPU support
simple build --release --features=vulkan

# Bootstrap build (minimal 9.3MB)
simple build --bootstrap

# All tests (4,067 tests in 17.4 seconds)
simple test

# Run specific test file
simple test path/to/spec.spl

# With verbose output
simple test --verbose

# Coverage reports
simple build coverage

# Check before commit (fmt + lint + test)
simple build check

# Full check (includes coverage + duplication)
simple build check --full

# Format code
simple build fmt

# Lint
simple build lint

# From a repo checkout — register with Claude Code
claude mcp add simple-mcp -- \
  /absolute/path/to/simple/bin/simple \
  /absolute/path/to/simple/src/app/mcp/main.spl

# Or use the project .mcp.json (auto-detected by Claude Code)
sh config/mcp/install.shs

claude plugin marketplace add tools/claude-plugin/marketplace
claude plugin install simple-mcp@simple-local

# From a repo checkout
claude plugin marketplace add tools/claude-plugin/marketplace
claude plugin install simple-lsp@simple-local

cd /path/to/simple

# 1. MCP server
sh config/mcp/install.shs

# 2. LSP plugin
claude plugin marketplace add tools/claude-plugin/marketplace
claude plugin install simple-lsp@simple-local

> "Run the linter on src/app/cli/main.spl and fix any warnings"

> "Show me all unused variables in the compiler frontend"

> "Run the unit tests for the SDN parser"

> "Build the project in release mode and show the result"

> "What does the function `parse_expression` in the parser do?"

> "Find all TODO items in the codebase"

> "Check the doc coverage for the standard library"

> "Debug why test/01_unit/lib/common/value_spec.spl is failing"

cd src/app/vscode_extension
npm install && npm run compile && npm run package
code --install-extension simple-language-0.1.0.vsix

-- lazy.nvim
{ "nicholasgasior/simple.nvim", ft = "simple", opts = {} }

-- Or from project checkout
vim.opt.rtp:prepend("/path/to/simple/src/app/nvim_plugin")
require("simple").setup()

scripts/t32q.shs build
scripts/t32q.shs on
scripts/t32q.shs wait
scripts/t32q.shs ping
scripts/t32q.shs reopen
scripts/t32q.shs off

scripts/t32q.shs gui-on
scripts/t32q.shs gui-reopen
scripts/t32q.shs off

scripts/t32q.shs doctor

scripts/t32_semihost_hello.shs --board stm32wb
scripts/t32_semihost_hello.shs --board stm32h7
scripts/t32_semihost_hello.shs --board stm32wb --build-only

cd /path/to/simple

# T32 MCP — controls live TRACE32 debug sessions (23 tools)
claude mcp add t32-mcp -- \
  /absolute/path/to/simple/bin/simple \
  /absolute/path/to/simple/examples/10_tooling/trace32_tools/t32_mcp/main.spl

# T32 LSP MCP — CMM script analysis, no hardware needed (6 tools)
claude mcp add t32-lsp-mcp -- \
  /absolute/path/to/simple/bin/simple \
  /absolute/path/to/simple/examples/10_tooling/trace32_tools/t32_lsp_mcp/main.spl

claude plugin marketplace add tools/claude-plugin/marketplace
claude plugin install cmm-lsp@simple-local

> "Parse this CMM script and check for errors: config/t32/stm32h7_gdb_start.cmm"

> "Connect to TRACE32 on localhost:20000 and read the CPU registers"

> "Show me all labels and macros defined in my CMM script"

> "Convert this GUI PRACTICE script to CLI batch mode"

> "Check if my CMM script has any undefined macros or unreachable code"

> "Set a breakpoint at main, run to it, and show local variables"

> "What TRACE32 commands are available for memory access?"

> "Auto-complete suggestions for 'Data.LOAD' in my CMM script"