compiler 0.0.2-preview.1

The Zena self-hosted compiler

Readme Files Dependencies Versions

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.json manifest 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);
}
VersionPublishedDependenciesApproved by
0.0.2-preview.1 2026-11-19