wit-parser 0.0.1-preview.1
A WIT (WebAssembly Interface Types) parser, resolver and component encoder
wit-parser#
A WebAssembly Interface Types (WIT) parser, semantic resolver, .wit.json
serializer, and component type encoder for Zena.
Installation#
zena pkg add zena-lang:wit-parser
Example#
import { parse } from 'zena-lang:wit-parser';
import { AstItemTag } from 'zena-lang:wit-parser/parser';
let source = `
package example:greeter@1.0.0;
interface greet {
record greeting { text: string, formal: bool }
hello: func(name: string) -> greeting;
}
interface farewell {
use greet.{greeting};
goodbye: func(name: string) -> greeting;
}
world greeter {
export greet;
export farewell;
}
`;
// Parses syntax and resolves names and cross-interface `use` references.
// Throws `ParseError` or `ResolveError` if the document is invalid.
let doc = parse(source);
var interfaces = 0;
var worlds = 0;
for (let item in doc.items) {
if (item.tag == AstItemTag.Interface) {
interfaces += 1;
} else if (item.tag == AstItemTag.World) {
worlds += 1;
}
}
Libraries#
zena-lang:wit-parser#
The primary entry point for parsing, resolving, and serializing WIT source text.
| Function | Description |
|---|---|
parse(source) |
Parses and resolves source into a validated Ast. Throws ParseError or ResolveError. |
parseSyntax(source) |
Parses source without resolving names, for single-file syntax tooling such as formatters. |
resolve(ast) |
Resolves names and validates an Ast in place. |
toJson(ast, packageOrder?) |
Serializes a resolved Ast to the .wit.json format emitted by wasm-tools component wit --json. |
zena-lang:wit-parser also re-exports Ast, ParseError, and ResolveError. Both
error types carry a Span with byte offsets into the source text.
zena-lang:wit-parser/parser#
The AST node declarations (Ast, AstItem, AstItemTag, InterfaceDef,
WorldDef, TypeDef, Type, NamedFunc, ResourceFunc, Use, Include,
Docs, Attribute, PackageName, NestedPackage, and related types) and
Parser.
zena-lang:wit-parser/document#
Utilities for assembling multi-file WIT directories into a single source document while tracking file boundaries for error reporting:
WitFile(name, source)andjoinWitDocument(files): concatenates.witfiles in canonical name order and records where each file starts.WitDocument.locate(offset): maps a byte offset back to aWitLocation(file, 1-basedline, 1-basedcolumn).witDiagnostic(doc, error): formats aLexError,ParseError, orResolveErrorwith its filename, line, column, source line, and caret underline.findInterface(ast, namespace, interfacePath): looks up an interface (pkg/iface) in a parsed document.
zena-lang:wit-parser/component-encoder#
Encodes a resolved WIT world into WebAssembly Component Model binary type and import sections:
encodeTypesOnlyComponent(ast, worldName): encodes the named world as a standalone types-only component binary.ComponentTypeEncoder: emits component type, alias, import, and export sections and canonical ABI metadata (WitFuncMeta,WitFlatMeta).expandedWorldItems(ast, world)andworldNames(ast): expands worldincludes and transitiveusedependencies.
zena-lang:wit-parser/lexer and zena-lang:wit-parser/token#
Low-level tokenization: Lexer, LexError, Token, TokenType, and Span.
zena-lang:wit-parser/resolver#
Semantic validation and name resolution: Resolver and ResolveError.
/**
* WIT Parser
*
* A recursive descent parser for WIT (WebAssembly Interface Types) syntax.
* Produces an unresolved parse tree that is later transformed by the resolver
* into the resolved AST.
*
* Based on the canonical implementation in wasm-tools:
* https://github.com/bytecodealliance/wasm-tools/blob/main/crates/wit-parser/src/ast.rs
*/
import {StringBuilder} from 'zena:core';
import {TokenType, Span, Token, describeToken, isKeyword} from './token.zena';
import {Lexer, LexError} from './lexer.zena';
// ============================================================================
// Parse Error
// ============================================================================
/**
* Error produced during parsing.
*/
export class ParseError extends Error {
span: Span;
new(message: String, span: Span) : span = span, super(message);
}
// ============================================================================
// Unresolved AST Types (Parse Tree)
// ============================================================================
function normalizeDocs(contents: String) {
if (contents.length == 0) {
return "";
}
// 1. Split into lines and trim trailing whitespace
let lines = new GrowableArray<String>();
var lineStart = 0;
for (var i = 0; i <= contents.length; i += 1) {
if (i == contents.length || contents.getByteAt(i) == 10) { // 10 is '\n'
// Extract line
let line = contents.sliceBytes(lineStart, i);
// Trim training whitespace (space 32, tab 9, CR 13)
var end = line.length;
while (end > 0) {
let b = line.getByteAt(end - 1);
if (b == 32 || b == 9 || b == 13) {
end -= 1;
} else {
break;
}
}
lines.push(line.sliceBytes(0, end));
lineStart = i + 1;
}
}
// 2. Scan non-empty lines to find the minimum leading whitespace count
var minLeadingWs = 999999;
var hasNonEmpty = false;
for (let line in lines) {
if (line.length > 0) {
hasNonEmpty = true;
var leadingWs = 0;
while (leadingWs < line.length) {
let b = line.getByteAt(leadingWs);
if (b == 32 || b == 9) {
leadingWs += 1;
} else {
break;
}
}
if (leadingWs < minLeadingWs) {
minLeadingWs = leadingWs;
}
}
}
if (!hasNonEmpty) {
minLeadingWs = 0;
}
// 3. Strip the minimum leading whitespace and join back with newline
let sb = new StringBuilder();
for (var idx = 0; idx < lines.length; idx += 1) {
let line = lines[idx];
if (line.length > 0) {
if (minLeadingWs < line.length) {
sb.append(line.sliceBytes(minLeadingWs, line.length));
} else {
// Line is entirely whitespace
}
}
if (idx < lines.length - 1) {
sb.appendByte(10); // '\n'
}
}
return sb.toString();
}
/**
* Documentation comments collected from /// comments.
*/
export class Docs {
span: Span;
var contents: String | null = null;
/** Annotations that appeared before this item. */
var attributes: GrowableArray<Attribute> | null = null;
new(span: Span) : span = span;
}
// ============================================================================
// Annotations/Attributes
// ============================================================================
/**
* Tag for Attribute kinds.
* WIT supports: @since(version = x.y.z), @unstable(feature = name), @deprecated(version = x.y.z)
*/
export enum AttributeTag {
Since,
Unstable,
Deprecated,
}
/**
* An attribute/annotation on an item.
*/
export class Attribute {
tag: AttributeTag;
span: Span;
/** For @since and @deprecated: the version string */
var version: String | null = null;
/** For @unstable: the feature name */
var feature: Id | null = null;
new(tag: AttributeTag, span: Span) : tag = tag, span = span;
static since(version: String, span: Span): Attribute {
let a = new Attribute(AttributeTag.Since, span);
a.version = version;
return a;
}
static unstable(feature: Id, span: Span): Attribute {
let a = new Attribute(AttributeTag.Unstable, span);
a.feature = feature;
return a;
}
static deprecated(version: String, span: Span): Attribute {
let a = new Attribute(AttributeTag.Deprecated, span);
a.version = version;
return a;
}
}
/**
* An identifier in the source.
*/
export class Id {
name: String;
span: Span;
new(name: String, span: Span) : name = name, span = span;
}
/**
* A package name: namespace:name@version
*/
export class PackageName {
namespace: Id;
name: Id;
var span: Span;
var version: String | null = null;
var versionSpan: Span | null = null;
new(namespace: Id, name: Id, span: Span) : namespace = namespace, name = name, span = span;
}
// ============================================================================
// Use Paths
// ============================================================================
/**
* Tag for UsePath variants.
*/
export enum UsePathTag {
Id, // Just an identifier: `foo`
Package, // Package path: `foo:bar/baz`
}
/**
* A path in a use statement.
*/
export sealed class UsePath {
case IdUsePath, PackageUsePath
tag: UsePathTag;
var id: Id | null = null; // For Id tag
var packageId: PackageName | null = null; // For Package tag
var name: Id | null = null; // For Package tag (interface name)
new(this.tag);
static fromId(id: Id): UsePath {
return new IdUsePath(id);
}
static fromPackage(pkgId: PackageName, name: Id): UsePath {
return new PackageUsePath(pkgId, name);
}
/** Get the final name component. */
getName(): Id {
// Not a match: the self-hosted checker does not (yet) prove
// exhaustiveness over a sealed class whose subclasses are declared
// separately with `extends` rather than as `case` members.
if (this is IdUsePath) {
return (this as IdUsePath).id as Id;
}
return (this as PackageUsePath).name as Id;
}
}
export final class IdUsePath extends UsePath {
new(id: Id) : super(UsePathTag.Id) {
this.id = id;
}
}
export final class PackageUsePath extends UsePath {
new(pkgId: PackageName, name: Id) : super(UsePathTag.Package) {
this.packageId = pkgId;
this.name = name;
}
}
/**
* A name in a use statement with optional rename.
*/
export class UseName {
name: Id;
var asName: Id | null = null;
new(name: Id) : name = name;
}
// ============================================================================
// Types
// ============================================================================
/**
* Tag for Type variants.
*/
export enum TypeTag {
// Primitives
U8, U16, U32, U64,
S8, S16, S32, S64,
F32, F64,
Char, Bool, String,
ErrorContext,
// Composite
List,
Option,
Result,
Tuple,
Future,
Stream,
Map,
// Handle types
Own, // own<T>
Borrow, // borrow<T>
// Named type reference
Name,
}
/**
* A type in the unresolved AST.
*/
export sealed class Type {
case U8Type, U16Type, U32Type, U64Type
case S8Type, S16Type, S32Type, S64Type
case F32Type, F64Type
case CharType, BoolType, StringType
case ErrorContextType
case ListType, OptionType, ResultType, TupleType, FutureType, StreamType, MapType
case OwnType, BorrowType, NameType
tag: TypeTag;
var span: Span;
// Keep these fields on the base class as nullable to maintain backwards-compatibility
var inner: Type | null = null;
var fixedLength = 0 - 1; // -1
var okType: Type | null = null;
var errType: Type | null = null;
var types: GrowableArray<Type> | null = null;
var keyType: Type | null = null;
var valueType: Type | null = null;
var name: Id | null = null;
new(this.tag, this.span);
static primitive(tag: TypeTag, span: Span): Type {
return match (tag) {
case TypeTag.U8: new U8Type(span)
case TypeTag.U16: new U16Type(span)
case TypeTag.U32: new U32Type(span)
case TypeTag.U64: new U64Type(span)
case TypeTag.S8: new S8Type(span)
case TypeTag.S16: new S16Type(span)
case TypeTag.S32: new S32Type(span)
case TypeTag.S64: new S64Type(span)
case TypeTag.F32: new F32Type(span)
case TypeTag.F64: new F64Type(span)
case TypeTag.Char: new CharType(span)
case TypeTag.Bool: new BoolType(span)
case TypeTag.String: new StringType(span)
case TypeTag.ErrorContext: new ErrorContextType(span)
case _: throw new Error("not a primitive type tag")
};
}
static list(inner: Type, span: Span): Type {
return new ListType(inner, span);
}
static option(inner: Type, span: Span): Type {
return new OptionType(inner, span);
}
static result(ok: Type | null, err: Type | null, span: Span): Type {
return new ResultType(ok, err, span);
}
static tuple(types: GrowableArray<Type>, span: Span): Type {
return new TupleType(types, span);
}
static future(inner: Type | null, span: Span): Type {
return new FutureType(inner, span);
}
static stream(inner: Type | null, span: Span): Type {
return new StreamType(inner, span);
}
static map(key: Type, value: Type, span: Span): Type {
return new MapType(key, value, span);
}
static own(inner: Type, span: Span): Type {
return new OwnType(inner, span);
}
static borrow(inner: Type, span: Span): Type {
return new BorrowType(inner, span);
}
static named(name: Id, span: Span): Type {
return new NameType(name, span);
}
}
export final class U8Type extends Type { new(span: Span) : super(TypeTag.U8, span); }
export final class U16Type extends Type { new(span: Span) : super(TypeTag.U16, span); }
export final class U32Type extends Type { new(span: Span) : super(TypeTag.U32, span); }
export final class U64Type extends Type { new(span: Span) : super(TypeTag.U64, span); }
export final class S8Type extends Type { new(span: Span) : super(TypeTag.S8, span); }
export final class S16Type extends Type { new(span: Span) : super(TypeTag.S16, span); }
export final class S32Type extends Type { new(span: Span) : super(TypeTag.S32, span); }
export final class S64Type extends Type { new(span: Span) : super(TypeTag.S64, span); }
export final class F32Type extends Type { new(span: Span) : super(TypeTag.F32, span); }
export final class F64Type extends Type { new(span: Span) : super(TypeTag.F64, span); }
export final class CharType extends Type { new(span: Span) : super(TypeTag.Char, span); }
export final class BoolType extends Type { new(span: Span) : super(TypeTag.Bool, span); }
export final class StringType extends Type { new(span: Span) : super(TypeTag.String, span); }
export final class ErrorContextType extends Type { new(span: Span) : super(TypeTag.ErrorContext, span); }
export final class ListType extends Type {
new(inner: Type, span: Span) : super(TypeTag.List, span) { this.inner = inner; }
}
export final class OptionType extends Type {
new(inner: Type, span: Span) : super(TypeTag.Option, span) { this.inner = inner; }
}
export final class ResultType extends Type {
new(ok: Type | null, err: Type | null, span: Span) : super(TypeTag.Result, span) {
this.okType = ok;
this.errType = err;
}
}
export final class TupleType extends Type {
new(types: GrowableArray<Type>, span: Span) : super(TypeTag.Tuple, span) { this.types = types; }
}
export final class FutureType extends Type {
new(inner: Type | null, span: Span) : super(TypeTag.Future, span) { this.inner = inner; }
}
export final class StreamType extends Type {
new(inner: Type | null, span: Span) : super(TypeTag.Stream, span) { this.inner = inner; }
}
export final class MapType extends Type {
new(key: Type, value: Type, span: Span) : super(TypeTag.Map, span) {
this.keyType = key;
this.valueType = value;
}
}
export final class OwnType extends Type {
new(inner: Type, span: Span) : super(TypeTag.Own, span) { this.inner = inner; }
}
export final class BorrowType extends Type {
new(inner: Type, span: Span) : super(TypeTag.Borrow, span) { this.inner = inner; }
}
export final class NameType extends Type {
new(name: Id, span: Span) : super(TypeTag.Name, span) { this.name = name; }
}
// ============================================================================
// Function Types
// ============================================================================
/**
* A function parameter.
*/
export class Param {
var name: Id;
var type: Type;
new(name: Id, type: Type) : name = name, type = type;
}
/**
* A function signature.
*/
export class Func {
var span: Span;
var isAsync = false;
var params = new GrowableArray<Param>();
var result: Type | null = null;
new(span: Span) : span = span;
}
/**
* A named function (in interface or resource).
*/
export class NamedFunc {
var docs: Docs;
var name: Id;
var func: Func;
new(docs: Docs, name: Id, func: Func) : docs = docs, name = name, func = func;
}
// ============================================================================
// Type Definitions
// ============================================================================
/**
* A field in a record.
*/
export class Field {
var docs: Docs;
var name: Id;
var type: Type;
new(docs: Docs, name: Id, type: Type) : docs = docs, name = name, type = type;
}
/**
* A flag in a flags type.
*/
export class FlagDef {
var docs: Docs;
var name: Id;
new(docs: Docs, name: Id) : docs = docs, name = name;
}
/**
* A case in a variant.
*/
export class Case {
var docs: Docs;
var name: Id;
var type: Type | null = null;
new(docs: Docs, name: Id) : docs = docs, name = name;
}
/**
* A case in an enum.
*/
export class EnumCaseDef {
var docs: Docs;
var name: Id;
new(docs: Docs, name: Id) : docs = docs, name = name;
}
/**
* Tag for resource function kinds.
*/
export enum ResourceFuncTag {
Method,
Static,
Constructor,
}
/**
* A function in a resource.
*/
export class ResourceFunc {
var tag: ResourceFuncTag;
var func: NamedFunc;
new(tag: ResourceFuncTag, func: NamedFunc) : tag = tag, func = func;
}
/**
* Tag for TypeDef kinds.
*/
export enum TypeDefTag {
Alias, // type foo = bar
Record, // record foo { ... }
Flags, // flags foo { ... }
Variant, // variant foo { ... }
Enum, // enum foo { ... }
Resource, // resource foo { ... }
}
/**
* A type definition.
*/
export sealed class TypeDef {
case AliasDef, RecordDef, FlagsDef, VariantDef, EnumDef, ResourceDef
var docs: Docs;
var tag: TypeDefTag;
var name: Id;
var aliasType: Type | null = null;
var fields: GrowableArray<Field> | null = null;
var flags: GrowableArray<FlagDef> | null = null;
var cases: GrowableArray<Case> | null = null;
var enumCases: GrowableArray<EnumCaseDef> | null = null;
var resourceFuncs: GrowableArray<ResourceFunc> | null = null;
new(this.docs, this.tag, this.name);
static alias(docs: Docs, name: Id, type: Type): TypeDef {
return new AliasDef(docs, name, type);
}
static record(docs: Docs, name: Id, fields: GrowableArray<Field>): TypeDef {
return new RecordDef(docs, name, fields);
}
static flagsDef(docs: Docs, name: Id, flags: GrowableArray<FlagDef>): TypeDef {
return new FlagsDef(docs, name, flags);
}
static variant(docs: Docs, name: Id, cases: GrowableArray<Case>): TypeDef {
return new VariantDef(docs, name, cases);
}
static enumDef(docs: Docs, name: Id, cases: GrowableArray<EnumCaseDef>): TypeDef {
return new EnumDef(docs, name, cases);
}
static resource(docs: Docs, name: Id, funcs: GrowableArray<ResourceFunc>): TypeDef {
return new ResourceDef(docs, name, funcs);
}
}
export final class AliasDef extends TypeDef {
new(docs: Docs, name: Id, aliasType: Type) : super(docs, TypeDefTag.Alias, name) {
this.aliasType = aliasType;
}
}
export final class RecordDef extends TypeDef {
new(docs: Docs, name: Id, fields: GrowableArray<Field>) : super(docs, TypeDefTag.Record, name) {
this.fields = fields;
}
}
export final class FlagsDef extends TypeDef {
new(docs: Docs, name: Id, flags: GrowableArray<FlagDef>) : super(docs, TypeDefTag.Flags, name) {
this.flags = flags;
}
}
export final class VariantDef extends TypeDef {
new(docs: Docs, name: Id, cases: GrowableArray<Case>) : super(docs, TypeDefTag.Variant, name) {
this.cases = cases;
}
}
export final class EnumDef extends TypeDef {
new(docs: Docs, name: Id, enumCases: GrowableArray<EnumCaseDef>) : super(docs, TypeDefTag.Enum, name) {
this.enumCases = enumCases;
}
}
export final class ResourceDef extends TypeDef {
new(docs: Docs, name: Id, resourceFuncs: GrowableArray<ResourceFunc>) : super(docs, TypeDefTag.Resource, name) {
this.resourceFuncs = resourceFuncs;
}
}
// ============================================================================
// Interface Items
// ============================================================================
/**
* Tag for InterfaceItem kinds.
*/
export enum InterfaceItemTag {
TypeDef,
Func,
Use,
}
/**
* An item in an interface.
*/
export sealed class InterfaceItem {
case InterfaceTypeDef, InterfaceFunc, InterfaceUse
var tag: InterfaceItemTag;
var typeDef: TypeDef | null = null;
var func: NamedFunc | null = null;
var use: Use | null = null;
new(this.tag);
static fromTypeDef(td: TypeDef): InterfaceItem {
return new InterfaceTypeDef(td);
}
static fromFunc(f: NamedFunc): InterfaceItem {
return new InterfaceFunc(f);
}
static fromUse(u: Use): InterfaceItem {
return new InterfaceUse(u);
}
}
export final class InterfaceTypeDef extends InterfaceItem {
new(typeDef: TypeDef) : super(InterfaceItemTag.TypeDef) {
this.typeDef = typeDef;
}
}
export final class InterfaceFunc extends InterfaceItem {
new(func: NamedFunc) : super(InterfaceItemTag.Func) {
this.func = func;
}
}
export final class InterfaceUse extends InterfaceItem {
new(use: Use) : super(InterfaceItemTag.Use) {
this.use = use;
}
}
/**
* A use statement in an interface.
*/
export class Use {
var docs: Docs;
var from: UsePath;
var names: GrowableArray<UseName>;
new(docs: Docs, from: UsePath, names: GrowableArray<UseName>) : docs = docs, from = from, names = names;
}
/**
* An interface definition.
*/
export class InterfaceDef {
var docs: Docs;
var name: Id;
var items = new GrowableArray<InterfaceItem>();
var isInline = false;
var packageIndex = 0;
new(docs: Docs, name: Id) : docs = docs, name = name;
}
// ============================================================================
// World Items
// ============================================================================
/**
* Tag for ExternKind (import/export kind).
*/
export enum ExternKindTag {
Interface, // import/export an inline interface
Path, // import/export a path reference
Func, // import/export a function
}
/**
* The kind of an import or export.
*/
export sealed class ExternKind {
case InterfaceExtern, PathExtern, FuncExtern
var tag: ExternKindTag;
var name: Id | null = null; // For Interface and Func
var items: GrowableArray<InterfaceItem> | null = null; // For Interface
var path: UsePath | null = null; // For Path
var funcDef: Func | null = null; // For Func
new(this.tag);
static iface(name: Id, items: GrowableArray<InterfaceItem>): ExternKind {
return new InterfaceExtern(name, items);
}
static fromPath(path: UsePath): ExternKind {
return new PathExtern(path);
}
static makeFunc(name: Id, f: Func): ExternKind {
return new FuncExtern(name, f);
}
}
export final class InterfaceExtern extends ExternKind {
new(name: Id, items: GrowableArray<InterfaceItem>) : super(ExternKindTag.Interface) {
this.name = name;
this.items = items;
}
}
export final class PathExtern extends ExternKind {
new(path: UsePath) : super(ExternKindTag.Path) {
this.path = path;
}
}
export final class FuncExtern extends ExternKind {
new(name: Id, funcDef: Func) : super(ExternKindTag.Func) {
this.name = name;
this.funcDef = funcDef;
}
}
/**
* An import in a world.
*/
export class Import {
var docs: Docs;
var kind: ExternKind;
new(docs: Docs, kind: ExternKind) : docs = docs, kind = kind;
}
/**
* An export in a world.
*/
export class Export {
var docs: Docs;
var kind: ExternKind;
new(docs: Docs, kind: ExternKind) : docs = docs, kind = kind;
}
/**
* An include statement in a world.
*/
export class Include {
var docs: Docs;
var from: UsePath;
var names: GrowableArray<IncludeName>;
new(docs: Docs, from: UsePath, names: GrowableArray<IncludeName>) : docs = docs, from = from, names = names;
}
/**
* A name in an include statement.
*/
export class IncludeName {
var name: Id;
var asName: Id;
new(name: Id, asName: Id) : name = name, asName = asName;
}
/**
* Tag for WorldItem kinds.
*/
export enum WorldItemTag {
Import,
Export,
Use,
TypeDef,
Include,
}
/**
* An item in a world.
*/
export sealed class WorldItem {
case WorldImport, WorldExport, WorldUse, WorldTypeDef, WorldInclude
var tag: WorldItemTag;
var importItem: Import | null = null;
var exportItem: Export | null = null;
var use: Use | null = null;
var typeDef: TypeDef | null = null;
var include: Include | null = null;
var isIncluded = false;
var isExplicit = false;
var packageIndex: i32 = 0 - 1; // -1
var inheritedDocs: Docs | null = null;
new(this.tag);
static fromImport(i: Import): WorldItem {
return new WorldImport(i);
}
static fromExport(e: Export): WorldItem {
return new WorldExport(e);
}
static fromUse(u: Use): WorldItem {
return new WorldUse(u);
}
static fromTypeDef(td: TypeDef): WorldItem {
return new WorldTypeDef(td);
}
static fromInclude(i: Include): WorldItem {
return new WorldInclude(i);
}
}
export final class WorldImport extends WorldItem {
new(importItem: Import) : super(WorldItemTag.Import) {
this.importItem = importItem;
}
}
export final class WorldExport extends WorldItem {
new(exportItem: Export) : super(WorldItemTag.Export) {
this.exportItem = exportItem;
}
}
export final class WorldUse extends WorldItem {
new(use: Use) : super(WorldItemTag.Use) {
this.use = use;
}
}
export final class WorldTypeDef extends WorldItem {
new(typeDef: TypeDef) : super(WorldItemTag.TypeDef) {
this.typeDef = typeDef;
}
}
export final class WorldInclude extends WorldItem {
new(include: Include) : super(WorldItemTag.Include) {
this.include = include;
}
}
/**
* A world definition.
*/
export class WorldDef {
var docs: Docs;
var name: Id;
var items = new GrowableArray<WorldItem>();
var packageIndex = 0;
new(docs: Docs, name: Id) : docs = docs, name = name;
}
// ============================================================================
// Top-level Items
// ============================================================================
/**
* A top-level use statement.
*/
export class ToplevelUse {
var item: UsePath;
var asName: Id | null = null;
new(item: UsePath) : item = item;
}
/**
* A nested package definition: `package foo:bar { ... }`
*/
export class NestedPackage {
var docs: Docs;
var name: PackageName;
var items = new GrowableArray<AstItem>();
new(docs: Docs, name: PackageName) : docs = docs, name = name;
}
/**
* Tag for AstItem kinds.
*/
export enum AstItemTag {
Interface,
World,
Use,
}
/**
* A top-level item in a WIT file.
*/
export sealed class AstItem {
case AstInterface, AstWorld, AstUse
var tag: AstItemTag;
var interfaceDef: InterfaceDef | null = null;
var worldDef: WorldDef | null = null;
var use: ToplevelUse | null = null;
new(this.tag);
static fromInterface(i: InterfaceDef): AstItem {
return new AstInterface(i);
}
static fromWorld(w: WorldDef): AstItem {
return new AstWorld(w);
}
static fromUse(u: ToplevelUse): AstItem {
return new AstUse(u);
}
}
export final class AstInterface extends AstItem {
new(interfaceDef: InterfaceDef) : super(AstItemTag.Interface) {
this.interfaceDef = interfaceDef;
}
}
export final class AstWorld extends AstItem {
new(worldDef: WorldDef) : super(AstItemTag.World) {
this.worldDef = worldDef;
}
}
export final class AstUse extends AstItem {
new(use: ToplevelUse) : super(AstItemTag.Use) {
this.use = use;
}
}
/**
* A parsed WIT file (unresolved).
*/
export class Ast {
var packageName: PackageName | null = null;
/** Doc comments on the package declaration. */
var packageDocs: Docs | null = null;
var items = new GrowableArray<AstItem>();
/** Nested packages defined inline: `package foo:bar { ... }` */
var nestedPackages = new GrowableArray<NestedPackage>();
}
// ============================================================================
// Parser
// ============================================================================
/**
* A recursive descent parser for WIT syntax.
*/
export class Parser {
#lexer: Lexer;
var #current: Token;
/**
* One token of pushback, filled only by #peekAhead(). The grammar is
* otherwise single-lookahead; versions are the exception, where a `.`
* may start another pre-release segment or may be the separator before
* `.{`, and telling them apart needs to see past it.
*/
var #peeked: Token | null = null;
#source: String;
new(source: String, lexer: Lexer, current: Token)
: #source = source, #lexer = lexer, #current = current;
// --------------------------------------------------------------------------
// Public API
// --------------------------------------------------------------------------
/**
* Parse a complete WIT file.
*/
static parse(source: String): Ast {
let lexer = new Lexer(source);
let parser = new Parser(source, lexer, lexer.next());
return parser.#parseAst();
}
// --------------------------------------------------------------------------
// Core Parsing Helpers
// --------------------------------------------------------------------------
/** Get current token without consuming it. */
#peek(): Token {
return this.#current;
}
/** Check if current token is of the given type. */
#check(type: TokenType): boolean {
return this.#current.type == type;
}
/** Consume current token and return it. */
#advance(): Token {
let token = this.#current;
if (this.#peeked != null) {
this.#current = this.#peeked as Token;
this.#peeked = null;
} else {
this.#current = this.#lexer.next();
}
return token;
}
/** The token after the current one. */
#peekAhead(): Token {
if (this.#peeked == null) {
this.#peeked = this.#lexer.next();
}
return this.#peeked as Token;
}
/**
* True when the current token is a `.` introducing another semver
* segment, rather than the `.` that separates a version from what
* follows it — `use foo:bar/baz@1.0.0-alpha.{a}` ends its version at
* `alpha`, and the next `.` belongs to the use path.
*/
#atVersionSegmentDot(): boolean {
if (!this.#check(TokenType.Period)) {
return false;
}
let next = this.#peekAhead().type;
return next == TokenType.Id || next == TokenType.Integer;
}
/** Consume current token if it matches, return true if consumed. */
#eat(type: TokenType): boolean {
if (this.#check(type)) {
this.#advance();
return true;
}
return false;
}
/** Expect current token to be of type, consume and return it. Throws on mismatch. */
#expect(type: TokenType): Token {
if (!this.#check(type)) {
throw new ParseError(
`expected ${describeToken(type)}, found ${describeToken(this.#current.type)}`,
this.#current.span
);
}
return this.#advance();
}
/** Expect a semicolon (with helpful error message). */
#expectSemicolon(): void {
this.#expect(TokenType.Semicolon);
}
/** Get the text for a span. */
#text(span: Span): String {
return this.#lexer.getSpanText(span);
}
// --------------------------------------------------------------------------
// Identifier Parsing
// --------------------------------------------------------------------------
/** Parse an identifier. */
#parseId(): Id {
let token = this.#peek();
if (token.type == TokenType.Id || token.type == TokenType.ExplicitId) {
this.#advance();
var text = this.#text(token.span);
if (token.type == TokenType.ExplicitId) {
// `%type`, `%flags`: the prefix only escapes a keyword, and is
// no part of the name. Every consumer — the resolver, the
// component encoder's export names, the synthesizer's Zena
// spellings — wants the name itself.
text = text.sliceBytes(1, text.length);
}
return new Id(text, token.span);
}
// A keyword where a name belongs — `world` as a parameter name,
// `type` as a field name — is a common mistake with a one character
// fix, so the message gives the fix. Everything else is only named.
if (isKeyword(token.type)) {
throw new ParseError(
`expected an identifier or string, found ${describeToken(token.type)}` +
`; write \`%${this.#text(token.span)}\` to use a keyword as a name`,
token.span);
}
throw new ParseError(
`expected an identifier or string, found ${describeToken(token.type)}`,
token.span);
}
// --------------------------------------------------------------------------
// Docs and Attribute Parsing
// --------------------------------------------------------------------------
/** Parse doc comments (/// comments) and attributes (@since, @unstable, @deprecated). */
#parseDocs(): Docs {
let docs = new Docs(this.#current.span);
// First, check for comments accumulated by the lexer (// and /* */ comments)
let precedingComments = this.#lexer.takePrecedingComments();
if (precedingComments != null) {
docs.contents = precedingComments;
}
// Collect consecutive doc comments (/// ...) - these take precedence
if (this.#check(TokenType.DocComment)) {
let sb = new StringBuilder();
var first = true;
while (this.#check(TokenType.DocComment)) {
let token = this.#advance();
// The span includes "/// " prefix and content
// Extract just the content part (after "/// ")
let text = this.#text(token.span);
// Strip the "/// " prefix (4 bytes if space follows, 3 bytes otherwise)
// text is at minimum "///" (3 chars) plus optional content
var content = text.sliceBytes(3, text.length);
if (text.length > 3 && text.getByteAt(3) == 32) {
content = text.sliceBytes(4, text.length);
}
// Strip trailing newline if present
if (content.length > 0 && content.getByteAt(content.length - 1) == 10) {
content = content.sliceBytes(0, content.length - 1);
}
if (!first) {
sb.append("\n");
}
sb.append(content);
first = false;
}
// If we had preceding comments, append doc comments; otherwise set
if (docs.contents != null) {
let existingContent = docs.contents as String;
let docCommentContent = sb.toString();
let combined = new StringBuilder();
combined.append(existingContent);
combined.append("\n");
combined.append(docCommentContent);
docs.contents = combined.toString();
} else {
docs.contents = sb.toString();
}
}
// Parse any attributes
if (this.#check(TokenType.At)) {
let attrs = new GrowableArray<Attribute>();
while (this.#check(TokenType.At)) {
attrs.push(this.#parseAttribute());
}
docs.attributes = attrs;
}
if (docs.contents != null) {
docs.contents = normalizeDocs(docs.contents as String);
}
return docs;
}
/**
* Parse a single attribute: @name(key = value)
* Supported: @since(version = x.y.z), @unstable(feature = name), @deprecated(version = x.y.z)
*/
#parseAttribute(): Attribute {
let startSpan = this.#expect(TokenType.At).span;
let name = this.#parseId();
let nameStr = name.name;
this.#expect(TokenType.LeftParen);
if (nameStr == "since") {
// @since(version = x.y.z)
this.#expectKeyword("version");
this.#expect(TokenType.Equals);
let version = this.#parseVersionString();
let endSpan = this.#expect(TokenType.RightParen).span;
return Attribute.since(version, new Span(startSpan.start, endSpan.end));
}
if (nameStr == "unstable") {
// @unstable(feature = name)
this.#expectKeyword("feature");
this.#expect(TokenType.Equals);
let feature = this.#parseId();
let endSpan = this.#expect(TokenType.RightParen).span;
return Attribute.unstable(feature, new Span(startSpan.start, endSpan.end));
}
if (nameStr == "deprecated") {
// @deprecated(version = x.y.z)
this.#expectKeyword("version");
this.#expect(TokenType.Equals);
let version = this.#parseVersionString();
let endSpan = this.#expect(TokenType.RightParen).span;
return Attribute.deprecated(version, new Span(startSpan.start, endSpan.end));
}
throw new ParseError("unknown attribute: expected `since`, `unstable`, or `deprecated`", name.span);
}
/** Parse a version string like 1.0.0 or 1.0.0-alpha.1+build */
#parseVersionString(): String {
let start = this.#peek().span.start;
// Parse: integer.integer.integer
this.#expect(TokenType.Integer);
this.#expect(TokenType.Period);
this.#expect(TokenType.Integer);
this.#expect(TokenType.Period);
var lastToken = this.#expect(TokenType.Integer);
var end = lastToken.span.end;
// Handle pre-release (-alpha.1) and build metadata (+build.123)
while (this.#check(TokenType.Minus) || this.#check(TokenType.Plus)) {
this.#advance();
while (this.#check(TokenType.Id) || this.#check(TokenType.Integer)) {
lastToken = this.#advance();
end = lastToken.span.end;
if (!this.#atVersionSegmentDot()) {
break;
}
this.#advance();
}
}
return this.#text(new Span(start, end));
}
/** Expect current token to be an identifier with a specific name. */
#expectKeyword(keyword: String): void {
let token = this.#peek();
if (token.type != TokenType.Id) {
throw new ParseError(`expected \`${keyword}\``, token.span);
}
let text = this.#text(token.span);
if (!(text == keyword)) {
throw new ParseError(`expected \`${keyword}\``, token.span);
}
this.#advance();
}
// --------------------------------------------------------------------------
// Package Name Parsing
// --------------------------------------------------------------------------
/** Parse a package name: namespace:name@version */
#parsePackageName(): PackageName {
let namespace = this.#parseId();
this.#expect(TokenType.Colon);
let name = this.#parseId();
let pkg = new PackageName(namespace, name, new Span(namespace.span.start, name.span.end));
// Optional version: @1.2.3
if (this.#eat(TokenType.At)) {
let versionStart = this.#peek().span.start;
// Parse version: integer.integer.integer with optional pre-release/build
this.#expect(TokenType.Integer);
this.#expect(TokenType.Period);
this.#expect(TokenType.Integer);
this.#expect(TokenType.Period);
var lastToken = this.#expect(TokenType.Integer);
var versionEnd = lastToken.span.end;
// Handle pre-release (-alpha.1) and build metadata (+build.123)
// Semver allows: 1.0.0-alpha, 1.0.0--, 1.0.0-alpha.1, etc.
while (this.#check(TokenType.Minus) || this.#check(TokenType.Plus)) {
lastToken = this.#advance();
versionEnd = lastToken.span.end;
// Consume identifier/integer/period parts until we hit something else
while (this.#check(TokenType.Id) || this.#check(TokenType.Integer) || this.#check(TokenType.Period)) {
lastToken = this.#advance();
versionEnd = lastToken.span.end;
}
}
let versionSpan = new Span(versionStart, versionEnd);
pkg.version = this.#text(versionSpan);
pkg.versionSpan = versionSpan;
pkg.span = new Span(namespace.span.start, versionEnd);
}
return pkg;
}
// --------------------------------------------------------------------------
// Use Path Parsing
// --------------------------------------------------------------------------
/** Parse a use path: id, id:id/id, or id:id@version/id */
#parseUsePath(): UsePath {
let id = this.#parseId();
// Check for package path: namespace:name/interface or namespace:name@version/interface
if (this.#eat(TokenType.Colon)) {
return this.#parsePackagePath(id);
}
// Just an identifier
return UsePath.fromId(id);
}
/**
* Parse a package path once `namespace:` has been consumed.
*
* The version may sit after the package name or after the interface
* name — `wasi:clocks@0.2.8/monotonic-clock` and
* `wasi:clocks/monotonic-clock@0.2.8` are both legal, and real WASI
* uses the second. Shared with world import/export, which previously
* had its own copy that accepted only the first.
*/
#parsePackagePath(id: Id): UsePath {
let pkgName = this.#parseId();
var version: String | null = null;
var versionSpan: Span | null = null;
if (this.#eat(TokenType.At)) {
let parsed = this.#parseVersion();
version = parsed.version;
versionSpan = parsed.span;
}
this.#expect(TokenType.Slash);
let interfaceName = this.#parseId();
if (version == null && this.#eat(TokenType.At)) {
let parsed = this.#parseVersion();
version = parsed.version;
versionSpan = parsed.span;
}
let pkgId = new PackageName(id, pkgName, new Span(id.span.start, pkgName.span.end));
pkgId.version = version;
pkgId.versionSpan = versionSpan;
return UsePath.fromPackage(pkgId, interfaceName);
}
/** Parse a semver version string. Returns the version text and span. */
#parseVersion(): {version: String, span: Span} {
let versionStart = this.#peek().span.start;
this.#expect(TokenType.Integer);
this.#expect(TokenType.Period);
this.#expect(TokenType.Integer);
this.#expect(TokenType.Period);
var lastToken = this.#expect(TokenType.Integer);
var versionEnd = lastToken.span.end;
// Handle pre-release and build metadata
while (this.#check(TokenType.Minus) || this.#check(TokenType.Plus)) {
this.#advance();
while (this.#check(TokenType.Id) || this.#check(TokenType.Integer)) {
lastToken = this.#advance();
versionEnd = lastToken.span.end;
if (!this.#atVersionSegmentDot()) {
break;
}
this.#advance();
}
}
let span = new Span(versionStart, versionEnd);
return {version: this.#text(span), span: span};
}
// --------------------------------------------------------------------------
// Type Parsing
// --------------------------------------------------------------------------
/** Parse a type. */
#parseType(): Type {
let token = this.#peek();
// Primitive types
if (token.type == TokenType.U8) { this.#advance(); return Type.primitive(TypeTag.U8, token.span); }
if (token.type == TokenType.U16) { this.#advance(); return Type.primitive(TypeTag.U16, token.span); }
if (token.type == TokenType.U32) { this.#advance(); return Type.primitive(TypeTag.U32, token.span); }
if (token.type == TokenType.U64) { this.#advance(); return Type.primitive(TypeTag.U64, token.span); }
if (token.type == TokenType.S8) { this.#advance(); return Type.primitive(TypeTag.S8, token.span); }
if (token.type == TokenType.S16) { this.#advance(); return Type.primitive(TypeTag.S16, token.span); }
if (token.type == TokenType.S32) { this.#advance(); return Type.primitive(TypeTag.S32, token.span); }
if (token.type == TokenType.S64) { this.#advance(); return Type.primitive(TypeTag.S64, token.span); }
if (token.type == TokenType.F32) { this.#advance(); return Type.primitive(TypeTag.F32, token.span); }
if (token.type == TokenType.F64) { this.#advance(); return Type.primitive(TypeTag.F64, token.span); }
if (token.type == TokenType.Char) { this.#advance(); return Type.primitive(TypeTag.Char, token.span); }
if (token.type == TokenType.Bool) { this.#advance(); return Type.primitive(TypeTag.Bool, token.span); }
if (token.type == TokenType.String) { this.#advance(); return Type.primitive(TypeTag.String, token.span); }
if (token.type == TokenType.ErrorContext) { this.#advance(); return Type.primitive(TypeTag.ErrorContext, token.span); }
// list<T> or list<T, N> (fixed-size list)
if (token.type == TokenType.List) {
this.#advance();
this.#expect(TokenType.LessThan);
let inner = this.#parseType();
var len = -1;
// Optional: fixed size (e.g., list<u32, 4>)
if (this.#eat(TokenType.Comma)) {
// Parse size - must be an integer literal
let sizeToken = this.#expect(TokenType.Integer);
let sizeText = this.#source.sliceBytes(sizeToken.span.start, sizeToken.span.end);
if (let (true, val) = parseI32(sizeText)) {
len = val;
}
}
let endToken = this.#expect(TokenType.GreaterThan);
let t = Type.list(inner, new Span(token.span.start, endToken.span.end));
t.fixedLength = len;
return t;
}
// option<T>
if (token.type == TokenType.Option) {
this.#advance();
this.#expect(TokenType.LessThan);
let inner = this.#parseType();
let endToken = this.#expect(TokenType.GreaterThan);
return Type.option(inner, new Span(token.span.start, endToken.span.end));
}
// result<O, E> or result<O> or result
if (token.type == TokenType.Result) {
this.#advance();
var okType: Type | null = null;
var errType: Type | null = null;
var endSpan = token.span;
if (this.#eat(TokenType.LessThan)) {
// Check for underscore (no ok type)
if (this.#check(TokenType.Underscore)) {
this.#advance();
} else {
okType = this.#parseType();
}
if (this.#eat(TokenType.Comma)) {
// Check for underscore (no err type)
if (this.#check(TokenType.Underscore)) {
this.#advance();
} else {
errType = this.#parseType();
}
}
let endToken = this.#expect(TokenType.GreaterThan);
endSpan = endToken.span;
}
return Type.result(okType, errType, new Span(token.span.start, endSpan.end));
}
// tuple<T1, T2, ...>
if (token.type == TokenType.Tuple) {
this.#advance();
this.#expect(TokenType.LessThan);
let types = new GrowableArray<Type>();
if (!this.#check(TokenType.GreaterThan)) {
types.push(this.#parseType());
while (this.#eat(TokenType.Comma)) {
// Allow trailing comma
if (this.#check(TokenType.GreaterThan)) break;
types.push(this.#parseType());
}
}
let endToken = this.#expect(TokenType.GreaterThan);
return Type.tuple(types, new Span(token.span.start, endToken.span.end));
}
// future<T> or future
if (token.type == TokenType.Future) {
this.#advance();
var inner: Type | null = null;
var endSpan = token.span;
if (this.#eat(TokenType.LessThan)) {
inner = this.#parseType();
let endToken = this.#expect(TokenType.GreaterThan);
endSpan = endToken.span;
}
return Type.future(inner, new Span(token.span.start, endSpan.end));
}
// stream<T> or stream
if (token.type == TokenType.Stream) {
this.#advance();
var inner: Type | null = null;
var endSpan = token.span;
if (this.#eat(TokenType.LessThan)) {
inner = this.#parseType();
let endToken = this.#expect(TokenType.GreaterThan);
endSpan = endToken.span;
}
return Type.stream(inner, new Span(token.span.start, endSpan.end));
}
// map<K, V>
if (token.type == TokenType.Map) {
this.#advance();
this.#expect(TokenType.LessThan);
let keyType = this.#parseType();
this.#expect(TokenType.Comma);
let valueType = this.#parseType();
let endToken = this.#expect(TokenType.GreaterThan);
return Type.map(keyType, valueType, new Span(token.span.start, endToken.span.end));
}
// own<T> - inner must be an identifier, not a primitive
if (token.type == TokenType.Own) {
let startSpan = token.span;
this.#advance();
this.#expect(TokenType.LessThan);
let innerToken = this.#peek();
if (innerToken.type != TokenType.Id && innerToken.type != TokenType.ExplicitId) {
throw new ParseError(`expected an identifier or string, found keyword \`${this.#text(innerToken.span)}\``, innerToken.span);
}
let id = this.#parseId();
let inner = Type.named(id, id.span);
let endToken = this.#expect(TokenType.GreaterThan);
return Type.own(inner, new Span(startSpan.start, endToken.span.end));
}
// borrow<T> - inner must be an identifier, not a primitive
if (token.type == TokenType.Borrow) {
let startSpan = token.span;
this.#advance();
this.#expect(TokenType.LessThan);
let innerToken = this.#peek();
if (innerToken.type != TokenType.Id && innerToken.type != TokenType.ExplicitId) {
throw new ParseError(`expected an identifier or string, found keyword \`${this.#text(innerToken.span)}\``, innerToken.span);
}
let id = this.#parseId();
let inner = Type.named(id, id.span);
let endToken = this.#expect(TokenType.GreaterThan);
return Type.borrow(inner, new Span(startSpan.start, endToken.span.end));
}
// Named type reference (identifier)
if (token.type == TokenType.Id || token.type == TokenType.ExplicitId) {
let id = this.#parseId();
return Type.named(id, id.span);
}
throw new ParseError("expected type", token.span);
}
// --------------------------------------------------------------------------
// Function Parsing
// --------------------------------------------------------------------------
/** Parse a function signature: func(params) -> result */
#parseFunc(): Func {
let isAsync = this.#eat(TokenType.Async);
let startToken = this.#expect(TokenType.Func);
let func = new Func(startToken.span);
func.isAsync = isAsync;
// Parameters
this.#expect(TokenType.LeftParen);
if (!this.#check(TokenType.RightParen)) {
func.params.push(this.#parseParam());
while (this.#eat(TokenType.Comma)) {
if (this.#check(TokenType.RightParen)) break; // Allow trailing comma
func.params.push(this.#parseParam());
}
}
this.#expect(TokenType.RightParen);
// Optional result
if (this.#eat(TokenType.RArrow)) {
func.result = this.#parseType();
}
return func;
}
/**
* Parse a function parameter: name: type
*
* WIT allows a doc comment on a parameter, and real WASI uses them
* heavily — wasi:io/streams documents most of its arguments this way.
* They carry no meaning downstream (Param has nowhere to put them, and
* the wasm-tools JSON does not record them), but they must be consumed
* or the `///` is met where an identifier is expected.
*/
#parseParam(): Param {
this.#parseDocs();
let name = this.#parseId();
this.#expect(TokenType.Colon);
let type = this.#parseType();
return new Param(name, type);
}
// --------------------------------------------------------------------------
// Type Definition Parsing
// --------------------------------------------------------------------------
/** Parse a type definition. */
#parseTypeDef(docs: Docs): TypeDef {
let token = this.#peek();
// type name = aliased-type;
if (token.type == TokenType.Type) {
this.#advance();
let name = this.#parseId();
this.#expect(TokenType.Equals);
let type = this.#parseType();
this.#expectSemicolon();
return TypeDef.alias(docs, name, type);
}
// record name { fields }
if (token.type == TokenType.Record) {
this.#advance();
let name = this.#parseId();
let fields = this.#parseList<Field>(
TokenType.LeftBrace,
TokenType.RightBrace,
() => this.#parseField()
);
return TypeDef.record(docs, name, fields);
}
// flags name { flags }
if (token.type == TokenType.Flags) {
this.#advance();
let name = this.#parseId();
let flags = this.#parseList<FlagDef>(
TokenType.LeftBrace,
TokenType.RightBrace,
() => this.#parseFlagDef()
);
return TypeDef.flagsDef(docs, name, flags);
}
// variant name { cases }
if (token.type == TokenType.Variant) {
this.#advance();
let name = this.#parseId();
let cases = this.#parseList<Case>(
TokenType.LeftBrace,
TokenType.RightBrace,
() => this.#parseCase()
);
return TypeDef.variant(docs, name, cases);
}
// enum name { cases }
if (token.type == TokenType.Enum) {
this.#advance();
let name = this.#parseId();
let cases = this.#parseList<EnumCaseDef>(
TokenType.LeftBrace,
TokenType.RightBrace,
() => this.#parseEnumCase()
);
return TypeDef.enumDef(docs, name, cases);
}
// resource name { methods }
if (token.type == TokenType.Resource) {
this.#advance();
let name = this.#parseId();
// Resources can be empty (just a declaration) or have a body
let funcs = new GrowableArray<ResourceFunc>();
if (this.#eat(TokenType.LeftBrace)) {
while (!this.#check(TokenType.RightBrace)) {
let funcDocs = this.#parseDocs();
funcs.push(this.#parseResourceFunc(funcDocs));
}
this.#expect(TokenType.RightBrace);
} else {
this.#expectSemicolon();
}
return TypeDef.resource(docs, name, funcs);
}
throw new ParseError("expected type definition", token.span);
}
/** Parse a record field: name: type */
#parseField(): Field {
let docs = this.#parseDocs();
let name = this.#parseId();
this.#expect(TokenType.Colon);
let type = this.#parseType();
return new Field(docs, name, type);
}
/** Parse a flag: name */
#parseFlagDef(): FlagDef {
let docs = this.#parseDocs();
let name = this.#parseId();
return new FlagDef(docs, name);
}
/** Parse a variant case: name or name(type) */
#parseCase(): Case {
let docs = this.#parseDocs();
let name = this.#parseId();
let c = new Case(docs, name);
// Optional payload type in parentheses
if (this.#eat(TokenType.LeftParen)) {
c.type = this.#parseType();
this.#expect(TokenType.RightParen);
}
return c;
}
/** Parse an enum case: name */
#parseEnumCase(): EnumCaseDef {
let docs = this.#parseDocs();
let name = this.#parseId();
return new EnumCaseDef(docs, name);
}
/** Parse a resource function: constructor, method, or static. */
#parseResourceFunc(docs: Docs): ResourceFunc {
let token = this.#peek();
// constructor(params) or constructor(params) -> result
if (token.type == TokenType.Constructor) {
this.#advance();
this.#expect(TokenType.LeftParen);
let params = new GrowableArray<Param>();
if (!this.#check(TokenType.RightParen)) {
params.push(this.#parseParam());
while (this.#eat(TokenType.Comma)) {
if (this.#check(TokenType.RightParen)) break;
params.push(this.#parseParam());
}
}
this.#expect(TokenType.RightParen);
let func = new Func(token.span);
func.params = params;
// Optional return type for constructor (e.g., constructor() -> result<T>)
if (this.#eat(TokenType.RArrow)) {
func.result = this.#parseType();
}
this.#expectSemicolon();
let namedFunc = new NamedFunc(docs, new Id("constructor", token.span), func);
return new ResourceFunc(ResourceFuncTag.Constructor, namedFunc);
}
// name: func(...) or name: static func(...)
let name = this.#parseId();
this.#expect(TokenType.Colon);
// Check for static
let isStatic = this.#eat(TokenType.Static);
let func = this.#parseFunc();
this.#expectSemicolon();
let namedFunc = new NamedFunc(docs, name, func);
if (isStatic) {
return new ResourceFunc(ResourceFuncTag.Static, namedFunc);
}
return new ResourceFunc(ResourceFuncTag.Method, namedFunc);
}
// --------------------------------------------------------------------------
// Interface Parsing
// --------------------------------------------------------------------------
/** Parse an interface definition. */
#parseInterface(docs: Docs): InterfaceDef {
this.#expect(TokenType.Interface);
let name = this.#parseId();
let iface = new InterfaceDef(docs, name);
this.#expect(TokenType.LeftBrace);
while (!this.#check(TokenType.RightBrace)) {
let itemDocs = this.#parseDocs();
iface.items.push(this.#parseInterfaceItem(itemDocs));
}
this.#expect(TokenType.RightBrace);
return iface;
}
/** Parse an interface item. */
#parseInterfaceItem(docs: Docs): InterfaceItem {
let token = this.#peek();
// use path.{names};
if (token.type == TokenType.Use) {
return InterfaceItem.fromUse(this.#parseUse(docs));
}
// Type definitions
if (token.type == TokenType.Type ||
token.type == TokenType.Record ||
token.type == TokenType.Flags ||
token.type == TokenType.Variant ||
token.type == TokenType.Enum ||
token.type == TokenType.Resource) {
return InterfaceItem.fromTypeDef(this.#parseTypeDef(docs));
}
// Function: name: func(...);
if (token.type == TokenType.Id || token.type == TokenType.ExplicitId) {
let name = this.#parseId();
this.#expect(TokenType.Colon);
let func = this.#parseFunc();
this.#expectSemicolon();
return InterfaceItem.fromFunc(new NamedFunc(docs, name, func));
}
throw new ParseError("expected interface item", token.span);
}
/** Parse a use statement: use path.{names}; */
#parseUse(docs: Docs): Use {
this.#expect(TokenType.Use);
let from = this.#parseUsePath();
this.#expect(TokenType.Period);
let names = this.#parseList<UseName>(
TokenType.LeftBrace,
TokenType.RightBrace,
() => this.#parseUseName()
);
this.#expectSemicolon();
return new Use(docs, from, names);
}
/** Parse a use name: name or name as alias */
#parseUseName(): UseName {
let name = this.#parseId();
let useName = new UseName(name);
if (this.#eat(TokenType.As)) {
useName.asName = this.#parseId();
}
return useName;
}
// --------------------------------------------------------------------------
// World Parsing
// --------------------------------------------------------------------------
/** Parse a world definition. */
#parseWorld(docs: Docs): WorldDef {
this.#expect(TokenType.World);
let name = this.#parseId();
let world = new WorldDef(docs, name);
this.#expect(TokenType.LeftBrace);
while (!this.#check(TokenType.RightBrace)) {
let itemDocs = this.#parseDocs();
world.items.push(this.#parseWorldItem(itemDocs));
}
this.#expect(TokenType.RightBrace);
return world;
}
/** Parse a world item. */
#parseWorldItem(docs: Docs): WorldItem {
let token = this.#peek();
// import ...
if (token.type == TokenType.Import) {
this.#advance();
let kind = this.#parseExternKind();
return WorldItem.fromImport(new Import(docs, kind));
}
// export ...
if (token.type == TokenType.Export) {
this.#advance();
let kind = this.#parseExternKind();
return WorldItem.fromExport(new Export(docs, kind));
}
// use path.{names};
if (token.type == TokenType.Use) {
return WorldItem.fromUse(this.#parseUse(docs));
}
// include path;
if (token.type == TokenType.Include) {
return WorldItem.fromInclude(this.#parseInclude(docs));
}
// Type definitions
if (token.type == TokenType.Type ||
token.type == TokenType.Record ||
token.type == TokenType.Flags ||
token.type == TokenType.Variant ||
token.type == TokenType.Enum ||
token.type == TokenType.Resource) {
return WorldItem.fromTypeDef(this.#parseTypeDef(docs));
}
throw new ParseError("expected world item", token.span);
}
/** Parse an import/export kind. */
#parseExternKind(): ExternKind {
let token = this.#peek();
// Check for: name: interface { ... } or name: func(...)
if (token.type == TokenType.Id || token.type == TokenType.ExplicitId) {
let id = this.#parseId();
if (this.#eat(TokenType.Colon)) {
// name: interface { ... }
if (this.#eat(TokenType.Interface)) {
let items = new GrowableArray<InterfaceItem>();
this.#expect(TokenType.LeftBrace);
while (!this.#check(TokenType.RightBrace)) {
let itemDocs = this.#parseDocs();
items.push(this.#parseInterfaceItem(itemDocs));
}
this.#expect(TokenType.RightBrace);
return ExternKind.iface(id, items);
}
// name: [async] func(...)
if (this.#check(TokenType.Func) || this.#check(TokenType.Async)) {
let func = this.#parseFunc();
this.#expectSemicolon();
return ExternKind.makeFunc(id, func);
}
let path = this.#parsePackagePath(id);
this.#expectSemicolon();
return ExternKind.fromPath(path);
}
// Just a simple identifier path (local interface reference)
let path = UsePath.fromId(id);
this.#expectSemicolon();
return ExternKind.fromPath(path);
}
throw new ParseError("expected import/export kind", token.span);
}
/** Parse an include statement: include path; or include path with { renames } */
#parseInclude(docs: Docs): Include {
this.#expect(TokenType.Include);
let from = this.#parseUsePath();
var names = new GrowableArray<IncludeName>();
if (this.#eat(TokenType.With)) {
names = this.#parseList<IncludeName>(
TokenType.LeftBrace,
TokenType.RightBrace,
() => {
let name = this.#parseId();
this.#expect(TokenType.As);
let asName = this.#parseId();
return new IncludeName(name, asName);
}
);
} else {
this.#expectSemicolon();
}
return new Include(docs, from, names);
}
// --------------------------------------------------------------------------
// Top-level Parsing
// --------------------------------------------------------------------------
/** Parse a complete AST. */
#parseAst(): Ast {
let ast = new Ast();
var currentTopPackage: NestedPackage | null = null;
// Optional package declaration at start
var docs = this.#parseDocs();
if (this.#check(TokenType.Package)) {
this.#expect(TokenType.Package);
ast.packageName = this.#parsePackageName();
// Track if this package has docs
if (docs.contents != null) {
ast.packageDocs = docs;
}
this.#expectSemicolon();
docs = this.#parseDocs();
}
// Parse items until EOF
while (!this.#check(TokenType.Eof)) {
// Check for package keyword - could be nested or top-level declaration
if (this.#check(TokenType.Package)) {
// Peek ahead: nested package has `{`, top-level declaration has `;`
// Parse the package keyword and name first to check
this.#advance(); // consume 'package'
let name = this.#parsePackageName();
if (this.#check(TokenType.LeftBrace)) {
// Nested package: package name { ... }
let pkg = new NestedPackage(docs, name);
this.#expect(TokenType.LeftBrace);
while (!this.#check(TokenType.RightBrace) && !this.#check(TokenType.Eof)) {
let itemDocs = this.#parseDocs();
pkg.items.push(this.#parseAstItem(itemDocs));
}
this.#expect(TokenType.RightBrace);
ast.nestedPackages.push(pkg);
} else {
// Top-level package declaration (with semicolon)
this.#expectSemicolon();
if (ast.packageName == null) {
// First package - set as main package
ast.packageName = name;
// Track if this package has docs
if (docs.contents != null) {
ast.packageDocs = docs;
}
currentTopPackage = null;
} else {
// Check if this is the same package or a different package
let existing = ast.packageName as PackageName;
let existingKey = this.#packageKey(existing);
let newKey = this.#packageKey(name);
if (existingKey == newKey) {
// Same package as main
if (docs.contents != null && ast.packageDocs != null) {
throw new ParseError(
"found doc comments on multiple 'package' items",
name.span
);
}
if (docs.contents != null) {
ast.packageDocs = docs;
}
currentTopPackage = null;
} else {
// Different package
let existingNested = this.#findNestedPackage(ast.nestedPackages, newKey);
if (existingNested != null) {
currentTopPackage = existingNested;
} else {
let pkg = new NestedPackage(docs, name);
ast.nestedPackages.push(pkg);
currentTopPackage = pkg;
}
}
}
}
docs = this.#parseDocs();
continue;
}
if (currentTopPackage != null) {
let pkg = currentTopPackage;
pkg.items.push(this.#parseAstItem(docs));
} else {
ast.items.push(this.#parseAstItem(docs));
}
docs = this.#parseDocs();
}
return ast;
}
/** Build a package lookup key including version if present. */
#packageKey(name: PackageName): String {
var key = `${name.namespace.name}:${name.name.name}`;
if (name.version != null) {
key = `${key}@${name.version as String}`;
}
return key;
}
/** Find an existing nested package by key. */
#findNestedPackage(packages: GrowableArray<NestedPackage>, key: String): NestedPackage | null {
for (let pkg in packages) {
let pkgKey = this.#packageKey(pkg.name);
if (pkgKey == key) {
return pkg;
}
}
return null;
}
/** Parse a top-level item. */
#parseAstItem(docs: Docs): AstItem {
let token = this.#peek();
// interface name { ... }
if (token.type == TokenType.Interface) {
return AstItem.fromInterface(this.#parseInterface(docs));
}
// world name { ... }
if (token.type == TokenType.World) {
return AstItem.fromWorld(this.#parseWorld(docs));
}
// use path;
if (token.type == TokenType.Use) {
this.#advance();
let item = this.#parseUsePath();
let use = new ToplevelUse(item);
if (this.#eat(TokenType.As)) {
use.asName = this.#parseId();
}
this.#expectSemicolon();
return AstItem.fromUse(use);
}
throw new ParseError("expected `interface`, `world`, or `use`", token.span);
}
// --------------------------------------------------------------------------
// List Parsing Helper
// --------------------------------------------------------------------------
/** Parse a comma-separated list with delimiters. */
#parseList<T>(
open: TokenType,
close: TokenType,
parseItem: () => T
): GrowableArray<T> {
let items = new GrowableArray<T>();
this.#expect(open);
if (!this.#check(close)) {
items.push(parseItem());
while (this.#eat(TokenType.Comma)) {
if (this.#check(close)) break; // Allow trailing comma
items.push(parseItem());
}
}
this.#expect(close);
return items;
}
}
| Version | Published | Dependencies | Approved by |
|---|---|---|---|
| 0.0.1-preview.1 | 2026-11-19 | none |
|