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.
/**
* Assembling and querying WIT documents, for the parser's consumers.
*
* The parser takes a source string; these are the steps just before
* and after it that every consumer repeats — joining a package
* directory's files into one document in a canonical way, finding an
* interface in the parsed result, and naming the file and line a
* failure happened at. They live here rather than in each consumer
* because their behavior is contract: the compiler's `--wit` flag and
* its WIT-backed packages must agree on what "a directory of WIT"
* means, whether the host reads it from disk or holds it in memory.
*
* Nothing here does I/O. The caller reads the files.
*/
import { StringBuilder } from 'zena:core';
import { Span } from './token.zena';
import { LexError } from './lexer.zena';
import {
Ast, AstItem, AstItemTag, InterfaceDef, PackageName, ParseError
} from './parser.zena';
import { ResolveError } from './resolver.zena';
/** Byte-wise string order, for a listing that reads the same everywhere. */
function byteCompare(a: String, b: String) {
var minLen = a.length;
if (b.length < minLen) {
minLen = b.length;
}
for (var i = 0; i < minLen; i += 1) {
let d = a.getByteAt(i) - b.getByteAt(i);
if (d != 0) {
return d;
}
}
return a.length - b.length;
}
/** One file of a WIT package directory: its name and its text. */
export final class WitFile {
name: String;
source: String;
new(this.name, this.source);
}
/** Where one of a joined document's files begins in it. */
export final class WitFileStart {
name: String;
start: i32;
new(this.name, this.start);
}
/** Where a byte offset in a document falls, for a reader to go look. */
export final class WitLocation {
/** The file the offset came from, named as the document's files were. */
file: String;
/** 1-based line within that file. */
line: i32;
/** 1-based column, in bytes. */
column: i32;
new(this.file, this.line, this.column);
}
/**
* A joined document and where each of its files begins in it.
*
* A directory of WIT is parsed as one document, so a `Span` from the
* parser is an offset into the concatenation while a reader needs a
* file and a line in it. The starts are recorded as the document is
* joined, which keeps `locate` the only code that knows how it was put
* together.
*/
export final class WitDocument {
/** The joined source, as the parser sees it. */
source: String;
/** Each `.wit` file in document order. Empty for an empty document. */
files: Array<WitFileStart>;
new(this.source, this.files);
/** Which file `offset` is in, and where in it. */
locate(offset: i32): WitLocation {
var at = offset;
if (at < 0) { at = 0; }
if (at > this.source.length) { at = this.source.length; }
var file = "";
var fileStart = 0;
for (let f in this.files) {
if (f.start <= at) {
file = f.name;
fileStart = f.start;
}
}
// Lines count from the file's own start, not the document's, so the
// number is the one an editor shows.
var line = 1;
var lineStart = fileStart;
for (var i = fileStart; i < at; i += 1) {
if (this.source.getByteAt(i) == 10) { // '\n'
line += 1;
lineStart = i + 1;
}
}
return new WitLocation(file, line, at - lineStart + 1);
}
/** The text of the line `offset` is on, without its newline. */
lineTextAt(offset: i32): String {
var at = offset;
if (at < 0) { at = 0; }
if (at > this.source.length) { at = this.source.length; }
var start = at;
while (start > 0 && this.source.getByteAt(start - 1) != 10) {
start -= 1;
}
var end = at;
while (end < this.source.length && this.source.getByteAt(end) != 10) {
end += 1;
}
return this.source.sliceBytes(start, end);
}
}
/**
* The document a directory of WIT makes: its `.wit` files concatenated
* in byte order of their names, each followed by a newline, and where
* each of them begins in the result. Files with other extensions are
* left out, and with no `.wit` files the document is empty.
*/
export function joinWitDocument(files: Array<WitFile>): WitDocument {
let wit = new GrowableArray<WitFile>();
for (let file in files) {
if (file.name.endsWith(".wit")) {
wit.push(file);
}
}
// Name order, so the document is the same however the host lists.
for (var a = 0; a < wit.length; a += 1) {
for (var b = a + 1; b < wit.length; b += 1) {
if (byteCompare(wit[b].name, wit[a].name) < 0) {
let t = wit[a];
wit[a] = wit[b];
wit[b] = t;
}
}
}
let starts = new Array<WitFileStart>();
var source = "";
for (let file in wit) {
starts.push(new WitFileStart(file.name, source.length));
source = `${source}${file.source}\n`;
}
return new WitDocument(source, starts);
}
/**
* `joinWitDocument`'s source alone, for a caller with nothing to
* report against it.
*/
export function joinWitFiles(files: Array<WitFile>): String {
return joinWitDocument(files).source;
}
/**
* The span `e` happened at, when `e` is one of the three failures the
* parser raises against a document: `LexError`, `ParseError`,
* `ResolveError`. Anything else is a fault in the parser itself and
* carries no position.
*/
export function witErrorSpan(e: Error): Span | null {
if (e is LexError) {
return e.span;
}
if (e is ParseError) {
return e.span;
}
if (e is ResolveError) {
return e.span;
}
return null;
}
/**
* `e` rendered against `doc` as a terminal diagnostic: the file, line
* and column it happened at, then the offending line and an underline.
* The header is `file:line:column - Error: `, which is what the Zena
* compiler's own syntax errors carry.
*
* Null when `e` carries no span, and null when its span is past the end
* of `doc`: the compiler splices a program's WIT-backed packages onto a
* document before parsing it, and a failure in that spliced text has no
* file this document can name. The caller reports the message plainly.
*/
export function witDiagnostic(doc: WitDocument, e: Error): String | null {
let span = witErrorSpan(e);
if (span == null) {
return null;
}
let at = span;
if (at.start > doc.source.length) {
return null;
}
let loc = doc.locate(at.start);
let sb = new StringBuilder();
sb.append(`${loc.file}:${loc.line}:${loc.column} - Error: ${e.message}\n`);
sb.append(`${doc.lineTextAt(at.start)}\n`);
for (var i = 1; i < loc.column; i += 1) {
sb.append(" ");
}
// A zero-width span — the end of the document — still gets one caret
// to point with.
var width = at.end - at.start;
if (width < 1) { width = 1; }
for (var i = 0; i < width; i += 1) {
sb.append("^");
}
return sb.toString();
}
/** One interface of a parsed document, with its package's name. */
export final class FoundInterface {
def: InterfaceDef;
packageName: PackageName;
new(this.def, this.packageName);
}
/**
* The interface `namespace:interfacePath` (`pkg/iface`) in `ast`, from
* the main package or a nested one.
*
* Versions are the WIT's own business — callers resolve by unversioned
* name — so matching ignores them, and two versions of one interface
* in the same document is an error rather than a guess.
*/
export function findInterface(
ast: Ast,
namespace: String,
interfacePath: String
): FoundInterface {
let found = findInterfaceOrNull(ast, namespace, interfacePath);
if (found == null) {
throw new Error("WIT interface '" + namespace + ":" + interfacePath +
"' is not declared by the package's WIT.");
}
return found;
}
/** `findInterface`, but an absent interface is null rather than a
* throw — for callers with their own way of saying no, like a `use`
* hop reported as a per-member skip. A duplicate still throws. */
export function findInterfaceOrNull(
ast: Ast,
namespace: String,
interfacePath: String
): FoundInterface | null {
var found: FoundInterface | null = null;
var matches = 0;
let consider = (pkg: PackageName | null, items: Array<AstItem>) => {
if (pkg == null) {
return;
}
let p = pkg;
for (let item in items) {
if (item.tag != AstItemTag.Interface) {
continue;
}
let def = item.interfaceDef as InterfaceDef;
let path = `${p.name.name}/${def.name.name}`;
if (p.namespace.name == namespace && path == interfacePath) {
found = new FoundInterface(def, p);
matches += 1;
}
}
};
consider(ast.packageName, ast.items);
for (let nested in ast.nestedPackages) {
consider(nested.name, nested.items);
}
if (matches > 1) {
throw new Error("WIT interface '" + namespace + ":" + interfacePath +
"' is declared more than once (differing versions?) — pin one.");
}
return found;
}
| Version | Published | Dependencies | Approved by |
|---|---|---|---|
| 0.0.1-preview.1 | 2026-11-19 | none |
|