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 rules for contract clauses (docs/design/contracts.md): `requires`
* and `ensures` on a function, `invariant` on a loop.
*
* A clause's condition is an ordinary boolean expression. What differs
* between the kinds is where on the flow graph the condition is checked,
* and that an `ensures` condition can name `result` and call `old`.
*/
import { HashSet } from 'zena:collections';
import {
AssignmentExpression, AwaitExpression, CallExpression, ContractClause,
ContractKind, ContractMode, Expression, Identifier, Node, Parameter,
ThisExpression, contractKeyword, isOldCallee,
} from '../ast.zena';
import { DiagnosticCode } from '../diagnostics.zena';
import { FlowNode } from '../analysis/flow.zena';
import { SymbolId } from '../scope/symbol.zena';
import { PurityObligation } from '../semantic-model.zena';
import {
ErrorType, InlineTupleType, Type, UnionType, VoidType, unwrapAliases
} from '../types.zena';
import { walkEnter } from '../visitor.zena';
import { isInlineType } from './annotations.zena';
import { CheckerContext } from './context.zena';
import { checkExpression, validateConditionType } from './expressions.zena';
import { ConditionNarrowings, conditionNarrowings } from './narrowing.zena';
/**
* Whether `t` is an inline tuple, or a union of inline tuples: the
* inline results the lowering lays out as lanes (`inlineLayoutOf`).
*/
function isInlineTupleResult(t: Type): boolean {
let bare = unwrapAliases(t);
if (bare is InlineTupleType) { return true; }
if (let UnionType {types} = bare) {
for (let member in types) {
if (!(unwrapAliases(member) is InlineTupleType)) { return false; }
}
return true;
}
return false;
}
/** Checks one condition as a boolean, and that evaluating it changes nothing. */
function checkCondition(ctx: CheckerContext, clause: ContractClause) {
let {condition} = clause;
let conditionType = checkExpression(ctx, condition, null);
// An error type has been reported where it arose.
if (!(conditionType is ErrorType)) {
validateConditionType(ctx, conditionType, condition);
}
// A clause can be left out of a build, so a condition that assigns or
// suspends would make the program behave differently without it.
let keyword = contractKeyword(clause.kind);
walkEnter(condition, (n) => {
if (n is AssignmentExpression) {
ctx.error(
`A '${keyword}' condition cannot assign.`,
DiagnosticCode.InvalidAssignment, n.loc);
} else if (n is AwaitExpression) {
ctx.error(
`A '${keyword}' condition cannot await.`,
DiagnosticCode.TypeMismatch, n.loc);
}
});
// A `static` condition is never run, so it can stand for a fact only
// if evaluating it would change nothing. That depends on the bodies
// of what it calls, and is settled when every module is checked.
if (clause.mode == ContractMode.Static && !(conditionType is ErrorType)) {
ctx.model.addPurityObligation(new PurityObligation(
condition, `A 'static ${keyword}' condition`, clause.kind == ContractKind.Ensures
));
}
}
/**
* Checks a function's `requires` clauses. Called at the start of the
* body's flow, with the parameters bound: a precondition sees what the
* body sees on entry.
*
* A precondition is checked on every call, and a call that fails it
* does not reach the body. So what a condition narrows when it is true
* holds from there on: each clause leaves its narrowings on the flow
* for the clauses after it and for the body, as the test of an `if`
* does for its consequent.
*
* Returns the flow position to check the function's postconditions
* from (checkEnsuresClauses). That is the entry plus the narrowings on
* parameters, which cannot be reassigned, so those still hold on the
* way out. Narrowings on member paths are left out: a path can start
* at a variable the body assigns.
*/
export function checkRequiresClauses(
ctx: CheckerContext,
contracts: GrowableArray<ContractClause> | null,
params: GrowableArray<Parameter>
): FlowNode {
let entryFlow = ctx.currentFlow;
if (contracts == null) { return entryFlow; }
let parameterIds = new HashSet<SymbolId>();
for (let param in params) {
let parameter = ctx.model.resolveDeclaration(param);
if (parameter != null) { parameterIds.add(parameter.id); }
}
let onParameters = new ConditionNarrowings();
for (let clause in contracts) {
if (clause.kind != ContractKind.Requires) { continue; }
checkCondition(ctx, clause);
// A `debug` clause is left out of some builds, and a `static` one of
// every build, so nothing after them can rely on what they would
// have narrowed.
if (clause.mode != ContractMode.Checked) { continue; }
let narrowings = conditionNarrowings(ctx, clause.condition).whenTrue;
ctx.pushFlowNarrowings(narrowings);
// A later clause narrows what an earlier one left, so its type for
// a parameter replaces the earlier one.
for (let id in narrowings.bindings.keys()) {
if (parameterIds.has(id)) {
onParameters.bindings[id] = narrowings.bindings[id];
}
}
}
let bodyFlow = ctx.currentFlow;
ctx.setFlow(entryFlow);
ctx.pushFlowNarrowings(onParameters);
let ensuresFlow = ctx.currentFlow;
ctx.setFlow(bodyFlow);
return ensuresFlow;
}
/**
* Reports `this` in a constructor's `requires` conditions. They run
* ahead of the field initializers, before the object exists.
*/
export function rejectThisInRequires(
ctx: CheckerContext,
contracts: GrowableArray<ContractClause> | null
): void {
if (contracts == null) { return; }
for (let clause in contracts) {
if (clause.kind != ContractKind.Requires) { continue; }
walkEnter(clause.condition, (n) => {
if (n is ThisExpression) {
ctx.error(
"A constructor's 'requires' condition cannot use 'this': it runs before the object exists.",
DiagnosticCode.TypeMismatch, n.loc);
}
});
}
}
/**
* Checks a function's `ensures` clauses. Called after the body, when
* an inferred return type is known, with `resultType` the type a
* `return` hands back: for an `async` function, the value its future
* completes with, and for a generator, nothing.
*
* `entryFlow` is the flow position checkRequiresClauses returned. A
* postcondition holds on every path out of the body, so nothing one of
* those paths narrowed is known in it, and it is checked from the
* entry.
*/
export function checkEnsuresClauses(
ctx: CheckerContext,
contracts: GrowableArray<ContractClause> | null,
params: GrowableArray<Parameter>,
resultType: Type,
entryFlow: FlowNode,
isGenerator: boolean = false
): void {
if (contracts == null) { return; }
// An inline tuple result is returned as several values, and `result`
// is bound to them as an inline parameter is. An inline record, or a
// union mixing an inline tuple with anything else, has no such
// binding yet (#932).
if (isInlineType(resultType) && !isInlineTupleResult(resultType)) {
rejectEnsuresClauses(ctx, contracts, 'a function that returns an inline record');
return;
}
var reportedParameter = false;
for (let clause in contracts) {
if (clause.kind != ContractKind.Ensures) { continue; }
if (!reportedParameter) {
reportedParameter = true;
for (let param in params) {
if (param.name.name == 'result') {
ctx.error(
"A parameter named 'result' cannot be read in an 'ensures' condition, " +
"where 'result' is the returned value. Rename the parameter.",
DiagnosticCode.DuplicateDeclaration, param.name.loc);
}
}
}
let resultSymbol = ctx.model.resolveDeclaration(clause);
let returnsNothing = resultType is VoidType;
if (resultSymbol != null) {
ctx.declareBinding(resultSymbol, if (returnsNothing) new ErrorType() else resultType);
if (returnsNothing) {
walkEnter(clause.condition, (n) => {
if (n is Identifier && ctx.model.resolve(n) === resultSymbol) {
// A generator's call returns its iterator; its body, which
// the postcondition follows, returns nothing.
ctx.error(
if (isGenerator) {
"'result' has no value here: a generator's body returns nothing."
} else {
"'result' has no value here: the function returns nothing."
},
DiagnosticCode.TypeMismatch, n.loc);
}
});
}
}
ctx.setFlow(entryFlow);
ctx.setInEnsures(true);
checkCondition(ctx, clause);
ctx.setInEnsures(false);
}
}
/**
* Checks a loop's `invariant` clauses. Called inside the loop's flow,
* ahead of its condition: an invariant holds each time the loop is
* about to test whether to run again.
*/
export function checkLoopInvariants(
ctx: CheckerContext,
invariants: GrowableArray<ContractClause> | null
): void {
if (invariants == null) { return; }
for (let clause in invariants) {
checkCondition(ctx, clause);
}
}
/** Reports the `ensures` clauses of a function that cannot have any yet. */
export function rejectEnsuresClauses(
ctx: CheckerContext,
contracts: GrowableArray<ContractClause> | null,
where: String
): void {
if (contracts == null) { return; }
for (let clause in contracts) {
if (clause.kind == ContractKind.Ensures) {
ctx.errorOnceAt(
`'ensures' clauses on ${where} are not supported yet.`,
DiagnosticCode.TypeMismatch, clause.loc);
}
}
}
/** Reports the clauses of a function that cannot have any yet. */
export function rejectContracts(
ctx: CheckerContext,
contracts: GrowableArray<ContractClause> | null,
where: String
): void {
if (contracts == null) { return; }
for (let clause in contracts) {
ctx.errorOnceAt(
`'${contractKeyword(clause.kind)}' clauses on ${where} are not supported yet.`,
DiagnosticCode.TypeMismatch, clause.loc);
}
}
/**
* The type of `old(e)`, or null when `call` is an ordinary call.
* `old(e)` is `e`'s value when the function was entered, so it has
* `e`'s type, and `e` can name only what exists on entry.
*/
export function checkOldExpression(ctx: CheckerContext, call: CallExpression): Type | null {
if (!isOldCallee(call.callee) || !(ctx.inEnsures || ctx.inOld)) { return null; }
if (ctx.inOld) {
ctx.error("'old' cannot be used inside another 'old'.", DiagnosticCode.TypeMismatch, call.loc);
return new ErrorType();
}
// A constructor is entered before its object exists, and its
// postconditions run in a different compiled function from its entry.
if (ctx.inConstructor) {
ctx.error(
"'old' in a constructor's 'ensures' condition is not supported yet.",
DiagnosticCode.TypeMismatch, call.loc);
return new ErrorType();
}
if (call.args.length != 1 || call.typeArguments != null) {
ctx.error(
"'old' takes one expression: 'old(e)' is the value 'e' had when the function was entered.",
DiagnosticCode.ArgumentCountMismatch, call.loc);
return new ErrorType();
}
let argument = call.args[0];
ctx.setInEnsures(false);
ctx.setInOld(true);
let argumentType = checkExpression(ctx, argument, null);
ctx.setInOld(false);
ctx.setInEnsures(true);
// The value is kept from entry as one value; an inline one is several.
if (isInlineType(argumentType)) {
ctx.error(
"'old' of an inline value is not supported yet.",
DiagnosticCode.TypeMismatch, call.loc);
return new ErrorType();
}
walkEnter(argument, (n) => {
if (n is Identifier) {
let named = ctx.model.resolve(n);
if (named != null && named.declaration is ContractClause) {
ctx.error(
"'result' cannot be used inside 'old': it has no value when the function is entered.",
DiagnosticCode.TypeMismatch, n.loc);
}
}
});
// The argument runs on entry in a build that checks the clause and
// not at all in one that leaves it out, so it can change nothing.
if (!(argumentType is ErrorType)) {
ctx.model.addPurityObligation(new PurityObligation(argument, "The argument of 'old'", false));
}
return argumentType;
}
- 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 |
|
|