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.
/**
* The WIT parser's public entry point.
*
* Until now the only way in was `parser-test-harness.zena`, whose interface
* (`parse(): void` plus `getOutputByte(i)`) exists to be driven from a Wasm
* host one byte at a time. That is a test rig, not an API. This module is the
* callable surface: a consumer hands over WIT source and gets back a validated
* AST, or an exception describing what was wrong with it.
*
* The AST types themselves live in `parser.zena`, which the package also
* exports — walking a document means touching most of 87 declarations, so
* mirroring them here would be a maintenance tax with no benefit. Only the
* handful needed to call these functions and catch their failures are
* re-exported below.
*
* Names are unqualified because the module already says what they are about —
* an importer wanting `parseWit` can rename at the import site.
*
* import {parse} from 'zena-lang:wit-parser';
* import {AstItemTag} from 'zena-lang:wit-parser/parser';
*
* let doc = parse(source);
*
* Errors are thrown rather than returned. `Result<T, E>` is an inline
* multi-value union (docs/design/result-option.md) but is not in the stdlib
* yet; once it is, a non-throwing variant can be added alongside these without
* disturbing callers.
*/
import { Parser, Ast } from './parser.zena';
import { Resolver } from './resolver.zena';
import { serializeAstToJson } from './ast-json.zena';
/**
* Parse and resolve WIT source into a validated AST.
*
* This is what a consumer almost always wants: parsing alone accepts documents
* that are syntactically fine but meaningless, such as a `use` of an interface
* that does not exist.
*
* Throws `ParseError` for malformed syntax and `ResolveError` for a name or
* semantic failure. Both carry a `Span` locating the problem.
*/
export function parse(source: String): Ast {
let ast = Parser.parse(source);
Resolver.resolve(ast);
return ast;
}
/**
* Parse without resolving names.
*
* For tooling that wants a syntax tree of a single file in isolation — a
* formatter, or an editor reparsing on keystroke — where cross-package
* references cannot be resolved yet and their absence is not an error.
*/
export function parseSyntax(source: String): Ast {
return Parser.parse(source);
}
/**
* Resolve an already-parsed AST, validating it in place.
*
* Separate from `parseSyntax` so a caller assembling a document from several
* sources can parse each and resolve once at the end.
*/
export function resolve(ast: Ast): void {
Resolver.resolve(ast);
}
/**
* Serialize an AST to the `.wit.json` shape `wasm-tools component wit --json`
* emits, which is how the test corpus compares against upstream.
*
* `packageOrder` optionally fixes the order packages are emitted in; it exists
* because a concatenated multi-package document has no inherent order.
*/
export function toJson(ast: Ast, packageOrder: String | null = null): String {
return serializeAstToJson(ast, packageOrder);
}
export { Ast, ParseError } from './parser.zena';
export { ResolveError } from './resolver.zena';
| Version | Published | Dependencies | Approved by |
|---|---|---|---|
| 0.0.1-preview.1 | 2026-11-19 | none |
|