compiler 0.0.2-preview.1
The Zena self-hosted compiler
compiler#
The Zena compiler, written in Zena. It parses, type-checks, and compiles Zena source code to WebAssembly (Wasm GC) and WebAssembly Text (WAT).
Usage#
Parsing a Single File#
Use compiler/parser to parse Zena source text into an AST (Module):
import { parse } from 'compiler/parser';
let ast = parse('export let answer = 42;', 'example.zena');
Loading and Checking a Program#
Use compiler (createCompiler and checkCompilation) with a CompilerHost to resolve imports across a module graph and type-check a program:
import {
createCompiler, checkCompilation, buildStdlibConfig
} from 'compiler';
import { FsCompilerHost } from 'compiler/fs-host';
let stdlibRoot = '/stdlib';
let host = new FsCompilerHost(stdlibRoot);
let packages = buildStdlibConfig(stdlibRoot, 'host');
let compiler = createCompiler(host, {
stdlibRoot,
packages,
});
let result = await compiler.compile({
entry: '/workspace/main.zena',
target: 'host',
});
let checked = checkCompilation(result);
Compiling a File to WebAssembly#
Use compiler/compile-file to compile an entry file on disk to a .wasm or .wat output file:
import { compileFile } from 'compiler/compile-file';
let ok = await compileFile({
entry: 'src/main.zena',
outPath: 'out/main.wasm',
stdlibRoot: '/stdlib',
});
Libraries#
compiler/compiler/compiler— compiler entry point (Compiler,createCompiler,checkCompilation,ProgramCheckResult)compiler/compile-file— end-to-end file compilation (compileFile,CompileFileOptions)compiler/tokenizer— lexer and token definitions (tokenize,Token,TokenType)compiler/parser— recursive-descent parser (parse,Parser)compiler/ast— AST node definitions (Node,Module,Statement,Expression,TypeAnnotation)compiler/visitor— AST traversal helpers (walk,Visitor)compiler/scope— lexical scope and symbol resolution (ScopeBuilder,ScopeResult,Symbol)compiler/checker— static type checker (checkModule,CheckResult)compiler/semantic-model— semantic queries over a checked module (SemanticModel)compiler/types— compiler type representations (Type,ClassType,FunctionType,typeToString)compiler/diagnostics— compiler diagnostics and source spans (Diagnostic,DiagnosticCode,DiagnosticSeverity,SourceSpan)compiler/package-manifest—zena-package.jsonmanifest and workspace loader (loadWorkspace,loadPackageMap)compiler/module-resolver— package and relative module specifier resolution (ModuleResolver,PackageConfig)compiler/library-loader— module graph loader (LibraryLoader,CompilerHost,SourceFile)compiler/codegen/binary-generator— WebAssembly GC binary emitter (BinaryGenerator)compiler/codegen/wat-generator— WebAssembly Text (WAT) emitter (WatGenerator)
License#
MIT
8.3 KiB
Raw
import { Set, HashMap, HashSet } from 'zena:collections';
import { Type } from '../types.zena';
import { SymbolId } from '../scope/symbol.zena';
import { Node, SourceLocation } from '../ast.zena';
/**
* The checker's control-flow graph (docs/design/ownership.md, "The checker
* flow graph").
*
* Flow nodes are built by the checker as it walks a function body, in the
* style of TypeScript's binder: each node points backward at its
* antecedents, so a query walks from a use toward the function entry. The
* graph is a side structure — it never replaces the AST, and it exists
* per checked body, not per instantiation, which is what lets it serve
* checking of code RTA later drops.
*
* The first consumer is narrowing validity: a narrowing records the flow
* node where its guard established it, and a read walks backward from the
* reference to that node, failing if some path crosses an assignment that
* no longer satisfies the narrowed type. Move checking builds on the same
* nodes.
*
* Nodes compare by `id`, never by `==`: joins make the graph cyclic
* through loop back edges, so structural equality must not be reachable.
*/
export sealed class FlowNode {
case FlowStart, FlowAssign, FlowMove, FlowNarrowings, FlowJoin,
FlowUnreachable, FlowSuspend
/** Unique within one CheckerContext; minted by the checker. */
var id: i32 = 0;
}
/**
* Entry of a function body (or of the module's top level). `enclosing`
* is the flow at the closure's creation site in the enclosing body, so
* a walk can keep going for a captured binding — a closure sees the
* narrowings that held where it was written.
*/
export final class FlowStart extends FlowNode {
var enclosing: FlowNode | null = null;
/**
* Whether this body shares `this` with its enclosing body (a closure
* inside a method does; a method, accessor or top-level body starts a
* fresh `this`). A `this`-rooted path walk stops where `this` stops.
*/
var sharesThis: boolean = false;
}
/**
* Follows code that cannot be reached — after `return`, `throw`,
* `break`, `continue`. Joins drop unreachable antecedents.
*/
export final class FlowUnreachable extends FlowNode {}
/**
* An assignment to a local binding. `assignedType` is the checked type of
* the stored value; null means the type was unavailable, which a validity
* walk must treat as incompatible.
*/
export final class FlowAssign extends FlowNode {
antecedent: FlowNode;
symbolId: SymbolId;
assignedType: Type | null;
/**
* Set for a store into a member path a dispose moved out (`this.field`),
* which revives it; such a node carries `noSymbolId`, so the symbol
* walks pass through it. Empty for binding assignments.
*/
var pathKey: String = "";
new(this.antecedent, this.symbolId, this.assignedType) : super();
}
/**
* A move of an owned binding: passed to an `Own` parameter, moved into
* another binding, or consumed by a `this: Own<this>` method. The binding
* is dead on every path through this node until a reassignment revives
* it. `loc` is where the move happened, for the use-after-move message
* and for the loop back-edge report.
*/
export final class FlowMove extends FlowNode {
antecedent: FlowNode;
symbolId: SymbolId;
name: String;
loc: SourceLocation | null;
/**
* Set for a move of a member path (`this.field` in a consuming
* method) instead of a binding; such a node carries `noSymbolId`, so
* the symbol walks pass through it. Empty for binding moves.
*/
var pathKey: String = "";
/**
* Set for the mark an `isFirstClass<T>()` branch leaves on each `T`
* value at its entry: on that path `T` is first-class, so the value
* counts as consumed (the required-consumption walk stops here), yet
* it is not dead, and a later use is no use after move.
*/
var consumesOnly: boolean = false;
new(this.antecedent, this.symbolId, this.name, this.loc) : super();
}
/**
* The narrowings a condition (or match pattern) establishes on the path
* it guards: what the checker's condition engine computed for one
* branch, attached to that branch's entry. A backward walk takes the
* nearest node mentioning its binding or path — composition of nested
* guards is already baked in, because the engine computes each map from
* the types that held where the condition sits.
*/
export final class FlowNarrowings extends FlowNode {
antecedent: FlowNode;
bindings: HashMap<SymbolId, Type>;
paths: HashMap<String, Type>;
new(this.antecedent, this.bindings, this.paths) : super();
}
/**
* A merge point: the end of an `if`, a loop header, a `match` join, the
* short-circuit join of `&&`/`||`/`??`, or a `catch` entry (whose
* antecedents include every assignment in the protected body). Loop
* headers gain their back edge after the body is walked.
*/
export final class FlowJoin extends FlowNode {
antecedents = new Array<FlowNode>();
/** Unreachable antecedents carry no paths, so they are not recorded. */
add(node: FlowNode): void {
if (node is FlowUnreachable) { return; }
this.antecedents.push(node);
}
}
/**
* A suspension point: an `await` or a `yield`. Transparent to
* narrowing and to move liveness; a second-class borrow read on a path
* through one has outlived the extent it was borrowed from —
* ownership.md §"Borrows and suspension".
*/
export final class FlowSuspend extends FlowNode {
antecedent: FlowNode;
new(this.antecedent) : super();
}
/**
* One read of a second-class borrow inside a suspending body, checked
* when the body's flow graph is complete (loop back edges included):
* a suspension on any backward path from the read to the binding's
* birth is the error.
*/
export final class BorrowUseRec {
symbolId: SymbolId;
name: String;
node: FlowNode;
exprNodeId: i32;
loc: SourceLocation | null;
new(this.symbolId, this.name, this.node, this.exprNodeId, this.loc);
}
/**
* One if/else whose arms may need compensating drops (ownership.md
* §"The branch-join rule"): recorded while checking, decided when the
* enclosing scope closes and every capture and escape is known. The
* arm-end flow nodes let the decision ask, per binding, whether a move
* lies on one arm and not the other.
*/
export final class PendingEdgeIf {
ifNode: Node;
preBranch: FlowNode;
trueEnd: FlowNode;
falseEnd: FlowNode;
trueReachable: boolean;
falseReachable: boolean;
new(this.ifNode, this.preBranch, this.trueEnd, this.falseEnd,
this.trueReachable, this.falseReachable);
}
/**
* One match whose arms may need compensating drops: the N-ary sibling
* of PendingEdgeIf. Arm ends align with the match's cases by index; a
* diverged arm's end is FlowUnreachable and needs no compensation.
*/
export final class PendingEdgeMatch {
matchNode: Node;
preBranch: FlowNode;
armEnds: GrowableArray<FlowNode>;
new(this.matchNode, this.preBranch, this.armEnds);
}
/**
* An early exit — a `return`, `break` or `continue` — recorded for the
* same decision: the flow where control leaves, and the depth of the
* innermost own scope it leaves (a `return` leaves the body's, a `break`
* or `continue` those inside its loop). A binding released at none of
* its scope's ends, because some path moves it, is released here when
* it is still live (ownership.md §"The branch-join rule").
*/
export final class PendingExit {
exitNode: Node;
flow: FlowNode;
fromDepth: i32;
new(this.exitNode, this.flow, this.fromDepth);
}
/**
* The checker's per-body flow state, saved and restored around nested
* function bodies the way return/yield context is: a closure checked in
* the middle of an enclosing body gets its own FlowStart and its own
* loop and exception stacks.
*/
export final class FlowBodyState {
current: FlowNode;
start: FlowStart;
loopHeads: GrowableArray<FlowJoin>;
loopExits: GrowableArray<FlowJoin>;
exceptionTargets: GrowableArray<FlowJoin>;
loopMoves: GrowableArray<GrowableArray<FlowMove>>;
loopDeclared: GrowableArray<HashSet<i32>>;
pendingEdgeIfs: GrowableArray<PendingEdgeIf>;
var borrowUses = new Array<BorrowUseRec>();
var pendingEdgeMatches = new Array<PendingEdgeMatch>();
var pendingExits = new Array<PendingExit>();
var bodyExits = new Array<FlowNode>();
var bodyPathMoves = new Array<FlowMove>();
var scopedBodyFloor: i32 = 0;
var scopedLoopFloorCount: i32 = 0;
new(this.current, this.start, this.loopHeads, this.loopExits,
this.exceptionTargets, this.loopMoves, this.loopDeclared,
this.pendingEdgeIfs);
}
- zena-lang:wit-parser wit-parser.zena-lang.pkg.zena-lang.dev ~0.0.1-preview.1
| Version | Published | Dependencies | Approved by |
|---|---|---|---|
| 0.0.2-preview.1 | 2026-11-19 |
|
|