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 Lexer Token Types
*
* Token definitions for the WIT (WebAssembly Interface Types) lexer.
* Based on the canonical implementation in wasm-tools:
* https://github.com/bytecodealliance/wasm-tools/blob/main/crates/wit-parser/src/ast/lex.rs
*/
// ============================================================================
// Token Type Enum
// ============================================================================
/**
* All possible token types in WIT syntax.
*
* Note: Enum values are auto-assigned starting from 0.
*/
export enum TokenType {
// Whitespace and comments (usually skipped)
Whitespace,
Comment,
DocComment, // /// doc comment
// Punctuation
Equals, // =
Comma, // ,
Colon, // :
Period, // .
Semicolon, // ;
LeftParen, // (
RightParen, // )
LeftBrace, // {
RightBrace, // }
LessThan, // <
GreaterThan, // >
RArrow, // ->
Star, // *
At, // @
Slash, // /
Plus, // +
Minus, // -
// Keywords - Types
U8,
U16,
U32,
U64,
S8,
S16,
S32,
S64,
F32,
F64,
Char,
Bool,
String,
// Keywords - Composite Types
Record,
Flags,
Variant,
Enum,
Option,
Result,
List,
Tuple,
Future,
Stream,
Map,
// Keywords - Resources
Resource,
Own,
Borrow,
Constructor,
Static,
// Keywords - Declarations
Type,
Func,
Interface,
World,
Package,
Use,
As,
From,
Import,
Export,
Include,
With,
// Keywords - Async
Async,
ErrorContext,
// Special
Underscore, // _
// Identifiers and literals
Id, // Regular identifier (e.g., my-func)
ExplicitId, // %-prefixed identifier (e.g., %bool)
Integer, // Numeric literal
// End of file
Eof,
}
// ============================================================================
// Token Structure
// ============================================================================
/**
* A source span indicating where a token appears in the input.
*/
export class Span {
start: i32;
end: i32;
new(start: i32, end: i32) : start = start, end = end;
/** Length of this span in bytes. */
length: i32 {
get {
return this.end - this.start;
}
}
}
/**
* A token with its type and source location.
*/
export class Token {
type: TokenType;
span: Span;
new(type: TokenType, span: Span) : type = type, span = span;
}
// ============================================================================
// Keyword Lookup
// ============================================================================
/**
* Map a keyword string to its token type, or return Id if not a keyword.
*
* WIT keywords are all lowercase with hyphens (kebab-case).
*/
export function keywordToToken(s: String): TokenType {
// Types
if (s == "u8") { return TokenType.U8; }
if (s == "u16") { return TokenType.U16; }
if (s == "u32") { return TokenType.U32; }
if (s == "u64") { return TokenType.U64; }
if (s == "s8") { return TokenType.S8; }
if (s == "s16") { return TokenType.S16; }
if (s == "s32") { return TokenType.S32; }
if (s == "s64") { return TokenType.S64; }
if (s == "f32") { return TokenType.F32; }
if (s == "f64") { return TokenType.F64; }
if (s == "char") { return TokenType.Char; }
if (s == "bool") { return TokenType.Bool; }
if (s == "string") { return TokenType.String; }
// Composite types
if (s == "record") { return TokenType.Record; }
if (s == "flags") { return TokenType.Flags; }
if (s == "variant") { return TokenType.Variant; }
if (s == "enum") { return TokenType.Enum; }
if (s == "option") { return TokenType.Option; }
if (s == "result") { return TokenType.Result; }
if (s == "list") { return TokenType.List; }
if (s == "tuple") { return TokenType.Tuple; }
if (s == "future") { return TokenType.Future; }
if (s == "stream") { return TokenType.Stream; }
if (s == "map") { return TokenType.Map; }
// Resources
if (s == "resource") { return TokenType.Resource; }
if (s == "own") { return TokenType.Own; }
if (s == "borrow") { return TokenType.Borrow; }
if (s == "constructor") { return TokenType.Constructor; }
if (s == "static") { return TokenType.Static; }
// Declarations
if (s == "type") { return TokenType.Type; }
if (s == "func") { return TokenType.Func; }
if (s == "interface") { return TokenType.Interface; }
if (s == "world") { return TokenType.World; }
if (s == "package") { return TokenType.Package; }
if (s == "use") { return TokenType.Use; }
if (s == "as") { return TokenType.As; }
if (s == "from") { return TokenType.From; }
if (s == "import") { return TokenType.Import; }
if (s == "export") { return TokenType.Export; }
if (s == "include") { return TokenType.Include; }
if (s == "with") { return TokenType.With; }
// Async
if (s == "async") { return TokenType.Async; }
if (s == "error-context") { return TokenType.ErrorContext; }
// Special
if (s == "_") { return TokenType.Underscore; }
// Not a keyword
return TokenType.Id;
}
/**
* Whether `t` is one of WIT's keywords — a word the grammar claims, so
* spelling it as a name takes the `%` escape.
*
* The keywords are one contiguous run of the enum, from the first type
* keyword through `_`; a keyword added outside that run would not be
* recognized here.
*/
export function isKeyword(t: TokenType): boolean {
let n = t as i32;
return n >= (TokenType.U8 as i32) && n <= (TokenType.Underscore as i32);
}
/**
* Get a human-readable description of a token type.
*/
export function describeToken(t: TokenType): String {
return match (t) {
case TokenType.Whitespace: "whitespace"
case TokenType.Comment: "a comment"
case TokenType.DocComment: "a doc comment"
case TokenType.Equals: "'='"
case TokenType.Comma: "','"
case TokenType.Colon: "':'"
case TokenType.Period: "'.'"
case TokenType.Semicolon: "';'"
case TokenType.LeftParen: "'('"
case TokenType.RightParen: "')'"
case TokenType.LeftBrace: "'{'"
case TokenType.RightBrace: "'}'"
case TokenType.LessThan: "'<'"
case TokenType.GreaterThan: "'>'"
case TokenType.RArrow: "'->'"
case TokenType.Star: "'*'"
case TokenType.At: "'@'"
case TokenType.Slash: "'/'"
case TokenType.Plus: "'+'"
case TokenType.Minus: "'-'"
case TokenType.U8: "keyword `u8`"
case TokenType.U16: "keyword `u16`"
case TokenType.U32: "keyword `u32`"
case TokenType.U64: "keyword `u64`"
case TokenType.S8: "keyword `s8`"
case TokenType.S16: "keyword `s16`"
case TokenType.S32: "keyword `s32`"
case TokenType.S64: "keyword `s64`"
case TokenType.F32: "keyword `f32`"
case TokenType.F64: "keyword `f64`"
case TokenType.Char: "keyword `char`"
case TokenType.Bool: "keyword `bool`"
case TokenType.String: "keyword `string`"
case TokenType.Record: "keyword `record`"
case TokenType.Flags: "keyword `flags`"
case TokenType.Variant: "keyword `variant`"
case TokenType.Enum: "keyword `enum`"
case TokenType.Option: "keyword `option`"
case TokenType.Result: "keyword `result`"
case TokenType.List: "keyword `list`"
case TokenType.Tuple: "keyword `tuple`"
case TokenType.Future: "keyword `future`"
case TokenType.Stream: "keyword `stream`"
case TokenType.Map: "keyword `map`"
case TokenType.Resource: "keyword `resource`"
case TokenType.Own: "keyword `own`"
case TokenType.Borrow: "keyword `borrow`"
case TokenType.Constructor: "keyword `constructor`"
case TokenType.Static: "keyword `static`"
case TokenType.Type: "keyword `type`"
case TokenType.Func: "keyword `func`"
case TokenType.Interface: "keyword `interface`"
case TokenType.World: "keyword `world`"
case TokenType.Package: "keyword `package`"
case TokenType.Use: "keyword `use`"
case TokenType.As: "keyword `as`"
case TokenType.From: "keyword `from`"
case TokenType.Import: "keyword `import`"
case TokenType.Export: "keyword `export`"
case TokenType.Include: "keyword `include`"
case TokenType.With: "keyword `with`"
case TokenType.Async: "keyword `async`"
case TokenType.ErrorContext: "keyword `error-context`"
case TokenType.Underscore: "keyword `_`"
case TokenType.Id: "an identifier"
case TokenType.ExplicitId: "an '%' identifier"
case TokenType.Integer: "an integer"
case TokenType.Eof: "end of file"
};
}
| Version | Published | Dependencies | Approved by |
|---|---|---|---|
| 0.0.1-preview.1 | 2026-11-19 | none |
|