Standard Library Reference

Modular Standard Library (std/...)

BramandScript adheres to the Lean VM & Modular Standard Library Principle (Rule 12). Rather than polluting the core bytecode execution engine with high-level domain algorithms, capabilities are structured into clean, modular .bmd packages located in the stdlib/ directory.

import "std/math" as math

let radius = 5.0
let circle_area = math.PI * radius * radius
println("Circle area:", circle_area)

println("GCD(84, 36):", math.gcd(84, 36))     // 12
println("LCM(12, 18):", math.lcm(12, 18))     // 36
println("5! =", math.factorial(5))             // 120
println("Average:", math.avg([10, 20, 30, 40])) // 25.0

import "std/strings" as str

let title = "bramand virtual machine"
println(str.capitalize(title))            // "Bramand virtual machine"
println(str.pad_left("42", 6, "0"))       // "000042"
println(str.slugify("Next Gen VM Engine")) // "next-gen-vm-engine"
println(str.truncate("A very long sentence here", 11, "...")) // "A very long..."

import "std/collections" as coll

let numbers = [1, 2, 3, 4, 5, 6, 7, 8]
let evens = coll.filter(numbers, fn(x) { return x % 2 == 0 })
let squared = coll.map(evens, fn(x) { return x * x })
println("Squared evens:", squared) // [4, 16, 36, 64]

// Deep recursive flatten
let nested = [1, [2, [3, [4, 5]]], 6]
println("Flat:", coll.flatten(nested)) // [1, 2, 3, 4, 5, 6]

// Grouping by parity
let grouped = coll.group_by(numbers, fn(x) {
    if x % 2 == 0 { return "even" }
    return "odd"
})
println("Even bucket:", grouped["even"]) // [2, 4, 6, 8]

import "std/json" as json

let data = json.parse("{\"node\": \"cluster-01\", \"port\": 8080}")
println("Node:", data["node"])

// Defensive parsing with fallback
let bad_json = "{ corrupted: json }"
let safe_data = json.safe_parse(bad_json, {"fallback": true})
println("Fallback:", safe_data["fallback"]) // true

import "std/io" as io

io.print_header("Disk Quota Monitor")
io.write_text("cache/test.txt", "data payload\n")
if io.exists("cache/test.txt") {
    println("File created successfully.")
    io.remove("cache/test.txt")
}

import "std/testing" as t

describe("Authentication Security Suite", fn() {
    test("token length validation", fn() {
        let token = "bmd_secret_98765"
        t.assert_true(len(token) > 10, "token must exceed 10 chars")
        t.assert_not_null(token, "token must not be null")
        assert_eq(token[0], "b", "prefix must start with b")
        assert_ne(token, "", "token cannot be empty")
    })
})

import "std/tooling/disasm" as d
import "std/tooling/fmt" as f

// Disassemble a function closure dynamically
fn square(x) { return x * x }
println(d.disassemble(square))

// Canonical formatting
let formatted = f.format_source("fn add(a,b){return a+b}")
println(formatted)

import "std/log" as log

// Standard text logging with contextual attributes
log.info("Server started", {"port": 8080, "env": "production"})

// JSON formatted logging for cloud log aggregators
log.set_format("json")
log.warn("Database latency high", {"latency_ms": 450, "pool": "primary"})

// Instance logger with custom sink
let custom = log.new_logger(log.LEVEL_DEBUG, "json", fn(entry) {
    println("[SINK]", entry["message"])
})
custom.debug("Cache miss", {"key": "user:123"})

import "std/retry" as retry

let attempts = 0
let fetch_data = fn() {
    attempts = attempts + 1
    if attempts < 3 {
        throw "Connection timed out"
    }
    return {"status": 200, "data": "OK"}
}

// Retries up to 4 times with exponential backoff starting at 20ms
let result = retry.with_backoff(fetch_data, 4, 20, 500, 2)
println("Final result:", result["status"]) // 200

import "std/config" as cfg

let raw_env = "# Server Environment\nPORT=8080\nHOST=0.0.0.0\nexport DEBUG=true\n"
let env = cfg.parse_dotenv(raw_env)

println("Host:", env["HOST"]) // "0.0.0.0"
println("Port:", cfg.get(env, "PORT", "3000")) // "8080"
println("DB URL:", cfg.get(env, "DATABASE_URL", "sqlite://app.db")) // "sqlite://app.db"

import "std/uuid" as uuid

let id = uuid.v4()
println("UUID:", id) // "c4b69d4e-5e36-4071-87a2-7fa6203923c5"
println("Valid:", uuid.validate(id)) // true
println("Version:", uuid.version(id)) // 4

let parsed = uuid.parse(id)
println("Variant:", parsed.variant)   // "RFC4122"
println("Time Low:", parsed.time_low) // "c4b69d4e"

import "std/semaphore" as sem_mod

let sem = sem_mod.new(3) // Limit to 3 concurrent operations

// Automatic permit acquire and deferred release
let res = sem.with_permit(fn() {
    println("Active permits in use. Available:", sem.available())
    return "work done"
})

import "std/circuitbreaker" as cb_mod

let cb = cb_mod.new({
    "failure_threshold": 3,
    "reset_timeout": 5000,
    "fallback": fn() { return {"cached": true, "data": []} }
})

let response = cb.execute(fn() {
    return fetchRemoteService()
})

import "std/pool" as pool_mod

let pool = pool_mod.new(8) // 8 concurrent workers
let urls = ["item1", "item2", "item3", "item4"]

// Parallel map preserving exact output index order
let results = pool.map(urls, fn(url) {
    return processTask(url)
})

Terminal UI, TrueColor & CLI Framework (std/tui)

The std/tui standard library module provides an international-grade, zero-dependency Terminal User Interface and CLI application framework built entirely in BramandScript and Go's standard library. It encompasses 11 integrated submodules and native terminal builtins for rich command-line experiences:

1. std/tui/color — TrueColor Engine & Linear Gradients

Create rich 24-bit TrueColor ANSI strings using RGB or HEX definitions. The gradient generator calculates smooth linear color interpolations across arbitrary string lengths:

import "std/tui" as tui

// 24-bit TrueColor from HEX or RGB
let neon = tui.hex("#00f0ff") + "Cyberpunk Theme" + tui.RESET
println(neon)

// Multi-color linear gradient
let heading = tui.gradient("✦ BRAMAND CLUSTER ENGINE ✦", "#00f0ff", "#ff007f")
println(heading)

// Pre-defined Neon color palette constants
println(tui.hex(tui.NEON_GREEN) + "Node Operational" + tui.RESET)

2. std/tui/terminal & Native Keystroke Builtins

Low-level terminal inspection, cursor movement, and raw mode keystroke polling enable real-time games, interactive editors, and dynamic TUIs:

import "std/tui" as tui

// Query terminal columns and rows
let dims = term_size()
println("Viewport:", dims.cols, "columns by", dims.rows, "rows")

// Enable raw mode for single keypress capture (no enter key required)
term_raw(true)
println("Press any key to proceed (or 'q' to quit)...")
let key = read_key() // Blocks until keypress or SGR sequence
if key == "q" {
    term_raw(false)
    exit(0)
}

// Non-blocking poll for pending key
let pending = poll_key()
term_raw(false) // Always restore canonical mode!

// Screen clearing & cursor positioning
tui.clear()
tui.cursor_to(5, 10)
println("Coordinates (5, 10)")

3. std/tui/table & std/tui/border

Tables automatically compute column widths while taking ANSI escape sequences into account (ignoring color codes for width calculations):

import "std/tui" as tui

// Render responsive Unicode box
let box_str = tui.box([
    tui.bold("Cluster Node Status"),
    tui.dim("Region: us-east-1 · Uptime: 99.98%"),
    tui.status("ok", "All VM fibers operational")
], {
    "title": "SYSTEM TELEMETRY",
    "border": "rounded",
    "border_color": tui.hex("#00f0ff"),
    "width": 50
})
println(box_str)

// Auto-sizing Table
let tbl = tui.new_table(["Service", "Port", "Status", "Latency"], {
    "border": "rounded",
    "border_color": tui.hex("#38bdf8")
})
tbl.add_row(["bmd.http.gateway", "8080", tui.badge("ACTIVE", "#10b981", "#ffffff"), "1.24 ms"])
tbl.add_row(["bmd.compiler.daemon", "9010", tui.badge("READY", "#3b82f6", "#ffffff"), "0.38 ms"])
tbl.add_row(["bmd.storage.kv", "9020", tui.badge("OK", "#06b6d4", "#ffffff"), "0.15 ms"])
tbl.print()

4. std/tui/progress, std/tui/chart & std/tui/tree

Sub-block 1/8th Unicode precision progress bars, sparkline trends, and hierarchical tree views:

import "std/tui" as tui

// 1. Sub-block Smooth Progress Bar with Gradient
let bar = tui.render_bar(68, 100, {
    "width": 30,
    "show_pct": true,
    "gradient_start": "#00f0ff",
    "gradient_end": "#10b981"
})
println("Heap Memory: " + bar)

// 2. Unicode Sparkline
let traffic = [12, 18, 32, 45, 60, 85, 95, 78, 62, 40, 25, 10]
println("Load Trend (60s): " + tui.sparkline(traffic, {"color": tui.CYAN}))

// 3. Hierarchical Tree
let root = tui.new_tree_node("bramandScript", [
    tui.new_tree_node("compiler", [
        tui.new_tree_node("lexer.go", []),
        tui.new_tree_node("parser.go", [])
    ]),
    tui.new_tree_node("vm", [
        tui.new_tree_node("vm.go", []),
        tui.new_tree_node("builtins.go", [])
    ])
])
println(tui.render_tree(root))

5. std/tui/input & std/tui/cli

Interactive user input dialogs with raw-mode password masking and full-featured CLI subcommand dispatch:

import "std/tui" as tui

// 1. Password input with masked bullets (●●●●●)
let pass = tui.secret("Enter cluster token: ")

// 2. Boolean confirmation
if tui.confirm("Deploy to production?", false) {
    println("Deploying...")
}

// 3. Full CLI Application Framework
let app = tui.new_cli("cluster", "1.0.0", "Cloud Cluster Management Tool")

app.command("deploy", "Deploy application payload to node", fn(ctx) {
    let target = ctx.args[0]
    let is_prod = ctx.flags["prod"] == true
    println("Deploying target:", target, "prod:", is_prod)
    return 0
})

app.command("status", "Inspect cluster health vitals", fn(ctx) {
    println(tui.status("ok", "Cluster healthy across all nodes."))
    return 0
})

app.run(args())

Arbitrary-Precision BigInt & BigFloat

BramandScript provides native arbitrary-precision arithmetic powered by Go's standard math/big package. Overloaded operators (+, -, *, /, %, **, unary -) and comparison operators work seamlessly with BigInt and BigFloat types.

let a = big_int("115792089237316195423570985008687907853269984665640564039457584007913129639935")
let b = big_int(2)
let sum = a + b
println("BigInt sum:", sum)

let f1 = big_float("3.1415926535897932384626433832795028841971", 256)
let f2 = big_float("2.7182818284590452353602874713526624977572", 256)
println("High precision product:", f1 * f2)

Vectors & Matrices (Linear Algebra)

Perform linear algebra operations for numerical simulations, 3D graphics, machine learning algorithms, and physics modeling:

let v1 = vec(1.0, 2.0, 3.0)
let v2 = vec(4.0, 5.0, 6.0)
println("Dot product:", v1.dot(v2))       // 32.0
println("Cross product:", v1.cross(v2))   // [-3.0, 6.0, -3.0]
println("Magnitude:", v1.magnitude())      // 3.7416573867739413

let m1 = matrix([[1, 2], [3, 4]])
let m2 = matrix([[2, 0], [1, 2]])
let prod = m1 * m2
println("Matrix multiplication:\n" + str(prod))
println("Determinant:", m1.det())         // -2.0

Trigonometric, Logarithmic & Statistical Library

All trigonometric, hyperbolic, transcendental, and statistical functions execute natively with zero external dependencies:

let samples = [12.5, 14.2, 11.8, 15.6, 13.9, 14.2]
println("Mean:", mean(samples))
println("Median:", median(samples))
println("Mode:", mode(samples))
println("Variance:", variance(samples))
println("Std Dev:", std_dev(samples))

println("Hypot(3, 4):", hypot(3.0, 4.0)) // 5.0
println("Log2(1024):", log2(1024.0))     // 10.0

JSON, CSV & Base64 Serialization

Robust, zero-dependency serialization and deserialization primitives:

// CSV parsing and generation
let csv_data = "name,role,level\nAlice,Admin,5\nBob,Dev,3"
let rows = csv_parse(csv_data)
println("CSV Rows:", rows)

// Base64 and Base64-URL
let encoded = base64_encode("BramandScript Engine")
let decoded = base64_decode(encoded)
println("Base64 roundtrip:", decoded)

Cryptography & CSPRNG (Secure Random & UUIDv4)

Cryptographically secure random number generation, secure UUID v4 tokens, SHA-256, SHA-512, MD5, and HMAC message authentication:

let hash = sha256("admin_secret_key")
println("SHA-256:", hash)

let token = uuid()
println("UUID v4:", token)

let mac = hmac_sha256("signing_key", "order_id=1024&amount=500")
println("HMAC-SHA256:", mac)

let rand_val = random_int(1, 1000)
println("CSPRNG Integer:", rand_val)

Web, HTTP Routing & Real-Time Hub (std/net)

The std/net package provides a high-performance web microframework built from scratch in BramandScript. It features a Radix/Trie URL router with parameter extraction, unified HTTP context with JSON body binding, composable onion middleware chaining, W3C Server-Sent Events (SSE), and multi-room WebSocket hubs.

import "std/net" as net

let router = net.create_router()

// Route with path parameters and query binding
router.get("/api/v1/users/:id", fn(ctx) {
    let user_id = ctx.param("id", "0")
    let verbose = ctx.query_param("verbose", "false")
    ctx.status(200)
    return ctx.send_json({
        "id": user_id,
        "name": "Aryan",
        "verbose": verbose == "true"
    })
})

// Route groups
let v1 = router.group("/api/v1")
v1.post("/echo", fn(ctx) {
    let body = ctx.json_body()
    return ctx.send_json(body)
})

Database & Storage Engine (std/db)

The std/db package delivers embedded persistence capabilities written 100% in BramandScript. It includes an append-only Write-Ahead Log (WAL) Key-Value store with log compaction, a JSON document collection database with MongoDB-style query operators, a fluent ANSI SQL query builder, and an Active-Record schema validation model layer.

import "std/db" as db

// 1. JSON Document Collection with Predicate Queries
let coll = db.create_collection("catalog", "catalog.json")
coll.insert({ "name": "Mechanical Keyboard", "price": 129.99, "category": "gear" })
coll.insert({ "name": "4K Monitor", "price": 399.00, "category": "display" })

// Filter documents where price > 100
let premium = coll.find({ "price": { "$gt": 100.0 } })

// 2. Fluent QueryBuilder to ANSI SQL
let q = db.query("users")
q.select(["id", "username", "email"])
q.where_gt("age", 18)
q.order_by("created_at", "DESC")
q.limit(10)

let sql = q.to_sql()
// SELECT id, username, email FROM users WHERE age > 18 ORDER BY created_at DESC LIMIT 10

Multi-Dimensional Tensor & Linear Algebra (std/math/tensor)

The std/math/tensor module delivers arbitrary N-dimensional tensor data structures with row-major memory layouts and strided coordinates. It natively computes 2D matrix multiplication (matmul), matrix transposition, determinant calculation, Gauss-Jordan matrix inversion, and solving linear systems (A * x = b).

import "std/math/tensor" as tensor

let A = tensor.from_array([
    [4.0, 7.0, 2.0],
    [3.0, 6.0, 1.0],
    [2.0, 5.0, 3.0]
])

println("det(A):", A.det())           // 9.0

// Invert matrix using Gauss-Jordan elimination
let A_inv = A.inv()

// Solve linear system: A * x = b where b = [10, 8, 3]^T
let b = tensor.from_array([[10.0], [8.0], [3.0]])
let x = A_inv.matmul(b)
// Solved: x = 3, y = 0, z = -1

Tabular DataFrame Engine (std/dataframe)

The std/dataframe module provides a Pandas-style tabular data analysis engine for BramandScript. It supports automated type-inferred CSV parsing, functional row filtering, column selection, sorting, grouped aggregations (group_by), and automated summary statistics (describe).

import "std/dataframe" as df

let raw_csv = read_file("employees.csv")
let frame = df.from_csv(raw_csv)

// Filter senior staff with salary >= 120,000
let seniors = frame.filter(fn(row) {
    return int(row["salary"]) >= 120000
})

// Group by department with multiple aggregation metrics
let summary = frame.group_by("department").agg({
    "salary": "mean",
    "sales": "sum",
    "id": "count"
})

// Export aggregated results directly to CSV
summary.save_csv("dept_summary.csv")

Neural Networks & Autograd Engine (std/ml)

The std/ml module is a pure BramandScript reverse-mode automatic differentiation (Autograd) and deep learning library inspired by Micrograd. It manages scalar computation graphs, reverse topological sort backpropagation, neural network layers, Multi-Layer Perceptrons (MLP), loss functions, and gradient descent optimization.

import "std/ml" as ml

// Construct 2 -> 4 -> 1 MLP
let model = ml.new_mlp(2, [4, 1])

// Training iteration:
let x = [ml.val(0.5), ml.val(0.8)]
let y_target = ml.val(1.0)

// 1. Forward pass
let y_pred = model.call(x)
let loss = ml.mse_loss([y_pred], [y_target])

// 2. Backward pass (reverse-mode automatic differentiation)
model.zero_grad()
loss.backward()

// 3. Optimizer step
model.step(0.05)

Exact Rational Numbers & Arbitrary Decimal Engine (std/math/rational & decimal)

Financial and scientific applications cannot tolerate binary IEEE-754 floating-point rounding errors (e.g. 0.1 + 0.2 != 0.3). BramandScript provides two first-class modules: exact fractional arithmetic with automatic GCD reduction (std/math/rational) and arbitrary/fixed-precision decimal arithmetic (std/math/decimal).

import "std/math/rational" as r
import "std/math/decimal" as d

// 1. Exact Fractions with Automatic GCD Reduction
let f1 = r.rational(2, 6)             // Automatically reduced to 1/3
let f2 = r.rational(1, 6)
let sum = f1.add(f2)                  // 1/3 + 1/6 = 1/2
let prod = f1.mul(r.rational(3, 2))   // 1/3 * 3/2 = 1/2
println("Sum:", sum.to_string())      // "1/2"
println("Float value:", sum.to_float()) // 0.5

// 2. Exact Financial Decimal Arithmetic (Zero Float Drift)
let d1 = d.decimal("0.1")
let d2 = d.decimal("0.2")
let total = d1.add(d2)
println("Exact decimal sum:", total.to_string()) // "0.3"

Complex Numbers, Number Theory & Constants (std/math/complex, ntheory, constants)

A full-featured mathematical engine supporting Cartesian/polar complex numbers with Euler identity evaluation, cryptographic number theory (Miller-Rabin primality, Pollard-rho, extended GCD, modular inverse), and Chudnovsky-grade constant generation:

import "std/math/complex" as c
import "std/math/ntheory" as nt
import "std/math/constants" as consts

// Complex Cartesian & Polar Arithmetic
let z1 = c.complex(3, 4)
println("|z1| magnitude:", z1.abs())      // 5.0
println("z1 conjugate:", z1.conj().to_string()) // "3 - 4i"

// Euler Identity Verification: e^(i*pi) + 1 = 0
let i_pi = c.complex(0, 3.141592653589793)
let euler = i_pi.exp() // Real part ~ -1.0, Imag ~ 0.0

// Cryptographic Number Theory
println("Is 7919 prime?", nt.is_prime(7919))            // true
println("Prime factors of 84:", nt.prime_factors(84))  // [2, 2, 3, 7]
println("Modular inverse of 7 mod 26:", nt.mod_inv(7, 26)) // 15
println("Combinations 6C2:", nt.nCr(6, 2))             // 15

// High-Precision Pi, E, and Golden Ratio Phi Digits
println("Pi (20 digits):", consts.compute_pi_digits(20))
println("E (20 digits):", consts.compute_e_digits(20))

Calculus, Optimization & ODE Solvers (std/math/calculus, opt, ode)

High-precision numerical differentiation, adaptive Simpson and Gauss-Legendre quadrature integration, root-finding (Newton-Raphson, Bisection, Brent-Dekker), scalar/gradient minimization, and 4th-order Runge-Kutta (RK4) differential equation integrators.

import "std/math/calculus" as calc
import "std/math/opt" as opt
import "std/math/ode" as ode

// 1. Numerical Differentiation: f(x) = x^3 at x = 2 -> f'(2) = 12
let f = fn(x) { return x * x * x; }
let d1 = calc.diff(f, 2.0)
let d2 = calc.diff2(f, 2.0)
println("d/dx x^3 at 2.0:", d1) // ~12.0

// 2. Numerical Integration: Integrate x^2 from 0 to 3 -> (3^3)/3 = 9.0
let quad = calc.integrate_simpson(fn(x) { return x * x; }, 0.0, 3.0, 50)
println("Simpson integral:", quad) // 9.0

// 3. Non-Linear Root Finding: x^2 - 4 = 0 -> root = 2.0
let root = opt.root_brent(fn(x) { return (x * x) - 4.0; }, 0.0, 5.0)
println("Brent root:", root.root) // 2.0

// 4. 4th-Order Runge-Kutta ODE Solver: dy/dt = -y, y(0) = 1.0 -> y(1.0) = 1/e
let trajectory = ode.ode_solve_rk4(fn(t, y) { return -y; }, 1.0, 0.0, 1.0, 0.1)
let final_state = trajectory[len(trajectory) - 1]
println("y(1.0) via RK4:", final_state[1]) // ~0.367879

Matrix Decompositions, Spectral Analysis & Sparse CSR (std/math/decomp, eigen, sparse)

Industrial-grade numerical linear algebra factorizations (LU with partial row pivoting, QR via Householder reflections, Cholesky decomposition), linear system solvers, least-squares regression, eigenvalue extraction via shifted QR, and memory-efficient Compressed Sparse Row (CSR) matrices.

import "std/math/decomp" as decomp
import "std/math/eigen" as eigen
import "std/math/sparse" as sparse

// 1. Solve Linear System A * x = b via LU Decomposition
let A = [
    [3.0, 2.0, -1.0],
    [2.0, -2.0, 4.0],
    [-1.0, 0.5, -1.0]
]
let b = [1.0, -2.0, 0.0]
let x = decomp.solve_linear_system(A, b)
println("Solution vector x:", x)

// 2. Symmetric Spectral Analysis via QR Eigenvalues
let sym = [
    [2.0, 1.0],
    [1.0, 2.0]
]
let spectral = eigen.eigen_qr(sym, 100, 0.0000000001)
println("Eigenvalues:", spectral.eigenvalues) // [3.0, 1.0]
println("Spectral radius:", eigen.spectral_radius(sym)) // 3.0

// 3. Compressed Sparse Row (CSR) Matrix Operations
let dense = [
    [1.0, 0.0, 0.0],
    [0.0, 0.0, 3.0],
    [4.0, 0.0, 5.0]
]
let csr = sparse.csr_from_dense(dense)
println("Non-zero entries (nnz):", csr.nnz()) // 4
let result_v = csr.matmul_vec([2.0, 10.0, 4.0]) // [2.0, 12.0, 28.0]

Resumable Iterators & Generator Streams (std/iter)

First-class stateful coroutine generators with yield, plus fluent lazy streaming operations (take, drop, map, filter, cycle, zip, to_array).

import "std/iter" as iter

// Generator function yielding values on demand
let gen = iter.generator(fn(yield) {
    let i = 1
    while true {
        yield i * 10
        i += 1
    }
})

// Take first 4 items lazily without evaluating infinite loop
let first_four = iter.take(gen, 4) // [10, 20, 30, 40]
println("First four:", first_four)

// Fluent streaming transformations
let stream = iter.range(1, 10, 2) // [1, 3, 5, 7, 9]
let doubled = stream.map(fn(x) { return x * 2; }).filter(fn(x) { return x > 5; })
println("Stream array:", doubled.to_array()) // [6, 10, 14, 18]

Native Compression & Archiving (std/compress)

Compress and decompress data streams or package entire file hierarchies into standard POSIX tar archives in pure Go standard library with zero external CLI dependencies.

import "std/compress/gzip" as gzip
import "std/compress/zlib" as zlib
import "std/compress/tar" as tar

// 1. Gzip Compression Round-Trip
let raw_text = "BramandScript pure standard library offline-first high performance!"
let gz_bytes = gzip.compress(raw_text)
let restored = gzip.decompress(gz_bytes)
println("Gzip verified:", str(restored) == raw_text)

// 2. Tar Multi-File Directory Archiving
let archive_bytes = tar.pack({
    "config.bmd": "let port = 8080;",
    "static/index.html": "<h1>Bramand App</h1>"
})
let extracted_files = tar.unpack(archive_bytes)
println("Unpacked config:", str(extracted_files["config.bmd"]))

Binary Struct Packing & MessagePack (std/binary/pack)

Compact wire protocols, telemetry serialization, and network socket framing using Python-style struct.pack / unpack format specifiers (>I, <h, f, d, s) and MessagePack binary encoding.

import "std/binary/pack" as bin

// 1. Python-style binary struct packing (>hhi4s = Big-Endian int16, int16, int32, 4-char string)
let format = ">hhi4s"
let packed_bytes = bin.pack(format, [42, -99, 123456, "BMD!"])
let unpacked_arr = bin.unpack(format, packed_bytes)
println("Unpacked ID:", unpacked_arr[0], "Magic:", unpacked_arr[3])

// 2. High-Speed MessagePack Encoding
let data = { "user": "bramand", "id": 101, "scores": [98.5, 95.0] }
let msgpack_bytes = bin.encode(data)
let decoded_data = bin.decode(msgpack_bytes)
println("Decoded user:", decoded_data.user) // "bramand"

Modern Cryptography Suite: AES-256-GCM, Ed25519 & JWT (std/crypto/advanced)

Commercial-grade authenticated symmetric encryption with 128-bit authentication tags (AES-256-GCM), high-speed elliptic curve digital signatures (Ed25519), and secure JSON Web Token (JWT) signing and verification.

import "std/crypto/advanced" as crypto

// 1. Authenticated Symmetric Encryption (AES-256-GCM)
let key = "abcdefghijklmnopqrstuvwxyz123456" // 32-byte key
let secret_msg = "Ultra confidential transaction payload"
let enc = crypto.encrypt_gcm(key, secret_msg, null, "aad-data")
let dec = crypto.decrypt_gcm(key, enc.combined, null, "aad-data")
println("Decrypted message:", str(dec))

// 2. Ed25519 Digital Signatures
let kp = crypto.keypair_ed25519()
let message = "Authorize wire transfer #9842"
let signature = crypto.sign_ed25519(kp.private_key, message)
let is_valid = crypto.verify_ed25519(kp.public_key, message, signature)
println("Ed25519 signature valid?", is_valid) // true

// 3. JSON Web Token (JWT) Verification
let payload = { "sub": "user_42", "role": "admin", "iat": 1700000000 }
let secret = "production_secure_jwt_secret_key"
let token = crypto.sign_jwt(payload, secret, "HS256")
let result = crypto.verify_jwt(token, secret, "HS256")
println("JWT verified?", result.valid, "Role:", result.payload.role)

Terminal Unicode & Braille Plotting Engine (std/tui/plot)

Scientific, financial, and machine learning visualization library rendering high-resolution 2x4 Braille dot-matrix curves, scatter plots, and Unicode box bar charts directly inside any terminal without GUI dependencies.

import "std/tui/plot" as plot

// Plot a mathematical function curve using high-resolution Braille dots
let parabola = plot.plot_function(fn(x) { return x * x; }, -2.0, 2.0, "Parabola", 40, 10)
println(parabola)

// Render a clean Unicode horizontal bar chart
let categories = ["Compiler", "VM Exec", "Stdlib", "Crypto"]
let timings_ms = [4.2, 12.8, 8.5, 3.1]
let bar_chart = plot.plot_bar(categories, timings_ms, "Hotspot Profile", 25)
println(bar_chart)

Date, Time & Calendar Engine (std/datetime)

A high-performance date, time, duration, and calendar arithmetic suite. Supports ISO 8601, RFC 3339, Unix epoch millisecond timestamps, UTC conversions, leap year verification, calendar offsets, and custom format conversions (YYYY-MM-DD HH:mm:ss).

1. Functions Reference

import "std/datetime" as dt

// Construct calendar date
let d = dt.new(2026, 11, 9, 14, 30, 0)
println("ISO 8601:", d.to_iso())        // 2026-11-09T14:30:00Z
println("Weekday:", d["weekday"])        // "Monday"
println("Is leap year:", d.is_leap_year()) // false

// Calendar arithmetic
let next_week = d.add_days(7)
println("Next week:", next_week.to_iso())

// Duration diff calculations
let span = next_week.diff(d)
println("Days span:", span["days"])      // 7

File System & Path Engine (std/fs & std/path)

Production filesystem engine supporting recursive directory walking with filters, pattern matching (glob), temporary file creation, directory tree hierarchies, file metadata (stat), and canonical path normalization.

1. std/path API Reference

2. std/fs API Reference

import "std/path" as path
import "std/fs" as fs

let full_path = path.join(["/var", "log", "app.log"])
println("Base:", path.base(full_path)) // "app.log"
println("Ext:", path.ext(full_path))   // ".log"
println("Dir:", path.dir(full_path))   // "/var/log"

// Create and inspect a temporary file
let tmp = fs.temp_file("bench", ".txt")
fs.write_text(tmp["path"], "performance payload")

let st = fs.stat(tmp["path"])
println("File size in bytes:", st["size"])
println("Modified timestamp:", st["mod_time"])

fs.remove(tmp["path"])

Universal Data Encoding Suite (std/encoding)

Universal serialization suite featuring RFC 4180 compliant CSV parser and formatter, Hexadecimal encoders/decoders, URL query parameter builders/parsers, and Base64 wrapping utilities.

1. Functions Reference

import "std/encoding" as enc

// Hex Encode / Decode
let hex = enc.hex_encode("BramandScript 2026")
println("Hex:", hex)
println("Decoded:", enc.hex_decode(hex))

// URL Query Builder & Parser
let query = enc.url_build_query({ "search": "actor model", "page": 1 })
println("Encoded query:", query) // "page=1&search=actor+model"

// CSV Formatting & Parsing with Headers
let data = [
    { "id": "1", "name": "Alice", "role": "Architect" },
    { "id": "2", "name": "Bob", "role": "Lead" }
]
let csv_text = enc.csv_stringify(data)
let parsed = enc.csv_parse(csv_text, ",", true)
println("First record role:", parsed[0]["role"]) // "Architect"

Monadic Safety (Result, Option & ?)

BramandScript introduces first-class algebraic container types (Result and Option) combined with the postfix try-propagation operator (?) to eliminate runtime panics, uncaught exceptions, and defensive boilerplate checks.

1. Result Monad (Ok(v) & Err(e))

2. Option Monad (Some(v) & None())

3. Postfix Try-Propagation Operator (?)

Appending ? to any expression evaluating to a Result or Option automatically unwraps the successful value, or performs an early-return from the enclosing function unwinding the error or none value directly to the caller.

let parse_integer = fn(s) {
    if len(s) == 0 {
        return Err("empty string")
    }
    return Ok(int(s))
}

let calculate_average = fn(str_a, str_b) {
    let a = parse_integer(str_a)? // Unwraps Ok, or early-returns Err!
    let b = parse_integer(str_b)? // Unwraps Ok, or early-returns Err!
    return Ok((a + b) / 2)
}

let success = calculate_average("40", "60")
println("Result:", success.unwrap()) // 50

let failure = calculate_average("", "60")
println("Failure caught:", failure.is_err()) // true
println("Fallback:", failure.unwrap_or(0))   // 0

Low-Level Sockets & Networking (std/net)

The std/net module provides low-level duplex streaming TCP sockets, high-throughput UDP packet sockets, and TLS encryption primitives implemented directly in the Go standard library with zero external dependencies.

1. Functions & Factory Methods

2. Socket Instance Methods

import "std/net" as net;

let server = net.create_server(fn(sock) {
    sock.set_timeout(5000);
    let line = sock.read_line();
    sock.write("ECHO: " + trim(line) + "\n");
    sock.close();
});
server.listen(9001);

let client = net.connect("127.0.0.1", 9001);
client.write("Hello Bramand!\n");
let reply = client.read_line();
println("Received:", trim(reply));
client.close();
server.close();

Pure BramandScript HTTP/1.1 Engine (std/http)

A 100% self-hosted RFC 7230 HTTP/1.1 engine written entirely in BramandScript on top of raw TCP sockets. Includes an RFC 7230 wire parser, server with Request and Response abstractions, client convenience helpers, Radix Trie router, and middleware.

1. HTTP Client & Server API

import "std/http" as http;

let router = http.create_router();

router.get("/api/items/:id", fn(req, res) {
    let id = req.params["id"];
    res.json({ "id": id, "name": "Quantum CPU", "price": 4999 });
});

router.post("/api/items", fn(req, res) {
    let data = req.json();
    res.status(201).json({ "created": data, "id": 101 });
});

let server = http.create_server(router);
server.listen(8080);

Pure BramandScript WebSocket Engine (std/ws)

A 100% self-hosted RFC 6455 WebSocket engine written entirely in BramandScript atop raw TCP sockets. Includes handshake key derivation (Sec-WebSocket-Accept with SHA-1 and Base64), binary frame encoder/decoder with FIN bit, opcode bitfields, 4-byte client XOR payload masking, 7-bit/16-bit/64-bit payload lengths, and room broadcast.

1. WebSocket Server & Client API

import "std/ws" as ws;

let server = ws.create_server(8081, fn(conn) {
    conn.on("message", fn(msg) {
        conn.send("ACK: " + msg);
        server.broadcast("ANNOUNCE: " + msg);
    });
});

let client = ws.connect("ws://127.0.0.1:8081/feed", fn(c) {
    c.send("TELEMETRY_ONLINE");
});

client.on("message", fn(msg) {
    println("Received:", msg);
});

Pure BramandScript UDP DNS Resolver (std/dns)

A 100% self-hosted RFC 1035 UDP DNS packet codec and resolver engine. Directly formats binary queries, parses 12-byte headers, resolves QNAME labels with 0xC0 compression pointers, and manages an in-memory TTL cache.

1. Functions Reference

import "std/dns" as dns;

// Resolve domain via UDP query datagram
let ips = dns.resolve("bramand.org", dns.TYPE_A, "8.8.8.8:53");
println("Resolved IPs:", ips);

// Secondary lookup resolves instantly from in-memory TTL cache (0ms latency)
let primary_ip = dns.lookup("bramand.org");
println("Primary IP:", primary_ip);

Pure BramandScript HTTPS Engine (std/https)

Combines raw TLS dialer sockets (tls_dial) with the pure BMD HTTP wire parser and client pipeline. Enforces Server Name Indication (SNI) verification and TLS certificate validation by default.

1. Functions Reference

import "std/https" as https;

let res = https.get("https://api.github.com/zen", {
    "headers": { "User-Agent": "BramandScript/1.0" }
});
println("HTTPS Status:", res["status"], "Body:", res.text());

Process IPC & Operating System (std/process & std/os)

The std/process and std/os modules deliver native child process lifecycle management, standard I/O streaming pipes, Unix IPC pipelines, exit code verification, and host system introspection.

1. Subprocess & Stream Pipeline API (std/process)

2. OS System Introspection (std/os)

import "std/process" as process;

// IPC Unix pipeline: echo -> tr -> read
let p1 = process.spawn("echo", ["hello world"]);
let p2 = process.spawn("tr", ["a-z", "A-Z"]);
p1.pipe(p2);

let output = p2.stdout.read_all();
p1.wait();
p2.wait();
println("Transformed output:", trim(output)); // "HELLO WORLD"

Byte Buffers & Binary Stream Piping (std/buffer & std/io)

The std/buffer and std/io modules deliver high-performance byte buffer manipulation, Big-Endian / Little-Endian numeric serialization, IEEE 754 float codecs, and streaming pipe combinators with zero data loss.

1. Buffer Class & Static Factory (std/buffer)

2. Stream Combinators (std/io)

import "std/buffer" as buffer;
import "std/io" as io;

let Buffer = buffer.Buffer;

// 1. Pack binary header & float payload
let buf = Buffer.alloc(16);
buf.write_uint32_be(0xCAFEBABE, 0);
buf.write_uint32_be(1024, 4);
buf.write_double_be(3.14159265, 8);

// 2. Stream piping through BufferReader -> BufferWriter
let reader = io.BufferReader(buf);
let writer = io.BufferWriter();
let total = io.pipe(reader, writer, { "chunk_size": 4 });

let cloned = writer.to_buffer();
assert_eq(Buffer.compare(buf, cloned), 0);
println("Piped bytes with 100% integrity:", total);

Standard Builtin Functions Reference

All 180+ builtin functions are implemented natively in Go without external dependencies. They are indexed in compiler/builtins.go and executed via opcode OpGetBuiltin with zero overhead. Not a single builtin is omitted from this exhaustive reference:

1. Console Output & Standard I/O

2. Type Conversion & Introspection

3. Arrays, Hashes & Collections

4. String Processing Primitives

5. Concurrency & Synchronization

6. Filesystem & Process Environment

7. Clock, Epoch & ISO Timers

8. Terminal Raw I/O & Keystrokes

9. Raw Byte Buffers, Binary I/O & Runes

10. Dynamic Metaprogramming & Structural Interfaces

11. Arbitrary-Precision Big Numbers

12. Linear Algebra & Geometry

13. Mathematical & Transcendental Functions

14. Statistical Calculations

15. Formats & Serialization (JSON, CSV, Base64)

16. Cryptography & CSPRNG

17. Sockets, HTTP & WebSockets

18. AI Integration & Vector Similarity Search

19. Test Runner, Benchmarking & Diagnostics

20. Compression & Archiving Engine (std/compress)

21. Binary Serialization & Struct Packing (std/binary/pack)

22. Modern Cryptography Suite (std/crypto/advanced)

23. Compiler & VM Iteration Helpers

The following four builtins are internal execution primitives compiled into bytecode by the Pratt parser to power zero-allocation, high-throughput for-in loop iterations over Arrays, Hashes, Strings, and raw Bytes:

24. Native Reactive Event Streams (std/stream)

High-performance push/pull reactive stream pipelines with backpressure flow control signals, windowed operators, and multiplexing combinators:

25. In-Memory Relational SQL Suite (std/sql)

ANSI SQL parser, query planner, and relational query engine executing joins, filters, and aggregations across in-memory datasets and DataFrames:

26. Local AI Vector Metrics & Spatial Index (std/ai)

Pure Go stdlib hardware floating-point accelerated metrics, K-Nearest Neighbors (KNN) spatial index, and RAG document chunking pipeline: