Expand description
A trait for parsing a fragment of syntax in a recursive descent fashion.
The Parse
trait is main abstraction you’ll be working with when defining
custom parser or custom syntax for your WebAssembly text format (or when
using the official format items). Almost all items in the
ast
module implement the Parse
trait, and you’ll
commonly use this with:
- The top-level
parse
function to parse an entire input. - The intermediate
Parser::parse
function to parse an item out of an input stream and then parse remaining items.
Implementation of Parse
take a Parser
as input and will mutate the
parser as they parse syntax. Once a token is consume it cannot be
“un-consumed”. Utilities such as Parser::peek
and Parser::lookahead1
can be used to determine what to parse next.
When to parse (
and )
?
Conventionally types are not responsible for parsing their own (
and )
tokens which surround the type. For example WebAssembly imports look like:
(import "foo" "bar" (func (type 0)))
but the Import
type parser looks like:
impl<'a> Parse<'a> for Import<'a> {
fn parse(parser: Parser<'a>) -> Result<Self> {
parser.parse::<kw::import>()?;
// ...
}
}
It is assumed here that the (
and )
tokens which surround an import
statement in the WebAssembly text format are parsed by the parent item
parsing Import
.
Note that this is just a convention, so it’s not necessarily required for
all types. It’s recommended that your types stick to this convention where
possible to avoid nested calls to Parser::parens
or accidentally trying
to parse too many parenthesis.
Examples
Let’s say you want to define your own WebAssembly text format which only
contains imports and functions. You also require all imports to be listed
before all functions. An example Parse
implementation might look like:
use wast::{Import, Func, kw};
use wast::parser::{Parser, Parse, Result};
// Fields of a WebAssembly which only allow imports and functions, and all
// imports must come before all the functions
struct OnlyImportsAndFunctions<'a> {
imports: Vec<Import<'a>>,
functions: Vec<Func<'a>>,
}
impl<'a> Parse<'a> for OnlyImportsAndFunctions<'a> {
fn parse(parser: Parser<'a>) -> Result<Self> {
// While the second token is `import` (the first is `(`, so we care
// about the second) we parse an `ast::ModuleImport` inside of
// parentheses. The `parens` function here ensures that what we
// parse inside of it is surrounded by `(` and `)`.
let mut imports = Vec::new();
while parser.peek2::<kw::import>() {
let import = parser.parens(|p| p.parse())?;
imports.push(import);
}
// Afterwards we assume everything else is a function. Note that
// `parse` here is a generic function and type inference figures out
// that we're parsing functions here and imports above.
let mut functions = Vec::new();
while !parser.is_empty() {
let func = parser.parens(|p| p.parse())?;
functions.push(func);
}
Ok(OnlyImportsAndFunctions { imports, functions })
}
}
Required methods
Attempts to parse Self
from parser
, returning an error if it could
not be parsed.
This method will mutate the state of parser
after attempting to parse
an instance of Self
. If an error happens then it is likely fatal and
there is no guarantee of how many tokens have been consumed from
parser
.
As recommended in the documentation of Parse
, implementations of
this function should not start out by parsing (
and )
tokens, but
rather parents calling recursive parsers should parse the (
and )
tokens for their child item that’s being parsed.
Errors
This function will return an error if Self
could not be parsed. Note
that creating an Error
is not exactly a cheap operation, so
Error
is typically fatal and propagated all the way back to the top
parse call site.