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

9.2 KiB Raw
/**
 * Existential record types, `{x: i32, ...}` (docs/design/row-types.md,
 * Decisions): a record whose type names some of its fields. A value is
 * a fat pointer whose instance is the record it holds, itself a fat
 * pointer of that record's closed type, and whose table forwards to it:
 * a getter per known field, then `<underlying>` (the record held),
 * `<shapeOf>` (its shape id) and `<hash>` (its hash). `is`, `as`, `==`
 * and `hash` work from those, and only the run time knows the record's
 * shape.
 *
 * The tables are made during reachability (`WasmModule.getExistentialPack`
 * and `getForwardDispatch`); this module lowers their slots and the
 * operations on existential values.
 */
import { ValType, ValTypeI32, ValTypeRef, ValTypeStructRef, refTargetOf } from '../wasm.zena';
import {
  ExistentialForward, ForwardKind, RecordDispatchInfo, RecordForwardTable, WasmFunction,
  WasmGlobal, WasmSignature, WasmStruct, existentialCastCandidates, existentialHashName,
  existentialShapeName, existentialUnderlyingName, isValSubtype, recordShapeFieldName,
} from '../wasm-module.zena';
import { IrBuilder } from './builder.zena';
import { IrBody, IrOp, IrRefField, IrRefFunc, IrRefGlobal } from './ir.zena';
import { LoweringContext, ZirUnsupported, noValues, oneValue } from './lowering-context.zena';

function bail(cx: LoweringContext, reason: String): never {
  throw new ZirUnsupported(`${reason} @${cx.func.name ?? '?'}`);
}

/** The signature a table slot holds a reference to. */
function slotSignature(table: WasmStruct, name: String) {
  let index = table.fieldIndexByName(name);
  if (index < 0) {
    throw new ZirUnsupported(`record table slot ${name} missing`);
  }
  let target = refTargetOf(table.fields[index].type);
  if (!(target is WasmSignature)) {
    throw new ZirUnsupported(`record table slot ${name} is not a function`);
  }
  return target;
}

/**
 * Calls slot `name` of the fat pointer `fat` (of dispatch `d`) on its
 * instance, as a record getter is called.
 */
function callSlot(b: IrBuilder, d: RecordDispatchInfo, fat: i32, name: String) {
  let sig = slotSignature(d.vtableType, name);
  let vt = b.emit(IrOp.iface_vtable, new ValTypeRef(d.vtableType) as ValType, fat, -1);
  let slot = b.emit(IrOp.struct_get, new ValTypeRef(sig) as ValType, vt,
      b.addRef(new IrRefField(d.vtableType, name)));
  let held = b.emit(IrOp.iface_instance, new ValTypeStructRef() as ValType, fat, -1);
  return b.callRef(slot, oneValue(held), sig.returns[0]);
}

/** `value` cast to the fat pointer type of `d`, unless it is already one. */
function asFat(b: IrBuilder, valueVt: ValType, value: i32, d: RecordDispatchInfo) {
  let fatVt = new ValTypeRef(d.fatPtrType) as ValType;
  if (isValSubtype(valueVt, fatVt)) {
    return value;
  }
  return b.emit(IrOp.ref_cast, fatVt, value, b.internType(fatVt));
}

/**
 * The body of a forwarding slot: its parameter is a fat pointer of the
 * forward's source, and the slot reads a field through it, returns the
 * closed record it is (or holds), that record's shape id, or its hash.
 */
export function lowerExistentialForward(func: WasmFunction): IrBody {
  let forward = func.existentialForward as ExistentialForward;
  let source = forward.source;
  let b = new IrBuilder();
  let entry = b.newBlock();
  let param = b.blockParam(entry, func.signature.params[0]);
  b.switchTo(entry);
  match (forward.kind) {
    case ForwardKind.Field: {
      let fat = asFat(b, func.signature.params[0], param, source);
      b.ret(callSlot(b, source, fat, forward.field as String));
    }
    case ForwardKind.Underlying: {
      if (source.isExistential) {
        b.ret(callSlot(b, source, asFat(b, func.signature.params[0], param, source),
            existentialUnderlyingName));
      } else {
        // The instance is the closed record itself.
        b.ret(param);
      }
    }
    case ForwardKind.Shape: {
      let fat = asFat(b, func.signature.params[0], param, source);
      if (source.isExistential) {
        b.ret(callSlot(b, source, fat, existentialShapeName));
      } else {
        // Read off the record's own table, so a narrowed view answers
        // with the shape it was narrowed to.
        let vt = b.emit(IrOp.iface_vtable, new ValTypeRef(source.vtableType) as ValType, fat, -1);
        b.ret(b.emit(IrOp.struct_get, new ValTypeI32() as ValType, vt,
            b.addRef(new IrRefField(source.vtableType, recordShapeFieldName))));
      }
    }
    case ForwardKind.Hash: {
      let fat = asFat(b, func.signature.params[0], param, source);
      if (source.isExistential) {
        b.ret(callSlot(b, source, fat, existentialHashName));
      } else {
        let hashFunc = forward.hashFunc;
        if (hashFunc == null) {
          throw new ZirUnsupported('existential pack without the record hash');
        }
        b.ret(b.callFunc(b.addRef(new IrRefFunc(hashFunc as WasmFunction)), oneValue(fat),
            new ValTypeI32() as ValType));
      }
    }
  }
  return b.finish();
}

/** A fat pointer of `table`'s target type over `instance`. */
function packWith(cx: LoweringContext, target: RecordDispatchInfo, instance: i32,
    tableGlobal: WasmGlobal) {
  return cx.b.emit(IrOp.iface_pack, new ValTypeRef(target.fatPtrType) as ValType, instance,
      cx.b.addRef(new IrRefGlobal(tableGlobal)));
}

/**
 * `value` (a record of `source`'s dispatch, closed or existential)
 * packed into the existential `target`.
 */
export function packExistential(cx: LoweringContext, value: i32, source: RecordDispatchInfo,
    target: RecordDispatchInfo): i32 {
  var table: RecordForwardTable | null = null;
  for (let pack in cx.wasm.existentialPacks) {
    if (pack.source === source && pack.target === target) {
      table = pack;
    }
  }
  if (table == null) {
    bail(cx, 'existential pack not registered');
  }
  return packWith(cx, target, value, (table as RecordForwardTable).vtableGlobal);
}

/**
 * `value`, an existential of `source`, as the closed record type
 * `target`, whose fields `source` names: a projection read through it.
 */
export function projectExistential(cx: LoweringContext, value: i32, source: RecordDispatchInfo,
    target: RecordDispatchInfo): i32 {
  let table = findForward(cx, source, target);
  if (table == null) {
    bail(cx, 'existential projection not registered');
  }
  return packWith(cx, target, value, (table as RecordForwardTable).vtableGlobal);
}

function findForward(cx: LoweringContext, source: RecordDispatchInfo,
    target: RecordDispatchInfo): RecordForwardTable | null {
  for (let table in cx.wasm.forwardTables) {
    if (table.source === source && table.target === target) {
      return table;
    }
  }
  return null;
}

/** The closed record an existential of `d` holds, as a `structref`. */
export function existentialUnderlying(cx: LoweringContext, value: i32, d: RecordDispatchInfo): i32 {
  return callSlot(cx.b, d, asFat(cx.b, cx.valueTypeOf(value), value, d), existentialUnderlyingName);
}

/** The hash of the record an existential of `d` holds. */
export function existentialHash(cx: LoweringContext, value: i32, d: RecordDispatchInfo): i32 {
  return callSlot(cx.b, d, asFat(cx.b, cx.valueTypeOf(value), value, d), existentialHashName);
}

/**
 * `value is target` for an existential of `source` and a closed record
 * type `target`: the record held is exactly a `target`, so has its
 * shape id.
 */
export function existentialIs(cx: LoweringContext, value: i32, source: RecordDispatchInfo,
    target: RecordDispatchInfo): i32 {
  let i32vt = new ValTypeI32() as ValType;
  let shape = callSlot(cx.b, source, asFat(cx.b, cx.valueTypeOf(value), value, source),
      existentialShapeName);
  return cx.b.binary(IrOp.i32_eq, i32vt, shape, cx.b.constI32(target.shapeId, i32vt));
}

/**
 * `value as target` for an existential of `source` and a closed record
 * type `target` naming fields `source` does not: the record held must
 * have `target`'s fields, so the run time picks its shape from those
 * packed and projects it, and traps for any other.
 */
export function existentialAs(cx: LoweringContext, value: i32, source: RecordDispatchInfo,
    target: RecordDispatchInfo): i32 {
  let i32vt = new ValTypeI32() as ValType;
  let fat = asFat(cx.b, cx.valueTypeOf(value), value, source);
  let shape = callSlot(cx.b, source, fat, existentialShapeName);
  let held = callSlot(cx.b, source, fat, existentialUnderlyingName);
  let fatVt = new ValTypeRef(target.fatPtrType) as ValType;
  let merge = cx.b.newBlock();
  let result = cx.b.blockParam(merge, fatVt);
  for (let s in existentialCastCandidates(cx.wasm.existentialPacks, target)) {
    let isS = cx.b.binary(IrOp.i32_eq, i32vt, shape, cx.b.constI32(s.shapeId, i32vt));
    let thenB = cx.b.newBlock();
    let nextB = cx.b.newBlock();
    cx.b.brIf(isS, thenB, noValues(), nextB, noValues());
    cx.b.switchTo(thenB);
    let heldFat = cx.b.emit(IrOp.ref_cast, new ValTypeRef(s.fatPtrType) as ValType, held,
        cx.b.internType(new ValTypeRef(s.fatPtrType) as ValType));
    let converted = if (s === target) heldFat else {
      let table = findForward(cx, s, target);
      if (table == null) {
        bail(cx, 'existential cast projection not registered');
      }
      packWith(cx, target, heldFat, (table as RecordForwardTable).vtableGlobal)
    };
    cx.b.br(merge, oneValue(converted));
    cx.b.switchTo(nextB);
  }
  cx.b.unreachable();
  cx.b.switchTo(merge);
  return result;
}
VersionPublishedDependenciesApproved by
0.0.2-preview.1 2026-11-19