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

8.5 KiB Raw
/**
 * Template tag and code emission helpers for synthesizing Zena source code.
 */
import {
  TemplateStringsArray, StringBuilder, FixedArray, GrowableArray
} from 'zena:core';

/**
 * A deferred Zena code template.
 */
export final class ZenaTemplate {
  strings: TemplateStringsArray;
  values: FixedArray<anyref>;
  new(this.strings, this.values);
}

/**
 * Tagged template function for Zena code generation.
 */
export function zena(strings: TemplateStringsArray, values: FixedArray<anyref>): ZenaTemplate {
  return new ZenaTemplate(strings, values);
}

/** Whether `b` can be part of a line's indentation: space (0x20) or tab (0x09). */
function isIndentByte(b: i32) {
  return b == 0x20 || b == 0x09;
}

/** The index of the next `\n` in `[from, end)`, or -1 if none. */
function nextNewline(seg: String, from: i32, end: i32): i32 {
  for (var i = from; i < end; i += 1) {
    if (seg.getByteAt(i) == 0x0A) {
      return i;
    }
  }
  return -1;
}

/**
 * Where content starts in the first literal: past the opening line when
 * that line is blank, and at 0 otherwise.
 */
function contentStart(first: String): i32 {
  let len = first.length;
  for (var i = 0; i < len; i += 1) {
    let b = first.getByteAt(i);
    if (b == 0x0A) {
      return i + 1;
    }
    if (!isIndentByte(b) && b != 0x0D) {
      return 0;
    }
  }
  return 0;
}

/**
 * Where content ends in the last literal: before the closing line when
 * that line is blank — dropping its line break with it — and at the end
 * otherwise.
 */
function contentEnd(last: String) {
  let len = last.length;
  var i = len - 1;
  while (i >= 0) {
    let b = last.getByteAt(i);
    if (b == 0x0A) {
      if (i > 0 && last.getByteAt(i - 1) == 0x0D) {
        return i - 1;
      }
      return i;
    }
    if (!isIndentByte(b)) {
      return len;
    }
    i -= 1;
  }
  return len;
}

/**
 * Calculates the common indentation prefix length across all content lines
 * in the template.
 */
function computeCommonIndentLen(
    strings: TemplateStringsArray,
    start0: i32,
    endN: i32): i32 {
  let segCount = strings.length;
  var commonIndent: String | null = null;

  for (var s = 0; s < segCount; s += 1) {
    let seg = strings[s];
    let segEnd = if (s == segCount - 1) endN else seg.length;
    let valueFollows = s < segCount - 1;
    var pos = if (s == 0) start0 else 0;
    var atLineStart = s == 0;

    while (pos < segEnd) {
      if (atLineStart) {
        var wsEnd = pos;
        while (wsEnd < segEnd && isIndentByte(seg.getByteAt(wsEnd))) {
          wsEnd += 1;
        }

        // Check if the rest of the line is blank:
        var isBlank = false;
        if (wsEnd >= segEnd) {
          isBlank = !valueFollows;
        } else {
          let b = seg.getByteAt(wsEnd);
          if (b == 0x0A) {
            isBlank = true;
          } else if (b == 0x0D) {
            isBlank = wsEnd + 1 < segEnd && seg.getByteAt(wsEnd + 1) == 0x0A;
          }
        }

        if (!isBlank) {
          let currentIndent = seg.sliceBytes(pos, wsEnd);
          if (commonIndent == null) {
            commonIndent = currentIndent;
          } else {
            let existing = commonIndent as String;
            let limit = if (existing.length < currentIndent.length) existing.length else currentIndent.length;
            var matchLen = 0;
            while (matchLen < limit && existing.getByteAt(matchLen) == currentIndent.getByteAt(matchLen)) {
              matchLen += 1;
            }
            commonIndent = existing.sliceBytes(0, matchLen);
          }
        }

        pos = wsEnd;
        atLineStart = false;
        if (pos >= segEnd) {
          break;
        }
      }

      let nl = nextNewline(seg, pos, segEnd);
      if (nl < 0) {
        break;
      }
      pos = nl + 1;
      atLineStart = true;
    }
  }

  return if (commonIndent != null) (commonIndent as String).length else 0;
}

/**
 * Emits a string value into `sb`, indenting any newlines with `lineIndent`.
 */
function emitString(sb: StringBuilder, lineIndent: String, str: String) {
  var pos = 0;
  let len = str.length;
  while (pos < len) {
    let nl = nextNewline(str, pos, len);
    if (nl < 0) {
      sb.append(str.sliceBytes(pos, len));
      break;
    }
    sb.append(str.sliceBytes(pos, nl + 1));
    sb.append(lineIndent);
    pos = nl + 1;
  }
}

/**
 * Emits a single interpolated value into `sb`.
 */
function emitValue(sb: StringBuilder, lineIndent: String, val: anyref, indentFirst: boolean): void {
  if (val == null) {
    return;
  }
  if (val is ZenaTemplate) {
    emit(sb, lineIndent, val as ZenaTemplate, indentFirst);
    return;
  }
  if (val is String) {
    let str = val as String;
    if (indentFirst) {
      sb.append(lineIndent);
    }
    emitString(sb, lineIndent, str);
    return;
  }
  if (val is GrowableArray<ZenaTemplate>) {
    let arr = val as GrowableArray<ZenaTemplate>;
    for (var i = 0; i < arr.length; i += 1) {
      if (i > 0) {
        sb.append("\n").append(lineIndent);
      }
      emit(sb, lineIndent, arr[i], false);
    }
    return;
  }
  if (val is FixedArray<ZenaTemplate>) {
    let arr = val as FixedArray<ZenaTemplate>;
    for (var i = 0; i < arr.length; i += 1) {
      if (i > 0) {
        sb.append("\n").append(lineIndent);
      }
      emit(sb, lineIndent, arr[i], false);
    }
    return;
  }
  if (val is GrowableArray<String>) {
    let arr = val as GrowableArray<String>;
    for (var i = 0; i < arr.length; i += 1) {
      if (i > 0) {
        sb.append("\n").append(lineIndent);
      }
      emitString(sb, lineIndent, arr[i]);
    }
    return;
  }
  if (val is FixedArray<String>) {
    let arr = val as FixedArray<String>;
    for (var i = 0; i < arr.length; i += 1) {
      if (i > 0) {
        sb.append("\n").append(lineIndent);
      }
      emitString(sb, lineIndent, arr[i]);
    }
    return;
  }
  if (val is GrowableArray<anyref>) {
    let arr = val as GrowableArray<anyref>;
    for (var i = 0; i < arr.length; i += 1) {
      if (i > 0) {
        sb.append("\n").append(lineIndent);
      }
      emitValue(sb, lineIndent, arr[i], false);
    }
    return;
  }
  if (val is FixedArray<anyref>) {
    let arr = val as FixedArray<anyref>;
    for (var i = 0; i < arr.length; i += 1) {
      if (i > 0) {
        sb.append("\n").append(lineIndent);
      }
      emitValue(sb, lineIndent, arr[i], false);
    }
    return;
  }
}

/**
 * Emits a `ZenaTemplate` into `sb` prefixed by `baseIndent`.
 */
export function emit(sb: StringBuilder, baseIndent: String, template: ZenaTemplate,
    indentFirstLine: boolean = true): void {
  let segCount = template.strings.length;
  if (segCount == 0) {
    return;
  }

  let start0 = contentStart(template.strings[0]);
  var endN = contentEnd(template.strings[segCount - 1]);
  if (segCount == 1 && endN < start0) {
    endN = start0;
  }

  let commonIndentLen = computeCommonIndentLen(template.strings, start0, endN);

  var atLineStart = true;
  var isFirstLine = true;
  var currentLineIndent = baseIndent;

  for (var s = 0; s < segCount; s += 1) {
    let seg = template.strings[s];
    let segEnd = if (s == segCount - 1) endN else seg.length;
    var pos = if (s == 0) start0 else 0;

    while (pos < segEnd) {
      if (atLineStart) {
        // Strip common indentation:
        var wsEnd = pos;
        while (wsEnd < segEnd && isIndentByte(seg.getByteAt(wsEnd))) {
          wsEnd += 1;
        }

        let wsLen = wsEnd - pos;
        let drop = if (wsLen < commonIndentLen) wsLen else commonIndentLen;
        pos += drop;

        if (!isFirstLine || indentFirstLine) {
          sb.append(baseIndent);
        }
        isFirstLine = false;

        // Measure the remaining indentation on this line:
        var relWsEnd = pos;
        while (relWsEnd < segEnd && isIndentByte(seg.getByteAt(relWsEnd))) {
          relWsEnd += 1;
        }
        let relativeIndent = seg.sliceBytes(pos, relWsEnd);
        sb.append(relativeIndent);
        currentLineIndent = baseIndent + relativeIndent;
        pos = relWsEnd;

        atLineStart = false;
        if (pos >= segEnd) {
          break;
        }
      }

      let nl = nextNewline(seg, pos, segEnd);
      if (nl < 0) {
        sb.append(seg.sliceBytes(pos, segEnd));
        pos = segEnd;
        break;
      }

      sb.append(seg.sliceBytes(pos, nl + 1));
      pos = nl + 1;
      atLineStart = true;
      currentLineIndent = baseIndent;
    }

    if (s < template.values.length) {
      emitValue(sb, currentLineIndent, template.values[s], false);
    }
  }
}

/**
 * Renders a `ZenaTemplate` to a String.
 */
export function render(template: ZenaTemplate, baseIndent: String = ""): String {
  let sb = new StringBuilder();
  emit(sb, baseIndent, template);
  return sb.toString();
}

VersionPublishedDependenciesApproved by
0.0.2-preview.1 2026-11-19