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
7.0 KiB
Raw
import {
Module, VariableDeclaration, FunctionDeclaration, MixinDeclaration, DeclareFunction, IdentifierPattern,
} from './ast.zena';
import { SemanticModel, ModelIndex } from './semantic-model.zena';
import { Symbol } from './scope/symbol.zena';
import { stdlibModuleNameForEntryPath } from './stdlib-manifest.zena';
export type CompilationUnit = {
ast: Module,
model: SemanticModel
};
/**
* An immutable snapshot of a single compilation state.
* Encapsulates the compilation units and entry point.
*/
export final class Program {
// This array maintains topological ordering guarantees from the compiler
// pipeline, which is necessary for sequential WebAssembly code emission.
// Although a tree walk (DFS) over a module dependency graph could derive
// the order dynamically, doing the topological sort once up front and storing
// it prevents redundant walks during code generation.
units: GrowableArray<CompilationUnit>;
unitsByPath = new Map<String, CompilationUnit>();
entryPoint: CompilationUnit | null;
/**
* Who owns each node and binding. Not built here: it belongs to the
* check that produced these models, which is also what lets a model
* be shared by every compile in a batch without any of them writing
* to it. A `Program` over models from more than one check — which
* the compiler never builds — would see only the first's.
*/
var modelIndex = new ModelIndex();
mixinDeclarations = new Map<String, MixinDeclaration>();
exportedSymbols = new Map<String, GrowableArray<Symbol>>();
exportedFunctions = new Map<String, GrowableArray<DeclareFunction>>();
new(this.units, this.entryPoint = null) {
// Adopted from the check, never built here. The empty index the
// field initializer supplies stands in only for a `Program` over
// models that were never checked, which is a test fixture.
if (this.units.length > 0) {
let fromCheck = this.units[0].model.index;
if (fromCheck != null) {
this.modelIndex = fromCheck;
}
}
for (let u in this.units) {
this.unitsByPath[u.ast.path] = u;
if (u.ast.path.startsWith("/")) {
this.unitsByPath[u.ast.path.sliceBytes(1, u.ast.path.length)] = u;
} else {
this.unitsByPath["/" + u.ast.path] = u;
}
// A stdlib unit is keyed by its canonical id, which for a module
// with a `path` or `virtual` manifest entry is a path id
// ("zena:wasi/index.zena", "zena:console/host.zena").
// Imports name the module ("zena:wasi"), so index that
// spelling too — from the manifest, so only real entry files get a
// module name and private files get none. Deriving it from the file
// name instead produced "zena:zena:stream" for a top-level
// path id, which is why the reachability import resolver needed a
// filename-suffix search to find these at all.
if (u.ast.path.startsWith("zena:")) {
let entryPath = u.ast.path.sliceBytes(5, u.ast.path.length);
let moduleName = stdlibModuleNameForEntryPath(entryPath);
if (moduleName != null) {
this.unitsByPath["zena:" + (moduleName as String)] = u;
}
}
// Precompute mixin declarations and export maps
for (let stmt in u.ast.body) {
match (stmt) {
case MixinDeclaration as md: {
this.mixinDeclarations[`${u.ast.path}::${md.name.name}`] = md;
}
case DeclareFunction as df: {
let {name} = df.name;
let key = `${u.ast.path}::${name}`;
let arr = if (let (true, a) = this.exportedFunctions.get(key)) {
a
} else {
let newArr = new Array<DeclareFunction>();
this.exportedFunctions[key] = newArr;
newArr
};
arr.push(df);
let sym = u.model.resolveDeclaration(df);
if (sym != null) {
let symKey = `${u.ast.path}::${name}`;
let symArr = if (let (true, sa) = this.exportedSymbols.get(symKey)) {
sa
} else {
let newArr = new Array<Symbol>();
this.exportedSymbols[symKey] = newArr;
newArr
};
symArr.push(sym);
}
}
case VariableDeclaration as vd: {
match (vd.pattern) {
case IdentifierPattern {name} as pat: {
this.#recordValueBinding(u, pat, name);
}
case _: {}
}
}
case FunctionDeclaration {name as namePat}: {
this.#recordValueBinding(u, namePat, namePat.name);
}
case _: {}
}
}
}
}
/**
* The unit this compile linked for `path`, or null.
*
* `path` is a library path as a Symbol carries it, which for a virtual
* library is the implementation its own compile resolved —
* `zena:console/host.zena`, not `zena:console`. A compile for another
* target linked a different library under that name, so a direct
* lookup would miss. Mapping the path id back to the name finds
* whichever implementation *this* compile has, which is what a shared
* check result will need: the model names the library, and the unit
* answering for it is the target's.
*
* The manifest already indexes every virtual implementation path under
* its name (`buildLibraryIndex`), so the reverse hop is a lookup
* rather than a search.
*/
unitFor(path: String): CompilationUnit | null {
if (let (true, unit) = this.unitsByPath.get(path)) {
return unit;
}
if (!path.startsWith("zena:")) {
return null;
}
let moduleName = stdlibModuleNameForEntryPath(
path.sliceBytes(5, path.length));
if (moduleName == null) {
return null;
}
return this.unitsByPath.get(`zena:${moduleName}`) ?? null;
}
/**
* Record a module-level value binding (a `let`/`var` name or a
* `function` declaration's name) under both its file path key and, for
* stdlib modules, its `zena:<name>` key.
*/
#recordValueBinding(u: CompilationUnit, pat: IdentifierPattern, name: String): void {
let sym = u.model.resolveDeclaration(pat);
if (sym == null) { return; }
let key = `${u.ast.path}::${name}`;
let arr = if (let (true, a) = this.exportedSymbols.get(key)) {
a
} else {
let newArr = new Array<Symbol>();
this.exportedSymbols[key] = newArr;
newArr
};
arr.push(sym);
var lastSlash2 = -1;
var idx2 = 0;
while (idx2 < u.ast.path.length) {
if (u.ast.path.getByteAt(idx2) == 47) { lastSlash2 = idx2; }
idx2 += 1;
}
let fileName2 = if (lastSlash2 >= 0) u.ast.path.sliceBytes(lastSlash2 + 1, u.ast.path.length) else u.ast.path;
if (fileName2.endsWith(".zena")) {
let stdName2 = fileName2.sliceBytes(0, fileName2.length - 5);
let stdKey = `zena:${stdName2}::${name}`;
let stdArr = if (let (true, sa) = this.exportedSymbols.get(stdKey)) {
sa
} else {
let newArr2 = new Array<Symbol>();
this.exportedSymbols[stdKey] = newArr2;
newArr2
};
stdArr.push(sym);
}
}
}
- 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 |
|
|