script/dom/bindings/
mod.rs

1/* This Source Code Form is subject to the terms of the Mozilla Public
2 * License, v. 2.0. If a copy of the MPL was not distributed with this
3 * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
4
5//! The code to expose the DOM to JavaScript through IDL bindings.
6//!
7//! Exposing a DOM object to JavaScript
8//! ===================================
9//!
10//! As [explained earlier](../index.html#a-dom-object-and-its-reflector), the
11//! implementation of an interface `Foo` involves two objects: the DOM object
12//! (implemented in Rust) and the reflector (a `JSObject`).
13//!
14//! In order to expose the interface's members to the web, properties
15//! corresponding to the operations and attributes are defined on an object in
16//! the reflector's prototype chain or on the reflector itself.
17//!
18//! Typically, these properties are either value properties whose value is a
19//! function (for operations) or accessor properties that have a getter and
20//! optionally a setter function (for attributes, depending on whether they are
21//! marked `readonly`).
22//!
23//! All these JavaScript functions are set up such that, when they're called,
24//! they call a Rust function in the generated glue code. This glue code does
25//! some sanity checks and [argument conversions](conversions/index.html), and
26//! calls into API implementation for the DOM object.
27//!
28//! Rust reflections of WebIDL constructs
29//! =====================================
30//!
31//! WebIDL members are turned into methods on the DOM object (static methods
32//! for a static members and instance methods for regular members).
33//!
34//! The instance methods for an interface `Foo` are defined on a
35//! `dom::bindings::codegen::Bindings::FooBinding::FooMethods` trait. This
36//! trait is then implemented for `Foo`. (All methods take an `&self`
37//! parameter, as pointers to DOM objects can be freely aliased.)
38//!
39//! The return type and argument types are determined
40//! [as described below](#rust-reflections-of-webidl-types).
41//! In addition to those, all methods that are
42//! [allowed to throw](#throwing-exceptions)
43//! will have the return value wrapped in
44//! [`Fallible<T>`](error/type.Fallible.html).
45//! Methods that use certain WebIDL types like `any` or `object` will get a
46//! `*mut JSContext` argument prepended to the argument list. Static methods
47//! will be passed a [`&GlobalScope`](../globalscope/struct.GlobalScope.html)
48//! for the relevant global. This argument comes before the `*mut JSContext`
49//! argument, if any.
50//!
51//! Rust reflections of WebIDL operations (methods)
52//! -----------------------------------------------
53//!
54//! A WebIDL operation is turned into one method for every overload.
55//! The first overload gets the base name, and consecutive overloads have an
56//! underscore appended to the name.
57//!
58//! The base name of the Rust method is simply the name of the WebIDL operation
59//! with the first letter converted to uppercase.
60//!
61//! Rust reflections of WebIDL attributes
62//! -------------------------------------
63//!
64//! A WebIDL attribute is turned into a pair of methods: one for the getter and
65//! one for the setter. A readonly attribute only has a getter and no setter.
66//!
67//! The getter's name is the name of the attribute with the first letter
68//! converted to uppercase. It has `Get` prepended to it if the type of the
69//! attribute is nullable or if the getter can throw.
70//!
71//! The method signature for the getter looks just like an operation with no
72//! arguments and the attribute's type as the return type.
73//!
74//! The setter's name is `Set` followed by the name of the attribute with the
75//! first letter converted to uppercase. The method signature looks just like
76//! an operation with a void return value and a single argument whose type is
77//! the attribute's type.
78//!
79//! Rust reflections of WebIDL constructors
80//! ---------------------------------------
81//!
82//! A WebIDL constructor is turned into a static class method named
83//! `Constructor`. The arguments of this method will be the arguments of the
84//! WebIDL constructor, with a `&GlobalScope` for the relevant global prepended.
85//! The return value of the constructor for MyInterface is exactly the same as
86//! that of a method returning an instance of MyInterface. Constructors are
87//! always [allowed to throw](#throwing-exceptions).
88//!
89//! Rust reflections of WebIDL types
90//! --------------------------------
91//!
92//! The exact Rust representation for WebIDL types can depend on the precise
93//! way that they're being used (e.g., return values and arguments might have
94//! different representations).
95//!
96//! Optional arguments which do not have a default value are represented by
97//! wrapping `Option<T>` around the representation of the argument type.
98//! Optional arguments which do have a default value are represented by the
99//! argument type itself, set to the default value if the argument was not in
100//! fact passed in.
101//!
102//! Variadic WebIDL arguments are represented by wrapping a `Vec<T>` around the
103//! representation of the argument type.
104//!
105//! See [the type mapping for particular types](conversions/index.html).
106//!
107//! Rust reflections of stringifiers
108//! --------------------------------
109//!
110//! *To be written.*
111//!
112//! Rust reflections of legacy callers
113//! ---------------------------------
114//!
115//! Legacy callers are not yet implemented.
116//!
117//! Throwing exceptions
118//! ===================
119//!
120//! WebIDL methods, getters, and setters that need to throw exceptions need to
121//! be explicitly marked as such with the `[Throws]`, `[GetterThrows]` and
122//! `[SetterThrows]` custom attributes.
123//!
124//! `[Throws]` applies to both methods and attributes; for attributes it means
125//! both the getter and the setter (if any) can throw. `[GetterThrows]` applies
126//! only to attributes. `[SetterThrows]` applies only to writable attributes.
127//!
128//! The corresponding Rust methods will have the return value wrapped in
129//! [`Fallible<T>`](error/type.Fallible.html). To throw an exception, simply
130//! return `Err()` from the method with the appropriate [error value]
131//! (error/enum.Error.html).
132
133#![allow(unsafe_code)]
134#![deny(missing_docs)]
135#![deny(non_snake_case)]
136
137pub(crate) mod buffer_source;
138#[allow(dead_code)]
139pub(crate) mod cell;
140pub(crate) mod constructor;
141pub(crate) mod conversions;
142pub(crate) mod domname;
143pub(crate) mod error;
144pub(crate) mod frozenarray;
145pub(crate) mod function;
146pub(crate) mod import;
147pub(crate) mod inheritance;
148pub(crate) mod like;
149pub(crate) mod principals;
150pub(crate) mod proxyhandler;
151pub(crate) mod refcounted;
152pub(crate) mod reflector;
153pub(crate) mod root;
154pub(crate) mod serializable;
155pub(crate) mod settings_stack;
156pub(crate) mod str;
157pub(crate) mod structuredclone;
158pub(crate) mod trace;
159pub(crate) mod transferable;
160pub(crate) mod utils;
161pub(crate) mod weakref;
162pub(crate) mod xmlname;
163
164pub(crate) use script_bindings::{callback, iterable, num};
165
166/// Generated JS-Rust bindings.
167#[allow(missing_docs, non_snake_case)]
168pub(crate) mod codegen {
169    pub(crate) mod DomTypeHolder {
170        include!(concat!(env!("OUT_DIR"), "/DomTypeHolder.rs"));
171    }
172    pub(crate) use script_bindings::codegen::GenericBindings;
173    #[allow(dead_code)]
174    pub(crate) mod Bindings {
175        include!(concat!(env!("OUT_DIR"), "/ConcreteBindings/mod.rs"));
176    }
177    pub(crate) mod InterfaceObjectMap {
178        include!(concat!(env!("OUT_DIR"), "/InterfaceObjectMap.rs"));
179    }
180    pub(crate) mod ConcreteInheritTypes {
181        include!(concat!(env!("OUT_DIR"), "/ConcreteInheritTypes.rs"));
182    }
183    pub(crate) use script_bindings::codegen::{PrototypeList, RegisterBindings};
184    #[allow(dead_code)]
185    pub(crate) mod UnionTypes {
186        include!(concat!(env!("OUT_DIR"), "/UnionTypes.rs"));
187    }
188}
script/dom/bindings/mod.rs

script/dom/bindings/
mod.rs
