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.
import {PackageName, Id} from './parser.zena';
import {StringReader} from 'zena:core';
/** Normalize an identifier - strip '%' prefix if present (explicit escaping). */
export function normalizeId(name: String): String {
if (name.length > 0 && name.getByteAt(0) == 37) { // '%'
return name.sliceBytes(1, name.length);
} else {
return name;
}
}
export function compareStrings(s1: String, s2: String): i32 {
let len1 = s1.length;
let len2 = s2.length;
let minLen = if (len1 < len2) len1 else len2;
for (var i = 0; i < minLen; i += 1) {
let b1 = s1.getByteAt(i);
let b2 = s2.getByteAt(i);
if (b1 < b2) {
return -1;
}
if (b1 > b2) {
return 1;
}
}
if (len1 < len2) {
return -1;
}
if (len1 > len2) {
return 1;
}
return 0;
}
export function isPurelyNumeric(s: String): boolean {
if (s.length == 0) return false;
for (var i = 0; i < s.length; i += 1) {
let b = s.getByteAt(i);
if (b < 48 || b > 57) {
return false;
}
}
return true;
}
export function stringToInt(s: String): i32 {
var val = 0;
for (var i = 0; i < s.length; i += 1) {
let b = s.getByteAt(i);
val = val * 10 + (b - 48);
}
return val;
}
function readInt(r: StringReader) {
var val = 0;
while (!r.isAtEnd) {
let b = r.peekByte();
if (b >= 48 && b <= 57) {
val = val * 10 + (b - 48);
r.advanceByte();
} else {
break;
}
}
return val;
}
export function getPreIdentifiers(s: String, start: i32, end: i32): Array<String> {
let arr = new GrowableArray<String>();
if (start < 0 || start >= end) return arr;
var curStart = start;
for (var i = start; i < end; i += 1) {
if (s.getByteAt(i) == 46) { // '.'
arr.push(s.sliceBytes(curStart, i));
curStart = i + 1;
}
}
if (curStart < end) {
arr.push(s.sliceBytes(curStart, end));
}
return arr;
}
export function compareVersions(v1: String, v2: String): i32 {
let r1 = new StringReader(v1);
let r2 = new StringReader(v2);
let maj1 = readInt(r1);
if (r1.peekByte() == 46) { r1.advanceByte(); } // '.'
let min1 = readInt(r1);
if (r1.peekByte() == 46) { r1.advanceByte(); } // '.'
let pat1 = readInt(r1);
let maj2 = readInt(r2);
if (r2.peekByte() == 46) { r2.advanceByte(); } // '.'
let min2 = readInt(r2);
if (r2.peekByte() == 46) { r2.advanceByte(); } // '.'
let pat2 = readInt(r2);
if (maj1 < maj2) return -1;
if (maj1 > maj2) return 1;
if (min1 < min2) return -1;
if (min1 > min2) return 1;
if (pat1 < pat2) return -1;
if (pat1 > pat2) return 1;
var hasPre1 = false;
var preStart1 = -1;
var buildStart1 = -1;
if (r1.peekByte() == 45) { // '-'
hasPre1 = true;
r1.advanceByte();
preStart1 = r1.position;
}
while (!r1.isAtEnd) {
if (r1.peekByte() == 43) { // '+'
buildStart1 = r1.position;
break;
}
r1.advanceByte();
}
let preEnd1 = if (buildStart1 >= 0) buildStart1 else r1.position;
var hasPre2 = false;
var preStart2 = -1;
var buildStart2 = -1;
if (r2.peekByte() == 45) { // '-'
hasPre2 = true;
r2.advanceByte();
preStart2 = r2.position;
}
while (!r2.isAtEnd) {
if (r2.peekByte() == 43) { // '+'
buildStart2 = r2.position;
break;
}
r2.advanceByte();
}
let preEnd2 = if (buildStart2 >= 0) buildStart2 else r2.position;
if (hasPre1 && !hasPre2) return -1;
if (!hasPre1 && hasPre2) return 1;
if (!hasPre1 && !hasPre2) {
return compareStrings(v1, v2);
}
let arr1 = getPreIdentifiers(v1, preStart1, preEnd1);
let arr2 = getPreIdentifiers(v2, preStart2, preEnd2);
let len1 = arr1.length;
let len2 = arr2.length;
let minLen = if (len1 < len2) len1 else len2;
for (var idx = 0; idx < minLen; idx += 1) {
let id1 = arr1[idx];
let id2 = arr2[idx];
let isNum1 = isPurelyNumeric(id1);
let isNum2 = isPurelyNumeric(id2);
if (isNum1 && isNum2) {
let n1 = stringToInt(id1);
let n2 = stringToInt(id2);
if (n1 < n2) return -1;
if (n1 > n2) return 1;
} else if (isNum1) {
return -1;
} else if (isNum2) {
return 1;
} else {
let comp = compareStrings(id1, id2);
if (comp != 0) return comp;
}
}
if (len1 < len2) return -1;
if (len1 > len2) return 1;
return compareStrings(v1, v2);
}
export function formatPackageName(name: PackageName | null): String {
if (name == null) { return ""; }
let n = name;
var result = `${normalizeId(n.namespace.name)}:${normalizeId(n.name.name)}`;
if (n.version != null) {
result = `${result}@${n.version as String}`;
}
return result;
}
export function comparePackageNames(pn1: PackageName | null, pn2: PackageName | null): i32 {
if (pn1 == null && pn2 == null) return 0;
if (pn1 == null) return -1;
if (pn2 == null) return 1;
let p1 = pn1;
let p2 = pn2;
let ns1 = normalizeId(p1.namespace.name);
let ns2 = normalizeId(p2.namespace.name);
let nsComp = compareStrings(ns1, ns2);
if (nsComp != 0) return nsComp;
let n1 = normalizeId(p1.name.name);
let n2 = normalizeId(p2.name.name);
let nComp = compareStrings(n1, n2);
if (nComp != 0) return nComp;
if (p1.version == null && p2.version == null) return 0;
if (p1.version == null) return -1;
if (p2.version == null) return 1;
return compareVersions(p1.version as String, p2.version as String);
}
export function comparePackageNameStrings(pkgOrder: Array<String>, k1: String, k2: String): i32 {
if (k1 == k2) return 0;
// Sort according to pkgOrder if both are present in the list
var idx1 = -1;
var idx2 = -1;
for (var pIdx = 0; pIdx < pkgOrder.length; pIdx += 1) {
if (pkgOrder[pIdx] == k1) { idx1 = pIdx; }
if (pkgOrder[pIdx] == k2) { idx2 = pIdx; }
}
if (idx1 >= 0 && idx2 >= 0) {
if (idx1 < idx2) return -1;
return 1;
}
let p1 = parsePackageParts(k1);
let p2 = parsePackageParts(k2);
let nsComp = compareStrings(p1.namespace, p2.namespace);
if (nsComp != 0) return nsComp;
let nComp = compareStrings(p1.name, p2.name);
if (nComp != 0) return nComp;
let hasVer1 = p1.version != null;
let hasVer2 = p2.version != null;
if (!hasVer1 && !hasVer2) return 0;
if (!hasVer1 && hasVer2) return -1;
if (hasVer1 && !hasVer2) return 1;
return compareVersions(p1.version as String, p2.version as String);
}
class PackageParts {
namespace: String;
name: String;
version: String | null;
new(this.namespace, this.name, this.version);
}
function parsePackageParts(name: String): PackageParts {
let colonParts = name.split(":");
var namespace = "";
var rest = name;
if (colonParts.length == 2) {
namespace = colonParts[0];
rest = colonParts[1];
}
let atParts = rest.split("@");
if (atParts.length == 2) {
return new PackageParts(namespace, atParts[0], atParts[1]);
}
return new PackageParts(namespace, rest, null);
}
export class PackageNameRef {
packageName: String;
version: String | null;
new(this.packageName, this.version);
}
export function parsePackageName(name: String): PackageNameRef {
let atParts = name.split("@");
if (atParts.length == 2) {
return new PackageNameRef(atParts[0], atParts[1]);
}
return new PackageNameRef(name, null);
}
export class InterfaceNameRef {
packageName: String;
version: String | null;
interfaceName: String;
new(this.packageName, this.version, this.interfaceName);
}
export function parseInterfaceName(name: String): InterfaceNameRef | null {
let slashParts = name.split("/");
if (slashParts.length != 2) {
return null;
}
let pkgRef = parsePackageName(slashParts[0]);
return new InterfaceNameRef(pkgRef.packageName, pkgRef.version, slashParts[1]);
}
| Version | Published | Dependencies | Approved by |
|---|---|---|---|
| 0.0.1-preview.1 | 2026-11-19 | none |
|