Prism Documentation

A dialect of C with defer, orelse, and automatic zero-initialization. Drop into any codebase with CC=prism make.

Install

Linux / macOS

cc prism.c -flto -s -O3 -o prism && ./prism install

Downloads a single prism.c file, compiles it with your system compiler, and installs to /usr/local/bin/prism.

Windows (MSVC)

Open a Developer Command Prompt (or run vcvars64.bat) and build:

cl /Fe:prism.exe prism.c /O2 /D_CRT_SECURE_NO_WARNINGS /nologo

Requires Visual Studio Build Tools with the Desktop development with C++ workload.

Quick start

# Compile a file
prism foo.c -o foo

# Compile and run immediately
prism run foo.c

# See the transpiled output
prism transpile foo.c

Drop-in overlay

Prism uses a GCC-compatible interface. Any flag you'd pass to gcc or clang passes through automatically.

# Instead of:
CC=gcc make

# Use:
CC=prism make

All standard flags (-O2, -Wall, -I, -L, -l) pass through to the backend compiler unchanged. Prism consumes only its own flags.

defer

The problem: C requires manual cleanup at every exit point. Each new resource adds cleanup to every error path. Miss one and you leak.

int compile(const char *path) {
    FILE *f = fopen(path, "r");
    if (!f) return -1;

    char *src = read_file(f);
    if (!src) {
        fclose(f);
        return -1;
    }

    Token *tok = tokenize(src);
    if (!tok) {
        free(src);
        fclose(f);
        return -1;
    }

    int result = emit(ast);
    free(src);   // remember all
    fclose(f);   // in right order
    return result;
}

int compile(const char *path) {
    FILE *f = fopen(path, "r");
    if (!f) return -1;
    defer fclose(f);

    char *src = read_file(f);
    if (!src) return -1;
    defer free(src);

    Token *tok = tokenize(src);
    if (!tok) return -1;
    defer token_free(tok);

    Node *ast = parse(tok);
    if (!ast) return -1;
    defer node_free(ast);

    return emit(ast);
}

Write cleanup once. It runs on every exit — return, break, continue, goto, or reaching }. Defers execute in LIFO order (last defer runs first).

Edge cases

• Statement expressions ({ ... }) — defers fire at the inner scope, not the outer function scope
• switch fallthrough — defers don't double-fire between cases (verified by the CFG pass)
• Nested loops — break/continue unwind the correct scope's defers only
• Computed goto — goto *ptr with active defers is a hard error; defer cleanup cannot be determined for an indirect jump target

Forbidden contexts

Defer is rejected in functions that use:

• setjmp / longjmp — non-local jumps bypass cleanup
• vfork — including the (vfork)() paren-wrapped pattern
• Inline asm — assembly may jump out of the function unpredictably

Inside a defer body, these are always errors regardless of context:

• return, goto, break, continue
• GNU statement expressions ({…}) containing any of the above

Zero-init

The problem: Uninitialized reads are the #1 source of C vulnerabilities. -Wall only catches obvious cases.

int sum_positive(int *arr, int n) {
    int total; // could be anything
    for (int i = 0; i < n; i++)
        if (arr[i] > 0)
            total += arr[i];
    return total; // UB if no positives
}

// All locals start at zero:
int x;              // 0
char *ptr;          // NULL
int arr[10];        // {0, 0, ...}
struct {
    int a; float b;
} s;                // {0, 0.0}

Before code generation, Pass 1 walks the entire preprocessed token stream at all depths to build a complete symbol table of every typedef, enum constant, parameter shadow, and VLA tag. This distinguishes size_t x; (declaration → initialize) from size_t * x; (expression → don't touch).

What gets initialized

Zero-initialization only applies inside function bodies. File-scope declarations and struct/union/enum definitions are never touched.

raw

Opt out of zero-initialization for a specific variable without disabling it globally.

raw int x;              // uninitialized
raw char buf[65536];    // no memset overhead
raw struct Large data;  // skip zeroing

When to use

• Large buffers immediately overwritten (read(), recv())
• Performance-critical inner loops where zeroing is measurable
• Interfacing with APIs that fully initialize the data themselves

raw variables can be jumped over by goto safely — no initialization to bypass. Exception: raw on a VLA does not exempt it from the goto check, because jumping past a VLA bypasses implicit stack allocation regardless of initialization.

orelse

Handle failure inline — check a value and bail in one expression.

defer solved the cleanup problem. orelse solves the check-and-bail boilerplate:

FILE *f = fopen(path, "r");
if (!f) return -1;
defer fclose(f);

char *src = read_file(f);
if (!src) return -1;
defer free(src);

FILE *f =
    fopen(path, "r") orelse return -1;
defer fclose(f);

char *src =
    read_file(f) orelse return -1;
defer free(src);

orelse checks if the value is falsy (null pointer, zero). If so, the action fires and all active defers run — identical to a normal return.

Forms

Control flow examples

int *p = get_ptr() orelse return -1;
int *q = next()    orelse break;
int *r = try_it()  orelse continue;
int *s = find()    orelse goto cleanup;

Block — arbitrary code on failure

FILE *f = fopen(path, "r") orelse {
    log_error("failed to open %s", path);
    return -1;
}

Fallback value

char *name = get_name() orelse "unknown";

Works with any falsy scalar

int fd = open(path, O_RDONLY) orelse return -1;  // integer: 0 is falsy
size_t n = read_data(fd, buf) orelse break;      // 0 bytes = done

Limitations

orelse does not support struct or union values — it is a compile error:

struct Vec2 v = make_vec2() orelse return -1;  // Error

Struct pointers work fine:

struct Vec2 *p = get_vec2() orelse return -1;  // OK

Invalid contexts (compile errors): inside struct bodies, inside typeof, in ternary expressions, in for-init control parens, at file scope.

Safety enforcement

Prism's CFG verifier runs as Phase 2A — after all semantic analysis, before a single byte of output is emitted. All violations are hard errors by default.

CFG violation table

VLA skips are always hard errors because jumping past a VLA bypasses implicit stack allocation — this is undefined behavior regardless of whether the variable is initialized. raw does not exempt a VLA from this check.

// Error: goto 'skip' would skip over variable declaration 'x'
void unsafe() {
    goto skip;
    int x;
skip:
    printf("%d", x);
}

Defer in forbidden contexts

void bad() {
    jmp_buf buf;
    defer cleanup();  // Error: defer forbidden with setjmp
    if (setjmp(buf)) return;
}

_Generic compatibility

case and default inside _Generic association lists are not treated as switch cases — Prism tracks _Generic scope separately so they don't trigger spurious CFG violations.

CLI reference

Commands

Prism flags

These are consumed by Prism and not passed to the backend compiler.

All other flags are passed through to the backend compiler unchanged. User-supplied -x <lang> is respected and used as the pipe language instead of the default c.

Compiler detection

When the backend compiler basename doesn't make it obvious (e.g. cc on Termux, FreeBSD, or some Linux distros), Prism probes <CC> --version to detect clang vs GCC. This is used to avoid passing unsupported flags — for example, -fpreprocessed is clang-only.

Multi-file & passthrough

# Multiple source files
prism main.c utils.c -o app

# Mix with assembly
prism main.c boot.s -o kernel

# C++ files pass through untouched
prism main.c helper.cpp -o mixed

Passthrough extensions (not transpiled): .s, .S (assembly), .cc, .cpp, .cxx, .mm (C++), .m (Objective-C).

Error reporting

Prism emits #line directives so compiler errors point to your original source, not the transpiled output:

# You see:
main.c:42:5: error: use of undeclared identifier 'foo'

# Not:
/tmp/prism_xyz.c:1847:5: error: use of undeclared identifier 'foo'

Disable with prism -fno-line-directives src.c — useful when debugging the transpiler output directly.

Library mode

Prism can be compiled as a library for embedding in other tools. This excludes the CLI main().

cc -DPRISM_LIB_MODE -c prism.c -o prism.o

API

PrismFeatures prism_defaults(void);
PrismResult   prism_transpile_file(const char *path, PrismFeatures features);
void          prism_free(PrismResult *r);

PrismFeatures holds compiler path, include paths, defines, compiler flags, force-includes, and boolean feature toggles (defer, zeroinit, orelse, line_directives, warn_safety, flatten_headers).

PrismResult returns a status code and the transpiled source string:

Error recovery: In library mode, error_tok triggers longjmp instead of exit(1). All arena-allocated Pass 1 structures are reclaimed on the jump — no leaks, no dangling pointers. The context is safe to reuse for the next call.

Architecture

Prism processes C in two passes. Pass 1 performs full semantic analysis and catches all errors. Pass 2 is a near-pure code generator that reads Pass 1's immutable artifacts — no type table mutations, no speculative token walking, no mid-emit errors.

Invariants

Pass overview

Token structure

Tokens are 20 bytes on the hot path. Source location data (line_no, file_idx, loc_offset) is stored in a separate cold array to keep the hot pool cache-friendly.

Self-hosting

Prism compiles itself. The transpiled C output of stage 1 and stage 2 is identical — verified by the CI pipeline on every commit.

# Stage 0 — host compiler builds Prism from source
cc -O2 -o prism_stage0 prism.c

# Stage 1 — Prism compiles itself
./prism_stage0 prism.c -o prism_stage1

# Stage 2 — self-built Prism compiles itself again
./prism_stage1 prism.c -o prism_stage2

# Outputs are identical
diff <(./prism_stage1 transpile prism.c) <(./prism_stage2 transpile prism.c)

CI runs on: Linux x86_64, macOS x86_64/arm64, Windows (build-only), Linux arm64, Linux riscv64.

Full specification: .github/SPEC.md