reference

MUTANT LANGUAGE REFERENCE

Canonical policies, reference sheets, migration matrices, and source-of-truth documentation.

Mutant Language Reference

This document is the practical reference for Mutant language features, reserved keywords, and builtins.

Source of truth:

• Keywords: token/token.go
• Builtins registry: builtin/builtin.go
• Builtin names/constants: builtin/names.go
• Builtin teaching metadata/signatures: builtin/metadata.go

Related references:

• Capability Reference — the full, category-grouped catalog of every builtin (generated from the metadata above).
• Deep-dive guides: Secure Networking, Graph Database, Runtime Integration, Structured Data.

Language Features

Mutant supports:

• Variables and assignment with let
• Primitive literals: integers, floats, booleans, strings
• Compound literals: arrays, hashes, struct literals
• Prefix operators: ! and unary -
• Infix operators: + - * / % < > <= >= == != && ||
• Indexing and field access
• Conditionals: if / else
• Loops: for, with break and continue
• First-class functions, closures, and function calls
• Return statements (single and multi-value)
• Macros
• Type declarations: struct and enum

Multi-value returns (the `(value, err)` idiom)

Fallible builtins return two values — a result and an error — which you bind together:

let load = fn(path) {
    let data, err = fs_read(path);
    if (err) {
        putln("[error] fs_read:", err);
        return "";
    };
    return data;
};

let report = load("report.json");
putln("read", len(report), "bytes");

This convention runs through the whole standard library; the Capability Reference marks which builtins return a pair. (Idiom note: keep return inside functions rather than at the top level of a program.)

First-class functions and closures

Functions are values: you can bind them, pass them, return them, and capture free variables.

let adder = fn(n) {
    return fn(x) { return x + n; };   // closes over n
};
let add10 = adder(10);
putln(add10(5));                       // 15

Higher-order collection functions

Closures compose with the functional collection builtins map, filter, reduce, each, and sort_by:

let nums = [5, 3, 8, 1];
let doubled = map(nums, fn(x) { return x * 2; });
let big = filter(nums, fn(x) { return x > 3; });
let total = reduce(nums, fn(acc, x) { return acc + x; }, 0);
let sorted = sort_by(nums, fn(x) { return x; });

map/filter/each callbacks may also take (element, index).

Logical operators

&& (and) and || (or) combine conditions and short-circuit — the right operand is only evaluated when the left doesn't already decide the result. They return a strict boolean (using the same truthiness rules as if). Precedence: comparisons bind tighter than &&, which binds tighter than ||.

// The right side is skipped when the left decides the outcome.
let has_both = si_frac == 0 && fn_frac > 0;   // both conditions must hold
let ready = configured || force;               // either is enough

Notes

Reserved Keywords

• break
• continue
• else
• enum
• false
• fn
• for
• if
• let
• macro
• return
• struct
• true

Builtins

Total builtins currently registered: 399, across 32 capability categories.

The complete catalog — every builtin with its signature, platform support, and description — lives in the Capability Reference, which is generated directly from builtin/metadata.go so it never goes stale. The categories are indexed below; each links into that reference.

Platform support

Almost every builtin is pure-Go and cross-platform — the forensic parsers operate on captured artifacts, so they run on any host. A few live-system builtins are platform-restricted and fail honestly elsewhere; the language server warns when you call one on an unsupported OS:

• process_memory_scan — Windows, Linux
• process_modules — Windows, Linux
• reg_open — cross-platform for hive-file/JSON inputs; the live-registry path (HKLM\...) is Windows-only
• process_kill — cross-platform; on Windows only SIGKILL semantics apply

Quick Example

// Read a JSON target list, resolve each host, and print a report.
// Program logic lives in a function so `return` is never used at the top level.
let run = fn() {
    let raw, err = fs_read("targets.json");
    if (err) {
        putln("[error] fs_read:", err);
        return false;
    };

    let targets, parse_err = json_parse(raw);
    if (parse_err) {
        putln("[error] json_parse:", parse_err);
        return false;
    };

    let results = map(targets["hosts"], fn(host) {
        let addrs, resolve_err = net_resolve(host);
        if (resolve_err) {
            return { "host": host, "ok": false, "error": resolve_err };
        };
        return { "host": host, "ok": true, "addresses": addrs };
    });

    let report, stringify_err = json_stringify({ "results": results });
    if (stringify_err) {
        putln("[error] json_stringify:", stringify_err);
        return false;
    };
    putln(report);
    return true;
};

run();

Maintenance

When adding or changing language keywords or builtins, update the source definitions first (token/token.go, builtin/builtin.go, builtin/names.go, builtin/metadata.go), then regenerate CAPABILITY_REFERENCE.md from the metadata and review this file. The category counts above and in the capability reference come straight from the registry, so keep them in sync by regenerating rather than hand-editing.