Crate wast

source · []
Expand description

A crate for low-level parsing of the WebAssembly text formats: WAT and WAST.

This crate is intended to be a low-level detail of the wat crate, providing a low-level parsing API for parsing WebAssembly text format structures. The API provided by this crate is very similar to syn and provides the ability to write customized parsers which may be an extension to the core WebAssembly text format. For more documentation see the parser module.

High-level Overview

This crate provides a few major pieces of functionality

  • lexer - this is a raw lexer for the wasm text format. This is not customizable, but if you’d like to iterate over raw tokens this is the module for you. You likely won’t use this much.

  • parser - this is the workhorse of this crate. The parser module provides the Parse trait primarily and utilities around working with a Parser to parse streams of tokens.

  • Module - this contains an Abstract Syntax Tree (AST) of the WebAssembly Text format (WAT) as well as the unofficial WAST format. This also has a Module::encode method to emit a module in its binary form.

Stability and WebAssembly Features

This crate provides support for many in-progress WebAssembly features such as reference types, multi-value, etc. Be sure to check out the documentation of the wast crate for policy information on crate stability vs WebAssembly Features. The tl;dr; version is that this crate will issue semver-non-breaking releases which will break the parsing of the text format. This crate, unlike wast, is expected to have numerous Rust public API changes, all of which will be accompanied with a semver-breaking release.

Compile-time Cargo features

This crate has a wasm-module feature which is turned on by default which includes all necessary support to parse full WebAssembly modules. If you don’t need this (for example you’re parsing your own s-expression format) then this feature can be disabled.

Modules

Common annotations used to parse WebAssembly text files.

Types and support for parsing the component model text format.

Types and support for parsing the core wasm text format.

Common keyword used to parse WebAssembly text files.

Definition of a lexer for the WebAssembly text format.

Traits for parsing the WebAssembly Text format

Common tokens that implement the Parse trait which are otherwise not associated specifically with the wasm text format per se (useful in other contexts too perhaps).

Macros

A macro, like custom_keyword, to create a type which can be used to parse/peek annotation directives.

A macro to create a custom keyword parser.

A macro for defining custom reserved symbols.

Structs

A convenience error type to tie together all the detailed errors produced by this crate.

A parsed representation of a *.wast file.

Enums

The different kinds of directives found in a *.wast file.

A *.wat file parser, or a parser for one parenthesized module.