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
11.9 KiB
Raw
// The standard library declarations the compiler has built-in knowledge of,
// and where each one lives.
//
// The compiler cannot recognize these by name alone. A program may declare
// its own `Array`, `Error` or `Iterator`, and treating one of those as the
// standard library's applies stdlib lowering to a layout that does not
// match it. Every check goes through `isWellKnown`, which compares two
// things exactly: the declaration's name, and the library that owns the
// module declaring it.
//
// Keying on the library rather than the file means a library may move its
// declarations between its own files without touching this table. Moving a
// declaration to a different library does change its entry, and because the
// checked-in bootstrap carries the old one, such a move takes two steps:
// add the new library here, reseed, then move the declaration.
//
// To give the compiler knowledge of another declaration, add a variant and
// a row to `buildLocations`. Those are the only two places a well-known
// declaration is written down.
import { stdlibLibraryOf } from './stdlib-manifest.zena';
import { HashMap } from 'zena:collections';
/** A standard library declaration the compiler treats specially. */
export enum WellKnown {
/** `String`, which backs string literals and concatenation. */
StringClass,
/** `TemplateStringsArray`, the first argument of a tagged template. */
TemplateStringsArrayClass,
/** `Box<T>`, which a tagged template's primitive interpolation is
* wrapped in when the tag's value type accepts the box. */
BoxClass,
/** `Error`, the type `throw` and `catch` trade in. */
ErrorClass,
/** `Iterator<T>` and `Iterable<T>`, the `for`-in protocol. */
IteratorInterface,
IterableInterface,
/** `AsyncIterator<T>` and `AsyncIterable<T>`, what a `for await` adds
* to it (docs/design/async-iteration.md). */
AsyncIteratorInterface,
AsyncIterableInterface,
/** The array types, which back array literals and indexed `for`-in. */
ArrayInterface,
MutableArrayInterface,
FixedArrayClass,
ImmutableArrayClass,
GrowableArrayClass,
/** The ranges a range literal builds: `Range` is their base, and
* `BoundedRange` and `FromRange` are the two a `for`-in compiles to a
* counting loop. */
RangeClass,
BoundedRangeClass,
FromRangeClass,
ToRangeClass,
FullRangeClass,
/** `StringIndex`, the other type a range literal's bounds may have. */
StringIndexAlias,
/** `HashMap<K, V>`, which a map literal builds. */
HashMapClass,
/** `Future<T>` and `CancelScope`, which `async`/`await` lower onto. */
FutureClass,
CancelScopeClass,
/** `TaskGroup`, whose `cancel` is the whole-program cancellation
* gate's evidence: the one call that marks a scope cancelled. */
TaskGroupClass,
/** `Awaited<T>`, the type operator an `await`'s result is read through. */
AwaitedAlias,
/** `Hashable`, which a generic's `Hashable` bound is satisfied against
* — including by primitives, which implement it structurally. */
HashableInterface,
/** `Equatable`, satisfied the same way as `Hashable`: by primitives
* structurally, and by case classes that derive their equality. */
EquatableInterface,
/** `Stringable`, which opts a class into custom string conversion
* via `[Stringable.toString]()`. */
StringableInterface,
/** `Resource`, the bound `resource class` and the ownership handles
* are checked against. */
ResourceClass,
/** The three ownership handles, which are distinct type aliases. */
OwnAlias,
BorrowAlias,
UnmanagedAlias,
/** `Scoped<T>`, the no-duplicate no-escape corner (not a handle). */
ScopedAlias,
/** `Option<T>`, what a Pending iteration step's future settles with. */
OptionAlias,
/** `BigInt`, which backs `n`-suffixed and contextually typed integer literals. */
BigIntClass,
}
/**
* Where a well-known declaration lives: its local name, the library that
* owns it, and — only while it is being moved between libraries — the
* library it is moving to.
*
* Both libraries are exact names compared with `==`; `movingTo` is not a
* relaxation of the match, it is a second exact answer that is true for
* the length of a migration. It exists because the checked-in bootstrap
* carries this table: a declaration cannot move to a library the
* bootstrap has never heard of, so the new location has to be accepted
* for one reseed before the file moves, and dropped after the next one.
* See docs/design/stdlib-organization.md, Phase 1.
*/
final class Location {
library: String;
name: String;
movingTo: String | null;
new(this.library, this.name, this.movingTo = null);
}
var locations: HashMap<i32, Location> | null = null;
var ordered: GrowableArray<WellKnown> | null = null;
function buildLocations() {
let t = new Map<i32, Location>();
let order = new Array<WellKnown>();
let add = (w: WellKnown, library: String, name: String) => {
t[w as i32] = new Location(library, name);
order.push(w);
};
/** Registers a declaration that is mid-move to another library. */
let moving = (w: WellKnown, library: String, name: String,
movingTo: String) => {
t[w as i32] = new Location(library, name, movingTo);
order.push(w);
};
add(WellKnown.StringClass, 'core', 'String');
add(WellKnown.TemplateStringsArrayClass, 'core', 'TemplateStringsArray');
add(WellKnown.BoxClass, 'core', 'Box');
add(WellKnown.ErrorClass, 'core', 'Error');
add(WellKnown.IteratorInterface, 'core', 'Iterator');
add(WellKnown.IterableInterface, 'core', 'Iterable');
add(WellKnown.ArrayInterface, 'core', 'Array');
add(WellKnown.MutableArrayInterface, 'core', 'MutableArray');
add(WellKnown.FixedArrayClass, 'core', 'FixedArray');
add(WellKnown.ImmutableArrayClass, 'core', 'ImmutableArray');
add(WellKnown.GrowableArrayClass, 'core', 'GrowableArray');
add(WellKnown.RangeClass, 'core', 'Range');
add(WellKnown.BoundedRangeClass, 'core', 'BoundedRange');
add(WellKnown.FromRangeClass, 'core', 'FromRange');
add(WellKnown.ToRangeClass, 'core', 'ToRange');
add(WellKnown.FullRangeClass, 'core', 'FullRange');
add(WellKnown.StringIndexAlias, 'core', 'StringIndex');
add(WellKnown.HashMapClass, 'collections', 'HashMap');
// Declared in async/future.zena, a private file of zena:async. Keying on
// the library is what lets that be true without a prefix match.
add(WellKnown.FutureClass, 'async', 'Future');
add(WellKnown.CancelScopeClass, 'async', 'CancelScope');
add(WellKnown.TaskGroupClass, 'async', 'TaskGroup');
add(WellKnown.AwaitedAlias, 'async', 'Awaited');
add(WellKnown.HashableInterface, 'core', 'Hashable');
add(WellKnown.EquatableInterface, 'core', 'Equatable');
add(WellKnown.StringableInterface, 'core', 'Stringable');
add(WellKnown.ResourceClass, 'core', 'Resource');
add(WellKnown.OwnAlias, 'core', 'Own');
add(WellKnown.BorrowAlias, 'core', 'Borrow');
add(WellKnown.UnmanagedAlias, 'core', 'Unmanaged');
add(WellKnown.ScopedAlias, 'core', 'Scoped');
add(WellKnown.OptionAlias, 'core', 'Option');
add(WellKnown.AsyncIteratorInterface, 'async', 'AsyncIterator');
add(WellKnown.AsyncIterableInterface, 'async', 'AsyncIterable');
add(WellKnown.BigIntClass, 'bigint', 'BigInt');
locations = t;
ordered = order;
return t;
}
/**
* Every well-known declaration, in registration order. A caller that has to
* visit them all — filling the checker's table as each library is checked —
* iterates this instead of repeating the list.
*/
export function allWellKnown(): GrowableArray<WellKnown> {
if (ordered == null) {
buildLocations();
}
return ordered as GrowableArray<WellKnown>;
}
function locationOf(w: WellKnown): Location {
let t = if (locations != null) {
locations as HashMap<i32, Location>
} else {
buildLocations()
};
if (let (true, loc) = t.get(w as i32)) {
return loc;
}
// Unreachable unless a variant was added without a row.
throw new Error('No location registered for well-known declaration ' +
i32ToString(w as i32));
}
/** The library `w` is declared in. */
export function wellKnownLibrary(w: WellKnown): String {
return locationOf(w).library;
}
/** The name `w` is declared under, inside its library. */
export function wellKnownName(w: WellKnown): String {
return locationOf(w).name;
}
/**
* The standard library symbols the compiler names itself, and the fixed
* member key each one keys.
*
* A member keyed by a symbol is normally keyed by that symbol's identity,
* minted per compilation (`:act_87`), so two same-named symbols key two
* members. Codegen cannot resolve anything, though, so the members it
* calls on its own — the release action it runs when a resource is
* dropped, the iterator a `for`-in asks for, the async runtime's hooks —
* have to be nameable as constants. Each row is one such symbol: the
* library that declares it, the type that declares it when it is a
* `static symbol` (empty for a top-level `symbol`), and its name.
*
* Matching is exact on all three, so a program's own `symbol complete` or
* `interface Disposable` keys by identity like any other symbol.
*/
final class ProtocolSymbol {
library: String;
owner: String;
name: String;
new(this.library, this.owner, this.name);
}
var protocolSymbols: GrowableArray<ProtocolSymbol> | null = null;
function buildProtocolSymbols() {
let t = new Array<ProtocolSymbol>();
let add = (library: String, owner: String, name: String) => {
t.push(new ProtocolSymbol(library, owner, name));
};
// Dropping a resource runs its release action.
add('core', 'Disposable', 'dispose');
// Custom string conversion for template literals and `toString()`.
add('core', 'Stringable', 'toString');
// A `for`-in over anything but an array asks for an iterator; a
// `for await` over an asynchronous iterable asks its own symbol.
add('core', 'Iterable', 'iterator');
add('async', 'AsyncIterable', 'asyncIterator');
// The async runtime's hooks, which `async`/`await` lower onto.
add('async', '', 'registerTask');
add('async', '', 'install');
add('async', '', 'checkpoint');
add('async', '', 'shieldScope');
add('async', '', 'childScope');
add('async', '', 'cancelScope');
add('async', '', 'subscribe');
add('async', '', 'valueOrThrow');
add('async', '', 'complete');
add('async', '', 'fail');
add('async', '', 'adoptFrom');
add('async', '', 'cancelComplete');
// An implicit drop of a future of an owner releases through it.
add('async', '', 'release');
protocolSymbols = t;
return t;
}
/**
* The fixed member key of the symbol `name` declared in `modulePath` —
* on the type `owner`, or at the top level when `owner` is empty — when
* it is one the compiler names itself; null for every other symbol.
*/
export function protocolSymbolKey(
owner: String, name: String, modulePath: String): String | null {
let library = stdlibLibraryOf(modulePath);
if (library == null) {
return null;
}
let rows = if (protocolSymbols != null) {
protocolSymbols as GrowableArray<ProtocolSymbol>
} else {
buildProtocolSymbols()
};
for (let row in rows) {
if (row.name == name && row.owner == owner &&
row.library == (library as String)) {
return ":" + name;
}
}
return null;
}
/**
* Whether a declaration named `name` in the module `modulePath` is the
* well-known declaration `w`.
*
* `modulePath` is the canonical id of the declaring module — `sourcePath`
* on a class, interface or mixin type, `declaringModule` on a type alias.
* Both halves are compared exactly, and a module outside the standard
* library belongs to no library and so matches nothing.
*
* The name is tested first because it rules out almost every call without
* touching the manifest.
*/
export function isWellKnown(w: WellKnown, name: String,
modulePath: String): boolean {
let loc = locationOf(w);
if (name != loc.name) {
return false;
}
let library = stdlibLibraryOf(modulePath);
if (library == null) {
return false;
}
let owner = library as String;
if (owner == loc.library) {
return true;
}
let movingTo = loc.movingTo;
return movingTo != null && owner == (movingTo as String);
}
- 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 |
|
|