This document defines an interface definition language, Web IDL, that can be used to describe interfaces that are intended to be implemented in web browsers. Web IDL is an IDL variant with a number of features that allow the behavior of common script objects in the web platform to be specified more readily. How interfaces described with Web IDL correspond to constructs within ECMAScript execution environments is also detailed in this document. It is expected that newly published specifications reference this document to ensure conforming implementations of interfaces are interoperable.
Status of This DocumentThis section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
This is the "Level 1" Version of WebIDL, it contains parts of the main Editor's copy [WEBIDL] that are considered stable, implemented and tested. Implementors who do not need to reference a stable version of WebIDL should defer to the Editor's copy [WEBIDL] only, as it may contain updated algorithm and definitions; this specification is suitable for reference by other specification authors in so far as it wholly contains the syntax definitions used in the citing document. New syntax definitions will be added in the next Level of WebIDL.
It is important to note that parts of this specification highlight future changes. Some features might become deprecated and new features will be added. Readers of this specification should also read the Editor's Copy and subsequent Levels of this specification to ensure that what they use is still matching implementations.
This document is produced by the Web Platform Working Group in the W3C Interaction Domain. Changes made to this document can be found in the specification’s commit log on GitHub: recent changes, older changes.
There is a bug tracker for the specification, but look at the Editor's copy to ensure that possible bugs are not yet addressed.
This document was published by the Web Platform Working Group as a Recommendation. If you wish to make comments regarding this document, please send them to public-script-coord@w3.org (subscribe, archives). All comments are welcome.
Please see the Working Group's implementation report.
This document has been reviewed by W3C Members, by software developers, and by other W3C groups and interested parties, and is endorsed by the Director as a W3C Recommendation. It is a stable document and may be used as reference material or cited from another document. W3C's role in making the Recommendation is to draw attention to the specification and to promote its widespread deployment. This enhances the functionality and interoperability of the Web.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This document is governed by the 1 September 2015 W3C Process Document.
Table of ContentsThis section is informative.
Technical reports published by the W3C that include programming language interfaces have typically been described using the Object Management Group’s Interface Definition Language (IDL) [ OMGIDL]. The IDL provides a means to describe these interfaces in a language independent manner. Usually, additional language binding appendices are included in such documents which detail how the interfaces described with the IDL correspond to constructs in the given language.
However, the bindings in these specifications for the language most commonly used on the web, ECMAScript, are consistently specified with low enough precision as to result in interoperability issues. In addition, each specification must describe the same basic information, such as DOM interfaces described in IDL corresponding to properties on the ECMAScript global object, or the unsigned long IDL type mapping to the Number type in ECMAScript.
This specification defines an IDL language similar to OMG IDL for use by specifications that define interfaces for Web APIs. A number of extensions are given to the IDL to support common functionality that previously must have been written in prose. In addition, precise language bindings for ECMAScript Edition 6 are given.
1.1 Typographic conventionsThe following typographic conventions are used in this document:
a = b + obj.f()interface identifier {
interface-members…
}; (Red text is used to highlight specific parts of the syntax discussed in surrounding prose.)Warning
This is a warning.
IDL
interface Example {
attribute long something;
};ECMAScript
window.onload = function() { window.alert("loaded"); };As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MAY, MUST, MUST NOT, REQUIRED, SHALL, SHOULD, and SHOULD NOT are to be interpreted as described in [RFC2119].
The following conformance classes are defined by this specification:
A set of IDL fragments is considered to be a conforming set of IDL fragments if, taken together, they satisfy all of the MUST-, REQUIRED- and SHALL-level criteria in this specification that apply to IDL fragments.
A user agent is considered to be a conforming implementation relative to a conforming set of IDL fragments if it satisfies all of the MUST-, REQUIRED- and SHALL-level criteria in this specification that apply to implementations for all language bindings that the user agent supports.
A user agent is considered to be a conforming ECMAScript implementation relative to a conforming set of IDL fragments if it satisfies all of the MUST-, REQUIRED- and SHALL-level criteria in this specification that apply to implementations for the ECMAScript language binding.
This section describes a language, Web IDL, which can be used to define interfaces for APIs in the Web platform. A specification that defines Web APIs can include one or more IDL fragments that describe the interfaces (the state and behavior that objects can exhibit) for the APIs defined by that specification. An IDL fragment is a sequence of definitions that matches the Definitions grammar symbol. The set of IDL fragments that an implementation supports is not ordered. See Appendix A. for the complete grammar and an explanation of the notation used.
The different kinds of definitions that can appear in an IDL fragment are: interfaces, partial interface definitions, dictionaries, partial dictionary definitions, typedefs and implements statements. These are all defined in the following sections.
Each definition (matching Definition) can be preceded by a list of extended attributes (matching ExtendedAttributeList), which can control how the definition will be handled in language bindings. The extended attributes defined by this specification that are language binding agnostic are discussed in section 3.11 , while those specific to the ECMAScript language binding are discussed in section 4.3 .
[extended-attributes]
interface identifier {
interface-members…
};
The following is an example of an IDL fragment.
IDL
interface Paint { };
interface SolidColor : Paint {
attribute double red;
attribute double green;
attribute double blue;
};
interface Pattern : Paint {
attribute DOMString imageURL;
};
[Constructor]
interface GraphicalWindow {
readonly attribute unsigned long width;
readonly attribute unsigned long height;
attribute Paint currentPaint;
void drawRectangle(double x, double y, double width, double height);
void drawText(double x, double y, DOMString text);
};Here, four interfaces are being defined. The GraphicalWindow interface has two read only attributes, one writable attribute, and two operations defined on it. Objects that implement the GraphicalWindow interface will expose these attributes and operations in a manner appropriate to the particular language being used.
In ECMAScript, the attributes on the IDL interfaces will be exposed as accessor properties and the operations as Function-valued data properties on a prototype object for all GraphicalWindow objects; each ECMAScript object that implements GraphicalWindow will have that prototype object in its prototype chain.
The [Constructor] that appears on GraphicalWindow is an extended attribute. This extended attribute causes a constructor to exist in ECMAScript implementations, so that calling new GraphicalWindow() would return a new object that implemented the interface.
Every interface, partial interface definition, dictionary, partial dictionary definition, enumeration, callback function and typedef (together called named definitions) and every constant, attribute, and dictionary member has an identifier, as do some operations. The identifier is determined by an identifier token somewhere in the declaration:
interface, dictionary, enum or callback keyword determines the identifier of that definition.
interface interface-identifier { interface-members… };
partial interface interface-identifier { interface-members… };
dictionary dictionary-identifier { dictionary-members… };
partial dictionary dictionary-identifier { dictionary-members… };
enum enumeration-identifier { enumeration-values… };
callback callback-identifier = callback-signature;interface identifier {
attribute type attribute-identifier;
};
typedef type typedef-identifier;
dictionary identifier {
type dictionary-member-identifier;
};const type constant-identifier = value;
return-type operation-identifier(arguments…);
Note
Operations can have no identifier when they are being used to declare a special kind of operation, such as a getter or setter.
For all of these constructs, the identifier is the value of the identifier token with any leading U+005F LOW LINE ("_") character (underscore) removed.
Note
A leading "_" is used to escape an identifier from looking like a reserved word so that, for example, an interface named “interface” can be defined. The leading "_" is dropped to unescape the identifier.
Operation arguments can take a slightly wider set of identifiers. In an operation declaration, the identifier of an argument is specified immediately after its type and is given by either an identifier token or by one of the keywords that match the ArgumentNameKeyword symbol. If one of these keywords is used, it need not be escaped with a leading underscore.
return-type operation-identifier(argument-type argument-identifier, …);[71] ArgumentNameKeyword → "attribute"
If an identifier token is used, then the identifier of the operation argument is the value of that token with any leading U+005F LOW LINE ("_") character (underscore) removed. If instead one of the ArgumentNameKeyword keyword token is used, then the identifier of the operation argument is simply that token.
The identifier of any of the abovementioned IDL constructs MUST NOT be “constructor”, “toString”, “toJSON”, or begin with a U+005F LOW LINE ("_") character. These are known as reserved identifiers.
Note
Further restrictions on identifier names for particular constructs may be made in later sections.
Within the set of IDL fragments that a given implementation supports, the identifier of every interface, dictionary, enumeration, callback function and typedef MUST NOT be the same as the identifier of any other interface, dictionary, enumeration, callback function or typedef.
Within an IDL fragment, a reference to a definition need not appear after the declaration of the referenced definition. References can also be made across IDL fragments.
Therefore, the following IDL fragment is valid:
IDL
interface B : A {
void f(SequenceOfLongs x);
};
interface A {
};
typedef sequence<long> SequenceOfLongs;The following IDL fragment demonstrates how identifiers are given to definitions and interface members.
IDL
typedef double number;
interface System {
object createObject(DOMString _interface);
sequence<object> getObjects(DOMString interface);
getter DOMString (DOMString keyName);
};
interface TextField {
attribute boolean _const;
attribute DOMString? _value;
};Note that while the second attribute on the TextField interface need not have been escaped with an underscore (because “value” is not a keyword in the IDL grammar), it is still unescaped to obtain the attribute’s identifier.
3.2 InterfacesIDL fragments are used to describe object oriented systems. In such systems, objects are entities that have identity and which are encapsulations of state and behavior. An interface is a definition (matching Interface or "callback" Interface) that declares some state and behavior that an object implementing that interface will expose.
interface identifier {
interface-members…
};
An interface is a specification of a set of interface members (matching InterfaceMembers), which are the constants, attributes, operations and other declarations that appear between the braces in the interface declaration. Attributes describe the state that an object implementing the interface will expose, and operations describe the behaviors that can be invoked on the object. Constants declare named constant values that are exposed as a convenience to users of objects in the system.
Interfaces in Web IDL describe how objects that implement the interface behave. In bindings for object oriented languages, it is expected that an object that implements a particular IDL interface provides ways to inspect and modify the object's state and to invoke the behavior described by the interface.
An interface can be defined to inherit from another interface. If the identifier of the interface is followed by a U+003A COLON (":") character and an identifier, then that identifier identifies the inherited interface. An object that implements an interface that inherits from another also implements that inherited interface. The object therefore will also have members that correspond to the interface members from the inherited interface.
interface identifier : identifier-of-inherited-interface {
interface-members…
};
The order that members appear in has no significance except in the case of overloading.
Interfaces may specify an interface member that has the same name as one from an inherited interface. Objects that implement the derived interface will expose the member on the derived interface. It is language binding specific whether the overridden member can be accessed on the object.
Consider the following two interfaces.
IDL
interface A {
void f();
void g();
};
interface B : A {
void f();
void g(DOMString x);
};In the ECMAScript language binding, an instance of B will have a prototype chain that looks like the following:
[Object.prototype: the Object prototype object]
↑
[A.prototype: interface prototype object for A]
↑
[B.prototype: interface prototype object for B]
↑
[instanceOfB]
Calling instanceOfB.f() in ECMAScript will invoke the f defined on B. However, the f from A can still be invoked on an object that implements B by calling A.prototype.f.call(instanceOfB).
The inherited interfaces of a given interface A is the set of all interfaces that A inherits from, directly or indirectly. If A does not inherit from another interface, then the set is empty. Otherwise, the set includes the interface B that A inherits from and all of B’s inherited interfaces.
An interface MUST NOT be declared such that its inheritance hierarchy has a cycle. That is, an interface A cannot inherit from itself, nor can it inherit from another interface B that inherits from A, and so on.
Note that general multiple inheritance of interfaces is not supported, and objects also cannot implement arbitrary sets of interfaces. Objects can be defined to implement a single given interface A, which means that it also implements all of A’s inherited interfaces. In addition, an implements statement can be used to define that objects implementing an interface will always also implement another interface.
Each interface member can be preceded by a list of extended attributes (matching ExtendedAttributeList), which can control how the interface member will be handled in language bindings.
interface identifier {
[extended-attributes]
const type identifier = value;
[extended-attributes]
attribute type identifier;
[extended-attributes]
return-type identifier(arguments…);
};
A callback interface is an interface that uses the callback keyword at the start of its definition. Callback interfaces are ones that can be implemented by user objects and not by platform objects, as described in section 3.9 .
callback interface identifier {
interface-members…
};
Callback interfaces MUST NOT inherit from any non-callback interfaces, and non-callback interfaces MUST NOT inherit from any callback interfaces. Callback interfaces MUST NOT have any consequential interfaces.
Static attributes and static operations MUST NOT be defined on a callback interface.
Warning
Specification authors SHOULD NOT define callback interfaces that have only a single operation, unless required to describe the requirements of existing APIs. Instead, a callback function SHOULD be used.
The definition of EventListener as a callback interface is an example of an existing API that needs to allow user objects with a given property (in this case “handleEvent”) to be considered to implement the interface. For new APIs, and those for which there are no compatibility concerns, using a callback function will allow only a Function object (in the ECMAScript language binding).
Note
Specification authors wanting to define APIs that take ECMAScript objects as “property bag” like function arguments are suggested to use dictionary types rather than callback interfaces.
For example, instead of this:
IDL
callback interface Options {
attribute DOMString? option1;
attribute DOMString? option2;
attribute long? option3;
};
interface A {
void doTask(DOMString type, Options options);
};to be used like this:
ECMAScript
var a = getA();
a.doTask("something", { option1: "banana", option3: 100 });instead write the following:
IDL
dictionary Options {
DOMString? option1;
DOMString? option2;
long? option3;
};
interface A {
void doTask(DOMString type, Options options);
};The IDL for interfaces can be split into multiple parts by using partial interface definitions (matching "partial" PartialInterface). The identifier of a partial interface definition MUST be the same as the identifier of an interface definition. All of the members that appear on each of the partial interfaces are considered to be members of the interface itself.
interface SomeInterface {
interface-members…
};
partial interface SomeInterface {
interface-members…
};
Note
Partial interface definitions are intended for use as a specification editorial aide, allowing the definition of an interface to be separated over more than one section of the document, and sometimes multiple documents.
The order of appearance of an interface definition and any of its partial interface definitions does not matter.
Note
A partial interface definition cannot specify that the interface inherits from another interface. Inheritance must be specified on the original interface definition.
Extended attributes can be specified on partial interface definitions, with some limitations. The following extended attributes MUST NOT be specified on partial interface definitions: [Constructor], [NamedConstructor], [NoInterfaceObject].
Any extended attribute specified on a partial interface definition is considered to appear on the interface itself.
The relevant language binding determines how interfaces correspond to constructs in the language.
The following extended attributes are applicable to interfaces: [Constructor], [Exposed], [Global], [NamedConstructor], [NoInterfaceObject], [OverrideBuiltins]. [PrimaryGlobal], [Unforgeable].
The following IDL fragment demonstrates the definition of two mutually referential interfaces. Both Human and Dog inherit from Animal. Objects that implement either of those two interfaces will thus have a name attribute.
IDL
interface Animal {
attribute DOMString name;
};
interface Human : Animal {
attribute Dog? pet;
};
interface Dog : Animal {
attribute Human? owner;
};The following IDL fragment defines simplified versions of a few DOM interfaces, one of which is a callback interface.
IDL
interface Node {
readonly attribute DOMString nodeName;
readonly attribute Node? parentNode;
Node appendChild(Node newChild);
void addEventListener(DOMString type, EventListener listener);
};
callback interface EventListener {
void handleEvent(Event event);
};Since the EventListener interface is annotated callback interface, user objects can implement it:
ECMAScript
var node = getNode();
var listener = {
handleEvent: function(event) {
...
}
};
node.addEventListener("click", listener);
node.addEventListener("click", function() { ... }); It is not possible for a user object to implement Node, however:
ECMAScript
var node = getNode();
var newNode = {
nodeName: "span",
parentNode: null,
appendChild: function(newchild) {
...
},
addEventListener: function(type, listener) {
...
}
};
node.appendChild(newNode); A constant is a declaration (matching Const) used to bind a constant value to a name. Constants can appear on interfaces.
Warning
Constants have in the past primarily been used to define named integer codes in the style of an enumeration. The Web platform is moving away from this design pattern in favor of the use of strings. Specification authors who wish to define constants are strongly advised to discuss this on the public-script-coord@w3.org mailing list before proceeding.
const type identifier = value;
The identifier of a constant MUST NOT be the same as the identifier of another interface member defined on the same interface. The identifier also MUST NOT be “length”, “name” or “prototype”.
Note
These three names are the names of properties that exist on all Function objects.
The type of a constant (matching ConstType) MUST NOT be any type other than a primitive type or a nullable primitive type. If an identifier is used, it MUST reference a typedef whose type is a primitive type or a nullable primitive type.
The ConstValue part of a constant declaration gives the value of the constant, which can be one of the two boolean literal tokens (true and false), the null token, an integer token, a float token, or one of the three special floating point constant values (-Infinity, Infinity and NaN).
The value of the boolean literal tokens true and false are the IDL boolean values true and false.
The value of an integer token is an integer whose value is determined as follows:
The type of an integer token is the same as the type of the constant, dictionary member or optional argument it is being used as the value of. The value of the integer token MUST NOT lie outside the valid range of values for its type, as given in section 3.10 .
The value of a float token is either an IEEE 754 single-precision floating point number or an IEEE 754 double-precision floating point number, depending on the type of the constant, dictionary member or optional argument it is being used as the value for, determined as follows:
The value of a constant value specified as Infinity, -Infinity or NaN is either an IEEE 754 single-precision floating point number or an IEEE 754 double-precision floating point number, depending on the type of the constant, dictionary member or optional argument is is being used as the value for:
Infinity
Infinity
-Infinity
-Infinity
NaN
NaN
The type of a float token is the same as the type of the constant, dictionary member or optional argument it is being used as the value of. The value of the float token MUST NOT lie outside the valid range of values for its type, as given in section 3.10 . Also, Infinity, -Infinity and NaN MUST NOT be used as the value of a float or double.
The value of the null token is the special null value that is a member of the nullable types. The type of the null token is the same as the type of the constant, dictionary member or optional argument it is being used as the value of.
If VT is the type of the value assigned to a constant, and DT is the type of the constant, dictionary member or optional argument itself, then these types MUST be compatible, which is the case if DT and VT are identical, or DT is a nullable type whose inner type is VT.
Constants are not associated with particular instances of the interface on which they appear. It is language binding specific whether constants are exposed on instances.
Note
The ECMAScript language binding does however allow constants to be accessed through objects implementing the IDL interfaces on which the constants are declared. For example, with the following IDL:
IDL
interface A {
const short rambaldi = 47;
};the constant value can be accessed in ECMAScript either as A.rambaldi or instanceOfA.rambaldi.
The following extended attributes are applicable to constants: [Exposed].
The following IDL fragment demonstrates how constants of the above types can be defined.
IDL
interface Util {
const boolean DEBUG = false;
const octet LF = 10;
const unsigned long BIT_MASK = 0x0000fc00;
const double AVOGADRO = 6.022e23;
};An attribute is an interface member (matching "inherit" ReadOnly AttributeRest, "static" ReadOnly AttributeRest, "stringifier" ReadOnly AttributeRest, or ReadOnly AttributeRest) that is used to declare data fields with a given type and identifier whose value can be retrieved and (in some cases) changed. There are two kinds of attributes:
attribute type identifier;
static attribute type identifier;
If an attribute has no static keyword, then it declares a regular attribute. Otherwise, it declares a static attribute.
The identifier of an attribute MUST NOT be the same as the identifier of another interface member defined on the same interface. The identifier of a static attribute MUST NOT be “prototype”.
The type of the attribute is given by the type (matching Type) that appears after the attribute keyword. If the Type is an identifier or an identifier followed by ?, then the identifier MUST identify an interface, enumeration, callback function or typedef.
The type of the attribute, after resolving typedefs, MUST NOT be a nullable or non-nullable version of any of the following types:
The attribute is read only if the readonly keyword is used before the attribute keyword. An object that implements the interface on which a read only attribute is defined will not allow assignment to that attribute. It is language binding specific whether assignment is simply disallowed by the language, ignored or an exception is thrown.
readonly attribute type identifier;
A regular attribute that is not read only can be declared to inherit its getter from an ancestor interface. This can be used to make a read only attribute in an ancestor interface be writable on a derived interface. An attribute inherits its getter if its declaration includes inherit in the declaration. The read only attribute from which the attribute inherits its getter is the attribute with the same identifier on the closest ancestor interface of the one on which the inheriting attribute is defined. The attribute whose getter is being inherited MUST be of the same type as the inheriting attribute, and inherit MUST NOT appear on a read only attribute or a static attribute.
interface Ancestor {
readonly attribute TheType theIdentifier;
};
interface Derived : Ancestor {
inherit attribute TheType theIdentifier;
};
When the stringifier keyword is used in a regular attribute declaration, it indicates that objects implementing the interface will be stringified to the value of the attribute. See section 3.2.4.2 for details.
stringifier attribute DOMString identifier;
If an implementation attempts to get or set the value of an attribute on a user object (for example, when a callback object has been supplied to the implementation), and that attempt results in an exception being thrown, then, unless otherwise specified, that exception will be propagated to the user code that caused the implementation to access the attribute. Similarly, if a value returned from getting the attribute cannot be converted to an IDL type, then any exception resulting from this will also be propagated to the user code that resulted in the implementation attempting to get the value of the attribute.
The following extended attributes are applicable to regular and static attributes: [Clamp], [EnforceRange], [Exposed], [SameObject], [TreatNullAs].
The following extended attributes are applicable only to regular attributes: [LenientThis], [PutForwards], [Replaceable], [Unforgeable].
The following IDL fragment demonstrates how attributes can be declared on an interface:
IDL
interface Animal {
readonly attribute DOMString name;
attribute unsigned short age;
};
interface Person : Animal {
inherit attribute DOMString name;
};An operation is an interface member (matching "static" OperationRest, "stringifier" OperationRest, "serializer" OperationRest, ReturnType OperationRest or SpecialOperation) that defines a behavior that can be invoked on objects implementing the interface. There are three kinds of operation:
return-type identifier(arguments…);
special-keywords… return-type identifier(arguments…); special-keywords… return-type (arguments…);
static return-type identifier(arguments…);
If an operation has an identifier but no static keyword, then it declares a regular operation. If the operation has one or more special keywords used in its declaration (that is, any keyword matching Special, or the stringifier keyword), then it declares a special operation. A single operation can declare both a regular operation and a special operation; see section 3.2.4 for details on special operations.
If an operation has no identifier, then it MUST be declared to be a special operation using one of the special keywords.
The identifier of a regular operation or static operation MUST NOT be the same as the identifier of a constant or attribute defined on the same interface. The identifier of a static operation MUST NOT be “prototype”.
Note
The identifier can be the same as that of another operation on the interface, however. This is how operation overloading is specified.
The identifier of a static operation also MUST NOT be the same as the identifier of a regular operation defined on the same interface.
The return type of the operation is given by the type (matching ReturnType) that appears before the operation’s optional identifier. A return type of void indicates that the operation returns no value. If the return type is an identifier followed by ?, then the identifier MUST identify an interface, dictionary, enumeration, callback function or typedef.
An operation’s arguments (matching ArgumentList) are given between the parentheses in the declaration. Each individual argument is specified as a type (matching Type) followed by an identifier (matching ArgumentName).
Note
For expressiveness, the identifier of an operation argument can also be specified as one of the keywords matching the ArgumentNameKeyword symbol without needing to escape it.
If the Type of an operation argument is an identifier followed by ?, then the identifier MUST identify an interface, enumeration, callback function or typedef. If the operation argument type is an identifier not followed by ?, then the identifier MUST identify any one of those definitions or a dictionary.
return-type identifier(type identifier, type identifier, …);
The identifier of each argument MUST NOT be the same as the identifier of another argument in the same operation declaration.
Each argument can be preceded by a list of extended attributes (matching ExtendedAttributeList), which can control how a value passed as the argument will be handled in language bindings.
return-type identifier([extended-attributes] type identifier, [extended-attributes] type identifier, …);
The following IDL fragment demonstrates how regular operations can be declared on an interface:
IDL
interface Dimensions {
attribute unsigned long width;
attribute unsigned long height;
};
interface Button {
boolean isMouseOver();
void setDimensions(Dimensions size);
void setDimensions(unsigned long width, unsigned long height);
};An operation is considered to be variadic if the final argument uses the ... token just after the argument type. Declaring an operation to be variadic indicates that the operation can be invoked with any number of arguments after that final argument. Those extra implied formal arguments are of the same type as the final explicit argument in the operation declaration. The final argument can also be omitted when invoking the operation. An argument MUST NOT be declared with the ... token unless it is the final argument in the operation’s argument list.
return-type identifier(type... identifier); return-type identifier(type identifier, type... identifier);
Extended attributes that take an argument list ([Constructor] and [NamedConstructor], of those defined in this specification) and callback functions are also considered to be variadic when the ... token is used in their argument lists.
The following IDL fragment defines an interface that has two variadic operations:
IDL
interface IntegerSet {
readonly attribute unsigned long cardinality;
void union(long... ints);
void intersection(long... ints);
};In the ECMAScript binding, variadic operations are implemented by functions that can accept the subsequent arguments:
ECMAScript
var s = getIntegerSet();
s.union();
s.union(1, 4, 7); A binding for a language that does not support variadic functions might specify that an explicit array or list of integers be passed to such an operation.
An argument is considered to be an optional argument if it is declared with the optional keyword. The final argument of a variadic operation is also considered to be an optional argument. Declaring an argument to be optional indicates that the argument value can be omitted when the operation is invoked. The final argument in an operation MUST NOT explicitly be declared to be optional if the operation is variadic.
return-type identifier(type identifier, optional type identifier);
Optional arguments can also have a default value specified. If the argument’s identifier is followed by a U+003D EQUALS SIGN ("=") and a value (matching DefaultValue), then that gives the optional argument its default value. The implicitly optional final argument of a variadic operation MUST NOT have a default value specified. The default value is the value to be assumed when the operation is called with the corresponding argument omitted.
return-type identifier(type identifier, optional type identifier = value);
Warning
It is strongly suggested not to use default value of true for boolean-typed arguments, as this can be confusing for authors who might otherwise expect the default conversion of undefined to be used (i.e., false).
If the type of an argument is a dictionary type or a union type that has a dictionary type as one of its flattened member types, and that dictionary type and its ancestors have no required members, and the argument is either the final argument or is followed only by optional arguments, then the argument MUST be specified as optional. Such arguments are always considered to have a default value of an empty dictionary, unless otherwise specified.
Note
This is to encourage API designs that do not require authors to pass an empty dictionary value when they wish only to use the dictionary’s default values.
Dictionary types cannot have a default value specified explicitly, so the “unless otherwise specified” clause above can only be invoked for a union type that has a dictionary type as one of its flattened member types.
When a boolean literal token (true or false), the null token, an integer token, a float token or one of the three special floating point literal values (Infinity, -Infinity or NaN) is used as the default value, it is interpreted in the same way as for a constant.
Optional argument default values can also be specified using a string token, whose value is a string type determined as follows:
If the type of the optional argument is an enumeration, then its default value if specified MUST be one of the enumeration’s values.
Optional argument default values can also be specified using the two token value [], which represents an empty sequence value. The type of this value is the same the type of the optional argument it is being used as the default value of. That type MUST be a sequence type or a nullable type.
The following IDL fragment defines an interface with a single operation that can be invoked with two different argument list lengths:
IDL
interface ColorCreator {
object createColor(double v1, double v2, double v3, optional double alpha);
};It is equivalent to an interface that has two overloaded operations:
IDL
interface ColorCreator {
object createColor(double v1, double v2, double v3);
object createColor(double v1, double v2, double v3, double alpha);
};If an implementation attempts to invoke an operation on a user object (for example, when a callback object has been supplied to the implementation), and that attempt results in an exception being thrown, then, unless otherwise specified, that exception will be propagated to the user code that caused the implementation to invoke the operation. Similarly, if a value returned from invoking the operation cannot be converted to an IDL type, then any exception resulting from this will also be propagated to the user code that resulted in the implementation attempting to invoke the operation.
The following extended attributes are applicable to operations: [Exposed], [NewObject], [TreatNullAs], [Unforgeable].
The following extended attributes are applicable to operation arguments: [Clamp], [EnforceRange], [TreatNullAs].
3.2.4 Special operationsA special operation is a declaration of a certain kind of special behavior on objects implementing the interface on which the special operation declarations appear. Special operations are declared by using one or more special keywords in an operation declaration.
There are six kinds of special operations. The table below indicates for a given kind of special operation what special keyword is used to declare it and what the purpose of the special operation is:
Special operation Keyword Purpose Gettersgetter Defines behavior for when an object is indexed for property retrieval. Setters setter Defines behavior for when an object is indexed for property assignment or creation. Deleters deleter Defines behavior for when an object is indexed for property deletion. Legacy callers legacycaller Defines behavior for when an object is called as if it were a function. Stringifiers stringifier Defines how an object is converted into a DOMString. Serializers serializer Defines how an object is converted into a serialized form.
Not all language bindings support all of the six kinds of special object behavior. When special operations are declared using operations with no identifier, then in language bindings that do not support the particular kind of special operations there simply will not be such functionality.
The following IDL fragment defines an interface with a getter and a setter:
IDL
interface Dictionary {
readonly attribute unsigned long propertyCount;
getter double (DOMString propertyName);
setter void (DOMString propertyName, double propertyValue);
};In language bindings that do not support property getters and setters, objects implementing Dictionary will not have that special behavior.
Defining a special operation with an identifier is equivalent to separating the special operation out into its own declaration without an identifier. This approach is allowed to simplify prose descriptions of an interface’s operations.
The following two interfaces are equivalent:
IDL
interface Dictionary {
readonly attribute unsigned long propertyCount;
getter double getProperty(DOMString propertyName);
setter void setProperty(DOMString propertyName, double propertyValue);
};IDL
interface Dictionary {
readonly attribute unsigned long propertyCount;
double getProperty(DOMString propertyName);
void setProperty(DOMString propertyName, double propertyValue);
getter double (DOMString propertyName);
setter void (DOMString propertyName, double propertyValue);
};A given special keyword MUST NOT appear twice on an operation.
Getters and setters come in two varieties: ones that take a DOMString as a property name, known as named property getters and named property setters, and ones that take an unsigned long as a property index, known as indexed property getters and indexed property setters. There is only one variety of deleter: named property deleters. See section 3.2.4.4 and section 3.2.4.5 for details.
On a given interface, there MUST exist at most one stringifier, at most one serializer, at most one named property deleter, and at most one of each variety of getter and setter. Multiple legacy callers can exist on an interface to specify overloaded calling behavior.
If an interface has a setter of a given variety, then it MUST also have a getter of that variety. If it has a named property deleter, then it MUST also have a named property getter.
Special operations declared using operations MUST NOT be variadic nor have any optional arguments.
Special operations MUST NOT be declared on callback interfaces.
If an object implements more than one interface that defines a given special operation, then it is undefined which (if any) special operation is invoked for that operation.
3.2.4.1 Legacy callersWhen an interface has one or more legacy callers, it indicates that objects that implement the interface can be called as if they were functions. As mentioned above, legacy callers can be specified using an operation declared with the legacycaller keyword.
legacycaller return-type identifier(arguments…); legacycaller return-type (arguments…);
If multiple legacy callers are specified on an interface, overload resolution is used to determine which legacy caller is invoked when the object is called as if it were a function.
Legacy callers MUST NOT be defined to return a promise type.
Warning
Legacy callers are universally recognised as an undesirable feature. They exist only so that legacy Web platform features can be specified. Legacy callers SHOULD NOT be used in specifications unless required to specify the behavior of legacy APIs, and even then this should be discussed on the public-script-coord@w3.org mailing list before proceeding.
The following IDL fragment defines an interface with a legacy caller.
IDL
interface NumberQuadrupler {
legacycaller double compute(double x);
};An ECMAScript implementation supporting this interface would allow a platform object that implements NumberQuadrupler to be called as a function:
ECMAScript
var f = getNumberQuadrupler();
f.compute(3);
f(3); When an interface has a stringifier, it indicates that objects that implement the interface have a non-default conversion to a string. As mentioned above, stringifiers can be specified using an operation declared with the stringifier keyword.
stringifier DOMString identifier(); stringifier DOMString ();
If an operation used to declare a stringifier does not have an identifier, then prose accompanying the interface MUST define the stringification behavior of the interface. If the operation does have an identifier, then the object is converted to a string by invoking the operation to obtain the string.
Stringifiers declared with operations MUST be declared to take zero arguments and return a DOMString.
As a shorthand, if the stringifier keyword is declared using an operation with no identifier, then the operation’s return type and argument list can be omitted.
stringifier;
The following two interfaces are equivalent:
IDL
interface A {
stringifier DOMString ();
};IDL
interface A {
stringifier;
};The stringifier keyword can also be placed on an attribute. In this case, the string to convert the object to is the value of the attribute. The stringifier keyword MUST NOT be placed on an attribute unless it is declared to be of type DOMString or USVString. It also MUST NOT be placed on a static attribute.
stringifier attribute DOMString identifier;
The following IDL fragment defines an interface that will stringify to the value of its name attribute:
IDL
[Constructor]
interface Student {
attribute unsigned long id;
stringifier attribute DOMString name;
};In the ECMAScript binding, using a Student object in a context where a string is expected will result in the value of the object’s “name” property being used:
ECMAScript
var s = new Student();
s.id = 12345678;
s.name = '周杰倫';
var greeting = 'Hello, ' + s + '!'; The following IDL fragment defines an interface that has custom stringification behavior that is not specified in the IDL itself.
IDL
[Constructor]
interface Student {
attribute unsigned long id;
attribute DOMString? familyName;
attribute DOMString givenName;
stringifier DOMString ();
};Thus, prose is required to explain the stringification behavior, such as the following paragraph:
Objects that implement the Student interface must stringify as follows. If the value of the familyName attribute is null, the stringification of the object is the value of the givenName attribute. Otherwise, if the value of the familyName attribute is not null, the stringification of the object is the concatenation of the value of the givenName attribute, a single space character, and the value of the familyName attribute.
An ECMAScript implementation of the IDL would behave as follows:
ECMAScript
var s = new Student();
s.id = 12345679;
s.familyName = 'Smithee';
s.givenName = 'Alan';
var greeting = 'Hi ' + s; Warning
The NodeFilterSerializers will be simplified soon, please see discussions in Issue 188
When an interface has a serializer, it indicates that objects provide a way for them to be converted into a serialized form. Serializers can be declared using the serializer keyword:
serializer;
Prose accompanying an interface that declares a serializer in this way MUST define the serialization behavior of the interface. Serialization behavior is defined as returning a serialized value of one of the following types:
How the serialization behavior is made available on an object in a language binding, and how exactly the abstract serialized value is converted into an appropriate concrete value, is language binding specific.
Serialization behavior can also be specified directly in IDL, rather than separately as prose. This is done by following the serializer keyword with a U+003D EQUALS SIGN ("=") character and a serialization pattern, which can take one of the following six forms:
A map with entries corresponding to zero or more attributes from the interface, and optionally attributes from an inherited interface:
serializer = { attribute-identifier, attribute-identifier, … };
serializer = { inherit, attribute-identifier, attribute-identifier, … };
Each identifier MUST be the identifier of an attribute declared on the interface. The identified attributes all MUST have a serializable type.
The inherit keyword MUST NOT be used unless the interface inherits from another that defines a serializer, and the closest such interface defines its serializer using this serialization pattern form or the following form (i.e. { attribute }).
The serialization behavior for this form of serialization pattern is as follows:
inherit keyword was used, then set map to be the result of the serialization behavior of the closest inherited interface that declares a serializer.A map with entries corresponding to all attributes from the interface that have a serializable type, and optionally attributes from an inherited interface:
serializer = { attribute };
serializer = { inherit, attribute };
The inherit keyword MUST NOT be used unless the interface inherits from another that defines a serializer, and the closest such interface defines its serializer using this serialization pattern form or the previous form.
The serialization behavior for this form of serialization pattern is as follows:
inherit keyword was used, then set map to be the result of the serialization behavior of the closest inherited interface that declares a serializer.A map with entries corresponding to the named properties:
serializer = { getter };
This form MUST NOT be used unless the interface or one it inherits from supports named properties and the return type of the named property getter is a serializable type.
The serialization behavior for this form of serialization pattern is as follows:
A list of value of zero or more attributes on the interface:
serializer = [ attribute-identifier, attribute-identifier, … ];
Each identifier MUST be the identifier of an attribute declared on the interface. The identified attributes all MUST have a serializable type.
The serialization behavior for this form of serialization pattern is as follows:
A list with entries corresponding to the indexed properties:
serializer = [ getter ];
This form MUST NOT be used unless the interface or one it inherits from supports indexed properties and the return type of the indexed property getter is a serializable type.
The serialization behavior for this form of serialization pattern is as follows:
A single attribute:
serializer = attribute-identifier;
The identifier MUST be the identifier of an attribute declared on the interface, and this attribute MUST have a serializable type.
The serialization behavior for this form of serialization pattern is as follows:
Note
Entries are added to maps in a particular order so that in the ECMAScript language binding it is defined what order properties are added to objects. This is because this order can influence the serialization that JSON.stringify can produce.
The list of serializable types and how they are converted to serialized values is as follows:
Serializers can also be specified using an operation with the serializer keyword:
serializer type identifier();
Serializers declared with operations MUST be declared to take zero arguments and return a serializable type.
The serialization behavior of the interface with a serializer declared with an operation is the result of converting the value returned from invoking the operation to a serialized value.
The following IDL fragment defines an interface Transaction that has a serializer defines in prose:
IDL
interface Transaction {
readonly attribute Account from;
readonly attribute Account to;
readonly attribute double amount;
readonly attribute DOMString description;
readonly attribute unsigned long number;
serializer;
};
interface Account {
DOMString name;
unsigned long number;
};The serializer could be defined as follows:
The serialization behavior of the Transaction interface is to run the following algorithm, where O is the object that implements Transaction:
- Let map be an empty map.
- Add an entry to map whose key is “from” and whose value is the serialized value of the
numberattribute on the Account object referenced by thefromattribute on O.- Add an entry to map whose key is “to” and whose value is the serialized value of the
numberattribute on the Account object referenced by thefromattribute on O.- For both of the attributes
amountanddescription, add an entry to map whose key is the identifier of the attribute and whose value is the serialized value of the value of the attribute on O.- Return map.
If it was acceptable for Account objects to be serializable on their own, then serialization patterns could be used to avoid having to define the serialization behavior in prose:
IDL
interface Transaction {
readonly attribute Account from;
readonly attribute Account to;
readonly attribute double amount;
readonly attribute DOMString description;
readonly attribute unsigned long number;
serializer = { from, to, amount, description };
};
interface Account {
DOMString name;
unsigned long number;
serializer = number;
};In the ECMAScript language binding, there would exist a toJSON method on Transaction objects:
ECMAScript
var txn = getTransaction();
txn.toJSON();
JSON.stringify(txn);An interface that defines an indexed property getter is said to support indexed properties.
If an interface supports indexed properties, then the interface definition MUST be accompanied by a description of what indices the object can be indexed with at any given time. These indices are called the supported property indices.
Indexed property getters MUST be declared to take a single unsigned long argument. Indexed property setters MUST be declared to take two arguments, where the first is an unsigned long.
getter type identifier(unsigned long identifier); setter type identifier(unsigned long identifier, type identifier); getter type (unsigned long identifier); setter type (unsigned long identifier, type identifier);
The following requirements apply to the definitions of indexed property getters and setters:
Note
Note that if an indexed property getter or setter is specified using an operation with an identifier, then indexing an object with an integer that is not a supported property index does not necessarily elicit the same behavior as invoking the operation with that index. The actual behavior in this case is language binding specific.
In the ECMAScript language binding, a regular property lookup is done. For example, take the following IDL:
IDL
interface A {
getter DOMString toWord(unsigned long index);
};Assume that an object implementing A has supported property indices in the range 0 ≤ index < 2. Also assume that toWord is defined to return its argument converted into an English word. The behavior when invoking the operation with an out of range index is different from indexing the object directly:
ECMAScript
var a = getA();
a.toWord(0);
a[0];
a.toWord(5);
a[5]; The following IDL fragment defines an interface OrderedMap which allows retrieving and setting values by name or by index number:
IDL
interface OrderedMap {
readonly attribute unsigned long size;
getter any getByIndex(unsigned long index);
setter void setByIndex(unsigned long index, any value);
getter any get(DOMString name);
setter void set(DOMString name, any value);
};Since all of the special operations are declared using operations with identifiers, the only additional prose that is necessary is that which describes what keys those sets have. Assuming that the get() operation is defined to return null if an attempt is made to look up a non-existing entry in the OrderedMap, then the following two sentences would suffice:
An object map implementing OrderedMap supports indexed properties with indices in the range 0 ≤ index <
map.size.Such objects also support a named property for every name that, if passed to
get(), would return a non-null value.
As described in section 4.8 , an ECMAScript implementation would create properties on a platform object implementing OrderedMap that correspond to entries in both the named and indexed property sets. These properties can then be used to interact with the object in the same way as invoking the object’s methods, as demonstrated below:
ECMAScript
var map = getOrderedMap();
var x, y;
x = map[0];
map[1] = false;
y = map.apple;
map.berry = 123;
delete map.cake;
An interface that defines a named property getter is said to support named properties.
If an interface supports named properties, then the interface definition MUST be accompanied by a description of the ordered set of names that can be used to index the object at any given time. These names are called the supported property names.
Named property getters and deleters MUST be declared to take a single DOMString argument. Named property setters MUST be declared to take two arguments, where the first is a DOMString.
getter type identifier(DOMString identifier); setter type identifier(DOMString identifier, type identifier); deleter type identifier(DOMString identifier); getter type (DOMString identifier); setter type (DOMString identifier, type identifier); deleter type (DOMString identifier);
The following requirements apply to the definitions of named property getters, setters and deleters:
Static attributes and static operations are ones that are not associated with a particular instance of the interface on which it is declared, and is instead associated with the interface itself. Static attributes and operations are declared by using the static keyword in their declarations.
It is language binding specific whether it is possible to invoke a static operation or get or set a static attribute through a reference to an instance of the interface.
Static attributes and operations MUST NOT be declared on callback interfaces.
The following IDL fragment defines an interface Circle that has a static operation declared on it:
IDL
interface Point { };
interface Circle {
attribute double cx;
attribute double cy;
attribute double radius;
static readonly attribute long triangulationCount;
static Point triangulate(Circle c1, Circle c2, Circle c3);
};In the ECMAScript language binding, the Function object for triangulate and the accessor property for triangulationCount will exist on the interface object for Circle:
ECMAScript
var circles = getCircles();
typeof Circle.triangulate;
typeof Circle.triangulationCount;
Circle.prototype.triangulate;
Circle.prototype.triangulationCount;
circles[0].triangulate;
circles[0].triangulationCount;
var triangulationPoint = Circle.triangulate(circles[0], circles[1], circles[2]);
window.alert(Circle.triangulationCount);If a regular operation or static operation defined on an interface has an identifier that is the same as the identifier of another operation on that interface of the same kind (regular or static), then the operation is said to be overloaded. When the identifier of an overloaded operation is used to invoke one of the operations on an object that implements the interface, the number and types of the arguments passed to the operation determine which of the overloaded operations is actually invoked. If an interface has multiple legacy callers defined on it, then those legacy callers are also said to be overloaded. In the ECMAScript language binding, constructors can be overloaded too. There are some restrictions on the arguments that overloaded operations, legacy callers and constructors can be specified to take, and in order to describe these restrictions, the notion of an effective overload set is used.
Operations and legacy callers MUST NOT be overloaded across interface and partial interface definitions.
Note
For example, the overloads for both f and g are disallowed:
IDL
interface A {
void f();
};
partial interface A {
void f(double x);
void g();
};
partial interface A {
void g(DOMString x);
};Note that the [Constructor] and [NamedConstructor] extended attributes are disallowed from appearing on partial interface definitions, so there is no need to also disallow overloading for constructors.
An effective overload set represents the allowable invocations for a particular operation, constructor (specified with [Constructor] or [NamedConstructor]), legacy caller or callback function. The algorithm to compute an effective overload set operates on one of the following six types of IDL constructs, and listed with them below are the inputs to the algorithm needed to compute the set.
An effective overload set is used, among other things, to determine whether there are ambiguities in the overloaded operations, constructors and callers specified on an interface.
The elements of an effective overload set are tuples of the form < callable, type list, optionality list>. If the effective overload set is for regular operations, static operations or legacy callers, then callable is an operation; if it is for constructors or named constructors, then callable is an extended attribute; and if it is for callback functions, then callable is the callback function itself. In all cases, type list is a list of IDL types, and optionality list is a list of three possible optionality values – “required”, “optional” or “variadic” – indicating whether the argument at a given index was declared as being optional or corresponds to a variadic argument. Each tuple represents an allowable invocation of the operation, constructor, legacy caller or callback function with an argument value list of the given types. Due to the use of optional arguments and variadic operations and constructors, there may be multiple entries in an effective overload set identifying the same operation or constructor.
The algorithm below describes how to compute an effective overload set. The following input variables are used, if they are required:
Whenever an argument of an extended attribute is mentioned, it is referring to an argument of the extended attribute’s named argument list.
Note
So void f(long x, long... y); is considered to be declared to take two arguments.
Note
This leaves off the final, variadic argument.
For the following interface:
IDL
interface A {
void f(DOMString a);
void f(Node a, DOMString b, double... c);
void f();
void f(Event a, DOMString b, optional DOMString c, double... d);
};assuming Node and Event are two other interfaces of which no object can implement both, the effective overload set for regular operations with identifier f and argument count 4 is:
{ <f1, (DOMString), (required)>,
<f2, (Node, DOMString), (required, required)>,
<f2, (Node, DOMString, double), (required, required, variadic)>,
<f2, (Node, DOMString, double, double), (required, required, variadic, variadic)>,
<f3, (), ()>,
<f4, (Event, DOMString), (required, required)>,
<f4, (Event, DOMString, DOMString), (required, required, optional)>,
<f4, (Event, DOMString, DOMString, double), (required, required, optional, variadic)> }
Two types are distinguishable if at most one of the two includes a nullable type or is a dictionary type, and at least one of the following three conditions is true:
The two types (taking their inner types if they are nullable types) appear in the following table and there is a “●” mark in the corresponding entry or there is a letter in the corresponding entry and the designated additional requirement below the table is satisfied:
boolean numeric types string types interface object callbackNote
Promise types do not appear in the above table, and as a consequence are not distinguishable with any other type.
If there is more than one entry in an effective overload set that has a given type list length, then for those entries there MUST be an index i such that for each pair of entries the types at index i are distinguishable . The lowest such index is termed the distinguishing argument index for the entries of the effective overload set with the given type list length.
Consider the effective overload set shown in the previous example. There are multiple entries in the set with type lists 2, 3 and 4. For each of these type list lengths, the distinguishing argument index is 0, since Node and Event are distinguishable.
The following use of overloading however is invalid:
IDL
interface B {
void f(DOMString x);
void f(double x);
};since DOMString and double are not distinguishable.
In addition, for each index j, where j is less than the distinguishing argument index for a given type list length, the types at index j in all of the entries’ type lists MUST be the same and the booleans in the corresponding list indicating argument optionality MUST be the same.
The following is invalid:
IDL
interface B {
void f(DOMString w);
void f(long w, double x, Node y, Node z);
void f(double w, double x, DOMString y, Node z);
};For argument count 4, the effective overload set is:
{ <f1, (DOMString), (required)>,
<f2, (long, double, Node, Node), (required, required, required, required)>,
<f3, (double, double, DOMString, Node), (required, required, required, required)> }
Looking at entries with type list length 4, the distinguishing argument index is 2, since Node and DOMString are distinguishable. However, since the arguments in these two overloads at index 0 are different, the overloading is invalid.
3.2.7 Iterable declarationsAn interface can be declared to be iterable by using an iterable declaration (matching Iterable) in the body of the interface.
iterable<value-type>; iterable<key-type, value-type>;
Objects implementing an interface that is declared to be iterable support being iterated over to obtain a sequence of values.
Note
In the ECMAScript language binding, an interface that is iterable will have “entries”, “forEach”, “keys”, “values” and @@iterator properties on its interface prototype object.
If a single type parameter is given, then the interface has a value iterator and provides values of the specified type. If two type parameters are given, then the interface has a pair iterator and provides value pairs, where the first value is a key and the second is the value associated with the key.
A value iterator MUST only be declared on an interface that supports indexed properties and has an integer-typed attribute named “length”. The value-type of the value iterator MUST be the same as the type returned by the indexed property getter. A value iterator is implicitly defined to iterate over the object’s indexed properties.
A pair iterator MUST NOT be declared on an interface that supports indexed properties. Prose accompanying an interface with a pair iterator MUST define what the list of value pairs to iterate over is.
Note
The ECMAScript forEach method that is generated for a value iterator invokes its callback like Array.prototype.forEach does, and the forEach method for a pair iterator invokes its callback like Map.prototype.forEach does.
Since value iterators are currently allowed only on interfaces that support indexed properties, it makes sense to use an Array-like forEach method. There may be a need for value iterators (a) on interfaces that do not support indexed properties, or (b) with a forEach method that instead invokes its callback like Set.protoype.forEach (where the key is the same as the value). If you’re creating an API that needs such a forEach method, please send a request to public-script-coord@w3.org.
Interfaces with iterable declarations MUST NOT have any interface members named “entries”, “forEach”, “keys” or “values”, or have any inherited or consequential interfaces that have interface members with these names.
Consider the following interface SessionManager, which allows access to a number of Session objects:
IDL
interface SessionManager {
Session getSessionForUser(DOMString username);
readonly attribute unsigned long sessionCount;
iterable<Session>;
};
interface Session {
readonly attribute DOMString username;
};The behavior of the iterator could be defined like so:
The values to iterate over are the open Session objects on the SessionManager sorted by username.
In the ECMAScript language binding, the interface prototype object for the SessionManager interface has a values method that is a function, which, when invoked, returns an iterator object that itself has a next method that returns the next value to be iterated over. It has values and entries methods that iterate over the indexes of the list of session objects and [index, session object] pairs, respectively. It also has a @@iterator method that allows a SessionManager to be used in a for..of loop:
ECMAScript
var sm = getSessionManager();
typeof SessionManager.prototype.values;
var it = sm.values();
String(it);
typeof it.next;
for (;;) {
let result = it.next();
if (result.done) {
break;
}
let session = result.value;
window.alert(session.username);
}
for (let session of sm) {
window.alert(session.username);
}An interface MUST NOT have more than one iterable declaration. The inherited and consequential interfaces of an interface with an iterable declaration MUST NOT also have an iterable declaration.
The following extended attributes are applicable to iterable declarations: [Exposed].
3.3 DictionariesA dictionary is a definition (matching Dictionary) used to define an associative array data type with a fixed, ordered set of key–value pairs, termed dictionary members, where keys are strings and values are of a particular type specified in the definition.
dictionary identifier {
dictionary-members…
};
Dictionaries are always passed by value. In language bindings where a dictionary is represented by an object of some kind, passing a dictionary to a platform object will not result in a reference to the dictionary being kept by that object. Similarly, any dictionary returned from a platform object will be a copy and modifications made to it will not be visible to the platform object.
A dictionary can be defined to inherit from another dictionary. If the identifier of the dictionary is followed by a colon and a identifier, then that identifier identifies the inherited dictionary. The identifier MUST identify a dictionary.
A dictionary MUST NOT be declared such that its inheritance hierarchy has a cycle. That is, a dictionary A cannot inherit from itself, nor can it inherit from another dictionary B that inherits from A, and so on.
dictionary Base {
dictionary-members…
};
dictionary Derived : Base {
dictionary-members…
};
The inherited dictionaries of a given dictionary D is the set of all dictionaries that D inherits from, directly or indirectly. If D does not inherit from another dictionary, then the set is empty. Otherwise, the set includes the dictionary E that D inherits from and all of E’s inherited dictionaries.
A dictionary value of type D can have key–value pairs corresponding to the dictionary members defined on D and on any of D’s inherited dictionaries. On a given dictionary value, the presence of each dictionary member is optional, unless that member is specified as required. When specified in the dictionary value, a dictionary member is said to be present, otherwise it is not present. Dictionary members can also optionally have a default value, which is the value to use for the dictionary member when passing a value to a platform object that does not have a specified value. Dictionary members with default values are always considered to be present.
Each dictionary member (matching DictionaryMember) is specified as a type (matching Type) followed by an identifier (given by an identifier token following the type). The identifier is the key name of the key–value pair. If the Type is an identifier followed by ?, then the identifier MUST identify an interface, enumeration, callback function or typedef. If the dictionary member type is an identifier not followed by ?, then the identifier MUST identify any one of those definitions or a dictionary.
dictionary identifier {
type identifier;
};
If the identifier is followed by a U+003D EQUALS SIGN ("=") and a value (matching DefaultValue), then that gives the dictionary member its default value.
dictionary identifier {
type identifier = value;
};
When a boolean literal token (true or false), the null token, an integer token, a float token, one of the three special floating point literal values (Infinity, -Infinity or NaN), a string token or the two token sequence [] used as the default value, it is interpreted in the same way as for an operation’s optional argument default value.
If the type of the dictionary member is an enumeration, then its default value if specified MUST be one of the enumeration’s values.
If the type of the dictionary member is preceded by the required keyword, the member is considered a required dictionary member and must be present on the dictionary. A required dictionary member MUST NOT have a default value.
dictionary identifier {
required type identifier;
};
The type of a dictionary member MUST NOT include the dictionary it appears on. A type includes a dictionary D if at least one of the following is true:
As with interfaces, the IDL for dictionaries can be split into multiple parts by using partial dictionary definitions (matching "partial" Dictionary). The identifier of a partial dictionary definition MUST be the same as the identifier of a dictionary definition. All of the members that appear on each of the partial dictionary definitions are considered to be members of the dictionary itself.
dictionary SomeDictionary {
dictionary-members…
};
partial dictionary SomeDictionary {
dictionary-members…
};
Note
As with partial interface definitions, partial dictionary definitions are intended for use as a specification editorial aide, allowing the definition of an interface to be separated over more than one section of the document, and sometimes multiple documents.
The order of the dictionary members on a given dictionary is such that inherited dictionary members are ordered before non-inherited members, and the dictionary members on the one dictionary definition (including any partial dictionary definitions) are ordered lexicographically by the Unicode codepoints that comprise their identifiers.
Note
For example, with the following definitions:
IDL
dictionary B : A {
long b;
long a;
};
dictionary A {
long c;
long g;
};
dictionary C : B {
long e;
long f;
};
partial dictionary A {
long h;
long d;
};the order of the dictionary members of a dictionary value of type C is c, d, g, h, a, b, e, f.
Dictionaries are required to have their members ordered because in some language bindings the behavior observed when passing a dictionary value to a platform object depends on the order the dictionary members are fetched. For example, consider the following additional interface:
IDL
interface Something {
void f(A a);
};and this ECMAScript code:
ECMAScript
var something = getSomething();
var x = 0;
var dict = { };
Object.defineProperty(dict, "d", { get: function() { return ++x; } });
Object.defineProperty(dict, "c", { get: function() { return ++x; } });
something.f(dict);The order that the dictionary members are fetched in determines what values they will be taken to have. Since the order for A is defined to be c then d, the value for c will be 1 and the value for d will be 2.
The identifier of a dictionary member MUST NOT be the same as that of another dictionary member defined on the dictionary or on that dictionary’s inherited dictionaries.
Dictionaries MUST NOT be used as the type of an attribute or constant.
The following extended attributes are applicable to dictionaries: [Constructor], [Exposed].
The following extended attributes are applicable to dictionary members: [Clamp], [EnforceRange].
One use of dictionary types is to allow a number of optional arguments to an operation without being constrained as to the order they are specified at the call site. For example, consider the following IDL fragment:
IDL
[Constructor]
interface Point {
attribute double x;
attribute double y;
};
dictionary PaintOptions {
DOMString? fillPattern = "black";
DOMString? strokePattern = null;
Point position;
};
interface GraphicsContext {
void drawRectangle(double width, double height, optional PaintOptions options);
};In an ECMAScript implementation of the IDL, an Object can be passed in for the optional PaintOptions dictionary:
ECMAScript
var ctx = getGraphicsContext();
ctx.drawRectangle(300, 200, { fillPattern: "red", position: new Point(10, 10) });Both fillPattern and strokePattern are given default values, so if they are omitted, the definition of drawRectangle can assume that they have the given default values and not include explicit wording to handle their non-presence.
3.4 ExceptionsAn exception is a type of object that represents an error and which can be thrown or treated as a first class value by implementations. Web IDL does not allow exceptions to be defined, but instead has a number of pre-defined exceptions that specifications can reference and throw in their definition of operations, attributes, and so on. Exceptions have an error name, a DOMString, which is the type of error the exception represents, and a message, which is an optional, user agent-defined value that provides human readable details of the error.
There are two kinds of exceptions available to be thrown from specifications. The first is a simple exception, which is identified by one of the following names:
These correspond to all of the ECMAScript error objects ( [ ECMA-262] , section 19.5) (apart from SyntaxError, which is deliberately omitted as it is for use only by the ECMAScript parser). The meaning of each simple exception matches its corresponding Error object in the ECMAScript specification.
The second kind of exception is a DOMException, which is an exception that encapsulates a name and an optional integer code, for compatibility with historically defined exceptions in the DOM.
For simple exceptions, the error name is the name of the exception. For a DOMException, the error name MUST be one of the names listed in the error names table below. The table also indicates the DOMException's integer code for that error name, if it has one.
There are two types that can be used to refer to exception objects: Error, which encompasses all exceptions, and DOMException which includes just DOMException objects. This allows for example an operation to be declared to have a DOMException return type or an attribute to be of type Error.
Exceptions can be created by providing its error name. Exceptions can also be thrown, by providing the same details required to create one.
The resulting behavior from creating and throwing an exception is language binding-specific.
Note
See section 4.13 for details on what creating and throwing an exception entails in the ECMAScript language binding.
3.4.1 Error namesThe error names table below lists all the allowed error names for DOMExceptions, a description, and legacy code values.
Note
If an error name is not listed here, please file a bug as indicated at the top of this specification and it will be addressed shortly. Thanks!
Name Description Legacy code name and value "IndexSizeError" The index is not in the allowed range. INDEX_SIZE_ERR (1) "HierarchyRequestError" The operation would yield an incorrect node tree. HIERARCHY_REQUEST_ERR (3) "WrongDocumentError" The object is in the wrong document. WRONG_DOCUMENT_ERR (4) "InvalidCharacterError" The string contains invalid characters. INVALID_CHARACTER_ERR (5) "NoModificationAllowedError" The object can not be modified. NO_MODIFICATION_ALLOWED_ERR (7) "NotFoundError" The object can not be found here. NOT_FOUND_ERR (8) "NotSupportedError" The operation is not supported. NOT_SUPPORTED_ERR (9) "InUseAttributeError" The attribute is in use. INUSE_ATTRIBUTE_ERR (10) "InvalidStateError" The object is in an invalid state. INVALID_STATE_ERR (11) "SyntaxError" The string did not match the expected pattern. SYNTAX_ERR (12) "InvalidModificationError" The object can not be modified in this way. INVALID_MODIFICATION_ERR (13) "NamespaceError" The operation is not allowed by Namespaces in XML. [XMLNS] NAMESPACE_ERR (14) "InvalidAccessError" The object does not support the operation or argument. INVALID_ACCESS_ERR (15) "SecurityError" The operation is insecure. SECURITY_ERR (18) "NetworkError" A network error occurred. NETWORK_ERR (19) "AbortError" The operation was aborted. ABORT_ERR (20) "URLMismatchError" The given URL does not match another URL. URL_MISMATCH_ERR (21) "QuotaExceededError" The quota has been exceeded. QUOTA_EXCEEDED_ERR (22) "TimeoutError" The operation timed out. TIMEOUT_ERR (23) "InvalidNodeTypeError" The supplied node is incorrect or has an incorrect ancestor for this operation. INVALID_NODE_TYPE_ERR (24) "DataCloneError" The object can not be cloned. DATA_CLONE_ERR (25) "EncodingError" The encoding operation (either encoded or decoding) failed. — "NotReadableError" The I/O read operation failed. — "UnknownError" The operation failed for an unknown transient reason (e.g. out of memory). — "ConstraintError" A mutation operation in a transaction failed because a constraint was not satisfied. — "DataError" Provided data is inadequate. — "TransactionInactiveError" A request was placed against a transaction which is currently not active, or which is finished. — "ReadOnlyError" The mutating operation was attempted in a "readonly" transaction. — "VersionError" An attempt was made to open a database using a lower version than the existing version. — "OperationError" The operation failed for an operation-specific reason. — 3.5 Enumerations
An enumeration is a definition (matching Enum) used to declare a type whose valid values are a set of predefined strings. Enumerations can be used to restrict the possible DOMString values that can be assigned to an attribute or passed to an operation.
enum identifier { enumeration-values… };
The enumeration values are specified as a comma-separated list of string literals. The list of enumeration values MUST NOT include duplicates.
Warning
It is strongly suggested that enumeration values be all lowercase, and that multiple words be separated using dashes or not be separated at all, unless there is a specific reason to use another value naming scheme. For example, an enumeration value that indicates an object should be created could be named "createobject" or 'create-object". Consider related uses of enumeration values when deciding whether to dash-separate or not separate enumeration value words so that similar APIs are consistent.
The behavior when a string value that is not one a valid enumeration value is used when assigning to an attribute, or passed as an operation argument, whose type is the enumeration, is language binding specific.
Note
In the ECMAScript binding, assignment of an invalid string value to an attribute is ignored, while passing such a value as an operation argument results in an exception being thrown.
No extended attributes defined in this specification are applicable to enumerations.
The following IDL fragment defines an enumeration that is used as the type of an attribute and an operation argument:
IDL
enum MealType { "rice", "noodles", "other" };
interface Meal {
attribute MealType type;
attribute double size;
void initialize(MealType type, double size);
};An ECMAScript implementation would restrict the strings that can be assigned to the type property or passed to the initializeMeal function to those identified in the enumeration.
ECMAScript
var meal = getMeal();
meal.initialize("rice", 200);
try {
meal.initialize("sandwich", 100);
} catch (e) {
}
meal.type = "noodles";
meal.type = "dumplings";
meal.type == "noodles"; A callback function is a definition (matching "callback" CallbackRest) used to declare a function type.
callback identifier = return-type (arguments…);
The identifier on the left of the equals sign gives the name of the callback function and the return type and argument list (matching ReturnType and ArgumentList) on the right side of the equals sign gives the signature of the callback function type.
Callback functions MUST NOT be used as the type of a constant.
The following extended attribute is applicable to callback functions: [TreatNonObjectAsNull].
The following IDL fragment defines a callback function used for an API that invokes a user-defined function when an operation is complete.
IDL
callback AsyncOperationCallback = void (DOMString status);
interface AsyncOperations {
void performOperation(AsyncOperationCallback whenFinished);
};In the ECMAScript language binding, a Function object is passed as the operation argument.
ECMAScript
var ops = getAsyncOperations();
ops.performOperation(function(status) {
window.alert("Operation finished, status is " + status + ".");
});A typedef is a definition (matching Typedef) used to declare a new name for a type. This new name is not exposed by language bindings; it is purely used as a shorthand for referencing the type in the IDL.
typedef type identifier;
The type being given a new name is specified after the typedef keyword (matching Type), and the identifier token following the type gives the name.
The Type MUST NOT identify the same or another typedef.
No extended attributes defined in this specification are applicable to typedefs.
The following IDL fragment demonstrates the use of typedefs to allow the use of a short identifier instead of a long sequence type.
IDL
interface Point {
attribute double x;
attribute double y;
};
typedef sequence<Point> Points;
interface Widget {
boolean pointWithinBounds(Point p);
boolean allPointsWithinBounds(Points ps);
};An implements statement is a definition (matching ImplementsStatement) used to declare that all objects implementing an interface A (identified by the first identifier) MUST additionally implement interface B (identified by the second identifier), including all other interfaces that B inherits from.
identifier-A implements identifier-B;
Transitively, if objects implementing B are declared with an implements statement to additionally implement interface C, then all objects implementing A do additionally implement interface C.
The two identifiers MUST identify two different interfaces.
The interface identified on the left-hand side of an implements statement MUST NOT inherit from the interface identifier on the right-hand side, and vice versa. Both identified interfaces also MUST NOT be callback interfaces.
If each implements statement is considered to be an edge in a directed graph, from a node representing the interface on the left-hand side of the statement to a node representing the interface on the right-hand side, then this graph MUST NOT have any cycles.
Interfaces that a given object implements are partitioned into those that are considered and those that are not. An interface A is considered to be a supplemental interface of an object O if:
B implements A; orNote
Specification authors are discouraged from writing implements statements where the interface on the left-hand side is a supplemental interface. For example, if author 1 writes:
IDL
interface Window { ... };
interface SomeFunctionality { ... };
Window implements SomeFunctionality;and author 2 later writes:
IDL
interface Gizmo { ... };
interface MoreFunctionality { ... };
SomeFunctionality implements MoreFunctionality;
Gizmo implements SomeFunctionality;then it might be the case that author 2 is unaware of exactly which interfaces already are used on the left-hand side of an implements SomeFunctionality statement, and so has required more objects implement MoreFunctionality than he or she expected.
Better in this case would be for author 2 to write:
IDL
interface Gizmo { ... };
interface MoreFunctionality { ... };
Gizmo implements SomeFunctionality;
Gizmo implements MoreFunctionality;The consequential interfaces of an interface A are:
A implements B;C implements D, where C is a consequential interface of A.For a given interface, there MUST NOT be any member defined on any of its consequential interfaces whose identifier is the same as any other member defined on any of those consequential interfaces or on the original interface itself.
Note
For example, that precludes the following:
IDL
interface A { attribute long x; };
interface B { attribute long x; };
A implements B;
interface C { attribute long y; };
interface D { attribute long y; };
interface E : D { };
C implements E;
interface F { };
interface H { attribute long z; };
interface I { attribute long z; };
F implements H;
F implements I; No extended attributes defined in this specification are applicable to implements statements.
The following IDL fragment defines two interfaces, stating that one interface is always implemented on objects implementing the other.
IDL
interface Entry {
readonly attribute unsigned short entryType;
};
interface Observable {
void addEventListener(DOMString type,
EventListener listener,
boolean useCapture);
};
Entry implements Observable;An ECMAScript implementation would thus have an “addEventListener” property in the prototype chain of every Entry:
ECMAScript
var e = getEntry();
typeof e.addEventListener; Note that it is not the case that all Observable objects implement Entry.
3.9 Objects implementing interfacesIn a given implementation of a set of IDL fragments, an object can be described as being a platform object, a user object, or neither. There are two kinds of object that are considered to be platform objects:
In a browser, for example, the browser-implemented DOM objects (implementing interfaces such as Node and Document) that provide access to a web page’s contents to ECMAScript running in the page would be platform objects. These objects might be exotic objects, implemented in a language like C++, or they might be native ECMAScript objects. Regardless, an implementation of a given set of IDL fragments needs to be able to recognize all platform objects that are created by the implementation. This might be done by having some internal state that records whether a given object is indeed a platform object for that implementation, or perhaps by observing that the object is implemented by a given internal C++ class. How exactly platform objects are recognised by a given implementation of a set of IDL fragments is implementation specific.
All other objects in the system would not be treated as platform objects. For example, assume that a web page opened in a browser loads an ECMAScript library that implements DOM Core. This library would be considered to be a different implementation from the browser provided implementation. The objects created by the ECMAScript library that implement the Node interface will not be treated as platform objects that implement Node by the browser implementation.
User objects are those that authors would create, implementing callback interfaces that the Web APIs use to be able to invoke author-defined operations or to send and receive values to the author’s program through manipulating the object’s attributes. In a web page, an ECMAScript object that implements the EventListener interface, which is used to register a callback that the DOM Events implementation invokes, would be considered to be a user object.
Note that user objects can only implement callback interfaces and platform objects can only implement non-callback interfaces.
3.10 TypesThis section lists the types supported by Web IDL, the set of values corresponding to each type, and how constants of that type are represented.
The following types are known as integer types: byte, octet, short, unsigned short, long, unsigned long, long long and unsigned long long.
The following types are known as numeric types: the integer types, float, unresticted float, double and unrestricted double.
The primitive types are boolean and the numeric types.
The string types are DOMString, all enumeration types, ByteString and USVString.
The exception types are Error and DOMException.
The typed array types are Int8Array, Int16Array, Int32Array, Uint8Array, Uint16Array, Uint32Array, Uint8ClampedArray, Float32Array and Float64Array.
The buffer source types are ArrayBuffer, DataView, and the typed array types.
The object type, all interface types and the exception types are known as object types.
Every type has a type name, which is a string, not necessarily unique, that identifies the type. Each sub-section below defines what the type name is for each type.
When conversions are made from language binding specific types to IDL types in order to invoke an operation or assign a value to an attribute, all conversions necessary will be performed before the specified functionality of the operation or attribute assignment is carried out. If the conversion cannot be performed, then the operation will not run or the attribute will not be updated. In some language bindings, type conversions could result in an exception being thrown. In such cases, these exceptions will be propagated to the code that made the attempt to invoke the operation or assign to the attribute.
3.10.1 anyThe any type is the union of all other possible non- union types. Its type name is “Any”.
The any type is like a discriminated union type, in that each of its values has a specific non-any type associated with it. For example, one value of the any type is the unsigned long 150, while another is the long 150. These are distinct values.
The particular type of an any value is known as its specific type. (Values of union types also have specific types.)
3.10.2 booleanThe boolean type has two values: true and false.
boolean constant values in IDL are represented with the true and false tokens.
The type name of the boolean type is “Boolean”.
3.10.3 byteThe byte type is a signed integer type that has values in the range [−128, 127].
byte constant values in IDL are represented with integer tokens.
The type name of the byte type is “Byte”.
3.10.4 octetThe octet type is an unsigned integer type that has values in the range [0, 255].
octet constant values in IDL are represented with integer tokens.
The type name of the octet type is “Octet”.
3.10.5 shortThe short type is a signed integer type that has values in the range [−32768, 32767].
short constant values in IDL are represented with integer tokens.
The type name of the short type is “Short”.
3.10.6 unsigned shortThe unsigned short type is an unsigned integer type that has values in the range [0, 65535].
unsigned short constant values in IDL are represented with integer tokens.
The type name of the unsigned short type is “UnsignedShort”.
3.10.7 longThe long type is a signed integer type that has values in the range [−2147483648, 2147483647].
long constant values in IDL are represented with integer tokens.
The type name of the long type is “Long”.
3.10.8 unsigned longThe unsigned long type is an unsigned integer type that has values in the range [0, 4294967295].
unsigned long constant values in IDL are represented with integer tokens.
The type name of the unsigned long type is “UnsignedLong”.
3.10.9 long longThe long long type is a signed integer type that has values in the range [−9223372036854775808, 9223372036854775807].
long long constant values in IDL are represented with integer tokens.
The type name of the long long type is “LongLong”.
3.10.10 unsigned long longThe unsigned long long type is an unsigned integer type that has values in the range [0, 18446744073709551615].
unsigned long long constant values in IDL are represented with integer tokens.
The type name of the unsigned long long type is “UnsignedLongLong”.
3.10.11 floatThe float type is a floating point numeric type that corresponds to the set of finite single-precision 32 bit IEEE 754 floating point numbers. [IEEE-754]
float constant values in IDL are represented with float tokens.
The type name of the float type is “Float”.
Warning
Unless there are specific reasons to use a 32 bit floating point type, specifications SHOULD use double rather than float, since the set of values that a double can represent more closely matches an ECMAScript Number.
3.10.12 unrestricted floatThe unrestricted float type is a floating point numeric type that corresponds to the set of all possible single-precision 32 bit IEEE 754 floating point numbers, finite and non-finite. [IEEE-754]
unrestricted float constant values in IDL are represented with float tokens.
The type name of the unrestricted float type is “UnrestrictedFloat”.
3.10.13 doubleThe double type is a floating point numeric type that corresponds to the set of finite double-precision 64 bit IEEE 754 floating point numbers. [IEEE-754]
double constant values in IDL are represented with float tokens.
The type name of the double type is “Double”.
3.10.14 unrestricted doubleThe unrestricted double type is a floating point numeric type that corresponds to the set of all possible double-precision 64 bit IEEE 754 floating point numbers, finite and non-finite. [IEEE-754]
unrestricted double constant values in IDL are represented with float tokens.
The type name of the unrestricted double type is “UnrestrictedDouble”.
3.10.15 DOMStringThe DOMString type corresponds to the set of all possible sequences of code units. Such sequences are commonly interpreted as UTF-16 encoded strings [RFC2781] although this is not required. While DOMString is defined to be an OMG IDL boxed sequence<unsigned short> valuetype in DOM Level 3 Core ([ DOM3CORE], section 1.2.1), this document defines DOMString to be an intrinsic type so as to avoid special casing that sequence type in various situations where a string is required.
Note
Note also that null is not a value of type DOMString. To allow null, a nullable DOMString, written as DOMString? in IDL, needs to be used.
Nothing in this specification requires a DOMString value to be a valid UTF-16 string. For example, a DOMString value might include unmatched surrogate pair characters. However, authors of specifications using Web IDL might want to obtain a sequence of Unicode scalar values given a particular sequence of code units. The following algorithm defines a way to convert a DOMString to a sequence of Unicode scalar values:
There is no way to represent a constant DOMString value in IDL, although DOMString dictionary member and operation optional argument default values can be specified using a string literal.
The type name of the DOMString type is “String”.
3.10.16 ByteStringThe ByteString type corresponds to the set of all possible sequences of bytes. Such sequences might be interpreted as UTF-8 encoded strings [RFC3629] or strings in some other 8-bit-per-code-unit encoding, although this is not required.
There is no way to represent a constant ByteString value in IDL.
The type name of the ByteString type is “ByteString”.
Warning
Specifications SHOULD only use ByteString for interfacing with protocols that use bytes and strings interchangably, such as HTTP. In general, strings SHOULD be represented with DOMString values, even if it is expected that values of the string will always be in ASCII or some 8 bit character encoding. Sequences or Typed Arrays with octet or byte elements SHOULD be used for holding 8 bit data rather than ByteString. [ TYPEDARRAYS]
3.10.17 USVStringThe USVString type corresponds to the set of all possible sequences of Unicode scalar values, which are all of the Unicode code points apart from the surrogate code points.
There is no way to represent a constant USVString value in IDL, although USVString dictionary member and operation optional argument default values can be specified using a string literal.
The type name of the USVString type is “USVString”.
Warning
Specifications SHOULD only use USVString for APIs that perform text processing and need a string of Unicode scalar values to operate on. Most APIs that use strings should instead be using DOMString, which does not make any interpretations of the code units in the string. When in doubt, use DOMString.
3.10.18 objectThe object type corresponds to the set of all possible non-null object references.
There is no way to represent a constant object value in IDL.
To denote a type that includes all possible object references plus the null value, use the nullable type object?.
The type name of the object type is “Object”.
3.10.19 Interface typesAn identifier that identifies an interface is used to refer to a type that corresponds to the set of all possible non-null references to objects that implement that interface.
For non-callback interfaces, an IDL value of the interface type is represented just by an object reference. For callback interfaces, an IDL value of the interface type is represented by a tuple of an object reference and a callback context. The callback context is a language binding specific value, and is used to store information about the execution context at the time the language binding specific object reference is converted to an IDL value.
There is no way to represent a constant object reference value for a particular interface type in IDL.
To denote a type that includes all possible references to objects implementing the given interface plus the null value, use a nullable type.
The type name of an interface type is the identifier of the interface.
3.10.20 Dictionary typesAn identifier that identifies a dictionary is used to refer to a type that corresponds to the set of all dictionaries that adhere to the dictionary definition.
There is no way to represent a constant dictionary value in IDL.
The type name of a dictionary type is the identifier of the dictionary.
3.10.21 Enumeration typesAn identifier that identifies an enumeration is used to refer to a type whose values are the set of strings (sequences of code units, as with DOMString) that are the enumeration’s values.
Like DOMString, there is no way to represent a constant enumeration value in IDL, although enumeration-typed dictionary member default values can be specified using a string literal.
The type name of an enumeration type is the identifier of the enumeration.
3.10.22 Callback function typesAn identifier that identifies a callback function is used to refer to a type whose values are references to objects that are functions with the given signature.
An IDL value of the callback function type is represented by a tuple of an object reference and a callback context.
There is no way to represent a constant callback function value in IDL.
The type name of a callback function type is the identifier of the callback function.
3.10.23 Nullable types — T?A nullable type is an IDL type constructed from an existing type (called the inner type), which just allows the additional value null to be a member of its set of values. Nullable types are represented in IDL by placing a U+003F QUESTION MARK ("?") character after an existing type. The inner type MUST NOT be any, another nullable type, or a union type that itself has includes a nullable type or has a dictionary type as one of its flattened member types.
Note
Although dictionary types can in general be nullable, they cannot when used as the type of an operation argument or a dictionary member.
Nullable type constant values in IDL are represented in the same way that constant values of their inner type would be represented, or with the null token.
The type name of a nullable type is the concatenation of the type name of the inner type T and the string “OrNull”.
For example, a type that allows the values true, false and null is written as boolean?:
IDL
interface MyConstants {
const boolean? ARE_WE_THERE_YET = false;
};The following interface has two attributes: one whose value can be a DOMString or the null value, and another whose value can be a reference to a Node object or the null value:
IDL
interface Node {
readonly attribute DOMString? namespaceURI;
readonly attribute Node? parentNode;
};The sequence<T> type is a parameterized type whose values are (possibly zero-length) sequences of values of type T.
Sequences are always passed by value. In language bindings where a sequence is represented by an object of some kind, passing a sequence to a platform object will not result in a reference to the sequence being kept by that object. Similarly, any sequence returned from a platform object will be a copy and modifications made to it will not be visible to the platform object.
There is no way to represent a constant sequence value in IDL.
Sequences MUST NOT be used as the type of an attribute or constant.
Note
This restriction exists so that it is clear to specification writers and API users that sequences are copied rather than having references to them passed around. Instead of a writable attribute of a sequence type, it is suggested that a pair of operations to get and set the sequence is used.
The type name of a sequence type is the concatenation of the type name for T and the string “Sequence”.
3.10.25 Promise types — Promise<T>A promise type is a parameterized type whose values are references to objects that “is used as a place holder for the eventual results of a deferred (and possibly asynchronous) computation result of an asynchronous operation” [ECMA-262]. See section 25.4 of the ECMAScript specification for details on the semantics of promise objects.
There is no way to represent a promise value in IDL.
The type name of a promise type is the concatenation of the type name for T and the string “Promise”.
3.10.26 Union typesA union type is a type whose set of values is the union of those in two or more other types. Union types (matching UnionType) are written as a series of types separated by the or keyword with a set of surrounding parentheses. The types which comprise the union type are known as the union’s member types.
Note
For example, you might write (Node or DOMString) or (double or sequence<double>). When applying a ? suffix to a union type as a whole, it is placed after the closing parenthesis, as in (Node or DOMString)?.
Note that the member types of a union type do not descend into nested union types. So for (double or (sequence<long> or Event) or (Node or DOMString)?) the member types are double, (sequence<long> or Event) and (Node or DOMString)?.
Like the any type, values of union types have a specific type, which is the particular member type that matches the value.
The flattened member types of a union type is a set of types determined as follows:
Note
For example, the flattened member types of the union type (Node or (sequence<long> or Event) or (XMLHttpRequest or DOMString)? or sequence<(sequence<double> or NodeList)>) are the six types Node, sequence<long>, Event, XMLHttpRequest, DOMString and sequence<(sequence<double> or NodeList)>.
The number of nullable member types of a union type is an integer determined as follows:
The any type MUST NOT be used as a union member type.
The number of nullable member types of a union type MUST be 0 or 1, and if it is 1 then the union type MUST also not have a dictionary type in its flattened member types.
A type includes a nullable type if:
Each pair of flattened member types in a union type, T and U, MUST be distinguishable.
Union type constant values in IDL are represented in the same way that constant values of their member types would be represented.
The type name of a union type is formed by taking the type names of each member type, in order, and joining them with the string “Or”.
3.10.27 ErrorThe Error type corresponds to the set of all possible non-null references to exception objects, including simple exceptions and DOMExceptions.
There is no way to represent a constant Error value in IDL.
The type name of the Error type is “Error”.
3.10.28 DOMExceptionThe DOMException type corresponds to the set of all possible non-null references to objects representing DOMExceptions.
There is no way to represent a constant DOMException value in IDL.
The type name of the DOMException type is “DOMException”.
3.10.29 Buffer source typesThere are a number of types that correspond to sets of all possible non-null references to objects that represent a buffer of data or a view on to a buffer of data. The table below lists these types and the kind of buffer or view they represent.
Type Kind of buffer ArrayBuffer An object that holds a pointer (which may be null) to a buffer of a fixed number of bytes DataView A view on to an ArrayBuffer that allows typed access to integers and floating point values stored at arbitrary offsets into the buffer Int8Array,Note
These types all correspond to classes defined in ECMAScript.
To detach an ArrayBuffer is to set its buffer pointer to null.
There is no way to represent a constant value of any of these types in IDL.
The type name of all of these types is the name of the type itself.
At the specification prose level, IDL buffer source types are simply references to objects. To inspect or manipulate the bytes inside the buffer, specification prose MUST first either get a reference to the bytes held by the buffer source or get a copy of the bytes held by the buffer source. With a reference to the buffer source’s bytes, specification prose can get or set individual byte values using that reference.
Warning
Extreme care must be taken when writing specification text that gets a reference to the bytes held by a buffer source, as the underyling data can easily be changed by the script author or other APIs at unpredictable times. If you are using a buffer source type as an operation argument to obtain a chunk of binary data that will not be modified, it is strongly recommended to get a copy of the buffer source’s bytes at the beginning of the prose defining the operation.
Requiring prose to explicitly get a reference to or copy of the bytes is intended to help specification reviewers look for problematic uses of these buffer source types.
Note
When designing APIs that take a buffer, it is recommended to use the BufferSource typedef rather than ArrayBuffer or any of the view types.
When designing APIs that create and return a buffer, it is recommended to use the ArrayBuffer type rather than Uint8Array.
Attempting to get a reference to or get a copy of the bytes held by a buffer source when the ArrayBuffer has been detached will fail in a language binding-specific manner.
Note
See section 4.2.30 below for how interacting with buffer source types works in the ECMAScript language binding.
3.11 Extended attributesAn extended attribute is an annotation that can appear on definitions , interface members, dictionary members, and operation arguments, and is used to control how language bindings will handle those constructs. Extended attributes are specified with an ExtendedAttributeList, which is a square bracket enclosed, comma separated list of ExtendedAttributes.
The ExtendedAttribute grammar symbol matches nearly any sequence of tokens, however the extended attributes defined in this document only accept a more restricted syntax. Any extended attribute encountered in an IDL fragment is matched against the following six grammar symbols to determine which form (or forms) it is in:
This specification defines a number of extended attributes that are applicable to the ECMAScript language binding, which are described in section 4.3 . Each extended attribute definition will state which of the above six forms are allowed.
4. ECMAScript bindingThis section describes how definitions written with the IDL defined in section 3. correspond to particular constructs in ECMAScript, as defined by the ECMAScript Language Specification 6th Edition [ ECMA-262].
Objects defined in this section have internal properties as described in ECMA-262 sections 9.1 and 9.3.1 unless otherwise specified, in which case one or more of the following are redefined in accordance with the rules for exotic objects: [[Call]], [[Set]], [[DefineOwnProperty]], [[GetOwnProperty]], [[Delete]] and [[HasInstance]].
Other specifications MAY override the definitions of any internal method of a platform object that is an instance of an interface.
Warning
As overriding internal ECMAScript object methods is a low level operation and can result in objects that behave differently from ordinary objects, this facility SHOULD NOT be used unless necessary for security or compatibility. The expectation is that this will be used for Location objects and possibly WindowProxy objects.
Unless otherwise specified, the [[Extensible]] internal property of objects defined in this section has the value true.
Unless otherwise specified, the [[Prototype]] internal property of objects defined in this section is the Object prototype object.
Some objects described in this section are defined to have a class string, which is the string to include in the string returned from Object.prototype.toString. If an object has a class string, then the object MUST, at the time it is created, have a property whose name is the @@toStringTag symbol and whose value is the specified string.
If an object is defined to be a function object, then it has characteristics as follows:
Algorithms in this section use the conventions described in ECMA-262 section 5.2, such as the use of steps and substeps, the use of mathematical operations, and so on. The ToBoolean, ToNumber, ToUint16, ToInt32, ToUint32, ToString, ToObject, IsAccessorDescriptor and IsDataDescriptor abstract operations and the Type(x) notation referenced in this section are defined in ECMA-262 sections 6 and 7.
When an algorithm says to “throw a SomethingError” then this means to construct a new ECMAScript SomethingError object and to throw it, just as the algorithms in ECMA-262 do.
Note that algorithm steps can call in to other algorithms and abstract operations and not explicitly handle exceptions that are thrown from them. When an exception is thrown by an algorithm or abstract operation and it is not explicitly handled by the caller, then it is taken to end the algorithm and propagate out to its caller, and so on.
Consider the following algorithm:
Since ToString can throw an exception (for example if passed the object ({ toString: function() { throw 1 } })), and the exception is not handled in the above algorithm, if one is thrown then it causes this algorithm to end and for the exception to propagate out to its caller, if there is one.
In an ECMAScript implementation of a given set of IDL fragments, there will exist a number of ECMAScript objects that correspond to definitions in those IDL fragments. These objects are termed the initial objects, and comprise the following:
Each ECMAScript global environment ([ECMA-262], section 8.2) MUST have its own unique set of each of the initial objects, created before control enters any ECMAScript execution context associated with the environment, but after the global object for that environment is created. The [[Prototype]]s of all initial objects in a given global environment MUST come from that same global environment.
In an HTML user agent, multiple global environments can exist when multiple frames or windows are created. Each frame or window will have its own set of initial objects, which the following HTML document demonstrates:
HTML
<!DOCTYPE html>
<title>Different global environments</title>
<iframe id=a></iframe>
<script>
var iframe = document.getElementById("a");
var w = iframe.contentWindow;
Object == w.Object;
Node == w.Node;
iframe instanceof w.Node;
iframe instanceof w.Object;
iframe.appendChild instanceof Function;
iframe.appendChild instanceof w.Function;
</script>Unless otherwise specified, each ECMAScript global environment exposes all interfaces that the implementation supports. If a given ECMAScript global environment does not expose an interface, then the requirements given in section 4.6 are not followed for that interface.
Note
This allows, for example, ECMAScript global environments for Web Workers to expose different sets of supported interfaces from those exposed in environments for Web pages.
4.2 ECMAScript type mappingThis section describes how types in the IDL map to types in ECMAScript.
Each sub-section below describes how values of a given IDL type are represented in ECMAScript. For each IDL type, it is described how ECMAScript values are converted to an IDL value when passed to a platform object expecting that type, and how IDL values of that type are converted to ECMAScript values when returned from a platform object.
4.2.1 anySince the IDL any type is the union of all other IDL types, it can correspond to any ECMAScript value type.
How to convert an ECMAScript value to an IDL any value depends on the type of the ECMAScript value:
An IDL any value is converted to an ECMAScript value as follows. If the value is an object reference to a special object that represents an ECMAScript undefined value, then it is converted to the ECMAScript undefined value. Otherwise, the rules for converting the specific type of the IDL any value as described in the remainder of this section are performed.
4.2.2 voidThe only place that the void type may appear in IDL is as the return type of an operation. Functions on platform objects that implement an operation whose IDL specifies a void return type MUST return the undefined value.
ECMAScript functions that implement an operation whose IDL specifies a void return type MAY return any value, which will be discarded.
4.2.3 booleanAn ECMAScript value V is converted to an IDL boolean value by running the following algorithm:
The IDL boolean value true is converted to the ECMAScript true value and the IDL boolean value false is converted to the ECMAScript false value.
4.2.4 byteAn ECMAScript value V is converted to an IDL byte value by running the following algorithm:
The result of converting an IDL byte value to an ECMAScript value is a Number that represents the same numeric value as the IDL byte value. The Number value will be an integer in the range [−128, 127].
4.2.5 octetAn ECMAScript value V is converted to an IDL octet value by running the following algorithm:
The result of converting an IDL octet value to an ECMAScript value is a Number that represents the same numeric value as the IDL octet value. The Number value will be an integer in the range [0, 255].
4.2.6 shortAn ECMAScript value V is converted to an IDL short value by running the following algorithm:
The result of converting an IDL short value to an ECMAScript value is a Number that represents the same numeric value as the IDL short value. The Number value will be an integer in the range [−32768, 32767].
4.2.7 unsigned shortAn ECMAScript value V is converted to an IDL unsigned short value by running the following algorithm:
The result of converting an IDL unsigned short value to an ECMAScript value is a Number that represents the same numeric value as the IDL unsigned short value. The Number value will be an integer in the range [0, 65535].
4.2.8 longAn ECMAScript value V is converted to an IDL long value by running the following algorithm:
The result of converting an IDL long value to an ECMAScript value is a Number that represents the same numeric value as the IDL long value. The Number value will be an integer in the range [−2147483648, 2147483647].
4.2.9 unsigned longAn ECMAScript value V is converted to an IDL unsigned long value by running the following algorithm:
The result of converting an IDL unsigned long value to an ECMAScript value is a Number that represents the same numeric value as the IDL unsigned long value. The Number value will be an integer in the range [0, 4294967295].
4.2.10 long longAn ECMAScript value V is converted to an IDL long long value by running the following algorithm:
The result of converting an IDL long long value to an ECMAScript value is a Number value that represents the closest numeric value to the long long, choosing the numeric value with an even significand if there are two equally close values ( [ ECMA-262] , section 6.1.6). If the long long is in the range [−2 53 + 1, 253 − 1], then the Number will be able to represent exactly the same value as the long long.
4.2.11 unsigned long longAn ECMAScript value V is converted to an IDL unsigned long long value by running the following algorithm:
The result of converting an IDL unsigned long long value to an ECMAScript value is a Number value that represents the closest numeric value to the unsigned long long, choosing the numeric value with an even significand if there are two equally close values ( [ ECMA-262] , section 6.1.6). If the unsigned long long is less than or equal to 253 − 1, then the Number will be able to represent exactly the same value as the unsigned long long.
4.2.12 floatAn ECMAScript value V is converted to an IDL float value by running the following algorithm:
The result of converting an IDL float value to an ECMAScript value is the Number value that represents the same numeric value as the IDL float value.
4.2.13 unrestricted floatAn ECMAScript value V is converted to an IDL unrestricted float value by running the following algorithm:
Note
Since there is only a single ECMAScript NaN value, it must be canonicalized to a particular single precision IEEE 754 NaN value. The NaN value mentioned above is chosen simply because it is the quiet NaN with the lowest value when its bit pattern is interpreted as an unsigned 32 bit integer.
The result of converting an IDL unrestricted float value to an ECMAScript value is a Number:
An ECMAScript value V is converted to an IDL double value by running the following algorithm:
The result of converting an IDL double value to an ECMAScript value is the Number value that represents the same numeric value as the IDL double value.
4.2.15 unrestricted doubleAn ECMAScript value V is converted to an IDL unrestricted double value by running the following algorithm:
Note
Since there is only a single ECMAScript NaN value, it must be canonicalized to a particular double precision IEEE 754 NaN value. The NaN value mentioned above is chosen simply because it is the quiet NaN with the lowest value when its bit pattern is interpreted as an unsigned 64 bit integer.
The result of converting an IDL unrestricted double value to an ECMAScript value is a Number:
An ECMAScript value V is converted to an IDL DOMString value by running the following algorithm:
The result of converting an IDL DOMString value to an ECMAScript value is the String value that represents the same sequence of code units that the IDL DOMString represents.
4.2.17 ByteStringAn ECMAScript value V is converted to an IDL ByteString value by running the following algorithm:
The result of converting an IDL ByteString value to an ECMAScript value is a String value whose length is the length of the ByteString, and the value of each element of which is the value of the corresponding element of the ByteString.
4.2.18 USVStringAn ECMAScript value V is converted to an IDL USVString value by running the following algorithm:
An IDL USVString value is converted to an ECMAScript value by running the following algorithm:
IDL object values are represented by ECMAScript Object values.
An ECMAScript value V is converted to an IDL object value by running the following algorithm:
The result of converting an IDL object value to an ECMAScript value is the Object value that represents a reference to the same object that the IDL object represents.
4.2.20 Interface typesIDL interface type values are represented by ECMAScript Object or Function values.
An ECMAScript value V is converted to an IDL interface type value by running the following algorithm (where I is the interface):
The result of converting an IDL interface type value to an ECMAScript value is the Object value that represents a reference to the same object that the IDL interface type value represents.
4.2.21 Dictionary typesIDL dictionary type values are represented by ECMAScript Object values. Properties on the object (or its prototype chain) correspond to dictionary members.
An ECMAScript value V is converted to an IDL dictionary type value by running the following algorithm (where D is the dictionary):
Note
The order that dictionary members are looked up on the ECMAScript object are not necessarily the same as the object’s property enumeration order.
An IDL dictionary value V is converted to an ECMAScript Object value by running the following algorithm (where D is the dictionary):
({}).IDL enumeration types are represented by ECMAScript String values.
An ECMAScript value V is converted to an IDL enumeration type value as follows (where E is the enumeration):
The result of converting an IDL enumeration type value to an ECMAScript value is the String value that represents the same sequence of code units as the enumeration value.
4.2.23 Callback function typesIDL callback function types are represented by ECMAScript Function objects, except in the [TreatNonObjectAsNull] case, when they can be any object.
An ECMAScript value V is converted to an IDL callback function type value by running the following algorithm:
The result of converting an IDL callback function type value to an ECMAScript value is a reference to the same object that the IDL callback function type value represents.
4.2.24 Nullable types — T?IDL nullable type values are represented by values of either the ECMAScript type corresponding to the inner IDL type, or the ECMAScript null value.
An ECMAScript value V is converted to an IDL nullable type T? value (where T is the inner type) as follows:
The result of converting an IDL nullable type value to an ECMAScript value is:
IDL sequence<T> values are represented by ECMAScript Array values.
An ECMAScript value V is converted to an IDL sequence<T> value as follows:
An IDL sequence value S of type sequence<T> is converted to an ECMAScript Array object as follows:
[].To create an IDL value of type sequence<T> given an iterable iterable and an iterator getter method, perform the following steps:
The following interface defines an attribute of a sequence type as well as an operation with an argument of a sequence type.
IDL
interface Canvas {
sequence<DOMString> getSupportedImageCodecs();
void drawPolygon(sequence<double> coordinates);
sequence<double> getLastDrawnPolygon();
};In an ECMAScript implementation of this interface, an Array object with elements of type String is used to represent a sequence<DOMString>, while an Array with elements of type Number represents a sequence<double>. The Array objects are effectively passed by value; every time the getSupportedImageCodecs() function is called a new Array is returned, and whenever an Array is passed to drawPolygon no reference will be kept after the call completes.
ECMAScript
var canvas = getCanvas();
var supportedImageCodecs = canvas.getSupportedImageCodecs();
supportedImageCodecs[0];
supportedImageCodecs[0] = "image/jpeg";
canvas.getSupportedImageCodecs()[0];
canvas.getSupportedImageCodecs() == canvas.getSupportedImageCodecs();
var a = [0, 0, 100, 0, 50, 62.5];
canvas.drawPolygon(a);
a = [false, '',
{ valueOf: function() { alert('hi'); return 100; } }, 0,
'50', new Number(62.5)];
canvas.drawPolygon(s);
a[4] = 20;
var b = canvas.getLastDrawnPolygon();
alert(b[4]); IDL promise type values are represented by ECMAScript Promise objects.
An ECMAScript value V is converted to an IDL Promise<T> value as follows:
The result of converting an IDL promise type value to an ECMAScript value is the Promise value that represents a reference to the same object that the IDL promise type represents.
One can perform some steps once a promise is settled. There can be one or two sets of steps to perform, covering when the promise is fulfilled, rejected, or both. When a specification says to perform some steps once a promise is settled, the following steps MUST be followed:
IDL union type values are represented by ECMAScript values that correspond to the union’s member types.
To convert an ECMAScript value V to an IDL union type value is done as follows:
An IDL union type value is converted to an ECMAScript value as follows. If the value is an object reference to a special object that represents an ECMAScript undefined value, then it is converted to the ECMAScript undefined value. Otherwise, the rules for converting the specific type of the IDL union type value as described in this section ().
4.2.28 ErrorIDL Error values are represented by native ECMAScript Error objects and platform objects for DOMExceptions.
An ECMAScript value V is converted to an IDL Error value by running the following algorithm:
The result of converting an IDL Error value to an ECMAScript value is the Error value that represents a reference to the same object that the IDL Error represents.
4.2.29 DOMExceptionIDL DOMException values are represented by platform objects for DOMExceptions.
An ECMAScript value V is converted to an IDL DOMException value by running the following algorithm:
The result of converting an IDL DOMException value to an ECMAScript value is the Object value that represents a reference to the same object that the IDL DOMException represents.
4.2.30 Buffer source typesValues of the IDL buffer source types are represented by objects of the corresponding ECMAScript class.
An ECMAScript value V is converted to an IDL ArrayBuffer value by running the following algorithm:
An ECMAScript value V is converted to an IDL DataView value by running the following algorithm:
An ECMAScript value V is converted to an IDL Int8Array, Int16Array, Int32Array, Uint8Array, Uint16Array, Uint32Array, Uint8ClampedArray, Float32Array or Float64Array value by running the following algorithm:
The result of converting an IDL value of any buffer source type to an ECMAScript value is the Object value that represents a reference to the same object that the IDL value represents.
When getting a reference to or getting a copy of the bytes held by a buffer source that is an ECMAScript ArrayBuffer, DataView or typed array object, these steps MUST be followed:
To detach an ArrayBuffer, these steps MUST be followed:
This section defines a number of extended attributes whose presence affects only the ECMAScript binding.
4.3.1 [Clamp]If the [Clamp] extended attribute appears on an operation argument, writable attribute or dictionary member whose type is one of the integer types, it indicates that when an ECMAScript Number is converted to the IDL type, out of range values will be clamped to the range of valid values, rather than using the operators that use a modulo operation (ToInt32, ToUint32, etc.).
The [Clamp] extended attribute MUST take no arguments.
The [Clamp] extended attribute MUST NOT appear on a read only attribute, or an attribute, operation argument or dictionary member that is not of an integer type. It also MUST NOT be used in conjunction with the [EnforceRange] extended attribute.
See the rules for converting ECMAScript values to the various IDL integer types in section 4.2 for the specific requirements that the use of [Clamp] entails.
In the following IDL fragment, two operations are declared that take three octet arguments; one uses the [Clamp] extended attribute on all three arguments, while the other does not:
IDL
interface GraphicsContext {
void setColor(octet red, octet green, octet blue);
void setColorClamped([Clamp] octet red, [Clamp] octet green, [Clamp] octet blue);
};In an ECMAScript implementation of the IDL, a call to setColorClamped with Number values that are out of range for an octet are clamped to the range [0, 255].
ECMAScript
var context = getGraphicsContext();
context.setColor(-1, 255, 257);
context.setColorClamped(-1, 255, 257);If the [Constructor] extended attribute appears on an interface, it indicates that the interface object for this interface will have an [[Construct]] internal method, allowing objects implementing the interface to be constructed.
If it appears on a dictionary, then it indicates that the ECMAScript global object will have a property whose name is the identifier of the dictionary and whose value is a constructor function that can return an ECMAScript object that represents a dictionary value of the given type.
Multiple [Constructor] extended attributes may appear on a given interface or dictionary.
The [Constructor] extended attribute MUST either take no arguments or take an argument list. The bare form, [Constructor], has the same meaning as using an empty argument list, [Constructor()]. For each [Constructor] extended attribute on the interface, there will be a way to construct an object that implements the interface by passing the specified arguments.
The prose definition of a constructor MUST either return an IDL value of a type corresponding to the interface or dictionary the [Constructor] extended attribute appears on, or throw an exception.
If the [Constructor] extended attribute is specified on an interface, then the [NoInterfaceObject] extended attribute MUST NOT also be specified on that interface.
The [Constructor] extended attribute MUST NOT be used on a callback interface.
See section 4.6.1.1 for details on how a constructor for an interface is to be implemented, and section 4.6.3 for how a constructor for a dictionary is to be implemented.
The following IDL defines two interfaces. The second has the [Constructor] extended attribute, while the first does not.
IDL
interface NodeList {
Node item(unsigned long index);
readonly attribute unsigned long length;
};
[Constructor,
Constructor(double radius)]
interface Circle {
attribute double r;
attribute double cx;
attribute double cy;
readonly attribute double circumference;
};An ECMAScript implementation supporting these interfaces would have a [[Construct]] property on the Circle interface object which would return a new object that implements the interface. It would take either zero or one argument. The NodeList interface object would not have a [[Construct]] property.
ECMAScript
var x = new Circle();
var y = new Circle(1.25);
var z = new NodeList();
The following IDL defines a dictionary type with a constructor:
IDL
[Constructor(unsigned long patties, unsigned long cheeseSlices)]
dictionary BurgerOrder {
unsigned long pattyCount;
unsigned long cheeseSliceCount;
};The constructor is defined with the following prose:
When the BurgerOrder constructor is invoked, it must return a dictionary value of type BurgerOrder whose pattyCount and cheeseSliceCount members are set to the values of the patties and cheeseSlices arguments, respectively.
An ECMAScript implementation supporting this dictionary type would have a constructor function on the global object that returns a plain object with properties corresponding to the dictionary’s members:
ECMAScript
typeof BurgerOrder;
var order = new BurgerOrder(1, 2);
order.hasOwnProperty("pattyCount");
order.pattyCount;
Object.getPrototypeOf(order) == Object.prototype; If the [EnforceRange] extended attribute appears on an operation argument, writable regular attribute or dictionary member whose type is one of the integer types, it indicates that when an ECMAScript Number is converted to the IDL type, out of range values will cause an exception to be thrown, rather than converted to being a valid value using the operators that use a modulo operation (ToInt32, ToUint32, etc.). The Number will be rounded towards zero before being checked against its range.
The [EnforceRange] extended attribute MUST take no arguments.
The [EnforceRange] extended attribute MUST NOT appear on a read only attribute, a static attribute, or an attribute, operation argument or dictionary member that is not of an integer type. It also MUST NOT be used in conjunction with the [Clamp] extended attribute.
See the rules for converting ECMAScript values to the various IDL integer types in section 4.2 for the specific requirements that the use of [EnforceRange] entails.
In the following IDL fragment, two operations are declared that take three octet arguments; one uses the [EnforceRange] extended attribute on all three arguments, while the other does not:
IDL
interface GraphicsContext {
void setColor(octet red, octet green, octet blue);
void setColorEnforcedRange([EnforceRange] octet red, [EnforceRange] octet green, [EnforceRange] octet blue);
};In an ECMAScript implementation of the IDL, a call to setColorEnforcedRange with Number values that are out of range for an octet will result in an exception being thrown.
ECMAScript
var context = getGraphicsContext();
context.setColor(-1, 255, 257);
context.setColorEnforcedRange(-0.9, 255, 255.2);
context.setColorEnforcedRange(-1, 255, 256);If the [Exposed] extended attribute appears on an interface, partial interface, an individual interface member, or dictionary with a constructor, it indicates that the interface, interface member or dictionary constructor is exposed on a particular set of global interfaces, rather than the default of being exposed only on the primary global interface.
The [Exposed] extended attribute MUST either take an identifier or take an identifier list. Each of the identifiers mentioned MUST be a global name.
Every construct that the [Exposed] extended attribute can be specified on has an exposure set, which is a set of interfaces defining which global environments the construct can be used in. The exposure set for a given construct is defined as follows:
If the [Exposed] extended attribute is specified on the construct, then the exposure set is the set of all interfaces that have a global name that is listed in the extended attribute's argument.
If the [Exposed] extended attribute does not appear on a construct, then its exposure set is defined implicitly, depending on the type of construct:
If [Exposed] appears on an overloaded operation, then it MUST appear identically on all overloads.
The [Exposed] extended attribute MUST NOT be specified on both an interface member and a partial interface definition the interface member is declared on.
If [Exposed] appears on both an interface and one of its interface members, then the interface member's exposure set MUST be a subset of the interface's exposure set.
An interface's exposure set MUST be a subset of the exposure set of all of the interface's consequential interfaces.
If an interface X inherits from another interface Y then the exposure set of X MUST be a subset of the exposure set of Y.
The [Exposed] extended attribute MUST NOT be specified on a dictionary that does not also have a [Constructor] extended attribute.
An interface, interface member or dictionary is exposed in a given ECMAScript global environment if the ECMAScript global object implements an interface that is in the interface, interface member or dictionary's exposure set.
See section 4.6 , section 4.6.3 , section 4.6.6 , section 4.6.7 , section 4.6.8 and section 4.6.9 for the specific requirements that the use of [Exposed] entails.
[Exposed] is intended to be used to control whether interfaces or individual interface members are available for use only in workers, only in the Window, or in both.
The following IDL fragment shows how that might be achieved:
IDL
[PrimaryGlobal]
interface Window {
...
};
[Global=Worker]
interface SharedWorkerGlobalScope : WorkerGlobalScope {
...
};
[Global=Worker]
interface DedicatedWorkerGlobalScope : WorkerGlobalScope {
...
};
[Exposed=(Window,Worker)]
interface MathUtils {
static double someComplicatedFunction(double x, double y);
};
[Exposed=Worker]
interface WorkerUtils {
static void setPriority(double x);
};
interface Node {
...
};If the [Global] or [PrimaryGlobal] extended attribute appears on an interface, it indicates that objects implementing this interface can be used as the global object in an ECMAScript environment, and that the structure of the prototype chain and how properties corresponding to interface members will be reflected on the prototype objects will be different from other interfaces. Specifically:
Note
Placing named properties on an object in the prototype chain is done so that variable declarations and bareword assignments will shadow the named property with a property on the global object itself.
Placing properties corresponding to interface members on the object itself will mean that common feature detection methods like the following will work:
ECMAScript
var indexedDB = window.indexedDB || window.webkitIndexedDB ||
window.mozIndexedDB || window.msIndexedDB;
var requestAnimationFrame = window.requestAnimationFrame ||
window.mozRequestAnimationFrame || ...;Because of the way variable declarations are handled in ECMAScript, the code above would result in the window.indexedDB and window.requestAnimationFrame evaluating to undefined, as the shadowing variable property would already have been created before the assignment is evaluated.
If the [Global] or [PrimaryGlobal] extended attributes is used on an interface, then:
If [Global] or [PrimaryGlobal] is specified on a partial interface definition, then that partial interface definition MUST be the part of the interface definition that defines the named property getter.
The [Global] and [PrimaryGlobal] extended attribute MUST NOT be used on an interface that can have more than one object implementing it in the same ECMAScript global environment.
Note
This is because the named properties object, which exposes the named properties, is in the prototype chain, and it would not make sense for more than one object’s named properties to be exposed on an object that all of those objects inherit from.
If an interface is declared with the [Global] or [PrimaryGlobal] extended attribute, then there MUST NOT be more than one interface member across the interface and its consequential interfaces with the same identifier. There also MUST NOT be more than one stringifier, or more than one serializer across those interfaces.
Note
This is because all of the members of the interface and its consequential interfaces get flattened down on to the object that implements the interface.
The [Global] and [PrimaryGlobal] extended attributes can also be used to give a name to one or more global interfaces, which can then be referenced by the [Exposed] extended attribute.
The [Global] and [PrimaryGlobal] extended attributes MUST either take no arguments or take an identifier list.
If the [Global] or [PrimaryGlobal] extended attribute is declared with an identifier list argument, then those identifiers are the interface’s global names; otherwise, the interface has a single global name, which is the interface's identifier.
Note
The identifier argument list exists so that more than one global interface can be addressed with a single name in an [Exposed] extended attribute.
The [Global] and [PrimaryGlobal] extended attributes MUST NOT be declared on the same interface. The [PrimaryGlobal] extended attribute MUST be declared on at most one interface. The interface [PrimaryGlobal] is declared on, if any, is known as the primary global interface.
See section 4.6.5 , section 4.8.3 and section 4.8.7 for the specific requirements that the use of [Global] and [PrimaryGlobal] entails for named properties, and section 4.6.6 , section 4.6.7 and section 4.6.8 for the requirements relating to the location of properties corresponding to interface members.
The [PrimaryGlobal] extended attribute is intended to be used by the Window interface as defined in HTML5 ([HTML5], section 5.2). ([Global] is intended to be used by worker global interfaces.) The Window interface exposes frames as properties on the Window object. Since the Window object also serves as the ECMAScript global object, variable declarations or assignments to the named properties will result in them being replaced by the new value. Variable declarations for attributes will not create a property that replaces the existing one.
IDL
[PrimaryGlobal]
interface Window {
getter any (DOMString name);
attribute DOMString name;
};The following HTML document illustrates how the named properties on the Window object can be shadowed, and how the property for an attribute will not be replaced when declaring a variable of the same name:
HTML
<!DOCTYPE html>
<title>Variable declarations and assignments on Window</title>
<iframe name=abc></iframe>
<script>
window.abc;
abc = 1;
window.abc;
</script>
<script>
Window.prototype.def = 2;
window.hasOwnProperty("length");
length;
def;
</script>
<script>
var length;
length;
var def;
def;
</script>If the [LenientThis] extended attribute appears on a regular attribute, it indicates that invocations of the attribute’s getter or setter with a this value that is not an object that implements the interface on which the attribute appears will be ignored.
The [LenientThis] extended attribute MUST take no arguments. It MUST NOT be used on a static attribute.
Warning
Specifications SHOULD NOT use [LenientThis] unless required for compatibility reasons. Specification authors who wish to use this feature are strongly advised to discuss this on the public-script-coord@w3.org mailing list before proceeding.
See the Attributes section for how [LenientThis] is to be implemented.
The following IDL fragment defines an interface that uses the [LenientThis] extended attribute.
IDL
interface Example {
[LenientThis] attribute DOMString x;
attribute DOMString y;
};An ECMAScript implementation that supports this interface will allow the getter and setter of the accessor property that corresponds to x to be invoked with something other than an Example object.
ECMAScript
var example = getExample();
var obj = { };
example.x;
Object.getOwnPropertyDescriptor(Example.prototype, "x").get.call(obj);
Example.prototype.x;
Example.prototype.y;If the [NamedConstructor] extended attribute appears on an interface, it indicates that the ECMAScript global object will have a property with the specified name whose value is a constructor function that can create objects that implement the interface. Multiple [NamedConstructor] extended attributes may appear on a given interface.
The [NamedConstructor] extended attribute MUST either take an identifier or take a named argument list. The first form, [NamedConstructor=identifier], has the same meaning as using an empty argument list, [NamedConstructor=identifier()]. For each [NamedConstructor] extended attribute on the interface, there will be a way to construct an object that implements the interface by passing the specified arguments to the constructor function that is the value of the aforementioned property.
The identifier used for the named constructor MUST NOT be the same as that used by an [NamedConstructor] extended attribute on another interface, MUST NOT be the same as an identifier of an interface that has an interface object, and MUST NOT be one of the reserved identifiers.
The [NamedConstructor] extended attribute MUST NOT be used on a callback interface.
See section 4.6.2 for details on how named constructors are to be implemented.
The following IDL defines an interface that uses the [NamedConstructor] extended attribute.
IDL
[NamedConstructor=Audio,
NamedConstructor=Audio(DOMString src)]
interface HTMLAudioElement : HTMLMediaElement {
};An ECMAScript implementation that supports this interface will allow the construction of HTMLAudioElement objects using the Audio constructor.
ECMAScript
typeof Audio;
var a1 = new Audio();
var a2 = new Audio('a.flac');
If the [NewObject] extended attribute appears on a regular or static operation, then it indicates that when calling the operation, a reference to a newly created object MUST always be returned.
The [NewObject] extended attribute MUST take no arguments.
The [NewObject] extended attribute MUST NOT be used on anything other than a regular or static operation whose return type is an interface type or a promise type.
As an example, this extended attribute is suitable for use on the createElement operation on the Document interface ([DOM], section 6.5), since a new object should always be returned when it is called.
IDL
interface Document : Node {
[NewObject] Element createElement(DOMString localName);
...
};If the [NoInterfaceObject] extended attribute appears on an interface, it indicates that an interface object will not exist for the interface in the ECMAScript binding.
Warning
The [NoInterfaceObject] extended attribute SHOULD NOT be used on interfaces that are not solely used as supplemental interfaces, unless there are clear Web compatibility reasons for doing so. Specification authors who wish to use this feature are strongly advised to discuss this on the public-script-coord@w3.org mailing list before proceeding.
The [NoInterfaceObject] extended attribute MUST take no arguments.
If the [NoInterfaceObject] extended attribute is specified on an interface, then the [Constructor] extended attribute MUST NOT also be specified on that interface. A [NamedConstructor] extended attribute is fine, however.
The [NoInterfaceObject] extended attribute MUST NOT be specified on an interface that has any static operations defined on it.
The [NoInterfaceObject] extended attribute MUST NOT be specified on a callback interface unless it has a constant declared on it. This is because callback interfaces without constants never have interface objects.
An interface that does not have the [NoInterfaceObject] extended attribute specified MUST NOT inherit from an interface that has the [NoInterfaceObject] extended attribute specified.
See section 4.6 for the specific requirements that the use of [NoInterfaceObject] entails.
The following IDL fragment defines two interfaces, one whose interface object is exposed on the ECMAScript global object, and one whose isn’t:
IDL
interface Storage {
void addEntry(unsigned long key, any value);
};
[NoInterfaceObject]
interface Query {
any lookupEntry(unsigned long key);
};An ECMAScript implementation of the above IDL would allow manipulation of Storage’s prototype, but not Query’s.
ECMAScript
typeof Storage;
var fn = Storage.prototype.addEntry;
Storage.prototype.addEntry = function(key, value) {
alert('Calling addEntry()');
return fn.call(this, key, value);
};
typeof Query;
var fn = Query.prototype.lookupEntry;
If the [OverrideBuiltins] extended attribute appears on an interface, it indicates that for a platform object implementing the interface, properties corresponding to all of the object’s supported property names will appear to be on the object, regardless of what other properties exist on the object or its prototype chain. This means that named properties will always shadow any properties that would otherwise appear on the object. This is in contrast to the usual behavior, which is for named properties to be exposed only if there is no property with the same name on the object itself or somewhere on its prototype chain.
The [OverrideBuiltins] extended attribute MUST take no arguments and MUST NOT appear on an interface that does not define a named property getter or that also is declared with the [Global] or [PrimaryGlobal] extended attribute. If the extended attribute is specified on a partial interface definition, then that partial interface definition MUST be the part of the interface definition that defines the named property getter.
See section 4.8.1 and section 4.8.7 for the specific requirements that the use of [OverrideBuiltins] entails.
The following IDL fragment defines two interfaces, one that has a named property getter and one that does not.
IDL
interface StringMap {
readonly attribute unsigned long length;
getter DOMString lookup(DOMString key);
};
[OverrideBuiltins]
interface StringMap2 {
readonly attribute unsigned long length;
getter DOMString lookup(DOMString key);
};In an ECMAScript implementation of these two interfaces, getting certain properties on objects implementing the interfaces will result in different values:
ECMAScript
var map1 = getStringMap();
map1.abc;
map1.length;
map1.toString;
var map2 = getStringMap2();
map2.abc;
map2.length;
map2.toString;If the [PutForwards] extended attribute appears on a read only regular attribute declaration whose type is an interface type, it indicates that assigning to the attribute will have specific behavior. Namely, the assignment is “forwarded” to the attribute (specified by the extended attribute argument) on the object that is currently referenced by the attribute being assigned to.
The [PutForwards] extended attribute MUST take an identifier. Assuming that:
then there MUST be another attribute B declared on J whose identifier is N. Assignment of a value to the attribute A on an object implementing I will result in that value being assigned to attribute B of the object that A references, instead.
Note that [PutForwards]-annotated attributes can be chained. That is, an attribute with the [PutForwards] extended attribute can refer to an attribute that itself has that extended attribute. There MUST NOT exist a cycle in a chain of forwarded assignments. A cycle exists if, when following the chain of forwarded assignments, a particular attribute on an interface is encountered more than once.
An attribute with the [PutForwards] extended attribute MUST NOT also be declared with the [Replaceable] extended attribute.
The [PutForwards] extended attribute MUST NOT be used on an attribute that is not read only.
The [PutForwards] extended attribute MUST NOT be used on a static attribute.
The [PutForwards] extended attribute MUST NOT be used on an attribute declared on a callback interface.
See the Attributes section for how [PutForwards] is to be implemented.
The following IDL fragment defines interfaces for names and people. The [PutForwards] extended attribute is used on the name attribute of the Person interface to indicate that assignments to that attribute result in assignments to the full attribute of the Person object:
IDL
interface Name {
attribute DOMString full;
attribute DOMString family;
attribute DOMString given;
};
interface Person {
[PutForwards=full] readonly attribute Name name;
attribute unsigned short age;
};In the ECMAScript binding, this would allow assignments to the “name” property:
ECMAScript
var p = getPerson();
p.name = 'John Citizen';
p.name.full = 'John Citizen'; If the [Replaceable] extended attribute appears on a read only regular attribute, it indicates that setting the corresponding property on the platform object will result in an own property with the same name being created on the object which has the value being assigned. This property will shadow the accessor property corresponding to the attribute, which exists on the interface prototype object.
The [Replaceable] extended attribute MUST take no arguments.
An attribute with the [Replaceable] extended attribute MUST NOT also be declared with the [PutForwards] extended attribute.
The [Replaceable] extended attribute MUST NOT be used on an attribute that is not read only.
The [Replaceable] extended attribute MUST NOT be used on a static attribute.
The [Replaceable] extended attribute MUST NOT be used on an attribute declared on a callback interface.
See section 4.6.7 for the specific requirements that the use of [Replaceable] entails.
The following IDL fragment defines an interface with an operation that increments a counter, and an attribute that exposes the counter’s value, which is initially 0:
IDL
interface Counter {
[Replaceable] readonly attribute unsigned long value;
void increment();
};Assigning to the “value” property on a platform object implementing Counter will shadow the property that corresponds to the attribute:
ECMAScript
var counter = getCounter();
counter.value;
counter.hasOwnProperty("value");
Object.getPrototypeOf(counter).hasOwnProperty("value");
counter.increment();
counter.increment();
counter.value;
counter.value = 'a';
counter.hasOwnProperty("value");
counter.increment();
counter.value;
delete counter.value;
counter.value; If the [SameObject] extended attribute appears on a read only attribute, then it indicates that when getting the value of the attribute on a given object, the same value MUST always be returned.
The [SameObject] extended attribute MUST take no arguments.
The [SameObject] extended attribute MUST NOT be used on anything other than a read only attribute whose type is an interface type or object.
As an example, this extended attribute is suitable for use on the implementation attribute on the Document interface ([DOM], section 6.5), since the same object is always returned for a given Document object.
IDL
interface Document : Node {
[SameObject] readonly attribute DOMImplementation implementation;
...
};If the [TreatNonObjectAsNull] extended attribute appears on a callback function, then it indicates that any value assigned to an attribute whose type is a nullable callback function that is not an object will be converted to the null value.
See section 4.2.24 for the specific requirements that the use of [TreatNonObjectAsNull] entails.
The following IDL fragment defines an interface that has one attribute whose type is a [TreatNonObjectAsNull]-annotated callback function and another whose type is a callback function without the extended attribute:
IDL
callback OccurrenceHandler = void (DOMString details);
[TreatNonObjectAsNull]
callback ErrorHandler = void (DOMString details);
interface Manager {
attribute OccurrenceHandler? handler1;
attribute ErrorHandler? handler2;
};In an ECMAScript implementation, assigning a value that is not an object (such as a Number value) to handler1 will have different behavior from that when assigning to handler2:
ECMAScript
var manager = getManager();
manager.handler1 = function() { };
manager.handler1;
try {
manager.handler1 = 123;
} catch (e) {
}
manager.handler2 = function() { };
manager.handler2;
manager.handler2 = 123;
manager.handler2; If the [TreatNullAs] extended attribute appears on an attribute or operation argument whose type is DOMString, it indicates that a null value assigned to the attribute or passed as the operation argument will be handled differently from its default handling. Instead of being stringified to “null”, which is the default, it will be converted to the empty string “”.
If [TreatNullAs] is specified on an operation itself, and that operation is on a callback interface, then it indicates that a user object implementing the interface will have the return value of the function that implements the operation handled in the same way as for operation arguments and attributes, as above.
The [TreatNullAs] extended attribute MUST take the identifier EmptyString.
The [TreatNullAs] extended attribute MUST NOT be specified on an operation argument, attribute or operation return value whose type is not DOMString.
Note
This means that even an attribute of type DOMString? must not use [TreatNullAs], since null is a valid value of that type.
The [TreatNullAs] extended attribute also MUST NOT be specified on an operation on a non-callback interface.
See section 4.2.16 for the specific requirements that the use of [TreatNullAs] entails.
The following IDL fragment defines an interface that has one attribute with the [TreatNullAs] extended attribute, and one operation with an argument that has the extended attribute:
IDL
interface Dog {
attribute DOMString name;
[TreatNullAs=EmptyString] attribute DOMString owner;
boolean isMemberOfBreed([TreatNullAs=EmptyString] DOMString breedName);
};An ECMAScript implementation implementing the Dog interface would convert a null value assigned to the “owner” property or passed as the argument to the isMemberOfBreed function to the empty string rather than "null":
ECMAScript
var d = getDog();
d.name = null;
d.owner = null;
d.isMemberOfBreed(null);
If the [Unforgeable] extended attribute appears on a non-static attribute or non-static operations, it indicates that the attribute or operation will be reflected as an ECMAScript property in a way that means its behavior cannot be modified and that performing a property lookup on the object will always result in the attribute’s property value being returned. In particular, the property will be non-configurable and will exist as an own property on the object itself rather than on its prototype.
If the [Unforgeable] extended attribute appears on an interface, it indicates that all of the non-static attributes and non-static operations declared on that interface and its consequential interfaces will be similarly reflected as own ECMAScript properties on objects that implement the interface, rather than on the prototype.
An attribute or operation is said to be unforgeable on a given interface A if any of the following are true:
The [Unforgeable] extended attribute MUST take no arguments.
The [Unforgeable] extended attribute MUST NOT appear on anything other than an attribute, non- static operation or an interface. If it does appear on an operation, then it MUST appear on all operations with the same identifier on that interface.
If an attribute or operation X is unforgeable on an interface A, and A is one of the inherited interfaces of another interface B, then B and all of its consequential interfaces MUST NOT have a non-static attribute or regular operation with the same identifier as X.
Note
For example, the following is disallowed:
IDL
interface A1 {
[Unforgeable] readonly attribute DOMString x;
};
interface B1 : A1 {
void x();
};
interface B2 : A1 { };
B2 implements Mixin;
interface Mixin {
void x();
};
[Unforgeable]
interface A2 {
readonly attribute DOMString x;
};
interface B3 : A2 {
void x();
};
interface B4 : A2 { };
B4 implements Mixin;
interface Mixin {
void x();
};
interface A3 { };
A3 implements A2;
interface B5 : A3 {
void x();
};See section 4.6.7 , section 4.6.8 , section 4.8 , section 4.8.1 and section 4.8.7 for the specific requirements that the use of [Unforgeable] entails.
The following IDL fragment defines an interface that has two attributes, one of which is designated as [Unforgeable]:
IDL
interface System {
[Unforgeable] readonly attribute DOMString username;
readonly attribute long long loginTime;
};In an ECMAScript implementation of the interface, the username attribute will be exposed as a non-configurable property on the object itself:
ECMAScript
var system = getSystem();
system.hasOwnProperty("username");
system.hasOwnProperty("loginTime");
System.prototype.hasOwnProperty("username");
System.prototype.hasOwnProperty("loginTime");
try {
Object.defineProperty(system, "username", { value: "administrator" });
} catch (e) { }
var forgedLoginTime = 5;
Object.defineProperty(System.prototype, "loginTime", { value: forgedLoginTime });
system.loginTime; Certain algorithms in the sections below are defined to perform a security check on a given object. This check is used to determine whether a given operation invocation or attribute access should be allowed. The security check takes the following four inputs:
Note
The expectation is that the HTML specification defines how a security check is performed, and that it will either throw an appropriate exception or return normally. [HTML5]
4.5 Overload resolution algorithmIn order to define how overloaded function invocations are resolved, the overload resolution algorithm is defined. Its input is an effective overload set, S, and a list of ECMAScript values, arg0..n−1. Its output is a pair consisting of the operation or extended attribute of one of S’s entries and a list of IDL values or the special value “missing”. The algorithm behaves as follows:
Note
All entries in S at this point have the same type and optionality value at index i.
Note
This is the argument that will be used to resolve which overload is selected.
Note
The overload resolution algorithm performs both the identification of which overloaded operation, constructor, etc. is being called, and the conversion of the ECMAScript argument values to their corresponding IDL values. Informally, it operates as follows.
First, the selection of valid overloads is done by considering the number of ECMAScript arguments that were passed in to the function:
Once we have a set of possible overloads with the right number of arguments, the ECMAScript values are converted from left to right. The nature of the restrictions on overloading means that if we have multiple possible overloads at this point, then there will be one position in the argument list that will be used to distinguish which overload we will finally select; this is the distinguishing argument index.
We first convert the arguments to the left of the distinguishing argument. (There is a requirement that an argument to the left of the distinguishing argument index has the same type as in the other overloads, at the same index.) Then we inspect the type of the ECMAScript value that is passed in at the distinguishing argument index to determine which IDL type it may correspond to. This allows us to select the final overload that will be invoked. If the value passed in is undefined and there is an overload with an optional argument at this position, then we will choose that overload. If there is no valid overload for the type of value passed in here, then we throw a TypeError. The inspection of the value at the distinguishing argument index does not have any side effects; the only side effects that come from running the overload resolution algorithm are those that come from converting the ECMAScript values to IDL values.
At this point, we have determined which overload to use. We now convert the remaining arguments, from the distinguishing argument onwards, again ignoring any additional arguments that were ignored due to being passed after the last possible argument.
When converting an optional argument’s ECMAScript value to its equivalent IDL value, undefined will be converted into the optional argument’s default value, if it has one, or a special value “missing” otherwise.
Optional arguments corresponding to a final, variadic argument do not treat undefined as a special “missing” value, however. The undefined value is converted to the type of variadic argument as would be done for a non-optional argument.
4.6 InterfacesFor every interface that is exposed in a given ECMAScript global environment and:
a corresponding property MUST exist on the ECMAScript environment's global object. The name of the property is the identifier of the interface, and its value is an object called the interface object.
The property has the attributes { [[Writable]]: true, [[Enumerable]]: false, [[Configurable]]: true }. The characteristics of an interface object are described in section 4.6.1 .
In addition, for every [NamedConstructor] extended attribute on an exposed interface, a corresponding property MUST exist on the ECMAScript global object. The name of the property is the identifier that occurs directly after the “ =”, and its value is an object called a named constructor, which allows construction of objects that implement the interface. The property has the attributes { [[Writable]]: true, [[Enumerable]]: false, [[Configurable]]: true }. The characteristics of a named constructor are described in section 4.6.2 .
4.6.1 Interface objectThe interface object for a given non-callback interface is a function object. It has properties that correspond to the constants and static operations defined on that interface, as described in sections 4.6.6 Constants4.6.6 and 4.6.8 Operations4.6.8 .
The [[Prototype]] internal property of an interface object for a non-callback interface is determined as follows:
An interface object for a non-callback interface MUST have a property named “prototype” with attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false } whose value is an object called the interface prototype object. This object has properties that correspond to the regular attributes and regular operations defined on the interface, and is described in more detail in section 4.6.4 .
Note
Since an interface object for a non-callback interface is a function object the typeof operator will return "function" when applied to such an interface object.
The internal [[Prototype]] property of an interface object for a callback interface MUST be the Object.prototype object.
Warning
The NodeFilter implementations contradicts the paragraph above. This is discussed in Issue 78, Issue 96 and for the NodeFilter specfic case: Issue 83
Note
Remember that interface objects for callback interfaces only exist if they have constants declared on them; when they do exist, they are not function objects.
4.6.1.1 Interface object [[Call]] methodWarning
The current text currently allows calling XMLHttpRequest() or DOMException() to create an object, but the consensus is toward mandating using new. See Issue 62.
If the interface is declared with a [Constructor] extended attribute, then the interface object can be called as a function to create an object that implements that interface. Interfaces that do not have a constructor will throw an exception when called as a function.
The internal [[Call]] method of the interface object behaves as follows, assuming arg0..n−1 is the list of argument values passed to the constructor, and I is the interface:
If the internal [[Call]] method of the interface object returns normally, then it MUST return an object that implements interface I. This object also MUST be associated with the ECMAScript global environment associated with the interface object.
Interface objects for non-callback interfaces MUST have a property named “length” with attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true } whose value is a Number. If the [Constructor] extended attribute does not appear on the interface definition, then the value is 0. Otherwise, the value is determined as follows:
All interface objects MUST have a property named “name” with attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true } whose value is the identifier of the corresponding interface.
4.6.1.2 Interface object [[HasInstance]] methodWarning
The [[HasInstance]] implementations are currently not interoperable and the definition needs update to ES6. This is discussed in Issue 129
The internal [[HasInstance]] method of every interface object A MUST behave as follows, assuming V is the object argument passed to [[HasInstance]]:
A named constructor that exists due to one or more [NamedConstructor] extended attributes with a given identifier is a function object. It MUST have a [[Call]] internal property, which allows construction of objects that implement the interface on which the [NamedConstructor] extended attributes appear. It behaves as follows, assuming arg0..n−1 is the list of argument values passed to the constructor, id is the identifier of the constructor specified in the extended attribute named argument list, and I is the interface on which the [NamedConstructor] extended attribute appears:
If the internal [[Call]] method of the named constructor returns normally, then it MUST return an object that implements interface I. This object also MUST be associated with the ECMAScript global environment associated with the named constructor.
A named constructor MUST have a property named “length” with attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true } whose value is a Number determined as follows:
A named constructor MUST have a property named “name” with attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true } whose value is the identifier used for the named constructor.
A named constructor MUST also have a property named “prototype” with attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false } whose value is the interface prototype object for the interface on which the [NamedConstructor] extended attribute appears.
4.6.3 Dictionary constructorsFor every dictionary type that has one or more [Constructor] extended attributes and which is exposed in a given ECMAScript global environment, a corresponding property MUST exist on the ECMAScript environment's global object. The name of the property is the identifier of the dictionary, and its value is a function object called the dictionary constructor.
The property has the attributes { [[Writable]]: true, [[Enumerable]]: false, [[Configurable]]: true }.
The internal [[Call]] method of the interface object behaves as follows, assuming arg0..n−1 is the list of argument values passed to the constructor, and D is the dictionary type:
If the internal [[Call]] method of the named constructor returns normally, then it MUST return an object that is associated with the ECMAScript global environment associated with the dictionary constructor.
A dictionary constructor object MUST have a property named “length” with attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true } whose value is a Number determined as follows:
A dictionary constructor object MUST have a property named “name” with attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true } whose value is the identifier of the dictionary.
4.6.4 Interface prototype objectThere MUST exist an interface prototype object for every non-callback interface defined, regardless of whether the interface was declared with the [NoInterfaceObject] extended attribute. The interface prototype object for a particular interface has properties that correspond to the regular attributes and regular operations defined on that interface. These properties are described in more detail in sections 4.6.7 Attributes4.6.7 and 4.6.8 Operations4.6.8 .
As with the interface object, the interface prototype object also has properties that correspond to the constants defined on that interface, described in section 4.6.8 .
If the [NoInterfaceObject] extended attribute was not specified on the interface, then the interface prototype object MUST also have a property named “constructor” with attributes { [[Writable]]: true, [[Enumerable]]: false, [[Configurable]]: true } whose value is a reference to the interface object for the interface.
The interface prototype object for a given interface A MUST have an internal [[Prototype]] property whose value is returned from the following steps:
Note
The interface prototype object of an interface that is defined with the [NoInterfaceObject] extended attribute will be accessible if the interface is used as a non-supplemental interface. For example, with the following IDL:
IDL
[NoInterfaceObject]
interface Foo {
};
partial interface Window {
attribute Foo foo;
};it is not possible to access the interface prototype object through the interface object (since it does not exist as window.Foo). However, an instance of Foo can expose the interface prototype object by gettings its internal [[Prototype]] property value – Object.getPrototypeOf(window.foo) in this example.
If the interface is used solely as a supplemental interface, then there will be no way to access its interface prototype object, since no object will have the interface prototype object as its internal [[Prototype]] property value. In such cases, it is an acceptable optimization for this object not to exist.
The class string of an interface prototype object is the concatenation of the interface’s identifier and the string “Prototype”.
4.6.5 Named properties objectFor every interface declared with the [Global] or [PrimaryGlobal] extended attribute that supports named properties, there MUST exist an object known as the named properties object for that interface.
The named properties object for a given interface A MUST have an internal [[Prototype]] property whose value is returned from the following steps:
The class string of a named properties object is the concatenation of the interface’s identifier and the string “Properties”.
4.6.5.1 Named properties object [[GetOwnProperty]] methodThe internal [[GetOwnProperty]] method of every named properties object MUST behave as follows when called with object O and property name P:
Note
For example, if the interface is the Window interface as defined in HTML5 ([HTML5], section 5.2), then the sole object will be this global environment’s window object.
When the internal [[DefineOwnProperty]] method of a named properties object O is called with property key P and Property Descriptor ( [ ECMA-262] , section 6.2.4) Desc, the following steps MUST be taken:
The internal [[Delete]] method of every named properties object MUST behave as follows when called with object O and property name P.
For each exposed constant defined on an interface A, there MUST be a corresponding property. The property has the following characteristics:
In addition, a property with the same characteristics MUST exist on the interface object, if that object exists.
4.6.7 AttributesFor each exposed attribute of the interface, whether it was declared on the interface itself or one of its consequential interfaces, there MUST exist a corresponding property. The characteristics of this property are as follows:
Note
This means that even if an implements statement was used to make an attribute available on the interface, I is the interface on the left hand side of the implements statement, and not the one that the attribute was originally declared on.
The value of the Function object’s “length” property is the Number value 0.
The value of the Function object’s “name” property is a String whose value is the concatenation of “get ” and the identifier of the attribute.
readonly and has neither a [PutForwards] nor a [Replaceable] extended attribute declared on it. Otherwise, it is a Function object whose behavior when invoked is as follows:
The value of the Function object’s “length” property is the Number value 1.
The value of the Function object’s “name” property is a String whose value is the concatenation of “set ” and the identifier of the attribute.
Note
Although there is only a single property for an IDL attribute, since accessor property getters and setters are passed a this value for the object on which property corresponding to the IDL attribute is accessed, they are able to expose instance-specific data.
Note
Note that attempting to assign to a property corresponding to a read only attribute results in different behavior depending on whether the script doing so is in strict mode. When in strict mode, such an assignment will result in a TypeError being thrown. When not in strict mode, the assignment attempt will be ignored.
4.6.8 OperationsFor each unique identifier of an exposed operation defined on the interface, there MUST exist a corresponding property, unless the effective overload set for that identifier and operation and with an argument count of 0 has no entries. The characteristics of this property are as follows:
Note
This means that even if an implements statement was used to make an operation available on the interface, I is the interface on the left hand side of the implements statement, and not the one that the operation was originally declared on.
If the interface has an exposed stringifier, then there MUST exist a property with the following characteristics:
The value of the property is a Function object, which behaves as follows:
stringifier was specified:
Warning
The NodeFilterSerializers will be simplified soon, please see discussions in Issue 188
If the interface has an exposed serializer, then a property MUST exist whose name is “toJSON”, with attributes { [[Writable]]: true, [[Enumerable]]: true, [[Configurable]]: true } and whose value is a Function object.
The location of the property is determined as follows:
The property’s Function object, when invoked, MUST behave as follows:
serializer was specified:
The value of the Function object’s “length” property is the Number value 0.
The value of the Function object’s “name” property is the String value “toJSON”.
The following steps define how to convert a serialized value to an ECMAScript value:
({}).[].If the interface has any of the following:
then a property MUST exist whose name is the @@iterator symbol, with attributes { [[Writable]]: true, [[Enumerable]]: false, [[Configurable]]: true } and whose value is a function object.
The location of the property is determined as follows:
If the interface defines an indexed property getter, then the Function object is %ArrayProto_values% ( [ ECMA-262] , section 6.1.7.4).
If the interface has a pair iterator, then the Function, when invoked, MUST behave as follows:
The value of the @@iterator Function object’s “length” property is the Number value 0.
The value of the @@iterator Function object’s “name” property is the String value “[Symbol.iterator]”.
4.6.9.2 forEachIf the interface has any of the following:
then a property named “forEach” MUST exist with attributes { [[Writable]]: true, [[Enumerable]]: true, [[Configurable]]: true } and whose value is a function object.
The location of the property is determined as follows:
If the interface defines an indexed property getter, then the Function object is the initial value of the “forEach” data property of %ArrayPrototype% ( [ ECMA-262] , section 6.1.7.4).
If the interface has a pair iterator, then the Function MUST have the same behavior as one that would exist assuming the interface had this operation instead of the iterable declaration:
IDL
void forEach(Function callback, optional any thisArg);with the following prose definition:
The value of the Function object’s “length” property is the Number value 1.
The value of the Function object’s “name” property is the String value “forEach”.
4.6.10 Iterable declarations 4.6.10.1 entriesIf the interface has an iterable declaration, then a property named “entries” MUST exist with attributes { [[Writable]]: true, [[Enumerable]]: true, [[Configurable]]: true } and whose value is a function object.
The location of the property is determined as follows:
If the interface has a value iterator, then the Function object is the initial value of the “entries” data property of %ArrayPrototype% ( [ ECMA-262] , section 6.1.7.4).
If the interface has a pair iterator, then the Function, when invoked, MUST behave as follows:
The value of the Function object’s “length” property is the Number value 0.
The value of the Function object’s “name” property is the String value “entries”.
4.6.10.2 keysIf the interface has an iterable declaration, then a property named “keys” MUST exist with attributes { [[Writable]]: true, [[Enumerable]]: true, [[Configurable]]: true } and whose value is a function object.
The location of the property is determined as follows:
If the interface has a value iterator, then the Function object is the initial value of the “keys” data property of %ArrayPrototype% ( [ ECMA-262] , section 6.1.7.4).
If the interface has a pair iterator, then the Function, when invoked, MUST behave as follows:
The value of the Function object’s “length” property is the Number value 0.
The value of the Function object’s “name” property is the String value “keys”.
4.6.10.3 valuesIf the interface has an iterable declaration, then a property named “values” MUST exist with attributes { [[Writable]]: true, [[Enumerable]]: true, [[Configurable]]: true } and whose value is the function object that is the value of the @@iterator property.
The location of the property is determined as follows:
A default iterator object for a given interface, target and iteration kind is an object whose internal [[Prototype]] property is the iterator prototype object for the interface.
A default iterator object has three internal values:
When a default iterator object is first created, its index is set to 0.
The class string of a default iterator object for a given interface is the result of concatenting the identifier of the interface and the string “ Iterator”.
4.6.10.5 Iterator prototype objectThe iterator prototype object for a given interface is an object that exists for every interface that has a pair iterator. It serves as the prototype for default iterator objects for the interface.
The internal [[Prototype]] property of an iterator prototype object MUST be %IteratorPrototype% ( [ ECMA-262] , section 6.1.7.4).
An iterator prototype object MUST have a property named “next” with attributes { [[Writable]]: true, [[Enumerable]]: true, [[Configurable]]: true } and whose value is a function object that behaves as follows:
The class string of an iterator prototype object for a given interface is the result of concatenting the identifier of the interface and the string “Iterator”.
4.6.11 Initializing objects from iterablesSome objects, which are attempting to emulate map- and set-like interfaces, will want to accept iterables as constructor parameters and initialize themselves in this way. Here we provide some algorithms that can be invoked in order to do so in the same way as in the ECMAScript spec, so that those objects behave the same as the built-in Map and Set objects.
To add map elements from an iterable iterable to an object destination with adder method name adder, perform the following steps:
'0').'1').The interface prototype object of an interface A MUST have a copy of each property that corresponds to one of the constants, attributes, operations and iterable declarations that exist on all of the interface prototype objects of A’s consequential interfaces. For operations, where the property is a data property with a Function object value, each copy of the property MUST have distinct Function objects. For attributes, each copy of the accessor property MUST have distinct Function objects for their getters, and similarly with their setters.
Note
When invoking an operation by calling a Function object that is the value of one of the copies that exists due to an implements statement, the this value is checked to ensure that it is an object that implements the interface corresponding to the interface prototype object that the property is on.
For example, consider the following IDL:
IDL
interface A {
void f();
};
interface B { };
B implements A;
interface C { };
C implements A;Attempting to call B.prototype.f on an object that implements A (but not B) or one that implements C will result in a TypeError being thrown. However, calling A.prototype.f on an object that implements B or one that implements C would succeed. This is handled by the algorithm in section 4.6.8 that defines how IDL operation invocation works in ECMAScript.
Similar behavior is required for the getter and setter Function objects that correspond to an IDL attributes, and this is handled in section 4.6.7 .
4.8 Platform objects implementing interfacesEvery platform object is associated with a global environment, just as the initial objects are. It is the responsibility of specifications using Web IDL to state which global environment (or, by proxy, which global object) each platform object is associated with.
The primary interface of a platform object that implements one or more interfaces is the most-derived non-supplemental interface that it implements. The value of the internal [[Prototype]] property of the platform object is the interface prototype object of the primary interface from the platform object’s associated global environment.
The global environment that a given platform object is associated with can change after it has been created. When the global environment associated with a platform object is changed, its internal [[Prototype]] property MUST be immediately updated to be the interface prototype object of the primary interface from the platform object’s newly associated global environment.
Every platform object that implements an [Unforgeable]-annotated interface and which does not have a stringifier that is unforgeable on any of the interfaces it implements MUST have a property with the following characteristics:
Every platform object that implements an [Unforgeable]-annotated interface and which does not have a serializer that is unforgeable on any of the interfaces it implements MUST have a property with the following characteristics:
Every platform object that implements an [Unforgeable]-annotated interface MUST have a property with the following characteristics:
The class string of a platform object that implements one or more interfaces MUST be the identifier of the primary interface of the platform object.
4.8.1 Indexed and named propertiesIf a platform object implements an interface that supports indexed or named properties, the object will appear to have additional properties that correspond to the object’s indexed and named properties. These properties are not “real” own properties on the object, but are made to look like they are by being exposed by the [[GetOwnProperty]] internal method.
However, when the [Global] or [PrimaryGlobal] extended attribute has been used, named properties are not exposed on the object but on another object in the prototype chain, the named properties object.
It is permissible for an object to implement multiple interfaces that support indexed properties. However, if so, and there are conflicting definitions as to the object’s supported property indices, or if one of the interfaces is a supplemental interface for the platform object, then it is undefined what additional properties the object will appear to have, or what its exact behavior will be with regard to its indexed properties. The same applies for named properties.
The indexed property getter that is defined on the derived-most interface that the platform object implements is the one that defines the behavior when indexing the object with an array index. Similarly for indexed property setters. This way, the definitions of these special operations from ancestor interfaces can be overridden.
Platform objects implementing an interface that supports indexed or named properties cannot be fixed; if Object.freeze, Object.seal or Object.preventExtensions is called on one of these objects, the function MUST throw a TypeError. Similarly, an interface prototype object that exposes named properties due to the use of [Global] or [PrimaryGlobal] also MUST throw a TypeError if one of the three functions above is called on it.
The name of each property that appears to exist due to an object supporting indexed properties is an array index property name, which is a property name P such that Type(P) is String and for which the following algorithm returns true:
A property name is an unforgeable property name on a given platform object if the object implements an interface that has an interface member with that identifier and that interface member is unforgeable on any of the interfaces that O implements. If the object implements an [Unforgeable]-annotated interface, then “toString” and “valueOf” are also unforgeable property names on that object.
The named property visibility algorithm is used to determine if a given named property is exposed on an object. Some named properties are not exposed on an object depending on whether the [OverrideBuiltins] extended attribute was used. The algorithm operates as follows, with property name P and object O:
Note
This should ensure that for objects with named properties, property resolution is done in the following order:
Support for getters is handled by the platform object [[GetOwnProperty]] method defined in section , and for setters by the platform object [[DefineOwnProperty]] method defined in section and the platform object [[Set]] method defined in section .
4.8.2 The PlatformObjectGetOwnProperty abstract operationThe PlatformObjectGetOwnProperty abstract operation performs the following steps when called with an object O, a property name P, and a boolean ignoreNamedProps value:
The internal [[GetOwnProperty]] method of every platform object O that implements an interface which supports indexed or named properties MUST behave as follows when called with property name P:
To invoke an indexed property setter with property name P and ECMAScript value V, the following steps MUST be performed:
To invoke a named property setter with property name P and ECMAScript value V, the following steps MUST be performed:
The internal [[Set]] method of every platform object O that implements an interface which supports indexed or named properties MUST behave as follows when called with property name P, value V, and ECMAScript language value Receiver:
When the internal [[DefineOwnProperty]] method of a platform object O that implements an interface which supports indexed or named properties is called with property key P and Property Descriptor ( [ ECMA-262] , section 6.2.4) Desc, the following steps MUST be taken:
The internal [[Delete]] method of every platform object O that implements an interface which supports indexed or named properties MUST behave as follows when called with property name P.
The internal [[Call]] method of every platform object O that implements an interface I with at least one legacy caller MUST behave as follows, assuming arg0..n−1 is the list of argument values passed to [[Call]]:
This document does not define a complete property enumeration order for all platform objects implementing interfaces (or for platform objects representing exceptions). However, if a platform object implements an interface that supports indexed or named properties, then properties on the object MUST be enumerated in the following order:
Note
Future versions of the ECMAScript specification may define a total order for property enumeration.
4.9 User objects implementing callback interfacesAs described in section 3.9 , callback interfaces can be implemented in script by an ECMAScript object. The following cases determine whether and how a given object is considered to be a user object implementing a callback interface:
A single operation callback interface is a callback interface that:
A user object’s operation is called with a list of IDL argument values idlarg0..n−1 by following the algorithm below. The callback this value is the value to use as the this value when a callable object was supplied as the implementation of a single operation callback interface. By default, undefined is used as the callback this value, however this MAY be overridden by other specifications.
Note that ECMAScript objects need not have properties corresponding to constants on them to be considered as user objects implementing interfaces that happen to have constants declared on them.
The value of a user object’s attribute is retrieved using the following algorithm:
The value of a user object’s attribute is set using the following algorithm:
An ECMAScript callable object that is being used as a callback function value is called in a manner similar to how operations on user objects are called (as described in the previous section). The callable object is called with a list of values arg0..n−1, each of which is either an IDL value of the special value “missing” (representing a missing optional argument), by following the algorithm below. By default, the callback this value when invoking a callback function is undefined, unless overridden by other specifications.
There MUST exist a property on the ECMAScript global object whose name is “DOMException” and value is an object called the DOMException constructor object, which provides access to legacy DOMException code constants and allows construction of DOMException instances. The property has the attributes { [[Writable]]: true, [[Enumerable]]: false, [[Configurable]]: true }.
4.11.1 DOMException constructor objectThe DOMException constructor object MUST be a function object but with a [[Prototype]] value of %Error% ( [ ECMA-262] , section 6.1.7.4).
For every legacy code listed in the error names table, there MUST be a property on the DOMException constructor object whose name and value are as indicated in the table. The property has attributes { [[Writable]]: false, [[Enumerable]]: true, [[Configurable]]: false }.
The DOMException constructor object MUST also have a property named “prototype” with attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false } whose value is an object called the DOMException prototype object. This object also provides access to the legacy code values.
4.11.1.1 DOMException(message, name)When the DOMException function is called with arguments message and name, the following steps are taken:
"name", PropertyDescriptor{[[Value]]: name, [[Writable]]: true, [[Enumerable]]: false, [[Configurable]]: true})."code", PropertyDescriptor{[[Value]]: code, [[Writable]]: true, [[Enumerable]]: false, [[Configurable]]: true}).The DOMException prototype object MUST have an internal [[Prototype]] property whose value is %ErrorPrototype% ( [ ECMA-262] , section 6.1.7.4).
The class string of the DOMException prototype object is “DOMExceptionPrototype”.
There MUST be a property named “constructor” on the DOMException prototype object with attributes { [[Writable]]: true, [[Enumerable]]: false, [[Configurable]]: true } and whose value is the DOMException constructor object.
For every legacy code listed in the error names table, there MUST be a property on the DOMException prototype object whose name and value are as indicated in the table. The property has attributes { [[Writable]]: false, [[Enumerable]]: true, [[Configurable]]: false }.
4.12 Exception objectsSimple exceptions are represented by native ECMAScript objects of the corresponding type.
DOMExceptions are represented by platform objects that inherit from the DOMException prototype object.
Every platform object representing a DOMException in ECMAScript is associated with a global environment, just as the initial objects are. When an exception object is created by calling the DOMException constructor object, either normally or as part of a new expression, then the global environment of the newly created object is associated with MUST be the same as for the DOMException constructor object itself.
The value of the internal [[Prototype]] property of a DOMException object MUST be the DOMException prototype object from the global environment the exception object is associated with.
The class string of a DOMException object MUST be “DOMException”.
Note
The intention is for DOMException objects to be just like the other various native Error objects that the ECMAScript specification defines, apart from responding differently to being passed to Object.prototype.toString and it having a “code” property. If an implementation places non-standard properties on native Error objects, exposing for example stack traces or error line numbers, then these ought to be exposed on exception objects too.
4.13 Creating and throwing exceptionsFirst, we define the current global environment as the result of running the following algorithm:
When a simple exception or DOMException E is to be created, with error name N and optional user agent-defined message M, the following steps MUST be followed:
When a simple exception or DOMException E is to be thrown, with error name N and optional user agent-defined message M, the following steps MUST be followed:
Note
The above algorithms do not restrict platform objects representing exceptions propagating out of a Function to be ones that are associated with the global environment where that Function object originated. For example, consider the IDL:
IDL
interface A {
double doComputation(MathUtils m, double x);
};
interface MathUtils {
double computeSquareRoot(double x);
};If we pass a MathUtils object from a different global environment to doComputation, then the exception thrown will be from that global environment:
ECMAScript
var a = getA();
var m = otherWindow.getMathUtils();
a instanceof Object;
m instanceof Object;
m instanceof otherWindow.Object;
try {
a.doComputation(m, -1);
} catch (e) {
e instanceof DOMException;
e instanceof otherWindow.DOMException;
}Any requirements in this document to throw an instance of an ECMAScript built-in Error MUST use the built-in from the current global environment.
4.14 Handling exceptionsNone of the algorithms or processing requirements in the ECMAScript language binding catch ECMAScript exceptions. Whenever an ECMAScript Function is invoked due to requirements in this section and that Function ends due to an exception being thrown, that exception MUST propagate to the caller, and if not caught there, to its caller, and so on.
The following IDL fragment defines two interfaces and an exception. The valueOf attribute on ExceptionThrower is defined to throw an exception whenever an attempt is made to get its value.
IDL
interface Dahut {
attribute DOMString type;
};
interface ExceptionThrower {
attribute long valueOf;
};Assuming an ECMAScript implementation supporting this interface, the following code demonstrates how exceptions are handled:
ECMAScript
var d = getDahut();
var et = getExceptionThrower();
try {
d.type = { toString: function() { throw "abc"; } };
} catch (e) {
}
try {
d.type = { toString: { } };
} catch (e) {
}
d.type = et;
This section specifies some common definitions that all conforming implementations MUST support.
5.1 ArrayBufferViewIDL
typedef (Int8Array or Int16Array or Int32Array or
Uint8Array or Uint16Array or Uint32Array or Uint8ClampedArray or
Float32Array or Float64Array or DataView) ArrayBufferView;The ArrayBufferView typedef is used to represent objects that provide a view on to an ArrayBuffer.
5.2 BufferSourceIDL
typedef (ArrayBufferView or ArrayBuffer) BufferSource;The BufferSource typedef is used to represent objects that are either themselves an ArrayBuffer or which provide a view on to an ArrayBuffer.
5.3 DOMTimeStampIDL
typedef unsigned long long DOMTimeStamp;The DOMTimeStamp type is used for representing a number of milliseconds, either as an absolute time (relative to some epoch) or as a relative amount of time. Specifications that use this type will need to define how the number of milliseconds is to be interpreted.
5.4 FunctionIDL
callback Function = any (any... arguments);The Function callback function type is used for representing function values with no restriction on what arguments are passed to it or what kind of value is returned from it.
5.5 VoidFunctionIDL
callback VoidFunction = void ();The VoidFunction callback function type is used for representing function values that take no arguments and do not return any value.
6. ExtensibilityThis section is informative.
Extensions to language binding requirements can be specified using extended attributes that do not conflict with those defined in this document. Extensions for private, project-specific use should not be included in IDL fragments appearing in other specifications. It is recommended that extensions that are required for use in other specifications be coordinated with the group responsible for work on Web IDL, which at the time of writing is the W3C Web Platform Working Group, for possible inclusion in a future version of this document.
Extensions to any other aspect of the IDL language are strongly discouraged.
7. Referencing this specificationThis section is informative.
It is expected that other specifications that define Web platform interfaces using one or more IDL fragments will reference this specification. It is suggested that those specifications include a sentence such as the following, to indicate that the IDL is to be interpreted as described in this specification:
The IDL fragment in Appendix A of this specification must, in conjunction with the IDL fragments defined in this specification's normative references, be interpreted as required for conforming sets of IDL fragments, as described in the “Web IDL” specification. [WEBIDL]
In addition, it is suggested that the conformance class for user agents in referencing specifications be linked to the conforming implementation class from this specification:
8. AcknowledgementsA conforming FooML user agent must also be a conforming implementation of the IDL fragment in Appendix A of this specification, as described in the “Web IDL” specification. [WEBIDL]
This section is informative.
The editor would like to thank the following people for contributing to this specification: Glenn Adams, David Andersson, L. David Baron, Art Barstow, Nils Barth, Robin Berjon, David Bruant, Jan-Ivar Bruaroey, Marcos Cáceres, Giovanni Campagna, Domenic Denicola, Michael Dyck, Brendan Eich, João Eiras, Gorm Haug Eriksen, Sigbjorn Finne, David Flanagan, Aryeh Gregor, Dimitry Golubovsky, James Graham, Aryeh Gregor, Kartikaya Gupta, Marcin Hanclik, Jed Hartman, Stefan Haustein, Dominique Hazaël-Massieux, Ian Hickson, Björn Höhrmann, Kyle Huey, Lachlan Hunt, Oliver Hunt, Jim Jewett, Wolfgang Keller, Anne van Kesteren, Olav Junker Kjær, Magnus Kristiansen, Takeshi Kurosawa, Yves Lafon, Travis Leithead, Jim Ley, Kevin Lindsey, Jens Lindström, Peter Linss, 呂康豪 (Kang-Hao Lu), Kyle Machulis, Mark Miller, Ms2ger, Andrew Oakley, 岡坂 史紀 (Shiki Okasaka), Jason Orendorff, Olli Pettay, Simon Pieters, Andrei Popescu, François Remy, Tim Renouf, Alex Russell, Takashi Sakamoto, Doug Schepers, Jonas Sicking, Garrett Smith, Sam Sneddon, Jungkee Song, Josh Soref, Maciej Stachowiak, Anton Tayanovskyy, Peter Van der Beken, Jeff Walden, Allen Wirfs-Brock, Jeffrey Yasskin and Collin Xu.
Special thanks also go to Sam Weinig for maintaining this document while the editor was unavailable to do so.
A. IDL grammarThis section defines an LL(1) grammar whose start symbol, Definitions, matches an entire IDL fragment.
Each production in the grammar has on its right hand side either a non-zero sequence of terminal and non-terminal symbols, or an epsilon (ε) which indicates no symbols. Symbols that begin with an uppercase letter are non-terminal symbols. Symbols within quotes are terminal symbols that are matched with the exact text between the quotes. Symbols that begin with a lowercase letter are terminal symbols that are matched by the regular expressions (using Perl 5 regular expression syntax [PERLRE]) as follows:
integer = /-?([1-9][0-9]*|0[Xx][0-9A-Fa-f]+|0[0-7]*)/ float = /-?(([0-9]+\.[0-9]*|[0-9]*\.[0-9]+)([Ee][+-]?[0-9]+)?|[0-9]+[Ee][+-]?[0-9]+)/ identifier = /_?[A-Za-z][0-9A-Z_a-z-]*/ string = /"[^"]*"/ whitespace = /[\t\n\r ]+/ = /\/\/.*|\/\*(.|\n)*?\*\// other = /[^\t\n\r 0-9A-Za-z]/The tokenizer operates on a sequence of Unicode characters [ UNICODE]. When tokenizing, the longest possible match MUST be used. For example, if the input text is “a1”, it is tokenized as a single identifier, and not as a separate identifier and integer. If the longest possible match could match one of the above named terminal symbols or one of the quoted terminal symbols from the grammar, it MUST be tokenized as the quoted terminal symbol. Thus, the input text “long” is tokenized as the quoted terminal symbol "long" rather than an identifier called “long”, and “.” is tokenized as the quoted terminal symbol "." rather than an other.
The IDL syntax is case sensitive, both for the quoted terminal symbols used in the grammar and the values used for identifier terminals. Thus, for example, the input text “Const” is tokenized as an identifier rather than the quoted terminal symbol "const", an interface with identifier “A” is distinct from one named “a”, and an extended attribute [constructor] will not be recognized as the [Constructor] extended attribute.
Implicitly, any number of whitespace and comment terminals are allowed between every other terminal in the input text being parsed. Such whitespace and comment terminals are ignored while parsing.
The following LL(1) grammar, starting with Definitions, matches an IDL fragment:
Note
The Other non-terminal matches any single terminal symbol except for "(", ")", "[", "]", "{", "}" and ",".
While the ExtendedAttribute non-terminal matches any non-empty sequence of terminal symbols (as long as any parentheses, square brackets or braces are balanced, and the "," token appears only within those balanced brackets), only a subset of those possible sequences are used by the extended attributes defined in this specification — see section 3.11 for the syntaxes that are used by these extended attributes.
B. References B.1 Normative referencesRetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.3