44. Documentation

Migration Guides

Coming from Python

Python developers will find Braid familiar but need to adjust to a few key differences:

Add Semicolons and Braces

Python uses indentation for block structure. Braid uses {} and ;. Every statement must end with a semicolon, and blocks are delimited by braces.

# Python
def greet(name):
    print(f"Hello, {name}")

// Braid
fn greet(name: string) {
    print("Hello, " + name);
}

Add Types (Optional)

Python is dynamically typed. Braid is statically typed but uses inference. You can omit type annotations and the compiler will infer them. Explicit types on parameters and return values are optional but recommended.

// Type-annotated
fn divide(a: float, b: float) -&gt; float {
    return a / b
}

// Type-inferred
let x = 42       // int
let y = 3.14     // float
let z = "hello"  // string

Use fn Instead of def

Replace def name(args): with fn name(args) {}.

No List Comprehensions

Braid does not yet support list comprehensions. Use while loops or array operations instead.

Error Handling via nil Returns

Instead of exceptions, Braid uses nil-returning functions and match for error handling:

fn safe_divide(a: float, b: float) {
    if b == 0.0 {
        return nil
    }
    return a / b
}

match safe_divide(10.0, 0.0) {
    nil => print("Division by zero"),
    val => print("Result: " + val)
}

Coming from Rust

Less Strict Ownership

Rust's borrow checker enforces ownership, lifetimes, and borrowing rules at compile time. Braid uses ARC with cycle detection — you don't need to annotate lifetimes, use & references, or fight the borrow checker. Just assign and use values freely.

// Rust
fn process(data: &Vec<i32>) -> i32 {
    data.iter().sum()
}

// Braid
fn process(data: [int]) -> int {
    let sum = 0
    // just use data directly
    return sum
}

Simpler Syntax

No turbofish (::<>), no lifetime annotations ('a), no &/* dereferencing. Braid uses fn instead of fn, and generics use angle brackets without turbofish.

Match is Still There

Braid has match similar to Rust's, but without exhaustive checking (currently). Patterns can be integers, strings, booleans, enums, and nil.

Coming from C

Named Types Instead of Typedef

Braid's struct and enum declarations create named types directly — no separate typedef needed.

// C
typedef struct { int x; int y; } Point;

// Braid
struct Point { x: int; y: int }

ARC Instead of malloc/free

No manual memory management. All values are tracked by reference count and freed automatically when they go out of scope. Cycle detection runs periodically to collect reference cycles.

No Pointer Arithmetic

Braid does not support pointer arithmetic. Use array indexing and slices instead.

String Handling

Braid strings are first-class UTF-8 values, not null-terminated character arrays. Use + for concatenation.

Coming from JavaScript

Static Typing

JavaScript is dynamically typed. Braid requires all values to have known types at compile time. TypeScript developers will feel at home with type annotations, but Braid's type system is stricter (no any escape hatch).

No Prototype Chain

Braid uses struct with impl blocks for methods, not prototype-based inheritance. No this binding issues — use self as the first parameter.

No undefined/null Confusion

Braid has a single null value: nil. There is no undefined. Functions that can fail return nil instead of throwing exceptions.

// JavaScript
function add(a, b) { return a + b }

// Braid
fn add(a: int, b: int) -&gt; int {
    return a + b
}

Concurrency

Instead of JavaScript's single-threaded event loop, Braid supports spawn for green threads and async/await for cooperative multitasking with true parallelism.