NYX — The Language That Does Everything

One Language. Every Domain. Zero Compromise.

Nyx is a multi-paradigm compiled programming language that replaces Python, JavaScript, Rust, C++, Go, Java, and more — in a single, unified language with 10-100x Python performance, Rust-level memory safety, and 60% less code.

Install Now · Quick Start · Full Language Guide · All Engines · Examples

Download

irm https://raw.githubusercontent.com/suryasekhar06jemsbond-lab/Nyx/main/scripts/install.ps1 | iex

curl -fsSL https://raw.githubusercontent.com/suryasekhar06jemsbond-lab/Nyx/main/scripts/install.sh | sh

# Download nyx.exe and add to PATH
mkdir "$env:LOCALAPPDATA\Programs\nyx" -Force
Invoke-WebRequest -Uri "https://github.com/suryasekhar06jemsbond-lab/Nyx/releases/latest/download/nyx-windows-x64.exe" -OutFile "$env:LOCALAPPDATA\Programs\nyx\nyx.exe"
[Environment]::SetEnvironmentVariable("PATH", "$env:LOCALAPPDATA\Programs\nyx;$env:PATH", "User")

# Restart terminal, then:
nyx --version

# Download and install the VSIX
code --install-extension https://github.com/suryasekhar06jemsbond-lab/Nyx/releases/latest/download/nyx-language-6.0.0.vsix

Table of Contents

� Architecture Overview

Nyx has three execution modes — choose whatever fits your use case:

┌──────────────────────────────────────────────────────┐
│                   YOUR .ny FILE                      │
└─────────────────────┬────────────────────────────────┘
                      │
          ┌───────────┼───────────┐
          ▼           ▼           ▼
   ┌─────────┐  ┌──────────┐  ┌──────────┐
   │  Native  │  │  Python  │  │   Web    │
   │ Compiler │  │Interpre- │  │ Runtime  │
   │  (C99)   │  │  ter     │  │ (HTTP)   │
   └────┬─────┘  └────┬─────┘  └────┬─────┘
        ▼              ▼              ▼
   ┌─────────┐  ┌──────────┐  ┌──────────┐
   │  .exe   │  │ Evaluated│  │ HTTP     │
   │ binary  │  │ in Python│  │ Server   │
   └─────────┘  └──────────┘  └──────────┘

How The Interpreter Works

Source Code (.ny)
     │
     ▼
┌─────────┐    ┌─────────┐    ┌──────────────┐    ┌────────────┐
│  Lexer   │───▶│ Parser  │───▶│  AST (60+    │───▶│ Interpreter│
│ (530 ln) │    │(650 ln) │    │  node types) │    │  (551 ln)  │
└─────────┘    └─────────┘    └──────────────┘    └────────────┘
     │              │                                    │
     ▼              ▼                                    ▼
 150+ Token    Pratt Parser                     Scoped Environment
  Types       11 Precedence                      with built-ins
               Levels                            & std/lib imports

Lexer Features

• Unicode identifiers
• Hash (#), C++ (//), C block (/* */) comments
• String escape sequences, raw strings (r"..."), byte strings (b"..."), f-strings (f"...{expr}...")
• Multiline strings ("""...""")
• Hex (0xFF), octal (0o77), binary (0b1010) numeric literals
• Token hooks, trivia tracking, error recovery, state save/restore

Parser Features

• Pratt parser with 11 precedence levels (LOWEST → INDEX)
• Extensible via register_prefix(), register_infix(), register_statement()
• Error recovery via _synchronize_statement() / _synchronize_expression()
• 60+ AST node types (see AST Reference)

Project Structure

Nyx/
├── run.py                    # Main entry point: python run.py file.ny
├── nyx_runtime.py            # Web runtime server for HTTP apps
├── nyx.bat / nyx.sh          # Platform launchers
├── Makefile                  # Native compiler build: make → build/nyx
├── package.json              # Project metadata (v5.5.0)
├── ny.registry               # Package registry index
├── nypm.config               # Package manager config
├── nypm.js                   # Package manager (12 commands)
│
├── src/                      # Core interpreter (Python)
│   ├── lexer.py              # 530 lines — tokenizer
│   ├── parser.py             # 650 lines — Pratt parser
│   ├── ast_nodes.py          # 900 lines — 60+ AST node types
│   ├── interpreter.py        # 551 lines — evaluator
│   └── token_types.py        # 680 lines — 150+ token types
│
├── native/                   # Native C compiler
│   └── nyx.c                 # C99 compiler (v3.3.3)
│
├── stdlib/                   # 109 standard library modules
│   ├── math.ny, io.ny, json.ny, http.ny, crypto.ny, ...
│   └── dfas/                 # Dynamic Field Arithmetic System (10 files)
│
├── engines/                  # 117 specialized engines
│   ├── nyai/, nygpu/, nyweb/, nygame/, ...
│
├── compiler/                 # Bootstrap compiler
│   ├── bootstrap.ny          # Self-hosting bootstrap
│   ├── v3_seed.ny            # V3 seed compiler
│   └── v3_compiler_template.c
│
├── language/                 # Language specification
│   ├── grammar.ebnf          # Complete formal grammar
│   ├── types.md              # Full type system spec
│   ├── ownership.md          # Ownership & borrowing model
│   └── concurrency.md        # Concurrency model spec
│
├── examples/                 # Example programs
├── tests/                    # 180+ test files
├── benchmarks/               # Performance benchmarks
├── docs/                     # 70+ documentation files
├── tools/                    # Nyx Studio, crypto CLI, etc.
├── configs/production/       # AAA game engine production configs
└── editor/vscode/            # VS Code extension

�🌟 Why Nyx?

"Learn one language. Build everything. Replace your entire stack."

Nyx vs Other Languages

Installation

Install Nyx Runtime

Option 1 — Download Pre-built Binary (Fastest)

Download nyx.exe from the latest release:

# Windows — one-liner install
mkdir "$env:LOCALAPPDATA\Programs\nyx" -Force
Invoke-WebRequest -Uri "https://github.com/suryasekhar06jemsbond-lab/Nyx/releases/latest/download/nyx-windows-x64.exe" -OutFile "$env:LOCALAPPDATA\Programs\nyx\nyx.exe"
[Environment]::SetEnvironmentVariable("PATH", "$env:LOCALAPPDATA\Programs\nyx;$env:PATH", "User")
# Restart terminal, then:
nyx hello.ny

Option 2 — Build from Source

# Clone and build
git clone https://github.com/suryasekhar06jemsbond-lab/Nyx.git
cd Nyx
make
./build/nyx hello.ny

# Windows (with GCC or Clang installed)
powershell -ExecutionPolicy Bypass -File scripts/build_windows.ps1 -Output build/nyx.exe
.\build\nyx.exe hello.ny

Option 3 — Python Interpreter (no compilation needed)

git clone https://github.com/suryasekhar06jemsbond-lab/Nyx.git
cd Nyx
python run.py hello.ny

Install VS Code Extension

Option 1 — Download VSIX from GitHub Releases (Recommended)

# Download the latest VSIX
# → https://github.com/suryasekhar06jemsbond-lab/Nyx/releases/latest/download/nyx-language-6.0.0.vsix

# Install from file
code --install-extension nyx-language-6.0.0.vsix

Option 2 — VS Code Marketplace

1. Open VS Code
2. Press Ctrl+Shift+X (Extensions)
3. Search "Nyx Language"
4. Click Install

Option 3 — Build from Source

cd editor/vscode/nyx-language
npm install
npm run compile
npx vsce package --no-dependencies
code --install-extension nyx-language-6.0.0.vsix

🔧 VS Code Extension Features

9 Integrated Commands

Language Features

• Syntax Highlighting — Full TextMate grammar with 20+ scopes for all Nyx syntax
• Code Completion — IntelliSense for keywords, builtins, functions, and snippets
• Hover Information — Documentation on hover for keywords and built-in functions
• Go to Definition — Jump to any function, class, or variable definition
• Find All References — Find every usage of any symbol in your file
• Rename Symbol — Safely rename variables, functions, and classes everywhere
• Document Symbols — Outline view showing all functions and classes
• Signature Help — See function parameters as you type
• Code Actions — Quick fixes like "Add import" for unknown modules
• Formatting — Auto-format on save or on demand
• Diagnostics — Real-time error detection as you type
• 50+ Code Snippets — Type fn, class, for, match, etc. and press Tab
• 2 Professional Themes — Nyx Dark and Nyx Light

20 Configuration Options

Open Settings (Ctrl+,) and search "nyx":

{
  "nyx.runtime.path": "nyx",
  "nyx.compiler.path": "nyc",
  "nyx.formatter.enabled": true,
  "nyx.formatter.tabSize": 4,
  "nyx.linting.enabled": true,
  "nyx.linting.level": "warning",
  "nyx.diagnostics.onSave": true,
  "nyx.debugger.stopOnEntry": false,
  "nyx.language.inferTypes": true,
  "nyx.language.strictMode": false,
  "nyx.hover.enabled": true,
  "nyx.completion.enabled": true
}

📖 The Complete Nyx Language Guide

Goal: After reading this guide, you will be able to build anything with Nyx — from "Hello World" to AI models, web servers, game engines, and operating system kernels.

📘 Chapter 1: Your First Nyx Program

Hello World

Create a file called hello.ny:

print("Hello, World!")

Run it:

nyx hello.ny

Output:

Hello, World!

That's it. No imports, no main function, no boilerplate. Just write and run.

Comments

# This is a single-line comment

/* This is a
   multi-line comment */

The Main Function (Optional)

# You can write code at the top level (no main needed)
print("I run directly!")

# Or use a main function for larger programs
fn main() {
    print("I run from main!")
    return 0
}
main()

Semicolons Are Optional

# Both styles are valid — use whichever you prefer

# Without semicolons (clean style)
let name = "Nyx"
print(name)

# With semicolons (traditional style)
let name = "Nyx";
print(name);

Print Multiple Values

print("Name:", "Nyx", "Version:", 6)
# Output: Name: Nyx Version: 6

📘 Chapter 2: Variables & Data Types

Declaring Variables

# Immutable (cannot be changed after creation)
let name = "Nyx"
let age = 25
let pi = 3.14159

# Mutable (can be changed)
let mut counter = 0
counter = counter + 1

# Constants (never changes, known at compile time)
const MAX_SIZE = 1000
const APP_NAME = "MyApp"

All Data Types

Type Checking

let x = 42
print(type_of(x))    # "int"
print(is_int(x))     # true
print(is_string(x))  # false

# Type checking functions (all built-in, no import needed)
is_int(42)        # true
is_bool(true)     # true
is_string("hi")   # true
is_array([1,2])   # true
is_function(print)# true
is_null(null)     # true

Type Conversion

let num = int("42")       # String to int → 42
let text = str(42)        # Int to string → "42"
let decimal = float("3.14") # String to float → 3.14

Destructuring

# Tuple destructuring
let (x, y) = (10, 20)

# Array destructuring
let [first, second, ...rest] = [1, 2, 3, 4, 5]
# first = 1, second = 2, rest = [3, 4, 5]

# Object destructuring
let {name, age} = {name: "Nyx", age: 1, type: "lang"}
# name = "Nyx", age = 1

📘 Chapter 3: Operators

Arithmetic

let a = 10 + 3    # 13  (addition)
let b = 10 - 3    # 7   (subtraction)
let c = 10 * 3    # 30  (multiplication)
let d = 10 / 3    # 3.33 (division)
let e = 10 % 3    # 1   (modulo/remainder)
let f = 10 // 3   # 3   (integer division)
let g = 2 ** 10   # 1024 (exponentiation)

Comparison

10 == 10   # true  (equal)
10 != 5    # true  (not equal)
10 > 5     # true  (greater than)
10 < 20    # true  (less than)
10 >= 10   # true  (greater or equal)
10 <= 20   # true  (less or equal)

Logical

true && false  # false (AND)
true || false  # true  (OR)
!true          # false (NOT)

Bitwise

5 & 3    # 1  (AND)
5 | 3    # 7  (OR)
5 ^ 3    # 6  (XOR)
~5       # -6 (NOT)
5 << 2   # 20 (left shift)
20 >> 2  # 5  (right shift)

Special Operators

# Null coalescing — use fallback if null
let name = user_name ?? "Anonymous"

# Pipeline — chain operations left to right
let result = data |> filter(|x| x > 0) |> map(|x| x * 2) |> sum()

# Range
0..10     # 0, 1, 2, ..., 9
0..=10    # 0, 1, 2, ..., 10

# Optional chaining
let city = user?.address?.city

Assignment

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

📘 Chapter 4: Control Flow

If / Else

let age = 18

if age >= 18 {
    print("Adult")
} else if age >= 13 {
    print("Teenager")
} else {
    print("Child")
}

If as Expression (Returns a Value)

let status = if age >= 18 { "adult" } else { "minor" }
print(status)  # "adult"

While Loop

let mut i = 0
while i < 5 {
    print(i)
    i = i + 1
}
# Output: 0 1 2 3 4

For Loop

# For-in loop (iterate over collection)
let fruits = ["apple", "banana", "cherry"]
for fruit in fruits {
    print(fruit)
}

# For with index
for i, fruit in fruits {
    print(i, ":", fruit)
}
# Output: 0 : apple  1 : banana  2 : cherry

# For with range
for i in 0..5 {
    print(i)
}
# Output: 0 1 2 3 4

# C-style for loop
for (let i = 0; i < 10; i = i + 1) {
    print(i)
}

Break & Continue

for i in 0..100 {
    if i == 5 { break }      # Stop the loop entirely
    if i % 2 == 0 { continue } # Skip even numbers
    print(i)
}
# Output: 1 3

Loop (Infinite)

let mut count = 0
loop {
    count = count + 1
    if count > 3 { break }
    print(count)
}
# Output: 1 2 3

Switch / Case

let day = "Monday"

switch day {
    case "Monday": { print("Start of week") }
    case "Friday": { print("Almost weekend!") }
    case "Saturday": { print("Weekend!") }
    case "Sunday": { print("Weekend!") }
    default: { print("Regular day") }
}

Match (Powerful Pattern Matching)

See Chapter 10 for full details.

let value = 42
let result = match value {
    case 0 => "zero"
    case 1..10 => "small"
    case n if n > 100 => "big"
    case _ => "medium"
}
print(result)  # "medium"

📘 Chapter 5: Functions

Basic Functions

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

Functions with Return Values

fn add(a, b) {
    return a + b
}
let sum = add(3, 4)  # 7

One-Line Functions (Expression Body)

fn add(a, b) = a + b
fn square(x) = x * x
fn is_even(n) = n % 2 == 0

Default Parameters

fn greet(name, greeting = "Hello") {
    print(greeting + ", " + name + "!")
}
greet("Nyx")           # Hello, Nyx!
greet("Nyx", "Hi")     # Hi, Nyx!

Multiple Return Values

fn divide(a, b) {
    return (a / b, a % b)  # Returns a tuple
}
let (quotient, remainder) = divide(17, 5)
# quotient = 3, remainder = 2

Recursive Functions

fn factorial(n) {
    if n <= 1 { return 1 }
    return n * factorial(n - 1)
}
print(factorial(10))  # 3628800

fn fibonacci(n) {
    if n <= 1 { return n }
    return fibonacci(n - 1) + fibonacci(n - 2)
}
print(fibonacci(10))  # 55

Higher-Order Functions

# Functions that take other functions as arguments
fn apply(f, x) = f(x)

fn double(x) = x * 2
print(apply(double, 5))  # 10

# Functions that return functions
fn multiplier(factor) {
    return fn(x) = x * factor
}
let triple = multiplier(3)
print(triple(7))  # 21

Typed Functions

fn add(a: int, b: int) -> int {
    return a + b
}

fn greet(name: str) -> str {
    return "Hello, " + name
}

📘 Chapter 6: Arrays, Objects & Collections

Arrays

# Create arrays
let numbers = [1, 2, 3, 4, 5]
let mixed = [1, "hello", true, null]
let empty = []

# Access elements (0-indexed)
print(numbers[0])   # 1
print(numbers[2])   # 3

# Length
print(len(numbers)) # 5

# Add elements
push(numbers, 6)    # [1, 2, 3, 4, 5, 6]

# Remove last element
let last = pop(numbers)  # Returns 6, array is now [1, 2, 3, 4, 5]

# Check membership
print(3 in numbers)  # true

# Iterate
for num in numbers {
    print(num)
}

# Array operations
let sorted = sort(numbers)
let reversed = reverse(numbers)
let total = sum(numbers)       # 15
let biggest = max(numbers)     # 5
let smallest = min(numbers)    # 1

List Comprehensions

# Create arrays with expressions
let squares = [x * x for x in 0..10]
# [0, 1, 4, 9, 16, 25, 36, 49, 64, 81]

# With filter
let even_squares = [x * x for x in 0..10 if x % 2 == 0]
# [0, 4, 16, 36, 64]

# With index
let indexed = [str(i) + ": " + item for i, item in ["a", "b", "c"]]
# ["0: a", "1: b", "2: c"]

Objects (Dictionaries / Maps)

# Create objects
let person = {
    name: "Nyx",
    age: 1,
    language: true
}

# Access values
print(person.name)       # "Nyx"
print(person["age"])     # 1

# Keys, values, items
print(keys(person))      # ["name", "age", "language"]
print(values(person))    # ["Nyx", 1, true]
print(items(person))     # [["name","Nyx"], ["age",1], ...]

# Check if key exists
print(has(person, "name"))  # true

# Iterate
for key, value in items(person) {
    print(key + " = " + str(value))
}

Dictionary Comprehensions

let squares_map = {str(x): x * x for x in 0..5}
# {"0": 0, "1": 1, "2": 4, "3": 9, "4": 16}

Tuples

let point = (10, 20)
let (x, y) = point
print(x)  # 10
print(y)  # 20

Built-in Collection Functions

# All of these are native — no imports needed
len([1,2,3])       # 3 — length of any collection
push(arr, item)    # Add item to end
pop(arr)           # Remove and return last item
sort(arr)          # Sort array
reverse(arr)       # Reverse array
sum(arr)           # Sum all numbers
min(arr)           # Smallest value
max(arr)           # Largest value
all(arr)           # True if all elements are truthy
any(arr)           # True if any element is truthy
range(n)           # [0, 1, 2, ..., n-1]
range(a, b)        # [a, a+1, ..., b-1]
clamp(x, lo, hi)  # Clamp x between lo and hi
abs(x)             # Absolute value
keys(obj)          # Get all keys of an object
values(obj)        # Get all values of an object
items(obj)         # Get key-value pairs
has(obj, key)      # Check if key exists

📘 Chapter 7: Strings

String Basics

let greeting = "Hello, World!"
let name = 'Nyx'
let multi = "This is a
multi-line string"

# String length
print(len(greeting))  # 13

# Concatenation
let full = "Hello" + " " + "World"

# Repetition
let line = "-" * 40   # "----------------------------------------"

# Access characters
print(greeting[0])    # "H"
print(greeting[7])    # "W"

String Methods (from stdlib/string.ny — no import needed)

# Case conversion
upper("hello")        # "HELLO"
lower("HELLO")        # "hello"
capitalize("hello")   # "Hello"
title("hello world")  # "Hello World"
swapcase("Hello")     # "hELLO"

# Searching
"hello".contains("ell")    # true
"hello".starts_with("he")  # true
"hello".ends_with("lo")    # true
"hello".index_of("ll")     # 2

# Trimming
"  hello  ".trim()         # "hello"
"  hello  ".trim_start()   # "hello  "
"  hello  ".trim_end()     # "  hello"

# Splitting & joining
"a,b,c".split(",")         # ["a", "b", "c"]
["a", "b", "c"].join("-")  # "a-b-c"

# Replacing
"hello world".replace("world", "Nyx")  # "hello Nyx"

# String formatting
let name = "Nyx"
let version = 6
print("${name} v${version}")  # "Nyx v6"

📘 Chapter 8: Classes & Object-Oriented Programming

Basic Class

class Animal {
    fn init(self, name, sound) {
        self.name = name
        self.sound = sound
    }

    fn speak(self) {
        print(self.name + " says " + self.sound + "!")
    }
}

let dog = Animal("Buddy", "Woof")
dog.speak()  # Buddy says Woof!

Inheritance

class Dog extends Animal {
    fn init(self, name) {
        super.init(name, "Woof")
        self.tricks = []
    }

    fn learn_trick(self, trick) {
        push(self.tricks, trick)
    }

    fn show_tricks(self) {
        for trick in self.tricks {
            print(self.name + " can " + trick)
        }
    }
}

let rex = Dog("Rex")
rex.learn_trick("sit")
rex.learn_trick("shake")
rex.show_tricks()
# Rex can sit
# Rex can shake

Typed Class with Enums

pub enum Status {
    Active,
    Inactive,
    Suspended
}

pub class User {
    name: str
    email: str
    age: int
    status: Status

    fn init(self, name: str, email: str, age: int) {
        self.name = name
        self.email = email
        self.age = age
        self.status = Status.Active
    }

    fn is_adult(self) -> bool {
        return self.age >= 18
    }

    fn to_string(self) -> str {
        return "${self.name} (${self.email})"
    }
}

Static Methods & Properties

class MathUtils {
    fn square(x) = x * x
    fn cube(x) = x * x * x
    fn is_prime(n) {
        if n < 2 { return false }
        for i in 2..n {
            if n % i == 0 { return false }
        }
        return true
    }
}

print(MathUtils.square(5))    # 25
print(MathUtils.is_prime(7))  # true

📘 Chapter 9: Traits & Generics

Traits (Interfaces)

trait Drawable {
    fn draw(self)
    fn area(self) -> float
}

class Circle implements Drawable {
    fn init(self, radius) {
        self.radius = radius
    }

    fn draw(self) {
        print("Drawing circle with radius " + str(self.radius))
    }

    fn area(self) -> float {
        return 3.14159 * self.radius * self.radius
    }
}

class Rectangle implements Drawable {
    fn init(self, width, height) {
        self.width = width
        self.height = height
    }

    fn draw(self) {
        print("Drawing rectangle " + str(self.width) + "x" + str(self.height))
    }

    fn area(self) -> float {
        return self.width * self.height
    }
}

# Polymorphism
let shapes = [Circle(5), Rectangle(4, 6)]
for shape in shapes {
    shape.draw()
    print("Area: " + str(shape.area()))
}

Generics

class Box<T> {
    fn init(self, value: T) {
        self.value = value
    }

    fn get(self) -> T {
        return self.value
    }

    fn map<U>(self, f: fn(T) -> U) -> Box<U> {
        return Box(f(self.value))
    }
}

let int_box = Box(42)
let str_box = Box("hello")
let doubled = int_box.map(|x| x * 2)  # Box(84)

# Generic functions
fn first<T>(arr: [T]) -> T {
    return arr[0]
}

# Generic with constraints
fn largest<T: Comparable>(a: T, b: T) -> T {
    return if a > b { a } else { b }
}

📘 Chapter 10: Pattern Matching

Basic Match

fn describe(value) = match value {
    case 0 => "zero"
    case 1 => "one"
    case 2 => "two"
    case _ => "something else"
}

print(describe(1))  # "one"
print(describe(99)) # "something else"

Match with Guards

fn classify(n) = match n {
    case 0 => "zero"
    case n if n > 0 && n < 10 => "small positive"
    case n if n >= 10 && n < 100 => "medium positive"
    case n if n >= 100 => "large positive"
    case n if n < 0 => "negative"
    case _ => "unknown"
}

Match on Types

fn process(value) = match value {
    case n: int => "integer: " + str(n)
    case s: str => "string: " + s
    case arr: array => "array with " + str(len(arr)) + " items"
    case _ => "unknown type"
}

Match with Destructuring

fn describe_point(point) = match point {
    case (0, 0) => "origin"
    case (x, 0) => "on x-axis at " + str(x)
    case (0, y) => "on y-axis at " + str(y)
    case (x, y) => "at (" + str(x) + ", " + str(y) + ")"
}

# Result type matching
fn handle_result(r) = match r {
    case Ok(value) => "Success: " + str(value)
    case Err(msg) => "Error: " + msg
}

Match with Enums

enum Color {
    Red,
    Green,
    Blue,
    Custom(r: int, g: int, b: int)
}

fn to_hex(color) = match color {
    case Color.Red => "#FF0000"
    case Color.Green => "#00FF00"
    case Color.Blue => "#0000FF"
    case Color.Custom(r, g, b) => "rgb(" + str(r) + "," + str(g) + "," + str(b) + ")"
}

📘 Chapter 11: Error Handling

Try / Catch / Finally

try {
    let result = 10 / 0
    print(result)
} catch (err) {
    print("Error caught: " + str(err))
} finally {
    print("This always runs")
}

Throw Errors

fn validate_age(age) {
    if age < 0 {
        throw "Age cannot be negative"
    }
    if age > 150 {
        throw "Age seems unrealistic"
    }
    return true
}

try {
    validate_age(-5)
} catch (err) {
    print("Validation failed: " + str(err))
}

Result Type (Recommended)

fn divide(a, b) {
    if b == 0 { return Err("Division by zero") }
    return Ok(a / b)
}

let result = divide(10, 3)
match result {
    case Ok(value) => print("Result: " + str(value))
    case Err(msg) => print("Error: " + msg)
}

# Short-circuit with try? operator
fn compute() {
    let a = divide(10, 2)?   # Returns Err early if error
    let b = divide(a, 3)?
    return Ok(b)
}

Option Type

fn find_user(id) {
    if id == 1 { return Some({name: "Nyx", age: 1}) }
    return None
}

let user = find_user(1)
match user {
    case Some(u) => print("Found: " + u.name)
    case None => print("User not found")
}

# With null coalescing
let name = find_user(99)?.name ?? "Unknown"

📘 Chapter 12: Modules & Imports

Import Syntax

# Import a file
import "utils.ny"

# Import from standard library (no install needed!)
import std/io
import std/math
import std/json
import std/http
import std/crypto

# Import specific items
from std/collections import List, Map, Set
from std/math import PI, sqrt, sin, cos

# Import with alias
import std/io as file_io

# Import an engine (no install needed!)
use nyhttpd
use nyai
use nygpu
use nygame

Dual Import Syntax

Nyx supports both import and use for maximum flexibility:

# These are equivalent:
import std/math
use std/math

# 'use' is preferred for engines
use nyai
use nygpu
use nyweb
use nygame

# 'import' is preferred for files and stdlib
import "my_module.ny"
import std/collections
from std/io import read_file, write_file

Creating Modules

# File: math_utils.ny
module MathUtils {
    fn add(a, b) = a + b
    fn multiply(a, b) = a * b
    const PI = 3.14159265358979
}

# File: main.ny
import "math_utils.ny"
print(MathUtils.add(3, 4))      # 7
print(MathUtils.PI)              # 3.14159...

📘 Chapter 13: Closures & Lambdas

Lambda Expressions

# Short lambda syntax
let double = |x| x * 2
let add = |a, b| a + b

print(double(5))   # 10
print(add(3, 4))   # 7

# Multi-line lambda
let process = |x| {
    let squared = x * x
    let result = squared + 1
    return result
}
print(process(5))  # 26

Closures (Capture Environment)

fn make_counter() {
    let mut count = 0
    return fn() {
        count = count + 1
        return count
    }
}

let counter = make_counter()
print(counter())  # 1
print(counter())  # 2
print(counter())  # 3

Using with Higher-Order Functions

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

# Filter: keep only even numbers
let evens = filter(numbers, |x| x % 2 == 0)
# [2, 4, 6, 8, 10]

# Map: transform each element
let doubled = map(numbers, |x| x * 2)
# [2, 4, 6, 8, 10, 12, 14, 16, 18, 20]

# Reduce: combine all elements
let total = reduce(numbers, 0, |acc, x| acc + x)
# 55

# Combined with pipeline
let result = numbers
    |> filter(|x| x > 3)
    |> map(|x| x * x)
    |> reduce(0, |acc, x| acc + x)
# 330

📘 Chapter 14: Pipelines & Comprehensions

Pipeline Operator (|>)

The pipeline operator passes the result of the left side as the first argument to the right side:

# Without pipeline (nested, hard to read)
let result = sum(map(filter(numbers, is_positive), square))

# With pipeline (linear, easy to read!)
let result = numbers
    |> filter(is_positive)
    |> map(square)
    |> sum()

# Real-world example
let report = users
    |> filter(|u| u.age >= 18)
    |> map(|u| u.name)
    |> sort()
    |> join(", ")
print(report)  # "Alice, Bob, Charlie"

List Comprehensions

# Basic
[x * 2 for x in 0..10]
# [0, 2, 4, 6, 8, 10, 12, 14, 16, 18]

# With condition
[x for x in 0..100 if is_prime(x)]
# [2, 3, 5, 7, 11, 13, ...]

# Nested
[(x, y) for x in 0..3 for y in 0..3]
# [(0,0), (0,1), (0,2), (1,0), ...]

# Dictionary comprehension
{name: len(name) for name in ["Nyx", "Python", "Rust"]}
# {"Nyx": 3, "Python": 6, "Rust": 4}

# Generator expression (lazy — doesn't compute all at once)
let squares = (x * x for x in 0..1000000)

📘 Chapter 15: Async & Concurrency

Async / Await

# Define async function
async fn fetch_data(url) {
    let response = await http.get(url)
    return response.body
}

# Run async code
let data = await fetch_data("https://api.example.com/data")
print(data)

Spawn (Parallel Tasks)

# Run tasks in parallel
let task1 = spawn fetch_data("https://api.example.com/users")
let task2 = spawn fetch_data("https://api.example.com/posts")
let task3 = spawn fetch_data("https://api.example.com/comments")

# Wait for all results
let (users, posts, comments) = await join!(task1, task2, task3)

Channels (Message Passing)

# Create a channel for communication between tasks
let (tx, rx) = channel()

# Producer
spawn fn() {
    for i in 0..10 {
        tx.send(i)
    }
    tx.close()
}

# Consumer
for value in rx {
    print("Received: " + str(value))
}

Structured Concurrency

# TaskGroup ensures all tasks complete or all are cancelled
async fn fetch_all() {
    let group = TaskGroup()
    group.spawn(fetch_users)
    group.spawn(fetch_posts)
    group.spawn(fetch_comments)
    let results = await group.join_all()
    return results
}

📘 Chapter 16: Memory & Ownership

Ownership (Rust-like)

# Every value has exactly one owner
let name = "Nyx"     # 'name' owns this string
let alias = name     # Ownership MOVES to 'alias'
# print(name)        # ERROR: 'name' no longer valid

# Clone to keep both
let name = "Nyx"
let copy = name.clone()  # Both are now valid

Borrowing

# Immutable borrow — read-only access
fn print_length(s: &str) {
    print(len(s))
}

let word = "hello"
print_length(&word)  # Borrows, doesn't take ownership
print(word)          # Still valid!

# Mutable borrow — read/write access
fn add_suffix(s: &mut str) {
    s = s + "!"
}

let mut greeting = "hello"
add_suffix(&mut greeting)
print(greeting)  # "hello!"

Smart Pointers

# Box — heap allocation with single owner
let boxed = Box(42)
print(boxed.get())  # 42

# Rc — reference counted (multiple owners)
let shared = Rc("shared data")
let ref1 = shared.clone()
let ref2 = shared.clone()
# All three can read the data

# Arc — atomic reference counting (thread-safe Rc)
let thread_safe = Arc("thread-safe data")

RAII (Resource Acquisition Is Initialization)

# Resources are automatically cleaned up when they go out of scope
fn process_file() {
    let file = open("data.txt")  # File opened
    let data = file.read()
    process(data)
    # file is automatically closed here when it goes out of scope
}

📘 Chapter 17: Low-Level & Systems Programming

Inline Assembly

import std/asm

# Write inline assembly (x86-64)
let builder = AsmBuilder.new("intel")
builder.mov("rax", 1)
builder.mov("rdi", 42)
builder.syscall()
let code = builder.build()

# ARM assembly
let arm = AsmBuilder.new("arm")
arm.mov("r0", 0)
arm.add("r0", "r0", 1)

SIMD Vectorization

import std/simd

# Detect CPU SIMD capabilities
let caps = SIMD_ISA.detect()
print(caps.has_avx2)   # true/false
print(caps.has_neon)   # true/false (ARM)

# Vector math — 4-16x faster than scalar
let a = Vec4f(1.0, 2.0, 3.0, 4.0)
let b = Vec4f(5.0, 6.0, 7.0, 8.0)
let c = a + b  # [6.0, 8.0, 10.0, 12.0] — single CPU instruction!
let d = a * b  # [5.0, 12.0, 21.0, 32.0]
let dot = a.dot(b)  # 70.0

Memory Allocators

import std/allocators

# Arena allocator — ultra-fast, bulk-free
let arena = ArenaAllocator.new(1024 * 1024)  # 1MB
let ptr1 = arena.alloc(256)
let ptr2 = arena.alloc(512)
arena.reset()  # Free everything at once — no per-object overhead

# Pool allocator — fixed-size objects, zero fragmentation
let pool = PoolAllocator.new(64, 1024)  # 64-byte objects, 1024 slots
let obj = pool.alloc()
pool.free(obj)

# Slab allocator — kernel-grade
let slab = SlabAllocator.new([32, 64, 128, 256, 512, 1024])
let ptr = slab.alloc(100)  # Gets 128-byte slab

Atomic Operations

import std/atomics

let counter = AtomicI32.new(0)
counter.fetch_add(1)     # Thread-safe increment
counter.compare_and_swap(1, 2)  # CAS operation

# Lock-free data structures
let stack = LockFreeStack()
stack.push(42)
let val = stack.pop()    # 42 — no locks, no blocking

Hardware Access

import std/hardware

# Read CPU information
let cpu = CPUID.read()
print(cpu.vendor)        # "GenuineIntel"
print(cpu.model_name)    # "Intel Core i9-13900K"
print(cpu.cores)         # 24

# Control registers (requires kernel mode)
let cr0 = ControlRegister.read_cr0()
let cr3 = ControlRegister.read_cr3()  # Page table base

DMA (Direct Memory Access)

import std/dma

# Zero-copy I/O with DMA
let buf = DMABuffer.alloc(4096, "read")
buf.lock()        # Pin in physical memory
# ... device reads directly into buf ...
buf.unlock()
let data = buf.read(0, 4096)

📘 Chapter 18: FFI & C Interop

Calling C Functions

import std/ffi

# Load a shared library
let libc = ffi.open("libc.so.6")  # Linux
# let libc = ffi.open("msvcrt.dll")  # Windows
# let libc = ffi.open("libSystem.dylib")  # macOS

# Get function pointer
let printf = libc.symbol("printf")

# Call C function
ffi.call(printf, "Hello from C! %d\n", 42)

# Close library
libc.close()

C Memory Operations

# Allocate C memory
let ptr = ffi.malloc(256)

# Write data
ffi.poke(ptr, 0, 42)      # Write 42 at offset 0
ffi.poke(ptr, 4, 100)     # Write 100 at offset 4

# Read data
let val = ffi.peek(ptr, 0) # Read from offset 0 → 42

# Free memory
ffi.free(ptr)

C String Interop

# Convert Nyx string to C string
let c_str = ffi.to_c_string("Hello, C!")

# Pass to C function
ffi.call(puts, c_str)

# Convert back
let nyx_str = ffi.from_c_string(c_ptr)

📘 Chapter 19: Testing & Debugging

Writing Tests

import std/test

# Basic assertions
assert(1 + 1 == 2)
assert(true)

# Equality
eq(add(2, 3), 5)
neq(add(2, 3), 6)

# Approximate (for floating point)
approx(3.14159, 3.14, 0.01)

# Contains
contains_([1, 2, 3], 2)

# Test that errors are thrown
raises(fn() { divide(1, 0) })

# Test suites
fn test_math() {
    eq(add(1, 2), 3)
    eq(multiply(3, 4), 12)
    eq(factorial(5), 120)
    print("All math tests passed!")
}

fn test_strings() {
    eq(upper("hello"), "HELLO")
    eq(len("Nyx"), 3)
    print("All string tests passed!")
}

test_math()
test_strings()

Runtime Debugging Flags

# Trace execution (see every step)
nyx --trace program.ny

# Debug mode (detailed error messages)
nyx --debug program.ny

# Step-through debugging
nyx --step program.ny

# Set breakpoints
nyx --break program.ny

# Parse only (syntax check, don't run)
nyx --parse-only program.ny
nyx --lint program.ny

# Memory profiling
nyx --profile-memory program.ny
nyx --max-alloc 100000 program.ny

# Limit execution
nyx --max-steps 1000000 program.ny
nyx --max-call-depth 100 program.ny

Benchmarking

import std/bench

bench("fibonacci", fn() {
    fibonacci(30)
})

bench("sort 10000", fn() {
    sort(range(10000))
})

📘 Chapter 20: File I/O & Networking

File Operations

import std/io

# Read entire file
let content = read_file("data.txt")
print(content)

# Read lines
let lines = read_lines("data.txt")
for line in lines {
    print(line)
}

# Write file
write_file("output.txt", "Hello, World!")

# Append to file
append_file("log.txt", "New log entry\n")

# File operations
file_exists("data.txt")    # true/false
file_size("data.txt")      # bytes
copy_file("a.txt", "b.txt")
move_file("old.txt", "new.txt")
mkdir("new_directory")

JSON

import std/json

# Parse JSON string
let data = json.parse('{"name": "Nyx", "version": 6}')
print(data.name)    # "Nyx"
print(data.version) # 6

# Create JSON string
let obj = {name: "Nyx", features: ["fast", "safe", "easy"]}
let json_str = json.stringify(obj)
print(json_str)
# {"name":"Nyx","features":["fast","safe","easy"]}

# Pretty print
let pretty = json.pretty(obj)

HTTP Client

import std/http

# GET request
let response = http.request({
    method: "GET",
    url: "https://api.example.com/data",
    headers: {"Accept": "application/json"},
    timeout: 5000
})
print(response.status)  # 200
print(response.body)

# POST request
let post_response = http.request({
    method: "POST",
    url: "https://api.example.com/users",
    headers: {"Content-Type": "application/json"},
    body: json.stringify({name: "Nyx", type: "language"})
})

HTTP Server (Native — No Framework Needed!)

use nyhttpd

let server = nyhttpd.HttpServer.new({
    port: 8080,
    worker_threads: 4
})

# Define routes
server.get("/", fn(req, res) {
    res.html("<h1>Welcome to Nyx!</h1>")
})

server.get("/api/hello", fn(req, res) {
    res.json({message: "Hello from Nyx!", time: date.now()})
})

server.post("/api/echo", fn(req, res) {
    res.json({echo: req.body})
})

print("Server running on http://localhost:8080")
server.start()

WebSocket

import std/socket

let ws = WebSocket.connect("ws://localhost:8080/ws")
ws.send("Hello, server!")
let msg = ws.receive()
print("Server says: " + msg)
ws.close()

� Chapter 21: Enums & Structs

Basic Enums

enum Direction {
    North,
    South,
    East,
    West
}

let heading = Direction.North

match heading {
    case Direction.North => print("Going north!")
    case Direction.South => print("Going south!")
    case Direction.East => print("Going east!")
    case Direction.West => print("Going west!")
}

Enums with Associated Data

enum Shape {
    Circle(radius: float),
    Rectangle(width: float, height: float),
    Triangle(base: float, height: float),
    Point
}

fn area(shape: Shape) -> float = match shape {
    case Shape.Circle(r) => 3.14159 * r * r
    case Shape.Rectangle(w, h) => w * h
    case Shape.Triangle(b, h) => 0.5 * b * h
    case Shape.Point => 0.0
}

let shapes = [
    Shape.Circle(5.0),
    Shape.Rectangle(4.0, 6.0),
    Shape.Triangle(3.0, 8.0),
    Shape.Point
]
for s in shapes {
    print("Area: " + str(area(s)))
}

Structs

struct Point {
    x: float,
    y: float
}

struct Color {
    r: u8,
    g: u8,
    b: u8,
    a: u8 = 255   # Default value
}

let p = Point { x: 10.0, y: 20.0 }
let c = Color { r: 255, g: 128, b: 0 }  # a defaults to 255

print(p.x)  # 10.0
print(c.a)  # 255

Struct Methods via impl

struct Vector2D {
    x: float,
    y: float
}

impl Vector2D {
    fn new(x: float, y: float) -> Vector2D {
        return Vector2D { x: x, y: y }
    }

    fn magnitude(self) -> float {
        return sqrt(self.x * self.x + self.y * self.y)
    }

    fn normalize(self) -> Vector2D {
        let mag = self.magnitude()
        return Vector2D { x: self.x / mag, y: self.y / mag }
    }

    fn dot(self, other: Vector2D) -> float {
        return self.x * other.x + self.y * other.y
    }

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

    fn scale(self, factor: float) -> Vector2D {
        return Vector2D { x: self.x * factor, y: self.y * factor }
    }
}

let v1 = Vector2D.new(3.0, 4.0)
print(v1.magnitude())    # 5.0
print(v1.normalize())    # Vector2D { x: 0.6, y: 0.8 }
print(v1.dot(Vector2D.new(1.0, 0.0)))  # 3.0

Type Aliases

type UserId = int
type Email = str
type Callback = fn(int) -> bool
type Matrix = [[float]]
type Result<T> = Ok(T) | Err(str)

📘 Chapter 22: Iterators & Generators

Generators with yield

fn fibonacci() {
    let mut a = 0
    let mut b = 1
    loop {
        yield a
        let temp = a
        a = b
        b = temp + b
    }
}

# First 10 fibonacci numbers
for i, fib in fibonacci() |> take(10) {
    print(str(i) + ": " + str(fib))
}

Infinite Sequences

fn naturals(start = 0) {
    let mut n = start
    loop {
        yield n
        n = n + 1
    }
}

fn primes() {
    for n in naturals(2) {
        let mut is_prime = true
        for d in 2..n {
            if n % d == 0 {
                is_prime = false
                break
            }
        }
        if is_prime { yield n }
    }
}

# First 20 primes
let first_20_primes = primes() |> take(20) |> collect()
print(first_20_primes)
# [2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47, 53, 59, 61, 67, 71]

Iterator Combinators

# Chain iterators
let combined = [1, 2, 3] |> chain([4, 5, 6]) |> collect()
# [1, 2, 3, 4, 5, 6]

# Zip two iterators
let pairs = [1, 2, 3] |> zip(["a", "b", "c"]) |> collect()
# [(1, "a"), (2, "b"), (3, "c")]

# Enumerate
let indexed = ["x", "y", "z"] |> enumerate() |> collect()
# [(0, "x"), (1, "y"), (2, "z")]

# Take / skip / step
let slice = 0..100 |> skip(10) |> take(5) |> collect()
# [10, 11, 12, 13, 14]

# Flat map
let words = ["hello world", "foo bar"]
    |> flat_map(|s| s.split(" "))
    |> collect()
# ["hello", "world", "foo", "bar"]

📘 Chapter 23: Macros & Metaprogramming

Declarative Macros

macro vec!(...items) {
    let arr = []
    for item in items {
        push(arr, item)
    }
    arr
}

let v = vec!(1, 2, 3, 4, 5)
print(v)  # [1, 2, 3, 4, 5]

Code Generation Macros

macro derive_debug!(T) {
    impl T {
        fn debug(self) -> str {
            let fields = reflect(T).fields()
            let parts = []
            for f in fields {
                push(parts, f.name + ": " + str(self[f.name]))
            }
            return type_name(T) + " { " + join(parts, ", ") + " }"
        }
    }
}

@derive_debug!
struct User {
    name: str,
    age: int,
    email: str
}

let u = User { name: "Nyx", age: 1, email: "nyx@lang.dev" }
print(u.debug())
# User { name: Nyx, age: 1, email: nyx@lang.dev }

Hygienic Macros

Nyx macros are hygienic — variables inside a macro don't leak into surrounding scope:

macro swap!(a, b) {
    let temp = a
    a = b
    b = temp
}

let mut x = 10
let mut y = 20
swap!(x, y)
print(x)  # 20
print(y)  # 10
# 'temp' does NOT exist here — it's scoped to the macro

📘 Chapter 24: Compile-Time Computation (comptime)

Comptime Functions

import std/comptime

# Computed at compile time, not runtime
comptime fn fibonacci(n: int) -> int {
    if n <= 1 { return n }
    return fibonacci(n - 1) + fibonacci(n - 2)
}

# This is a constant — computed during compilation
const FIB_20 = fibonacci(20)  # 6765, computed at compile time

# Generate lookup tables at compile time
comptime fn generate_lookup_table(size: int) -> [int] {
    let table = []
    for i in 0..size {
        push(table, i * i)
    }
    return table
}

const SQUARES = generate_lookup_table(256)

Static Assertions

# Checked at compile time
static_assert(sizeof(int) == 8, "int must be 8 bytes")
static_assert(alignof(float) >= 4, "float must be 4-byte aligned")

comptime fn assert_size(T: type, expected: int) {
    static_assert(sizeof(T) == expected)
}

Compile-Time Code Generation

import std/comptime

comptime fn generate_accessors(T: type) {
    let fields = reflect(T).fields()
    for f in fields {
        # Generate getter
        generate_code("fn get_" + f.name + "(self) -> " + f.type_name + " { return self." + f.name + " }")
        # Generate setter
        generate_code("fn set_" + f.name + "(self, val: " + f.type_name + ") { self." + f.name + " = val }")
    }
}

comptime fn generate_builder(T: type) {
    # Auto-generates a Builder pattern for any struct
    let fields = reflect(T).fields()
    generate_code("class " + type_name(T) + "Builder {")
    for f in fields {
        generate_code("    " + f.name + ": Option<" + f.type_name + "> = None")
    }
    for f in fields {
        generate_code("    fn " + f.name + "(self, val: " + f.type_name + ") -> Self { self." + f.name + " = Some(val); return self }")
    }
    generate_code("    fn build(self) -> " + type_name(T) + " { ... }")
    generate_code("}")
}

Compile-Time Reflection

import std/comptime

# Inspect any type at compile time
let info = Reflect.new(MyStruct)
print(info.type_name())     # "MyStruct"
print(info.type_size())     # 24
print(info.type_align())    # 8
print(info.fields())        # [FieldInfo { name: "x", ... }, ...]
print(info.methods())       # [MethodInfo { name: "new", ... }, ...]
print(info.traits())        # [TraitInfo { name: "Debug", ... }, ...]
print(info.implements_trait("Debug"))  # true

📘 Chapter 25: Advanced Type System

Dependent Types

import std/types_advanced

# Vec with compile-time-known length
let v3: Vec<float, 3> = Vec.new()  # A vector that MUST have exactly 3 elements
v3.push(1.0)
v3.push(2.0)
v3.push(3.0)
# v3.push(4.0)  # COMPILE ERROR: Vec<float, 3> is full

# Append preserves length information
let v5: Vec<float, 5> = v3.append(Vec.from([4.0, 5.0]))  # 3 + 2 = 5

Refinement Types

import std/types_advanced

# A type that only accepts positive numbers
struct Positive {
    fn check(value: int) -> bool = value > 0
}

let x: Refined<int, Positive> = Refined.new(42)   # OK
# let y: Refined<int, Positive> = Refined.new(-1) # COMPILE ERROR

# Use as regular int
let val = x.get()  # 42

Union Types

type StringOrInt = str | int
type Primitive = int | float | bool | str | null

fn process(value: StringOrInt) {
    match value {
        case s: str => print("String: " + s)
        case n: int => print("Number: " + str(n))
    }
}

Generic Constraints

trait Hashable {
    fn hash(self) -> int
}

trait Comparable {
    fn compare(self, other: Self) -> int
}

# Generic with multiple constraints
fn sorted_unique<T: Hashable + Comparable>(items: [T]) -> [T] {
    return items |> unique() |> sort()
}

# Where clause for complex constraints
fn merge<K, V>(a: Map<K, V>, b: Map<K, V>) -> Map<K, V>
    where K: Hashable + Comparable,
          V: Clone
{
    let result = a.clone()
    for (k, v) in b.items() {
        result[k] = v.clone()
    }
    return result
}

Higher-Kinded Types

# F is a type constructor (like Array, Option, Result...)
trait Functor<F> {
    fn map<A, B>(self: F<A>, f: fn(A) -> B) -> F<B>
}

trait Monad<M> extends Functor<M> {
    fn pure<A>(value: A) -> M<A>
    fn flat_map<A, B>(self: M<A>, f: fn(A) -> M<B>) -> M<B>
}

Optional Type (T? syntax)

# Nullable type shorthand
let name: str? = get_user_name()  # Might be null

# Safe navigation
let city = user?.address?.city   # Returns null if any part is null

# Null coalescing
let display_name = name ?? "Anonymous"

# Unwrap with default
let age = user?.age.unwrap_or(0)

📘 Chapter 26: Decorators & Attributes

Function Decorators

@deprecated("Use new_function instead")
fn old_function() {
    # ...
}

@inline
fn fast_add(a: int, b: int) -> int = a + b

@test
fn test_addition() {
    eq(fast_add(2, 3), 5)
}

# Custom decorator
fn memoize(func) {
    let mut cache = {}
    return fn(...args) {
        let key = str(args)
        if !has(cache, key) {
            cache[key] = func(...args)
        }
        return cache[key]
    }
}

@memoize
fn expensive_computation(n) {
    # Only computed once per unique n
    return fibonacci(n)
}

Struct/Class Attributes

@derive(Debug, Clone, PartialEq)
struct Config {
    host: str,
    port: int,
    max_connections: int = 100
}

@serializable
@validate
class User {
    @required
    name: str

    @required @format("email")
    email: str

    @min(0) @max(150)
    age: int
}

📘 Chapter 27: Unsafe & Raw Memory

Unsafe Blocks

import std/systems_extended

# Unsafe code is explicitly marked
unsafe {
    let ptr = _sys_malloc(256)
    _sys_memset(ptr, 0, 256)
    _sys_poke(ptr, 0, 42)
    let val = _sys_peek(ptr, 0)
    print(val)  # 42
    _sys_free(ptr)
}

Raw Pointer Operations

import std/systems_extended

unsafe {
    # Allocate
    let ptr = _sys_malloc(1024)
    let zeroed = _sys_calloc(256, 4)  # 256 × 4 bytes, zeroed
    let resized = _sys_realloc(ptr, 2048)

    # Copy/move memory
    _sys_memcpy(dest, src, 512)
    _sys_memmove(dest, src, 512)  # Handles overlapping

    # Compare memory
    let cmp = _sys_memcmp(a, b, 64)  # 0 if equal

    # Volatile reads/writes (won't be optimized away)
    let val = _sys_volatile_read(mmio_addr)
    _sys_volatile_write(mmio_addr, 0xFF)

    # Cache control
    _sys_cache_flush(ptr, 64)
    _sys_cache_invalidate(ptr, 64)
    _sys_prefetch(ptr)
}

Bit Manipulation

import std/systems_extended

bit_set(value, 3)       # Set bit 3
bit_clear(value, 5)     # Clear bit 5
bit_toggle(value, 0)    # Toggle bit 0
bit_test(value, 7)      # Test bit 7 → true/false

let mask = bit_mask(4, 8)          # Mask bits 4-8
let extracted = bit_extract_bits(value, 4, 8)  # Extract bits 4-8

popcount(0xFF)          # 8 — count set bits
leading_zeros(0x0F)     # 28 — count leading zeros
trailing_zeros(0xF0)    # 4 — count trailing zeros

Platform Detection

import std/systems_extended

let platform = get_platform()  # "windows", "linux", "macos"
let arch = get_arch()          # "x86_64", "aarch64", "riscv64"

📘 Chapter 28: Cryptography

Hashing (20+ Algorithms — All Built-in)

import std/crypto

# Common hash functions
let h1 = sha256("hello world")
let h2 = sha512("hello world")
let h3 = sha3_256("hello world")
let h4 = blake2b("hello world")
let h5 = blake3("hello world")
let h6 = md5("hello world")
let h7 = sha1("hello world")

# Fast non-crypto hashes
let h8 = fnv1a32("hello")
let h9 = fnv1a64("hello")
let h10 = djb2("hello")
let h11 = crc32("hello")
let h12 = crc32_fast("hello")    # Hardware-accelerated
let h13 = murmur3_32("hello", 42)
let h14 = murmur3_128("hello", 42)

# Combine hashes
let combined = hash_combine(h8, h9)

Ciphers

import std/crypto

# XOR encryption
let encrypted = xor_encrypt("secret message", "mykey")
let decrypted = xor_decrypt(encrypted, "mykey")

# Caesar cipher
let shifted = caesar_cipher("HELLO", 3)  # "KHOOR"

# Vigenère cipher
let vig_enc = vigenere_encrypt("ATTACKATDAWN", "LEMON")
let vig_dec = vigenere_decrypt(vig_enc, "LEMON")

# ROT13
let rotated = rot13("Hello World")

Hardware-Accelerated Crypto (AES-NI)

import std/crypto_hw

# Check CPU support
if AES_NI.is_supported() {
    # AES-128 CBC encryption (hardware-accelerated)
    let key = [0x2b, 0x7e, 0x15, 0x16, ...]  # 16 bytes
    let iv = [0x00, 0x01, 0x02, 0x03, ...]    # 16 bytes
    let plaintext = [0x6b, 0xc1, ...]

    let ciphertext = AES_NI.encrypt_cbc(plaintext, key, iv)
    let decrypted = AES_NI.decrypt_cbc(ciphertext, key, iv)

    # AES-GCM (authenticated encryption)
    let result = AES_NI.encrypt_gcm(plaintext, key, iv, aad)
    # result contains ciphertext + authentication tag
}

# Hardware SHA
if SHA_EXT.is_supported() {
    let digest = SHA_EXT.sha256(data)  # Hardware-accelerated SHA-256
    let sha1_digest = SHA_EXT.sha1(data)
}

# Hardware CRC32C
if CRC32C.is_supported() {
    let checksum = CRC32C.crc32_u32(0, data)
}

📘 Chapter 29: Database & Storage

Key-Value Store

import std/database

let store = KVStore()
store.put("user:1", {name: "Alice", age: 30})
store.put("user:2", {name: "Bob", age: 25})

let user = store.get("user:1")
print(user.name)  # "Alice"

# Query
let young_users = store.query(|k, v| v.age < 28)
store.create_index("age")

File-Backed Persistent Store

import std/database

let db = FileKVStore("mydata.json")
db.load()
db.put("config", {theme: "dark", lang: "nyx"})
db.save()
# Data persists across restarts

Relational Tables

import std/database

let db = Database()
let users = db.create_table("users", {
    id: "int",
    name: "str",
    email: "str",
    age: "int"
})

users.insert({id: 1, name: "Alice", age: 30, email: "alice@example.com"})
users.insert({id: 2, name: "Bob", age: 25, email: "bob@example.com"})
users.insert({id: 3, name: "Charlie", age: 35, email: "charlie@example.com"})

# Queries
let adults = users.select(|row| row.age >= 18)
let names = users.select(|row| true) |> map(|row| row.name)

# Aggregations
let avg_age = users.avg("age")
let total_users = users.count()
let oldest = users.max("age")

# Order and limit
let top_3 = users.order_by("age").limit(3)

# Group by
let by_age = users.group_by("age")

# Create index for fast lookups
users.create_index("email")

Document Store (NoSQL)

import std/database

let docs = DocumentStore()
docs.insert({name: "Nyx", type: "language", version: 6})
docs.insert({name: "Python", type: "language", version: 3})

let languages = docs.find({type: "language"})
let nyx = docs.find_one({name: "Nyx"})

docs.create_index("name")
let fast_lookup = docs.find_by_index("name", "Nyx")

Redis Client

import std/redis

let client = RedisClient("localhost", 6379)
client.connect()

# String operations
client.set("greeting", "Hello, Nyx!")
let val = client.get("greeting")

# List operations
client.lpush("queue", "task1")
client.lpush("queue", "task2")
let task = client.rpop("queue")

# Hash operations
client.hset("user:1", "name", "Alice")
client.hset("user:1", "age", "30")
let name = client.hget("user:1", "name")

# Set operations
client.sadd("tags", "nyx")
client.sadd("tags", "language")
let members = client.smembers("tags")

# Pub/Sub
client.subscribe("events")
client.publish("events", "user_logged_in")

client.disconnect()

Caching

import std/cache

# LRU Cache (Least Recently Used)
let cache = LRUCache(1000, 3600)  # 1000 max entries, 1 hour TTL
cache.set("user:1", {name: "Alice"})
let user = cache.get("user:1")  # Cache hit

# Check stats
let stats = cache.stats()
print(stats.hits)
print(stats.misses)
print(stats.hit_rate)

# LFU Cache (Least Frequently Used)
let lfu = LFUCache(500, 1800)
lfu.set("hot_data", compute_expensive())

📘 Chapter 30: GUI & Desktop Applications

Creating a Window

import std/gui

let app = Application()
let window = Window("My Nyx App", 800, 600)

window.resizable(true)
window.minsize(400, 300)

# Add widgets
window.add_label("title", "Welcome to Nyx!", {font_size: 24, bold: true})
window.add_button("click_me", "Click Me!", fn() {
    print("Button clicked!")
})

# Text input
window.add_entry("name_input", {placeholder: "Enter your name..."})
window.add_button("submit", "Submit", fn() {
    let name = window.get_value("name_input")
    window.update_label("title", "Hello, " + name + "!")
})

# Menu bar
window.create_menu("File", [
    {label: "New", shortcut: "Ctrl+N", action: fn() { new_file() }},
    {label: "Open", shortcut: "Ctrl+O", action: fn() { open_file() }},
    {label: "Save", shortcut: "Ctrl+S", action: fn() { save_file() }},
    {label: "---"},  # Separator
    {label: "Exit", action: fn() { app.quit() }}
])

# Toolbar
window.create_toolbar([
    {icon: "new", tooltip: "New File", action: new_file},
    {icon: "open", tooltip: "Open File", action: open_file},
    {icon: "save", tooltip: "Save File", action: save_file}
])

# Status bar
window.create_statusbar("Ready")

# Event binding
window.bind("resize", fn(event) {
    print("Window resized to " + str(event.width) + "x" + str(event.height))
})

# Timers
window.set_timer(1000, fn() {
    window.update_statusbar("Updated: " + str(time.now()))
})

app.run(window)

Game Development

import std/game

# Full game engine — colors, keys, surfaces, clock
let BLACK = game.BLACK
let WHITE = game.WHITE
let RED = game.RED

let game_window = Game("My Nyx Game", 800, 600)
let clock = Clock()

class Player {
    fn init(self) {
        self.x = 400
        self.y = 300
        self.speed = 5
        self.health = 100
    }

    fn update(self, keys) {
        if keys[game.K_w] { self.y = self.y - self.speed }
        if keys[game.K_s] { self.y = self.y + self.speed }
        if keys[game.K_a] { self.x = self.x - self.speed }
        if keys[game.K_d] { self.x = self.x + self.speed }
        self.x = clamp(self.x, 0, 800)
        self.y = clamp(self.y, 0, 600)
    }

    fn draw(self, surface) {
        surface.fill_rect(self.x - 16, self.y - 16, 32, 32, RED)
    }
}

let player = Player()

# Game loop
game_window.run(fn(surface, events, keys) {
    surface.fill(BLACK)
    player.update(keys)
    player.draw(surface)
    clock.tick(60)  # 60 FPS
})

Data Visualization

import std/visualize

# 140+ named colors, 8 palettes, 12 gradient maps
# Full matplotlib/plotly-equivalent plotting

let data = [1, 4, 9, 16, 25, 36, 49, 64, 81, 100]
let chart = BarChart(data, {
    title: "Squares",
    x_label: "n",
    y_label: "n²",
    color_palette: "viridis"
})
chart.save("squares.png")

📚 Standard Library (109 Modules — Full API Reference)

All 109 modules are native and free to use. No nypm install needed. Just import and go.

Core Modules

Math & Science

import std/symbolic
let x = Symbol("x")
let expr = x**2 + 2*x + 1
print(expr.factor())      # (x + 1)^2
print(expr.diff(x))       # 2*x + 2
print(expr.integrate(x))  # x^3/3 + x^2 + x
print(expr.subs(x, 3))    # 16

Data Structures

I/O & Serialization

Networking

Async & Concurrency

Cryptography

Database

AI & Machine Learning

Systems & Low-Level

VM & Hypervisor (10 Modules)

GUI, Game & Visualization

DevOps & Tooling

import std/log
let logger = get_logger("myapp")
logger.set_level(DEBUG)
logger.add_handler(ConsoleHandler())
logger.add_handler(FileHandler("app.log"))
logger.info("Application started")
logger.error("Something went wrong")

DFAS — Dynamic Field Arithmetic (10 modules in stdlib/dfas/)

🔥 All 117+ Engines (Complete Reference)

All engines are native and built-in. No installation required. Just use engine_name and go. 113 engine directories exist in engines/ covering every domain from AI to robotics.

AI & Machine Learning (21 Engines)

// Example: Train a neural network with nynet + nyopt
use nytensor
use nynet
use nyopt
use nyloss

let model = Sequential([
    Linear(784, 256),
    ReLU(),
    Dropout(0.2),
    Linear(256, 128),
    ReLU(),
    Linear(128, 10),
    Softmax()
])

let optimizer = Adam(model.parameters(), lr: 0.001, weight_decay: 1e-4)
let scheduler = CosineAnnealing(optimizer, T_max: 100)
let loss_fn = CrossEntropy()

for epoch in 0..100 {
    for batch in train_loader {
        let output = model.forward(batch.x)
        let loss = loss_fn(output, batch.y)
        loss.backward()
        optimizer.step()
        optimizer.zero_grad()
    }
    scheduler.step()
    print(f"Epoch {epoch}: loss={loss.item():.4f}")
}

GPU & High-Performance Computing (7 Engines)

// Example: GPU tensor computation
use nygpu
use nytensor

let device = nygpu.best_device()  // Auto-select fastest GPU
let a = nytensor.randn([1024, 1024]).to(device)
let b = nytensor.randn([1024, 1024]).to(device)
let c = a.matmul(b)  // GPU-accelerated matrix multiply
print(f"Result shape: {c.shape}, device: {c.device}")

Data & Storage (9 Engines)

// Example: Data pipeline with nyframe
use nyframe

let df = nyframe.read_csv("sales.csv")
    |> filter(|row| row.amount > 100)
    |> group_by("region")
    |> agg({
        total: sum("amount"),
        avg_amount: mean("amount"),
        count: count()
    })
    |> sort_by("total", descending: true)

df.to_csv("report.csv")
df.show(10)

Web & Networking (6 Engines)

// Example: Full REST API with authentication
use nyhttpd
use nyapi

let server = nyhttpd.HttpServer.new({port: 3000, workers: 4})

// Middleware
server.use(nyapi.cors({origins: ["*"]}))
server.use(nyapi.rate_limit({max: 100, window: "1m"}))
server.use(nyapi.jwt_auth({secret: env("JWT_SECRET"), exclude: ["/auth/login"]}))

// Routes
server.get("/api/users", fn(req, res) {
    let users = db.query("SELECT * FROM users LIMIT $1 OFFSET $2",
        [req.query.limit ?? 20, req.query.offset ?? 0])
    res.json({data: users, total: db.count("users")})
})

server.post("/auth/login", fn(req, res) {
    let user = db.find_one("users", {email: req.body.email})
    if user and verify_password(req.body.password, user.hash) {
        res.json({token: nyapi.jwt_sign({sub: user.id}, "24h")})
    } else {
        res.status(401).json({error: "Invalid credentials"})
    }
})

server.start()

Security & Crypto (9 Engines)

Multimedia & Games (8 Engines)

// Example: 2D game with ECS
use nygame

let game = nygame.Game("Space Shooter", 800, 600)

// Define components
struct Position { x: f32, y: f32 }
struct Velocity { dx: f32, dy: f32 }
struct Sprite { texture: string, width: int, height: int }
struct Health { hp: int, max_hp: int }

// Create entities
let player = game.spawn()
    .with(Position { x: 400.0, y: 500.0 })
    .with(Velocity { dx: 0.0, dy: 0.0 })
    .with(Sprite { texture: "ship.png", width: 64, height: 64 })
    .with(Health { hp: 100, max_hp: 100 })

// Game loop
game.on_update(fn(dt) {
    // Movement system
    for entity in game.query(Position, Velocity) {
        entity.get(Position).x += entity.get(Velocity).dx * dt
        entity.get(Position).y += entity.get(Velocity).dy * dt
    }
})

game.run()

DevOps & Infrastructure (8 Engines)

Science & Simulation (6 Engines)

Finance & Trading (5 Engines)

// Example: Algorithmic trading strategy
use nytrade
use nymarket
use nybacktest

let strategy = nybacktest.Strategy("MeanReversion")

strategy.on_bar(fn(bar, portfolio) {
    let sma_20 = bar.close.sma(20)
    let std_20 = bar.close.std(20)
    let z_score = (bar.close[-1] - sma_20) / std_20

    if z_score < -2.0 and !portfolio.has_position(bar.symbol) {
        portfolio.buy(bar.symbol, shares: 100)
    } else if z_score > 0.0 and portfolio.has_position(bar.symbol) {
        portfolio.sell(bar.symbol, shares: 100)
    }
})

let results = nybacktest.run(strategy, {
    data: nymarket.historical("AAPL", "2020-01-01", "2024-12-31"),
    initial_capital: 100000,
    commission: 0.001
})
results.report()

Distributed Systems (6 Engines)

Robotics & IoT (3 Engines)

Build, Config & Core (15+ Additional Engines)

🏗️ Formal Grammar (EBNF)

Complete Extended Backus-Naur Form grammar for the Nyx programming language.

Program Structure

program        = { statement } ;
statement      = declaration | expression_stmt | control_flow | import_stmt
               | class_decl | module_decl | try_stmt | raise_stmt
               | assert_stmt | with_stmt | async_stmt | pass_stmt ;

declaration    = let_decl | fn_decl | typealias_decl ;
let_decl       = "let" [ "mut" ] identifier [ ":" type ] "=" expression ;
fn_decl        = "fn" identifier "(" [ param_list ] ")" [ "->" type ] block ;
typealias_decl = "typealias" identifier "=" type ;

Expressions

expression     = assignment ;
assignment     = ( postfix "=" ) assignment | logical_or ;
logical_or     = logical_and { "||" logical_and } ;
logical_and    = bitwise_or { "&&" bitwise_or } ;
bitwise_or     = bitwise_xor { "|" bitwise_xor } ;
bitwise_xor    = bitwise_and { "^" bitwise_and } ;
bitwise_and    = equality { "&" equality } ;
equality       = relational { ( "==" | "!=" ) relational } ;
relational     = shift { ( "<" | ">" | "<=" | ">=" | "<=>" | "is" | "instanceof" ) shift } ;
shift          = additive { ( "<<" | ">>" ) additive } ;
additive       = multiplicative { ( "+" | "-" ) multiplicative } ;
multiplicative = power { ( "*" | "/" | "%" | "//" ) power } ;
power          = unary { "**" unary } ;
unary          = ( "-" | "!" | "~" | "++" | "--" | "&" | "&mut" | "*" | "typeof"
               | "sizeof" | "alignof" | "move" | "ref" ) unary | postfix ;
postfix        = primary { call | index | member | "?" | "++" | "--" } ;
call           = "(" [ arg_list ] ")" ;
index          = "[" expression "]" ;
member         = ( "." | "?." | "::" ) identifier ;

Primary Expressions

primary        = literal | identifier | block | if_expr | switch_expr
               | fn_literal | array_literal | object_literal | tuple_literal
               | "(" expression ")" | comprehension | new_expr | "super"
               | "self" | await_expr ;
literal        = integer | float | string | boolean | "null" ;
integer        = decimal | "0x" hex | "0o" octal | "0b" binary ;
string         = '"' { char | escape } '"' | "'" { char | escape } "'"
               | 'r"' { char } '"' | 'b"' { byte } '"' | 'f"' { char | "${" expression "}" } '"' ;

Control Flow

if_expr        = "if" expression block { "elif" expression block } [ "else" block ] ;
switch_expr    = "switch" expression "{" { case_clause } [ default_clause ] "}" ;
match_expr     = "match" expression "{" { pattern "=>" expression "," } "}" ;
while_stmt     = "while" expression block ;
for_stmt       = "for" identifier "=" expression ";" expression ";" expression block ;
for_in_stmt    = "for" pattern "in" expression block ;
loop_stmt      = "loop" block ;

Class & Struct Declarations

class_decl     = "class" identifier [ "<" type_params ">" ] [ "extends" type ]
                 [ "implements" type { "," type } ] "{" { class_member } "}" ;
struct_decl    = "struct" identifier [ "<" type_params ">" ] "{" { struct_field } "}" ;
enum_decl      = "enum" identifier "{" enum_variant { "," enum_variant } "}" ;
trait_decl     = "trait" identifier [ "<" type_params ">" ] "{" { method_sig } "}" ;
impl_block     = "impl" [ "<" type_params ">" ] [ trait "for" ] type "{" { fn_decl } "}" ;

Type System

type           = primitive_type | compound_type | ref_type | user_type
               | generic_type | tuple_type | union_type | fn_type ;
primitive_type = "int" | "i8" | "i16" | "i32" | "i64" | "u8" | "u16" | "u32" | "u64"
               | "f32" | "f64" | "bool" | "char" | "str" | "void" | "null" | "never" ;
ref_type       = ( "&" | "&mut" ) type ;
generic_type   = identifier "<" type { "," type } ">" ;
union_type     = type "|" type { "|" type } ;
fn_type        = "fn" "(" [ type_list ] ")" "->" type ;

Operator Precedence (12 Levels)

🧠 Interpreter Architecture (Complete Internals)

The complete pipeline from source code to execution — every component documented.

Execution Pipeline

Source Code (.ny)
     │
     ▼
┌──────────────────────────────────────────────────────────┐
│   Lexer (src/lexer.py)                                    │
│   Unicode-aware tokenizer · 150+ token types              │
│   Supports: raw/byte/format/multiline strings             │
│   Number formats: decimal, hex, octal, binary, scientific │
│   Comments: # line, // line, /* block */ (nested)         │
│   Token hooks & runtime-extensible registry               │
└──────────────────────┬───────────────────────────────────┘
                       │ Token Stream (with position & trivia)
                       ▼
┌──────────────────────────────────────────────────────────┐
│   Parser (src/parser.py)                                  │
│   Pratt parser · 11 precedence levels · extensible        │
│   25 prefix parse functions · 14 infix parse functions    │
│   20+ statement parsers · Automatic error recovery        │
│   Dynamic registration: register_prefix/infix/statement   │
└──────────────────────┬───────────────────────────────────┘
                       │ AST (70+ node types with source locations)
                       ▼
┌──────────────────────────────────────────────────────────┐
│   Interpreter (src/interpreter.py)                        │
│   Async tree-walking evaluator · 11 built-ins             │
│   Scoped Environment chain · Boxed value types            │
│   NyxClass/UserFunction · 1M step limit (configurable)    │
│   Module system with import resolvers                     │
│   Auto-wraps return values: int→Integer, str→String, etc  │
└──────────────────────────────────────────────────────────┘

Source Files Overview

Lexer Deep Dive (src/lexer.py)

The lexer converts source text into a stream of Token objects with full Unicode support, configurable options, and an extensible hook system.

Token Object Fields

Every token carries rich metadata:

Lexer Configuration Options

String Types

Escape Sequences

Number Formats

TokenRegistry (Runtime-Extensible)

The TokenRegistry class enables dynamic extension of the tokenizer at runtime:

// Register a new keyword
registry.register_keyword("myword", MY_TOKEN)

// Register a new operator with precedence
registry.register_operator("==>", MY_OP, precedence: 5, assoc: "right")

// Add token transformer hooks
registry.add_transformer(fn(token) {
    // Transform tokens in-flight
    return token
})

// Soft keywords (context-sensitive)
// These are only treated as keywords in specific contexts:
// async, await, match, trait, macro

All 150+ Token Types (Complete with Symbols)

Parser Deep Dive (src/parser.py)

A Pratt parser (top-down operator precedence parsing) that converts the token stream into a typed AST.

Precedence Levels (11 levels)

All Prefix Parse Functions (25)

All Infix Parse Functions (14)

All Statement Parsers (20)

For-Loop Variants

// C-style for loop → ForStatement
for (let i = 0; i < 10; i = i + 1) { ... }

// Single-variable for-in → ForInStatement
for item in collection { ... }

// Dual-variable for-in (key, value) → ForInStatement
for key, value in object { ... }

// Dual-variable for-in (index, element) → ForInStatement
for i, elem in array { ... }

Parser Extension API

// Register custom prefix parse function
parser.register_prefix(MY_TOKEN, fn(parser) { ... })

// Register custom infix parse function
parser.register_infix(MY_TOKEN, fn(parser, left) { ... })

// Register custom statement parser
parser.register_statement(MY_TOKEN, fn(parser) { ... })

// Register error hook for custom error handling
parser.register_error_hook(fn(error_msg) { ... })

Error Recovery

The parser uses statement synchronization to recover from errors:

1. On parse error → record error message
2. Skip tokens until finding a synchronization point: let, fn, class, return, if, while, for, try, import, use, or }
3. Resume parsing from the synchronization point
4. Configurable: max_errors (default: 200), stop_on_first_error (default: false)

All 70+ AST Node Types (Complete with Fields)

Interpreter Deep Dive (src/interpreter.py)

An async tree-walking evaluator that directly traverses the AST and produces values.

Environment (Scope Chain)

┌─────────────────┐
│   Global Env    │  Built-ins: print, len, range, max, min, sum, abs, round, str, int, float
│   store: {...}  │  Modules: resolved imports
└────────┬────────┘
         │ outer
┌────────▼────────┐
│  Function Env   │  Parameters bound here
│  store: {...}   │  Local variables
└────────┬────────┘
         │ outer
┌────────▼────────┐
│   Block Env     │  Block-scoped variables
│  store: {...}   │
└─────────────────┘

• define(name, value) — always defines in the local scope
• set(name, value) — searches up the chain; defines locally if not found anywhere
• get(name) — searches up the chain; raises NameError if not found at any level

Boxed Value Types

The interpreter wraps Python values into boxed types for type safety:

Signal System

NyxClass and UserFunction

# NyxClass — class wrapper
class NyxClass:
    name: str                         # Class name
    methods: Dict[str, UserFunction]  # Method map

    def instantiate(interpreter, args):
        instance = {"__class__": self}  # Instance is a dict!
        if "init" in methods:
            methods["init"].call(interpreter, [instance] + args)
        return instance

# UserFunction — function wrapper
class UserFunction:
    parameters: List[Identifier]      # Parameter names
    body: BlockStatement              # Function body AST
    env: Environment                  # Closure environment

    def call(interpreter, args):
        local_env = Environment(outer=self.env)   # New scope
        for param, arg in zip(parameters, args):
            local_env.define(param.value, arg)     # Bind args
        try:
            interpreter.eval(body, local_env)
        except ReturnSignal as rs:
            return rs.value

Complete eval() Dispatch Table

All Operator Implementations

Truthiness Rules (_truthy())