The NOVA (Natively Optimized Versatile Architecture) Tutorial

A guided walk from zero to a deployed full-stack application in NOVA. Every snippet compiles with the current nova binary. Each section explains not just what the syntax is but why the design is the way it is, what goes wrong when you misuse a feature, and how everything connects. If something doesn't work, that's a bug — file it.

1. Install

What is this? NOVA ships as a single self-contained installer per platform: the compiler, runtime, standard library, and a matched clang/LLVM toolchain arrive together. There is nothing to separately install first — no package manager, no Visual Studio Build Tools, no apt install llvm clang. NOVA compiles through LLVM (Low-Level Virtual Machine) — the same compiler backend used by C, Rust, and Swift, which is why it achieves C-level performance — but you never have to go find or configure it yourself.

# Linux / macOS
curl -fsSL novachan.org/install.sh | sh

# Windows (PowerShell)
iwr novachan.org/install.ps1 -useb | iex

Prefer not to pipe a script into your shell, or need a specific version? See all platform downloads for direct archive links and checksums. The installer places everything under ~/.nova (or the platform-appropriate equivalent) and sets NOVA_HOME for you — the rest of this chapter's manual NOVA_HOME/alias steps are for the build-from-source path below, not something a normal install needs.

Building from source (contributing to the compiler)

The installer above is the right choice for using NOVA. If you are instead working on the compiler itself — the scenario this section originally covered — you build from a clone and manage NOVA_HOME yourself. The compiler is self-hosted: the NOVA compiler is written in NOVA and compiles itself, currently producing a binary named gen3_test.exe under nova-compiler/test_programs/ once bootstrapped. You still need a system clang for this path (it is what compiles the compiler's own bootstrap step) — the bundled-toolchain resolution the installer sets up is for compiling your NOVA programs, not for bootstrapping the compiler from source.

For day-to-day use from a source checkout, alias the built binary so you can type nova instead of the full path:

# Linux/macOS — add to ~/.bashrc or ~/.zshrc
alias nova='/path/to/nova-compiler/gen3_test'

# Windows PowerShell — add to $PROFILE
function nova { & "C:\path\to\nova-compiler\gen3_test.exe" @args }

Setting NOVA_HOME

NOVA resolves standard library modules — including Forge — by looking in $NOVA_HOME/lib/. Set this environment variable to the directory that contains the lib/ folder:

# Linux/macOS
export NOVA_HOME=/path/to/nova-compiler

# Windows PowerShell
$env:NOVA_HOME = "C:\path\to\nova-compiler"

Starting a new project

You do not have to hand-create files to start a NOVA project. nova new <name> scaffolds a working project skeleton — directory layout, an entry file, and a nova.toml manifest — so the very first thing you run already compiles. This matters more than it sounds: starting from a blank file forces you to remember the entry-point convention, the test-file naming convention, and the manifest format before you have written a single line of logic. A scaffolded start defers all of that until you actually need it.

# default skeleton is a REST API project
nova new blog

# or pick a shape explicitly
nova new blog --api            # REST API skeleton — same as the default
nova new blog --microservice   # health checks + graceful shutdown wired in
nova new blog --frontend       # browser-targeted skeleton
nova new blog --fullstack      # API + frontend in one project
nova new blog --lib            # library skeleton — exported modules, no entry point

cd blog
nova run main.nova

If you already have a directory and just want the manifest — for example, you are adding NOVA to a folder that already has files you want to keep — use nova init instead. It writes only nova.toml into the current directory and touches nothing else:

mkdir price-checker && cd price-checker
nova init

nova setup — the one-time build-speed unlock

The first time NOVA compiles anything on a fresh machine, every build re-links against the C runtime from scratch — a roughly 6.5 second tax on every single nova run, even for a one-line print("hello"). nova setup pre-compiles the runtime into a cached object file once, up front, so every later build links against that cache instead of rebuilding the runtime each time. This is a startup step, not an optional optimization — run it immediately after installing NOVA, before your first nova run:

nova setup

The difference is not marginal — it is the gap between NOVA feeling like a compiled language with Go's iteration speed, and NOVA feeling like it recompiles a C project from scratch on every run. nova setup is a one-time, per-machine step; run it again only after an update changes the runtime itself.

What happens when you run nova

The NOVA compiler is not an interpreter — it is a full ahead-of-time compiler. When you type nova run hello.nova, here is what happens behind the scenes:

1. Lexing — the compiler reads your .nova file and breaks it into tokens (keywords, identifiers, operators, literals)
2. Parsing — tokens become an AST (Abstract Syntax Tree) representing the structure of your program
3. Type inference — the HM (Hindley-Milner) engine walks the AST, infers every type without you writing annotations, checks for type errors, and resolves function calls
4. IR (Intermediate Representation) generation — the typed AST is lowered to NOVA's IR, a simplified instruction set that is easier to optimize
5. LLVM codegen — the IR is translated to LLVM IR, the same format used by C and Rust compilers
6. Compilation — LLVM compiles the IR to native machine code (.exe on Windows, ELF on Linux)
7. Execution — the compiled binary runs directly on your CPU with no interpreter, no JIT (Just-In-Time) warmup, no VM

nova run and nova build — same pipeline, different destinations

Every earlier example told you to save a file and run nova run hello.nova — but run is only one of several subcommands built on the exact compile pipeline listed above (lex → parse → infer → IR → LLVM → codegen). What changes between them is the optimization level applied at the LLVM step, and whether the compiler executes the result or just leaves it on disk. nova run defaults to -O0 (no optimization) and executes the binary immediately after building it — the right choice while you are actively editing, since skipping LLVM's optimization passes is what keeps the edit-compile-run loop fast. nova build defaults to -O2 (full optimization) and does not run anything — it produces an executable and stops, because a binary you deploy and run many times is worth extra compile time up front for faster generated code.

# fast iteration loop — compiles in milliseconds, executes immediately
nova run calc.nova

# production build — takes longer to compile, produces a faster binary, does not run it
nova build calc.nova
./calc

calc.nova prints the same 42 either way — only the compiled artifact and its execution speed differ. Vs Rust: this is the same split as cargo run (debug profile, unoptimized, runs immediately) vs cargo build --release (optimized, binary only) — NOVA just gives each job its own command with a sensible default, instead of one command plus a flag you have to remember to add.

nova compile and nova emit — inspecting the pipeline without a binary

Sometimes you want to see what the compiler produced without paying for a full link — to debug a codegen issue, to feed the output into another LLVM-based tool, or to sanity-check a specific target. nova compile stops the pipeline right after LLVM IR generation and writes the result to a .ll file next to your source — it never invokes clang, so there is no linking and no executable. nova emit is for looking at that output directly instead of saving it: by default it prints the LLVM IR to stdout, and with --asm it asks LLVM to lower that IR all the way to native assembly text — still without linking into a runnable binary. --target <triple> works with either command and points it at a target other than your host machine.

nova compile calc.nova              # writes calc.ll — no executable produced
nova emit calc.nova                 # prints the LLVM IR itself to stdout
nova emit calc.nova --asm           # prints native assembly instead of LLVM IR

(Abridged — the real output carries full type and TBAA metadata, per the Compilation pipeline spec.) Reach for nova compile when you want the artifact on disk; reach for nova emit when you just want to look at it once, in the terminal, with no leftover file to clean up.

nova wasm — compiling to WebAssembly

NOVA's LLVM backend targets more than your host CPU. nova wasm compiles a .nova file straight to a runnable WebAssembly bundle: a .wasm binary plus two JavaScript glue files — <name>.run.cjs (a runnable entry point) and _wasm_runtime.cjs (the JS-side runtime support the WASM output depends on, for the host calls a WASM sandbox cannot make on its own). This is what lets the same NOVA source that runs as a native binary on your machine also run inside Node.js or a browser's WASM sandbox — no rewrite, no separate WASM-specific language subset.

nova wasm calc.nova
nova wasm calc.nova -o dist/calc -O1   # custom output path, one step of optimization

The -O0/-O1 options work the same way they do for run/build, just with a lower ceiling: WASM optimization stops at -O1 rather than -O2, reflecting that a WASM build's goal is portability into a JS host, not squeezing out the last cycle of native performance.

nova eval — evaluating one expression without a file

Sometimes you just want to know what an expression evaluates to — how a builtin behaves on a specific input, whether an operator does what you expect — without creating a throwaway .nova file and running the whole pipeline. nova eval "<expr>" skips LLVM entirely: it tree-walks (directly interprets) a single expression and prints the result. This is the same job python -c "..." or node -e "..." do for their languages — a scratchpad for one-line questions, not a way to run programs.

nova eval "2 + 3 * 4"
nova eval "len([1, 2, 3, 4, 5])"
nova eval "upper(\"nova\")"

Build option flags

These flags apply across nova run, nova build, and nova compile (partially to emit/wasm, as noted) — each one overrides that command's default, not just restates it:

nova build server.nova -O0 -o debug_server    # fast compile, unoptimized — for local debugging
nova build server.nova -O2 -o server          # slow compile, optimized — what you ship
nova run server.nova -O2                      # benchmark the optimized path while still developing

Editor setup

NOVA has a VS Code extension in the nova-vscode/ directory. It provides syntax highlighting, goto definition (Ctrl+Click — works for functions, methods, structs, enums, traits, fields, and across modules), and diagnostics. Copy nova-vscode/ into your extensions directory and reload.

Cross-compiling for other platforms

What is this? Because NOVA compiles through LLVM, the compiler is not tied to producing code for the machine it happens to be running on. LLVM's whole value as a backend is that one frontend (NOVA's typed IR) can target any platform LLVM knows an instruction-selection and calling-convention story for — you just have to tell it which one. NOVA exposes this directly as a --target flag on nova build, nova compile, and nova emit. The exact same .nova source file, unmodified, produces a correct binary for a completely different OS and CPU architecture than the one doing the compiling.

This is not a hypothetical convenience. A solo developer running Windows who needs to ship a Linux container for a cloud host, or who wants an Apple Silicon build for a Mac release without owning a Mac, hits this on day one — and without --target, NOVA would be exactly as platform-locked as any compiler that only emits code for its own host.

The three commands differ in how far they carry the cross-compiled output, which matters because linking for a foreign target usually requires that target's own linker and libraries — tools you likely don't have installed:

• nova build file.nova --target <t> — compiles and links a runnable executable for <t>. This only succeeds if a suitable cross-linker/toolchain for that target is available on your machine.
• nova compile file.nova --target <t> — stops after LLVM IR generation and writes a .ll file for <t>. No linker involved, so this always succeeds regardless of what toolchains you have installed.
• nova emit file.nova --target <t> — prints the generated LLVM IR straight to stdout (add --asm for native assembly instead of IR). This is the fastest way to inspectwhat NOVA generates for a target you cannot actually run — e.g. checking the ARM64 codegen for a struct-heavy function from an x86 machine, with no ARM toolchain anywhere in the picture.

nova build myapp.nova --target linux          # cross-compile for Linux
nova build myapp.nova --target wasm           # compile to WebAssembly
nova emit myapp.nova --target macos-arm64     # inspect ARM64 IR

The recognized short names and the LLVM triple each one expands to:

If you pass a value that isn't one of the short names above, NOVA doesn't reject it — it forwards the string verbatim to LLVM as a raw target triple. This is the escape hatch for anything the short-name table doesn't cover: nova compile file.nova --target riscv64-unknown-linux-gnu works today even though riscv64 has no short alias, because the string reaches LLVM exactly as typed.

Targeting WebAssembly

What is this? wasm / wasm32 selects the wasm32-unknown-unknown LLVM triple — the same target used to run C, Rust, and Go code inside a browser tab or a WASM edge runtime. It slots into --target exactly like linux or macos-arm64 above: no special syntax, no separate compiler, the same nova build / nova compile / nova emit commands you already use for native builds.

nova compile myapp.nova --target wasm   # .ll for the wasm32 triple — no linker required
nova emit myapp.nova --target wasm32    # inspect the generated wasm32 IR directly

Selecting --target wasm on build/compile/emit controls exactly one thing: which LLVM triple your .nova source is lowered against. It is deliberately narrow, and it is a different tool from the dedicated nova wasm command (see the CLI reference) — nova wasm is the full packaging pipeline that produces a ready-to-run bundle (the .wasm module plus its JS host glue) in one step. Use --target wasm when you're driving build/compile/emit yourself and only need the wasm32 codegen; use nova wasm when you want something you can hand to a browser or a WASM host without assembling the glue code yourself.

A correctness fix worth knowing about if you're targeting wasm: earlier builds of the WASM target never ran a program's top-level initialization step — module-level let bindings and similar setup code that runs before main() — because --no-entry WASM builds call only the exported main function directly, and that initialization lived somewhere --no-entry never reached. This is fixed: WASM builds now run the same initialization sequence native builds do, in the same order, before main executes.

Verified on four platforms, not just cross-compiled

What this means: the target table above says NOVA can produce a binary for Linux x64, Linux ARM64, and macOS from a Windows machine. Separately — and this is the part worth being precise about — NOVA's full regression suite (3,590 tests), run in both of its memory-tracking modes, plus the self-hosting bootstrap check (the compiler compiling itself to a byte-identical output, twice in a row) all pass natively on Windows, Linux x64, Linux ARM64, and macOS. Cross-compilation support and "we tested it for real on that platform" are two different claims, and both are true here — but we're telling you which is which rather than letting one imply the other.

Why this took real work, and what it actually found: testing the same compiler and runtime on four platforms surfaces bugs that testing on one platform structurally cannot — because the bug depends on something that only differs between platforms. That happened here, repeatedly, and the honest version of "we support macOS and Linux" includes what had to be fixed to make that true:

• Signed integer overflow was undefined behavior, not wrapping. NOVA's language spec says integer arithmetic wraps on overflow — but one runtime code path relied on C's +/* directly, which is undefined on signed overflow in C itself. On most platforms the generated code happened to wrap anyway; on macOS, the optimizer used that undefined behavior differently, producing an intermittent, hard-to-reproduce wrong answer in a cryptographic routine. Single-platform testing had no way to catch this, because the bug wasn't in the logic — it was in which platform's compiler exploited the UB.
• A data race in address-range lookup produced silently wrong answers on macOS specifically. Two threads could read and update the runtime's module address-range table without synchronization; macOS's memory layout made the race far more likely to actually manifest than it was on Windows or Linux, where the same unsynchronized code had been quietly getting lucky.
• String literals were identified by memory address, and an integer could collide with one. If a plain integer happened to equal the address of a literal string elsewhere in the binary, the runtime could mistake one for the other. Fixed by identifying literals by content and relocating them into the arena — a class of bug that address-based sniffing can never fully rule out, only reduce the odds of hitting.
• TLS didn't exist at all on macOS or Linux. The runtime's TLS upgrade function has three implementations — Windows' native SChannel, an OpenSSL-backed path, and a stub that silently returns failure when neither is compiled in. The POSIX build was shipping with neither real backend wired in, so every https:// request and every tls_upgrade() call failed on those platforms. Now building the OpenSSL backend into POSIX builds.
• macOS's own assembler needed different object-file directives than Linux's. NOVA emits a small amount of hand-written assembly (used by the stack-overflow containment mechanism); Linux's ELF format and macOS's Mach-O format disagree on symbol prefixing and on directives like .type/.size that ELF requires and Mach-O rejects.

None of this shows up as a feature — it shows up as "the tests pass on that platform now, and didn't before." That's the point: cross-platform correctness in a systems language is earned by finding and closing exactly these kinds of gaps, not by assuming LLVM's portability makes the runtime portable for free.

What the editor extension talks to: nova lsp

The VS Code extension above is a thin client — the actual intelligence behind goto-definition and diagnostics lives in a separate process the extension launches for you automatically, speaking the Language Server Protocol (LSP), the same open protocol behind rust-analyzer and gopls. nova lsp (equivalently nova --lsp) starts that server directly. You only need to run it by hand if you use an LSP-capable editor other than the bundled VS Code extension — Neovim, Sublime Text, Emacs with eglot — where you point the editor's language-server setting at this command instead of installing a separate plugin.

nova lsp
# equivalently:
nova --lsp

nova repl — interactive experiments

For exploration that spans more than one expression — trying a few builtins in sequence, building up a small data structure by hand to see how it prints, checking how a match arm evaluates a specific value — nova repl starts a read-eval-print loop: it reads one line, evaluates it, prints the result, and (unlike nova eval) keeps every variable you defined available for the next line. This is the same idea as Python's interactive shell or plain node with no file argument.

nova repl
> x = 10
> y = 20
> x + y
30
> upper("nova")
NOVA

2. Hello, world

What is this? Your first NOVA program. It demonstrates that NOVA requires zero ceremony — no imports, no class wrappers, no semicolons, no braces. One line does one thing.

print("Hello, world!")

Save as hello.nova and run: nova run hello.nova

Line-by-line: print is a built-in function available everywhere with no import. It takes any value, converts it to a string, writes it to stdout, and adds a newline. Compare: Python print("..."), Go fmt.Println("...") (needs import), Rust println!("...") (macro syntax), C printf("...\n") (needs #include). NOVA is the simplest.

String interpolation

name = "Alice"
age  = 30
print("Hello, {name}! You are {age} years old.")
// Output: Hello, Alice! You are 30 years old.

x     = 7
items = ["a", "b", "c"]
print("x squared is {x * x}")            // x squared is 49
print("There are {len(items)} items")    // There are 3 items

Line-by-line: {name} inside a double-quoted string is replaced by the variable's value. Any expression works: {x * x}, {len(items)}. This is always active — no f"..." prefix needed (unlike Python). To get a literal brace, escape it: \{.

Format specifiers — controlling how a value prints

Plain {expr} interpolation calls the value's default string conversion. When you need to control the result of that conversion — pad a number with zeros, fix a float to two decimal places, align a column of text — add a format spec after a colon: {expr:[[fill]align][0][width][.precision][d|f|s|x|o|b]}. It's the same mini-language Python's f"{x:04d}" and Rust's format!("{:>8}") use. The trailing type letter (d decimal, f float, s string, x hex, o octal, b binary) documents intent but is optional — the compiler already knows the expression's type.

n = 7
print("{n:04d}")                // 0007 — zero-padded to width 4

pi = 3.14159
print("{pi:.2f}")              // 3.14 — fixed to 2 decimal places

price = 9.5
print("Total: ${price:.2f}")   // Total: $9.50

name = "Bob"
print("[{name:>8s}]")         // [     Bob] — right-align in 8 columns
print("[{name:<8s}]")         // [Bob     ] — left-align in 8 columns
print("[{name:^8s}]")          // [  Bob   ] — center-align

byte_val = 255
print("{byte_val:04x}")        // 00ff — zero-padded hexadecimal

// format specs also work on index expressions, not just bare variables
items = ["a", "bb", "ccc"]
print("[{items[1]:>5s}]")     // [   bb]

Your first function

fn greet(name)
    print("Hello, {name}!")

fn main()
    greet("Bob")
    greet("Carol")

Line-by-line:

• fn greet(name) — declares a function. No type annotation on name. The compiler infers name is a string because you pass "Bob" at the call site. In Java: void greet(String name). In NOVA: just fn greet(name).
• The body is indented 4 spaces. Indentation defines the block (like Python). No braces, no end.
• fn main() — the program entry point. When it exists, execution starts here.

main() — when you need it

For simple one-file scripts, top-level code runs directly — no main() needed. For larger programs with multiple functions that call each other, use fn main():

fn add(a, b)
    a + b

fn main()
    result = add(3, 4)
    print("3 + 4 = {result}")
// Output: 3 + 4 = 7

Line-by-line breakdown:

• fn add(a, b) — declares a function called add that takes two parameters. No type annotations written. The compiler figures out a and b are integers because you call add(3, 4) below — integer literals tell the compiler the type.
• a + b — this is the entire body of the function. No return keyword. In NOVA, the last expression in a function is automatically its return value. a + b evaluates to 7, and that value is returned to the caller. This is like Rust, Ruby, and Kotlin, where the last expression is the implicit return.
• fn main() — the main function is the entry point. When fn main() exists, NOVA starts executing there instead of running top-level statements in order.
• result = add(3, 4) — calls the add function with arguments 3 and 4, stores the return value (7) in a variable called result. No let, no var, no const — just write the name and assign. This is NOVA's zero-ceremony design: the simplest possible syntax for the most common operation.
• print("3 + 4 = {result}") — prints the string with {result} replaced by the value of the variable (which is 7). Output: 3 + 4 = 7.

When to use main() vs top-level code:

• One-file scripts: Do not need main(). Top-level statements run in order. Great for quick experiments.
• Multi-file projects: Use main() as the entry point so the compiler knows where execution begins.
• Programs with tests: Use main() so that test functions (test_run/test_summary) do not conflict with normal execution.

Comments

// This is a line comment — everything from // to end of line is ignored
x = 42  // This is an inline comment

// NOVA does not have multi-line /* */ comments
// Use multiple // lines instead
// like this
// and this

// Comments are great for explaining WHY, not what:
timeout_ms = 5000  // 5 seconds — enough for slow mobile connections

3. Values and types

What is this? NOVA has five basic value types. The compiler infers all of them — you never have to write type annotations for local variables. The Hindley-Milner (HM) type inference engine figures out every type from how values are used.

Integers

Integers are 64-bit signed values. They can hold any value from -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807.

x   = 42
y   = -17
big = 1_000_000_000    // underscores for readability
hex = 0xFF              // hexadecimal: 255
bin = 0b1010            // binary: 10
oct = 0o77              // octal: 63
print(hex)              // 255

Integer overflow behavior: NOVA integers wrap on overflow. If you add 1 to the maximum 64-bit integer, it wraps to the minimum — defined behavior, never undefined like C.

max_int = 9223372036854775807
print(max_int + 1)   // -9223372036854775808 (wrapped)

// Integer division truncates toward zero
print(7 / 2)          // 3 (not 3.5)
print(-7 / 2)         // -3 (rounds toward zero, not -4)
print(7 % 2)          // 1 (remainder)

Overflow detection with checked_add / checked_sub / checked_mul: If you need to fail fast on overflow instead of wrapping silently, use the checked variants — on success they return the same plain int as +/-/*, but the moment the operation overflows they panic (crash the current task) instead of returning a value. They do not return a Result:

a = 9223372036854775807    // max int
result = checked_add(a, 1)   // PANICS: "NOVA panic: integer overflow" — crashes this task, no value returned
print(result)              // never reached

// Safe multiplication — useful in cryptography and image processing
r2 = checked_mul(1000000, 1000000)   // 10^12 — fits in i64, returns 1000000000000
r3 = checked_mul(10000000000, 10000000000)  // 10^20 — too large, PANICS: "integer overflow"

overflow_panic() — triggering the same crash by hand

checked_add, checked_sub, and checked_mul don't invent a special failure mode when they detect overflow — internally they call overflow_panic(), the same primitive you can call directly. It immediately terminates the current task with "NOVA panic: integer overflow". Reach for it when you have already computed your own overflow condition by hand — checking that a multiplication would overflow before doing the multiply, for instance — and you want the identical crash and error message the checked_* family gives, rather than inventing your own ad hoc error string.

fn buffer_bytes(elements, elem_size)
    // Guard the multiply by hand: elements * elem_size would overflow i64
    if elem_size != 0 and elements > 9223372036854775807 / elem_size
        overflow_panic()      // same crash checked_mul would produce
    elements * elem_size

print(buffer_bytes(1000, 8))                    // 8000
print(buffer_bytes(9223372036854775807, 2))   // panics: NOVA panic: integer overflow

Floats

Floats are 64-bit IEEE 754 double-precision values, the same as double in C or float in Python.

pi  = 3.14159
sci = 1.5e10        // scientific notation: 15000000000.0

// THE FLOAT COMPARISON TRAP — do not do this:
x = 0.1 + 0.2
if x == 0.3
    print("equal")    // This will NOT print — 0.1+0.2 = 0.30000000000000004

// CORRECT: compare with a tolerance
if abs(0.1 + 0.2 - 0.3) < 0.0001
    print("approximately equal")    // This prints

Math functions available for floats:

print(sqrt(16.0))       // 4.0
print(abs(-5.3))         // 5.3
print(floor(3.7))       // 3.0
print(ceil(3.2))        // 4.0
print(round(3.5))       // 4.0  (rounds to nearest, .5 rounds up)
print(pow(2.0, 10.0))  // 1024.0
print(sin(3.14159))     // ~0.0 (angles in RADIANS)
print(cos(0.0))         // 1.0
print(log(2.71828))     // ~1.0 (natural log, base e)
print(log2(1024.0))    // 10.0
print(log10(1000.0))   // 3.0
print(exp(1.0))         // 2.71828... (e^x)
print(min(3.0, 7.0))   // 3.0
print(max(3.0, 7.0))   // 7.0
print(atan2(1.0, 1.0)) // 0.7853... (pi/4 — angle of vector (1,1))
print(hypot(3.0, 4.0)) // 5.0   (sqrt(a²+b²) — hypotenuse)

Strings

Strings are immutable UTF-8 sequences. Every operation that "changes" a string creates a new one.

s = "Hello, NOVA!"
print(len(s))                        // 12
print(upper(s))                       // HELLO, NOVA!
print(lower(s))                       // hello, nova!
print(find(s, "NOVA"))               // 7 (index of first match)
print(replace(s, "NOVA", "World")) // Hello, World!
print(starts_with(s, "Hello"))     // true
print(split("one two", " "))      // ["one", "two"]
print(slice(s, 7, 11))              // NOVA
print(char_at(s, 0))               // H
print(char_at(s, -1))              // ! (negative = from end)
print(pad_left("42", 5, "0"))     // 00042
print(repeat("ha", 3))             // hahaha

The string building trap: Strings are immutable, so result = result + piece inside a loop copies the entire accumulated string each iteration — O(n²) total work. For N=1000, this copies ~500,000 characters instead of ~1000.

// SLOW: O(n²) — each + copies the whole string
result = ""
for i in 0..999
    result = result + str(i) + ","

// FAST: O(n) — collect parts in a list, join once at the end
parts = []
for i in 0..999
    push(parts, str(i))
result = join(parts, ",")

// ALSO FAST: buffer approach (no list overhead)
buf = buffer_create()
for i in 0..999
    buf_append(buf, str(i))
result = buf_to_str(buf)

Triple-quoted strings — multi-line text, dedented

Ordinary "..." strings are single-line. For multi-line text — embedded HTML, SQL queries, JSON templates, help text — use triple quotes: """...""". NOVA strips whatever leading indentation is common to every line of the literal, so you can indent the literal to match the surrounding code without that indentation becoming part of the string's value.

html = """
    <html>
      <body>
        <h1>Report</h1>
      </body>
    </html>
    """
print(html)
// the 4-space indent common to every line is stripped:
// <html>
//   <body>
//     <h1>Report</h1>
//   </body>
// </html>

name = "Alice"
greeting = """Hello, {name}!"""
print(greeting)      // Hello, {name}! — the braces are LITERAL here, not interpolated

For text that is naturally full of backslashes — regular expressions, Windows paths, JSON containing escaped quotes — triple backtick blocks go one step further than triple quotes: they skip escape processing entirely, so every backslash is a literal character instead of the start of an escape sequence.

pattern = ```\d+\.\d\d```
print(pattern)         // \d+\.\d\d — every backslash is literal, not an escape code

win_path = ```C:\Users\alice\data.csv```
print(win_path)        // C:\Users\alice\data.csv — no need to double every backslash

Type conversions

print(str(42))         // "42"
print(str(3.14))       // "3.14"
print(str(true))       // "true"
print(int("42"))       // 42
print(float("3.14"))   // 3.14
print(int(3.9))        // 3 (truncates toward zero — does NOT round)
print(int(-3.9))       // -3 (truncates toward zero)
print(float(7) / float(2))  // 3.5 (explicit float division)

Line-by-line breakdown:

• str(42) — converts integer 42 to the string "42". Works on any value.
• int("42") — parses the string "42" as a decimal integer. Crashes if the string is not a valid integer — use parse_int_safe("42") if the input might be invalid (returns Ok(42) or Err(...)).
• int(3.9) — truncates the decimal part. 3.9 becomes 3. This is NOT rounding — int(3.9) and int(3.1) both return 3. To round, use int(round(3.9)) which gives 4.
• float(7) / float(2) — converts both ints to float first, then divides. Gives 3.5. Without the float() calls, 7 / 2 would give 3 (integer division).

Booleans

a = true
b = false
print(not a)      // false
print(a and b)    // false — both must be true
print(a or b)     // true — at least one must be true

// Comparison operators return bool
print(3 == 3)     // true
print(3 != 4)     // true
print(3 < 4)      // true
print(3 >= 3)     // true

Short-circuit evaluation: and and or only evaluate the right side if needed:

// If the left side of `and` is false, right side is NEVER evaluated
x = 0
if x != 0 and 10 / x > 2
    print("safe")
// Without short-circuit: 10/0 would crash. With short-circuit: x != 0 is false,
// so `10/x` is never reached. Safe.

// If the left side of `or` is true, right side is NEVER evaluated
if true or expensive_check()
    print("fast")   // expensive_check() is never called

Truthiness: In boolean contexts like if, these values are falsy: 0, "" (empty string), false, and null. Everything else is truthy:

if 42:         print("truthy")    // prints — non-zero int is truthy
if "":         print("truthy")    // does NOT print — empty string is falsy
if "hello":   print("truthy")    // prints — non-empty string is truthy
if []:        print("truthy")    // does NOT print — empty list is falsy
if [0]:       print("truthy")    // prints — list with one element is truthy

Lists

Lists are ordered, mutable sequences that can hold any values. They are the primary collection type in NOVA.

nums  = [1, 2, 3, 4, 5]
names = ["alice", "bob", "carol"]
mixed = [1, "hello", 3.14, true]    // lists can hold mixed types
empty = []

// Access by index — 0-based
print(nums[0])      // 1 (first element)
print(nums[4])      // 5 (last element via index)
print(nums[-1])     // 5 (last element via negative index)
print(nums[-2])     // 4 (second to last)
print(len(nums))    // 5

// SAFETY: out-of-range access panics with a clear message
print(nums[10])     // Runtime error: index 10 out of bounds (list length 5)
// In C this would silently read garbage memory. NOVA stops you.

Line-by-line breakdown:

• nums[0] — index 0 is the first element. Lists are "zero-indexed" — a 5-element list has indices 0, 1, 2, 3, 4.
• nums[-1] — negative indices count from the end. -1 is the last element, -2 is second-to-last, etc.
• len(nums) — returns the number of elements (5). Note: the last valid index is len(nums) - 1 = 4, not 5.
• Out-of-range access — NOVA checks bounds at runtime and panics with a clear message rather than silently corrupting memory (which C does).

Modifying lists:

nums = [1, 2, 3]

// Append to end — O(1) amortized
push(nums, 4)
print(nums)             // [1, 2, 3, 4]

// Remove and return last element — O(1)
last = pop(nums)
print(last)             // 4
print(nums)             // [1, 2, 3]

// Insert at position — O(n) because elements shift
insert(nums, 1, 99)
print(nums)             // [1, 99, 2, 3]

// Remove by value (first occurrence) — O(n)
remove(nums, 99)
print(nums)             // [1, 2, 3]

// Remove by index — O(n) because elements shift
remove_at(nums, 0)
print(nums)             // [2, 3]

// Membership test
print(2 in nums)        // true
print(99 in nums)       // false

// Concatenate two lists — creates a new list
a = [1, 2]
b = [3, 4]
c = a + b
print(c)                // [1, 2, 3, 4]

// Sort in place — modifies the original list
data = [3, 1, 4, 1, 5]
sort(data)
print(data)             // [1, 1, 3, 4, 5]

// Reverse in place
reverse(data)
print(data)             // [5, 4, 3, 1, 1]

// Slice — returns a new sub-list (does NOT modify original)
sub = data[1:3]
print(sub)              // [4, 3]

Trailing commas

NOVA allows — but never requires — a trailing comma right before the closing bracket in any comma-separated construct: list literals, dict literals, function call arguments, function parameter lists, and struct field initializers. The comma carries no meaning of its own; it exists purely so that adding, removing, or reordering a line never forces you to also edit the punctuation on the line above it.

// Trailing comma in a multi-line list literal
scores = [
    95,
    87,
    91,
]
print(len(scores))            // 3

// Trailing comma in a dict literal
config = {
    "host": "localhost",
    "port": 8080,
}

// Trailing comma in a function call and in a parameter list
fn volume(
    l,
    w,
    h,
)
    l * w * h

print(volume(
    2,
    3,
    4,
))                          // 24

// Trailing comma in a struct initializer (must still be a single line — see below)
type Point
    x: float
    y: float

p = Point { x: 1.0, y: 2.0, }
print(p.x)                // 1.0

Dicts

Dicts are unordered key-value maps. Keys are typically strings. Very fast lookup — O(1) amortized via hash table.

person = {"name": "Alice", "age": 30, "city": "NYC"}

// Read a value
print(person["name"])      // Alice

// Check key existence BEFORE accessing — missing key returns default, not error
if contains(person, "email")
    print(person["email"])
else
    print("no email")        // prints this

// Set / add a key
person["email"] = "alice@example.com"
print(person["email"])      // alice@example.com

// Update an existing key
person["age"] = 31
print(person["age"])        // 31

// Delete a key
delete(person, "city")
print(contains(person, "city"))  // false

// Length
print(len(person))          // 3

// Get all keys / all values
ks = keys(person)
vs = values(person)

// Iterate over key-value pairs
for k in keys(person)
    print("{k}: {person[k]}")

Line-by-line breakdown:

• {"name": "Alice", "age": 30} — dict literal. Keys are strings in quotes, values can be any type.
• person["name"] — dict lookup. If the key does not exist, returns a default value (0 for int context, "" for string context), which can silently cause bugs.
• contains(person, "email") — always check key existence before accessing a key that might not be there. This prevents silent default-value bugs.
• delete(person, "city") — removes a key from the dict. Dict is modified in-place.
• for k in keys(person) — iterate over all keys. Dict iteration order is not guaranteed (hash map).

null — the absence of a value

x = null
if x
    print("has value")
else
    print("is null")    // prints this — null is falsy

print(x == null)        // true

Use null sparingly — only for optional fields. Prefer the Result type (see Section 9) for operations that can fail, because Result carries the reason for failure while null just means "nothing." null alone tells you nothing about what went wrong.

Type inference: how the compiler knows what type everything is

NOVA uses Hindley-Milner type inference (the same algorithm used by Haskell and Rust). You write no type annotations on local variables. The compiler figures out every type from how you use the value:

x     = 42           // compiler infers: int (because 42 is an int literal)
y     = 3.14          // compiler infers: float
name  = "Alice"    // compiler infers: string
items = [1, 2, 3]   // compiler infers: list of int

// Inference works across function calls too
fn double(x)
    x * 2

print(double(5))       // compiler infers x is int here → returns int
print(double(3.14))    // compiler infers x is float here → returns float

// If types conflict, you get a compile error
x = 42
x = "hello"   // compile error: cannot assign string to int variable

When to write type annotations — for 95% of code, write zero annotations. The compiler figures everything out. The two cases where you do need them:

• Struct field types (critical for performance): x: float on a struct field means native CPU register math. x: Float (capital) means dynamic dispatch — 150× slower. Always use lowercase.
• Function parameters for public APIs: fn distance(a: Point, b: Point) -> float — clearer for readers even though the compiler could infer it.

type Point
    x: float    // CORRECT: lowercase float = native CPU math = fast
    y: float
    // x: Float   ← WRONG: capital Float = dynamic dispatch = 150x SLOWER

The any type and runtime type predicates

Most NOVA code never needs any — Hindley-Milner inference pins down a concrete type for nearly everything you write. any exists for the genuinely dynamic slice of code: values arriving from JSON, a database row, or a plugin boundary whose shape isn't known until the program is running. Declaring something any needs no special ceremony — the compiler widens to any at the declaration and narrows it back down every time you check it with a type predicate.

fn describe(v: any) -> string
    if is_int(v)
        return "int: " + str(v)
    if is_float(v)
        return "float: " + str(v)
    if is_string(v)
        return "string: " + v
    if is_list(v)
        return "list of " + str(len(v)) + " items"
    if is_struct(v)
        return "struct " + type_name(v)
    "unknown"

print(describe(42))          // int: 42
print(describe(3.14))        // float: 3.14
print(describe("hi"))         // string: hi
print(describe([1, 2, 3]))  // list of 3 items

The full predicate set: is_int, is_float, is_string, is_bool, is_list, is_dict, is_struct, and is_numeric (true for either int or float, useful when you don't care which). Each returns a plain bool, so they compose directly with if, and/or, and match guards.

type_of(v) and type_name(v) answer two different questions. type_of returns a coarse KIND string — "int", "string", "list", "struct" — and that last one is the SAME string for every struct type that has ever existed in your program. type_name returns the concrete declared name:

type Point
    x: int
    y: int

let v: any = Point(1, 2)
print(type_of(v))     // struct -- coarse kind, same for EVERY struct type
print(type_name(v))   // Point  -- the concrete type name

The null value

null is a special value meaning "no value." It is used when a function or lookup has no result. Unlike Python's None or Java's null, you rarely need to write null yourself — it appears as a return value from functions that can fail to find something:

// dict.get() returns null if the key does not exist
d = {"x": 42}
val = d["y"]    // "y" is not in the dict
if val == null
    print("key not found")

// channel_recv_timeout returns null on timeout (no message received)
ch = channel()
result = channel_recv_timeout(ch, 100)   // wait 100ms
if result == null
    print("timed out")

The null trap — always check before using: Accessing a field or calling a function on null will panic at runtime.

// WRONG: crash at runtime if key not found
name = user_data["name"]
print(upper(name))    // CRASH if name is null

// CORRECT: check null before use
name = user_data["name"]
if name == null
    print("no name provided")
else
    print(upper(name))

Optional types with T?

T? is sugar for Option<T> — a type that is either "there is a value of type T" or "there is nothing." It works anywhere a type appears: a struct field, a function parameter, a let type annotation, or a return type. Reach for it when "missing" needs to be a tracked, checked possibility rather than a value you have to remember to compare against null — the compiler forces every caller to deal with the "nothing" case before it can reach the value inside.

type User
    id:   int
    name: string

// Return type says: "either a User, or nothing" — right in the signature
fn find_by_id(users, id) -> User?
    for u in users
        if u.id == id
            return some(u)
    none()

users = [User { id: 1, name: "Alice" }, User { id: 2, name: "Bob" }]

found = find_by_id(users, 2)
if is_some(found)
    print(unwrap(found).name)     // Bob
else
    print("no such user")

missing = find_by_id(users, 99)
if is_some(missing)
    print(unwrap(missing).name)
else
    print("no such user")          // no such user

The same sugar works directly on a struct field or a let-typed local:

type Profile
    username: string
    bio: string?          // a profile might not have a bio yet

p = Profile { username: "nova_dev", bio: none() }
print(is_some(p.bio))       // false

Variable reassignment and scope

Variables are block-scoped. Once created, a variable can be reassigned with =. NOVA has compound assignment operators for common update patterns:

x = 10

// Reassignment — just use = again
x = x + 1    // x is now 11
x = x * 2    // x is now 22

// Compound assignment — shorthand for the common patterns
x += 5    // x = x + 5 → x is now 27
x -= 7    // x = x - 7 → x is now 20
x *= 3    // x = x * 3 → x is now 60
x /= 4    // x = x / 4 → x is now 15
x %= 7    // x = x % 7 → x is now 1

// NOVA has no ++ or -- operators
// Use += 1 and -= 1 instead
i += 1    // equivalent to i++ in C/Java/JavaScript

Variable scope — indentation determines lifetime:

x = 10    // top-level scope — exists throughout the whole block

if x > 5
    y = 20    // y is only visible inside this if-block
    print(y)  // 20 — OK: inside the if-block

print(x)   // 10 — OK: x is in the outer scope
// print(y)  ← ERROR: y is out of scope here

// Loop variables are only visible inside the loop body
for i in 0..4
    square = i * i
    print(square)    // OK: inside the loop
// print(i)      ← ERROR: i is out of scope after the loop
// print(square) ← ERROR: square is out of scope after the loop

Immutable by default: let and let mut

Both x = 5 and let x = 5 compile to the same code — let never changes what's generated. What it changes is what the line COMMUNICATES: let marks "this is a brand-new binding," so a plain x = 5 later in the same scope reads unambiguously as a reassignment of something that already existed, not a second declaration. A bare let binding is meant to be treated as not-reassigned again — the moment you know a name will be updated later in the function, spell it let mut so a reader scanning top-to-bottom already knows, before they hit the reassignment, which names are going to change.

let x = 5                 // a plain binding — not reassigned again below
let mut counter = 0       // explicitly mutable — this name WILL be reassigned

counter = counter + 1
counter = counter + 1
print(counter)              // 2

let mut total = 0
for n in [10, 20, 30]
    total += n
print(total)                // 60

Multi-assign and swap

NOVA can assign to several names in one statement: a, b = 1, 2 binds them in parallel, and a, b = b, a swaps two values without a temporary variable. The right-hand side is fully evaluated — as a whole, using the OLD values of every name involved — before any assignment on the left happens, which is exactly what makes the swap correct even though a is being read and written in the same statement.

a = 1
b = 2
a, b = b, a
print("a={a} b={b}")          // a=2 b=1

// Parallel assignment for unrelated values — not just a swap
x, y, z = 10, 20, 30
print("x={x} y={y} z={z}")    // x=10 y=20 z=30

// A real use: swapping two list elements in place, e.g. inside a sort
nums = [5, 3, 8, 1]
i = 0
j = 2
nums[i], nums[j] = nums[j], nums[i]
print(nums)                   // [8, 3, 5, 1]

4. Control flow

What is this? How to make decisions and repeat things. NOVA uses indentation for blocks (like Python), and/or/not for boolean operators (NOT &&/||/!), and if is an expression (it returns a value).

If / else

fn classify(n)
    if n > 0
        "positive"
    else if n == 0
        "zero"
    else
        "negative"

fn main()
    print(classify(5))    // positive
    print(classify(0))    // zero
    print(classify(-3))   // negative

Line-by-line:

• if n > 0 — evaluates the condition. No parentheses needed (unlike C, Java, JavaScript).
• "positive" — the last expression in each branch is the value of the whole if expression. This function returns a string without writing return.
• else if n == 0 — chained condition. NOVA uses else if (two words), not elif.

If as an expression with then: For short single-line results, use then:

label = if n > 0 then "pos" else "non-pos"

Ternary if-expression — the value-first form

Besides if COND then A else B, NOVA also accepts the value-first ternary order familiar from Python: VALUE_IF_TRUE if COND else VALUE_IF_FALSE — no then keyword. Both are legitimate if-expression spellings; pick whichever reads more naturally at the call site. The value-first form chains right-associatively, so it stacks into an else-if ladder without extra parentheses.

x = 7
label = "big" if x > 3 else "small"
print(label)              // big

// chains right-associatively — reads like an else-if ladder
grade = "A" if x > 90 else "B" if x > 80 else "C"
print(grade)              // C  (x is 7 — neither > 90 nor > 80)

// the equivalent then/else form, for comparison — same result, different word order
label2 = if x > 3 then "big" else "small"
print(label2)             // big

A bare if/else as an entire function body

The multi-line block form above (if / else if / else, each branch on its own indented line) works as a function's implicit-return body. So does the then-based ternary shown above — but only on the right-hand side of an assignment. There's a third shape, tighter than either: write the condition and both branches on one line, with no then, as the function's only statement. NOVA recognizes this specifically when a statement starts with if — the value of the if/else expression becomes the function's return value, the same implicit-return rule used everywhere else in the language.

fn max(a: int, b: int) -> int
    if a > b a else b

fn abs_val(n: int) -> int
    if n < 0 -n else n

fn main()
    print(max(3, 7))
    print(max(12, 5))
    print(abs_val(-8))
    print(abs_val(6))

Notice max has no then anywhere. then belongs to the ternary-on-assignment form (label = if cond then a else b) shown above — it exists there to separate the condition from the value when both sit after an = on the same line. When the if opens the statement itself there is nothing to separate it from, so the grammar doesn't need the keyword: if a > b a else b parses unambiguously as "condition, then-branch, else-branch" without one.

For loops and ranges

// Iterate a list
for x in ["a", "b", "c"]
    print(x)
// a
// b
// c

// Range with .. (right end is EXCLUSIVE — half-open, like Python's range())
for i in 0..5
    print(i)
// 0 1 2 3 4

// Iterate with index: "for i, v in xs" is the native form — do NOT wrap it in enumerate()
fruits = ["apple", "banana", "cherry"]
for i, fruit in fruits
    print("{i}: {fruit}")
// 0: apple
// 1: banana
// 2: cherry

// Iterate a dict
scores = {"alice": 95, "bob": 87}
for name, score in scores
    print("{name} scored {score}")

While and break/continue

i = 0
while i < 10
    i = i + 1
    if i % 2 == 0
        continue    // skip even numbers
    print(i)
// 1 3 5 7 9

// Search loop: break when found
nums = [4, 7, 2, 9, 1]
i = 0
while i < len(nums)
    if nums[i] == 9
        print("found 9 at index {i}")
        break
    i = i + 1

The loop keyword

For infinite loops, loop is cleaner than while true:

count = 0
loop
    count = count + 1
    if count >= 5
        break
print(count)    // 5

Compound assignment operators

x = 10
x += 5   // x = 15
x -= 3   // x = 12
x *= 2   // x = 24
x /= 4   // x = 6
x %= 4   // x = 2

Multi-target assignment, swapping, and comma-list destructuring

NOVA lets a single assignment target several names at once from a comma-separated list. The right-hand side is evaluated into temporaries FIRST, then assigned left to right — so a, b = b, a is a genuine simultaneous swap, not a bug waiting for a missing temp variable.

a = 1
b = 2
a, b = b, a            // swap — no temp variable needed
print("a={a}, b={b}")    // a=2, b=1

// works with any number of targets, and any expressions on the right
x, y, z = 10, 20, 30
print("{x} {y} {z}")       // 10 20 30

// proof it's a REAL simultaneous swap: a sequential "a = b" then "b = a"
// would leave BOTH equal to the original b — this doesn't
nums = [5, 1, 9, 3]
nums[0], nums[3] = nums[3], nums[0]
print(nums)                 // [3, 1, 9, 5]

The same left/right shape works with let, treating the right-hand side as a list and mapping positions 1:1 — this is comma-list destructuring. Use it when a function already returns a list and you want to name each element instead of indexing into it.

fn divmod(a, b)
    [a / b, a % b]

let a, b = [10, 20]
print("a={a}, b={b}")    // a=10, b=20

let q, r = divmod(17, 5)
print("q={q}, r={r}")    // q=3, r=2

Iterating dicts — keys, values, pairs

Dicts can be iterated in three patterns. Pick the one that matches what you actually need:

scores = \{"Alice": 95, "Bob": 87, "Carol": 91\}

// Pattern 1: iterate keys, look up value separately
for name in keys(scores)
    print("{name}: {scores[name]}")

// Pattern 2: destructure key/value pairs directly (preferred)
for name, score in scores
    print("{name}: {score}")

// Pattern 3: build a new dict from two parallel lists
names  = ["Alice", "Bob", "Carol"]
points = [95, 87, 91]
result = \{\}
for i in 0..len(names) - 1
    result[names[i]] = points[i]
print(result)   // {Alice: 95, Bob: 87, Carol: 91}

Line-by-line breakdown:

• for name in keys(scores) — keys() returns a list of the dict's keys in insertion order. This pattern is useful when you need just the keys, or when you need to conditionally skip looking up the value.
• for name, score in scores — iterating a dict directly yields key/value pairs. This is the preferred pattern: it's one lookup per iteration instead of two (key lookup + value lookup). Python calls the equivalent dict.items(); NOVA makes it the default dict iteration.
• result[names[i]] = points[i] — builds a dict by combining two parallel lists. The range 0..len(names) - 1 is exclusive on the right end (half-open: includes a, excludes b), so with 3 names this iterates i = 0, 1, 2.

Destructuring tuples in a for-loop

When you're iterating a list whose elements are themselves tuples — pairs, coordinates, records you built by hand — for (a, b) in pairs destructures each element positionally right in the loop header, the same way let (a, b) = pair destructures a single tuple. This is distinct from the list/dict auto-dispatch form for i, v in items (which supplies the index or key FOR you): here, the tuples already exist as elements of the sequence you're iterating.

pairs = [(1, "one"), (2, "two"), (3, "three")]

for (n, word) in pairs
    print("{n} = {word}")
// 1 = one
// 2 = two
// 3 = three

// real use: coordinates your own code built, not a dict
points = [(0, 0), (3, 4), (6, 8)]
for (px, py) in points
    print("distance from origin: {sqrt(px * px + py * py)}")
// distance from origin: 0.0
// distance from origin: 5.0
// distance from origin: 10.0

loop — finding the first match

When you need to exit a loop from the middle — not from the condition at the top or bottom — loop with break is the clearest tool. This is better than while true because it signals intent: this loop exits from inside, not from an external condition.

fn find_first_even(nums)
    i = 0
    loop
        if i >= len(nums)
            return err("no even number found")
        if nums[i] % 2 == 0
            return ok(nums[i])
        i += 1

print(find_first_even([1, 3, 7, 4, 9]))   // Ok(4)
print(find_first_even([1, 3, 5]))          // Err(no even number found)

Line-by-line breakdown:

• i = 0 — the index starts at zero. We manually manage it because we need to track position to access elements.
• loop — starts an infinite loop. The loop runs until a return or break exits it.
• if i >= len(nums) — the bounds check comes first. If we've gone past the end, no even number exists. We return an error rather than crash.
• if nums[i] % 2 == 0 — the even check. % is the modulo operator. If the remainder when dividing by 2 is zero, the number is even.
• return ok(nums[i]) — exits the function immediately with the found value. We don't need to set a flag or break to an outer scope.
• i += 1 — only reached if neither condition matched. Advance to the next element.

Why not for i in 0..len(nums)-1? A for loop works too, but loop makes the mid-loop exit pattern explicit. When a reader sees loop, they know the exit is inside — the structure itself documents the intent.

Nested loops — multiplication table

Loops can be nested to any depth. Each loop has its own break and continue: break only exits the innermost loop it appears in, not all loops.

// Print a 4x4 multiplication table
for row in 1..5
    line = ""
    for col in 1..5
        line += "{row * col}\t"
    print(line)

// Output:
// 1  2  3  4
// 2  4  6  8
// 3  6  9  12
// 4  8  12 16

// break exits only the INNERMOST loop
// To exit the outer loop, use a flag:
found_row = -1
found_col = -1
done = false
for r in 1..5
    if done: break
    for c in 1..5
        if r * c == 6
            found_row = r
            found_col = c
            done = true
            break
print("First occurrence of 6: row={found_row}, col={found_col}")
// First occurrence of 6: row=2, col=3

Line-by-line breakdown:

• for row in 1..5 — iterates 1, 2, 3, 4 (exclusive right end (half-open range)). The outer loop controls which row we are printing.
• line = "" — resets the line string for each row. Each row is built by appending column values.
• for col in 1..5 — inner loop builds one row. \t in the string literal inserts a tab for alignment.
• if done: break — the outer-loop escape. When the flag is set, the outer loop exits on its next iteration. This is the standard pattern because NOVA has no labeled break.
• break in the inner loop — exits only the for c in 1..5 loop. Control returns to the outer loop, which checks if done and exits.

Loop types — comparison table

NOVA has three loop forms. Choosing the right one makes your intent clear to the reader:

Why loop instead of while true: Both work, but loop is better because it communicates intent. A reader who sees loop immediately knows the exit is inside the body, not at the top. A reader who sees while true has to scan the body to understand the exit. NOVA, Rust, and Crystal all have loop for this reason.

Complete countdown example — putting it together

// Count down from 10 using while
n = 10
while n > 0
    print(n)
    n -= 1
print("Blast off!")
// Output: 10 9 8 7 6 5 4 3 2 1 Blast off!

// Skip even numbers using continue
for i in 1..10
    if i % 2 == 0
        continue    // skip even numbers
    print(i)        // prints 1, 3, 5, 7, 9

// Stop early using break
for i in 0..9
    if i == 5
        break       // exit the loop at 5
    print(i)        // prints 0, 1, 2, 3, 4

// Infinite loop reading user input — exits from inside
loop
    line = readline()    // read a line from stdin
    if line == "quit"
        break
    print("You said: {line}")

Line-by-line breakdown:

• while n > 0 — checks the condition before each iteration. When n reaches 0, the loop stops. The n -= 1 inside the body decrements n each time.
• if i % 2 == 0: continue — continue immediately jumps to the next iteration without running any code below it in the loop body. This skips even numbers: when i is 2, 4, 6, 8, or 10, print is never reached.
• if i == 5: break — break immediately exits the entire loop. Execution continues with the first statement after the loop. So we print 0, 1, 2, 3, 4 — not 5.
• loop with if line == "quit": break — the exit condition is checked in the middle after reading input. The loop runs until the user types "quit." This cannot be expressed as a while condition because we need to read the input first to know whether to exit.

Loop performance — what the compiler sees

Every loop form in NOVA compiles to the same underlying LLVM IR — a branch, a body, and a back-edge. The for, while, and loop keywords are purely a developer-facing readability choice; they have identical performance characteristics. The compiler applies the same optimizations (loop invariant code motion, strength reduction, unrolling) to all of them.

The practical consequence: you should choose a loop form based on readability, not performance. The compiler will not penalize you for writing loop { if done: break } versus while not done. Choose the one that makes the code's intent clearest.

unless and until — negated conditionals

unless and until are sugar for the negated form of if and while. unless COND means if not COND; until COND means while not COND. Reach for them when phrasing a check in the positive would force a double negative on the reader.

done = false

fn process_next()
    print("processing next item")

unless done
    process_next()          // done is false, so this runs

count = 0
until count > 10
    count += 1
print(count)                 // 11

Line-by-line:

• unless done — runs the body only when done is false. It is exactly if not done, desugared by the compiler before type checking.
• until count > 10 — repeats the body until the condition becomes true. It is exactly while not (count > 10).
• Both keywords are pure readability sugar. Anything you write with unless/until you could write with if not/while not.

for...else and while...else — did the loop find something?

A loop's else clause runs when the loop finishes normally — that is, when it was not stopped early by break. This gives you a direct answer to "did the loop find what it was looking for?" without a separate boolean flag.

fn search(items, target)
    for item in items
        if item == target
            print("found!")
            break
    else
        print("not found")    // only runs if no break happened

search([3, 7, 2, 9, 4], 9)     // found!
search([3, 7, 2, 9, 4], 100)   // not found

Line-by-line:

• else is attached to the loop, not to the if inside it — notice its indentation matches for/while, one level shallower than the if.
• break skips the else — this is the entire point of the construct.
• Without this feature, the same logic needs a flag: found = false before the loop, found = true next to the break, then if not found: ... after the loop — three extra lines.

while / else — a dedicated example

The same else-runs-unless-break-fired rule from for...else applies identically to while. The clause runs when the loop's condition becomes false naturally — never when break ends it early. This is the direct way to distinguish "the search space ran out" from "we found it and stopped."

fn countdown_to_target(start, target)
    x = start
    while x > 0
        if x == target
            print("hit {target} on the way down")
            break
        x -= 1
    else
        print("reached zero without hitting {target}")   // only runs if no break happened

countdown_to_target(10, 5)      // hit 5 on the way down
countdown_to_target(10, -1)     // reached zero without hitting -1

Line-by-line:

• while x > 0 ... else — the else's indentation matches while, one level shallower than the loop body, exactly like for...else.
• First call: break fires when x == 5, so the else clause is skipped entirely.
• Second call: target -1 is never equal to any x the loop visits — x counts down to 1 and the condition x > 0 goes false before x could ever reach -1 — so the loop ends normally and else runs.

Chained comparisons

NOVA lets you chain comparison operators the way you'd write them on paper: 0 <= x <= 100 instead of 0 <= x and x <= 100. The compiler desugars a chain into an and of each adjacent pair — but crucially, it evaluates each middle term only once.

x = 42
if 0 <= x <= 100
    print("in range")          // in range

a = 1
b = 5
c = 9
d = 20
if a < b < c < d
    print("ascending")          // ascending

// Proof the middle term is evaluated ONCE, not twice:
count = 0
fn next_val()
    count += 1
    count

if 1 <= next_val() <= 10
    print("call count: {count}")   // call count: 1

Line-by-line:

• 0 <= x <= 100 — reads exactly like the math notation it mirrors. No and required.
• 1 <= next_val() <= 10 — the compiler evaluates the middle term once, stores it, and reuses the stored value for both comparisons — count ends at 1, proving next_val() ran exactly once.

For-in inline filter

Adding if CONDITION right after the iterable filters elements inline, before they ever reach the loop body — no separate filter() call and no extra indentation level.

items = [-3, 5, -1, 8, 0, 2]

for x in items if x > 0
    print(x)              // only positive items: 5, 8, 2

// Exactly equivalent to, but without the extra indentation level:
for x in items
    if x > 0
        print(x)

Line-by-line:

• for x in items if x > 0 — the if after the iterable is a filter clause, not a nested statement. Only elements that pass flow into the loop body.
• This is sugar — the compiler generates the same code as the nested-if version. Use the inline form when the filter is one simple condition.
• vs filter(items, x => x > 0) — filter() builds a new list before the loop starts. for x in items if x > 0 tests each element as it's produced and never allocates an intermediate list.

range_inclusive — when you genuinely need both ends

The .. operator is exclusive of its right bound (see the note above and Chapter 36) — that's the correct, Python-style default for most loops and slices. When the problem itself has an inclusive boundary — days 1 through 31, dice faces 1 through 6, a countdown that must include zero — reach for the range_inclusive(a, b) builtin instead of writing a..b + 1 by hand. Both forms visit the same values; range_inclusive says what it means at the call site instead of relying on the reader to silently apply the + 1 translation every time.

// Both ends inclusive — visits 1, 2, 3, 4, 5
for i in range_inclusive(1, 5)
    print(i)
// 1 2 3 4 5

// The equivalent using the exclusive `..` operator — you must remember the + 1
for i in 1..6
    print(i)
// 1 2 3 4 5 — same result, but the "6" only makes sense once you recall .. excludes it

// range_inclusive is a real list, not just loop syntax
days = range_inclusive(1, 31)
print(len(days))          // 31

5. Functions

What is this? Functions are the primary unit of code reuse. Declared with fn. The last expression in the body is the return value — no return keyword needed. Parameters don't need type annotations. Functions are first-class values — you can store them in variables and pass them to other functions.

Basic function syntax

fn add(a, b)
    a + b

print(add(3, 4))    // 7

Line-by-line breakdown:

• fn add(a, b) — declares a function named add with two parameters a and b. No types written — the compiler infers them from the call site. In Java this would be int add(int a, int b). In NOVA: just fn add(a, b).
• a + b — the body is indented one level (4 spaces). This is the only statement in the body. Because it is the last expression, its value is automatically the return value. No return keyword needed. This is the same as Rust, Ruby, and Kotlin.
• print(add(3, 4)) — calls add with arguments 3 and 4. The function computes 3 + 4 = 7 and returns 7. print outputs 7.

The risk of skipping types on public functions

An untyped parameter isn't checked against "any reasonable type" — it's checked against nothing until a call site fixes it. For a private helper only your own file calls, that's harmless: every call site is right there to read. For a function OTHER modules call, an untyped parameter silently accepts whatever shape a caller happens to pass, and the mismatch surfaces as a runtime failure deep inside the function body — far from the call site that actually got it wrong. The same risk applies to return types: if a function has no -> T annotation and its return paths produce genuinely different shapes, the compiler doesn't reject the conflict — it silently widens the inferred return type to any, and every caller loses type checking on the result without being told.

// UNTYPED public function — looks fine from inside this file...
fn compute_discount(price, pct)
    price * (1.0 - pct / 100.0)

// ...but nothing stops a caller from passing the wrong shape:
// compute_discount("99.99", 10)   // no compile error — misbehaves at runtime instead

// TYPED public function — the same mistake is caught immediately, at the call site
fn compute_discount_safe(price: float, pct: float) -> float
    price * (1.0 - pct / 100.0)

print(compute_discount_safe(99.99, 10.0))    // 89.991
// compute_discount_safe("99.99", 10.0)  // compile error: expected float, got string

// No -> annotation, and the two branches return DIFFERENT shapes
fn parse_setting(raw)
    if raw == "on"
        true            // bool
    else
        raw              // string — the compiler widens the inferred return type to `any`

setting = parse_setting("on")
print(setting)          // true

Explicit return — early exit

fn divide(a, b)
    if b == 0
        return err("division by zero")
    ok(a / b)

print(divide(10, 3))   // Ok(3)
print(divide(10, 0))   // Err(division by zero)

Line-by-line:

• if b == 0 — guards against division by zero.
• return err("division by zero") — return exits the function immediately with an error value. Without return, the function would fall through to the last line.
• ok(a / b) — the last expression is the return value when b != 0. ok() wraps the result in a success value.

Default parameters

fn greet(name, greeting = "Hello")
    print("{greeting}, {name}!")

greet("Alice")                // Hello, Alice!
greet("Bob", "Good morning")  // Good morning, Bob!

Default parameters must come after required parameters. If you provide the second argument, it overrides the default.

Optional parameter sugar (T?)

A parameter written p: T? is shorthand for p: Option<T> — it documents, right in the signature, that the caller may legitimately have nothing meaningful to pass. This is a different tool from the default-parameter-value form above: a default value (greeting = "Hello") is a concrete fallback the compiler substitutes automatically when an argument is OMITTED entirely. An optional parameter is Option-typed — the caller passes some(x) or none() explicitly, so "nothing was provided" becomes a real, type-checked case the function body has to handle, not a value quietly standing in for it.

fn greet(name: string?) -> string
    "Hello, " + (name ?? "stranger") + "!"

print(greet(some("Alice")))   // Hello, Alice!
print(greet(none()))          // Hello, stranger!

Line-by-line:

• name: string? — name has type Option<string>, not a bare string. Inside the body you must unwrap it before using it as a plain string — here with ?? to supply a fallback.
• name ?? "stranger" — if name is some(x), this yields x; if it's none(), it yields "stranger". See Chapter 9 for the full ??/Option story.

Multiple return values via structs

NOVA has real tuples — a literal like (a, b, c), with let (a, b, c) = ... destructuring and positional patterns in match (see Chapter 8, "Tuple patterns in match"). For return values, though, prefer a struct (named fields are self-documenting) — a tuple or list works for quick, throwaway local use:

// Preferred: struct (self-documenting, fields have names)
type DivResult
    quotient:  int
    remainder: int

fn divmod(a, b)
    DivResult { quotient: a / b, remainder: a % b }

r = divmod(17, 5)
print("17 / 5 = {r.quotient} remainder {r.remainder}")
// Output: 17 / 5 = 3 remainder 2

// Alternative: list (fields unnamed — only for quick local use)
fn minmax(items)
    lo = items[0]
    hi = items[0]
    for x in items
        if x < lo: lo = x
        if x > hi: hi = x
    [lo, hi]

result = minmax([3, 1, 4, 1, 5, 9])
print("min={result[0]}, max={result[1]}")   // min=1, max=9

Closures (anonymous functions)

Closures are functions without a name. Useful when you need a short function to pass to map(), filter(), or any other higher-order function. NOVA has three closure forms:

// Form 1: Arrow — single parameter, single expression
double = x => x * 2
print(double(5))    // 10

// Form 2: Arrow — multiple parameters (wrap in parentheses)
add = (a, b) => a + b
print(add(3, 4))    // 7

// Form 3: Block body — multiple statements, use fn keyword
process = fn(x)
    y = x * 2
    y + 1           // last expression is the return value
print(process(5))  // 11

Line-by-line breakdown of Form 1:

• double = x => x * 2 — creates a closure that takes one parameter x and returns x * 2. The => arrow separates the parameter from the body. This is similar to JavaScript's x => x * 2 or Python's lambda x: x * 2. The closure is stored in the variable double and can be called like any function.
• When you call double(5), the compiler substitutes x = 5 and evaluates 5 * 2 = 10.

Line-by-line breakdown of Form 3:

• process = fn(x) — the block-body form starts with fn(parameters). No name — it is anonymous. The body is indented below, just like a regular function.
• y = x * 2 — first statement: computes x * 2 and stores in y.
• y + 1 — last expression in the closure. Its value is the return value. For process(5): y = 10, then returns 10 + 1 = 11.

Two more closure forms: bar-lambda and multi-line block-lambda

Beyond the arrow form (x => expr) and the fn(x) ... block form shown above, NOVA accepts a fourth spelling — bar-lambda, |x| expr — familiar to anyone coming from Ruby or Rust. It compiles to the exact same closure as the arrow form; which one you reach for is purely a matter of house style or matching whatever syntax your team already knows.

// Bar-lambda: identical meaning to x => x + 1
inc = |x| x + 1
print(inc(5))            // 6

// Multiple parameters, comma-separated between the bars
add = |a, b| a + b
print(add(3, 4))         // 7

// Zero parameters — empty bars
always_true = || true
print(always_true())    // true

Separately, when a callback passed directly as a function CALL argument needs more than one statement, write the parameter(s) followed by => and an indented block on the following lines — no fn keyword needed. The compiler lifts the block into a real nested function that still captures the enclosing scope, so it behaves exactly like a named closure, just spelled inline:

fn run_with_logging(label, action)
    print("start: {label}")
    result = action()
    print("done: {label}")
    result

// Multi-line body — only recognized directly inside a call's argument list
total = run_with_logging("batch", () =>
    subtotal = 10 + 20
    subtotal + 5
)
print(total)                // 35

Closures capture by value — not by reference

x = 10
f = fn() print(x)
x = 20              // change x AFTER creating the closure
f()                 // prints 10, NOT 20 — closure captured x's value at creation

Line-by-line breakdown:

• x = 10 — sets x to 10.
• f = fn() print(x) — creates a closure that prints x. At this moment, x is 10. The closure captures a copy of 10. It now permanently remembers x = 10 regardless of what happens to the variable x later.
• x = 20 — changes the variable x to 20. The closure f already captured the old value and does not see this update.
• f() — calls the closure. Prints 10, not 20.

Why this matters — the Python closure bug:

# Python — this is a classic, real bug:
funcs = []
for i in range(5):
    funcs.append(lambda: print(i))
for f in funcs:
    f()   # prints 4, 4, 4, 4, 4 — NOT 0, 1, 2, 3, 4!
# All closures share the SAME `i` variable, which ends at 4

// NOVA — capture by value makes this bug impossible:
funcs = []
for i in 0..4
    push(funcs, fn() print(i))   // each closure captures its OWN copy of i
for f in funcs
    f()   // prints 0, 1, 2, 3, 4 — correct!

A fourth form: multi-line lambda in argument position

Form 3 above (fn(x) ... body ...) is single-expression-bodied even when it's the whole point of the closure — written as a bare fn(...) value, it takes exactly one expression, full stop, in every position. But when a closure is written directly as a call argument using the => arrow, NOVA accepts a genuine multi-line, multi-statement body — not just the one-line x => expr from Form 1. Write the arrow, then a newline, then an indented block exactly like a function body; the compiler lifts it into a real nested named function behind the scenes, so it still captures the enclosing scope like every other closure form, and it nests: a block lambda can contain another block lambda.

fn apply(n, f)
    f(n)

fn main()
    base = 100

    // arrow + newline + indented block — multiple statements, still captures `base`
    result = apply(5, x =>
        scaled = x * 2
        boosted = apply(scaled, y =>
            bonus = y + base       // nested block lambda — also captures `base`
            bonus
        )
        boosted
    )
    print(result)

Line-by-line breakdown:

• apply(5, x => ...) — the outer closure receives x = 5, computes scaled = 10, then calls apply again with a second, nested block lambda.
• The inner closure receives y = 10 and computes bonus = y + base = 110 — it reads base from the outermost scope even though it's nested two closures deep, exactly as any closure would.
• boosted ends up 110; the outer closure's last line, boosted, is its return value, so result is 110.

This exact shape is what lets NOVA route tables read naturally in a single call: a router-building function whose closure argument spans many lines, one per route registration, instead of forcing every route handler into its own separate named function just to satisfy the parser.

Higher-order functions: map, filter, reduce

A higher-order function takes another function as a parameter (or returns one). This lets you write general-purpose code customizable by the caller. The three built-in higher-order functions you'll use constantly:

map — transform every element:

nums = [1, 2, 3, 4, 5]
squares = map(nums, x => x * x)
print(squares)   // [1, 4, 9, 16, 25]

• map(nums, x => x * x) — takes a list and a function, applies the function to every element, returns a new list. Think of it as a conveyor belt: each item goes in, gets transformed, comes out. The original nums list is not modified.
• Step by step: 1*1=1, 2*2=4, 3*3=9, 4*4=16, 5*5=25 → [1, 4, 9, 16, 25]

filter — keep only elements that pass a test:

nums = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
evens = filter(nums, x => x % 2 == 0)
print(evens)     // [2, 4, 6, 8, 10]

• filter(nums, x => x % 2 == 0) — takes a list and a predicate (a function returning true/false). Returns a new list with only elements where the predicate returned true. The closure x % 2 == 0 tests if x is even.

reduce — combine all elements into a single value:

nums = [1, 2, 3, 4, 5]
total = reduce(nums, 0, (acc, x) => acc + x)
print(total)     // 15

• reduce(nums, 0, (acc, x) => acc + x) — takes a list, an initial value (the "accumulator"), and a function. Applies the function step by step: start acc=0, then acc=0+1=1, then acc=1+2=3, then acc=3+3=6, then acc=6+4=10, then acc=10+5=15. Returns the final accumulator.

Chaining map → filter → reduce:

nums = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

// Square all numbers, keep only squares > 20, sum them
// Step 1: map squares → [1, 4, 9, 16, 25, 36, 49, 64, 81, 100]
// Step 2: filter > 20 → [25, 36, 49, 64, 81, 100]
// Step 3: sum → 355
result = reduce(
    filter(map(nums, x => x * x), x => x > 20),
    0, (acc, x) => acc + x
)
print(result)    // 355

Writing your own higher-order function

fn apply_twice(f, x)
    f(f(x))

print(apply_twice(x => x + 1, 5))    // 7  — f(f(5)) = f(6) = 7
print(apply_twice(x => x * 2, 3))    // 12 — f(f(3)) = f(6) = 12

• fn apply_twice(f, x) — f is a parameter that holds a function. The compiler infers it is a function because you call it with f(...) inside the body.
• f(f(x)) — calls f on x, then calls f again on the result. For apply_twice(x => x + 1, 5): first call f(5) = 6, second call f(6) = 7.

Sorting with custom comparators

The built-in sort_by function accepts a function that extracts the sort key from each element. This lets you sort any list by any field:

type Student
    name:  string
    grade: int
    gpa:   float

students = [
    Student { name: "Carol", grade: 11, gpa: 3.7 },
    Student { name: "Alice", grade: 10, gpa: 3.9 },
    Student { name: "Bob",   grade: 12, gpa: 3.5 }
]

// Sort by name (alphabetical)
by_name = sort_by(students, s => s.name)
for s in by_name: print("{s.name}")
// Alice, Bob, Carol

// Sort by GPA (highest first) — negate to reverse
by_gpa_desc = sort_by(students, s => -s.gpa)
for s in by_gpa_desc: print("{s.name}: {s.gpa}")
// Alice: 3.9, Carol: 3.7, Bob: 3.5

// Sort by grade, then by name within same grade
by_grade = sort_by(students, s => s.grade)
for s in by_grade: print("Grade {s.grade}: {s.name}")
// Grade 10: Alice, Grade 11: Carol, Grade 12: Bob

Line-by-line breakdown:

• sort_by(students, s => s.name) — sorts by whatever the key function returns. Here the key is a string, so sort is alphabetical. The key function receives each element and returns the comparison key.
• sort_by(students, s => -s.gpa) — negating a float reverses the sort order. Highest GPA becomes the smallest negative number, so it appears first after sorting ascending. This is simpler than a separate sort_desc function.
• Sort is stable — when two elements have equal keys, they remain in their original relative order. This is why sorting by grade twice (first by name, then by grade) gives you a secondary sort by name within each grade.

Function composition — building pipelines

Function composition is the practice of combining two functions into one: the output of f becomes the input to g. In NOVA you can express this directly or build a compose utility:

// Manual composition: apply steps one at a time
data = ["  Alice  ", "BOB", "  carol", "DAVE  "]

normalized = map(
    filter(
        map(data, s => lower(trim(s))),     // step 1: trim whitespace, lowercase
        s => len(s) > 0                       // step 2: remove empty strings
    ),
    s => s[0] + slice(s, 1, len(s))          // step 3: capitalize first letter
)
print(normalized)    // ["Alice", "Bob", "Carol", "Dave"]

// Named step functions — more readable for complex pipelines
fn normalize(s)   lower(trim(s))
fn not_empty(s)   len(s) > 0
fn capitalize(s)  s[0] + slice(s, 1, len(s))

result = map(filter(map(data, normalize), not_empty), capitalize)
print(result)    // ["Alice", "Bob", "Carol", "Dave"]

The named-step version is more readable: each step's name tells you exactly what it does. The compiler inlines small functions, so there's no performance penalty for breaking the pipeline into named pieces.

Recursion

fn factorial(n)
    if n <= 1
        return 1
    n * factorial(n - 1)

print(factorial(10))    // 3628800

fn fibonacci(n)
    if n <= 1: return n
    fibonacci(n - 1) + fibonacci(n - 2)

print(fibonacci(10))    // 55

Named functions vs closures — when to use which

Returning functions — function factories

Functions are first-class values in NOVA. A function can return another function. This pattern is called a "function factory" or "closure factory." It is a clean alternative to configuration objects or classes when you need to create customized behavior:

fn make_adder(n)
    fn(x)
        x + n    // captures n from the outer scope

add5  = make_adder(5)
add10 = make_adder(10)
print(add5(3))    // 8  (3 + 5)
print(add10(3))   // 13 (3 + 10)
print(add5(add10(0)))  // 15 (0 + 10 = 10, then 10 + 5 = 15)

Line-by-line breakdown:

• fn make_adder(n) — outer function takes n, the "base" value. This is the factory — calling it produces a customized adder function.
• fn(x) x + n — the inner function is the return value of make_adder. It closes over n from the outer scope. Each call to make_adder creates a new closure with its own captured copy of n.
• add5 = make_adder(5) — calls the factory with n = 5. The result is a function that adds 5 to its argument. The closure permanently remembers n = 5.
• add10 = make_adder(10) — a separate call creates a separate closure with n = 10. add5 and add10 are independent — changing one does not affect the other.
• add5(3) — calls the closure with x = 3. Evaluates 3 + 5 = 8.

Function factories for validation:

// Factory: creates a function that tests if a number is in a range
fn in_range(lo, hi)
    fn(x)
        x >= lo and x <= hi

is_percentage  = in_range(0, 100)
is_single_byte = in_range(0, 255)
is_temp_celsius = in_range(-273, 1000)

print(is_percentage(75))     // true
print(is_percentage(150))    // false
print(is_single_byte(200))   // true

// Use them with filter — the predicate is already built, no lambda needed
scores = [45, 72, 110, 88, -5, 95]
valid  = filter(scores, is_percentage)
print(valid)    // [45, 72, 88, 95]

Why this pattern matters: In Python you'd write lambda x: 0 <= x <= 100 inline at each use site — readable for one use, repetitive for many. In Java you'd write a full class or interface. In NOVA, in_range(0, 100) is a reusable, named, testable function. Pass it to filter, map, or any higher-order function that expects a predicate.

How NOVA compares to other languages for higher-order functions:

Real-world functions example — a text processing library

Here is a complete example of functions working together to build a small, reusable text processing library. Notice how each function does exactly one thing, and larger operations are composed from smaller ones:

// text_utils.nova — a small text processing library

// Primitives — each does exactly one thing
fn normalize(s)   lower(trim(s))
fn not_empty(s)   len(s) > 0
fn word_count(s)  len(split(trim(s), " "))

// Composed from primitives — does more complex work
fn clean_lines(lines)
    filter(map(lines, normalize), not_empty)

fn word_frequency(text)
    words = split(lower(text), " ")
    freq = {}
    for w in words
        w = trim(w)
        if len(w) > 0
            if contains(freq, w)
                freq[w] += 1
            else
                freq[w] = 1
    freq

fn top_words(freq, n)
    pairs = []
    for word, count in freq
        push(pairs, [count, word])
    sorted = sort_by(pairs, p => -p[0])    // sort by count descending
    slice(sorted, 0, min(n, len(sorted)))   // take top N

// Using the library
text = "to be or not to be that is the question to be is the answer"
freq = word_frequency(text)
top = top_words(freq, 3)
for pair in top
    print("{pair[1]}: {pair[0]}")
// to: 3
// be: 3
// is: 2

lines = ["  Hello World  ", "", "  NOVA is great", "   "]
cleaned = clean_lines(lines)
print(cleaned)   // ["hello world", "nova is great"]

Design principles illustrated here:

• Single responsibility: Each function does exactly one thing. normalize only trims and lowercases. not_empty only tests length. This makes each function easy to test and reuse.
• Composition over complexity: clean_lines is just filter(map(...)) — no new logic, just combining existing functions. Reading it tells you exactly what it does.
• No mutation: Every function returns a new value. word_frequency builds a new dict rather than modifying one passed in. This makes functions safe to use from multiple places.
• First-class functions as parameters: sort_by(pairs, p => -p[0]) — the sort key is a closure that negates the count to get descending order. sort_by doesn't know or care what the key function does — it just calls it.

Pipe operator |>

The pipe operator takes the value on its left and inserts it as the first argument of the function call on its right. It turns deeply nested calls — which read inside-out — into a left-to-right sequence that reads in the same order the computation actually happens.

fn double(x) x * 2
fn square(x) x * x

result = 5 |> double |> square
print(result)         // 100

// Same computation, nested instead of piped — reads right-to-left:
result2 = square(double(5))
print(result2)        // 100 — identical result

// Pipes shine with a multi-step HOF pipeline:
v = [1, 2, 3, 4, 5]
    |> filter(fn(x) x > 2)
    |> map(fn(x) x * 10)
print(v)                // [30, 40, 50]

// The piped value is inserted as the FIRST argument;
// any arguments already in the parens shift right:
fn add(a, b) a + b

r = 3 |> add(4) |> double |> add(1)
print(r)                // 15

Line-by-line:

• 5 |> double |> square — 5 flows into double first (double(5) = 10), then 10 flows into square (square(10) = 100). Read top-to-bottom or left-to-right — never inside-out.
• |> filter(fn(x) x > 2) — when the right-hand side already has arguments in parens, the piped value slots in before them: v |> filter(pred) becomes filter(v, pred), matching every existing NOVA HOF signature (collection first, then the closure).
• 3 |> add(4) — becomes add(3, 4), not add(4, 3). The piped value is always argument zero; whatever you wrote inside the parens shifts one position to the right.

UFCS — Uniform Function Call Syntax

Any function whose first parameter matches the type of x can be called as a method on x: x.f(rest...) is rewritten to f(x, rest...) at compile time. This is purely a call-syntax rewrite — there's no new dispatch mechanism, no vtable, nothing at runtime.

// Any function f(x, ...) can be called as x.f(...)
data = [-2, 5, -8, 3, 9, -1]
result = data.filter(fn(x) x > 0).map(fn(x) x * 2).sort()
print(result)     // [6, 10, 18]

// Extension methods on any type: Type__method, called as x.method()
fn int__double(x: int) -> int
    x * 2
r = 3.double()
print(r)            // 6

fn string__shout(s: string) -> string
    upper(s) + "!!!"
print("hello".shout())   // HELLO!!!

Line-by-line:

• data.filter(...).map(...).sort() — filter, map, and sort all already take the collection as their first parameter, so UFCS turns the nested form sort(map(filter(data, ...), ...)) into a left-to-right chain that reads in execution order.
• fn int__double(x: int) -> int — the Type__method naming convention marks this as an extension method on int. It's an ordinary top-level function; the compiler recognizes the naming pattern and makes it callable as 3.double().
• Resolution order: struct method → module function → builtin. This lets you add methods to any type — including builtins like int and string — without ever touching their source.

Named arguments

Every parameter's name can be used as a keyword at the call site — name: value or name = value (both spellings work identically). This lets a call be self-documenting and lets arguments be given in any order.

fn greet(name, greeting = "Hello")
    greeting + ", " + name + "!"

print(greet("Alice"))                        // Hello, Alice!
print(greet(greeting: "Yo", name: "Eve"))     // Yo, Eve!
print(greet(name = "Bob", greeting = "Hey"))    // Hey, Bob!

Line-by-line:

• greet("Alice") — positional call. greeting is omitted, so it falls back to its default, "Hello".
• greet(greeting: "Yo", name: "Eve") — named arguments. Order at the call site no longer has to match declaration order.
• greet(name = "Bob", greeting = "Hey") — NOVA accepts = as an alternative to : for naming an argument. They mean exactly the same thing.

Variadic parameters (T...)

A trailing parameter typed T... collects any number of extra arguments into an ordinary list[T]. It must be the last parameter.

fn sum_all(xs: int...) -> int
    total = 0
    for x in xs
        total += x
    total

print(sum_all(1, 2, 3, 4))    // 10
print(sum_all(7))             // 7
print(sum_all())              // 0 — zero arguments is valid

Line-by-line:

• xs: int... — the ... after the type marks xs as variadic. Inside the function body, xs is a plain list[int].
• Only the last parameter may be variadic — fn f(a, b: int...) is valid; fn f(a: int..., b) is not.

Where clause

A where clause attaches local bindings to the single statement right before it. The bindings are computed first, then the expression uses them — read a where clause right-to-left: "compute these, then evaluate that."

result = x * y where x = 6, y = 7
print(result)      // 42

area = width * height where
    width = 10
    height = 20
print(area)        // 200

Line-by-line:

• x * y where x = 6, y = 7 — single-line form: comma-separated bindings.
• width * height where followed by indented bindings — multi-line form.
• Scope: width and height exist only for the statement they're attached to — they are not visible on the next line. This is Haskell's where, not a regular assignment.

Multi-clause functions with when guards

You can declare the same function name multiple times, each with a different when guard. NOVA tries each clause top-to-bottom and runs the body of the first one whose guard passes — a final clause with no when acts as the catch-all.

fn classify(n) when n < 0
    "negative"
fn classify(n) when n == 0
    "zero"
fn classify(n)
    "positive"

print(classify(-5))   // negative
print(classify(0))    // zero
print(classify(7))    // positive

Line-by-line:

• Three fn classify(n) heads, same name and arity — since each carries (or omits) a when guard, NOVA registers them as clauses of one function.
• when n < 0 — a guard. At the call site, NOVA evaluates each clause's guard in declaration order and dispatches to the first one that passes.
• The final fn classify(n) with no when is the catch-all. Order matters: clauses are tried top-to-bottom.

6. Structs

What is this? Structs are how you create custom data types with named fields. They are NOVA's equivalent of Java classes (but without inheritance), Go structs, Rust structs, or Python dataclasses. Declare with type. Access fields with dot notation. Methods are functions defined with the Type.method prefix.

Declaring a struct

type Point
    x: float
    y: float

type User
    name:  string
    age:   int
    email: string

Line-by-line:

• type Point — declares a new struct type named Point. Type names must start with an uppercase letter.
• x: float — declares a field named x of type float. Type annotations are required on struct fields — this is one of the few places NOVA asks you to write types explicitly.
• Each field goes on its own indented line under the type declaration.

THE most important rule in NOVA: lowercase field types

This single rule has the largest impact on your program's performance:

// FAST: lowercase type names → native CPU math → C-level performance
type FastPoint
    x: float    // lowercase float → stored as 64-bit IEEE 754 number
    y: float

// SLOW: capital type names → dynamic dispatch → ~150× slower
type SlowPoint
    x: Float    // capital Float → boxed value with runtime type checks
    y: Float

Why this matters — the numbers:

• x: float → compiler generates native CPU instructions: fmul, fadd. Time for 1M dot products: ~2ms.
• x: Float → compiler generates calls to nova_rt_mul() which checks the type at runtime before doing the operation. Time for 1M dot products: ~300ms.
• That is a 150× difference for the exact same algorithm.

Real consequences: A physics simulation at 60fps with 10,000 particles requires ~16ms per frame. FastPoint achieves this. SlowPoint would take ~2,400ms per frame — a slideshow.

Complete list of lowercase type names for struct fields: int, float, string, bool, list. Always use these, never their capitalized variants.

Constructing a struct

p = Point { x: 3.0, y: 4.0 }
u = User { name: "Alice", age: 30, email: "alice@example.com" }

// Access fields with dot notation
print(p.x)       // 3.0
print(u.name)    // Alice

// Mutate fields
p.x = 5.0
print(p.x)       // 5.0

// NOVA auto-renders structs for print — no toString() needed
print(p)         // Point{x: 5.0, y: 4.0}

Construction rules:

• Every field must be provided — you cannot omit any. This prevents the bug of creating a User with no email and crashing later.
• Field names in { } must match the declared names exactly.
• Giving an unknown field name or wrong type is a compile error, not a runtime crash.

// These are ALL compile errors — caught before your program runs:
p = Point { x: 3.0 }               // missing field 'y'
p = Point { x: 3.0, y: 4.0, z: 5.0 } // unknown field 'z'
p = Point { x: "hello", y: 4.0 }   // wrong type for 'x'

Methods

Methods are functions that belong to a struct type. Define them outside the type block using the TypeName.method_name prefix. Inside a method, self automatically refers to the instance:

type Circle
    radius: float

fn Circle.area() -> float
    3.14159 * self.radius * self.radius

fn Circle.circumference() -> float
    2.0 * 3.14159 * self.radius

fn Circle.scale(factor: float) -> Circle
    Circle { radius: self.radius * factor }    // returns NEW circle, does not modify self

c = Circle { radius: 5.0 }
print(c.area())             // 78.53975
print(c.circumference())    // 31.4159
big = c.scale(2.0)
print(big.area())           // 314.159

Line-by-line:

• fn Circle.area() -> float — the Circle. prefix says this method belongs to Circle. The -> float declares the return type. Inside this method, self automatically refers to the Circle instance the method was called on. You do NOT declare self as a parameter — NOVA adds it automatically.
• 3.14159 * self.radius * self.radius — self.radius reads the radius field of whichever instance this method was called on. Last expression = return value.
• fn Circle.scale(factor: float) -> Circle — methods can take extra parameters. This returns a NEW Circle with the scaled radius. It does NOT modify the original — c.radius stays 5.0 after calling c.scale(2.0).

How methods compare to other languages:

Operator dispatch — giving your types [], for..in, (), and +

NOVA recognizes a small set of method and function names by convention and wires them straight into operator syntax — no separate operator keyword, no interface to implement. Define index(self, i) on a type and x[i] calls it. Define iter(self) and for item in x calls it to get the thing that actually gets iterated. Define call(self, args...) and x(args) calls your type as if it were a function. And define a free function named Type__add, Type__sub, Type__mul, Type__eq, or Type__lt and the matching operator (+, -, *, ==, <) dispatches to it — the same Type__name naming convention UFCS already uses for extension methods (Chapter 5).

type Grid
    cells: list

fn Grid.index(i) -> int
    self.cells[i]

fn Grid.iter()
    self.cells

g = Grid { cells: [10, 20, 30, 40] }
print(g[2])                // 30 — calls Grid.index(g, 2)

for cell in g            // calls Grid.iter(g), then iterates the list it returns
    print(cell)
// 10 20 30 40

type Multiplier
    factor: int

fn Multiplier.call(x: int) -> int
    x * self.factor

double = Multiplier { factor: 2 }
print(double(21))         // 42 — calls Multiplier.call(double, 21)

type Vec2
    x: float
    y: float

fn Vec2__add(a: Vec2, b: Vec2) -> Vec2
    Vec2 { x: a.x + b.x, y: a.y + b.y }

v = Vec2 { x: 1.0, y: 2.0 } + Vec2 { x: 3.0, y: 4.0 }   // calls Vec2__add
print(v)                // Vec2{x: 4.0, y: 6.0}

Compare: this is the same idea as Python's __getitem__/__iter__/__call__/__add__ dunder protocol, Rust's Index/Iterator/Fn/Add traits, and C++'s operator[]/operator+ overloads — but resolved purely by name, with no trait to declare and no class to inherit from.

Structs as values — copy semantics

a = Point { x: 1.0, y: 2.0 }
b = a              // b is a COPY of a — separate data
b.x = 99.0
print(a.x)         // 1.0 — a is unchanged
print(b.x)         // 99.0

Structs are value types — when you assign or pass a struct, the data is copied. Lists and dicts are reference types — when you assign them, both variables point to the same data.

Nested structs

type Line
    start:  Point
    end_pt: Point

fn Line.length() -> float
    dx = self.end_pt.x - self.start.x
    dy = self.end_pt.y - self.start.y
    sqrt(dx * dx + dy * dy)

line = Line { start: Point { x: 0.0, y: 0.0 }, end_pt: Point { x: 3.0, y: 4.0 } }
print(line.length())    // 5.0 (Pythagorean theorem: sqrt(9 + 16))

Traits — shared behavior across types

A trait declares a set of methods that a type must provide — a method can be left bodiless (a required signature) or given a default body that implementing types inherit unless they override it. A type opts in explicitly, on its own declaration line — type TypeName : TraitName — there is no separate impl block, and NOVA does not infer conformance just because a type happens to have matching methods:

trait Shape
    fn area(self) -> float
    fn name(self) -> string

type Circle : Shape
    radius: float

type Rectangle : Shape
    width:  float
    height: float

fn Circle.area()   -> float  = 3.14159 * self.radius * self.radius
fn Circle.name()   -> string = "circle"

fn Rectangle.area() -> float  = self.width * self.height
fn Rectangle.name() -> string = "rectangle"

// A function accepting ANY type that satisfies the Shape trait
fn describe(s: Shape) -> string
    "{s.name()} with area {s.area()}"

c = Circle { radius: 5.0 }
r = Rectangle { width: 4.0, height: 6.0 }
print(describe(c))    // circle with area 78.53975
print(describe(r))    // rectangle with area 24.0

How NOVA traits differ from other languages:

• vs Java interfaces: Java requires class Circle implements Shape — a separate keyword on the class. NOVA folds the same idea into the type's own declaration line, type Circle : Shape — one declaration, not two — but it is still explicit: the compiler does not treat Circle as a Shape just because it happens to have matching methods.
• vs Rust traits: Rust requires a separate impl Shape for Circle { ... } block. NOVA has no impl keyword at all — conformance is declared once, inline, on the type itself: type Circle : Shape. Same nominal requirement as Rust, less ceremony — and because there is no free-standing impl block, you cannot attach a trait to a type you don't own the declaration of (a builtin like int, or a struct from another module).
• vs Go interfaces: Go is structural — any type with matching methods satisfies an interface automatically, no declaration anywhere. NOVA is not structural here: a generic <T: Shape> bound or a Shape-typed parameter only accepts types that wrote : Shape on their own declaration line.

Default method bodies in traits

A trait method can be written two ways. A bare signature — no indented body — means every conforming type MUST supply its own implementation. A signature WITH an indented body becomes a default: any conforming type that doesn't define that method inherits the trait's version unchanged. A type only writes its own version when its behavior genuinely differs from the shared default.

trait Describable
    fn name() -> string
    fn describe() -> string
        "I am " + self.name()

type Dog : Describable
    breed: string

fn Dog.name() -> string
    "Dog(" + self.breed + ")"

type Cat : Describable
    breed: string

fn Cat.name() -> string
    "Cat(" + self.breed + ")"

fn Cat.describe() -> string
    "A very independent " + self.name()

let d = Dog { breed: "Labrador" }
let c = Cat { breed: "Siamese" }

print(d.describe())   // I am Dog(Labrador) -- uses the trait's default, Dog never wrote its own
print(c.describe())   // A very independent Cat(Siamese) -- Cat overrides it

Line-by-line:

• fn name() -> string inside the trait has no body — it's abstract. Both Dog and Cat must (and do) define their own Type.name(), or the compiler rejects the : Describable conformance as incomplete.
• fn describe() -> string inside the trait DOES have a body — it's a default. Dog never defines Dog.describe(), so calling d.describe() runs the trait's own version, which in turn calls self.name() — and because self is a Dog at that call site, it resolves to Dog.name(), not some generic placeholder.
• Cat defines its own Cat.describe(), so that overrides the default entirely — the trait's version is never reached for Cat.

Compare: this is the same idea as Java 8+'s default interface methods (default String describe() { ... }) and Rust's trait default methods (a body written directly inside the trait block). NOVA needs no extra keyword like default — whether the method has an indented body IS the signal, read directly off the trait declaration.

Putting it all together — a geometry library

Here is a complete example that shows how structs, methods, and traits work together to build a real, usable module:

// geometry.nova — a small 2D geometry library

type Vec2
    x: float
    y: float

type Circle
    center: Vec2
    radius: float

type Rect
    min_pt: Vec2
    max_pt: Vec2

// Vec2 methods
fn Vec2.length() -> float
    sqrt(self.x * self.x + self.y * self.y)

fn Vec2.add(other: Vec2) -> Vec2
    Vec2 { x: self.x + other.x, y: self.y + other.y }

fn Vec2.scale(s: float) -> Vec2
    Vec2 { x: self.x * s, y: self.y * s }

fn Vec2.distance_to(other: Vec2) -> float
    dx = self.x - other.x
    dy = self.y - other.y
    sqrt(dx * dx + dy * dy)

// Circle methods
fn Circle.area() -> float
    3.14159 * self.radius * self.radius

fn Circle.contains(pt: Vec2) -> bool
    self.center.distance_to(pt) <= self.radius

// Rect methods
fn Rect.width() -> float
    self.max_pt.x - self.min_pt.x

fn Rect.height() -> float
    self.max_pt.y - self.min_pt.y

fn Rect.area() -> float
    self.width() * self.height()

fn Rect.contains(pt: Vec2) -> bool
    pt.x >= self.min_pt.x and pt.x <= self.max_pt.x and
    pt.y >= self.min_pt.y and pt.y <= self.max_pt.y

// Using the library
origin = Vec2 { x: 0.0, y: 0.0 }
center = Vec2 { x: 3.0, y: 4.0 }
circle = Circle { center: center, radius: 5.0 }

print(center.length())             // 5.0 (distance from origin)
print(origin.distance_to(center)) // 5.0
print(circle.area())              // 78.53975
print(circle.contains(Vec2 { x: 1.0, y: 1.0 }))  // true
print(circle.contains(Vec2 { x: 9.0, y: 9.0 }))  // false

box = Rect { min_pt: Vec2 { x: 0.0, y: 0.0 }, max_pt: Vec2 { x: 10.0, y: 5.0 } }
print(box.area())                            // 50.0
print(box.contains(Vec2 { x: 5.0, y: 3.0 }))  // true
print(box.contains(Vec2 { x: 11.0, y: 3.0 })) // false

Key patterns to notice:

• Methods call other methods: Rect.area() calls self.width() and self.height() — methods are composable.
• Methods accept struct parameters: Vec2.add(other: Vec2) and Circle.contains(pt: Vec2) take struct arguments. The type annotation on parameters in method signatures is required.
• Chained method calls: self.center.distance_to(pt) — self.center is a Vec2, so you can call Vec2.distance_to() on it. Chains read left to right naturally.
• All fields lowercase: x: float, y: float, radius: float. This is why the code runs at C-level speed — native float arithmetic throughout, no boxing, no type checks.

Structs as data containers — a complete product catalog example

Structs shine as data containers. Here is a realistic example building a small product catalog — using structs to model domain data, methods to add behavior, and functions to query and transform the collection:

type Product
    name:     string
    price:    float
    quantity: int
    category: string

fn Product.total_value() -> float
    self.price * self.quantity

fn Product.is_in_stock() -> bool
    self.quantity > 0

fn Product.discounted(pct: float) -> Product
    Product { name: self.name, price: self.price * (1.0 - pct / 100.0), quantity: self.quantity, category: self.category }

fn catalog_value(products)
    let total = 0.0
    for p in products
        total += p.total_value()
    total

fn main()
    let catalog = [
        Product { name: "Laptop",     price: 999.99, quantity: 5,  category: "electronics" },
        Product { name: "Headphones", price: 149.99, quantity: 0,  category: "electronics" },
        Product { name: "Desk",       price: 450.00, quantity: 3,  category: "furniture" },
        Product { name: "Chair",      price: 299.00, quantity: 10, category: "furniture" }
    ]

    print("Total value: {catalog_value(catalog)}")    // 9339.95

    // Filtering and transforming are written inline here rather than through
    // filter()/map() or a helper that returns a list — see the callout below
    // for exactly why, and what's actually safe today vs. what to avoid.
    for p in catalog
        if p.is_in_stock()
            print("{p.name}: {p.quantity} in stock")

    let sale = []
    for p in catalog
        if p.category == "electronics"
            push(sale, Product { name: p.name, price: p.price * 0.8, quantity: p.quantity, category: p.category })    // 20% off
    for p in sale
        print("{p.name} on sale: \${p.price}")

Line-by-line breakdown of the key patterns:

• fn Product.total_value() -> float — a method that computes a derived value from the struct's own fields. No arguments needed because the data is already in self. Called per-item inside catalog_value's own loop, this is reliable.
• fn Product.discounted(pct: float) -> Product — returns a NEW Product with a reduced price, functional-style: transform and return, don't mutate self. Reliable when called directly on a single value. The sale loop above builds the discounted Product inline instead of calling it — see the callout just below for why.
• Filtering is a plain if inside a for loop here, not filter(products, p => p.is_in_stock()) — again, see the callout.

Generics

A generic function or type works over any type T without the caller ever writing out a concrete type — the compiler infers T from how the function is called, the same way it infers everything else in NOVA. Type parameters are declared in angle brackets that come before the function name.

fn <T> identity(x: T) -> T
    return x

fn <T, U> my_map(xs: list<T>, f) -> list<U>
    let result = []
    for x in xs
        push(result, f(x))
    return result

type Box<T>
    value: T

Compare: Rust and C# put type parameters after the name (fn identity<T>(x: T)); NOVA puts them before, closer to how a universally-quantified type is written in formal type theory (∀T. T → T) — and it reads as "for any T, define identity."

Constraining a generic with a trait

An unconstrained <T> accepts literally any type — including ones whose values don't support whatever the function body tries to do with them. With no bound, the compiler can only catch a mismatch at the CALL SITE, once T is finally known, which puts the error far from the generic function's own definition. Writing <T: TraitName> instead narrows T to only the types that satisfy that trait, which lets the compiler check the function's BODY against the trait's methods right where the function is defined — the same before-the-name position as an unconstrained type parameter, just with : TraitName added.

trait Comparable
    fn less_than(self, other) -> bool

// Constrained: T must satisfy Comparable — the body can safely call less_than
fn <T: Comparable> smaller(a: T, b: T) -> T
    if a.less_than(b)
        a
    else
        b

type Money
    cents: int

fn Money.less_than(other: Money) -> bool
    self.cents < other.cents

m1 = Money { cents: 500 }
m2 = Money { cents: 250 }
cheaper = smaller(m1, m2)
print(cheaper.cents)         // 250

Struct reflection API (automatic — zero annotation)

Every struct you define automatically gets a set of reflection functions — no @derive, no annotation, no opt-in. The compiler already knows every field name and type at compile time, so it generates these for free.

type Person
    name: string
    age: int
let p = Person("Bob", 30)

field_names(p)              // ["name", "age"]
field_types(p)              // ["string", "int"]
field_get(p, "name")        // "Bob"
type_name(p)                // "Person"
fields(p)                   // ["Bob", 30]

When to use this: writing generic debug/print utilities, building your own serializers, validation frameworks that need to walk arbitrary structs, or ORM-style code that maps struct fields to database columns — all without writing per-type boilerplate.

Compare: Java needs reflection APIs (Class.getFields()) that are verbose and lose compile-time type safety. Python's vars(obj)/__dict__ works but has no static type information behind it. NOVA's reflection is generated by the compiler from real static field types, so field_types(p) is exact, not inferred at runtime from whatever value happens to be stored.

Automatic to_json / from_json

Every struct also auto-generates JSON conversion — to_json, from_json, from_json_safe, from_dict, and from_dict_list — again with zero annotation. from_json_safe returns a Result, so malformed input is a normal Err you handle with match, not a crash.

type User
    name: string
    age: int
let u = User("Ann", 30)
let j = u.to_json()         // {"name":"Ann","age":30}
let j2 = json_stringify(u)  // same

let r: Result<User> = from_json_safe(body)
match r
    Ok(u) => print(u.name)
    Err(e) => print("bad json: " + e)

Compare: Rust requires #[derive(Serialize, Deserialize)] plus the serde crate. Go requires struct tags (`json:"name"`) and still only gets marshal/unmarshal, not a full reflection API. Java needs a library like Jackson with annotations. NOVA needs none of this — every struct is JSON-capable and introspectable the moment you write type.

Automatic type coercion in from_dict

from_dict and from_dict_list build a struct from a plain dict — a database row, an HTTP form body, a CSV record — where every value naturally arrives as a STRING, regardless of what type the struct field actually is. Rather than making you hand-parse each field before construction, from_dict reads the target struct's declared field types and coerces automatically: a field typed int gets parsed as an integer, float gets parsed as a float, and bool accepts common string spellings like "true"/"false" — all before the struct object exists.

type Product
    name:     string
    price:    float
    quantity: int
    on_sale:  bool

// Every value here is a STRING — as if it came from a DB row or a form POST body
row = {"name": "Widget", "price": "19.99", "quantity": "42", "on_sale": "true"}

p = from_dict(row) as Product
print(p.price)             // 19.99 — the string "19.99" was coerced to a float
print(p.quantity + 1)      // 43 — the string "42" was coerced to an int, so + works
print(p.on_sale)           // true — coerced to a real bool, not the string "true"

Universal equality, hashing, and copy — no annotation required

Three more operations work automatically on every value in NOVA — not just structs, and not just the ones covered by the reflection/serialization table above. == performs structural equality (it compares fields recursively, not object identity). hash(v) computes a structural hash that's guaranteed consistent with that equality — equal values always hash equal, which is exactly what's required to use a struct as a dict key or a set member. And copy(v) performs a deep clone: new memory, with zero aliasing to the original. None of the three need an annotation, a trait, or a hand-written method — they fall directly out of the same field and type information the compiler already tracks for every struct.

type Point
    x: float
    y: float

a = Point { x: 1.0, y: 2.0 }
b = Point { x: 1.0, y: 2.0 }
print(a == b)              // true — structural equality: same fields, different objects
print(hash(a) == hash(b))    // true — equal values always hash equal

// copy() forces a deep clone even for REFERENCE types like lists
original = [1, 2, 3]
alias    = original          // lists are reference types — alias points at the SAME list
clone    = copy(original)    // copy() breaks that sharing

push(alias, 4)
push(clone, 99)
print(original)            // [1, 2, 3, 4] — alias shares storage with original
print(clone)               // [1, 2, 3, 99] — clone is fully independent

Universal equality, hashing, and cloning

Three more operations come free on every struct you declare, no annotation required: == for deep structural equality, copy(x) for an independent clone, and hash(x) for a content-derived integer. These are universal runtime operations built into the language itself — not code the compiler generates per type, and not something you reach for by importing a module.

type Point
    x: int
    y: int

let a = Point(1, 2)
let b = Point(1, 2)
print(a == b)                  // true -- compares every field, not object identity
print(a != Point(1, 3))     // true -- differs in y
print(hash(a) == hash(b))       // true -- hash() agrees with == : equal values hash equal

Structs already copy on plain assignment (see "Structs as values" above), so copy() matters most for lists and dicts — NOVA's reference types, where = aliases the same underlying data instead of duplicating it:

let original = [1, 2, 3]
let alias  = original        // NOT a copy -- alias points at the same list
let cloned = copy(original)   // cloned is an independent list

push(alias, 4)
push(cloned, 99)

print(original)    // [1, 2, 3, 4]  -- alias shares storage with original
print(cloned)      // [1, 2, 3, 99] -- untouched by the push through alias

Structural equality, hash, and copy — also automatic, also universal

The reflection API and JSON conversion above cover two-thirds of what @derive would normally exist to generate. The remaining third is three operations that work on every struct exactly the same way, produced directly by the compiler from the struct's own field list — no method to write, no interface to implement, no annotation to remember. == performs a deep, field-by-field structural comparison: two separately-constructed Person values with identical field values are equal. This is never pointer/reference identity — the trap Java's default == and Python's default is both fall into, where two objects that look identical compare unequal because they happen to occupy different memory. hash(v) derives a stable integer hash from every field, with the guarantee that two structurally-equal values always hash equal — the exact invariant Java's equals()/hashCode() contract requires you to maintain by hand, and the exact invariant a forgotten field update breaks in practice. In NOVA you cannot break it, because both operations are generated from the same field list at the same time. copy(v) produces an independent deep clone: every heap-backed field — a nested struct, a list, a dict — is cloned too, not just the top-level struct shell, so mutating the copy can never reach back and corrupt the value you copied it from.

type Point
    x: int
    y: int

let a = Point(1, 2)
let b = Point(1, 2)
let c = a

print(a == b)                // true -- same field values, different objects
print(a == c)                // true -- c is the same object as a

let cloned = copy(a)
cloned.x = 99
print(a.x)                    // 1 -- copy() made an independent clone
print(cloned.x)              // 99
print(hash(a) == hash(b))  // true -- structurally equal values hash equal

Structural cast from a dict — form_as

from_json_safe (above) starts from a JSON string. form_as is the equivalent typed, validating cast that starts from a dict you already have in hand — an HTTP form body, a database row, or any name-keyed {string: string} data — and decodes it into a struct by matching dict keys to field names. Like from_json_safe, the target type comes from the let binding's own type annotation, not from anything written at the call site: let r: Result<T> = form_as(d).

type Signup
    name: string
    age: int
    score: float

let d = {}
d["name"] = "ada"
d["age"] = "30"
d["score"] = "9.5"

let r: Result<Signup> = form_as(d)
match r
    Ok(s) => print("welcome, {s.name} (age {s.age})")
    Err(e) => print("bad form: {e}")

Field handling is total, not all-or-nothing: a key that is missing from the dict, or present with an empty string, decodes to that field's zero value (0, 0.0, false, "") instead of failing the whole cast — the common shape of an optional form field or a NULL-able database column. Only a value that is present, non-empty, and fails to coerce — "age": "not-a-number" into an int field — produces Err, and that error names the offending field so you know exactly which input to reject back to the user.

Type alias and distinct newtype

NOVA has two different ways to give a type a new name, and they mean opposite things. A plain type X = Y alias is transparent — zero cost, and X and Y are fully interchangeable everywhere. A type X = distinct Y newtype is opaque — a genuinely distinct type that will not unify with Y, even though it has the same runtime representation.

// Transparent alias — zero cost, fully interchangeable
type Json = dict<string, any>
type Headers = dict<string, string>

// Distinct newtype — genuinely distinct type, won't unify
type UserId = distinct int
let u = UserId(42)
assert_eq(u.value, 42)
// UserId + int is a type error — must convert explicitly

When to use which: use a plain alias (Json, Headers) purely for readability — you want the shorter name, but never want the type checker to stop you from passing a dict<string,any> wherever a Json is expected. Use distinct when mixing up two values of the same underlying representation would be a real bug — a UserId and a ProductId are both int underneath, but adding them together or passing one where the other is expected should be a compile error, not a runtime data-corruption bug.

Compare: this is the classic "newtype pattern" — Haskell's newtype, Rust's tuple-struct wrapper (struct UserId(i64)), F#'s units-of-measure. NOVA gives you both the zero-ceremony alias AND the type-safe wrapper as one keyword difference (distinct) instead of requiring a full wrapper struct with manual field access.

7. Enums

What is this? Enums (sum types / tagged unions) define a type that can be exactly one of several named variants, each carrying different data. Enums eliminate entire classes of bugs: you can't accidentally mix up a Circle and a Rectangle because the type system tracks which one you have.

Declaring and using enums

enum Shape
    Circle(radius: float)
    Rect(width: float, height: float)
    Triangle(base: float, height: float)

fn area(s)
    match s
        Circle(r)      => 3.14159 * r * r
        Rect(w, h)     => w * h
        Triangle(b, h) => 0.5 * b * h

fn describe(s)
    match s
        Circle(r)      => "circle with radius {r}"
        Rect(w, h)     => "rectangle {w}x{h}"
        Triangle(b, h) => "triangle base={b} height={h}"

fn main()
    shapes = [Circle(5.0), Rect(3.0, 4.0), Triangle(6.0, 8.0)]
    for s in shapes
        print("{describe(s)} has area {area(s)}")
// circle with radius 5.0 has area 78.53975
// rectangle 3.0x4.0 has area 12.0
// triangle base=6.0 height=8.0 has area 24.0

Trap: a variant constructor's value has the VARIANT's own type, not the parent enum's type

Circle(5.0) has static type Circle — not Shape — even though Circle is declared as one variant of the Shape enum above. NOVA's type checker does not implicitly widen a variant value to its parent sum type at a function boundary the way you might expect coming from Rust or TypeScript. This is exactly why area and describe above are written as fn area(s) rather than fn area(s: Shape): annotating the parameter as Shape would reject every individual call site, because the argument you actually pass — Circle(5.0), Rect(3.0, 4.0) — has the variant's own narrower type, not the enum's. Leaving the parameter unannotated lets inference assign it whatever type the call site actually needs; the match inside the function body is what establishes that all of Shape's variants are being handled together.

// WRONG — annotating s: Shape rejects a bare Circle(...) argument: Circle(5.0) has
// type Circle, not Shape, so a call like area(Circle(5.0)) fails to type-check.
// fn area(s: Shape) -> float
//     match s
//         Circle(r) => 3.14159 * r * r
//         ...

// CORRECT — leave the parameter unannotated; inference assigns the right type per call site.
fn area(s)
    match s
        Circle(r)      => 3.14159 * r * r
        Rect(w, h)     => w * h
        Triangle(b, h) => 0.5 * b * h

print(area(Circle(5.0)))

Enums without payload (simple variants)

enum Direction
    North
    South
    East
    West

fn move_player(pos, dir)
    x, y = pos
    match dir
        North => x, y - 1
        South => x, y + 1
        East  => x + 1, y
        West  => x - 1, y

Enums for state machines

enum OrderStatus
    Pending
    Processing(warehouse: string)
    Shipped(tracking: string)
    Delivered
    Cancelled(reason: string)

fn status_message(s)
    match s
        Pending           => "Your order is pending payment"
        Processing(w)     => "Being packed at {w}"
        Shipped(t)        => "On the way! Track: {t}"
        Delivered         => "Delivered. Enjoy!"
        Cancelled(reason) => "Cancelled: {reason}"

Named-field construction

For variants with many fields, you can use named-field syntax for clarity:

// Both are identical — positional vs. named
s1 = Circle(5.0)
s2 = Circle { radius: 5.0 }

r1 = Rectangle(4.0, 6.0)
r2 = Rectangle { width: 4.0, height: 6.0 }   // clearer with many fields

DON'T use dot notation on enum values

This is the most common mistake for newcomers from object-oriented languages:

s = Circle(5.0)

// WRONG: cannot access fields with dot notation
// print(s.radius)    // ERROR — field access not allowed on enums

// CORRECT: use match to extract data
match s
    Circle(r) => print(r)    // 5.0
    _         => print("not a circle")

Enums are not structs. You cannot access fields with . because the compiler does not know at that point which variant the value is. You must use match to tell the compiler which variant to extract from.

When to use enums vs structs

Why enums over dicts? A dict with a "type" field is a common pattern but it's unchecked — the compiler won't catch typos in "Procssing". An enum variant is checked at compile time: Processing(w) with a typo is a compile error, not a runtime surprise.

Recursive enums — tree structures

An enum variant can reference the enum itself. This lets you build recursive data structures — trees, linked lists, expression trees — entirely in NOVA's type system with no pointers or nullable fields.

enum IntList
    Empty
    Cons(head: int, tail: IntList)

fn list_sum(xs)
    match xs
        Empty          => 0
        Cons(h, rest)  => h + list_sum(rest)

// Build a list: 1 -> 2 -> 3 -> Empty
my_list = Cons(1, Cons(2, Cons(3, Empty)))
print(list_sum(my_list))   // 6

// A recursive length function
fn list_len(xs)
    match xs
        Empty         => 0
        Cons(_, rest) => 1 + list_len(rest)

print(list_len(my_list))   // 3

Line-by-line breakdown:

• enum IntList — declares a recursive enum. Empty is the base case (no data). Cons(head, tail) is the inductive case: one integer plus the rest of the list.
• Cons(1, Cons(2, Cons(3, Empty))) — builds a three-element list by nesting constructors. Each Cons holds one value and a reference to the remaining list. This is exactly the singly-linked list data structure, expressed in NOVA's type system rather than with raw pointers.
• match xs — the function recurses on the structure of the list. The Empty arm is the base case — the recursion terminates here, returning 0.
• Cons(h, rest) => h + list_sum(rest) — the recursive arm. The compiler guarantees this match is exhaustive: both Empty and Cons are handled. If you add a third variant to IntList later, the compiler will flag every match on IntList that doesn't handle it.
• Cons(_, rest) in list_len — the underscore _ is a wildcard: "there's a head field but I don't care what it is." The compiler still checks that the pattern is structurally correct; it just discards the head value.

Vs Python: Python has no recursive algebraic types. A Python programmer would use a class with a next field that can be None. The None is unchecked — you can accidentally pass a None to code that expects a list node. In NOVA, Empty is a real variant: the type system prevents you from treating an empty list as if it has a head element.

Real-world: command-line argument parsing

Enums are the natural representation for command-line arguments: each flag is a distinct variant, some carry values and some don't. This beats a string-switch approach because the compiler checks exhaustiveness — if you add a new flag, every match that processes CliArg will produce a compile error until you handle the new case.

enum CliArg
    Help
    Version
    OutputFile(path: string)
    Verbose
    Unknown(text: string)

fn parse_arg(s)
    match s
        "--help"    => Help
        "-h"        => Help
        "--version" => Version
        "--verbose" => Verbose
        _ =>
            if starts_with(s, "--output=")
                OutputFile(slice(s, 9, len(s)))
            else
                Unknown(s)

fn main()
    verbose = false
    output  = "out.txt"

    for a in args()
        match parse_arg(a)
            Help            => print("Usage: myapp [--verbose] [--output=FILE]")
            Version         => print("myapp 1.0.0")
            Verbose         => verbose = true
            OutputFile(path) => output = path
            Unknown(text)   => print("Unknown flag: {text}")

    print("verbose={verbose}, output={output}")

Line-by-line breakdown:

• enum CliArg — each command-line flag is a variant. Help and Verbose carry no data. OutputFile carries the file path. Unknown carries whatever string the user typed.
• fn parse_arg(s) — converts a raw string argument into a typed CliArg. The last expression is the return value — no return keyword.
• "--help" => Help — a string match arm. Both "--help" and "-h" map to the same Help variant. This is simpler than checking string equality in if-chains.
• _ => with a block body — the wildcard arm runs when no other arm matches. The block uses if/else to distinguish --output=... from truly unknown flags.
• OutputFile(slice(s, 9, len(s))) — strips the "--output=" prefix (9 characters) and wraps the remainder in the OutputFile variant.
• for a in args() — args() returns the command-line arguments as a list of strings (excluding the program name).
• match parse_arg(a) — the exhaustiveness check is on CliArg: all 5 variants are covered. If you add a 6th variant to the enum, the compiler will flag this match and require you to handle it.

Why enums beat string-switch: In Python or Java, you might do if arg == "--help", elif arg.startswith("--output="), etc. There's no way to enforce exhaustiveness — a new flag added to the parser might be silently ignored by the handler. NOVA's enum approach makes every new variant a compile-time obligation everywhere it's matched.

Enums with associated data — a payment system

One of the most powerful uses of enums is modeling domain concepts where different "shapes" of the same concept carry completely different data. Here is a payment method enum where each payment variant carries only the data relevant to that method:

enum PaymentMethod
    CreditCard(number: string, expiry: string, cvv: string)
    BankTransfer(account: string, routing: string)
    Crypto(wallet: string, coin: string)
    Cash

fn process_payment(amount, method)
    match method
        CreditCard(num, exp, _) =>
            print("Charging card *{slice(num, len(num)-4, len(num))} exp {exp}: \${amount}")
        BankTransfer(acc, routing) =>
            print("Wire \${amount} to account {acc} routing {routing}")
        Crypto(wallet, coin) =>
            print("Send \${amount} in {coin} to wallet {wallet}")
        Cash =>
            print("Cash payment of \${amount} — collect at register")

card    = CreditCard("4111111111111111", "12/26", "123")
bank    = BankTransfer("987654321", "021000021")
bitcoin = Crypto("1A1zP1eP5QGefi2DMPTfTL5SLmv7Divf", "BTC")

process_payment(99.99, card)
process_payment(500.00, bank)
process_payment(25.00, bitcoin)
process_payment(15.00, Cash)

Line-by-line breakdown:

• CreditCard(number: string, expiry: string, cvv: string) — this variant carries three string fields. A credit card needs number, expiry, AND CVV — all three are always present together.
• BankTransfer(account: string, routing: string) — completely different fields. Bank transfers have no expiry or CVV. The enum keeps each variant's data logically separate.
• Cash — a unit variant with no data. Cash payments carry no card details, no account number. This is expressed as no parentheses at all.
• CreditCard(num, exp, _) in the match — extracts number into num, expiry into exp, and discards cvv with _ (you don't log CVV to the console for security). The pattern binds positionally.
• slice(num, len(num)-4, len(num)) — extracts the last 4 digits of the card number for display. Never show full card numbers in logs.

What this looks like in Python — and why NOVA is better:

# Python — dict-based, no exhaustiveness checking
payment = {"type": "credit_card", "number": "4111..."}
if payment["type"] == "credit_card":
    process_card(payment["number"])   # KeyError if "number" missing
elif payment["type"] == "bank":
    process_bank(payment["account"])  # "credit_card" typo would be silent bug
# "crypto" silently ignored — no exhaustiveness error!

Option<T> — built-in optional values

NOVA has null for missing values, but for functions that need to signal "found / not found" in a type-safe way, Option<T> is cleaner — and it is a compiler-native type, exactly like Result<T,E> (Section 9). You never declare it yourself: the T? type suffix is sugar for Option<T>, some(value)/none() construct it, and match already recognizes Some(value)/None as its two cases — no enum definition required:

// Some(value) / None need no enum declaration -- Option<T> is compiler-native,
// exactly like Result<T,E>. A function that finds the first element matching a condition:
fn find_first(items, predicate)
    for item in items
        if predicate(item)
            return Some(item)
    None

fn find_user(users, name)
    find_first(users, u => u.name == name)

type User
    name:  string
    email: string

fn main()
    users = [
        User { name: "Alice", email: "alice@example.com" },
        User { name: "Bob",   email: "bob@example.com"   }
    ]

    result = find_user(users, "Alice")
    match result
        Some(u) => print("Found: {u.email}")   // Found: alice@example.com
        None    => print("User not found")

    missing = find_user(users, "Carol")
    match missing
        Some(u) => print("Found: {u.email}")
        None    => print("User not found")   // User not found

Option vs null — when to use each:

NOVA's built-in Result type (see Section 9) is a related pattern for operations that can fail WITH an error message — use Result when failure needs a reason, and Option<T> when it's simply "not found."

Enums as state machines

Enums shine when you model a system that can only be in one of a known set of states. The compiler guarantees you never create an invalid state — unlike integers or strings which accept any value.

enum TrafficLight
    Red
    Yellow
    Green

fn next_state(light)
    match light
        Red    => Green
        Green  => Yellow
        Yellow => Red

fn can_go(light)
    match light
        Green  => true
        Yellow => false  // slow down, not go
        Red    => false

// Simulate one full cycle
light = Red
for _ in 0..5
    print("{light} — go: {can_go(light)}")
    light = next_state(light)

Notice that next_state returns an enum value directly from a match — no intermediate variable needed. The compiler verifies that all three cases are handled; delete any arm and it refuses to compile.

Multi-state business workflow — order lifecycle

Here is a real-world example: an e-commerce order that can only advance through legal states. Invalid transitions (e.g. shipping a cancelled order) are compile-time impossible because the transition functions only accept the right variant.

enum OrderState
    Cart
    PendingPayment(total: float)
    Processing(order_id: string, total: float)
    Shipped(order_id: string, tracking: string)
    Delivered(order_id: string)
    Cancelled(reason: string)

// Each function encodes a legal transition
fn checkout(state, total)
    match state
        Cart => PendingPayment(total)
        _    => Cancelled("can only checkout from Cart")

fn pay(state, order_id)
    match state
        PendingPayment(total) => Processing(order_id, total)
        _                    => Cancelled("payment not expected in this state")

fn ship(state, tracking)
    match state
        Processing(id, _) => Shipped(id, tracking)
        _                 => Cancelled("can only ship a processing order")

fn deliver(state)
    match state
        Shipped(id, _) => Delivered(id)
        _              => Cancelled("can only deliver a shipped order")

fn summary(state)
    match state
        Cart                  => "Shopping cart (empty)"
        PendingPayment(total) => "Awaiting payment — total ${total}"
        Processing(id, total) => "Processing order #{id}, ${total}"
        Shipped(id, tracking) => "Shipped #{id}, tracking: {tracking}"
        Delivered(id)         => "Delivered #{id} — thank you!"
        Cancelled(reason)     => "Cancelled: {reason}"

// Walk an order through its full lifecycle
order = Cart
order = checkout(order, 149.99)
order = pay(order, "ORD-8821")
order = ship(order, "1Z999AA10123456784")
order = deliver(order)
print(summary(order))

8. Pattern matching

What is this? match inspects a value and runs different code based on its shape. It's more powerful than if/else: it extracts data in the same step, is exhaustive (compiler forces you to handle every case), and compiles to an efficient jump table for integer patterns.

Exhaustiveness — why match is safer than if/else chains

The central guarantee of match is that it must cover every possible case. When you match on an enum, the compiler checks that every variant has an arm. When you add a new variant to an enum later, every match that is missing the new arm becomes a compile error — which means the compiler automatically finds every place in your code that needs updating. This is impossible with if/else chains or string comparisons.

enum Direction
    North
    South
    East
    West

fn opposite(dir)
    match dir
        North => South   // must handle all 4 variants
        South => North   // if you omit one, the compiler errors
        East  => West
        West  => East

// Later, add a new variant: NorthEast
// The compiler now errors on `opposite` saying:
//   NorthEast is not covered — add an arm or use _ for a default
// With an if/else chain you would never know

Matching integers with guards

fn describe(x)
    match x
        0             => "zero"
        1             => "one"
        n if n < 0   => "negative: {n}"
        n if n > 100 => "big: {n}"
        _             => "other"     // _ = wildcard, matches anything

print(describe(0))     // zero
print(describe(-5))    // negative: -5
print(describe(200))   // big: 200
print(describe(42))    // other

Line-by-line:

• 0 => "zero" — matches the literal integer 0. The => separates the pattern from the value.
• n if n < 0 => ... — binds the value to n, then guards with an if condition. This is a guard clause.
• _ => "other" — the wildcard. _ matches anything and doesn't bind a name. Every match must be exhaustive — if you don't have a _, the compiler checks that all cases are covered.

Range patterns and or-patterns

Two more pattern kinds round out match: a range pattern LOW..HIGH => ... tests whether the subject falls within a range in a single arm, and an or-pattern p1 | p2 => ... matches if EITHER alternative matches, letting several cases share one arm body.

Critical gotcha — range PATTERNS are inclusive of both ends, the opposite of range EXPRESSIONS: the range expression 0..5 used in a for loop or a slice is exclusive of 5 (Python range() semantics). A match-arm range pattern 0..5 => ... is INCLUSIVE of 5 — it matches 0 through 5. These are two different parts of the grammar that happen to share the .. spelling; do not assume they share inclusivity too.

fn classify_temp(c)
    match c
        -10..0  => "freezing"   // matches -10 through 0, INCLUSIVE of 0
        1..15   => "cold"       // matches 1 through 15, INCLUSIVE of 15
        16..25  => "mild"
        26..40  => "hot"
        _        => "out of range"

print(classify_temp(0))     // freezing — 0 is the inclusive upper bound of -10..0
print(classify_temp(15))    // cold — 15 is the inclusive upper bound of 1..15
print(classify_temp(30))    // hot

// or-pattern: several distinct cases, one body
enum Status
    Pending
    Loading
    Ready
    Failed

fn is_settled(s)
    match s
        Ready | Failed     => true
        Pending | Loading => false

print(is_settled(Ready))     // true
print(is_settled(Loading))   // false

Line-by-line:

• -10..0 => "freezing" — a range pattern reads like a literal but tests membership; equivalent to a guard n if n >= -10 and n <= 0, but as a single arm instead of a bound-plus-guard.
• Ready | Failed => true — the or-pattern | lets two enum variants share one arm without duplicating the body or falling back to a guard like s if s == Ready or s == Failed.
• Arm order still matters with ranges exactly as it does with literals: a later range pattern that overlaps an earlier one is unreachable dead code — write non-overlapping ranges top to bottom.

Nested constructor patterns

What is this? A pattern arm can destructure more than one level of nesting in a single arm — Wrap(IntVal(n)) matches an Outer that is a Wrap AND, in the same breath, matches the Inner value inside it against IntVal, binding its field straight to n. Without this, the same check needs a separate nested match for every layer — exactly the ceremony NOVA's pattern matching exists to remove. It works to arbitrary depth, and it works both for your own enums and for the built-in Result/Option types.

enum Inner
    IntVal(n: int)
    StrVal(s: string)

enum Outer
    Wrap(inner: Inner)
    Empty()

fn render(o: Outer) -> string
    match o
        Wrap(IntVal(n)) => "int:{n}"       // two levels, one arm
        Wrap(StrVal(s)) => "str:{s}"
        Empty()       => "empty"

// Nesting through a BUILT-IN sum type works the same way —
// Result<Inner> here, not just user-defined enums.
fn sum_nested(r: Result<Inner>) -> string
    match r
        Ok(IntVal(n)) => "ok-int:{n}"
        Ok(StrVal(s)) => "ok-str:{s}"
        Err(e)         => "err:{e}"

print(render(Wrap(IntVal(42))))    // int:42
print(sum_nested(ok(IntVal(5))))   // ok-int:5

Line-by-line: Wrap(IntVal(n)) reads outside-in: first confirm the value is a Wrap, then look inside it and confirm THAT value is an IntVal, then bind its field to n — all as one pattern, checked as one arm. The nesting isn't limited to two levels or to your own enum types: it composes through Result, Option, and arbitrarily deep user-defined enums alike, because the compiler compiles a nested pattern the same way regardless of how many constructors deep it goes. Note the case difference between building and matching a Result: you construct one with the lowercase builtin ok(...)/err(...), but you match against it with the capitalized pattern Ok(...)/Err(...) — see the callout in §9 (Error handling).

Matching strings

fn http_status(method)
    match method
        "GET"    => "reading"
        "POST"   => "creating"
        "PUT"    => "updating"
        "DELETE" => "deleting"
        other    => "unknown method: {other}"

Classic FizzBuzz with match

fn fizzbuzz(n)
    match n % 15
        0 => "FizzBuzz"
        _ if n % 3 == 0 => "Fizz"
        _ if n % 5 == 0 => "Buzz"
        _ => str(n)

for i in 1..20
    print(fizzbuzz(i))

Matching enum variants (destructuring)

enum Message
    Quit
    Move(x: int, y: int)
    Say(text: string)

fn handle(msg)
    match msg
        Quit       => print("quitting")
        Move(x, y) => print("moving to {x},{y}")
        Say(t)     => print("says: {t}")

handle(Move(10, 20))    // moving to 10,20
handle(Say("hello"))    // says: hello

Why not if/else chains? match extracts data and checks the type in one step. An if/else equivalent would require two separate operations. The compiler also guarantees exhaustiveness — if you add a new variant later, every match on that enum becomes a compile error until you handle the new case.

Recursive match — expression evaluator

Match shines when combined with recursive enum types. This is the classic interpreter pattern used in real compilers:

enum Expr
    Num(value: float)
    Add(left: Expr, right: Expr)
    Mul(left: Expr, right: Expr)

fn eval(e)
    match e
        Num(v)    => v
        Add(l, r) => eval(l) + eval(r)
        Mul(l, r) => eval(l) * eval(r)

// Build the AST for: (2 + 3) * 4
expr = Mul(Add(Num(2.0), Num(3.0)), Num(4.0))
print(eval(expr))    // 20.0

Line-by-line breakdown:

• enum Expr — A recursive enum (an expression is either a number, or a pair of sub-expressions). Add and Mul each contain two Expr children — that is the recursion.
• Num(v) => v — Base case: a leaf node. Just return its value.
• Add(l, r) => eval(l) + eval(r) — Recursive case: evaluate the left sub-expression, evaluate the right sub-expression, then add them. The compiler guarantees this match is exhaustive — there is no "forgot a case" bug.
• expr = Mul(Add(Num(2.0), Num(3.0)), Num(4.0)) — Builds the tree (2 + 3) * 4 as a data structure. No parsing needed — NOVA's enum syntax IS the AST.
• eval(expr) — Walks the tree recursively: eval(Mul(...)) → eval(Add(Num(2), Num(3))) * eval(Num(4)) → (2+3) * 4 → 5 * 4 → 20.0.

This pattern is the foundation of every interpreter, compiler, and parser. In languages without match, this requires a visitor pattern with 6 files and 200 lines of boilerplate. In NOVA: 8 lines.

Matching Results

fn safe_divide(a, b)
    if b == 0
        return err("division by zero")
    ok(a / b)

match safe_divide(10, 3)
    Ok(v)  => print("result: {v}")
    Err(e) => print("error: {e}")
// Output: result: 3

The built-in Result type uses Ok(value) and Err(message). Matching on a Result is the canonical way to handle both success and failure. See Section 9 for the full error handling guide.

Matching with guards and multiple conditions

Match arms can include a if guard to add extra conditions beyond the pattern shape. When no single pattern handles two distinct values the same way, guards let you group logic without duplicating the arm body.

fn classify(n)
    match n
        0              => "zero"
        x if x < 0    => "negative"
        x if x % 2 == 0 => "positive even"
        _              => "positive odd"

print(classify(0))    // zero
print(classify(-3))   // negative
print(classify(8))    // positive even
print(classify(7))    // positive odd

// Matching HTTP status codes — group ranges with guards
fn status_label(code)
    match code
        200            => "OK"
        201            => "Created"
        204            => "No Content"
        301            => "Moved Permanently"
        302            => "Found"
        400            => "Bad Request"
        401            => "Unauthorized"
        403            => "Forbidden"
        404            => "Not Found"
        500            => "Internal Server Error"
        x if x >= 100 and x < 200 => "1xx Informational"
        x if x >= 200 and x < 300 => "2xx Success"
        x if x >= 300 and x < 400 => "3xx Redirect"
        x if x >= 400 and x < 500 => "4xx Client Error"
        x if x >= 500 and x < 600 => "5xx Server Error"
        _              => "Unknown status"

print(status_label(404))   // Not Found
print(status_label(418))   // 4xx Client Error