Vyb Programming Language
Systems Programming

Vyb Programming Guide#

Where the docs live. This README is the project overview. The canonical, maintained reference for every language feature is the docs/refman/PROGRAMMERS_GUIDE.md — language tour, ownership & polymorphism, closure capture forms, async (Future<T> / await / async lambdas), the memory model, and a full standard-library tour, with a core-feature registry (§1.1) that maps each feature to its section and is updated when core features change. Exact per-symbol signatures live in the auto-generated pages under docs/refman/.

1. Introduction#

Welcome to the Vyb programming language version 0.7.7. This overview walks you through what Vyb is and the thinking behind it. Vyb is a systems language built on a simple conviction: you should not have to choose between safety and power. Strong type safety and explicit ownership give your code discipline and predictability, while low-level escape hatches keep raw, machine-near control within reach when you need it. Code runs as fast native executables or through a JIT, so performance stays predictable from first prototype to final program. The syntax is readable and name-first, the abstractions are zero-cost, and the language aims to stay out of your way as your ambitions grow. The rest of this guide shows how those ideas take shape through feature summaries and examples.

1.1 Purpose & Audience#

This guide is intended for systems programmers, language designers, and developers who want:

• A compact, expressive syntax for both low-level control and high-level abstractions.
• Scoped ownership types (my/our/their/mild) and reference counting for explicit, safe memory handling, with system-level C interoperability via the FFI.
• Zero-cost monomorphized generics and aspect/bind polymorphism — native compiled performance or JIT, emitting through LLVM's target set (x86-64/Linux is release-tested; NVPTX device code is validated with ptxas from sm_75 through sm_90 in CI, and sm_90a additionally emits and validates on a local toolchain).
• Closures with full capture semantics: by-value copies, my<T> moves, our<T> retention, write-through mutable capture, and a reference-counted environment that survives return.
• Threads, channels, and a cooperative executor, with a compile-time thread-boundary capability that decides which closures may be handed to another thread.
• A foundation for a self-hosted compiler and hybrid VM/JIT architecture for rapid iteration and performance tuning.

Vyb is a systems language with a template-driven, name-first surface: monomorphized generics, ownership-qualified types (my/our/their/mild), freedom blocks for raw control, and a single toolchain that JITs, compiles AOT and links native executables.

Here is how Vyb's language surface compares against several modern systems languages:

Note: Each language offers a different balance of safety, performance, and ergonomics. Vyb's strength lies in unifying monomorphized generics, ownership types with low-level freedom, and a single toolchain that JITs, compiles AOT, and links native executables — in a terse, self-hostable package.

1.2 What is Vyb?#

Vyb is a statically typed, compiled systems language targeting native code via LLVM. Its key differentiators:

• Name-First Syntax: name(params)<ReturnType> -> — no fn keyword noise; function names come first.
• Aspect/Bind Polymorphism: Aspects (aspect) + struct binding (bind Aspect -> Type) instead of classes — more composable, no inheritance pitfalls.
• Readable Ownership: my<T> (unique), our<T> (shared), their<T> (borrowed), mild<T> (weak) — ownership intent is explicit without cryptic lifetime annotations.
• Programmer FREEDOM: freedom { ... } blocks for low-level control; loc<T> raw pointers within them — no hidden tax on safe code.
• select Expressions: Pattern matching that yields a value with a pass keyword for multi-statement arms — uniquely Vyb, not found in other languages.
• fail/trap Error System: Typed error propagation with zero-cost success path; no try/catch/finally.
• defer Statement: LIFO scope-exit cleanup without RAII ceremony.
• Monomorphized Generics: Zero-cost generics with aspect bounds (<T<Display>>).
• Closures: Full capture support — value copies, my<T> moves, our<T> retention, write-through mutable capture — with a reference-counted environment that is released when the closure dies.
• Threads and Concurrency: pthread-backed thread_spawn/thread_join with Mutex, Cond, atomics, channels, task/async executors and agent mailboxes; a compile-time thread-boundary capability (handoff/viewable) decides which captured values may cross to another thread.
• async/await: Future<T> with a cooperative multi-threaded executor (asm-based fiber context switch).
• Native Compilation: Full JIT (LLVM ORC), AOT (object files), and executable generation pipeline.

Parameter passing is explicit. A plain x<T> parameter is a value copy — the callee works on its own copy and the caller's variable is untouched (a Vec or an owning struct is deep-copied; a String shares its buffer; an our<T> bumps its refcount). To read or mutate in place without copying, take a their<T> borrow, supplied as borrow(x) (mutable) or view(x) (read-only their<T const>). Ownership is separate from reference-passing: my<T> is unique ownership (a named my passed to a my parameter moves — use-after-move is rejected), and our<T> is shared, ref-counted ownership; neither is another spelling of ref. The full, tested rules are in the “Parameter passing” section of the Programmer’s Guide.

Quick Start#

# Option A: official binary SDK (Linux x86_64) — download the newest
# vyb-sdk-<version>-linux-x86_64.tar.gz from the release page, unpack it, and
# put its bin/ on your PATH:
#   https://github.com/rickenator/Vyb/releases   (all releases)
#   releases are cut from the version tags: https://github.com/rickenator/Vyb/releases/tag/v0.7.7
# There is no macOS SDK yet: the runtime's async/fibre layer is Linux-only
# (ucontext/pipe2), so the release workflow cannot build it. See docs/sdk/INSTALL.md.

# Option B: build from source (requires LLVM 18 + CMake)
git clone https://github.com/rickenator/Vyb.git
cd Vyb
mkdir -p build && cd build && LLVM_DIR=/usr/lib/llvm-18/cmake cmake .. && make -j$(nproc) && cd ..

# Run the full test suite (1314 .vyb tests) with the canonical Vyb runner
build/vyb test/run_tests.vyb --vyb build/vyb --test-dir test

# Run your first Vyb program
echo 'main()<Int> -> { return 42 }' > hello.vyb
build/vyb hello.vyb  # Prints 42 and exits 0

# Emit CUDA kernels: pure NVPTX device code, validated by ptxas as it is emitted
build/vyb --kernel fixtures/kernel/axpy.vyb --ptx axpy.ptx

# Try select expressions with pattern matching
cat > example.vyb << 'EOF'
main()<Int> -> {
    numbers<Vec<Int>> = Vec()
    numbers.push(10)
    numbers.push(20)

    result<Int> = select(numbers.len()) -> {
        0 -> 0,
        2 -> {
            sum<Int> = numbers.get(0) + numbers.get(1)
            pass sum
        },
        ? -> -1
    }
    return result
}
EOF
build/vyb example.vyb  # Prints 30 and exits 0

# Complex return types with auto-serialization
echo 'main()<Int,String> -> { return 42, "Hello!" }' > tuple.vyb
build/vyb tuple.vyb  # Outputs: [42, "Hello!"]

Pointing a project at this checkout#

Vyb owns the toolchain paths, so a project that builds against it does not need to hardcode the checkout. The toplevel SOURCEME_VYB resolves this checkout and exports the two values every consumer needs (VYBHOME plus the derived VYB and VYB_STDLIB):

. "$HOME/Projects/Vyb/SOURCEME_VYB"   # one line, e.g. in your shell profile
# VYBHOME=/home/…/Vyb   VYB=$VYBHOME/build/vyb   VYB_STDLIB=$VYBHOME/stdlib

An explicit VYBHOME wins. Otherwise the home is derived from an existing VYB/VYB_BIN (a compiler binary, its build/ directory, or the checkout root), and otherwise from SOURCEME_VYB's own location — so the checkout can live anywhere. Sourcing is idempotent and touches only those three variables (PATH is left alone; the packaged SDK's sdk/env.sh is the one that prepends bin/). A strictly POSIX shell cannot report a sourced file's path, so set the home first: VYBHOME=/path/to/Vyb . /path/to/Vyb/SOURCEME_VYB. Covered by test/vybenv_smoke.sh in CI.

Compilation to Native Code#

Vyb provides a complete compilation pipeline from source to standalone executables:

Building Standalone Executables#

# Build executable (simplest form)
build/vyb hello.vyb --build hello
./hello  # Run directly!

# Build with custom name
build/vyb program.vyb --build myapp
./myapp

# Build with optimization
build/vyb program.vyb -b myapp -O3  # Maximum optimization

# Static linking (fully standalone, no runtime dependencies)
build/vyb program.vyb -b myapp --static

# What happens:
# 1. Compiles hello.vyb → hello.o (LLVM object file)
# 2. Compiles runtime/vyb_runtime.c → vyb_runtime.o (C runtime)
# 3. Links with system linker (lld/ld) + CRT files + libc/libm
# 4. Creates executable: hello

# Verify the executable
file myapp
# Output: myapp: ELF 64-bit LSB executable, x86-64, dynamically linked, with debug_info

ldd myapp
# Output:
#   linux-vdso.so.1 (0x00007fff...)
#   libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6 (0x00007f...)
#   libm.so.6 => /lib/x86_64-linux-gnu/libm.so.6 (0x00007f...)

Projects (vyb.toml)#

For multi-file projects, vyb.toml describes the package and every [[bin]], and vyb build compiles and links the whole project in one step:

[package]
name = "myapp"
version = "0.1.0"

[[bin]]
name = "myapp"
path = "src/main.vyb"

[dependencies]
mylib = { path = "../mylib" }

# Scaffold a new project
vyb new myapp          # creates myapp/vyb.toml + myapp/src/main.vyb

# Build every [[bin]] from the manifest (src/ and local path deps are added to
# the module search paths automatically; resolved deps are pinned in vyb.lock)
cd myapp && vyb build
./target/myapp

Compiling to Object Files#

# Compile to object file (default -O2 optimization)
build/vyb hello.vyb --compile hello.o

# Specify optimization level
build/vyb program.vyb -c program.o -O0  # No optimization (fast compile)
build/vyb program.vyb -c program.o -O1  # Basic optimization
build/vyb program.vyb -c program.o -O2  # Moderate optimization (default)
build/vyb program.vyb -c program.o -O3  # Aggressive optimization

# Verify object file was created
file hello.o
# Output: hello.o: ELF 64-bit LSB relocatable, x86-64, version 1 (SYSV), with debug_info, not stripped

# Inspect symbols in object file
objdump -t hello.o | grep main
# Output: 0000000000000000 g     F .text  000000000000005c main

Cross-Compilation Support#

Supports LLVM's target set. What is actually exercised today (the rest is backend-available but not covered by any gate):

Complete Compilation Features:

• ✅ Executable Generation: Full build pipeline with --build flag
• ✅ Runtime Library: Automatic compilation and linking of Vyb runtime
• ✅ System Linker Integration: Platform-aware linker selection (lld, ld, ld64)
• ✅ Dynamic Linking: Links against system libc and libm
• ✅ Static Linking: Optional --static flag for standalone binaries
• ✅ Object File Emission: AOT compilation to .o files
• ✅ Optimization Levels: -O0 through -O3 with LLVM optimizations
• ✅ Cross-Compilation: emits through LLVM's target set — x86-64/Linux is release-tested, NVPTX is validated sm_75 → sm_90 in CI (sm_90a locally); other targets are backend-available but not CI-covered
• ✅ Debug Information: Full DWARF debug metadata
• 🚧 NVPTX Kernel Mode (#198): --kernel lowers a main-less, host-runtime-free Vyb module to PTX through the in-process NVPTX backend (nvptx64-nvidia-cuda, default sm_86; override with VYB_KERNEL_GPU, or choose the artifact path with --ptx <path>).
• Host launch landed with #199 (launch-arg packing through the CUDA driver API, fixtures/cuda/launch_fill.vyb); cuBLAS/cuFFT/cuDNN bindings are verified on an RTX 3090 (sm_86); BLAS-composable tensors are the follow-on milestone.
• Gates: the module must be host-runtime-free (no __vyb_* references), PTX symbol presence is checked, and the emitted PTX is validated in-process with ptxas when present (hard-fail on reject, graceful skip when absent).
• Scope: a P0 feasibility probe — only sm_86 has real silicon behind it, and the verified workload is the shared-memory tiled matmul (all 256 elements of C = A×B checked against a host reference) plus the cuBLAS/cuFFT/cuDNN cross-validations. See test/kernel/, fixtures/kernel/axpy.vyb, and TODO.md §GPU for the full list.

See: doc/MODULE_FFI_BINARY_ROADMAP.md for the compilation pipeline

1.3 Key Concepts & Terminology#

• Template: A generic type/function parameterized by types or constants, instantiated at compile time.
• Binding Mutability: Variables are declared with unified syntax (mutable by default) or const (immutable binding, cannot be reassigned).
• Ownership Types:
  • my<T>: Unique ownership of data T.
  • our<T>: Shared (reference-counted) ownership of data T.
  • their<T>: Non-owning borrow/reference to data T.
  • mild<T>: Mild reference that can detect when target is destroyed.
• Data Mutability: Indicated by const on the type itself (e.g., my<T const> for unique ownership of immutable data).
• Borrowing:
  • view(expr): Creates an immutable borrow their<T const>.
  • borrow(expr): Creates a mutable borrow their<T>.
  • soft(expr): Creates a mild reference mild<T> from our<T>.
• freedom Blocks: Sections of code marked freedom { ... } where raw pointers (loc<T>) can be used and some compiler guarantees are relaxed. Within these blocks, operations like at(ptr) for dereferencing and from<loc<T>>() for pointer conversion are available.

1.4 Import vs Smuggle - Vyb's Unique Module System#

Vyb introduces a distinctive approach to module imports with two keywords that serve different security and trust models:

import - Trusted, Verified Modules:

• Used for modules from signed repositories or project-local sources verified in vyb.toml
• Enforces security checks and version verification
• Ideal for production dependencies and standard library modules
• Optional from "<locator>" specifies the source URL or local path
• Example: import std::collections::Vec
• Example: import utils::math::calculate from "./utils"

smuggle - Flexible, External Sources:

• Allows including symbols from external sources (e.g., GitHub repositories) or unsigned modules
• Bypasses some security checks for rapid prototyping and third-party integration
• Perfect for experimental dependencies, development tools, or one-off utilities
• from "<locator>" specifies the source (local path, GitHub shorthand, or full URL)
• Example: smuggle debug::Logger from "github.com/user/debug-tools"

Syntax:

import <module::path> [as <alias>] [from "<locator>"] [;]
smuggle <module::path> [from "<locator>"] [as <alias>] [;]

Locator formats for from:

• Local path: "./local/experiments"
• GitHub shorthand: "github.com/dev/tools"
• Full URL: "https://github.com/dev/tools"

This dual system provides both safety for production code and flexibility for development:

# Production imports - verified and trusted
import std::io::println
import utils::math::calculate from "./utils"

# Development/experimental - flexible but marked as such
smuggle debug::trace from "github.com/dev/tools"
smuggle experimental::feature from "./local/experiments"

main()<Int> -> {
    println("Production ready!")
    trace("Debug info from smuggled module")
    return calculate(42)
}

Declare dependencies in vyb.toml:

[dependencies]
std = "^1.0.0"  # Signed, from Vyb registry
utils = { git = "https://github.com/user/utils" }  # External, smuggled

This unique import/smuggle distinction makes Vyb's module system both secure and flexible, clearly marking the trust level of your dependencies. See doc/FEATURE_STATUS.md for implementation status.

In This Release#

Vyb v0.7.7 (freedom-1.0 series). Highlights of this cycle:

• Thread-boundary capability as a structural property — a closure handed to thread_spawn / task_spawn / async_spawn / agent_start must be able to cross an OS thread boundary, and the compiler proves it from the type graph instead of testing the captured variable's type string. See Threads and concurrency.
• Full closure support — capture by value, my<T> move, our<T> retention, write-through mutable capture, and a reference-counted environment that survives return. See Closures and lambdas.
• Refactoring the compiler sources — the analyzer and the expression emitter are split along cohesive seams; no behaviour change.
• Fixed — borrow(x) / view(x) addressed the operand's slot instead of the object for pointer-backed owners (my<T>, their<T>, ptr<T>, our<T>/mild<T> control blocks).

Feature highlights#

These features are complete and fully tested:

• defer statement — defer cleanup() executes at scope exit in LIFO order; ideal for resource cleanup

vyb main()<Int> -> { defer println("cleanup done") println("before return") return 0 } // Output: before return \n cleanup done - Math library — abs, min, max, sqrt, sin, cos, tan, exp, log, log2, log10, pow, floor, ceil, round

vyb main()<Int> -> { x<Float> = sqrt(2.0) y<Int> = abs(-5) println_int(y) // 5 return 0 } - String methods — .len(), .contains(), .starts_with(), .ends_with(), .to_upper(), .to_lower(), .substring(), .char_at(), .split(), .format(), String::from_bytes()

vyb main()<Int> -> { s<String> = "Hello, world!" if (s.contains("world")) { println(s.to_upper()) // HELLO, WORLD! } return 0 } - Type inference from initializer — Variables without annotation infer type from RHS

vyb x = 42 // inferred as Int msg = "hello" // inferred as String ok = true // inferred as Bool - Vec for loop type inference — Compiler-generated loop variables require no explicit types

vyb nums<Vec<Int>> = Vec() nums.push(10) for (n in nums) { println(n) // n is automatically Int } - select expressions — Pattern matching that yields a value; Vyb-original concept

vyb grade<String> = select(score) -> { >= 90 -> "A", >= 80 -> "B", >= 70 -> "C", ? -> "F" } - Set patterns in select arms ({ … }) — group several discrete values into one arm so you don't repeat a result per value; the arm matches when the target equals any element. Sets hold literals and bare enum-variant names only; empty {} and mixed types are rejected.

vyb parity(x<Int>)<String> -> { return select(x) -> { {1, 3, 5, 7, 9} -> "odd", {2, 4, 6, 8} -> "even", ? -> "out of bounds" } } - typeof / typename intrinsics — Runtime type introspection

vyb x<Int> = 42 same<Bool> = (typeof(x) == typeof(100)) // true name<String> = typename(x) // "Int" - Immutable bindings (const) — name<Type const> declares an immutable variable

vyb pi<Float const> = 3.14159

✅ Binary Executable Generation#

• Full Compilation Pipeline: Complete source → object → executable workflow
• Build Command: vyb program.vyb --build myapp creates standalone executables
• Runtime Library: Automatic compilation and linking of Vyb runtime (vyb_runtime.c)
• System Linker Integration: Platform-aware linker selection (lld, ld for Linux; ld64 for macOS)
• C Runtime Initialization: Automatic discovery and linking of CRT files (crt1.o, crti.o, crtn.o)
• Dynamic Linking: Links against system libc and libm by default
• Static Linking: Optional --static flag for fully standalone binaries
• Production Ready: Deploy native executables without any runtime dependencies
• Cross-Platform: Linux and macOS support with proper platform detection

✅ JSON Serialization & Deserialization#

• Runtime Type Metadata: Complete type registration system with field introspection
• Automatic Serialization: .to_string() method on structs generates JSON
• JSON Deserialization: T::from_string(json) creates instances from JSON strings
• Type Safety: Runtime validation of JSON structure against type definitions
• Supported Types: Int, Float, Bool, String primitives fully working
• Round-Trip Conversion: Full bidirectional struct ↔ JSON conversion
• Zero Boilerplate: No manual serialization code needed
• Test Suite: Comprehensive tests in test/json/ directory

✅ Native Code Compilation#

• Object File Emission: Compile to .o files with --compile/-c flag
• Optimization Levels: -O0 (none), -O1 (basic), -O2 (default), -O3 (aggressive)
• Cross-Compilation: emits through LLVM's target set (x86-64/Linux release-tested, NVPTX validated sm_75 → sm_90 in CI, sm_90a locally; other targets not CI-covered)
• Debug Information: Full DWARF metadata for debugging compiled code
• Standard Toolchain: Compatible with system linkers (ld, lld, gold)
• ELF Format: Standard relocatable object files for linking

✅ Core Language Features#

• Functions: name(params)<ReturnType> -> body with full LLVM compilation
• Standard parameters: param<Type> or param<Type const>
• Immutable parameters: param<Type const> for read-only arguments
• Variables: name<Type> = value with type inference and explicit typing
• Immutable bindings: name<Type const> = value — cannot be reassigned
• Resizable Arrays: Vec<T> with a vybish constructor (Vec(), Vec(n)) and push(), pop(), len(), get() methods
• Vec Iteration: for (item in vec) loops with inferred element type and break/continue
• Fixed Arrays: [T; N] with indexing
• Structs: struct Point { x<Int>, y<Int> } with field access (p.x, p.y)
• Control Flow: if/else, while/for loops, match statements, break/continue (including labeled: outer: for ... break outer)
• defer statement: defer expr — LIFO scope-exit execution for cleanup
• Select Expressions: select(expr) -> { pattern -> result } — pattern matching that returns a value; pass keyword for multi-statement arms; brace-delimited set arms ({1, 3, 5} -> "odd") match any element
• Arithmetic: Full binary operators (+, -, *, /, ==, !=, <, >, etc.)
• Bitwise Operators: |, &, ^, ~, <<, >> on Int with &=, |=, ^=, <<=, >>= compound-assigns
• Pattern Matching: match (expr) { pattern -> result } with comparison patterns (>= 90, < 0) and wildcard ?
• Error Handling: fail/trap system with zero-cost success path and type-safe error propagation
• I/O: println() for all types (auto-stringifies primitives); print() without newline
• Math: sqrt, abs, min, max, sin, cos, tan, pow, log, floor, ceil, round

✅ Advanced Type System#

• Multi-value returns: main()<Int,String> -> return 42, "hello" — auto-serialized as JSON
• Variadic Tuples: Tuple<T,U,V,...> with inline (T,U,V) syntax
• Auto-serialization: Complex return types automatically output as JSON
• Type inference: Full type checking and inference — x = 42 infers Int
• Generic collections: Vec<Int>, Vec<String> with full method support
• Member access: Struct field access (obj.field) and array indexing (arr[index])
• Ownership types (syntax fully parsed): my<T>, our<T>, their<T>, mild<T>
• freedom blocks: freedom { ... } for programmer-controlled sections with raw loc<T> pointers

✅ String Methods#

Comprehensive string manipulation built into the String type:

String concatenation with + auto-converts non-String operands:

id<Int> = 42
msg<String> = "User ID: " + id    // "User ID: 42"

Splitting returns a fresh Vec<String> of the parts between each occurrence of the separator. An empty separator yields a single-element Vec holding the whole string; leading, trailing, and consecutive separators produce empty parts.

csv<String> = "alpha,beta,gamma"
parts<Vec<String>> = csv.split(",")   // parts.len() == 3; parts.get(1) == "beta"

Formatting substitutes each {} placeholder with the string form of the corresponding argument in order. Arguments of any serializable type (String, Int, Float, Bool, ...) are converted automatically; placeholders beyond the supplied arguments are emitted verbatim.

tmpl<String> = "User {} has {} badge(s)."
msg<String> = tmpl.format("Vyb", 3)   // "User Vyb has 3 badge(s)."

Method calls on value receivers — every String method works not only on a named variable but on any String value: a literal, a function/expression result, or a struct/array field. Only the receiver itself still needs to be a String; no intermediate variable is required.

upper<String> = "hello".to_upper()                        // "HELLO"
head<String> = full_name().substring(0, 5)                // first 5 chars
count<Int> = get_csv().split(",").len()                   // number of fields

✅ Async Programming & Debugging#

Vyb parses and compiles async functions returning Future<T> and the await expression. An async fn(params...)<Future<T>> (T = Int, Float, Bool, String, or Void) starts a task on the stdlib's multi-threaded executor when called — its scalar arguments are snapshotted into a closing environment, and a String result travels back as a heap slot that await hands to the consumer as an owned transfer (a Float travels as its bit pattern and a Bool as 0/1 in the task's result slot). await parks the caller until the task completes (from main) or suspends the current fiber (so a worker can await a child task), including as a bare statement (await f) for Future<Void>. The future is returned by value as a real struct. Owned parameters are snapshotted into the task env: a String keeps its buffer with a retain (+1), an our<T> takes a shared-control-block retain (+1), and a Vec<T> is deep-copied so the env owns an independent copy; the env's per-layout dtor releases each one on cleanup (reclaiming Vec<String> element references too), so they safely outlive the caller's scope while the worker runs.

Async Function Syntax#

// Async function returning Future<Int>
async compute_value()<Future<Int>> -> {
    println("Computing...")
    return 42
}

// Async function that awaits another async function
async process_data()<Future<String>> -> {
    value<Int> = await compute_value()  // runs the pending task to completion
    println("Got value")
    return "processed"
}

Async Key Features#

• async keyword: Declares asynchronous functions that return Future
• await expressions: Resolve a Future's value where it is awaited
• Future types: Type-safe asynchronous return values
• Debug support: DWARF metadata for debugging async code paths

Usage Example#

main() -> {
    // Call async functions; each returns a Future<T>
    future1<Future<Int>> = compute_value()
    future2<Future<String>> = process_data()
    println("Tasks initiated")
    return
}

See: test/async/async_simple.vyb for a working example.

See also:

• test/async/async_event_loop.vyb — two concurrent sleeps finish in ~20ms
• test/async/async_params.vyb — parameterized concurrency
• test/async/async_nested_await.vyb — a task that awaits a child
• test/async/async_string.vyb, test/async/async_void.vyb — non-Int futures
• test/async/async_multicore.vyb — four CPU-bound tasks finish in parallel
• test/async/async_float_bool.vyb — Float/Bool futures, also awaited from inside a task
• test/async/async_string_param.vyb — String params retained in the env
• test/async/async_vec_param.vyb — Vec<T> params deep-copied (nested await + mixed envs)
• test/async/async_our_param.vyb — our<T> params retained across tasks
• test/async/async_struct_param.vyb — struct params deep-copied with owned fields
• test/async/async_await_chains.vyb — await results composed in expressions
• the asyncs stdlib module section

✅ Concurrency Modules (stdlib)#

The standard library ships threads (pthread-backed spawn/join/detach, Mutex, Cond, lock-free atomics), channels (thread-safe message passing, chan_select, string channels), tasks (fire-and-forget workers), asyncs (a multi-threaded fiber executor) and agents (mailbox workers). The API and the semantics of each — including what may be captured across a thread boundary — are in Threads and concurrency.

✅ Introspection System#

Vyb features runtime type introspection for self-aware programs:

Type Reflection Operators#

// Get runtime type hash — use for equality comparison
x<Int> = 42
same<Bool> = (typeof(x) == typeof(100))   // true — both Int

// Get type name as String
name<String> = typename(x)                // "Int"

// Works on any expression
same_expr<Bool> = (typeof(x + 5) == typeof(x * 2))   // true

Introspection Key Features#

• typeof(expr): Returns a type discriminant for runtime type comparison; same types always compare equal
• typename(expr): Returns String with the human-readable type name (e.g., "Int", "Float", "Bool")
• Expression-based: Works on variables, literals, arithmetic expressions
• Zero-cost: Type information extracted at compile-time, evaluated at runtime via std::hash
• Note: typeof result is an opaque Type value; use only for ==/!= comparisons

Usage Examples#

// Type comparison
x<Int> = 42
y<Float> = 3.14
if (typeof(x) != typeof(y)) {
    println("different types")
}

See: test/introspection/ for working examples and doc/INTROSPECTION_DESIGN.md for design philosophy

✅ Aspect System#

Philosophy: Vyb uses aspects + structs instead of classes and inheritance. This provides polymorphism, code reuse, and composition without the complexity and pitfalls of OOP class hierarchies. See doc/TRAIT_SYSTEM_DESIGN.md for detailed design and rationale.

Simple aspect receivers use self; the compiler treats it as the bound Self type. Use explicit receiver types like self<their<Self>> only when ownership mode matters.

Complete Aspect Example#

# Define an aspect (interface): method signatures only, no state
aspect Display {
    show(self)<String> ->
    format(self, prefix<String>)<String> ->
}

# A concrete struct - just data
struct Point {
    x<Int>,
    y<Int>
}

# Bind the aspect to the type, implementing the methods against the data
bind Display -> Point {
    show(self)<String> -> {
        return "Point at (" + self.x + ", " + self.y + ")"
    }

    format(self, prefix<String>)<String> -> {
        return prefix + ": (" + self.x + "," + self.y + ")"
    }
}

# Another type can bind the same aspect
struct Rectangle {
    width<Int>,
    height<Int>
}

bind Display -> Rectangle {
    show(self)<String> -> {
        return "Rectangle " + self.width + "x" + self.height
    }

    format(self, prefix<String>)<String> -> {
        return prefix + ": " + self.width + "x" + self.height
    }
}

main()<Int> -> {
    point<Point> = Point { x = 10, y = 20 }
    rect<Rectangle> = Rectangle { width = 5, height = 7 }

    # Dot-call the bound aspect methods - they read the struct's own fields
    println(point.show())         # "Point at (10, 20)"
    println(point.format("Item")) # "Item: (10,20)"
    println(rect.show())          # "Rectangle 5x7"
    println(rect.format("Item"))  # "Item: 5x7"

    return 0
}

Why Aspects > Classes:

• Multiple aspect implementations (no diamond problem)
• Composition over inheritance (more flexible)
• Extension without modification (bind aspects to any type)
• Static dispatch (zero-cost abstractions)
• No fragile base class problem
• Explicit binding makes relationships clear

See: doc/ASPECT_SYSTEM_DESIGN.md for complete specification and test/aspect/ for working examples

Core Contracts (core::aspects)#

The standard library ships six canonical contract aspects — Display, Debug, Clone, Equatable, Hashable, and Comparable (with Comparable : Equatable) — bound to the primitive scalar types (Int/Float/Bool/Char/String). core::aspects is auto-imported into non-stdlib modules (opt out with no_core()), so contract methods are available on built-in scalars with no import. They bind to user structs the same way, and drive the generic call sites for the stdlib collections and Iterator protocol:

// Hash/comparison-backed collections (import collections) resolve the
// Hashable/Comparable bounds on generic keys automatically.
nums<BTreeMap<Int, String>> = BTreeMap<Int, String>()

// Unqualified bounded-type-parameter dispatch resolves through the bound.
show_all<T<Display>>(item<T>) -> {
    println(item.display())   // resolves via the bound Display aspect
}

Primitive Types#

Signed Integers:

Unsigned Integers:

Floating Point:

Character Types:

Other Types:

Collection Types#

Ownership Types#

✅ Canonical Ownership Syntax#

Vyb features unified canonical syntax for ownership and borrowing operations:

Type Annotations#

# In variable declarations and function signatures
data<my<String>>     # Unique ownership type
shared<our<Config>>  # Shared ownership type
view<their<Data>>    # Borrowed reference type

Value Construction#

# Create owned values with my() and our() constructors
unique<my<String>>   = my("owned string")
shared<our<Config>>  = our(Config::new())
result<my<Data>>     = my(compute_data())

Borrowing Operations#

# Create temporary references with view/borrow/soft functions
readonly<their<String const>> = view(data)     # Immutable borrow
writable<their<String>>       = borrow(data)   # Mutable borrow
weak<mild<Node>>              = soft(shared)   # Weak reference
length<Int>                   = view(data).len()
borrow(data).clear()

Legacy Syntax Migration#

All legacy make_my(), make_our(), and prefix view expr / borrow expr syntax can be migrated to canonical syntax using the migration tool:

# Scan for legacy syntax
build/vyb migrate_syntax.vyb --scan --directory .

# Apply migrations with backup
build/vyb migrate_syntax.vyb --migrate --directory . --backup --report

Migration Results: ✅ 346 syntax updates applied across 22 files, ensuring consistent canonical syntax throughout the entire codebase.

✅ Memory Management#

• Ownership types: my<T>, our<T>, their<T>, mild<T> for safe memory handling
• Mild references: mild<T> created with soft() for breaking circular references with grab() and released() methods
• Borrowing: view(expr) and borrow(expr) for references
• Freedom operations: loc<T> pointers in freedom {} blocks
• Raw Memory Operations: Complete freedom block system with loc<T> pointers
• Memory Safety: Borrow checking and lifetime analysis prevent dangling pointers
• Temporary reclaim: a value built inline and never bound to a name is released at the site that builds it — a Vec consumed inside one expression (payload.split("\n").len()), a fresh row pushed or set into a Vec<Vec<T>> (rows.push(build_row(a, b))), a by-value Vec argument, and a Vec-returning call used as a statement (mk("a", "b") on its own line). Scope-exit teardown and the call-site reclaim share the same nested unwind — element String references, owned struct-element fields, every nested Vec level, then the buffer

Reclaiming Temporaries#

A temporary is unwound exactly like a named binding of the same type, so what is not reclaimed is a temporary whose own result aliases its storage: an element accessor such as payload.split("\n").get(0) returns a value that may point into the temporary's element buffer, so that buffer is left alone (one buffer per evaluation leaks). Bind the Vec to a name first — parts<Vec<String>> = payload.split("\n"), then parts.get(0) — and the binding's own scope-exit cleanup releases it.

main()<Int> -> {
    payload<String> = "a|b|c\nx|y|z\n"
    total<Int> = 0

    # The temporary Vec from split() is released as len() returns
    total = total + payload.split("\n").len()

    # A named binding owns its buffer, so a borrow out of it is safe
    parts<Vec<String>> = payload.split("\n")
    println(total.to_string() + " " + parts.get(0))
    return 0
}

test/ownership/vec_temp_receiver_reclaimed.vyb and test/ownership/vec_temp_{push_arg,set_arg,discarded_call}_reclaimed.vyb lock the reclaimed shapes in (the push/set fixtures read their rows back, so a slot that aliased freed storage would show as garbage).

Weak References with mild#

Vyb introduces mild<T> - weak references that solve circular reference problems without preventing cleanup:

Why mild?

• Break Cycles: Tree nodes with parent pointers, doubly-linked lists
• Observer Pattern: Subjects don't keep observers alive
• Caches: Entries that can be collected when memory is needed
• Safe Access: Can detect when target object has been destroyed

Key Methods:

# grab() -> our<T>?
# Attempts to upgrade mild reference to strong reference
# Returns nil if target has been destroyed
parent_strong<our<TreeNode>> = node.parent.grab()

# released() -> Bool
# Check if target object has been freed
# Returns true if destroyed, false if still alive
is_alive<Bool> = !node.parent.released()

Creating Mild References:

# Use soft() to create mild<T> from our<T>
shared_data<our<Config>> = our(Config::new())
shadow<mild<Config>> = soft(shared_data)  # Create mild reference

Example: Tree with Parent Pointers

struct TreeNode {
    value<Int>,
    children<Vec<our<TreeNode>>>,  # Strong refs to children
    parent<mild<TreeNode>>          # Mild ref to parent (breaks cycle)
}

create_child(parent<our<TreeNode>>, value<Int>)<our<TreeNode>> -> {
    return our(TreeNode {
        value: value,
        children: Vec(),
        parent: soft(parent)  # Create weak reference with soft()
    })
}

access_parent(node<our<TreeNode>>)<Int> -> {
    # Safely access parent through weak reference
    if (parent<our<TreeNode>> = node.parent.grab()) {
        return parent.value  # Success - parent still alive
    } else {
        return -1  # Parent was destroyed
    }
}

See: doc/OWNERSHIP_MILD.md for complete documentation and test/ownership/mild_test.vyb for examples

✅ Developer Experience#

• LLVM backend: JIT execution, AOT object files, and standalone executable generation
• Comprehensive parser: Handles all documented syntax including generics, async, aspects
• Rich error messages: Clear compilation feedback with file, line, and column info
• Advanced Test Harness: Modern parallel test runner with HTML/JSON reporting and triage analysis
• Debug Information: Complete DWARF debug metadata for source-level debugging in gdb/lldb — validated end-to-end by test/debug_step.sh (breakpoint by Vyb source line, stepping, local read-back)
• Git integration: Regular commits track development progress
• Migration Tool: build/vyb migrate_syntax.vyb for automated syntax upgrades

✅ Native Bridge / FFI#

Vyb's native bridge to C libraries is shipped and production-usable:

With extern "C" and the typed C aliases, the POSIX API is reachable with a thin Vyb wrapper, enabling networking, file I/O, threading, and more without language-level changes. FFI callbacks arrive as bare loc<fn> function pointer parameters (see test/ffi/callback_fnptr.vyb), and variadic C functions work directly (printf("%s", s) accepts a Vyb String). See doc/FFI_DESIGN.md for the complete design.

Language Overview#

Vyb (freedom-1.0 series) is a mature, actively developed systems programming language with name-first syntax, a sized type system (Int8–Int64, UInt8–UInt64, Float32/Float64, Char, Rune, Bytes), compile-time monomorphized generics, aspect/bind polymorphism, pattern matching, Vec<T>, and comprehensive collection support. The core language is stable and well tested.

Closures and lambdas#

A lambda is a first-class value of type fn(...) -> R: it can be held in a variable, passed to a function, returned from one, and fed to combinators such as Vec::map / filter / fold. The body may be an expression or a block.

makeAdder(base<Int>)<fn(Int) -> Int> -> {
    return |x<Int>| -> x + base
}

main()<Int> -> {
    twice<Int> = 2
    f<fn(Int) -> Int> = |x<Int>| -> x * twice
    println(f(10).to_string())            // 20 — a copy of `twice`

    add5<fn(Int) -> Int> = makeAdder(5)
    println(add5(10).to_string())         // 15 — the environment outlives the frame
    return 0
}

Value shape. A lambda that captures nothing lowers to a bare function pointer (null environment), so it satisfies an fn parameter with no allocation. A capturing lambda is a {env, fn} pair whose environment is a reference-counted heap struct holding exactly the captured values; the callable is an ordinary function whose hidden first parameter is that environment, so both forms call through one shape.

Capture forms and what each means.

counter<Int> = 0
bump<fn(Int) -> Int> = |u<Int>| -> counter = counter + 1
bump(0)
bump(0)
println(counter.to_string())          // 2 — the outer variable sees both writes

shared<our<Int>> = our(7)
read<fn(Int) -> Int> = |u<Int>| -> shared + 3
println(read(0).to_string())          // 10 — the closure retains the shared value

Lifecycle. The environment is reference-counted: copying the closure retains it, exiting the scope or overwriting the variable releases it, and a closure returned from a function hands back an owned reference, so the environment survives the frame that built it.

Escaping mutable captures are boxed. A mutable capture stores the outer variable's address, which is only meaningful while that frame is alive. When the analyzer sees a closure value leave its frame — returned, stored into a struct field or a Vec element, or handed to thread_spawn/task_spawn — each mutable capture is instead boxed: codegen allocates a heap cell, initialises it with the binding's current value (deep-copying storage the cell will own), and stores the cell pointer in the environment. The environment owns the cell — its generated destructor reclaims the cell's payload, if any, then frees the block when the last closure reference drops — so the closure works after its defining frame has exited:

makeCounter()<fn() -> Int> -> {
    n<Int> = 5
    return || -> {
        n = n + 1
        return n
    }
}

main()<Int> -> {
    f<fn() -> Int> = makeCounter()
    println(f().to_string())              // 6 — read from the cell, not from the dead frame
    println(f().to_string())              // 7 — the next call starts from the cell's value
    return 0
}

A closure that does not escape keeps the stack path, so the write-back contract in the table above is unchanged: two closures over one binding still do not share mutations through a read, and the enclosing frame still observes them.

A closure that does escape promotes its captured binding to one refcounted cell shared with the defining frame (checkpoint (c)), so the frame and every other closure over that binding observe the mutation — a spawner sees the write its spawned thread made through the closure, and two escaping closures over one binding see each other's (test/lambda/test_closure_mutable_frame_observes.vyb, test_closure_mutable_shared_binding.vyb). The frame holds one reference on the cell and each capturing environment another; the last owner runs the cell's destructor, which reclaims the payload and frees the block.

An in-place mutation through a mutable capture is a write like any other — v.push(x), v.set(i, x), v[i] = x, v.clear() on a captured binding are recorded as writes to it, and each exit from the closure body flushes the captured value back, so the enclosing scope and later invocations observe the mutation (test/lambda/test_closure_mutable_capture_inplace_mutation.vyb).

Where it stops. A mutable capture whose declared type has no sound heap-cell representation is still refused when the closure is returned — a borrow (their<T>/loc<T>), an FFI handle, an optional, an array, or a name the analysis cannot resolve (a type parameter):

Semantic Errors:
  Cannot return a closure with mutable captures: capture 'ro' holds state that would alias the enclosing stack frame after this function returns, and a mutable capture of that type cannot be boxed safely. Capture it by value, share it as our(ro), or keep the closure inside the frame.

Moving a my<T> into a closure is destructive in the same way, and reading the variable afterwards is an error:

Semantic Errors:
  Use after move: 'x' has been moved and is no longer valid.

Generic lambdas are still an open item (TODO.md §3), and the per-binding shared cell — which would let the defining frame observe a mutation made through an escaping closure — is not implemented; an escaping closure's writes land in its own cell.

Threads and concurrency#

Vyb's concurrency is a small set of stdlib modules over POSIX threads, plus one compile-time rule about closures: a closure handed to another thread must be able to cross an OS thread boundary.

The modules.

• threads — thread_spawn(work<fn() -> Int>) starts a pthread and returns an Int? handle (absent if the spawn failed); thread_join blocks until it finishes and yields the closure's result; thread_detach releases the handle without waiting. Mutex (mutex_new/lock/unlock), condition variables (cond_new/cond_wait/cond_signal) and lock-free atomic_* give mutual exclusion and shared counters. Everything maps 1:1 onto POSIX threads, keeping the pthread ABI out of Vyb code.
• channels — thread-safe message passing. chan_new()/chan_bounded(n) create Int channels; chan_send returns Bool, chan_recv blocks, chan_try returns Int? (no -1 sentinel), chan_len reports buffered depth, and chan_select(handles) waits on several at once and returns the index of the first ready one. strchan_* channels retain the string on send and transfer the reference on receive.
• tasks — fire-and-forget workers on a detached pthread: task_spawn returns an Int? handle, task_await blocks on its result, task_poll returns Int? (absent while it is still running), task_free reclaims it.
• asyncs — a multi-threaded executor: one scheduler per CPU core, stackful fibers pinned to their worker and load-balanced by round-robin spawn. A task suspends mid-body with async_sleep_ms (a timer, not a thread sleep), async_yield, or async_await (wait on another task), so concurrent timers finish in ~max rather than ~sum wall time and CPU-bound tasks spread across cores, with no state-machine transform. async_detach reclaims a finished task early so long-lived programs recycle fibers; async_run_all() flushes the executor.
• agents — mailbox workers. agent_start(behavior) runs behavior(message) on a worker thread for each message, then once more with an absent optional after agent_close has drained the mailbox; agent_send posts a message (a full bounded mailbox returns false), agent_len reports buffered-but-unhandled messages, agent_alive reports whether the worker still runs, and agent_free waits then reclaims it.

What a closure may capture across a thread boundary. thread_spawn, task_spawn, async_spawn and agent_start hand a closure's environment to another OS thread, so every captured value must remain valid there. The compiler proves this structurally from the type graph; the capability is called handoff:

• a plain value copy is handoff-capable — the environment carries its own copy;
• our<T> / mild<T> is handoff-capable iff its payload is: the environment takes a strong reference, so the target survives on the other thread;
• a named struct or enum is handoff-capable iff every field / variant payload is; Vec<T>, arrays, T? and tuples derive structurally;
• my<T> (a unique owner), their<T>/loc<T> (borrows and raw pointers) are never handoff-capable: moving an owner off its thread, or passing a borrow of the spawner's frame, would leave the spawner with an invalid owner or a dangling alias;
• a mutable capture is refused only when its declared type cannot be boxed soundly; when it can, the compiler promotes the captured binding to one refcounted heap cell shared by the spawner's frame and every environment that captures it (checkpoint (c)); the frame keeps one reference and each environment another, and the last owner runs the cell's destructor, so the spawner does observe the spawned closure's writes once it joins, and two escaping closures over one binding observe each other's (test/threads/test_thread_boundary_mutable_capture_boxed_accepted.vyb, test/lambda/test_closure_mutable_shared_binding.vyb);
• the one borrowing form that is accepted is a read-only view(x) — viewable — when the closure also captures the owner through strong ownership (our<X> / my<X>), since then the owner outlives the thread.

import threads::{thread_spawn, thread_join}

struct Pair { a: Int, b: Int }

main()<Int> -> {
    local<Int> = 3
    shared<our<Int>> = our(4)
    p<Pair> = Pair { a = 1, b = 2 }

    h<Int> = thread_spawn(|| -> local + shared + p.a + p.b) else -1
    if (h < 0) { return 1 }
    println("joined = " + thread_join(h).to_string())   // 10
    return 0
}

A capture whose declared type still names a type parameter is recorded by the semantic pass and judged by codegen at the instantiated type, so the same generic function can be accepted at one instantiation and refused at another. The check runs before code is generated, so a refusal is a compile error, not a runtime surprise:

Semantic Errors:
  thread_spawn: 'h' is Holder -- it cannot cross a thread boundary (not handoff-capable). Hand it off as shared ownership (our(h)) or pass a copy.

When the derivation is not enough: the reviewed claim (Handoff / Viewable). Ordinary types need nothing from you — their capability is derived from the type graph as described above. For the shapes the derivation cannot see through, core::aspects declares two marker aspects (re-exported by core::prelude), and a bind states the claim:

aspect Handoff  { handoff(self)<Bool>  -> { return true } }
aspect Viewable { viewable(self)<Bool> -> { return true } }

A marker aspect has no contract to satisfy; bind Handoff -> T is simply the claim "a value of T may cross a thread boundary", reviewed by whoever wrote the bind. This is a general escape hatch, not an FFI-only feature. Reach for it whenever the structural verdict is blind to your invariants or simply wrong for your design:

• an FFI struct holding a ptr<T> / loc<T>, or an opaque C handle — the motivating case;
• a hand-managed arena or pool whose lifetime you enforce yourself;
• a unique owner you are deliberately moving into the worker rather than sharing;
• a wrapper whose payload really does travel with the closure environment.

Here is a non-FFI claim — a struct holding a unique owner, which the structural derivation refuses on its own, handed to a worker that takes the owner with it:

import core::aspects
import threads::{thread_spawn, thread_join}

struct Token { n: my<Int> }

bind Handoff -> Token {
    handoff(self<Token>)<Bool> -> { return true }   // the claim; reviewed, not proven
}

main()<Int> -> {
    t<Token> = Token { n = my(7) }
    h<Int> = thread_spawn(|| -> {
        seen<Token> = t          // the unique owner moves into the closure environment
        return 0
    }) else -1
    if (h < 0) { return 1 }
    r<Int> = thread_join(h) else -2
    println("joined = " + r.to_string())                 // joined = 0
    return 0
}

And the FFI-shaped claim — a handle carrying raw memory, which the closure reads on the other thread (freedom is where raw addresses live):

import core::aspects
import threads::{thread_spawn, thread_join}

struct Handle { raw: loc<Int> }

bind Handoff -> Handle {
    handoff(self<Handle>)<Bool> -> { return true }
}

main()<Int> -> {
    x<Int> = 41
    h<Int> = -1
    freedom {
        p<loc<Int>> = loc(x)
        hd<Handle> = Handle { raw = p }
        h = thread_spawn(|| -> {
            seen<Handle> = hd
            return 0
        }) else -1
    }
    if (h < 0) { return 1 }
    r<Int> = thread_join(h) else -2
    println("joined = " + r.to_string() + " x = " + x.to_string())
    return 0                                             // joined = 0 x = 41
}

How the claim behaves:

• The capability check consults the curated bind first for the type it names, so the explicit claim wins over the computed verdict.
• When the claim contradicts the derived shape, registration reports a non-fatal warning — overriding is the point — and the payload carries your guarantee from then on. Verbatim from the first program above:

warning: curated thread-boundary bind: `bind Handoff -> Token` claims the type may cross a thread boundary, but its structural shape is not handoff-capable -- the explicit bind wins, so the program is accepted; the payload then carries the programmer's guarantee (doc/THREAD_BOUNDARY_SCOPE.md).

• The claim is asked at every level of the walk, not only for the type as written: bind Handoff -> Token also covers our<Token> (the idiomatic way to share it), Vec<Token>, Result<Token, E> and a struct field of type Token — and bind Viewable -> T travels the same way for the read-only relation. It is asked after the unique-owner and borrow refusals, so it rescues a composition without turning a my<T> / their<T> / loc<T> / ptr<T> that appears as the type itself into a handoff.
• Handoff implies Viewable: whatever may be handed to another thread may also be read there. bind Viewable -> T states only the weaker, read-only claim.
• Viewable is a relation, not a licence at a spawn site. A bind Viewable by itself does not admit a value capture at thread_spawn / task_spawn / async_spawn / agent_start; those sites require handoff capability. Read-only access crosses when the borrow rules above hold (view(x) plus a strongly captured owner), and the wording stays "accepted for handoff", never "guaranteed safe" — the claim is yours to keep. Claiming Viewable on a value that only ever gets read across threads is therefore a statement about the type, not a pass for handing it over:

import core::aspects
import threads::{thread_spawn, thread_join}

struct Window { raw: loc<Int> }

bind Viewable -> Window {                 // the weaker, read-only claim
    viewable(self<Window>)<Bool> -> { return true }
}

main()<Int> -> {
    x<Int> = 41
    freedom {
        p<loc<Int>> = loc(x)
        w<Window> = Window { raw = p }
        h<Int> = thread_spawn(|| -> {     // still refused: viewable is not a spawn licence
            seen<Window> = w
            return 0
        }) else -1
        if (h >= 0) { thread_join(h) }
    }
    return 0
}

warning: curated thread-boundary bind: `bind Viewable -> Window` claims the type may cross a thread boundary, but its structural shape is not viewable -- the explicit bind wins, so the program is accepted; the payload then carries the programmer's guarantee (doc/THREAD_BOUNDARY_SCOPE.md).

Semantic Errors:
  thread_spawn: 'w' is Window -- it cannot cross a thread boundary (not handoff-capable). Hand it off as shared ownership (our(w)) or pass a copy.

The claim travels with the type, so the same curated Token also crosses as a shared owner — the shape you reach for when several threads read it (runs; prints joined = 0):

import core::aspects
import threads::{thread_spawn, thread_join}

struct Token { n: my<Int> }

bind Handoff -> Token {
    handoff(self<Token>)<Bool> -> { return true }
}

main()<Int> -> {
    shared<our<Token>> = our(Token { n = my(7) })   // a shared owner of a curated type
    h<Int> = thread_spawn(|| -> {
        seen<our<Token>> = shared                   // `our<Token>` inherits the claim on `Token`
        return 0
    }) else -1
    if (h < 0) { return 1 }
    r<Int> = thread_join(h) else -2
    println("joined = " + r.to_string())            // joined = 0
    return 0
}

The full rule set and the measurements behind it are in doc/THREAD_BOUNDARY_SCOPE.md; the authoritative manual is docs/refman/PROGRAMMERS_GUIDE.md §5.

Channels are the usual way to get values out of a thread, while a closure's captures carry values in:

import threads::{thread_spawn, thread_join}
import channels::{chan_new, chan_send, chan_recv}

main()<Int> -> {
    ch<Int> = chan_new() else 0
    h<Int> = thread_spawn(|| -> {
        i<Int> = 0
        while (i < 3) {
            chan_send(ch, i * 10)
            i = i + 1
        }
        chan_send(ch, -1)
        return 0
    }) else -1
    if (h < 0) { return 1 }

    total<Int> = 0
    closer<Bool> = false
    while (!closer) {
        v<Int> = chan_recv(ch) else -1
        if (v < 0) { closer = true } else { total = total + v }
    }
    thread_join(h)
    println("total = " + total.to_string())   // 30
    return 0
}

The executor and mailbox forms:

import asyncs::{async_spawn, async_await, async_sleep_ms, async_run_all}
import tasks::{task_spawn, task_await, task_free}

a<Int> = async_spawn(|| -> { async_sleep_ms(20); return 10 }) else 0
b<Int> = async_spawn(|| -> { async_sleep_ms(20); return 32 }) else 0
println("async: " + async_await(a).to_string() + ", " + async_await(b).to_string())  // async: 10, 32

t<Int> = task_spawn(|| -> 40 + 2) else 0
println("task: " + task_await(t).to_string())   // task: 42
task_free(t)
async_run_all()

import agents

counter<Int> = agent_start(|message<Int?>| -> {
    match (message) {
        v -> { println("agent got " + v.to_string()) }
        ? -> { println("agent: mailbox closed") }
    }
}) else -1

agent_send(counter, 42)
agent_send(counter, 43)
agent_close(counter)
agent_free(counter)

Language Features Showcase#

// Complete language demonstration showing all major features

// Modern struct syntax with typed fields
struct Person {
    name<String>,
    age<Int>,
    scores<Vec<Int>>
}

// Define aspect for gradeable entities
aspect Gradeable {
    letter_grade(self)<String> -> { }
    is_passing(self)<Bool> -> { }
}

// Bind aspect to Person using match in the implementation
bind Gradeable -> Person {
    letter_grade(self)<String> -> {
        // Calculate average score
        total<Int> = 0
        i<Int> = 0
        while (i < self.scores.len()) {
            total = total + self.scores.get(i)
            i = i + 1
        }
        avg<Int> = total / self.scores.len()

        // Match statement with comparison patterns for grade ranges
        match (avg) {
            >= 90 -> return "A",
            >= 80 -> return "B",
            >= 70 -> return "C",
            >= 60 -> return "D",
            ? -> return "F"
        }
    }

    is_passing(self)<Bool> -> {
        grade<String> = self.letter_grade()
        match (grade) {
            "F" -> return false,
            ? -> return true
        }
    }
}

// select expression — Vyb-original: pattern matching that returns a value
get_grade_description(score<Int>)<String> -> {
    grade<String> = select(score) -> {
        >= 90 -> "Excellent",
        >= 80 -> "Good",
        >= 70 -> "Satisfactory",
        >= 60 -> "Passing",
        ? -> "Needs Improvement"
    }
    println(grade)
    return grade
}

// Generic function using aspect bounds
print_student_status<T<Gradeable>>(student<T>) -> {
    grade<String> = student.letter_grade()
    passing<Bool> = student.is_passing()
    println("Grade: " + grade)
    if (passing) {
        println("Status: PASSING")
    } else {
        println("Status: FAILING")
    }
}

// Resizable collections with full method support
create_person(name<String>, age<Int>)<Person> -> {
    person<Person> = Person {
        name = name,
        age = age,
        scores = Vec()
    }
    person.scores.push(85)
    person.scores.push(92)
    person.scores.push(78)
    return person
}

main()<Int> -> {
    student<Person> = create_person("Alice", 20)

    // Defer for guaranteed cleanup
    defer println("done")

    // Type introspection
    same<Bool> = (typeof(student.age) == typeof(42))

    // Call aspect method through generic function
    print_student_status(student)

    // Use select with comparison patterns
    description<String> = get_grade_description(85)

    return 0
}

Memory Safety & Freedom Operations#

Vyb's design philosophy: FREEDOM over restrictions. The language provides compiler-managed ownership by default, but empowers programmers with low-level control when needed:

// Ownership type syntax (runtime enforcement is in place for our/mild/their;
// full my<T> move tracking is still in progress)
restricted_memory_example()<Int> -> {
    owned<my<String>> = my("unique data")         // Unique ownership
    shared<our<String>> = our("shared data")      // Shared, ref-counted
    another_ref<our<String>> = shared             // Reference count +1
    view_ref<their<String const>> = view(shared)  // Immutable borrow
    return 42
}

// freedom block — low-level pointer access
freedom_memory_example()<Int> -> {
    x<Int> = 42
    freedom {
        p<loc<Int>> = loc(x)       // Get pointer to x
        println("in freedom block")
    }
    return x
}

FREEDOM Code Guidelines:

1. Minimize the scope of freedom blocks
2. Document all invariants and assumptions
3. Validate pointers before dereferencing
4. Encapsulate freedom operations behind restricted abstractions
5. Test freedom code extensively

Syntax and Literals#

Declaration bodies are braced (name(params)<ReturnType> -> { ... }) and the unified name<Type> form gives every declaration the same shape. Statements are newline-separated inside the braces.

Literal Forms#

// Integer literals
x<Int> = 42                       // 64-bit signed integer (default)
large<Int> = -9223372036854775808  // Full 64-bit range
red<Int> = 0xFF                   // Hexadecimal (base 16)
mask<Int> = 0b11001110            // Binary (base 2)
ud<UInt32> = 255u                 // Unsigned literal suffix
maxU<UInt64> = 18446744073709551615u  // Full UInt64 range (2^64 - 1)

// Sized integers use the same literal forms (0x80 means 128 as a byte).
b<UInt8> = 0x80

// Floating point literals
pi<Float> = 3.14159               // 64-bit IEEE 754 double precision
e<Float> = 2.71828

// Boolean literals
flag<Bool> = true
active<Bool> = false

// String literals
name<String> = "Alice"            // UTF-8 string
greeting<String> = "Hello\nVyb"  // Escape sequences supported
empty<String> = ""

// Array literals (fixed-size)
numbers<[Int; 5]> = [1, 2, 3, 4, 5]
floats<[Float; 3]> = [1.0, 2.5, -3.14]

// Dynamic arrays (Vec<T>)
items<Vec<Int>> = Vec()

// Immutable binding
PI<Float const> = 3.14159

Syntax Examples#

// Variable declarations with unified syntax
x<Int> = 42                  // Mutable variable
PI<Float const> = 3.14159    // Immutable constant (name<Type const>)

// Function declarations — name comes first
add(a<Int>, b<Int>)<Int> -> a + b

// Struct definitions with typed fields
struct Point {
    x<Float>,
    y<Float>
}

// Pattern matching with comparison operators and wildcard ?
process_value(val<Int>)<String> -> {
    match (val) {
        0 -> "zero",
        >= 1 -> "positive",
        ? -> "negative"
    }
}

// select — pattern matching that returns a value (Vyb-original)
classify(score<Int>)<String> -> {
    return select(score) -> {
        >= 90 -> "A",
        >= 80 -> "B",
        ? -> "C-or-below"
    }
}

// defer — LIFO scope-exit cleanup
open_and_process()<Int> -> {
    defer println("cleanup")
    println("working")
    return 0
}

Type System Features#

Current Primitive Types:

• Signed integers: Int/Int64 (default), Int32, Int16, Int8
• Unsigned integers: UInt64, UInt32, UInt16, UInt8
• Floating point: Float/Float64 (default), Float32
• Characters: Char (UTF-8 code unit), Rune (Unicode code point)
• Binary data: Bytes (fat pointer for raw bytes)
• Other: Bool, String, Void
• Integer casts: value as Type between the sized integer types — widening sign/zero-extends from the source type, narrowing truncates. E.g. packing eight UInt8 into an Int64: (b0 as Int64) | ((b1 as Int64) << 8) | ....
• Explicit integer assignment: a variable/field may only change integer width or signedness through as; a bare in-range constant still fits (x<Int8> = 3), but an out-of-range constant or any typed value crossing width/signedness is a compile error (x<Int8> = 300, x<Int8> = wide<Int>).

Current Collection Types:

• Fixed arrays: [T; N] with compile-time size
• Dynamic arrays: Vec<T> resizable collections
• Keyed maps: HashMap<K, V> (hash buckets, auto-growing), BTreeMap<K, V> (ordered by key)
• Sets: HashSet<K> distinct-key collections
• Tuples: Tuple<T,U,...> variadic heterogeneous types

HashMap, HashSet, and BTreeMap ship in stdlib/collections and are imported with import collections. Vec<T> itself layers Vyb-written higher-order helpers there — map / filter / reduce, sorted / reversed / find, min / max, and sort_in_place — taking non-capturing lambdas (fn) where a mapping function is needed.

Ownership Types: my<T> (unique), our<T> (shared), their<T> (borrowed), mild<T> (mild reference), loc<T> (freedom raw pointer)

Type Aliasing: All numeric types support multiple naming conventions:

• Vyb style: Int32, Float64, UInt8
• C style: int32, float64, uint8
• LLVM style: i32, f64, u8

Basic Syntax#

Vyb uses clean, expressive syntax with flexible parameter syntax:

# Functions support both standard and shorthand parameter syntax

# Standard syntax: explicit parameter<Type> or parameter<Type const>
add_standard(a<Int>, b<Int const>)<Int> -> {
    return a + b
}

# Shorthand syntax: Type directly (implicitly mutable)
add_shorthand(Int a, Int b)<Int> -> {
    return a + b
}

# Mixed syntax: combining both forms in same function
mixed_params(x<Int>, Int y, const Int z)<Int> -> {
    return x + y + z
}

# Complex return types with auto-serialization
get_data()<Int, String, Bool> -> {
    return 42, "result", true
}
# When called from main(), outputs: {"Int":42,"String":"result","Bool":true}

Function Parameters#

Vyb supports two parameter syntax styles for maximum flexibility:

# Standard syntax: explicit mutability
format_standard(prefix<String>, value<Int const>)<String> -> {
    return prefix + String::from_int(value)
}

# Shorthand syntax: type-first (more concise)
format_shorthand(String prefix, const Int value)<String> -> {
    return prefix + String::from_int(value)
}

# Both produce identical behavior and LLVM IR

Variables and Types#

# Variables with type inference
x = 42          # Int
name = "Alice"  # String
flag = true     # Bool

# Explicit typing
count<Int> = 0
message<String> = "Hello"

# Immutable values (const is a type modifier)
PI<Float const> = 3.14159
MAX_SIZE<Int const> = 1000

Structs and Data#

# Define a struct with modern syntax
struct Point {
    x<Int>,
    y<Int>
}

# Create and use with field access
main()<Int> -> {
    p<Point> = Point { x = 10, y = 20 }
    return p.x + p.y  # Returns 30
}

Modules & Import System#

Vyb's unique dual import system provides both security and flexibility:

# Trusted imports from verified sources
import std::collections::Vec
import utils::math::calculate
import std::io::println

# Flexible imports for development and experimentation
smuggle debug::trace from "github.com/dev/tools"
smuggle experimental::parser from "./local/experiments"

# Use imported symbols
main()<Int> -> {
    numbers<Vec<Int>> = Vec()
    numbers.push(calculate(10))

    println(numbers)  # From trusted std::io
    trace("Debug info")  # From smuggled debug module

    return numbers.get(0)
}

Import Types:

• import: For signed, verified modules from registries or project dependencies
• smuggle: For external, experimental, or development-only modules

Declare dependencies in vyb.toml:

[dependencies]
std = "^1.0.0"                    # Verified registry package
utils = { git = "https://..." }    # External Git repository
local_tools = { path = "../tools" } # Local development dependency

Bundle & Sharing System: Fine-grained visibility control with bundles (bundle(...) and share(...) directives; see test/modules/import_bundle_allowed.vyb and test/modules/import_private_rejected.vyb):

# Declare module bundles
bundle(math, math.Core)

# Control symbol visibility
share(all) public_function()<Int> -> { ... }      # Public to all
share(math.UI) ui_helper()<Int> -> { ... }        # Only to math.UI bundle
internal_helper()<Int> -> { ... }                 # Private to this file

Arrays and Collections#

# Resizable vectors with full method support
main()<Int> -> {
    numbers<Vec<Int>> = Vec()
    numbers.push(10)
    numbers.push(20)
    numbers.push(30)

    println(numbers)  # Outputs: { "type": "Vec<Int>", "address": "0x..." }

    length<Int> = numbers.len()    # Gets 3
    first<Int> = numbers.get(0)    # Gets 10
    last<Int> = numbers.pop()      # Gets and removes 30

    return first + last  # Returns 40
}

# Vec iteration - parentheses mandatory
iterate_example()<Int> -> {
    items<Vec<Int>> = Vec()
    items.push(1)
    items.push(2)
    items.push(3)

    sum<Int> = 0
    for (item in items) {
        sum = sum + item
    }

    return sum  # Returns 6
}

# Fixed-size arrays also supported
array_example()<Int> -> {
    fixed<[Int; 3]> = [1, 2, 3]
    return fixed[0]  # Array indexing
}

Keyed & Set Collections — imported with import collections:

import collections

main()<Int> -> {
    # HashMap<K, V> — hash-bucket index, auto-grows, average O(1) lookup
    scores<HashMap<String, Int>> = HashMap<String, Int>()
    scores.put("alpha", 1)
    scores.put("beta", 2)
    scores.put("alpha", 99)               # overwrites the existing key
    n_scores<Int> = scores.size()         # 2
    score<Int?> = scores.get("beta")                 # Int? (2 when present, absent if missing)
    has_alpha<Bool> = scores.contains_key("alpha")   # true

    # HashSet<K> — distinct keys
    tags<HashSet<String>> = HashSet<String>()
    tags.insert("x")
    tags.insert("y")
    again<Bool> = tags.insert("x")        # false (already present)

    # BTreeMap<K, V> — keys iterate in sorted (Comparable) order
    ordered<BTreeMap<Int, String>> = BTreeMap<Int, String>()
    ordered.put(3, "three")
    ordered.put(1, "one")
    ordered.put(2, "two")                 # iteration order 1, 2, 3
    return 0
}

Higher-Order Vec Combinators — non-capturing lambdas, also import collections:

import collections

main()<Int> -> {
    v<Vec<Int>> = Vec()
    v.push(3); v.push(9); v.push(5)

    doubled<Vec<Int>> = v.map(|n<Int>| -> n * 2)          # fresh [6, 18, 10]
    odds<Vec<Int>>    = v.filter(|n<Int>| -> n % 2 == 1)  # fresh [3, 9, 5]
    total<Int>        = v.reduce(0, |a<Int>, b<Int>| -> a + b)  # 17
    v.sort_in_place()                                     # in place: [3, 5, 9]
    smallest<Int> = v.first()                             # 3
    return 0
}

Control Flow#

# Conditional expressions with modern syntax
check_sign(x<Int>)<String> -> {
    if (x > 0) {
        return "positive"
    } else if (x < 0) {
        return "negative"
    } else {
        return "zero"
    }
}

# While loops with break/continue
factorial(n<Int>)<Int> -> {
    result<Int> = 1
    i<Int> = 1
    while (i <= n) {
        if (i == 0) {
            continue
        }
        result = result * i
        i = i + 1
        if (result > 1000) {
            break
        }
    }
    return result
}

# Vec iteration with for loops (parentheses mandatory)
sum_vector(numbers<Vec<Int>>)<Int> -> {
    total<Int> = 0
    for (num in numbers) {
        if (num < 0) {
            continue  # Skip negative numbers
        }
        total = total + num
        if (total > 100) {
            break  # Stop if sum exceeds 100
        }
    }
    return total
}

# For loops over the Iterator protocol: any non-identifier iterable
# expression desugars onto `.next()` (e.g. `v.iter()`, or a custom
# `bind Iterator` type). `break`/`continue` work and re-enter `next()`.
# An optional step (`for (x in v.iter(), 2)`) yields every 2nd element.
# The range (`0..n`) and plain-Vec (`for (x in vec)`) forms above are unchanged.
for (x in numbers.iter()) {
    total = total + x
}

# Range-based for loops (inclusive)
count_to_ten()<Int> -> {
    sum<Int> = 0
    for (i in 0..10) {
        sum = sum + i
    }
    return sum  # Returns 55
}

# Pattern matching with match statements
describe_number(x<Int>)<String> -> {
    match (x) {
        0 -> return "zero",
        1 -> return "one",
        42 -> return "the answer",
        ? -> return "some number"
    }
}

# Match arms can execute any statement, including return
# The match statement itself doesn't return a value, but pattern arms can
# return from the enclosing function when the type matches

# Select expressions - elegant pattern matching that returns a value
compute_bonus(level<Int>)<Int> -> {
    # Simple select with naked expressions (auto-return)
    multiplier<Int> = select(level) -> {
        1 -> 10,
        2 -> 20,
        3 -> 30,
        ? -> 5
    };
    return multiplier * 100
}

# Select with complex blocks and explicit pass keyword
process_request(code<Int>)<Int> -> {
    result<Int> = select(code) -> {
        1 -> {
            temp<Int> = 10;
            pass temp
        },
        2 -> {
            x<Int> = 20;
            pass x
        },
        3 -> {
            msg<Int> = 300;
            println(msg);
            pass msg
        },
        ? -> {
            pass 0
        }
    };
    return result
}

# Select expressions combine the best of match and expression values:
# - Naked expressions (1 -> 10) auto-return without 'pass'
# - Complex blocks ({ ... }) use 'pass' keyword to return value
# - 'pass' returns from the block, NOT the enclosing function
# - Type inference from first case ensures type safety
# - Wildcard '?' provides default case handling

select may also be used as a bare statement for side effects only — arms need not yield a value, and a block arm without pass simply falls through to the following statements. And because a select arm body is itself an expression, a select may appear as an arm of an enclosing select for per-branch sub-selection (see test/new_features/test_select_statement.vyb and test/new_features/test_select_nested.vyb).

Comparison Patterns (Range Matching)#

Vyb's pattern matching supports comparison patterns for elegant range-based matching with compile-time safety:

# Comparison operators in patterns: >, <, >=, <=, ==, !=

# Select expression - returns a value directly
classify_score(score<Int>)<String> -> {
    return select(score) -> {
        >= 90 -> "A",
        >= 80 -> "B",
        >= 70 -> "C",
        >= 60 -> "D",
        ? -> "F"
    }
}

# Match statement - returns from enclosing function
classify_score_match(score<Int>)<String> -> {
    match (score) {
        >= 90 -> return "A",
        >= 80 -> return "B",
        >= 70 -> return "C",
        >= 60 -> return "D",
        ? -> return "F"
    }
}

# Tax rate calculation with select
compute_tax_rate(income<Int>)<Float> -> {
    return select(income) -> {
        < 10000 -> 0.0,
        < 50000 -> 0.15,
        < 100000 -> 0.25,
        ? -> 0.35
    }
}

# Comparison patterns work with floats and integers
categorize_temperature(temp<Float>)<String> -> {
    match (temp) {
        < 0.0 -> return "freezing",
        < 10.0 -> return "cold",
        < 20.0 -> return "mild",
        < 30.0 -> return "warm",
        ? -> return "hot"
    }
}

# Unreachable pattern detection - compiler ERROR
invalid_patterns(x<Int>)<String> -> {
    match (x) {
        > 10 -> return "big",
        > 5 -> return "medium",  # ERROR: unreachable (subsumed by > 10)
        ? -> return "small"
    }
}

# Other unreachable pattern errors:
# - Wildcard before end: match (x) { ? -> "any", 5 -> "five" }  # ERROR
# - Duplicate patterns: match (x) { > 10 -> "a", > 10 -> "b" }  # ERROR
# - Overlapping ranges: match (x) { > 5 -> "a", >= 3 -> "b" }  # ERROR

Comparison Pattern Rules:

• Evaluation Order: Patterns tested top-to-bottom, first-match-wins
• Type Safety: Works with Int and Float types
• Compile-Time Errors: Unreachable patterns detected and rejected
• Wildcard Position: ? must be last pattern or compiler ERROR
• No Gaps Required: >= 90, >= 80, >= 70 is valid (evaluates top-to-bottom)

Match vs Select with Comparison Patterns:

• select: Expression that evaluates to a value - use naked expressions or pass keyword
• match: Statement for side effects - pattern arms can return from enclosing function
• Both support identical comparison pattern syntax and unreachable pattern detection

Set Patterns ({…}) in Select Arms#

An arm's pattern may be a brace-delimited set of several discrete values, so callers don't repeat a result per value. The arm matches when the target equals any element; first-match-wins ordering is preserved.

classify(x<Int>)<String> -> {
    return select(x) -> {
        {1, 3, 5, 7, 9} -> "odd",
        {2, 4, 6, 8}    -> "even",
        ?               -> "out of bounds"
    }
}

enum Color { Red, Green, Blue }
name(c<Color>)<String> -> {
    return select(c) -> {
        {Red, Blue}  -> "primary",
        {Green}      -> "green",
        ?            -> "unknown"
    }
}

Set elements may be literals (Int/Float/String/Bool/null) or bare enum-variant names (North, Shape::Square). These are enforced at compile time:

• Comparison patterns, payload-binding variants (Circle(r)), and arbitrary expressions are not allowed inside a set.
• An empty set {} is rejected, as is a wildcard that is not the last arm.
• Every element must share the select target's type (Int + String in one set is an error).
• A value listed in more than one arm is claimed by the earliest arm (no error).
• Enum-variant elements count toward select exhaustiveness checks on tagged-union enums.

Variadic Tuples#

Vyb supports fully variadic tuple types that can hold any number of heterogeneous elements (1 to N):

# Single-element tuples
get_single()<Tuple<Int>> -> {
    return 42  # Automatically wrapped in tuple struct
}

# Two-element tuples (dual syntax)
get_pair_inline()<Int, String> -> {
    return 10, "hello"  # Inline syntax
}

get_pair_generic()<Tuple<Int, String>> -> {
    return 20, "world"  # Generic syntax (equivalent)
}

# Multi-element tuples with mixed types
get_data()<Tuple<String, Int, Bool, Float>> -> {
    return "status", 200, true, 3.14
}

# Seven-element tuple demonstrating variadic support
get_complex()<Tuple<Int, Int, Bool, String, Int, Bool, Int>> -> {
    return 1, 2, true, "test", 3, false, 4
}

# Tuples work seamlessly with complex types
get_mixed()<Tuple<String, Vec<Int>, Bool>> -> {
    numbers<Vec<Int>> = Vec()
    numbers.push(1)
    numbers.push(2)
    return "data", numbers, true
}

main()<Int> -> {
    # All tuple syntaxes work identically
    single<Tuple<Int>> = get_single()
    pair<Tuple<Int,String>> = get_pair_inline()
    data<Tuple<String,Int,Bool,Float>> = get_data()

    return 0
}

Tuple Features:

• Variadic: Supports 1 to N type parameters (tested up to 7+ elements)
• Dual Syntax: Both (T,U,V) inline and Tuple<T,U,V> generic forms
• Type Safety: Full compile-time type checking for all elements
• Complex Types: Works with primitives, Strings, Vec, and custom types
• Auto-wrapping: Single values automatically wrapped when returning to tuple type
• LLVM Structs: Compiled to efficient anonymous struct types
• Element access: Bracket indexing (tuple[0], tuple[1], …) with .len()
• Tuple variables: Stored in typed variables, built from literals (a, b, c) (single-element (v,)), and passed to functions
• Serialization: A tuple returned from main() serializes to a JSON array ([1, "a", true])

String Theory#

Vyb's String type is a production-ready fat pointer implementation with comprehensive method support and natural literal syntax. Unlike C's null-terminated strings or C++'s heavyweight std::string, Vyb Strings combine the best of both worlds: efficient representation with modern conveniences.

String Structure#

# Internally, String is a fat pointer struct:
struct String {
    ptr: *i8,    # Pointer to null-terminated byte data
    len: i64     # Length (excluding null terminator)
}

This design provides:

• O(1) length queries - No strlen() scanning needed
• C interoperability - Null termination for printf, strstr, etc.
• Memory efficiency - Just 16 bytes overhead per string
• Safe indexing - Built-in bounds checking

Natural String Syntax#

String literals in Vyb are first-class citizens:

# Direct literal assignment
greeting<String> = "Hello, Vyb!"

# Literal concatenation (just works™)
message<String> = "Hello" + " " + "World"

# Method calls on literals
length<Int> = "Vyb".len()                    # Returns 3
first<Int> = "Quantum".char_at(0)            # Returns 'Q' (81)
check<Bool> = "Einstein".starts_with("Ein")  # Returns true

# All without explicit constructors!

String literals process backslash escapes: \n LF, \r CR, \t TAB, \\ a literal backslash, \" a double quote, \0 NUL, and \xHH a hex byte. Any other \X is kept verbatim (regex/path-friendly), so "\r\n" is a real CRLF pair — HTTP requests depend on this.

Complete Method Reference#

Constructor

# Create from raw bytes (C interop)
name<String> = String::from_bytes("Alice", 5)
raw<String> = String::from_bytes(c_ptr, c_len)

Property Access

msg<String> = "Hello"
length<Int> = msg.len()  # Returns 5, O(1) operation

Substring Operations

text<String> = "Hello World"

# Extract substring (end optional)
hello<String> = text.substring(0, 5)      # "Hello"
world<String> = text.substring(6, 11)     # "World"
rest<String> = text.substring(6)          # "World" (to end)

# Safe character access with bounds checking
first<Int> = text.char_at(0)      # 72 ('H')
space<Int> = text.char_at(5)      # 32 (' ')
invalid<Int> = text.char_at(99)   # 0 (null char for out of bounds)

Search and Comparison

sentence<String> = "The quick brown fox"

# Prefix/suffix checking
has_the<Bool> = sentence.starts_with("The")      # true
has_fox<Bool> = sentence.ends_with("fox")        # true
has_dog<Bool> = sentence.ends_with("dog")        # false

# Substring search
has_quick<Bool> = sentence.contains("quick")     # true
has_slow<Bool> = sentence.contains("slow")       # false

# Empty strings always match
always<Bool> = sentence.starts_with("")          # true

Case Conversion

mixed<String> = "Hello World"

# ASCII case conversion (allocates new string)
upper<String> = mixed.to_upper()   # "HELLO WORLD"
lower<String> = mixed.to_lower()   # "hello world"

# Original unchanged (immutability)
println(mixed)  # Still "Hello World"

String Concatenation

# Using + operator (most natural)
full<String> = "Hello" + " " + "World"

# Chaining operations
result<String> = "Code".to_upper() + " " + "Language".to_lower()
# Result: "CODE language"

# Mixed types auto-convert: "Count: " + 42
# message<String> = "Count: " + 42

Practical Examples#

Text Processing

process_input(text<String>)<Bool> -> {
    # Validate input
    if (text.len() == 0) {
        return false
    }

    # Check for command prefix
    if (text.starts_with("/")) {
        command<String> = text.substring(1)
        println("Command: " + command)
        return true
    }

    # Search for keywords
    if (text.contains("help")) {
        println("Help requested")
        return true
    }

    return false
}

String Manipulation

format_name(first<String>, last<String>)<String> -> {
    # Capitalize first letter of each name
    first_upper<String> = first.char_at(0).to_string().to_upper() +
                          first.substring(1).to_lower()

    last_upper<String> = last.char_at(0).to_string().to_upper() +
                         last.substring(1).to_lower()

    # Combine with space
    return first_upper + " " + last_upper
}

main()<Int> -> {
    formatted<String> = format_name("ALICE", "wonderland")
    println(formatted)  # "Alice Wonderland"
    return 0
}

Data Validation

validate_email(email<String>)<Bool> -> {
    # Simple email validation
    if (email.len() < 3) {
        return false  # Too short
    }

    if (!email.contains("@")) {
        return false  # No @ symbol
    }

    return true
}

Memory Management#

Allocation Strategy

# Read-only operations: ZERO allocations
len<Int> = "Hello".len()                    # No malloc
ch<Int> = "World".char_at(0)                # No malloc
check<Bool> = "Test".starts_with("Te")      # No malloc

# Transform operations: Allocate new strings
upper<String> = "hello".to_upper()          # malloc(6) for "HELLO\0"
sub<String> = "Hello World".substring(0, 5) # malloc(6) for "Hello\0"
concat<String> = "A" + "B"                  # malloc(3) for "AB\0"

# Reference-counted our<T> handles cleanup automatically when the last strong
# reference leaves scope with no strong references remaining

Bounds Safety

# All index operations are bounds-checked at runtime
text<String> = "Vyb"

safe<Int> = text.char_at(2)      # OK: returns 'n' (110)
safe2<Int> = text.char_at(0)     # OK: returns 'V' (86)

# Out of bounds returns safe defaults
oob1<Int> = text.char_at(-1)     # Returns 0 (null char)
oob2<Int> = text.char_at(100)    # Returns 0 (null char)

# substring returns empty string for invalid bounds
empty<String> = text.substring(10, 20)  # Returns {null, 0}

String Performance Characteristics#

C Interoperability#

All String methods produce null-terminated strings for C compatibility:

# Use with C functions via the FFI (extern "C" + typed C aliases)
name<String> = "Alice"
c_str<*i8> = name.to_bytes()  # Get raw pointer

# Interoperable with:
# printf("%s", c_str)
# strlen(c_str)
# strcmp(c_str1, c_str2)
# strstr(haystack, needle)

Concatenation & Chaining#

# Simple things are simple
msg<String> = "Hello" + " " + "World"

# Complex things are possible (when needed)
advanced<String> = data
    .to_lower()
    .substring(0, 100)
    .replace("old", "new")
    .trim()

String Theory Achievement Unlocked: You now understand Vyb Strings better than most physicists understand actual string theory! 🎻✨

Error Handling with trap/fail/ensure#

Vyb features an explicit error handling system that combines the clarity of exceptions with the safety of Result types. The trap/fail/ensure trio provides compile-time error tracking with zero runtime overhead for the happy path.

The Philosophy#

Traditional error handling offers two flawed extremes:

• Exceptions: Hidden control flow, unclear what can fail, runtime overhead
• Result Types: Verbose unwrapping, easy to ignore errors, cluttered code

Vyb's approach:

• Explicit propagation: Errors visible in type signatures
• Zero-cost success: No overhead when operations succeed
• Pattern matching: Handle errors elegantly with full type safety
• Heap allocation: Errors carry rich context through pointer passing

Error Fundamentals#

Functions declare error returns in their signatures using failable types:

# Functions that can fail return (T, error_ptr) tuples
divide(a<Int>, b<Int>)<Int> -> {
    if (b == 0) {
        fail 42  # Return error with code 42
    }
    return a / b
}

# The compiler wraps this as: { i64 result, i8* error } in LLVM

Type System Integration:

• Success path: Returns (value, null_ptr) tuple
• Error path: Returns (undefined, error_ptr) tuple
• Error pointers carry heap-allocated error structs
• Type IDs enable pattern matching on error types

The fail Keyword#

Create and propagate errors with fail:

# Simple error codes (primitive types)
fail 404                    # Integer error
fail "not found"            # String error
fail 3.14                   # Float error

# Structured errors (custom types)
struct DivisionError {
    code<Int>,
    dividend<Int>,
    divisor<Int>
}

divide_structured(a<Int>, b<Int>)<Int> -> {
    if (b == 0) {
        fail DivisionError {
            code = 42,
            dividend = a,
            divisor = b
        }
    }
    return a / b
}

Error Memory Layout:

Heap-allocated error struct (16 bytes):
  Offset 0-7:  Type ID hash (i64) - For pattern matching
  Offset 8-15: Error value/data    - Primitive or struct data

Type ID Hashing:

• Int → hash("Int") = -3994496327427856726
• String → hash("String") = unique value
• DivisionError → hash("DivisionError") = unique value
• Enables runtime type dispatch in trap handlers

The trap Block#

Handle errors with pattern matching:

# Basic trap with single error type
compute_safely(x<Int>, y<Int>)<Int> -> {
    result<Int> = {
        value<Int> = divide(x, y)  # May fail
        value * 2
    } trap (e<Int>) -> {
        println("Division failed with code: " + String::from_int(e))
        -1  # Return fallback value
    }
    return result
}

# Multiple error types with pattern matching
process_data(x<Int>)<String> -> {
    {
        value<Int> = risky_operation(x)
        "Success: " + String::from_int(value)
    } trap (e<Int>) -> {
        "Integer error: " + String::from_int(e)
    } trap (e<String>) -> {
        "String error: " + e
    } trap (e<DivisionError>) -> {
        "Division error code: " + String::from_int(e.code)
    }
}

# Wildcard trap - catch any error type
safe_operation(x<Int>)<Int> -> {
    result<Int> = {
        risky_call(x)
    } trap (e<DivisionError>) -> {
        println("Known error: division by zero")
        return 0
    } trap (e<?>) -> {
        println("Unknown error caught by wildcard!")
        return -1
    }
    return result
}

# Multi-type trap - catch union of error types
process_data(input<String>)<Int> -> {
    result<Int> = {
        parse_and_validate(input)
    } trap (e<ParseError | ValidationError>) -> {
        # Handler matches either ParseError or ValidationError
        println("Input processing failed")
        return -1
    } trap (e<NetworkError | TimeoutError>) -> {
        # Different handler for network-related errors
        println("Network issue, retrying...")
        return retry_operation(input)
    }
    return result
}

Pattern Matching Features:

• Type-safe: Only valid error types accepted
• Exhaustive: Compiler ensures all error types handled
• Field access: Access struct fields in trap handlers (e.code, e.dividend)
• Wildcard: Use } trap (e<?>) -> { } to catch any error type
• Multi-type: Use } trap (e<Type1 | Type2>) -> { } to catch union of types

Error Propagation#

Errors automatically propagate through call stacks:

# Three-level error propagation
divide(a<Int>, b<Int>)<Int> -> {
    if (b == 0) {
        fail 42  # Create error at bottom
    }
    return a / b
}

compute(x<Int>, y<Int>)<Int> -> {
    result<Int> = divide(x, y)  # Propagates error if divide fails
    return result + 10           # Only reached if divide succeeds
}

main()<Int> -> {
    val1<Int> = compute(10, 2)   # OK: 10/2 + 10 = 15

    val2<Int> = {
        compute(10, 0)  # Fails: division by zero
    } trap (e<Int>) -> {
        println("Caught error: " + String::from_int(e))
        -1  # Return fallback
    }

    return val1 + val2  # Returns 15 + (-1) = 14
}

Propagation Mechanics:

1. divide(10, 0) allocates error on heap, returns (undef, error_ptr)
2. compute checks error pointer, finds non-null, propagates (undef, error_ptr)
3. main trap block catches error, extracts type and value
4. Error memory freed after handling

Untrapped Errors#

Errors that escape without trap handlers trigger runtime termination:

divide(a<Int>, b<Int>)<Int> -> {
    if (b == 0) {
        fail 42
    }
    return a / b
}

main()<Int> -> {
    result<Int> = divide(10, 0)  # No trap handler!
    return result
}

Runtime Output:

┌─ UNTRAPPED FAILURE ──────────────────────────────────────────┐
│ Error: <runtime error>                                       │
│ Thread: 6472648897627130861                                  │
│ Time: 2025-10-21 10:01:29.810                                │
└──────────────────────────────────────────────────────────────┘

Exit Code: 1

Safety Guarantees:

• No silent failures
• No undefined behavior
• Clear error location (stack-trace capture in error structs)
• Graceful termination

Struct Errors with Context#

Rich error types carry debugging context:

struct ValidationError {
    field_name<String>,
    expected<String>,
    actual<String>,
    line_number<Int>
}

validate_input(input<String>)<Bool> -> {
    if (input.len() == 0) {
        fail ValidationError {
            field_name = "input",
            expected = "non-empty string",
            actual = "empty string",
            line_number = 42
        }
    }
    return true
}

main()<Int> -> {
    {
        is_valid<Bool> = validate_input("")
        0
    } trap (e<ValidationError>) -> {
        println("Validation failed:")
        println("  Field: " + e.field_name)
        println("  Expected: " + e.expected)
        println("  Actual: " + e.actual)
        println("  Line: " + String::from_int(e.line_number))
        1
    }
}

Output:

Validation failed:
  Field: input
  Expected: non-empty string
  Actual: empty string
  Line: 42

The ensure Keyword ✅ IMPLEMENTED#

The ensure keyword provides cleanup/finally semantics, guaranteeing code runs whether the block succeeds or fails:

# The ensure block runs on both success and failure paths
process_file(path<String>)<String> -> {
    file<File> = open_file(path)

    result<String> = {
        file.read()
    } trap (e<IOError>) -> {
        return ""
    } ensure -> {
        file.close()  # Always runs, success or failure
    }

    return result
}

# Execution order on error:
# 1. Block code executes and fails
# 2. Matching trap handler runs (if present)
# 3. ensure block always runs last

# Implementation details:
# - Parser fully supports } ensure -> { } syntax
# - Codegen inlines ensure blocks into control flow
# - Works with both success and failure paths
# - See: test/trap/test_ensure_simple.vyb

LLVM Code Generation#

The error handling system compiles to efficient LLVM IR:

; Failable function returning {i64 result, i8* error}
define { i64, ptr } @divide(i64 %a, i64 %b) {
entry:
  %is_zero = icmp eq i64 %b, 0
  br i1 %is_zero, label %error_path, label %success_path

error_path:
  ; Allocate error struct: 8 bytes type_id + 8 bytes value
  %error_mem = call ptr @malloc(i64 16)

  ; Store type ID at offset 0
  %type_id = i64 -3994496327427856726  ; hash("Int")
  store i64 %type_id, ptr %error_mem

  ; Store error value at offset 8
  %value_ptr = getelementptr i8, ptr %error_mem, i64 8
  store i64 42, ptr %value_ptr

  ; Return (undef, error_ptr) tuple
  %result = insertvalue { i64, ptr } undef, ptr %error_mem, 1
  ret { i64, ptr } %result

success_path:
  %quotient = sdiv i64 %a, %b
  ; Return (quotient, null) tuple
  %success = insertvalue { i64, ptr } undef, i64 %quotient, 0
  %success2 = insertvalue { i64, ptr } %success, ptr null, 1
  ret { i64, ptr } %success2
}

; Call site with error checking
define { i64, ptr } @compute(i64 %x, i64 %y) {
entry:
  %call = call { i64, ptr } @divide(i64 %x, i64 %y)
  %value = extractvalue { i64, ptr } %call, 0
  %error = extractvalue { i64, ptr } %call, 1

  ; Check if error occurred
  %has_error = icmp ne ptr %error, null
  br i1 %has_error, label %error_propagate, label %success

error_propagate:
  ; Propagate error up the stack
  %prop = insertvalue { i64, ptr } undef, ptr %error, 1
  ret { i64, ptr } %prop

success:
  %result = add i64 %value, 10
  %ret = insertvalue { i64, ptr } undef, i64 %result, 0
  %ret2 = insertvalue { i64, ptr } %ret, ptr null, 1
  ret { i64, ptr } %ret2
}

; Trap handler with type matching
define i64 @main() {
entry:
  %trap_error = alloca ptr
  store ptr null, ptr %trap_error
  br label %try_block

try_block:
  %call = call { i64, ptr } @compute(i64 10, i64 0)
  %value = extractvalue { i64, ptr } %call, 0
  %error = extractvalue { i64, ptr } %call, 1
  %has_error = icmp ne ptr %error, null
  br i1 %has_error, label %trap_landing, label %try_success

trap_landing:
  ; Load error and check type
  %error_typeid = load i64, ptr %error
  %type_matches = icmp eq i64 %error_typeid, -3994496327427856726
  br i1 %type_matches, label %catch_handler, label %unmatched

catch_handler:
  ; Extract error value from offset 8
  %value_ptr = getelementptr i8, ptr %error, i64 8
  %error_value = load i64, ptr %value_ptr

  ; Free error memory
  call void @free(ptr %error)

  ; Handle error (return -1)
  br label %after_trap

unmatched:
  ; No matching handler - call runtime
  call void @__vyb_runtime_untrapped_error(ptr %error)
  unreachable

try_success:
  br label %after_trap

after_trap:
  %result = phi i64 [ %value, %try_success ], [ -1, %catch_handler ]
  ret i64 %result
}

Error-Handling Performance Characteristics#

Happy Path (No Errors):

• Zero allocation: No heap operations when no errors occur
• Zero branching overhead: Modern CPUs predict success path well
• Single comparison: icmp ne ptr %error, null per call
• Optimal inlining: Small functions inline away error checks

Error Path:

• One malloc: 16-byte allocation for error struct
• Type matching: O(1) hash comparison per trap handler
• Single free: Clean error memory in trap handler
• Stack unwinding: Return through call frames (no exception tables)

Error Handling Best Practices#

1. Use Specific Error Types

# Good: Rich context
struct FileError {
    path<String>,
    operation<String>,
    reason<String>
}

# Less good: Generic integer codes
fail 404

2. Handle Errors Close to Source

# Good: Handle immediately if recovery is possible
result<String> = {
    read_file(path)
} trap (e<FileError>) -> {
    println("Using default config due to: " + e.reason)
    default_config()
}

# Sometimes okay: Let errors propagate if caller should decide
data<String> = read_file(path)  # Propagates error to caller

3. Document Error Conditions

# Read configuration from file
#
# Errors:
#   FileError { operation = "open", ... } - File doesn't exist
#   FileError { operation = "read", ... } - Permission denied
#   ParseError { ... } - Invalid TOML format
read_config(path<String>)<Config> -> {
    # Implementation...
}

4. Prefer Structured Errors Over Codes

# Good: Self-documenting
struct NetworkError {
    url<String>,
    status_code<Int>,
    retry_after<Int>
}

# Less good: Requires external documentation
fail 503  # What does this mean?

Example: Complete Error Handling#

A comprehensive example showing all error handling features:

# Define domain-specific error types
struct ParseError {
    input<String>,
    position<Int>,
    expected<String>
}

struct ValidationError {
    field<String>,
    constraint<String>
}

struct DatabaseError {
    query<String>,
    code<Int>
}

# Parse integer from string
parse_int(s<String>)<Int> -> {
    # Actual parsing logic would go here
    if (s.len() == 0) {
        fail ParseError {
            input = s,
            position = 0,
            expected = "non-empty string"
        }
    }
    return 42  # Simplified
}

# Validate age constraint
validate_age(age<Int>)<Bool> -> {
    if (age < 0) {
        fail ValidationError {
            field = "age",
            constraint = "must be non-negative"
        }
    }
    if (age > 150) {
        fail ValidationError {
            field = "age",
            constraint = "must be <= 150"
        }
    }
    return true
}

# Store user in database (can fail)
store_user(name<String>, age<Int>)<Int> -> {
    valid<Bool> = validate_age(age)  # Propagates ValidationError

    # Simulate database operation
    if (age == 42) {
        fail DatabaseError {
            query = "INSERT INTO users",
            code = 1062  # Duplicate entry
        }
    }

    return 1  # User ID
}

# Process user registration with comprehensive error handling
register_user(name<String>, age_str<String>)<String> -> {
    # Multi-level error handling with different error types
    result<String> = {
        # Parse age (may fail with ParseError)
        age<Int> = parse_int(age_str)

        # Store user (may fail with ValidationError or DatabaseError)
        user_id<Int> = store_user(name, age)

        "User registered with ID: " + String::from_int(user_id)

    } trap (e<ParseError>) -> {
        msg<String> = "Parse failed: " + e.expected +
                     " at position " + String::from_int(e.position)
        println(msg)
        "PARSE_ERROR"

    } trap (e<ValidationError>) -> {
        msg<String> = "Validation failed for " + e.field +
                     ": " + e.constraint
        println(msg)
        "VALIDATION_ERROR"

    } trap (e<DatabaseError>) -> {
        msg<String> = "Database error " + String::from_int(e.code) +
                     " in query: " + e.query
        println(msg)
        "DATABASE_ERROR"
    }

    return result
}

main()<Int> -> {
    # Test success path
    result1<String> = register_user("Alice", "25")
    println(result1)  # "User registered with ID: 1"

    # Test ParseError
    result2<String> = register_user("Bob", "")
    println(result2)  # "PARSE_ERROR"

    # Test ValidationError
    result3<String> = register_user("Charlie", "-5")
    println(result3)  # "VALIDATION_ERROR"

    # Test DatabaseError
    result4<String> = register_user("Dave", "42")
    println(result4)  # "DATABASE_ERROR"

    return 0
}

Key Takeaways:

• Type Safety: Each error type is distinct and statically checked
• Composability: Errors propagate through multiple function layers
• Clarity: Error handling is explicit in code structure
• Performance: Only allocates memory when errors actually occur
• Ergonomics: Pattern matching makes error handling elegant

The Vyb error handling system achieves the rare combination of safety, performance, and ergonomics that makes robust error handling a joy rather than a chore.

Build System#

Vyb uses CMake for building:

# Clean build
mkdir -p build && cd build
cmake .. && make clean && make -j

# Quick rebuild (from project root)
make -C build -j

# Run a single file
build/vyb test/string/string_test.vyb

# Run demos and examples
build/vyb test/run_examples.vyb --vyb build/vyb
cmake --build build --target run-examples

# Run the milestone gate
build/vyb test/run_milestone.vyb --vyb build/vyb
cmake --build build --target run-milestone

Test Harness#

Vyb's canonical test runner is test/run_tests.vyb — a Vyb program, the same suite wired into CTest as the run-tests target and used for the full regression gate (currently 1314 .vyb tests, all passing):

Quick Testing#

# Full suite (JIT execution), from the repo root
build/vyb test/run_tests.vyb --vyb build/vyb --test-dir test

# Run a single category (parse, semantic, async, tls, ...)
build/vyb test/run_tests.vyb --vyb build/vyb --test-dir test --category async

# Split the suite across cores: K is 0-based, N is the shard count
build/vyb test/run_tests.vyb --vyb build/vyb --test-dir test --shard 0/4 &

# Save results as JSON, or full run evidence
build/vyb test/run_tests.vyb --vyb build/vyb --test-dir test --json results.json
build/vyb test/run_tests.vyb --vyb build/vyb --test-dir test --evidence evidence.json

The runner is single-threaded, so --shard K/N is how CI (.github/workflows/ci.yml) runs the suite on several cores at once: it walks the same deterministic discovery list and keeps every Nth entry, so the shards are disjoint and complete. --list prints what an invocation selects without running it, and CI proves the partition by diffing the union of the four shard lists against the full list. The compiler build is cached through ccache, so a re-run does not rebuild it from scratch.

vyb --repo (or vyb test with no explicit paths inside the compiler repo) runs the same Vyb runner, so the compiler's own test path is written in Vyb end to end. A secondary harness (test_harness.vyb) plus triage_tool.vyb — both Vyb programs — add JSON/HTML reporting, failure-triage, and performance analysis on top of that suite; the authoritative pass/fail count is always the run-tests CTest target output.

Test Analysis and Triage#

# Analyze test failures and create triage plan
build/vyb triage_tool.vyb results.json

# Generate markdown triage report
build/vyb triage_tool.vyb results.json --output-format markdown --output triage.md

# Focus on critical issues only
build/vyb triage_tool.vyb results.json --priority critical,high

Test Features#

• 1314 Tests, All Passing: The full run_tests.vyb suite covers parse, semantic, modules, async, agents, tls, qt, and every other feature area
• Harness Reporting: test_harness.vyb adds JSON/HTML reports and failure triage on top of the runner (sequential execution; --workers is accepted for compatibility)
• Rich Reporting: HTML, JSON, and console output with detailed metrics
• Smart Categorization: Automatic test categorization and filtering
• Failure Analysis: Pattern recognition and triage plan generation
• Performance Tracking: Execution time analysis and slow test detection

GPU Kernels (CUDA / NVPTX)#

Vyb lowers a module to pure NVPTX device code with --kernel, emits PTX, and validates it with ptxas in the same step (a rejection is a hard error). Kernel mode has no host runtime: the string registry, heap allocator and call-stack runtime do not exist on the device, so kernels use the device intrinsics — tid_x, blk_x, dim_x, grid_x, ld_f32/ld_f64/ld_i32/ld_i64, st_f32/st_f64/st_i32, atomic_add_i32/atomic_add_f64, kernel_barrier, ld_shared_f64.

Emit and validate#

# a value/data-parallel kernel with no host references
build/vyb --kernel fixtures/kernel/axpy.vyb --ptx axpy.ptx            # default sm_86
build/vyb --kernel fixtures/kernel/axpy.vyb --ptx axpy.ptx --gpu sm_90
# -> PTX validated by ptxas (sm_86): axpy.ptx.cubin

// y = alpha * x + y — fixtures/kernel/axpy.vyb
axpy(alpha<Float>, x<Float>, y<Float>)<Float> -> {
    return alpha * x + y
}

Run a kernel on the GPU#

The signed cuda binding wraps the driver API. A kernel takes one argument — a device pointer to an array of i64 descriptor words, read in-kernel with ld_i64. The smallest complete example fills a device buffer:

build/vyb fixtures/cuda/launch_fill.vyb --module-path bindings --module-path bindings/cuda
# -> 42

Bigger worked examples: fixtures/kernel/matmul_smem.vyb (shared-memory tiled matmul) with fixtures/cuda/matmul_verify.vyb, and vendor cross-validation against cuBLAS, cuFFT and cuDNN in fixtures/cuda/.

Rules that save a bad afternoon#

• Build the argument array yourself. cuLaunchKernel takes one pointer — the array of argument cells — and addr() (issue #476) lets Vyb build it directly in one array literal: params = [addr(outD), addr(ka), …], then cuda_launch_n(hf, …, addr(params), nargs) (issue #478 made a literal with runtime elements work). Kernel arity is therefore not a launcher limit; the fixed-arity cuda_launch4* shims remain for the four-scalar case. (The issue #199 pitfall was packing: element i of kernelParams must point at the buffer holding argument i's value.) Float parameters travel as the raw f64 bits in their cell.
• Bulk transfers. Upload whole arrays with one cuMemcpyHtoD_v2 — from a buffer read with C stdio, or straight from a String's bytes via addr(s) (#476). A per-element cuda_write_i32 loop is fine for a 512-element fixture and fatal for a 60 MB array.
• Width discipline. The width of a store or atomic is the intrinsic's element type, not the width of the Vyb operand: st_f32 writes four bytes even though a Vyb Float is f64 in LLVM. fixtures/kernel/probe15_store_width.vyb is the regression fixture for exactly that, checked on silicon by fixtures/cuda/probe15_verify.vyb.
• Readback. A 4-byte scalar copied into an 8-byte host slot leaves garbage in the upper half — allocate device counters as 8 bytes and copy 8 bytes back.
• Testing. test/ffi/test_cuda_*.vyb run against the checked-in golden .ptx (fixtures/cuda/README.md); .github/workflows/gpu-kernel.yml re-emits every kernel across sm_75..sm_90 on CPU (sm_90a emits and ptxas-validates on a local toolchain) and runs the on-silicon cross-validations on a self-hosted GPU runner.

Full reference: doc/CUDA.md.

Project Structure#

Vyb/
├── src/              # C++ source code
│   ├── main.cpp      # Entry point with LLVM JIT
│   ├── lexer.cpp     # Tokenization
│   ├── parser.cpp    # Syntax analysis
│   └── ast.cpp       # Abstract syntax tree
├── include/vyb/      # Header files
├── test/             # Vyb test programs
├── examples/         # Example programs
├── doc/              # Documentation
└── build/            # Build output

Examples#

Simple Programs#

Hello World:

main() -> {
    println("Hello, Vyb!")
}

Mathematical Computation:

fibonacci(n<Int>)<Int> -> {
    if (n <= 1) {
        return n
    } else {
        return fibonacci(n - 1) + fibonacci(n - 2)
    }
}

main()<Int> -> {
    return fibonacci(10)  # Returns 55
}

Data Processing with Auto-Serialization:

struct Result {
    success<Bool>,
    value<Int>,
    message<String>
}

process_data(x<Int>)<Result> -> {
    if (x > 0) {
        return Result {
            success = true,
            value = x * 2,
            message = "Processing successful"
        }
    } else {
        return Result {
            success = false,
            value = 0,
            message = "Invalid input"
        }
    }
}

main()<Result> -> {
    return process_data(21)
}
# Outputs structured JSON for the Result

JSON Serialization & Deserialization#

Vyb includes a complete JSON serialization system with bidirectional conversion between structs and JSON:

Automatic Serialization#

struct Person {
    name<String>,
    age<Int>,
    active<Bool>
}

main()<Int> -> {
    person<Person> = Person { name: "Alice", age: 30, active: true }

    # Serialize to JSON string
    json<String> = person.to_string()
    println(json)  # Output: {"name": "Alice", "age": 30, "active": true}

    return 0
}

JSON Deserialization#

# Deserialize JSON back to struct
person2<Person> = Person::from_string(json)

# Access fields normally
println(person2.name)  # Output: Alice
println(person2.age.to_string())  # Output: 30

Supported Types#

• Primitives: Int, Float, Bool, String
• Vecs: Vec<Int>, Vec<String>, and Vec<struct> (arrays of objects)
• Struct Fields: Primitive, Vec, and nested struct fields
• Excluded: fn and Self field types are not serializable
• Round-Trip: Lossless struct → JSON → struct at arbitrary nesting depth. to_string() emits JSON with no fixed-size cap, so long strings, wide Vecs, and deeply nested structures never truncate; T::from_string(json) rebuilds the full value, including owned String and Vec payloads.
• Type Safety: Runtime validation of JSON structure
• Deserialization safety: T::from_string() never trusts lengths or counts from the input. Vec<T> capacity grows only as elements are actually parsed (never from a declared size), every allocation is OOM-guarded, and unknown fields are skipped rather than written out of bounds. Cleanly-deserialized input can't trigger an allocation bomb from hostile JSON.

Auto-Serialization for main() Returns#

One of Vyb's standout features is automatic serialization of complex return types from main():

• Simple integers: Serialize to stdout (main()<Int> -> { return 42 } prints 42)
• Complex types: Automatically serialize to JSON-like format
• Tuples: main()<Int,String> -> { return 10, "hello" } outputs [10, "hello"]
• Structs: Full structured output with field names and values

Implementation Details#

The JSON system is built on:

• Runtime Type Metadata: Global type registry with field information
• C Runtime Functions: __vyb_complex_to_json_with_metadata() and __vyb_complex_from_json_with_metadata()
• Type Registration: Automatic registration via global constructors
• Scalable Emitter: A growable output buffer emits arbitrary-depth JSON; recursive deserialization fills primitives, Vec<T>, and nested structs
• String Conversion: Seamless char* to VybString{data, length} struct conversion

See test/json/ for comprehensive examples and runtime/vyb_type_metadata.c for implementation.

This makes Vyb excellent for data processing scripts, API services, and configuration management.

Memory Safety#

Vyb provides multiple memory management strategies:

# Unique ownership: one owner, RAII cleanup
owned<my<String>> = my("unique data")

# Shared ownership (reference counted)
shared<our<String>> = our("shared data")
another_ref<our<String>> = shared  # Reference count incremented

# Borrowing (non-owning references)
view_ref<their<String>> = view(shared)      # Immutable borrow
mut_ref<their<String>> = borrow(owned)      # Mutable borrow

# Raw pointers for freedom operations
freedom {
    x<Int> = 42
    ptr<loc<Int>> = loc(x)  # Get pointer to x
    at(ptr) = 99           # Modify through pointer
}

Testing & Development Tools#

Vyb includes a modern, comprehensive testing infrastructure designed for efficient development and quality assurance:

🧪 Modern Test Harness#

The Vyb test harness (test_harness.vyb) layers reporting and triage on top of the canonical runner:

# Basic harness run over a directory
build/vyb test_harness.vyb --test-dirs test/units

# JSON + HTML reporting
build/vyb test_harness.vyb --test-dirs test/units --json-report results.json --html-report report.html

# Filter by pattern, category, tags, or priority
build/vyb test_harness.vyb --test-dirs test/units --pattern "test_async_*.vyb"
build/vyb test_harness.vyb --test-dirs test/units --category parser,semantic --priority high -v

The harness runs the selected files sequentially (--workers is accepted for compatibility) and reports the same per-test verdicts as the canonical runner.

Test Harness Features#

• Sequential Execution: runs the selected files in order (--workers accepted for compatibility)
• Rich Reporting: HTML reports with test results, timing, and failure analysis
• JSON Export: Machine-readable test data for CI/CD integration
• Triage Analysis: Automatic failure pattern recognition and prioritization
• Performance Tracking: Test execution timing and performance regression detection
• Flexible Filtering: Run specific tests, directories, or patterns
• Progress Tracking: Real-time progress bars and status updates
• Error Context: Detailed failure information with context and suggestions

Test Statistics#

• Total Tests: 1314 .vyb tests (full suite, all passing as of v0.7.7)
• Coverage Areas: Language features, control flow, error handling, type system, math, strings, introspection
• Test Types: Feature tests (with @expect: pass), future-feature docs (with @expect: fail), parser tests
• Success Rate: 100% (1314/1314) on the current suite

🔧 Syntax Migration Tools#

Automated tools ensure codebase consistency and syntax standardization:

# Scan for legacy syntax patterns
build/vyb migrate_syntax.vyb --scan --directory . --report

# Apply canonical syntax migrations with backup
build/vyb migrate_syntax.vyb --migrate --directory . --backup

Migration Capabilities#

• Legacy Detection: Identifies make_my(), make_our(), and function-call borrowing
• Automatic Conversion: Converts to canonical my(), our(), view, borrow syntax
• Backup Creation: Preserves original files before modification
• Comprehensive Reporting: Detailed migration reports with change summaries
• Pattern Recognition: Smart detection of syntax inconsistencies across file types

📊 Triage Analysis Tool#

Automated failure analysis and development prioritization:

# Generate a triage report from test results
build/vyb triage_tool.vyb test_results.json --output-format markdown --output triage_report.md

Triage Features#

• Pattern Recognition: Groups similar failures for efficient debugging
• Priority Assignment: Ranks issues by impact and frequency
• Root Cause Analysis: Identifies common failure patterns
• Debugging Recommendations: Suggests investigation strategies
• Progress Tracking: Monitors issue resolution over time

📈 Development Workflow#

The integrated toolchain supports efficient development:

1. Write Code: Use canonical syntax with ownership types
2. Run Tests: build/vyb test_harness.vyb --test-dirs test/units --json-report results.json
3. Check Syntax: build/vyb migrate_syntax.vyb --scan
4. Debug Issues: Use triage reports for prioritized debugging
5. Commit Changes: Regular Git commits with test validation

Architecture#

Vyb is built on solid foundations:

• Frontend: Hand-written recursive descent parser
• AST: Rich abstract syntax tree with source location tracking
• Backend: LLVM for code generation and ORC JIT execution
• Type System: Strong static typing with canonical ownership syntax
• Runtime: LLVM ORC JIT (LLJIT) with auto-serialization support
• Test Infrastructure: Modern parallel test harness with comprehensive reporting

Contributing#

Vyb is actively developed with regular commits tracking progress:

1. Language Features: Add new syntax, types, or operations
2. Standard Library: Implement core modules and utilities
3. Testing: Create comprehensive test cases
4. Documentation: Improve guides and examples
5. Performance: Optimize compilation and runtime

See doc/ directory for detailed design documents and RFCs.

Recent Progress#

Latest cycle (v0.7.x): stdlib concurrency + a network/UI demo

• ✅ chain stdlib module — a hash-chained legitimization core written entirely in Vyb over crypto.sha256: Record {label, value} facts are sealed into Merkle-rooted, prev-hash-linked ChainBlocks, producing a tamper-evident tip hash that a consumer can re-verify offline. One shared core, three consumers (VybOS package/boot legitimization, VybForge build records, smuggled-dependency receipts). Integrity layer by design — any record/order/link tamper fails verify; a signature layer (authenticity over keyed origins, key rotation, registry checkpoints) is the next increment on the same records. A provenance ledger, not a currency.
• ✅ Serializer field-offset fix (#215) — codegen now sets the host DataLayout before baking struct field offsets, so to_string() no longer mis-encodes an Int field that follows a Bool field at index ≥ 1.
• ✅ Set patterns in select arms ({ … }) — group several values into one arm; the arm matches when the target equals any element. Sets hold literals and bare enum-variant names; empty {} and mixed types are rejected, and the ? wildcard must remain the last arm.
• ✅ Per-task async reclamation (async_detach) — reclaim a single finished fiber's stack and captured environment early, so long-lived programs recycle fibers instead of accumulating one per async_spawn; a still-running task self-reaps on completion.
• ✅ http/https client hardening — chunked response-body decoding and dependable host connection (IPv4 address resolution), plus TLS context race fixes, so a web-capable client app can load real pages.
• ✅ VybLynx TUI demo (demos/VybLynx) — a curses box window with keyboard navigation, in-window URL editor, offline/error panes, and agent downloads; pages are fetched off the UI thread through the stdlib asyncs executor so the interface stays responsive.

v0.4.2 (freedom-1.0 series): Generic function monomorphization and FREEDOM blocks

• ✅ Generic Functions: Complete LLVM monomorphization system for generic functions with bounded type parameters
• Type Parameter Substitution: T → Point during codegen
• On-Demand Instantiation: Generate specialized functions like printItem_Point from templates
• Method Resolution: Call aspect methods on generic parameters (item.show() where item: T<Display>)
• Caching: Reuse monomorphized functions for same type combinations
• Integration: Works seamlessly with aspects, traits, and generic structs
• ✅ Select Expressions: Pattern matching expressions with select(expr) -> { pattern -> result }; syntax
• Naked expressions: Simple values auto-return without pass keyword
• Complex blocks: Use pass keyword to return from block without exiting function
• Type inference: First case determines result type for entire select
• Pattern matching: Exact equality patterns with wildcard ? support
• ✅ Canonical Syntax Unification: Complete migration to unified my()/our() constructors and view/borrow operators
• ✅ Modern Test Harness: test/run_tests.vyb running the full suite — 1314 .vyb tests all passing — with an auxiliary parallel/HTML/triage harness
• ✅ Syntax Migration Tools: Automated migration from legacy to canonical syntax with comprehensive reporting
• ✅ Match Statements: Complete pattern matching with -> arrow syntax and ? wildcard; no-match results in NOP
• ✅ Break/Continue: Loop control flow statements working in all loop types
• ✅ Vec Collections: Fully functional resizable arrays with all methods (new, push, pop, len, get)
• ✅ Modern Struct Syntax: Updated to field<Type> syntax with perfect field access
• ✅ Complete Binary Operations: All arithmetic, comparison, logical, and bitwise operators
• ✅ Dual Parameter Syntax: Both var<Type> name and Type name forms working seamlessly
• ✅ Member Access: Object field access (obj.field) and array indexing (arr[index])
• ✅ Auto-serialization: Complex return types with smart JSON-like output
• ✅ Async/Await: async functions with Future<T> types and await (synchronous resolution today)
• ✅ Debug Infrastructure: Full LLVM debug metadata for source-level debugging

Language Status: Vyb (freedom-1.0 series, tracked as v0.7.x) is an actively developed systems programming language with unified canonical syntax, a sized type system (Int8–Int64, UInt8–UInt64, Float32/Float64, Char, Rune, Bytes), compile-time monomorphized generics, aspect/bind polymorphism, a fail/trap error system, JIT/AOT/native codegen, and a modern test harness. The core language is stable and well tested; see doc/FEATURE_STATUS.md for the current feature matrix.

Getting Help#

• Documentation: See doc/ for language design and internals
• Examples: Check examples/ for working programs
• Tests: Review test/ for feature demonstrations
• Issues: Report bugs or request features on GitHub

Appendix#

A. Grammar (EBNF)#

The formal EBNF grammar now lives in the canonical reference, docs/refman/PROGRAMMERS_GUIDE.md §Appendix D — Grammar (EBNF). It is consolidated there so the project has one grammar home; the appendix also notes which productions are legacy.

B. Memory Model Reference#

Ownership Types:

• my<T>: Unique ownership, RAII cleanup
• our<T>: Shared ownership, reference counted
• their<T>: Non-owning borrow, lifetime checked
• mild<T>: Mild reference, can detect destruction via grab() and released()

Borrowing Operations:

• view(expr): Creates their<T const> immutable borrow
• borrow(expr): Creates their<T> mutable borrow
• soft(expr): Creates mild<T> mild reference from our<T>

Freedom Operations:

• loc<T>: Raw pointer type
• loc(expr): Get pointer to expression
• at(ptr): Dereference pointer (read/write)
• from<loc<T>>(expr): Pointer type conversion

C. Auto-Serialization Reference#

Vyb automatically serializes complex return types from main():

Simple Returns:

• main()<Int> -> { return 42 } → Exit code 42
• main()<String> -> { return "hello" } → Outputs: hello

Complex Returns:

• main()<Int,String> -> { return 42, "hello" } → Outputs: [42, "hello"]
• Struct returns → JSON with field names and values
• Vec returns → JSON array representation

Customization: Implement Serialize aspect for custom serialization behavior.

Glossary#

AST (Abstract Syntax Tree) Tree representation of source code structure produced by the parser.

Borrow Checking Compile-time analysis ensuring references don't outlive the data they point to.

Bundle Module visibility grouping via bundle(...) / share(...) directives.

Import Secure module inclusion from verified, signed sources.

JIT (Just-In-Time) Runtime compilation of code to native machine instructions for performance.

LLVM Low Level Virtual Machine - compiler infrastructure used by Vyb's backend.

Monomorphization Compile-time process of creating specialized versions of generic functions/types.

Ownership Memory management system using my<T>, our<T>, their<T>, mild<T> types.

Pattern Matching match statements that destructure and test values against patterns.

Smuggle Flexible module inclusion from external, potentially unverified sources.

Template Compile-time generic construct parameterized by types or constants.

Vec Resizable array collection with methods like push(), pop(), len(), get().

License#

Copyright 2026 Aniviza LLC. Licensed under the Apache License, Version 2.0 — see the LICENSE file for the full text.

Vyb (freedom-1.0 series): A mature systems programming language with a comprehensive sized type system, unified name-first syntax, pattern matching, compile-time monomorphized generics, resizable collections, an aspect/bind polymorphism system, and a unique import/smuggle module system.