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

12.8 KiB Raw
/**
 * The rule for inline bindings (docs/design/inline-parameters.md): an
 * `inline` parameter or `let` is never put in a heap object, so each use
 * of one reads it or passes it on to another inline position. A use that
 * would box it is an error at that use.
 *
 * Assignability converts between a tuple and its inline form without
 * seeing the expression, so the rule is a walk of its own over a body,
 * classifying each reference to an inline binding by its parent node.
 */
import {
  ArrayLiteral, AsExpression, AssignmentExpression, BinaryExpression,
  BlockStatement, CallExpression, Expression, PropertyAssignment, TupleLiteral,
  ExpressionStatement, FunctionExpression, Identifier, IdentifierPattern, IfExpression,
  IndexExpression, IsExpression, LetPatternCondition, MatchCase,
  MatchExpression, MemberExpression, MethodDefinition, NewExpression, Node,
  ReturnStatement, TryExpression, UsingStatement, VariableDeclaration, BindingPattern,
} from '../ast.zena';
import { DiagnosticCode } from '../diagnostics.zena';
import { ClassType, FunctionType, InlineTupleType, Type } from '../types.zena';
import { walk } from '../visitor.zena';
import { isInlineType } from './annotations.zena';
import { CheckerContext } from './context.zena';

/** Whether `e` names an inline parameter or `let`. */
export function isInlineBindingReference(ctx: CheckerContext, e: Expression): boolean {
  return inlineBindingTypeOf(ctx, e) != null;
}

/**
 * The inline type `e` forwards, or null: the type of the inline binding
 * it names, or that an arm of it names when it is an `if` or `match`. A
 * `let` it initializes is inline too, since the rule counts the arm as a
 * forward and boxing it is what the binding's `inline` rules out.
 */
export function forwardedInlineTypeOf(ctx: CheckerContext, e: Expression): Type | null {
  let named = inlineBindingTypeOf(ctx, e);
  if (named != null) {
    return named;
  }
  if (e is IfExpression) {
    let fromThen = armForwardedInlineType(ctx, e.consequent);
    if (fromThen != null) {
      return fromThen;
    }
    let alternate = e.alternate;
    return if (alternate != null) armForwardedInlineType(ctx, alternate) else null;
  }
  if (e is MatchExpression) {
    for (let mc in e.cases) {
      let fromArm = armForwardedInlineType(ctx, mc.body);
      if (fromArm != null) {
        return fromArm;
      }
    }
  }
  return null;
}

/** `forwardedInlineTypeOf` for an arm: an expression, or a block's tail. */
function armForwardedInlineType(ctx: CheckerContext, arm: Node): Type | null {
  if (arm is Expression) {
    return forwardedInlineTypeOf(ctx, arm);
  }
  if (arm is BlockStatement && arm.body.length > 0) {
    let last = arm.body[arm.body.length - 1];
    if (last is ExpressionStatement) {
      return forwardedInlineTypeOf(ctx, last.expression);
    }
  }
  return null;
}

/** The inline type of the parameter or `let` `e` names, or null. */
export function inlineBindingTypeOf(ctx: CheckerContext, e: Expression): Type | null {
  if (!(e is Identifier)) {
    return null;
  }
  let sym = ctx.model.resolve(e);
  if (sym == null) {
    return null;
  }
  let t = ctx.model.getBindingType(sym);
  return if (t != null && isInlineType(t) && !(t is FunctionType)) t else null;
}

/**
 * A function with an inline parameter named anywhere but as a call's
 * callee: a value of its type would need an adapter to a boxed parameter,
 * which does not exist yet (#543).
 */
export function rejectInlineFunctionValue(ctx: CheckerContext, expr: Expression, t: FunctionType): void {
  if (!hasInlineParameter(t)) {
    return;
  }
  ctx.error(
    "A function that takes a parameter inline is called directly, not used as a value: adapting it to a boxed parameter is not supported yet (#543).",
    DiagnosticCode.TypeMismatch,
    expr.loc
  );
}

/** Whether a function type takes some parameter inline. */
export function hasInlineParameter(ft: FunctionType): boolean {
  for (let p in ft.parameters) {
    if (isInlineType(p)) {
      return true;
    }
  }
  return false;
}

/**
 * Whether two function types take the same parameters inline: inline-ness
 * changes the wasm signature, so a function stands for another only when
 * they agree at every position either has.
 */
export function inlineParamsMatch(a: FunctionType, b: FunctionType): boolean {
  let n = if (a.parameters.length > b.parameters.length) a.parameters.length else b.parameters.length;
  for (var i = 0; i < n; i += 1) {
    let ai = i < a.parameters.length && isInlineType(a.parameters[i]);
    let bi = i < b.parameters.length && isInlineType(b.parameters[i]);
    if (ai != bi) {
      return false;
    }
  }
  return true;
}

/**
 * Reports each use of an inline binding in `body` that would box it.
 * `result` is the result type of the function `body` belongs to, which
 * decides whether returning the binding passes it on. Nested functions
 * are skipped: a reference from one is a capture, which the closure check
 * reports.
 */
export function checkInlineBindingUses(ctx: CheckerContext, body: Node, result: Type | null): void {
  walk(body, (n) => {
    if (n is FunctionExpression) {
      return false;
    }
    if (n is Identifier) {
      checkInlineReference(ctx, n, result);
    }
    return true;
  }, (n) => {});
}

function checkInlineReference(ctx: CheckerContext, ref: Identifier, result: Type | null): void {
  let sym = ctx.model.resolve(ref);
  // A declaration names its binding; only a reference uses it.
  if (sym == null || sym.declaration === ref) {
    return;
  }
  let bindingType = ctx.model.getBindingType(sym);
  if (bindingType == null || !isInlineType(bindingType) || bindingType is FunctionType) {
    return;
  }
  let problem = boxingUse(ctx, ref, result);
  if (problem != null) {
    ctx.error(
      `'${ref.name}' is inline, so it is only read or passed on: ${problem} would box it.`,
      DiagnosticCode.TypeMismatch,
      ref.loc
    );
  }
  let parent = ctx.model.getParent(ref);
  if (parent is AssignmentExpression && parent.left === ref && inProtectedRegion(ctx, ref)) {
    ctx.error(
      `'${ref.name}' is an inline 'var', so it cannot be assigned inside a 'try' or after a 'using': its handler would need the value in one place.`,
      DiagnosticCode.TypeMismatch,
      ref.loc
    );
  }
}

/**
 * Whether `node` is in a region an exception handler protects, in its own
 * function: a `try` body, or the statements after a `using` in its block,
 * which release the resource the way a `finally` would.
 */
function inProtectedRegion(ctx: CheckerContext, node: Node): boolean {
  var child = node;
  var p = ctx.model.getParent(node);
  while (p != null && !(p is FunctionExpression) && !(p is MethodDefinition)) {
    if (p is TryExpression && (p.body as Node) === child) {
      return true;
    }
    if (p is BlockStatement) {
      for (let statement in p.body) {
        if ((statement as Node) === child) {
          break;
        }
        if (statement is UsingStatement) {
          return true;
        }
      }
    }
    child = p;
    p = ctx.model.getParent(p);
  }
  return false;
}

/**
 * What the use of `node`, an inline value, does that would box it, or
 * null when it reads the value or passes it on to an inline position.
 */
function boxingUse(ctx: CheckerContext, node: Node, result: Type | null): String | null {
  let parent = ctx.model.getParent(node);
  if (parent == null) {
    return "this use";
  }
  return match (parent) {
    case VariableDeclaration {kind, pattern, init}: {
      if (init !== node) {
        "this use"
      } else if (kind == "var" && pattern is IdentifierPattern &&
          !isInlineVar(ctx, pattern)) {
        "holding it in a 'var'"
      } else {
        null
      }
    }
    case LetPatternCondition {init}: if (init === node) null else "this use"
    case MatchExpression {discriminant}: if (discriminant === node) null else "this use"
    case IndexExpression {object}: if (object === node) null else "indexing with it"
    case MemberExpression {object}: if (object === node) null else "this use"
    // `==` and `!=` compare slot by slot (#812), boxing neither side.
    case BinaryExpression {operator}:
      if (operator == "==" || operator == "!=") null else "this use"
    // `is` tests the literals in its slots (#812).
    case IsExpression {}: null
    case ExpressionStatement {}: statementUse(ctx, parent, result)
    case ReturnStatement {}: returnedUse(result)
    case FunctionExpression {}: returnedUse(result)
    // An arm passes the value on wherever the `if` or `match` does.
    case IfExpression {test}: if (test === node) "this use" else boxingUse(ctx, parent, result)
    case MatchCase {body}: {
      let matchExpr = ctx.model.getParent(parent);
      if (body !== node || matchExpr == null) {
        "this use"
      } else {
        boxingUse(ctx, matchExpr, result)
      }
    }
    case CallExpression {args}: {
      let callee = ctx.model.getResolvedOverload(parent) ?? ctx.model.getNodeType(parent.callee);
      argumentUse(node, args, callee)
    }
    case NewExpression {args, constructorName}: {
      argumentUse(node, args, constructorOf(ctx, parent, constructorName))
    }
    case AsExpression {}: "converting it with 'as'"
    case ArrayLiteral {}: "putting it in an array"
    case TupleLiteral {}: tupleElementUse(ctx, parent, node, result)
    case PropertyAssignment {}: "putting it in a record"
    // Writing an inline `var` replaces its slots; writing an inline value
    // into one passes it on.
    case AssignmentExpression {left, value, operator}: {
      if (operator != null) {
        "this use"
      } else if (left === node) {
        null
      } else if (value === node && left is Identifier && isInlineVar(ctx, left)) {
        null
      } else {
        "assigning it"
      }
    }
    case _: "this use"
  };
}

/** Whether `name` is, or names, a `var` of an inline type. */
function isInlineVar(ctx: CheckerContext, name: Node): boolean {
  let sym = if (name is Identifier) ctx.model.resolve(name)
      else ctx.model.resolveDeclaration(name);
  if (sym == null) {
    return false;
  }
  let t = ctx.model.getBindingType(sym);
  let decl = sym.declaration;
  return t != null && isInlineType(t) && !(t is FunctionType) &&
      decl != null && declaresVar(ctx, decl);
}

/** Whether the binding `decl` names is declared by a `var`. */
function declaresVar(ctx: CheckerContext, decl: Node): boolean {
  var p = ctx.model.getParent(decl);
  if (p is BindingPattern) {
    p = ctx.model.getParent(p);
  }
  return p is VariableDeclaration && p.kind == "var";
}

/**
 * An element of a tuple literal is passed on when the literal is an inline
 * tuple used without boxing and the element's position is inline itself:
 * its slots or fields are the literal's (#515, #811).
 */
function tupleElementUse(ctx: CheckerContext, literal: TupleLiteral, node: Node,
    result: Type | null): String | null {
  let t = ctx.model.getNodeType(literal);
  if (t != null && t is InlineTupleType) {
    var index = -1;
    for (var i = 0; i < literal.elements.length; i += 1) {
      if (literal.elements[i] === node) {
        index = i;
      }
    }
    if (index >= 0 && index < t.elementTypes.length && isInlineType(t.elementTypes[index])) {
      return boxingUse(ctx, literal, result);
    }
  }
  return "putting it in a tuple";
}

/**
 * An expression statement discards its value, unless it ends a block
 * that is an arm of an `if` or `match`, where it is the arm's value.
 */
function statementUse(ctx: CheckerContext, statement: Node, result: Type | null): String | null {
  let parent = ctx.model.getParent(statement);
  if (parent is BlockStatement) {
    let block = parent;
    let {body} = block;
    if (body.length > 0 && body[body.length - 1] === statement) {
      let arm = ctx.model.getParent(block);
      if (arm is IfExpression || arm is MatchCase) {
        return boxingUse(ctx, block, result);
      }
    }
  }
  return null;
}

function returnedUse(result: Type | null): String | null {
  return if (result != null && isInlineType(result)) null else "returning it as a boxed result";
}

function argumentUse(node: Node, args: GrowableArray<Expression>, callee: Type | null): String | null {
  var index = -1;
  for (var i = 0; i < args.length; i += 1) {
    if (args[i] === node) {
      index = i;
    }
  }
  if (index < 0) {
    return "this use";
  }
  if (let FunctionType {parameters} = callee) {
    if (index < parameters.length && isInlineType(parameters[index])) {
      return null;
    }
  }
  return "passing it for a parameter that is not inline";
}

/** The constructor a `new` calls, or null when it has none. */
function constructorOf(ctx: CheckerContext, expr: NewExpression,
    constructorName: Node | null): FunctionType | null {
  let created = ctx.model.getNodeType(expr);
  if (created == null || !(created is ClassType)) {
    return null;
  }
  let ct = created;
  if (constructorName != null && constructorName is Identifier) {
    let name = constructorName.name;
    return if (ct.constructors.has(name)) ct.constructors[name] else null;
  }
  return ct.constructorType;
}
VersionPublishedDependenciesApproved by
0.0.2-preview.1 2026-11-19