From a53b57b5958b38332664128bb0896888a72789ca Mon Sep 17 00:00:00 2001 From: Ivan Enderlin Date: Mon, 10 Feb 2020 16:39:06 +0100 Subject: [PATCH] doc(interface-types) Improve documentation of the `binary` module. --- src/decoders/binary.rs | 27 ++++++++++++++++++++++----- 1 file changed, 22 insertions(+), 5 deletions(-) diff --git a/src/decoders/binary.rs b/src/decoders/binary.rs index 2853f7e..403fc5b 100644 --- a/src/decoders/binary.rs +++ b/src/decoders/binary.rs @@ -1,3 +1,5 @@ +//! Parse the WIT binary representation into an AST. + use crate::{ast::*, interpreter::Instruction}; use nom::{ error::{make_error, ErrorKind, ParseError}, @@ -5,6 +7,7 @@ use nom::{ }; use std::{convert::TryFrom, str}; +/// Parse an `InterfaceType`. impl TryFrom for InterfaceType { type Error = &'static str; @@ -25,6 +28,7 @@ impl TryFrom for InterfaceType { } } +/// Parse an adapter kind. impl TryFrom for AdapterKind { type Error = &'static str; @@ -38,6 +42,7 @@ impl TryFrom for AdapterKind { } } +/// Parse a byte. fn byte<'input, E: ParseError<&'input [u8]>>(input: &'input [u8]) -> IResult<&'input [u8], u8, E> { if input.is_empty() { return Err(Err::Error(make_error(input, ErrorKind::Eof))); @@ -46,6 +51,7 @@ fn byte<'input, E: ParseError<&'input [u8]>>(input: &'input [u8]) -> IResult<&'i Ok((&input[1..], input[0])) } +/// Parse an unsigned LEB with value no larger than a 64-bits number. fn leb<'input, E: ParseError<&'input [u8]>>(input: &'input [u8]) -> IResult<&'input [u8], u64, E> { if input.is_empty() { return Err(Err::Error(make_error(input, ErrorKind::Eof))); @@ -65,6 +71,7 @@ fn leb<'input, E: ParseError<&'input [u8]>>(input: &'input [u8]) -> IResult<&'in )) } +/// Parse a UTF-8 string. fn string<'input, E: ParseError<&'input [u8]>>( input: &'input [u8], ) -> IResult<&'input [u8], &'input str, E> { @@ -84,6 +91,7 @@ fn string<'input, E: ParseError<&'input [u8]>>( })) } +/// Parse a list, with a item parser. #[allow(clippy::type_complexity)] fn list<'input, I, E: ParseError<&'input [u8]>>( input: &'input [u8], @@ -110,6 +118,7 @@ fn list<'input, I, E: ParseError<&'input [u8]>>( Ok((input, items)) } +/// Parse a type. fn ty<'input, E: ParseError<&'input [u8]>>( input: &'input [u8], ) -> IResult<&'input [u8], InterfaceType, E> { @@ -125,7 +134,8 @@ fn ty<'input, E: ParseError<&'input [u8]>>( } } -fn instructions<'input, E: ParseError<&'input [u8]>>( +/// Parse an instruction with its arguments. +fn instruction<'input, E: ParseError<&'input [u8]>>( input: &'input [u8], ) -> IResult<&'input [u8], Instruction, E> { let (mut input, opcode) = byte(input)?; @@ -243,6 +253,7 @@ fn instructions<'input, E: ParseError<&'input [u8]>>( }) } +/// Parse a list of exports. fn exports<'input, E: ParseError<&'input [u8]>>( input: &'input [u8], ) -> IResult<&'input [u8], Vec, E> { @@ -267,6 +278,7 @@ fn exports<'input, E: ParseError<&'input [u8]>>( Ok((input, exports)) } +/// Parse a list of types. fn types<'input, E: ParseError<&'input [u8]>>( input: &'input [u8], ) -> IResult<&'input [u8], Vec, E> { @@ -291,6 +303,7 @@ fn types<'input, E: ParseError<&'input [u8]>>( Ok((input, types)) } +/// Parse a list of imports. fn imports<'input, E: ParseError<&'input [u8]>>( input: &'input [u8], ) -> IResult<&'input [u8], Vec, E> { @@ -317,6 +330,7 @@ fn imports<'input, E: ParseError<&'input [u8]>>( Ok((input, imports)) } +/// Parse a list of adapters. fn adapters<'input, E: ParseError<&'input [u8]>>( input: &'input [u8], ) -> IResult<&'input [u8], Vec, E> { @@ -337,7 +351,7 @@ fn adapters<'input, E: ParseError<&'input [u8]>>( consume!((input, adapter_name) = string(input)?); consume!((input, adapter_input_types) = list(input, ty)?); consume!((input, adapter_output_types) = list(input, ty)?); - consume!((input, adapter_instructions) = list(input, instructions)?); + consume!((input, adapter_instructions) = list(input, instruction)?); adapters.push(Adapter::Import { namespace: adapter_namespace, @@ -352,7 +366,7 @@ fn adapters<'input, E: ParseError<&'input [u8]>>( consume!((input, adapter_name) = string(input)?); consume!((input, adapter_input_types) = list(input, ty)?); consume!((input, adapter_output_types) = list(input, ty)?); - consume!((input, adapter_instructions) = list(input, instructions)?); + consume!((input, adapter_instructions) = list(input, instruction)?); adapters.push(Adapter::Export { name: adapter_name, @@ -366,7 +380,7 @@ fn adapters<'input, E: ParseError<&'input [u8]>>( consume!((input, adapter_name) = string(input)?); consume!((input, adapter_input_types) = list(input, ty)?); consume!((input, adapter_output_types) = list(input, ty)?); - consume!((input, adapter_instructions) = list(input, instructions)?); + consume!((input, adapter_instructions) = list(input, instruction)?); adapters.push(Adapter::HelperFunction { name: adapter_name, @@ -381,6 +395,7 @@ fn adapters<'input, E: ParseError<&'input [u8]>>( Ok((input, adapters)) } +/// Parse a list of forwarded exports. fn forwards<'input, E: ParseError<&'input [u8]>>( input: &'input [u8], ) -> IResult<&'input [u8], Vec, E> { @@ -399,6 +414,8 @@ fn forwards<'input, E: ParseError<&'input [u8]>>( Ok((input, forwards)) } +/// Parse a sequence of bytes, expecting it to be a valid WIT binary +/// representation, into an `ast::Interfaces`. pub fn parse<'input, E: ParseError<&'input [u8]>>( bytes: &'input [u8], ) -> IResult<&'input [u8], Interfaces, E> { @@ -569,7 +586,7 @@ mod tests { ], )); - assert_eq!(list::(input, instructions), output); + assert_eq!(list::(input, instruction), output); } #[test]