Web IDL

1. Introduction

This 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.

2. Interface definition language

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 IDL grammar 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, namespaces, partial namespace 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 §2.12 Extended attributes, while those specific to the ECMAScript language binding are discussed in §3.3 ECMAScript-specific extended attributes.

[extended_attributes]
interface identifier {
  /* interface_members... */
};

Definitions :
    ExtendedAttributeList Definition Definitions
    ε

Definition :
    CallbackOrInterface
    Namespace
    Partial
    Dictionary
    Enum
    Typedef
    ImplementsStatement

CallbackOrInterface :
    "callback" CallbackRestOrInterface
    Interface

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);
};

2.1. Names

Every interface, partial interface definition, namespace, partial namespace 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:

• For named definitions, the identifier token that appears directly after the interface, namespace, dictionary, enum or callback keyword determines the identifier of that definition.

  interface interface_identifier { /* interface_members... */ };
  partial interface interface_identifier { /* interface_members... */ };
  namespace namespace_identifier { /* namespace_members... */ };
  partial namespace namespace_identifier { /* namespace_members... */ };
  dictionary dictionary_identifier { /* dictionary_members... */ };
  partial dictionary dictionary_identifier { /* dictionary_members... */ };
  enum enumeration_identifier { "enum", "values" /* , ... */ };
  callback callback_identifier = return_type (/* arguments... */);
  

• For attributes, typedefs and dictionary members, the final identifier token before the semicolon at the end of the declaration determines the identifier.

  interface identifier {
    attribute type attribute_identifier;
  };
  
  typedef type typedef_identifier;
  
  dictionary identifier {
    type dictionary_member_identifier;
  };
  

• For constants, the identifier token before the equals sign determines the identifier.

  const type constant_identifier = 42;

• For operations, the identifier token that appears after the return type but before the opening parenthesis (that is, one that is matched as part of the OptionalIdentifier grammar symbol in an OperationRest) determines the identifier of the operation. If there is no such identifier token, then the operation does not have an identifier.

  interface interface_identifier {
    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.

interface interface_identifier {
  return_type operation_identifier(argument_type argument_identifier /* , ... */);
};

ArgumentNameKeyword :
    "attribute"
    "callback"
    "const"
    "deleter"
    "dictionary"
    "enum"
    "getter"
    "implements"
    "inherit"
    "interface"
    "iterable"
    "legacycaller"
    "maplike"
    "namespace"
    "partial"
    "required"
    "serializer"
    "setlike"
    "setter"
    "static"
    "stringifier"
    "typedef"
    "unrestricted"

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, namespace, dictionary, enumeration, callback function and typedef must not be the same as the identifier of any other interface, namespace, 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.

interface B : A {
  void f(SequenceOfLongs x);
};

interface A {
};

typedef sequence<long> SequenceOfLongs;

// Typedef identifier: "number"
typedef double number;

// Interface identifier: "System"
interface System {

  // Operation identifier:          "createObject"
  // Operation argument identifier: "interface"
  object createObject(DOMString _interface);

  // Operation argument identifier: "interface"
  sequence<object> getObjects(DOMString interface);

  // Operation has no identifier; it declares a getter.
  getter DOMString (DOMString keyName);
};

// Interface identifier: "TextField"
interface TextField {

  // Attribute identifier: "const"
  attribute boolean _const;

  // Attribute identifier: "value"
  attribute DOMString? _value;
};

2.2. Interfaces

IDL 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 significance for property enumeration in the ECMAScript binding.

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.

interface A {
  void f();
  void g();
};

interface B : A {
  void f();
  void g(DOMString x);
};

[Object.prototype: the Object prototype object]
     ↑
[A.prototype: interface prototype object for A]
     ↑
[B.prototype: interface prototype object for B]
     ↑
[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 constant_identifier = 42;

  [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 §2.10 Objects implementing interfaces.

callback interface identifier {
  /* interface_members... */
};

Note: See also the similarly named callback function definition.

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.

Perhaps this warning shouldn’t apply if you are planning to extend the callback interface in the future. That’s probably a good reason to start off with a single operation callback interface.

I think we need to support operations not being implemented on a given user object implementing a callback interface. If specs extending an existing callback interface, we probably want to be able to avoid calling the operations that aren’t implemented (and having some default behavior instead). So we should perhaps define a term that means whether the operation is implemented, which in the ECMAScript binding would correspond to checking for the property’s existence.

callback interface Options {
  attribute DOMString? option1;
  attribute DOMString? option2;
  attribute long? option3;
};

interface A {
  void doTask(DOMString type, Options options);
};

var a = getA();  // Get an instance of A.

a.doTask("something", { option1: "banana", option3: 100 });

dictionary Options {
  DOMString? option1;
  DOMString? option2;
  long? option3;
};

interface A {
  void doTask(DOMString type, optional 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], [LegacyArrayClass], [NamedConstructor], [NoInterfaceObject].

Note: The above list of extended attributes is all of those defined in this document that are applicable to interfaces except for [Exposed], [Global], [OverrideBuiltins], [PrimaryGlobal], and [SecureContext].

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], [LegacyArrayClass], [NamedConstructor], [NoInterfaceObject], [OverrideBuiltins], [PrimaryGlobal], and [SecureContext].

CallbackRestOrInterface :
    CallbackRest
    Interface

Interface :
    "interface" identifier Inheritance "{" InterfaceMembers "}" ";"

Partial :
    "partial" PartialDefinition

PartialDefinition :
    PartialInterface
    PartialDictionary
    Namespace

PartialInterface :
    "interface" identifier "{" InterfaceMembers "}" ";"

InterfaceMembers :
    ExtendedAttributeList InterfaceMember InterfaceMembers
    ε

InterfaceMember :
    Const
    Operation
    Serializer
    Stringifier
    StaticMember
    Iterable
    ReadOnlyMember
    ReadWriteAttribute
    ReadWriteMaplike
    ReadWriteSetlike

Inheritance :
    ":" identifier
    ε

interface Animal {
  attribute DOMString name;
};

interface Human : Animal {
  attribute Dog? pet;
};

interface Dog : Animal {
  attribute Human? owner;
};

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);
};

var node = getNode();                                // Obtain an instance of Node.

var listener = {
  handleEvent: function(event) {
    // ...
  }
};
node.addEventListener("click", listener);            // This works.

node.addEventListener("click", function() { ... });  // As does this.

var node = getNode();  // Obtain an instance of Node.

var newNode = {
  nodeName: "span",
  parentNode: null,
  appendChild: function(newchild) {
    // ...
  },
  addEventListener: function(type, listener) {
    // ...
  }
};
node.appendChild(newNode);  // This will throw a TypeError exception.

2.2.1. Constants

A constant is a declaration (matching Const) used to bind a constant value to a name. Constants can appear on interfaces.

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 constant_identifier = 42;

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).

Note: These values – in addition to strings and the empty sequence – can also be used to specify the default value of a dictionary member or of an optional argument. Note that strings and the empty sequence [] cannot be used as the value of a constant.

The value of the boolean literal tokens true and false are the IDL boolean values true and false.

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 §2.11 Types.

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:

Type unrestricted float, constant value Infinity

The value is the IEEE 754 single-precision positive infinity value.

Type unrestricted double, constant value Infinity

The value is the IEEE 754 double-precision positive infinity value.

Type unrestricted float, constant value -Infinity

The value is the IEEE 754 single-precision negative infinity value.

Type unrestricted double, constant value -Infinity

The value is the IEEE 754 double-precision negative infinity value.

Type unrestricted float, constant value NaN

The value is the IEEE 754 single-precision NaN value with the bit pattern 0x7fc00000.

Type unrestricted double, constant value NaN

The value is the IEEE 754 double-precision NaN value with the bit pattern 0x7ff8000000000000.

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 §2.11 Types. 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.

interface A {
  const short rambaldi = 47;
};

The following extended attributes are applicable to constants: [Exposed], [SecureContext].

Const :
    "const" ConstType identifier "=" ConstValue ";"

ConstValue :
    BooleanLiteral
    FloatLiteral
    integer
    "null"

BooleanLiteral :
    "true"
    "false"

FloatLiteral :
    float
    "-Infinity"
    "Infinity"
    "NaN"

ConstType :
    PrimitiveType Null
    identifier Null

interface Util {
  const boolean DEBUG = false;
  const octet LF = 10;
  const unsigned long BIT_MASK = 0x0000fc00;
  const double AVOGADRO = 6.022e23;
};

2.2.2. Attributes

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:

1. regular attributes, which are those used to declare that objects implementing the interface will have a data field member with the given identifier

   interface interface_identifier {
     attribute type identifier;
   };
   

2. static attributes, which are used to declare attributes that are not associated with a particular object implementing the interface

   interface interface_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:

• a sequence type

• a dictionary type

• a record type

• a union type that has a nullable or non-nullable sequence type, dictionary, or record as one of its flattened member 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.

interface interface_identifier {
  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 §2.2.4.2 Stringifiers for details.

interface interface_identifier {
  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], [SecureContext], [TreatNullAs].

The following extended attributes are applicable only to regular attributes: [LenientSetter], [LenientThis], [PutForwards], [Replaceable], [Unforgeable].

ReadOnlyMember :
    "readonly" ReadOnlyMemberRest

ReadOnlyMemberRest :
    AttributeRest
    ReadWriteMaplike
    ReadWriteSetlike

ReadWriteAttribute :
    "inherit" ReadOnly AttributeRest
    AttributeRest

AttributeRest :
    "attribute" Type AttributeName ";"

AttributeName :
    AttributeNameKeyword
    identifier

AttributeNameKeyword :
    "required"

Inherit :
    "inherit"
    ε

ReadOnly :
    "readonly"
    ε

interface Animal {

  // A simple attribute that can be set to any string value.
  readonly attribute DOMString name;

  // An attribute whose value can be assigned to.
  attribute unsigned short age;
};

interface Person : Animal {

  // An attribute whose getter behavior is inherited from Animal, and need not be
  // specified in the description of Person.
  inherit attribute DOMString name;
};

2.2.3. Operations

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:

1. regular operations, which are those used to declare that objects implementing the interface will have a method with the given identifier

   interface interface_identifier {
     return_type identifier(/* arguments... */);
   };
   

2. special operations, which are used to declare special behavior on objects implementing the interface, such as object indexing and stringification

   interface interface_identifier {
     /* special_keywords... */ return_type identifier(/* arguments... */);
     /* special_keywords... */ return_type (/* arguments... */);
   };
   

3. static operations, which are used to declare operations that are not associated with a particular object implementing the interface

   interface interface_identifier {
     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 §2.2.4 Special operations for details on special operations. Note that in addition to being interface members, regular operations can also be namespace members.

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.

interface interface_identifier {
  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.

interface interface_identifier {
  return_type identifier([extended_attributes] type identifier, [extended_attributes] type identifier /* , ... */);
};

interface Dimensions {
  attribute unsigned long width;
  attribute unsigned long height;
};

interface Button {

  // An operation that takes no arguments and returns a boolean.
  boolean isMouseOver();

  // Overloaded operations.
  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.

interface interface_identifier {
  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.

interface IntegerSet {
  readonly attribute unsigned long cardinality;

  void union(long... ints);
  void intersection(long... ints);
};

var s = getIntegerSet();  // Obtain an instance of IntegerSet.

s.union();                // Passing no arguments corresponding to 'ints'.
s.union(1, 4, 7);         // Passing three arguments corresponding to 'ints'.

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.

interface interface_identifier {
  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.

interface interface_identifier {
  return_type identifier(type identifier, optional type identifier = "value");
};

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 record type or a union type that has a dictionary or record 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 or record, as appropriate, unless otherwise specified.

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.

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.

interface ColorCreator {
  object createColor(double v1, double v2, double v3, optional double alpha);
};

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], [SecureContext], [TreatNullAs], [Unforgeable].

The following extended attributes are applicable to operation arguments: [Clamp], [EnforceRange], [TreatNullAs].

DefaultValue :
    ConstValue
    string
    "[" "]"

Operation :
    ReturnType OperationRest
    SpecialOperation

SpecialOperation :
    Special Specials ReturnType OperationRest

Specials :
    Special Specials
    ε

Special :
    "getter"
    "setter"
    "deleter"
    "legacycaller"

OperationRest :
    OptionalIdentifier "(" ArgumentList ")" ";"

OptionalIdentifier :
    identifier
    ε

ArgumentList :
    Argument Arguments
    ε

Arguments :
    "," Argument Arguments
    ε

Argument :
    ExtendedAttributeList OptionalOrRequiredArgument

OptionalOrRequiredArgument :
    "optional" Type ArgumentName Default
    Type Ellipsis ArgumentName

ArgumentName :
    ArgumentNameKeyword
    identifier

Ellipsis :
    "..."
    ε

ReturnType :
    Type
    "void"

2.2.4. Special operations

A 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:

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.

interface Dictionary {
  readonly attribute unsigned long propertyCount;

  getter double (DOMString propertyName);
  setter void (DOMString propertyName, double propertyValue);
};

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.

interface Dictionary {
  readonly attribute unsigned long propertyCount;

  getter double getProperty(DOMString propertyName);
  setter void setProperty(DOMString propertyName, double propertyValue);
};

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 §2.2.4.4 Indexed properties and §2.2.4.5 Named properties 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.

2.2.4.1. Legacy callers

When 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.

interface interface_identifier {
  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 can only be defined on interfaces that also supports indexed or named properties.

Note: This artificial restriction allows bundling all interfaces with exotic object behavior into a single platform object category: legacy platform objects. This is possible because all existing interfaces which have a legacy caller also supports indexed or named properties.

Legacy callers must not be defined to return a promise type.

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.

interface NumberQuadrupler {
  // This operation simply returns four times the given number x.
  legacycaller double compute(double x);
};

var f = getNumberQuadrupler();  // Obtain an instance of NumberQuadrupler.

f.compute(3);                   // This evaluates to 12.
f(3);                           // This also evaluates to 12.

2.2.4.2. Stringifiers

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.

interface interface_identifier {
  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.

interface interface_identifier {
  stringifier;
};

interface A {
  stringifier DOMString ();
};

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.

interface interface_identifier {
  stringifier attribute DOMString identifier;
};

Stringifier :
    "stringifier" StringifierRest

StringifierRest :
    ReadOnly AttributeRest
    ReturnType OperationRest
    ";"

[Constructor]
interface Student {
  attribute unsigned long id;
  stringifier attribute DOMString name;
};

var s = new Student();
s.id = 12345678;
s.name = '周杰倫';

var greeting = 'Hello, ' + s + '!';  // Now greeting == 'Hello, 周杰倫!'.

[Constructor]
interface Student {
  attribute unsigned long id;
  attribute DOMString? familyName;
  attribute DOMString givenName;

  stringifier DOMString ();
};

var s = new Student();
s.id = 12345679;
s.familyName = 'Smithee';
s.givenName = 'Alan';

var greeting = 'Hi ' + s;  // Now greeting == 'Hi Alan Smithee'.

2.2.4.3. Serializers

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:

interface interface_identifier {
  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:

• a map of key–value pairs, where the keys are DOMString values (unique in the map) and the values are serialized values

• a list of serialized values

• a DOMString value

• an unrestricted double value

• a boolean value

• the null value

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.

Note: In the ECMAScript language binding, serialization behavior is exposed as a toJSON method which returns the serialized value converted into an ECMAScript value that can be serialized to JSON by the JSON.stringify function. See §3.6.7.2 Serializers for details.

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:

  interface interface_identifier {
    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:

  1. Let map be an empty map.

  2. If the inherit keyword was used, then set map to be the result of the serialization behavior of the closest inherited interface that declares a serializer.

  3. For each attribute identifier i in the serialization pattern, in order:

     1. Remove any entry in map with key name i.

     2. Let V be the value of the attribute with identifier i.

     3. Add an entry to map whose key name is i and whose value is result of converting V to a serialized value.

  4. Return map.

• A map with entries corresponding to all attributes from the interface that have a serializable type, and optionally attributes from an inherited interface:

  interface interface_identifier {
    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:

  1. Let map be an empty map.

  2. If the inherit keyword was used, then set map to be the result of the serialization behavior of the closest inherited interface that declares a serializer.

  3. For each identifier i of an attribute on the interface whose type is a serializable type, in the order they appear on the interface:

     1. Remove any entry in map with key name i.

     2. Let V be the value of the attribute with identifier i.

     3. Add an entry to map whose key name is i and whose value is result of converting V to a serialized value.

  4. Return map.

• A map with entries corresponding to the named properties:

  interface interface_identifier {
    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:

  1. Let map be an empty map.

  2. For each supported property name n on the object, in order:

     1. Let V be the value of the named property with name n.

     2. Add an entry to map whose key name is n and whose value is result of converting V to a serialized value.

  3. Return map.

• A list of value of zero or more attributes on the interface:

  interface interface_identifier {
    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:

  1. Let list be an empty list.

  2. For each attribute identifier i in the serialization pattern:

     1. Let V be the value of the attribute with identifier i.

     2. Append to list the value that is the result of converting V to a serialized value.

  3. Return list.

• A list with entries corresponding to the indexed properties:

  interface interface_identifier {
    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:

  1. Let list be an empty list.

  2. Let i be 0.

  3. While i is less than or equal to the greatest supported property index on the object:

     1. Let V be the value of the indexed property with index i if i is a supported property index, or null otherwise.

     2. Append to list the value that is the result of converting V to a serialized value.

     3. Set i to i + 1.

  4. Return list.

• A single attribute:

  interface interface_identifier {
    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:

  1. Let V be the value of the attribute with the specified identifier.

  2. Return the result of converting V to a serialized value.

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:

long long

converted by choosing the closest equivalent double value (as when converting a long long to an ECMAScript Number value)

unsigned long long

converted by choosing the closest equivalent double value (as when converting a unsigned long long to an ECMAScript Number value)

any other integer type

float

converted by choosing the equivalent double value

double

boolean

DOMString

the same value of the respective type

an enumeration type

the equivalent DOMString value

a USVString

the DOMString produced by encoding the given sequence of Unicode scalar values in UTF-16

a ByteString

the equivalent DOMString value where each code unit has the same value as the corresponding byte value

a nullable serializable type

converted to null if that is its value, otherwise converted as per its inner type

a union type where all of its member types are serializable types

converted as per its specific type

a sequence type that has a serializable type as its element type

converted to a list where each element is the result of converting its corresponding sequence element to a serialized value

a dictionary where all of its members have serializable types

converted to a map consisting of an entry for each dictionary member that is present, where the entry’s key is the identifier of the dictionary member and its value is the result of converting the dictionary member’s value to a serializable type

an interface type that has a serializer

converted by invoking the object’s serializer

Serializers can also be specified using an operation with the serializer keyword:

interface interface_identifier {
  serializer 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.

Serializer :
    "serializer" SerializerRest

SerializerRest :
    OperationRest
    "=" SerializationPattern ";"
    ";"

SerializationPattern :
    "{" SerializationPatternMap "}"
    "[" SerializationPatternList "]"
    identifier

SerializationPatternMap :
    "getter"
    "inherit" Identifiers
    identifier Identifiers
    ε

SerializationPatternList :
    "getter"
    identifier Identifiers
    ε

Identifiers :
    "," identifier Identifiers
    ε

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 {
  attribute DOMString name;
  attribute unsigned long number;
};

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 {
  attribute DOMString name;
  attribute unsigned long number;

  serializer = number;
};

// Get an instance of Transaction.
var txn = getTransaction();

// Evaluates to an object like this:
// {
//   from: 1234
//   to: 5678
//   amount: 110.75
//   description: "dinner"
// }
txn.toJSON();

// Evaluates to a string like this:
// '{"from":1234,"to":5678,"amount":110.75,"description":"dinner"}'
JSON.stringify(txn);

2.2.4.4. Indexed properties

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.

interface interface_identifier {
  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:

• If an indexed property getter was specified using an operation with an identifier, then the value returned when indexing the object with a given supported property index is the value that would be returned by invoking the operation, passing the index as its only argument. If the operation used to declare the indexed property getter did not have an identifier, then the interface definition must be accompanied by a description of how to determine the value of an indexed property for a given index.

• If an indexed property setter was specified using an operation with an identifier, then the behavior that occurs when indexing the object for property assignment with a given supported property index and value is the same as if the operation is invoked, passing the index as the first argument and the value as the second argument. If the operation used to declare the indexed property setter did not have an identifier, then the interface definition must be accompanied by a description of how to set the value of an existing indexed property and how to set the value of a new indexed property for a given property index and value.

interface A {
  getter DOMString toWord(unsigned long index);
};

var a = getA();

a.toWord(0);  // Evalautes to "zero".
a[0];         // Also evaluates to "zero".

a.toWord(5);  // Evaluates to "five".
a[5];         // Evaluates to undefined, since there is no property "5".

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);
};

// Assume map is a legacy platform object implementing the OrderedMap interface.
var map = getOrderedMap();
var x, y;

x = map[0];       // If map.length > 0, then this is equivalent to:
                  //
                  //   x = map.getByIndex(0)
                  //
                  // since a property named "0" will have been placed on map.
                  // Otherwise, x will be set to undefined, since there will be
                  // no property named "0" on map.

map[1] = false;   // This will do the equivalent of:
                  //
                  //   map.setByIndex(1, false)

y = map.apple;    // If there exists a named property named "apple", then this
                  // will be equivalent to:
                  //
                  //   y = map.get('apple')
                  //
                  // since a property named "apple" will have been placed on
                  // map.  Otherwise, y will be set to undefined, since there
                  // will be no property named "apple" on map.

map.berry = 123;  // This will do the equivalent of:
                  //
                  //   map.set('berry', 123)

delete map.cake;  // If a named property named "cake" exists, then the "cake"
                  // property will be deleted, and then the equivalent to the
                  // following will be performed:
                  //
                  //   map.remove("cake")

2.2.4.5. Named properties

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.

interface interface_identifier {
  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:

• If a named property getter was specified using an operation with an identifier, then the value returned when indexing the object with a given supported property name is the value that would be returned by invoking the operation, passing the name as its only argument. If the operation used to declare the named property getter did not have an identifier, then the interface definition must be accompanied by a description of how to determine the value of a named property for a given property name.

• If a named property setter was specified using an operation with an identifier, then the behavior that occurs when indexing the object for property assignment with a given supported property name and value is the same as if the operation is invoked, passing the name as the first argument and the value as the second argument. If the operation used to declare the named property setter did not have an identifier, then the interface definition must be accompanied by a description of how to set the value of an existing named property and how to set the value of a new named property for a given property name and value.

• If a named property deleter was specified using an operation with an identifier, then the behavior that occurs when indexing the object for property deletion with a given supported property name is the same as if the operation is invoked, passing the name as the only argument. If the operation used to declare the named property deleter did not have an identifier, then the interface definition must be accompanied by a description of how to delete an existing named property for a given property name.

Note: As with indexed properties, if an named property getter, setter or deleter is specified using an operation with an identifier, then indexing an object with a name that is not a supported property name does not necessarily elicit the same behavior as invoking the operation with that name; the behavior is language binding specific.

2.2.5. Static attributes and operations

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.

StaticMember :
    "static" StaticMemberRest

StaticMemberRest :
    ReadOnly AttributeRest
    ReturnType OperationRest

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);
};

var circles = getCircles();           // an Array of Circle objects

typeof Circle.triangulate;            // Evaluates to "function"
typeof Circle.triangulationCount;     // Evaluates to "number"
Circle.prototype.triangulate;         // Evaluates to undefined
Circle.prototype.triangulationCount;  // Also evaluates to undefined
circles[0].triangulate;               // As does this
circles[0].triangulationCount;        // And this

// Call the static operation
var triangulationPoint = Circle.triangulate(circles[0], circles[1], circles[2]);

// Find out how many triangulations we have done
window.alert(Circle.triangulationCount);

2.2.6. Overloading

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.

interface A {
  void f();
};

partial interface A {
  void f(double x);
  void g();
};

partial interface A {
  void g(DOMString x);
};

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.

For regular operations

For static operations

• the interface on which the operations are to be found

• the identifier of the operations

• the number of arguments to be passed

For legacy callers

• the interface on which the legacy callers are to be found

• the number of arguments to be passed

For constructors

• the interface on which the [Constructor] extended attributes are to be found

• the number of arguments to be passed

For named constructors

• the interface on which the [NamedConstructor] extended attributes are to be found

• the identifier of the named constructors

• the number of arguments to be passed

For callback functions

• the callback function

• the number of arguments to be passed

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.

interface A {
  /* f1 */ void f(DOMString a);
  /* f2 */ void f(Node a, DOMString b, double... c);
  /* f3 */ void f();
  /* f4 */ void f(Event a, DOMString b, optional DOMString c, double... d);
};

{ <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 the following algorithm returns true.

1. If one type includes a nullable type and the other type either includes a nullable type, is a union type with flattened member types including a dictionary type or record type, or is a dictionary type or record type, return false.

   None of the following pairs are distinguishable:

   • double? and record<DOMString, DOMString>
   • (Interface1 or long)? and (Interface2 or DOMString)?
   • (Interface1 or long?) and (Interface2 or DOMString)?
   • (Interface1 or long?) and (Interface2 or DOMString?)
   • (Dictionary1 or long) and (Interface2 or DOMString)?
   • (Dictionary1 or long) and (Interface2 or DOMString?)

2. If both types are either a union type or nullable union type, return true if each member type of the one is distinguishable with each member type of the other, or false otherwise.

3. If one type is a union type or nullable union type, return true if each member type of the union type is distinguishable with the non-union type, or false otherwise.

4. If 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, then return true. Otherwise return false.

   	boolean	numeric types	string types	interface	object	callback function	dictionary/record	sequence<T>	FrozenArray<T>	exception types	buffer source types
   boolean		●	●	●	●	●	●	●	●	●	●
   numeric types			●	●	●	●	●	●	●	●	●
   string types				●	●	●	●	●	●	●	●
   interface				(a)		(b)	(b)	●	●	●	●
   object
   callback function								●	●	●	●
   dictionary/record								●	●	●	●
   sequence<T>										●	●
   FrozenArray<T>										●	●
   exception types											●
   buffer source types

   1. The two identified interfaces are not the same, it is not possible for a single platform object to implement both interfaces, and it is not the case that both are callback interfaces.

   2. The interface type is not a callback interface.

   double and DOMString are distinguishable because there is a ● at the intersection of numeric types with string types.
   double and long are not distinguishable because they are both numeric types, and there is no ● or letter at the intersection of numeric types with numeric types.
   Given:

   callback interface CBIface {
       attribute DOMString attr1;
   };
   
   interface Iface {
       attribute DOMString attr2;
   };
   
   dictionary Dict {
       DOMString field1;
   };
   

   CBIface is distinguishable from Iface because the pair satisfies note (a), but it is not distinguishable from Dict because that pair does not satisfy note (b).

   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.

interface B {
  void f(DOMString x);
  void f(double x);
};

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.

interface B {
  /* f1 */ void f(DOMString w);
  /* f2 */ void f(long w, double x, Node y, Node z);
  /* f3 */ void f(double w, double x, DOMString y, Node z);
};

{ <f1, (DOMString), (required)>,
  <f2, (long, double, Node, Node), (required, required, required, required)>,
  <f3, (double, double, DOMString, Node), (required, required, required, required)> }

2.2.7. Iterable declarations

An interface can be declared to be iterable by using an iterable declaration (matching Iterable) in the body of the interface.

interface interface_identifier {
  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: This is how array iterator objects work. For interfaces that support indexed properties, the iterator objects returned by “entries”, “keys”, “values” and @@iterator are actual array iterator objects.

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.

interface SessionManager {
  Session getSessionForUser(DOMString username);
  readonly attribute unsigned long sessionCount;

  iterable<Session>;
};

interface Session {
  readonly attribute DOMString username;
  // ...
};

// Get an instance of SessionManager.
// Assume that it has sessions for two users, "anna" and "brian".
var sm = getSessionManager();

typeof SessionManager.prototype.values;            // Evaluates to "function"
var it = sm.values();                              // values() returns an iterator object
String(it);                                        // Evaluates to "[object SessionManager Iterator]"
typeof it.next;                                    // Evaluates to "function"

// This loop will alert "anna" and then "brian".
for (;;) {
  let result = it.next();
  if (result.done) {
    break;
  }
  let session = result.value;
  window.alert(session.username);
}

// This loop will also alert "anna" and then "brian".
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. An interface with an iterable declaration and its inherited and consequential interfaces must not have a maplike declaration or setlike declaration.

The following extended attributes are applicable to iterable declarations: [Exposed], [SecureContext].

Iterable :
    "iterable" "<" Type OptionalType ">" ";"

OptionalType :
    "," Type
    ε

2.2.8. Maplike declarations

An interface can be declared to be maplike by using a maplike declaration (matching ReadWriteMaplike or readonly MaplikeRest) in the body of the interface.

interface interface_identifier {
  readonly maplike<key_type, value_type>;
  maplike<key_type, value_type>;
};

Objects implementing an interface that is declared to be maplike represent an ordered list of key–value pairs known as its map entries. The types used for the keys and values are given in the angle brackets of the maplike declaration. Keys are required to be unique.

The map entries of an object implementing a maplike interface is empty at the of the object’s creation. Prose accompanying the interface can describe how the map entries of an object change.

Maplike interfaces support an API for querying the map entries appropriate for the language binding. If the readonly keyword is not used, then it also supports an API for modifying the map entries.

Note: In the ECMAScript language binding, the API for interacting with the map entries is similar to that available on ECMAScript Map objects. If the readonly keyword is used, this includes “entries”, “forEach”, “get”, “has”, “keys”, “values”, @@iterator methods and a “size” getter. For read–write maplikes, it also includes “clear”, “delete” and “set” methods.

Maplike interfaces must not have any interface members named “entries”, “forEach”, “get”, “has”, “keys”, “size”, or “values”, or have any inherited or consequential interfaces that have interface members with these names. Read–write maplike interfaces must not have any attributes or constants named “clear”, “delete”, or “set”, or have any inherited or consequential interfaces that have attributes or constants with these names.

Note: Operations named “clear”, “delete”, or “set” are allowed on read–write maplike interfaces and will prevent the default implementation of these methods being added to the interface prototype object in the ECMAScript language binding. This allows the default behavior of these operations to be overridden.

An interface must not have more than one maplike declaration. The inherited and consequential interfaces of a maplike interface must not also have a maplike declaration. A maplike interface and its inherited and consequential interfaces must not have an iterable declaration or setlike declaration.

ReadWriteMaplike :
    MaplikeRest

MaplikeRest :
    "maplike" "<" Type "," Type ">" ";"

No extended attributes defined in this specification are applicable to maplike declarations.

Add example.

2.2.9. Setlike declarations

An interface can be declared to be setlike by using a setlike declaration (matching ReadWriteSetlike or readonly SetlikeRest) in the body of the interface.

interface interface_identifier {
  readonly setlike<type>;
  setlike<type>;
};

Objects implementing an interface that is declared to be setlike represent an ordered list of values known as its set entries. The type of the values is given in the angle brackets of the setlike declaration. Values are required to be unique.

The set entries of an object implementing a setlike interface is empty at the of the object’s creation. Prose accompanying the interface can describe how the set entries of an object change.

Setlike interfaces support an API for querying the set entries appropriate for the language binding. If the readonly keyword is not used, then it also supports an API for modifying the set entries.

Note: In the ECMAScript language binding, the API for interacting with the set entries is similar to that available on ECMAScript Set objects. If the readonly keyword is used, this includes “entries”, “forEach”, “has”, “keys”, “values”, @@iterator methods and a “size” getter. For read–write setlikes, it also includes “add”, “clear”, and “delete” methods.

Setlike interfaces must not have any interface members named “entries”, “forEach”, “has”, “keys”, “size”, or “values”, or have any inherited or consequential interfaces that have interface members with these names.. Read–write setlike interfaces must not have any attributes or constants named “add”, “clear”, or “delete”, or have any inherited or consequential interfaces that have attributes or constants with these names.

Note: Operations named “add”, “clear”, or “delete” are allowed on read–write setlike interfaces and will prevent the default implementation of these methods being added to the interface prototype object in the ECMAScript language binding. This allows the default behavior of these operations to be overridden.

An interface must not have more than one setlike declaration. The inherited and consequential interfaces of a setlike interface must not also have a setlike declaration. A setlike interface and its inherited and consequential interfaces must not have an iterable declaration or maplike declaration.

ReadWriteSetlike :
    SetlikeRest

SetlikeRest :
    "setlike" "<" Type ">" ";"

No extended attributes defined in this specification are applicable to setlike declarations.

Add example.

2.3. Namespaces

A namespace is a definition (matching Namespace) that declares a global singleton with associated behaviors.

namespace identifier {
  /* namespace_members... */
};

A namespace is a specification of a set of namespace members (matching NamespaceMembers), which are the regular operations that appear between the braces in the namespace declaration. These operations describe the behaviors packaged into the namespace.

As with interfaces, the IDL for namespaces can be split into multiple parts by using partial namespace definitions (matching partial Namespace). The identifier of a partial namespace definition must be the same as the identifier of a namespace definition. All of the members that appear on each of the partial namespace definitions are considered to be members of the namespace itself.

namespace SomeNamespace {
  /* namespace_members... */
};

partial namespace SomeNamespace {
  /* namespace_members... */
};

Note: As with partial interface definitions, partial namespace definitions are intended for use as a specification editorial aide, allowing the definition of a namespace to be separated over more than one section of the document, and sometimes multiple documents.

The order that members appear in has significance for property enumeration in the ECMAScript binding.

Note that unlike interfaces or dictionaries, namespaces do not create types.

Of the extended attributes defined in this specification, only the [Exposed] and [SecureContext] extended attributes are applicable to namespaces.

Namespace :
    "namespace" identifier "{" NamespaceMembers "}" ";"

NamespaceMembers :
    ExtendedAttributeList NamespaceMember NamespaceMembers
    ε

NamespaceMember :
    ReturnType OperationRest

namespace VectorUtils {
  double dotProduct(Vector x, Vector y);
  Vector crossProduct(Vector x, Vector y);
};

Object.getPrototypeOf(VectorUtils);                         // Evaluates to Object.prototype.
Object.keys(VectorUtils);                                   // Evaluates to ["dotProduct", "crossProduct"].
Object.getOwnPropertyDescriptor(VectorUtils, "dotProduct"); // Evaluates to { value: <a function>, enumerable: true, configurable: true, writable: true }.

2.4. Dictionaries

A 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.

As with operation argument default values, is strongly suggested not to use of true as the default value for boolean-typed dictionary members, as this can be confusing for authors who might otherwise expect the default conversion of undefined to be used (i.e., false).

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:

• the type is D

• the type is a dictionary that inherits from D

• the type is a nullable type whose inner type includes D

• the type is a sequence type or frozen array whose element type includes D

• the type is a union type, one of whose member types includes D

• the type is a dictionary, one of whose members or inherited members has a type that includes D

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.

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;
};

interface Something {
  void f(A a);
};

var something = getSomething();  // Get an instance of Something.
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 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], [SecureContext],

The following extended attributes are applicable to dictionary members: [Clamp], [EnforceRange].

Dictionary :
    "dictionary" identifier Inheritance "{" DictionaryMembers "}" ";"

DictionaryMembers :
    ExtendedAttributeList DictionaryMember DictionaryMembers
    ε

DictionaryMember :
    Required Type identifier Default ";"

Required :
    "required"
    ε

PartialDictionary :
    "dictionary" identifier "{" DictionaryMembers "}" ";"

Default :
    "=" DefaultValue
    ε

[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);
};

// Get an instance of GraphicsContext.
var ctx = getGraphicsContext();

// Draw a rectangle.
ctx.drawRectangle(300, 200, { fillPattern: "red", position: new Point(10, 10) });

2.5. Exceptions

An 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 type values:

• EvalError

• RangeError

• ReferenceError

• TypeError

• URIError

These correspond to all of the ECMAScript error objects (apart from SyntaxError and Error, which are deliberately omitted as they are reserved for use by the ECMAScript parser and authors, respectively). 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.

Simple exceptions can be created by providing their error name. DOMExceptions, by providing their error name followed by DOMException. 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 §3.15 Creating and throwing exceptions for details on what creating and throwing an exception entails in the ECMAScript language binding.

2.5.1. Error names

The 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!

2.6. 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 { "enum", "values" /* , ... */ };

The enumeration values are specified as a comma-separated list of string literals. The list of enumeration values must not include duplicates.

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.

Enum :
    "enum" identifier "{" EnumValueList "}" ";"

EnumValueList :
    string EnumValueListComma

EnumValueListComma :
    "," EnumValueListString
    ε

EnumValueListString :
    string EnumValueListComma
    ε

enum MealType { "rice", "noodles", "other" };

interface Meal {
  attribute MealType type;
  attribute double size;     // in grams

  void initialize(MealType type, double size);
};

var meal = getMeal();                // Get an instance of Meal.

meal.initialize("rice", 200);        // Operation invoked as normal.

try {
  meal.initialize("sandwich", 100);  // Throws a TypeError.
} catch (e) {
}

meal.type = "noodles";               // Attribute assigned as normal.
meal.type = "dumplings";             // Attribute assignment ignored.
meal.type == "noodles";              // Evaluates to true.

2.7. Callback functions

The “Custom DOM Elements” spec wants to use callback function types for platform object provided functions. Should we rename “callback functions” to just “functions” to make it clear that they can be used for both purposes?

A callback function is a definition (matching callback CallbackRest) used to declare a function type.

callback identifier = return_type (/* arguments... */);

Note: See also the similarly named callback interfaces.

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].

CallbackRest :
    identifier "=" ReturnType "(" ArgumentList ")" ";"

callback AsyncOperationCallback = void (DOMString status);

interface AsyncOperations {
  void performOperation(AsyncOperationCallback whenFinished);
};

var ops = getAsyncOperations();  // Get an instance of AsyncOperations.

ops.performOperation(function(status) {
  window.alert("Operation finished, status is " + status + ".");
});

2.8. Typedefs

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.

Typedef :
    "typedef" Type identifier ";"

interface Point {
  attribute double x;
  attribute double y;
};

typedef sequence<Point> Points;

interface Widget {
  boolean pointWithinBounds(Point p);
  boolean allPointsWithinBounds(Points ps);
};

2.9. Implements statements

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 supplemental interfaces and those that are not. An interface A is considered to be a supplemental interface of an object O if:

• O implements a different interface B, and the IDL states that B implements A; or

• O implements a different supplemental interface C, and C inherits from A.

interface Window { /* ... */ };
interface SomeFunctionality { /* ... */ };
Window implements SomeFunctionality;

interface Gizmo { /* ... */ };
interface MoreFunctionality { /* ... */ };
SomeFunctionality implements MoreFunctionality;
Gizmo implements SomeFunctionality;

interface Gizmo { /* ... */ };
interface MoreFunctionality { /* ... */ };
Gizmo implements SomeFunctionality;
Gizmo implements MoreFunctionality;

The consequential interfaces of an interface A are:

• each interface B where the IDL states A implements B;

• each interface that a consequential interface of A inherits from; and

• each interface D where the IDL states that 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.

interface A { attribute long x; };
interface B { attribute long x; };
A implements B;  // B::x would clash with A::x

interface C { attribute long y; };
interface D { attribute long y; };
interface E : D { };
C implements E;  // D::y would clash with C::y

interface F { };
interface H { attribute long z; };
interface I { attribute long z; };
F implements H;
F implements I;  // H::z and I::z would clash when mixed in to F

No extended attributes defined in this specification are applicable to implements statements.

ImplementsStatement :
    identifier "implements" identifier ";"

interface Entry {
  readonly attribute unsigned short entryType;
  // ...
};

interface Observable {
  void addEventListener(DOMString type,
                        EventListener listener,
                        boolean useCapture);
  // ...
};

Entry implements Observable;

var e = getEntry();          // Obtain an instance of Entry.
typeof e.addEventListener;  // Evaluates to "function".

2.10. Objects implementing interfaces

In 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:

• objects that implement a non-callback interface;

• objects representing IDL DOMExceptions.

Legacy platform objects are platform objects that implement an interface which does not have a [Global] or [PrimaryGlobal] extended attribute, supports indexed or named properties, and may have one or multiple legacy callers.

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.

2.11. Types

This 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, unrestricted 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.

Type :
    SingleType
    UnionType Null

SingleType :
    NonAnyType
    "any"

UnionType :
    "(" UnionMemberType "or" UnionMemberType UnionMemberTypes ")"

UnionMemberType :
    NonAnyType
    UnionType Null

UnionMemberTypes :
    "or" UnionMemberType UnionMemberTypes
    ε

NonAnyType :
    PrimitiveType Null
    PromiseType Null
    StringType Null
    identifier Null
    "sequence" "<" Type ">" Null
    "object" Null
    "Error" Null
    "DOMException" Null
    BufferRelatedType Null
    "FrozenArray" "<" Type ">" Null
    RecordType Null

PrimitiveType :
    UnsignedIntegerType
    UnrestrictedFloatType
    "boolean"
    "byte"
    "octet"

UnrestrictedFloatType :
    "unrestricted" FloatType
    FloatType

FloatType :
    "float"
    "double"

UnsignedIntegerType :
    "unsigned" IntegerType
    IntegerType

IntegerType :
    "short"
    "long" OptionalLong

OptionalLong :
    "long"
    ε

StringType :
    "ByteString"
    "DOMString"
    "USVString"

PromiseType :
    "Promise" "<" ReturnType ">"

RecordType :
    "record" "<" StringType "," Type ">"

Null :
    "?"
    ε

2.11.1. any

The 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.)

2.11.2. boolean

The 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”.

2.11.3. byte

The 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”.

2.11.4. octet

The 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”.

2.11.5. short

The 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”.

2.11.6. unsigned short

The 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”.

2.11.7. long

The 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”.

2.11.8. unsigned long

The 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”.

2.11.9. long long

The 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”.

2.11.10. unsigned long long

The 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”.

2.11.11. float

The 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”.

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.

2.11.12. unrestricted float

The 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”.

2.11.13. double

The 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”.

2.11.14. unrestricted double

The 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”.

2.11.15. DOMString

The 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 §The DOMString Type, this document defines DOMString to be an intrinsic type so as to avoidspecial 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.

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”.

2.11.16. ByteString

The 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, although ByteString dictionary member and operation optional argument default values can be specified using a string literal.

The type name of the ByteString type is “ByteString”.

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, frozen arrays or Typed Arrays with octet or byte elements should be used for holding 8 bit data rather than ByteString.

2.11.17. USVString

The 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”.

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.

2.11.18. object

The 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”.

2.11.19. Interface types

An 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.

Note: For ECMAScript objects, the callback context is used to hold a reference to the incumbent settings object at the time the Object value is converted to an IDL callback interface type value. See §3.2.13 Interface types.

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.

2.11.20. Dictionary types

An 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.

2.11.21. Enumeration types

An 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.

2.11.22. Callback function types

An 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.

Note: As with callback interface types, the callback context is used to hold a reference to the incumbent settings object at the time an ECMAScript Object value is converted to an IDL callback function type value. See §3.2.16 Callback function types.

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.

2.11.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 or record type as one of its flattened member types.

Note: Although dictionary and record 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”.

interface MyConstants {
  const boolean? ARE_WE_THERE_YET = false;
};

interface Node {
  readonly attribute DOMString? namespaceURI;
  readonly attribute Node? parentNode;
  // ...
};

2.11.24. Sequence types — sequence<T>

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”.

2.11.25. Record types — record<K, V>

A record type is a parameterized type whose values are ordered associative arrays mapping instances of K to instances of V. The (key, value) pairs are called mappings. The order of a record’s mappings is determined when the record value is created. In a specification, a record’s value can be written:

« (key1, value1), (key2, value2), … »

However, there is no way to represent a constant record value in IDL.

K must be one of DOMString, USVString, or ByteString.

Records are always passed by value. In language bindings where a record is represented by an object of some kind, passing a record to a platform object will not result in a reference to the record being kept by that object. Similarly, any record returned from a platform object will be a copy and modifications made to it will not be visible to the platform object.

Records must not be used as the type of an attribute or constant.

The type name of a record type is the concatenation of the type name for K, the type name for V and the string “Record”.

2.11.26. 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”. 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”.

2.11.27. Union types

A 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.

Like the any type, values of union types have a specific type, which is the particular member type that matches the value.

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 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 or record type in its flattened member types.

A type includes a nullable type if:

• the type is a nullable type, or

• the type is a union type and its number of nullable member types is 1.

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”.

2.11.28. Error

The 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”.

2.11.29. DOMException

The 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”.

2.11.30. Buffer source types

There 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.

Note: These types all correspond to classes defined in ECMAScript.

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.

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 §3.2.24 Buffer source types below for how interacting with buffer source types works in the ECMAScript language binding.

We should include an example of specification text that uses these types and terms.

BufferRelatedType :
    "ArrayBuffer"
    "DataView"
    "Int8Array"
    "Int16Array"
    "Int32Array"
    "Uint8Array"
    "Uint16Array"
    "Uint32Array"
    "Uint8ClampedArray"
    "Float32Array"
    "Float64Array"

2.11.31. Frozen array types — FrozenArray<T>

A frozen array type is a parameterized type whose values are references to objects that hold a fixed length array of unmodifiable values. The values in the array are of type T.

Since FrozenArray<T> values are references, they are unlike sequence types, which are lists of values that are passed by value.

There is no way to represent a constant frozen array value in IDL.

The type name of a frozen array type is the concatenation of the type name for T and the string “Array”.

2.12. Extended attributes

An extended attribute is an annotation that can appear on definitions, interface members, namespace 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 §3.3 ECMAScript-specific extended attributes. Each extended attribute definition will state which of the above six forms are allowed.

ExtendedAttributeList :
    "[" ExtendedAttribute ExtendedAttributes "]"
    ε

ExtendedAttributes :
    "," ExtendedAttribute ExtendedAttributes
    ε

ExtendedAttribute :
    "(" ExtendedAttributeInner ")" ExtendedAttributeRest
    "[" ExtendedAttributeInner "]" ExtendedAttributeRest
    "{" ExtendedAttributeInner "}" ExtendedAttributeRest
    Other ExtendedAttributeRest

ExtendedAttributeRest :
    ExtendedAttribute
    ε

ExtendedAttributeInner :
    "(" ExtendedAttributeInner ")" ExtendedAttributeInner
    "[" ExtendedAttributeInner "]" ExtendedAttributeInner
    "{" ExtendedAttributeInner "}" ExtendedAttributeInner
    OtherOrComma ExtendedAttributeInner
    ε

Other :
    integer
    float
    identifier
    string
    other
    "-"
    "-Infinity"
    "."
    "..."
    ":"
    ";"
    "<"
    "="
    ">"
    "?"
    "ByteString"
    "DOMString"
    "FrozenArray"
    "Infinity"
    "NaN"
    "USVString"
    "any"
    "boolean"
    "byte"
    "double"
    "false"
    "float"
    "long"
    "null"
    "object"
    "octet"
    "or"
    "optional"
    "sequence"
    "short"
    "true"
    "unsigned"
    "void"
    ArgumentNameKeyword
    BufferRelatedType

OtherOrComma :
    Other
    ","

IdentifierList :
    identifier Identifiers

ExtendedAttributeNoArgs :
    identifier

ExtendedAttributeArgList :
    identifier "(" ArgumentList ")"

ExtendedAttributeIdent :
    identifier "=" identifier

ExtendedAttributeIdentList :
    identifier "=" "(" IdentifierList ")"

ExtendedAttributeNamedArgList :
    identifier "=" identifier "(" ArgumentList ")"

3. ECMAScript binding

This section describes how definitions written with the IDL defined in §2 Interface definition language 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.

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.

Should define whether @@toStringTag is writable, enumerable and configurable. All @@toStringTag properties in the ES6 spec are non-writable and non-enumerable, and configurable.

If an object is defined to be a function object, then it has characteristics as follows:

• Its [[Prototype]] internal property is %FunctionPrototype% unless otherwise specified.

• Its [[Get]] internal property is set as described in ECMA-262 section 9.1.8.

• Its [[Construct]] internal property is set as described in ECMA-262 section 19.2.2.3.

• Its @@hasInstance property is set as described in ECMA-262 section 19.2.3.8, unless otherwise specified.

The list above needs updating for the latest ES6 draft.

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.

3.1. ECMAScript environment

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:

• interface objects

• named constructors

• interface prototype objects

• named properties objects

• iterator prototype objects

• attribute getters

• attribute setters

• the Function objects that correspond to operations

• the Function objects that correspond to stringifiers

• the Function objects that correspond to serializers

• the Function objects that correspond to iterators

• map size getters

• DOMException constructor objects

• DOMException prototype objects

Each ECMAScript global environment 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.

<!DOCTYPE html>
<title>Different global environments</title>
<iframe id=a></iframe>
<script>
var iframe = document.getElementById("a");
var w = iframe.contentWindow;              // The global object in the frame

Object == w.Object;                        // Evaluates to false, per ECMA-262
Node == w.Node;                            // Evaluates to false
iframe instanceof w.Node;                  // Evaluates to false
iframe instanceof w.Object;                // Evaluates to false
iframe.appendChild instanceof Function;    // Evaluates to true
iframe.appendChild instanceof w.Function;  // Evaluates to false
</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 §3.6 Interfaces 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.

Although at the time of this writing the ECMAScript specification does not reflect this, every ECMAScript object must have an associated Realm. The mechanisms for associating objects with Realms are, for now, underspecified. However, we note that in the case of platform objects, the associated Realm is equal to the object’s relevant Realm, and for non-exotic function objects (i.e. not callable proxies, and not bound functions) the associated Realm is equal to the value of the function object’s [[Realm]] internal slot.

3.2. ECMAScript type mapping

This 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.

3.2.1. any

Since 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:

The undefined value

The IDL value is an object reference to a special object that represents the ECMAScript undefined value.

The null value

The IDL value is the null object? reference.

A Boolean value

The IDL value is the boolean value that represents the same truth value.

A Number value

The IDL value is that which is obtained by following the rules for converting the Number to an IDL unrestricted double value, as described in §3.2.8 unrestricted double.

A String value

The IDL value is that which is obtained by following the rules for converting the String to an IDL DOMString value, as described in §3.2.9 DOMString.

An object value

The IDL value is an object value that references the same object.

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.

3.2.2. void

The 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.

3.2.3. boolean

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.

3.2.4. Integer types

3.2.4.1. byte

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].

3.2.4.2. octet

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].

3.2.4.3. short

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].

3.2.4.4. unsigned short

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].

3.2.4.5. long

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].

3.2.4.6. unsigned long

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].

3.2.4.7. long long

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. If the long long is in the range [−2⁵³ + 1, 2⁵³ − 1], then the Number will be able to represent exactly the same value as the long long.

3.2.4.8. unsigned long long

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. If the unsigned long long is less than or equal to 2⁵³ − 1, then the Number will be able to represent exactly the same value as the unsigned long long.

3.2.4.9. Abstract operations

3.2.5. float

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.

3.2.6. unrestricted float

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.

3.2.7. double

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.

3.2.8. unrestricted double

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.

3.2.9. DOMString

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.

3.2.10. ByteString

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.

3.2.11. USVString

3.2.12. object

IDL object values are represented by ECMAScript Object values.

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.

3.2.13. Interface types

IDL interface type values are represented by ECMAScript Object or Function values.

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.

3.2.14. Dictionary types

IDL dictionary type values are represented by ECMAScript Object values. Properties on the object (or its prototype chain) correspond to dictionary members.

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.