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
13.5 KiB
Raw
import { growable } from 'zena:core';
import { Expression, SourceLocation } from '../ast.zena';
import {
ArrayType, BoolLiteralType, ClassType, ErrorType,
InlineTupleType as InlineTupleT, InterfaceType, Type, TypeAliasType,
UnionType as UnionT, instantiateClassType, instantiateInterfaceType,
isFutureClassType, isIterableRangeClass, typeToString
} from '../types.zena';
import { DiagnosticCode } from '../diagnostics.zena';
import { WellKnown, isWellKnown } from '../well-known.zena';
import { CheckerContext } from './context.zena';
import { substituteTypeParams } from './generics.zena';
/** What a for-in found to iterate: the element type, and whether the
* iterator it reaches is asynchronous. */
type IterationProtocol = {elementType: Type, isAsync: boolean};
/**
* The element type a for-in binds over `iterableType`, and which protocol
* it drives (docs/design/async-iteration.md, "Consuming"). The synchronous
* protocol — an array, `Iterator<T>`, `Iterable<T>` — is looked for
* first, then the asynchronous one, `AsyncIterator<T>` and
* `AsyncIterable<T>`; a type that is both iterates synchronously. A plain
* `for` over the asynchronous protocol is an error: the loop never waits,
* and a value that is still coming would have nowhere to go. Reports
* and returns an error type for anything that is not iterable.
*/
export function getIterationProtocol(
ctx: CheckerContext,
iterableType: Type,
iterableExpr: Expression,
isAwait: boolean
): IterationProtocol {
if (iterableType is ErrorType) {
return {elementType: new ErrorType(), isAsync: false};
}
if (iterableType is ArrayType) {
return {elementType: iterableType.elementType, isAsync: false};
}
let sync = protocolElementType(ctx, iterableType,
WellKnown.IteratorInterface, WellKnown.IterableInterface);
if (sync != null) {
return {elementType: sync, isAsync: false};
}
let asyncElem = protocolElementType(ctx, iterableType,
WellKnown.AsyncIteratorInterface, WellKnown.AsyncIterableInterface);
if (asyncElem != null) {
if (!isAwait) {
ctx.error(
"Type '" + typeToString(iterableType) + "' is an asynchronous iterable, " +
"and a `for` never waits. Use `for await`, or `requireSync` to " +
"throw if a value is not available yet.",
DiagnosticCode.TypeMismatch,
iterableExpr.loc
);
// The element type is still known; binding it keeps the body's
// own errors about the body.
}
return {elementType: asyncElem, isAsync: true};
}
let name = match (iterableType) {
case ClassType as ct: `Type '${ct.name}' is not iterable.`
case InterfaceType as it: `Type '${it.name}' is not iterable.`
case _: "Type is not iterable."
};
ctx.error(name, DiagnosticCode.TypeMismatch, iterableExpr.loc);
return {elementType: new ErrorType(), isAsync: false};
}
/**
* The element type `t` yields through one iteration protocol — its
* iterator interface `iteratorW` and iterable interface `iterableW` —
* or null when `t` takes no part in it. A class takes part by
* implementing either interface, itself or through a superclass; an
* interface by being or extending one.
*/
/** The element type `t` yields through the synchronous protocol, or
* null when it takes no part in it: what a `for`-in binds over an
* `Iterable<T>`, an `Iterator<T>`, or a class implementing either. */
export function syncElementType(ctx: CheckerContext, t: Type): Type | null {
return protocolElementType(ctx, t,
WellKnown.IteratorInterface, WellKnown.IterableInterface);
}
function protocolElementType(
ctx: CheckerContext,
t: Type,
iteratorW: WellKnown,
iterableW: WellKnown
): Type | null {
match (t) {
case ClassType as ct: {
// A `BoundedRange<T>` or `FromRange<T>` with a non-`i32` argument
// is not a counting loop, and (today) nothing else either.
if (ct.typeArguments != null && !isIterableRangeClass(ct) &&
(isWellKnown(WellKnown.BoundedRangeClass, ct.name, ct.sourcePath) ||
isWellKnown(WellKnown.FromRangeClass, ct.name, ct.sourcePath))) {
return null;
}
for (let iface in ct.implementsList) {
let elemType = findProtocolInterface(ctx, iface, iterableW);
if (elemType != null) {
return substituteTypeParams(ct.typeParameters, ct.typeArguments, elemType);
}
}
for (let iface in ct.implementsList) {
let elemType = findProtocolInterface(ctx, iface, iteratorW);
if (elemType != null) {
return substituteTypeParams(ct.typeParameters, ct.typeArguments, elemType);
}
}
let {superType} = ct;
if (superType != null) {
return protocolElementType(ctx, superType as Type, iteratorW, iterableW);
}
return null;
}
case InterfaceType as it: {
if (isWellKnown(iteratorW, it.name, it.sourcePath) ||
isWellKnown(iterableW, it.name, it.sourcePath)) {
let {typeArguments} = it;
if (typeArguments != null) {
let args = typeArguments;
if (args.length > 0) { return args[0]; }
}
}
let elemType = findProtocolInterface(ctx, it, iterableW);
if (elemType != null) {
return elemType;
}
return findProtocolInterface(ctx, it, iteratorW);
}
case _: {
return null;
}
}
}
/**
* The element type of `iface` seen as the well-known generic interface
* `w` — `iface` is `w` itself, or extends it — by identity against the
* prelude declaration; null when it is neither.
*/
function findProtocolInterface(ctx: CheckerContext, iface: InterfaceType, w: WellKnown): Type | null {
let prelude = ctx.tryResolveWellKnownType(w);
if (prelude == null) { return null; }
match (prelude) {
case InterfaceType as protocolType: {
// Compare by type id — instantiateInterfaceType preserves the source id.
let sourceId = if (iface.genericSource != null) {
(iface.genericSource as InterfaceType).id
} else {
iface.id
};
if (sourceId == protocolType.id) {
let {typeArguments} = iface;
if (typeArguments != null) {
let args = typeArguments;
if (args.length > 0) { return args[0]; }
}
return null;
}
// Walk the extends list, substituting this instantiation's type
// arguments into inherited entries first — the extendsList is
// shared by reference with the generic source, so its entries
// mention the SOURCE's parameters.
for (let ext in iface.extendsList) {
var parent = ext as Type;
if (iface.typeArguments != null) {
parent = substituteTypeParams(
iface.typeParameters, iface.typeArguments, parent);
}
if (parent is InterfaceType) {
let result = findProtocolInterface(ctx, parent, w);
if (result != null) { return result; }
}
}
return null;
}
case _: { return null; }
}
}
/**
* `Future<Option<V>>`: the future a Pending iteration step carries for
* elements of type `V` (docs/design/async-iteration.md, "The Step
* protocol"). Null when the element type is an error or the prelude's
* `Future` or `Option` is missing; lowering then refuses the loop loudly.
*/
export function pendingStepFutureType(ctx: CheckerContext, elementType: Type): Type | null {
if (elementType is ErrorType) {
return null;
}
let option = ctx.tryResolveWellKnownType(WellKnown.OptionAlias);
let future = ctx.tryResolveWellKnownType(WellKnown.FutureClass);
if (option == null || !(option is TypeAliasType) ||
future == null || !(future is ClassType)) {
return null;
}
let optionArgs = growable<Type>([elementType]);
let optionOfElement = substituteTypeParams(
option.typeParameters, optionArgs, option.target);
let futureArgs = growable<Type>([optionOfElement]);
return instantiateClassType(future, futureArgs);
}
/**
* The payload of a protocol inline-tuple union — exactly two inline
* tuple arms discriminated by literal `true`/`false` at position 0
* (the `Iterator.next` / `Map.get` / Result shapes). The payload is
* the true arm's element 1; a Result arm's trailing error slot plays
* no part. Null when `t` is any other type.
*/
export function protocolPayloadType(t: Type): Type | null {
if (!(t is UnionT)) { return null; }
let types = t.types;
if (types.length != 2) { return null; }
var trueArm: InlineTupleT | null = null;
var sawFalse = false;
for (let member in types) {
if (!(member is InlineTupleT)) { return null; }
if (member.elementTypes.length < 1) { return null; }
let head = member.elementTypes[0];
if (!(head is BoolLiteralType)) { return null; }
if (head.value) { trueArm = member; } else { sawFalse = true; }
}
if (trueArm == null || !sawFalse) { return null; }
if (trueArm.elementTypes.length < 2) { return null; }
return trueArm.elementTypes[1];
}
/**
* If `t` is the prelude Iterator<T> instantiation, returns T;
* otherwise null. A generator's declared return type must satisfy
* this (generators.md §2.2); the annotation is the call expression's
* type, and the yield type is its argument.
*/
export function extractIteratorYieldType(ctx: CheckerContext, t: Type): Type | null {
if (!(t is InterfaceType)) {
return null;
}
let prelude = ctx.tryResolveWellKnownType(WellKnown.IteratorInterface);
if (prelude == null || !(prelude is InterfaceType)) {
return null;
}
if (t.id != prelude.id) {
return null;
}
let args = t.typeArguments;
if (args == null) {
return null;
}
if (args.length != 1) {
return null;
}
return args[0];
}
/**
* The external type of a `gen` function with no annotation:
* Iterator<inferredYieldType> from the prelude.
*/
export function makeIteratorType(
ctx: CheckerContext,
yieldType: Type,
loc: SourceLocation | null
): Type {
let prelude = ctx.tryResolveWellKnownType(WellKnown.IteratorInterface);
if (prelude == null || !(prelude is InterfaceType)) {
ctx.error(
"Generator functions require the 'Iterator' interface from the prelude.",
DiagnosticCode.TypeMismatch,
loc
);
return new ErrorType();
}
let args = growable<Type>([yieldType]);
return instantiateInterfaceType(prelude, args);
}
/**
* If `t` is the prelude AsyncIterator<T> instantiation, returns T;
* otherwise null. An async generator's declared return type must
* satisfy this (async-iteration.md).
*/
export function extractAsyncIteratorYieldType(ctx: CheckerContext, t: Type): Type | null {
if (!(t is InterfaceType)) {
return null;
}
let prelude = ctx.tryResolveWellKnownType(WellKnown.AsyncIteratorInterface);
if (prelude == null || !(prelude is InterfaceType)) {
return null;
}
if (t.id != prelude.id) {
return null;
}
let args = t.typeArguments;
if (args == null) {
return null;
}
if (args.length != 1) {
return null;
}
return args[0];
}
/**
* The external type of an `async gen` function with no annotation:
* AsyncIterator<inferredYieldType> from 'zena:async'.
*/
export function makeAsyncIteratorType(
ctx: CheckerContext,
yieldType: Type,
loc: SourceLocation | null
): Type {
let prelude = ctx.tryResolveWellKnownType(WellKnown.AsyncIteratorInterface);
if (prelude == null || !(prelude is InterfaceType)) {
ctx.error(
"Async generator functions require the 'AsyncIterator' interface from 'zena:async'.",
DiagnosticCode.TypeMismatch,
loc
);
return new ErrorType();
}
let args = growable<Type>([yieldType]);
return instantiateInterfaceType(prelude, args);
}
/**
* If `t` is the prelude Future<T> instantiation, returns T; otherwise
* null. An async function's declared return type must satisfy this
* (async.md §1); the annotation is the call expression's type.
*/
export function extractFutureValueType(ctx: CheckerContext, t: Type): Type | null {
// By name and declaring module (isFutureClassType) rather than by
// identity with a recorded Future: inside zena:async's own files —
// exactly where the library's own async code (thenImpl) awaits —
// there may be no record yet, since it is filled as the declaring
// module is checked. The module id is reserved, so the name cannot
// be spoofed.
if (!isFutureClassType(t)) {
return null;
}
let ct = t as ClassType;
let args = ct.typeArguments;
if (args == null) {
return null;
}
if (args.length != 1) {
return null;
}
return args[0];
}
/**
* The value an `await` of `t` yields when `t` is a future: a `Future<T>`,
* or a subclass of one such as `DeferredFuture<T>`, at its `Future`
* superclass. Null otherwise. An async function's declared return type
* is held to `Future<T>` itself (extractFutureValueType), since its
* frame builds a plain future.
*/
export function awaitedFutureValueType(ctx: CheckerContext, t: Type): Type | null {
var current: ClassType | null = if (t is ClassType) t else null;
while (current != null) {
let value = extractFutureValueType(ctx, current);
if (value != null) {
return value;
}
current = current.superType;
}
return null;
}
/**
* The external type of an `async` function with no annotation:
* Future<inferredValueType> from the prelude.
*/
export function makeFutureType(
ctx: CheckerContext,
valueType: Type,
loc: SourceLocation | null
): Type {
let prelude = ctx.tryResolveWellKnownType(WellKnown.FutureClass);
if (prelude == null || !(prelude is ClassType)) {
ctx.error(
"Async functions require the 'Future' class from the prelude.",
DiagnosticCode.TypeMismatch,
loc
);
return new ErrorType();
}
let args = growable<Type>([valueType]);
return instantiateClassType(prelude, args);
}
- 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 |
|
|