24. Documentation

Standard Library

std.io - Input/Output

The std.io module provides basic I/O functions for printing and reading data. These are implemented as native functions in the BraidVM runtime.

import std.io

fn main() {
    io.print("Hello, World!")
    io.println("This is a line")
    io.print_int(42)
    io.print_float(3.14159)
    io.print_string("explicit string")
    let input = io.read()
}

The print function accepts any type and converts it to a string representation. println appends a newline. read reads a line from stdin and returns it as a string.

std.math - Mathematical Functions

The std.math module wraps standard C math functions for use in Braid programs. These are exposed via native fn declarations in the runtime.

import std.math

fn compute_stats(values: [float]) {
    let sum = 0.0
    let i = 0
    while i < len(values) {
        sum = sum + values[i]
        i = i + 1
    }
    let mean = sum / len(values)
    let variance = 0.0
    i = 0
    while i < len(values) {
        let diff = values[i] - mean
        variance = variance + diff * diff
        i = i + 1
    }
    variance = variance / len(values)
    io.print("Mean: ")
    io.print_float(mean)
    io.print(", Stddev: ")
    io.print_float(math.sqrt(variance))
}

std.compiler - Compiler Interface

The std.compiler module exposes compiler functionality at runtime. It allows compiling, evaluating, and inspecting Braid code dynamically.

import std.compiler

fn plugin_system(plugin_code: string, input: int) -&gt; int {
    let wrapped = "fn plugin(x: int) -> int { " + plugin_code + " }"
    let plugin_fn = compiler.compile(wrapped)
    return compiler.exec(plugin_fn, [input])
}

fn main() {
    let result = plugin_system("return x * x + 1", 5)
    io.print_int(result)    // 26
}

Function	Description
`compiler.compile(source)`	Compile source to bytecode module
`compiler.eval(source)`	Compile and execute, return result
`compiler.exec(module, args)`	Execute a compiled module with arguments

std.dts - Distinction Tree System

The std.dts module provides DTS (Distinction Tree) operations for hierarchical data processing, pattern matching on trees, and symbolic computation.

import std.dts

fn analyze_tree(tree) {
    let depth = dts.depth(tree)
    let size = dts.size(tree)
    let labels = dts.labels(tree)
    let prediction = dts.predict(tree, features)
    dts.traverse(tree, fn(node) {
        io.print("Visiting node: ")
        io.print(node)
    })
    return prediction
}

fn main() {
    let model = dts.load("model.dts")
    let features = [1.0, 0.5, 0.8]
    let result = dts.predict(model, features)
    io.print_float(result)
}

Module Overview

Module	Description
`std.io`	Print, println, read, print_int, print_float, print_string
`std.math`	sqrt, sin, cos, tan, exp, log, pow, abs, floor, ceil
`std.compiler`	compile, eval, exec - runtime code generation
`std.dts`	load, predict, traverse, depth, size, labels
`std.time`	now, sleep, timer, duration

Import Convention

Modules are imported using dot-separated paths. The compiler searches for .br or .bx files matching the path. Standard library modules are linked into the BraidVM runtime as native libraries.

import std.io
import std.math
import std.compiler
import std.dts
import std.time

fn use_all() {
    std.io.println("Using Braid standard library")
    let x = std.math.sqrt(16.0)
    let compiled = std.compiler.compile("fn f() -&gt; int { return 42 }")
    let result = std.compiler.exec(compiled, [])
    std.io.print_int(result)
}