Add support for webidl iterable using js_sys::Iterator

Author: richard-uk1

crates/backend/src/ast.rs

@@ -65,20 +65,32 @@ pub enum MethodSelf {
     RefShared,
 }
 
+/// A js to rust interface.
 #[cfg_attr(feature = "extra-traits", derive(Debug))]
 #[derive(Clone)]
 pub struct Import {
+    /// What kind of es6+ module this import comes from, if any.
     pub module: ImportModule,
+    /// Rust can import a js object at either 0 or 1 depth.
+    ///
+    /// At 0 depth this is none, at 1 depth this is the name of the namespace. An example use for
+    /// this is the `log` function which is accessed through `console.log`.
     pub js_namespace: Option<Ident>,
+    /// The type of js thing imported (with associated data).
     pub kind: ImportKind,
 }
 
+/// The scope that js code can reside in. It is either in the global scope, or a module.
 #[cfg_attr(feature = "extra-traits", derive(Debug))]
 #[derive(Clone)]
 pub enum ImportModule {
+    /// Global scope
     None,
+    /// A module named `.0`.
     Named(String, Span),
+    /// A module named `.0`, where paths are not resolved.
     RawNamed(String, Span),
+    /// TODO
     Inline(usize, Span),
 }
 
@@ -104,12 +116,17 @@ impl Hash for ImportModule {
     }
 }
 
+/// A sum type of the possible kinds of imports.
 #[cfg_attr(feature = "extra-traits", derive(Debug))]
 #[derive(Clone)]
 pub enum ImportKind {
+    /// A javascript function.
     Function(ImportFunction),
+    /// A global static variable.
     Static(ImportStatic),
+    /// A javascript object type.
     Type(ImportType),
+    /// A set of strings interpreted as a rust enum.
     Enum(ImportEnum),
 }
 
@@ -177,15 +194,20 @@ pub struct ImportStatic {
 #[cfg_attr(feature = "extra-traits", derive(Debug, PartialEq, Eq))]
 #[derive(Clone)]
 pub struct ImportType {
+    /// The Rust type's visibility
     pub vis: syn::Visibility,
+    /// The Rust type's name
     pub rust_name: Ident,
+    /// The javascript name for the type
     pub js_name: String,
+    /// Attributes to apply to the Rust type
     pub attrs: Vec<syn::Attribute>,
     pub doc_comment: Option<String>,
     pub instanceof_shim: String,
     pub is_type_of: Option<syn::Expr>,
     pub extends: Vec<syn::Path>,
     pub vendor_prefixes: Vec<Ident>,
+    pub iterable: Option<Iterable>,
 }
 
 #[cfg_attr(feature = "extra-traits", derive(Debug, PartialEq, Eq))]
@@ -298,6 +320,7 @@ pub struct Dictionary {
     pub ctor: bool,
     pub doc_comment: Option<String>,
     pub ctor_doc_comment: Option<String>,
+    pub iterable: Option<Iterable>,
 }
 
 #[cfg_attr(feature = "extra-traits", derive(Debug, PartialEq, Eq))]
@@ -310,6 +333,16 @@ pub struct DictionaryField {
     pub doc_comment: Option<String>,
 }
 
+/// Whether it is possible to call `Symbol.iterator` on a type.
+#[cfg_attr(feature = "extra-traits", derive(Debug, PartialEq, Eq))]
+#[derive(Clone)]
+pub enum Iterable {
+    /// The iterator returns pairs of the form `[key, value]` (in webidl `iterable<Type, Type>`)
+    MapLike,
+    /// The iterator returns the given type (in webidl `iterable<Type>`)
+    ArrayLike,
+}
+
 impl Export {
     /// Mangles a rust -> javascript export, so that the created Ident will be unique over function
     /// name and class name, if the function belongs to a javascript class.

crates/backend/src/codegen.rs

@@ -1,3 +1,8 @@
+//! This module performs Rust codegen for the `ast` types.
+//!
+//! When encoding the top-level program, a block of bytes is generated by the `encode` module, and
+//! stored in a data section in the final output. the wasm-bindgen tool uses this data to generate
+//! javascript glue. This module handles all the generated code on the Rust side.
 use crate::ast;
 use crate::encode;
 use crate::util::ShortHash;
@@ -10,6 +15,8 @@ use std::sync::Mutex;
 use syn;
 use wasm_bindgen_shared as shared;
 
+/// Like `proc_macro::ToTokens`, but supports returning diagnostic information for an invalid
+/// syntax tree.
 pub trait TryToTokens {
     fn try_to_tokens(&self, tokens: &mut TokenStream) -> Result<(), Diagnostic>;
 
@@ -94,6 +101,7 @@ impl TryToTokens for ast::Program {
         );
         let encoded = encode::encode(self)?;
         let mut bytes = Vec::new();
+        // Encode the prefix_json length little-endian.
         bytes.push((prefix_json.len() >> 0) as u8);
         bytes.push((prefix_json.len() >> 8) as u8);
         bytes.push((prefix_json.len() >> 16) as u8);
@@ -589,6 +597,11 @@ impl ToTokens for ast::ImportType {
             }
         });
 
+        let iterable_instance = match self.iterable.as_ref() {
+            Some(iter) => iterable(rust_name, iter),
+            None => quote!(),
+        };
+
         (quote! {
             #[allow(bad_style)]
             #(#attrs)*
@@ -745,6 +758,8 @@ impl ToTokens for ast::ImportType {
 
                 ()
             };
+
+            #iterable_instance
         })
         .to_tokens(tokens);
 
@@ -1283,6 +1298,11 @@ impl ToTokens for ast::Dictionary {
             quote! {}
         };
 
+        let iterable_instance = match self.iterable.as_ref() {
+            Some(iter) => iterable(name, iter),
+            None => quote!(),
+        };
+
         let const_name = Ident::new(&format!("_CONST_{}", name), Span::call_site());
         (quote! {
             #[derive(Clone, Debug)]
@@ -1296,6 +1316,7 @@ impl ToTokens for ast::Dictionary {
             #[allow(clippy::all)]
             impl #name {
                 #ctor
+                #iterable_instance
                 #methods
             }
 
@@ -1496,3 +1517,64 @@ fn respan(input: TokenStream, span: &dyn ToTokens) -> TokenStream {
     }
     new_tokens.into_iter().collect()
 }
+
+/// Generate the code for an iterable.
+fn iterable(rust_name: &Ident, iterable: &ast::Iterable) -> TokenStream {
+    // Wrap our iterator implementation in a const
+    let const_name = format!("__wbg_generated_const_{}_iter", rust_name);
+    let const_name = Ident::new(&const_name, Span::call_site());
+    let iter_name = Ident::new(&format!("{}Iter", rust_name), rust_name.span());
+
+    let item = match iterable {
+        ast::Iterable::MapLike => quote!((::wasm_bindgen::JsValue, ::wasm_bindgen::JsValue)),
+        ast::Iterable::ArrayLike => quote!(::wasm_bindgen::JsValue),
+    };
+    let get_values = match iterable {
+        ast::Iterable::MapLike => quote!{
+            let entry = next.value();
+            debug_assert!(entry.has_type::<js_sys::Array>());
+            let entry: js_sys::Array = entry.unchecked_into();
+            let key = entry.get(0);
+            let value = entry.get(1);
+            Some((key, value))
+        },
+        ast::Iterable::ArrayLike => quote!(Some(next.value())),
+    };
+
+    quote! {
+        #[allow(non_upper_case_globals)]
+        #[allow(clippy::all)]
+        const #const_name: () = {
+            use wasm_bindgen::{UnwrapThrowExt, JsCast};
+            struct #iter_name(::js_sys::Iterator);
+
+            impl Iterator for #iter_name {
+                type Item = #item;
+                fn next(&mut self) -> Option<Self::Item> {
+                    let next = self.0.next().unwrap_throw();
+                    if next.done() {
+                        return None; // We discard the end value here.
+                    }
+                    #get_values
+                }
+            }
+
+            impl #rust_name {
+                /// Wraps the javascript object at `Symbol.iterator`, and presents it as a rust `Iterator`. See
+                /// ["The iterable protocol" at MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#The_iterable_protocol)
+                pub fn iter(&self)
+                    -> impl std::iter::Iterator<Item=#item>
+                {
+                    let func = ::js_sys::Reflect::get(self.as_ref(), &::js_sys::Symbol::iterator())
+                        .unwrap_throw();
+                    debug_assert!(func.is_function());
+                    let iter = func.unchecked_into::<::js_sys::Function>()
+                        .call0(self)
+                        .unwrap_throw();
+                    // TODO debug check iter can be used as an iterator (e.g. check for `next` method)
+                    #iter_name(iter.unchecked_into::<::js_sys::Iterator>())
+                }
+            }
+        };
+    }
+}

crates/backend/src/util.rs

@@ -24,7 +24,8 @@ fn is_rust_keyword(name: &str) -> bool {
     }
 }
 
-// Create an `Ident`, possibly mangling it if it conflicts with a Rust keyword.
+/// Create a valid Rust `Ident` from an input string, which may be modified if the input was a
+/// Rust keyword, or began with a number.
 pub fn rust_ident(name: &str) -> Ident {
     if name == "" {
         panic!("tried to create empty Ident (from \"\")");
@@ -57,8 +58,7 @@ pub fn rust_ident(name: &str) -> Ident {
     }
 }
 
-// Create an `Ident` without checking to see if it conflicts with a Rust
-// keyword.
+/// Create an `Ident` without any checking for validity.
 pub fn raw_ident(name: &str) -> Ident {
     Ident::new(name, proc_macro2::Span::call_site())
 }
@@ -82,6 +82,7 @@ where
     path_ty(true, segments)
 }
 
+/// Create a global path type from the given segments, either with or without a leading colon.
 fn path_ty<I>(leading_colon: bool, segments: I) -> syn::Type
 where
     I: IntoIterator<Item = Ident>,
@@ -108,10 +109,12 @@ where
     .into()
 }
 
+/// Create a (path) type from an `Ident`.
 pub fn ident_ty(ident: Ident) -> syn::Type {
     simple_path_ty(Some(ident))
 }
 
+/// Lift an import function to an import, assuming no js module or namespace.
 pub fn wrap_import_function(function: ast::ImportFunction) -> ast::Import {
     ast::Import {
         module: ast::ImportModule::None,

crates/macro-support/src/parser.rs

@@ -557,6 +557,7 @@ impl ConvertToAst<BindgenAttrs> for syn::ForeignItemType {
             js_name,
             extends,
             vendor_prefixes,
+            iterable: None,
         }))
     }
 }

crates/typescript-tests/src/simple_struct.rs

@@ -14,7 +14,9 @@ impl A {
 
     pub fn foo(&self) {}
 
-    pub fn ret_bool(&self) -> bool { true }
+    pub fn ret_bool(&self) -> bool {
+        true
+    }
     pub fn take_bool(&self, _: bool) {}
     pub fn take_many(&self, _: bool, _: f64, _: u32) {}
 }

crates/web-sys/tests/wasm/headers.rs

@@ -1,4 +1,5 @@
-use wasm_bindgen::prelude::*;
+use std::collections::HashMap;
+use wasm_bindgen::{prelude::*, JsCast};
 use wasm_bindgen_test::*;
 use web_sys::Headers;
 
@@ -28,4 +29,23 @@ fn headers() {
     assert!(headers.append("a", "y").is_ok());
     assert!(headers.append("a", "z").is_ok());
     assert_eq!(headers.get("a").unwrap(), Some("y, z".to_string()));
+    let headers_map: HashMap<String, String> = collect_headers(headers.iter());
+    assert_eq!(headers_map.len(), 2);
+    assert_eq!(
+        headers_map.get("content-type"),
+        Some(&"text/plain".to_string())
+    );
+    assert_eq!(headers_map.get("a"), Some(&"y, z".to_string()));
+    // try creating the headers object in rust
+    let headers = Headers::new().unwrap();
+    assert!(headers.set("Content-Type", "text/plain").is_ok());
+    for (key, value) in headers.iter() {
+        assert_eq!(key.as_string().unwrap(), "content-type");
+        assert_eq!(value.as_string().unwrap(), "text/plain");
+    }
+}
+
+fn collect_headers(iter: impl Iterator<Item = (JsValue, JsValue)>) -> HashMap<String, String> {
+    iter.map(|(key, val)| (key.as_string().unwrap(), val.as_string().unwrap()))
+        .collect()
 }

crates/webidl/src/first_pass.rs

@@ -52,6 +52,7 @@ pub(crate) struct InterfaceData<'src> {
     pub(crate) operations: BTreeMap<OperationId<'src>, OperationData<'src>>,
     pub(crate) superclass: Option<&'src str>,
     pub(crate) definition_attributes: Option<&'src ExtendedAttributeList<'src>>,
+    pub(crate) iterable: Option<Iterable<'src>>,
 }
 
 /// We need to collect mixin data during the first pass, to be used later.
@@ -115,6 +116,17 @@ pub(crate) struct Arg<'src> {
     pub(crate) variadic: bool,
 }
 
+#[derive(Clone, Debug)]
+pub(crate) enum Iterable<'src> {
+    MapLike {
+        key: weedle::types::Type<'src>,
+        value: weedle::types::Type<'src>,
+    },
+    ArrayLike {
+        value: weedle::types::Type<'src>,
+    },
+}
+
 /// Implemented on an AST node to populate the `FirstPassRecord` struct.
 pub(crate) trait FirstPass<'src, Ctx> {
     /// Populate `record` with any constructs in `self`.
@@ -422,8 +434,18 @@ impl<'src> FirstPass<'src, &'src str> for weedle::interface::InterfaceMember<'sr
                     .push(const_);
                 Ok(())
             }
-            InterfaceMember::Iterable(_iterable) => {
-                log::warn!("Unsupported WebIDL iterable interface member: {:?}", self);
+            InterfaceMember::Iterable(IterableInterfaceMember::Single(iter)) => {
+                record.interfaces.get_mut(self_name).unwrap().iterable =
+                    Some(Iterable::ArrayLike {
+                        value: iter.generics.body.type_.clone(),
+                    });
+                Ok(())
+            }
+            InterfaceMember::Iterable(IterableInterfaceMember::Double(iter)) => {
+                record.interfaces.get_mut(self_name).unwrap().iterable = Some(Iterable::MapLike {
+                    key: iter.generics.body.0.type_.clone(),
+                    value: iter.generics.body.2.type_.clone(),
+                });
                 Ok(())
             }
             // TODO