Macro xterm_js_sys::interface

macro_rules! interface {
    (
        $(#[$metas:meta])*
        $vis:vis trait $nom:ident
            mirrors $js_interface:ident
            $(where
                $(Self extends $ext_js:path as $ext_rs:path,)+
            )?
    {
        $(
            $(#[$fn_metas:meta])*
            // All functions that we can mirror need to take `&self` so this is
            // okay.
            fn $fn_name:ident (&self $(, $arg_name:ident: $arg_ty:ty)* $(,)?)
                $(-> $ret_ty:ty)?
                ;
            // Default impls are not supported for now.

            // This is intentionally very constrained. The idea is that this
            // just mirrors the JS interface. if you want to offer additional
            // functionality on your Rust trait, use an extension trait.
        )*
    }) => { ... };
}

Creates a Rust trait to match a particular JS interface.

In addition to the actual trait, this produces:

• glue that lets 'static instances of the Rust trait be "turned into" instances of the JS interface
• a blanket impl that implements the Rust trait for all wasm-bindgen produced types that extend the JS interface
• an implementation of IntoJsInterface for all things that implement the Rust trait that's generated; this can be used to accept implementations of the Rust or implementations of the JS interface with impl IntoJsInterface<JsInterfaceName>

Note: if you get an error about "unconditional recursion" when using this macro or an error about a trait not being in scope, it's because a method that you added to the trait doesn't exist on the underlying JS interface. Apologies for the cryptic error!

Also note that if you omit methods in the Rust interface you won't be warned! You'll only find out when a JS user tries to call one of the methods you missed at which point you'll get a runtime error 🙁 (we could use JsCast::dyn_into) instead of its unchecked counterpart but we don't since that's not really all that much better (still a runtime error, but you'll get it on convert rather than when you try to use the method in question and you'll pay a performance penalty on every conversion).

Note that this currently requires that you have you IntoJsInterface in scope. This is because this trait must be defined in the crate where this macro is called in order for the blanket impl that this macro produces for IntoJsInterface to type check. Rather than make it so that this macro only works in this crate it'll instead work in other crates with the stipulation that you need to mirror over the trait. Suboptimal, I know. And this probably renders the little utility the IntoJsInterface trait had moot.