| //! 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`](https://docs.rs/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`](`parser::Parser`) to parse streams of |
| //! tokens. |
| //! |
| //! * [`Module`](crate::core::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`](crate::core::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](https://docs.rs/wast) 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. |
| //! |
| //! This crate also has an off-by-default `dwarf` feature which enables using |
| //! [`core::EncodeOptions::dwarf`] to embed DWARF debugging information in generated |
| //! binaries. |
| //! |
| //! [`Parse`]: parser::Parse |
| //! [`LexError`]: lexer::LexError |
| |
| #![deny(missing_docs, rustdoc::broken_intra_doc_links)] |
| #![cfg_attr(docsrs, feature(doc_auto_cfg))] |
| |
| /// A macro to create a custom keyword parser. |
| /// |
| /// This macro is invoked in one of two forms: |
| /// |
| /// ``` |
| /// // keyword derived from the Rust identifier: |
| /// wast::custom_keyword!(foo); |
| /// |
| /// // or an explicitly specified string representation of the keyword: |
| /// wast::custom_keyword!(my_keyword = "the-wasm-keyword"); |
| /// ``` |
| /// |
| /// This can then be used to parse custom keyword for custom items, such as: |
| /// |
| /// ``` |
| /// use wast::parser::{Parser, Result, Parse}; |
| /// |
| /// struct InlineModule<'a> { |
| /// inline_text: &'a str, |
| /// } |
| /// |
| /// mod kw { |
| /// wast::custom_keyword!(inline); |
| /// } |
| /// |
| /// // Parse an inline string module of the form: |
| /// // |
| /// // (inline "(module (func))") |
| /// impl<'a> Parse<'a> for InlineModule<'a> { |
| /// fn parse(parser: Parser<'a>) -> Result<Self> { |
| /// parser.parse::<kw::inline>()?; |
| /// Ok(InlineModule { |
| /// inline_text: parser.parse()?, |
| /// }) |
| /// } |
| /// } |
| /// ``` |
| /// |
| /// Note that the keyword name can only start with a lower-case letter, i.e. 'a'..'z'. |
| #[macro_export] |
| macro_rules! custom_keyword { |
| ($name:ident) => { |
| $crate::custom_keyword!($name = stringify!($name)); |
| }; |
| ($name:ident = $kw:expr) => { |
| #[allow(non_camel_case_types)] |
| #[allow(missing_docs)] |
| #[derive(Debug, Copy, Clone)] |
| pub struct $name(#[allow(dead_code)] pub $crate::token::Span); |
| |
| impl<'a> $crate::parser::Parse<'a> for $name { |
| fn parse(parser: $crate::parser::Parser<'a>) -> $crate::parser::Result<Self> { |
| parser.step(|c| { |
| if let Some((kw, rest)) = c.keyword()? { |
| if kw == $kw { |
| return Ok(($name(c.cur_span()), rest)); |
| } |
| } |
| Err(c.error(concat!("expected keyword `", $kw, "`"))) |
| }) |
| } |
| } |
| |
| impl $crate::parser::Peek for $name { |
| fn peek(cursor: $crate::parser::Cursor<'_>) -> $crate::parser::Result<bool> { |
| Ok(if let Some((kw, _rest)) = cursor.keyword()? { |
| kw == $kw |
| } else { |
| false |
| }) |
| } |
| |
| fn display() -> &'static str { |
| concat!("`", $kw, "`") |
| } |
| } |
| }; |
| } |
| |
| /// A macro for defining custom reserved symbols. |
| /// |
| /// This is like `custom_keyword!` but for reserved symbols (`Token::Reserved`) |
| /// instead of keywords (`Token::Keyword`). |
| /// |
| /// ``` |
| /// use wast::parser::{Parser, Result, Parse}; |
| /// |
| /// // Define a custom reserved symbol, the "spaceship" operator: `<=>`. |
| /// wast::custom_reserved!(spaceship = "<=>"); |
| /// |
| /// /// A "three-way comparison" like `(<=> a b)` that returns -1 if `a` is less |
| /// /// than `b`, 0 if they're equal, and 1 if `a` is greater than `b`. |
| /// struct ThreeWayComparison<'a> { |
| /// lhs: wast::core::Expression<'a>, |
| /// rhs: wast::core::Expression<'a>, |
| /// } |
| /// |
| /// impl<'a> Parse<'a> for ThreeWayComparison<'a> { |
| /// fn parse(parser: Parser<'a>) -> Result<Self> { |
| /// parser.parse::<spaceship>()?; |
| /// let lhs = parser.parse()?; |
| /// let rhs = parser.parse()?; |
| /// Ok(ThreeWayComparison { lhs, rhs }) |
| /// } |
| /// } |
| /// ``` |
| #[macro_export] |
| macro_rules! custom_reserved { |
| ($name:ident) => { |
| $crate::custom_reserved!($name = stringify!($name)); |
| }; |
| ($name:ident = $rsv:expr) => { |
| #[allow(non_camel_case_types)] |
| #[allow(missing_docs)] |
| #[derive(Debug)] |
| pub struct $name(pub $crate::token::Span); |
| |
| impl<'a> $crate::parser::Parse<'a> for $name { |
| fn parse(parser: $crate::parser::Parser<'a>) -> $crate::parser::Result<Self> { |
| parser.step(|c| { |
| if let Some((rsv, rest)) = c.reserved()? { |
| if rsv == $rsv { |
| return Ok(($name(c.cur_span()), rest)); |
| } |
| } |
| Err(c.error(concat!("expected reserved symbol `", $rsv, "`"))) |
| }) |
| } |
| } |
| |
| impl $crate::parser::Peek for $name { |
| fn peek(cursor: $crate::parser::Cursor<'_>) -> Result<bool> { |
| if let Some((rsv, _rest)) = cursor.reserved()? { |
| Ok(rsv == $rsv) |
| } else { |
| Ok(false) |
| } |
| } |
| |
| fn display() -> &'static str { |
| concat!("`", $rsv, "`") |
| } |
| } |
| }; |
| } |
| |
| /// A macro, like [`custom_keyword`], to create a type which can be used to |
| /// parse/peek annotation directives. |
| /// |
| /// Note that when you're parsing custom annotations it can be somewhat tricky |
| /// due to the nature that most of them are skipped. You'll want to be sure to |
| /// consult the documentation of [`Parser::register_annotation`][register] when |
| /// using this macro. |
| /// |
| /// # Examples |
| /// |
| /// To see an example of how to use this macro, let's invent our own syntax for |
| /// the [producers section][section] which looks like: |
| /// |
| /// ```wat |
| /// (@producer "wat" "1.0.2") |
| /// ``` |
| /// |
| /// Here, for simplicity, we'll assume everything is a `processed-by` directive, |
| /// but you could get much more fancy with this as well. |
| /// |
| /// ``` |
| /// # use wast::*; |
| /// # use wast::parser::*; |
| /// |
| /// // First we define the custom annotation keyword we're using, and by |
| /// // convention we define it in an `annotation` module. |
| /// mod annotation { |
| /// wast::annotation!(producer); |
| /// } |
| /// |
| /// struct Producer<'a> { |
| /// name: &'a str, |
| /// version: &'a str, |
| /// } |
| /// |
| /// impl<'a> Parse<'a> for Producer<'a> { |
| /// fn parse(parser: Parser<'a>) -> Result<Self> { |
| /// // Remember that parser conventionally parse the *interior* of an |
| /// // s-expression, so we parse our `@producer` annotation and then we |
| /// // parse the payload of our annotation. |
| /// parser.parse::<annotation::producer>()?; |
| /// Ok(Producer { |
| /// name: parser.parse()?, |
| /// version: parser.parse()?, |
| /// }) |
| /// } |
| /// } |
| /// ``` |
| /// |
| /// Note though that this is only half of the parser for annotations. The other |
| /// half is calling the [`register_annotation`][register] method at the right |
| /// time to ensure the parser doesn't automatically skip our `@producer` |
| /// directive. Note that we *can't* call it inside the `Parse for Producer` |
| /// definition because that's too late and the annotation would already have |
| /// been skipped. |
| /// |
| /// Instead we'll need to call it from a higher level-parser before the |
| /// parenthesis have been parsed, like so: |
| /// |
| /// ``` |
| /// # use wast::*; |
| /// # use wast::parser::*; |
| /// struct Module<'a> { |
| /// fields: Vec<ModuleField<'a>>, |
| /// } |
| /// |
| /// impl<'a> Parse<'a> for Module<'a> { |
| /// fn parse(parser: Parser<'a>) -> Result<Self> { |
| /// // .. parse module header here ... |
| /// |
| /// // register our custom `@producer` annotation before we start |
| /// // parsing the parentheses of each field |
| /// let _r = parser.register_annotation("producer"); |
| /// |
| /// let mut fields = Vec::new(); |
| /// while !parser.is_empty() { |
| /// fields.push(parser.parens(|p| p.parse())?); |
| /// } |
| /// Ok(Module { fields }) |
| /// } |
| /// } |
| /// |
| /// enum ModuleField<'a> { |
| /// Producer(Producer<'a>), |
| /// // ... |
| /// } |
| /// # struct Producer<'a>(&'a str); |
| /// # impl<'a> Parse<'a> for Producer<'a> { |
| /// # fn parse(parser: Parser<'a>) -> Result<Self> { Ok(Producer(parser.parse()?)) } |
| /// # } |
| /// # mod annotation { wast::annotation!(producer); } |
| /// |
| /// impl<'a> Parse<'a> for ModuleField<'a> { |
| /// fn parse(parser: Parser<'a>) -> Result<Self> { |
| /// // and here `peek` works and our delegated parsing works because the |
| /// // annotation has been registered. |
| /// if parser.peek::<annotation::producer>()? { |
| /// return Ok(ModuleField::Producer(parser.parse()?)); |
| /// } |
| /// |
| /// // .. typically we'd parse other module fields here... |
| /// |
| /// Err(parser.error("unknown module field")) |
| /// } |
| /// } |
| /// ``` |
| /// |
| /// [register]: crate::parser::Parser::register_annotation |
| /// [section]: https://github.com/WebAssembly/tool-conventions/blob/master/ProducersSection.md |
| #[macro_export] |
| macro_rules! annotation { |
| ($name:ident) => { |
| $crate::annotation!($name = stringify!($name)); |
| }; |
| ($name:ident = $annotation:expr) => { |
| #[allow(non_camel_case_types)] |
| #[allow(missing_docs)] |
| #[derive(Debug)] |
| pub struct $name(pub $crate::token::Span); |
| |
| impl<'a> $crate::parser::Parse<'a> for $name { |
| fn parse(parser: $crate::parser::Parser<'a>) -> $crate::parser::Result<Self> { |
| parser.step(|c| { |
| if let Some((a, rest)) = c.annotation()? { |
| if a == $annotation { |
| return Ok(($name(c.cur_span()), rest)); |
| } |
| } |
| Err(c.error(concat!("expected annotation `@", $annotation, "`"))) |
| }) |
| } |
| } |
| |
| impl $crate::parser::Peek for $name { |
| fn peek(cursor: $crate::parser::Cursor<'_>) -> $crate::parser::Result<bool> { |
| Ok(if let Some((a, _rest)) = cursor.annotation()? { |
| a == $annotation |
| } else { |
| false |
| }) |
| } |
| |
| fn display() -> &'static str { |
| concat!("`@", $annotation, "`") |
| } |
| } |
| }; |
| } |
| |
| pub mod lexer; |
| pub mod parser; |
| pub mod token; |
| |
| #[cfg(feature = "wasm-module")] |
| mod encode; |
| mod error; |
| #[cfg(feature = "wasm-module")] |
| mod gensym; |
| #[cfg(feature = "wasm-module")] |
| mod names; |
| pub use self::error::*; |
| |
| #[cfg(feature = "wasm-module")] |
| macro_rules! id { |
| ($($t:tt)*) => ($($t)*) |
| } |
| |
| #[cfg(feature = "wasm-module")] |
| id! { |
| mod wast; |
| mod wat; |
| pub use self::wast::*; |
| pub use self::wat::*; |
| |
| // Support for core wasm parsing |
| pub mod core; |
| |
| // Support for component model parsing |
| #[cfg(feature = "component-model")] |
| pub mod component; |
| #[cfg(not(feature = "component-model"))] |
| #[path = "component_disabled.rs"] |
| pub mod component; |
| } |
| |
| /// Common keyword used to parse WebAssembly text files. |
| pub mod kw { |
| custom_keyword!(after); |
| custom_keyword!(alias); |
| custom_keyword!(any); |
| custom_keyword!(anyref); |
| custom_keyword!(arg); |
| custom_keyword!(array); |
| custom_keyword!(arrayref); |
| custom_keyword!(assert_exception); |
| custom_keyword!(assert_exhaustion); |
| custom_keyword!(assert_invalid); |
| custom_keyword!(assert_malformed); |
| custom_keyword!(assert_return); |
| custom_keyword!(assert_trap); |
| custom_keyword!(assert_unlinkable); |
| custom_keyword!(assert_suspension); |
| custom_keyword!(before); |
| custom_keyword!(binary); |
| custom_keyword!(block); |
| custom_keyword!(borrow); |
| custom_keyword!(catch); |
| custom_keyword!(catch_ref); |
| custom_keyword!(catch_all); |
| custom_keyword!(catch_all_ref); |
| custom_keyword!(code); |
| custom_keyword!(cont); |
| custom_keyword!(contref); |
| custom_keyword!(component); |
| custom_keyword!(data); |
| custom_keyword!(declare); |
| custom_keyword!(delegate); |
| custom_keyword!(r#do = "do"); |
| custom_keyword!(dtor); |
| custom_keyword!(elem); |
| custom_keyword!(end); |
| custom_keyword!(tag); |
| custom_keyword!(exn); |
| custom_keyword!(exnref); |
| custom_keyword!(export); |
| custom_keyword!(r#extern = "extern"); |
| custom_keyword!(externref); |
| custom_keyword!(eq); |
| custom_keyword!(eqref); |
| custom_keyword!(f32); |
| custom_keyword!(f32x4); |
| custom_keyword!(f64); |
| custom_keyword!(f64x2); |
| custom_keyword!(field); |
| custom_keyword!(first); |
| custom_keyword!(func); |
| custom_keyword!(funcref); |
| custom_keyword!(get); |
| custom_keyword!(global); |
| custom_keyword!(i16); |
| custom_keyword!(i16x8); |
| custom_keyword!(i31); |
| custom_keyword!(i31ref); |
| custom_keyword!(i32); |
| custom_keyword!(i32x4); |
| custom_keyword!(i64); |
| custom_keyword!(i64x2); |
| custom_keyword!(i8); |
| custom_keyword!(i8x16); |
| custom_keyword!(import); |
| custom_keyword!(instance); |
| custom_keyword!(instantiate); |
| custom_keyword!(interface); |
| custom_keyword!(invoke); |
| custom_keyword!(item); |
| custom_keyword!(last); |
| custom_keyword!(local); |
| custom_keyword!(memory); |
| custom_keyword!(module); |
| custom_keyword!(modulecode); |
| custom_keyword!(nan_arithmetic = "nan:arithmetic"); |
| custom_keyword!(nan_canonical = "nan:canonical"); |
| custom_keyword!(nocont); |
| custom_keyword!(nofunc); |
| custom_keyword!(noextern); |
| custom_keyword!(noexn); |
| custom_keyword!(none); |
| custom_keyword!(null); |
| custom_keyword!(nullcontref); |
| custom_keyword!(nullfuncref); |
| custom_keyword!(nullexternref); |
| custom_keyword!(nullexnref); |
| custom_keyword!(nullref); |
| custom_keyword!(offset); |
| custom_keyword!(on); |
| custom_keyword!(outer); |
| custom_keyword!(own); |
| custom_keyword!(pagesize); |
| custom_keyword!(param); |
| custom_keyword!(parent); |
| custom_keyword!(passive); |
| custom_keyword!(quote); |
| custom_keyword!(r#else = "else"); |
| custom_keyword!(r#if = "if"); |
| custom_keyword!(r#loop = "loop"); |
| custom_keyword!(r#mut = "mut"); |
| custom_keyword!(r#type = "type"); |
| custom_keyword!(r#ref = "ref"); |
| custom_keyword!(ref_func = "ref.func"); |
| custom_keyword!(ref_null = "ref.null"); |
| custom_keyword!(register); |
| custom_keyword!(rec); |
| custom_keyword!(acq_rel); |
| custom_keyword!(rep); |
| custom_keyword!(resource); |
| custom_keyword!(resource_new = "resource.new"); |
| custom_keyword!(resource_drop = "resource.drop"); |
| custom_keyword!(resource_rep = "resource.rep"); |
| custom_keyword!(result); |
| custom_keyword!(seq_cst); |
| custom_keyword!(shared); |
| custom_keyword!(start); |
| custom_keyword!(sub); |
| custom_keyword!(switch); |
| custom_keyword!(r#final = "final"); |
| custom_keyword!(table); |
| custom_keyword!(then); |
| custom_keyword!(r#try = "try"); |
| custom_keyword!(v128); |
| custom_keyword!(value); |
| custom_keyword!(s8); |
| custom_keyword!(s16); |
| custom_keyword!(s32); |
| custom_keyword!(s64); |
| custom_keyword!(u8); |
| custom_keyword!(u16); |
| custom_keyword!(u32); |
| custom_keyword!(u64); |
| custom_keyword!(char); |
| custom_keyword!(case); |
| custom_keyword!(refines); |
| custom_keyword!(record); |
| custom_keyword!(string); |
| custom_keyword!(bool_ = "bool"); |
| custom_keyword!(float32); |
| custom_keyword!(float64); |
| custom_keyword!(variant); |
| custom_keyword!(flags); |
| custom_keyword!(option); |
| custom_keyword!(tuple); |
| custom_keyword!(list); |
| custom_keyword!(error); |
| custom_keyword!(canon); |
| custom_keyword!(lift); |
| custom_keyword!(lower); |
| custom_keyword!(enum_ = "enum"); |
| custom_keyword!(string_utf8 = "string-encoding=utf8"); |
| custom_keyword!(string_utf16 = "string-encoding=utf16"); |
| custom_keyword!(string_latin1_utf16 = "string-encoding=latin1+utf16"); |
| custom_keyword!(r#struct = "struct"); |
| custom_keyword!(structref); |
| custom_keyword!(realloc); |
| custom_keyword!(post_return = "post-return"); |
| custom_keyword!(with); |
| custom_keyword!(core); |
| custom_keyword!(true_ = "true"); |
| custom_keyword!(false_ = "false"); |
| custom_keyword!(language); |
| custom_keyword!(sdk); |
| custom_keyword!(processed_by = "processed-by"); |
| custom_keyword!(mem_info = "mem-info"); |
| custom_keyword!(needed); |
| custom_keyword!(export_info = "export-info"); |
| custom_keyword!(import_info = "import-info"); |
| custom_keyword!(thread); |
| custom_keyword!(thread_spawn = "thread.spawn"); |
| custom_keyword!(thread_hw_concurrency = "thread.hw_concurrency"); |
| custom_keyword!(wait); |
| custom_keyword!(definition); |
| } |
| |
| /// Common annotations used to parse WebAssembly text files. |
| pub mod annotation { |
| annotation!(custom); |
| annotation!(name); |
| annotation!(producers); |
| annotation!(dylink_0 = "dylink.0"); |
| annotation!(metadata_code_branch_hint = "metadata.code.branch_hint"); |
| } |
