1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214
//! A Rust parser for the [WebAssembly Text format][wat] //! //! This crate contains a stable interface to the parser for the [WAT][wat] //! format of WebAssembly text files. The format parsed by this crate follows //! the [online specification][wat]. //! //! # Examples //! //! Parse an in-memory string: //! //! ``` //! # fn foo() -> wast::Result<()> { //! let wat = r#" //! (module //! (func $foo) //! //! (func (export "bar") //! call $foo //! ) //! ) //! "#; //! //! let binary = wast::parse_str(wat)?; //! // ... //! # Ok(()) //! # } //! ``` //! //! Parse an on-disk file: //! //! ``` //! # fn foo() -> wast::Result<()> { //! let binary = wast::parse_file("./foo.wat")?; //! // ... //! # Ok(()) //! # } //! ``` //! //! ## Evolution of the WAT Format //! //! WebAssembly, and the WAT format, are an evolving specification. Features are //! added to WAT, WAT changes, and sometimes WAT breaks. The policy of this //! crate is that it will always follow the [official specification][wat] for //! WAT files. //! //! Future WebAssembly features will be accepted to this parser **and they will //! not require a feature gate to opt-in**. All implemented WebAssembly features //! will be enabled at all times. Using a future WebAssembly feature in the WAT //! format may cause breakage because while specifications are in development //! the WAT syntax (and/or binary encoding) will often change. This crate will //! do its best to keep up with these proposals, but breaking textual changes //! will be published as non-breaking semver changes to this crate. //! //! ## Stability //! //! This crate is intended to be a very stable shim over the `wast-parser` crate //! which is expected to be much more unstable. The `wast-parser` crate contains //! AST data structures for parsing `*.wat` files and they will evolve was the //! WAT and WebAssembly specifications evolve over time. //! //! This crate is currently at version 1.x.y, and it is intended that it will //! remain here for quite some time. Breaking changes to the WAT format will be //! landed as a non-semver-breaking version change in this crate. This crate //! will always follow the [official specification for WAT][wat]. //! //! [wat]: http://webassembly.github.io/spec/core/text/index.html #![deny(missing_docs)] use std::fmt; use std::path::Path; use wast_parser::parser::{self, ParseBuffer}; /// Parses a file on disk as a [WebAssembly Text format][wat] file, returning /// the file translated to a WebAssembly binary file. /// /// For more information see the [`parse_str`] documentation. /// /// # Errors /// /// For information about errors, see the [`parse_str`] documentation. /// /// # Examples /// /// ``` /// # fn foo() -> wast::Result<()> { /// let binary = wast::parse_file("./foo.wat")?; /// // ... /// # Ok(()) /// # } /// ``` /// /// [wat]: http://webassembly.github.io/spec/core/text/index.html pub fn parse_file(file: impl AsRef<Path>) -> Result<Vec<u8>> { _parse_file(file.as_ref()) } fn _parse_file(file: &Path) -> Result<Vec<u8>> { let contents = std::fs::read_to_string(file).map_err(|err| Error { kind: Box::new(ErrorKind::Io { err, msg: format!("failed to read `{}` to a string", file.display()), }), })?; parse_str(&contents).map_err(|mut e| { if let ErrorKind::Wast(e) = &mut *e.kind { e.set_path(file); } e }) } /// Parses an in-memory string as the [WebAssembly Text format][wat], returning /// the file as a binary WebAssembly file. /// /// This function is intended to be a stable convenience function for parsing a /// wat file into a WebAssembly binary file. This is a high-level operation /// which does not expose any parsing internals, for that you'll want to use the /// `wast-parser` crate. /// /// # Errors /// /// This function can fail for a number of reasons, including (but not limited /// to): /// /// * The `wat` input may fail to lex, such as having invalid tokens or syntax /// * The `wat` input may fail to parse, such as having incorrect syntactical /// structure /// * The `wat` input may contain names that could not be resolved /// /// # Examples /// /// ``` /// # fn foo() -> wast::Result<()> { /// assert_eq!(wast::parse_str("(module)")?, b"\0asm\x01\0\0\0"); /// assert!(wast::parse_str("module").is_err()); /// /// let wat = r#" /// (module /// (func $foo) /// /// (func (export "bar") /// call $foo /// ) /// ) /// "#; /// /// let binary = wast::parse_str(wat)?; /// // ... /// # Ok(()) /// # } /// ``` /// /// [wat]: http://webassembly.github.io/spec/core/text/index.html pub fn parse_str(wat: impl AsRef<str>) -> Result<Vec<u8>> { _parse_str(wat.as_ref()) } fn _parse_str(wat: &str) -> Result<Vec<u8>> { let buf = ParseBuffer::new(&wat).map_err(|e| Error::cvt(e, wat))?; let mut ast = parser::parse::<wast_parser::Wat>(&buf).map_err(|e| Error::cvt(e, wat))?; Ok(ast.module.encode().map_err(|e| Error::cvt(e, wat))?) } /// A convenience type definition for `Result` where the error is [`Error`] pub type Result<T> = std::result::Result<T, Error>; /// Errors from this crate related to parsing WAT files /// /// An error can during example phases like: /// /// * Lexing can fail if the document is syntactically invalid. /// * A string may not be utf-8 /// * The syntactical structure of the wat file may be invalid /// * The wat file may be semantically invalid such as having name resolution /// failures #[derive(Debug)] pub struct Error { kind: Box<ErrorKind>, } #[derive(Debug)] enum ErrorKind { Wast(wast_parser::Error), Io { err: std::io::Error, msg: String }, } impl Error { fn cvt<E: Into<wast_parser::Error>>(e: E, contents: &str) -> Error { let mut err = e.into(); err.set_text(contents); Error { kind: Box::new(ErrorKind::Wast(err)), } } } impl fmt::Display for Error { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { match &*self.kind { ErrorKind::Wast(err) => err.fmt(f), ErrorKind::Io { msg, .. } => msg.fmt(f), } } } impl std::error::Error for Error { fn source(&self) -> Option<&(dyn std::error::Error + 'static)> { match &*self.kind { ErrorKind::Wast(_) => None, ErrorKind::Io { err, .. } => Some(err), } } }