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
This specification defines an IDL language similar to OMG IDL +for use by specifications that define interfaces for Web APIs. A number of extensions are +given to the IDL to support common functionality that previously must +have been written in prose. In addition, precise language bindings +for ECMAScript Edition 6 are given.
+1.1. Typographic conventions
+The following typographic conventions are used in this document:
+-
+
-
+
Defining instances of terms: example term
+ -
+
Links to terms defined in this document or elsewhere: example term
+ -
+
Grammar terminals:
+sometoken -
+
Grammar non-terminals:
+ExampleGrammarNonTerminal -
+
Grammar symbols:
+identifier -
+
IDL and ECMAScript types:
+ExampleType -
+
Code snippets:
+a = b + obj.f() -
+
Unicode characters: U+0030 DIGIT ZERO ("0")
+ -
+
Extended attributes: [
+ExampleExtendedAttribute] -
+
Variable names in prose and algorithms: exampleVariableName.
+ -
+
Algorithms use the conventions of the ECMAScript specification, +including the ! and ? notation for unwrapping completion records.
+ -
+
IDL informal syntax examples:
+interface identifier { + /* interface_members... */ }; - -interface Pattern : Paint { - attribute DOMString imageURL; +
+(Specific parts of the syntax discussed in surrounding prose are highlighted.)
+ -
+
IDL grammar snippets:
+ExampleGrammarNonTerminal : + OtherNonTerminal "sometoken" + other AnotherNonTerminal + ε // nothing +
+ -
+
Non-normative notes:
+Note: This is a note.
+ -
+
Non-normative examples:
+ + -
+
Normative warnings:
+This is a warning.
+ -
+
Code blocks:
+// This is an IDL code block. +interface Example { + attribute long something; }; - -[Constructor] -interface GraphicalWindow { - readonly attribute unsigned long width; - readonly attribute unsigned long height; - - attribute Paint currentPaint; - - void drawRectangle(double x, double y, double width, double height); - - void drawText(double x, double y, DOMString text); -};
-- Here, four interfaces - are being defined. - The GraphicalWindow interface has two - read only attributes, - one writable attribute, and two operations - defined on it. Objects that implement the GraphicalWindow interface - will expose these attributes and operations in a manner appropriate to the - particular language being used. -
-- In ECMAScript, the attributes on the IDL interfaces will be exposed as accessor - properties and the operations as Function-valued - data properties on a prototype object for all GraphicalWindow - objects; each ECMAScript object that implements GraphicalWindow - will have that prototype object in its prototype chain. -
- -- The [Constructor] that appears on GraphicalWindow - is an extended attribute. - This extended attribute causes a constructor to exist in ECMAScript implementations, - so that calling
- - -new GraphicalWindow()would return a new object - that implemented the interface. --- -3.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- orcallbackkeyword - 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 { enumeration-values… }; -callback callback-identifier = callback-signature;-
- -
- 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; ++// This is an ECMAScript code block. +window.onload = function() { window.alert("loaded"); };
+
2. Conformance
+Everything in this specification is normative except for diagrams, +examples, notes and sections marked as being informative.
+The keywords “must”, +“must not”, +“required”, +“shall”, +“shall not”, +“should”, +“should not”, +“recommended”, +“may” and +“optional” in this document are to be +interpreted as described in Key words for use in RFCs to +Indicate Requirement Levels [RFC2119].
+The following conformance classes are defined by this specification:
+-
+
-
+
conforming set of IDL fragments
+ -
+
A set of IDL fragments is considered +to be a conforming set of IDL fragments if, taken together, they satisfy all of the +must-, +required- and shall-level +criteria in this specification that apply to IDL fragments.
+ -
+
conforming implementation
+ -
+
A user agent is considered to be a conforming implementation relative to a conforming set of IDL fragments if it satisfies all of the must-, +required- and shall-level +criteria in this specification that apply to implementations for all language +bindings that the user agent supports.
+ -
+
conforming ECMAScript implementation
+ -
+
A user agent is considered to be a conforming ECMAScript implementation relative to a conforming set of IDL fragments if it satisfies all of the must-, +required- and shall-level +criteria in this specification that apply to implementations for the ECMAScript +language binding.
+
2.1. Conformant Algorithms
+Requirements phrased in the imperative as part of algorithms (such as +“strip any leading space characters” or “return false and abort these +steps”) are to be interpreted with the meaning of the key word (“must”, +“should”, “may”, etc) used in introducing the algorithm.
+Conformance requirements phrased as algorithms or specific steps can be +implemented in any manner, so long as the end result is equivalent. In +particular, the algorithms defined in this specification are intended to +be easy to understand and are not intended to be performant. Implementers +are encouraged to optimize.
+3. 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 (matchingExtendedAttributeList ), +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 §3.12 Extended attributes, +while those specific to the ECMAScript language binding are discussed +in §4.3 ECMAScript-specific extended attributes.[extended_attributes] +interface identifier { + /* interface_members... */ }; - -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 = value;
-- - 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. -
- -return-type operation-identifier(arguments…);
--Note-- Operations can have no identifier when they are being used to declare a - special kind of operation, such as a getter or setter. -
-- For all of these constructs, the identifier - is the value of the identifier token with any leading - U+005F LOW LINE ("_") character (underscore) removed. -
--Note-- A leading "_" is used to escape an identifier from looking - like a reserved word so that, for example, an interface named “interface” can be - defined. The leading "_" is dropped to unescape the - identifier. -
-- Operation arguments can take a slightly wider set of identifiers. In an operation - declaration, the identifier of an argument is specified immediately after its - type and is given by either an identifier - token or by one of the keywords that match the ArgumentNameKeyword - symbol. If one of these keywords is used, it need not be escaped with a leading - underscore. -
-return-type operation-identifier(argument-type argument-identifier, …);
-
-[71] ArgumentNameKeyword → - "attribute"
| - "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. -
-- -Example-Therefore, the following IDL fragment is valid:
-- -IDL-
+interface B : A { - void f(SequenceOfLongs x); +Definitions : + ExtendedAttributeList Definition Definitions + ε +
+Definition : + CallbackOrInterface + Namespace + Partial + Dictionary + Enum + Typedef + ImplementsStatement +
+CallbackOrInterface : + "callback" CallbackRestOrInterface + Interface +
++ +The following is an example of an IDL fragment.
+interface Paint { }; + +interface SolidColor : Paint { + attribute double red; + attribute double green; + attribute double blue; }; - -interface A { + +interface Pattern : Paint { + attribute DOMString imageURL; }; - -typedef sequence<long> SequenceOfLongs;
-Example-- The following IDL fragment - demonstrates how identifiers - are given to definitions and interface members. -
--IDL// 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); + +[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); }; - -// Interface identifier: "TextField" -interface TextField { - - // Attribute identifier: "const" - attribute boolean _const; - - // Attribute identifier: "value" - attribute DOMString? _value; -};- Note that while the second attribute - on the TextField interface - need not have been escaped with an underscore (because “value” is - not a keyword in the IDL grammar), it is still unescaped - to obtain the attribute’s identifier. -
---3.2. 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. -
--Example-- Consider the following two interfaces. -
-IDL+
+interface A { - void f(); - void g(); +Here, four interfaces are being defined. + The
+GraphicalWindowinterface has two read only attributes, + one writable attribute, and two operations defined on it. Objects that implement theGraphicalWindowinterface + will expose these attributes and operations in a manner appropriate to the + particular language being used.In ECMAScript, the attributes on the IDL interfaces will be exposed as accessor + properties and the operations as
+Function -valued + data properties on a prototype object for allGraphicalWindowobjects; each ECMAScript object that implementsGraphicalWindowwill have that prototype object in its prototype chain.The [
+Constructor] that appears onGraphicalWindowis an extended attribute. + This extended attribute causes a constructor to exist in ECMAScript implementations, + so that callingnew GraphicalWindow()would return a new object + that implemented the interface.3.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 theinterface,namespace,dictionary,enumorcallbackkeyword +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; }; - -interface B : A { - void f(); - void g(DOMString x); -};
- In the ECMAScript language binding, an instance of B - will have a prototype chain that looks like the following: -
-[Object.prototype: the Object prototype object] - ↑ - [A.prototype: interface prototype object for A] - ↑ - [B.prototype: interface prototype object for B] - ↑ - [instanceOfB]
-- Calling
- -instanceOfB.f()in ECMAScript will invoke the f defined - on B. However, the f from A - can still be invoked on an object that implements B by - callingA.prototype.f.call(instanceOfB). -- The inherited interfaces of - a given interface A is the set of all interfaces that A - inherits from, directly or indirectly. If A does not inherit - from another interface, then the set is empty. Otherwise, the set - includes the interface B that A inherits - from and all of B’s inherited interfaces. -
-- An interface MUST NOT be declared such that - its inheritance hierarchy has a cycle. That is, an interface - A cannot inherit from itself, nor can it inherit from another - interface B that inherits from A, and so on. -
-- Note that general multiple inheritance of interfaces is not supported, and - objects also cannot implement arbitrary sets of interfaces. - Objects can be defined to implement a single given interface A, - which means that it also implements all of A’s - inherited interfaces. In addition, - an implements statement can be - used to define that objects implementing an interface will always - also implement another interface. -
-- Each interface member can be preceded by a list of extended attributes (matching - ExtendedAttributeList), - which can control how the interface member will be handled in language bindings. -
-interface identifier { - - [extended-attributes] - const type identifier = value; - - [extended-attributes] - attribute type identifier; - - [extended-attributes] - return-type identifier(arguments…); -};- -- A callback interface is - an interface - that uses the
-callbackkeyword at the start of - its definition. Callback interfaces are ones that can be - implemented by user objects - and not by platform objects, - as described in section 3.10 - below. -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. -
--Warning-- Specification authors SHOULD NOT define - callback interfaces - that have only a single operation, - unless required to describe the requirements of existing APIs. - Instead, a callback function SHOULD be used. -
-- The definition of EventListener as a - callback interface - is an example of an existing API that needs to allow - user objects with a - given property (in this case “handleEvent”) to be considered to implement the interface. - For new APIs, and those for which there are no compatibility concerns, - using a callback function will allow - only a Function object (in the ECMAScript - language binding). -
--Editorial note-- 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. -
-- -Editorial note-- 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. -
-- -Note-- Specification authors wanting to define APIs that take ECMAScript objects - as “property bag” like function arguments are suggested to use - dictionary types rather than - callback interfaces. -
-- For example, instead of this: -
--IDLcallback interface Options { - attribute DOMString? option1; - attribute DOMString? option2; - attribute long? option3; + +typedef type typedef_identifier; + +dictionary identifier { + type dictionary_member_identifier; }; - -interface A { - void doTask(DOMString type, Options options); -};- to be used like this: -
--ECMAScriptvar a = getA(); // Get an instance of A. - -a.doTask("something", { option1: "banana", option3: 100 });- instead write the following: -
--IDL
+dictionary Options { - DOMString? option1; - DOMString? option2; - long? option3; +- +
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 theOptionalIdentifier grammar symbol in anOperationRest ) determines the identifier of the operation. If +there is no suchidentifier token, +then the operation does not have an identifier.interface interface_identifier { + return_type operation_identifier(/* arguments... */); }; - -interface A { - void doTask(DOMString type, Options options); -};
- The IDL for interfaces can be split into multiple parts by using - partial interface definitions - (matching "partial" PartialInterface). - The identifier of a partial - interface definition MUST be the same - as the identifier of an interface definition. All of - the members that appear on each of the partial interfaces are considered to be - members of the interface itself. -
-interface SomeInterface { - interface-members… ++ +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 theArgumentNameKeyword 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 /* , ... */); }; - -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], - [ImplicitThis], - - [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], - [SecureContext] and - [Unforgeable].
-- 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], - [ImplicitThis], - - [LegacyArrayClass], - [NamedConstructor], - [NoInterfaceObject], - [OverrideBuiltins], - [PrimaryGlobal], - [SecureContext], - [Unforgeable]. -
- -
- -[3] CallbackOrInterface → "callback" CallbackRestOrInterface
| - Interface[4] CallbackRestOrInterface → CallbackRest
| - Interface[5] Interface → "interface" identifier Inheritance "{" InterfaceMembers "}" ";" [6] Partial → "partial" PartialDefinition [7] PartialDefinition → PartialInterface
| - PartialDictionary
| - Namespace[8] PartialInterface → "interface" identifier "{" InterfaceMembers "}" ";" [9] InterfaceMembers → ExtendedAttributeList InterfaceMember InterfaceMembers
| - ε[10] InterfaceMember → Const
| - Operation
| - Serializer
| - Stringifier
| - StaticMember
| - Iterable
| - ReadOnlyMember
| - ReadWriteAttribute
| - ReadWriteMaplike
| - ReadWriteSetlike[18] Inheritance → ":" identifier
| - ε- -Example- -- The following IDL fragment - demonstrates the definition of two mutually referential interfaces. - Both Human and Dog - inherit from Animal. Objects that implement - either of those two interfaces will thus have a
-nameattribute. -- -IDL-
+interface Animal { - attribute DOMString name; +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 theArgumentNameKeyword 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.
++ +Therefore, the following IDL fragment is valid:
+interface B : A { + void f(SequenceOfLongs x); }; - -interface Human : Animal { - attribute Dog? pet; + +interface A { }; - -interface Dog : Animal { - attribute Human? owner; -};
-Example-- The following IDL fragment defines - simplified versions of a few DOM interfaces, one of which - is a callback interface. -
--IDL+
+interface Node { - readonly attribute DOMString nodeName; - readonly attribute Node? parentNode; - Node appendChild(Node newChild); - void addEventListener(DOMString type, EventListener listener); + +typedef sequence<long> SequenceOfLongs; ++ +The following IDL fragment demonstrates how identifiers are given to definitions and interface members.
+// 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); }; - -callback interface EventListener { - void handleEvent(Event event); -};
- Since the EventListener interface is annotated - callback interface, user objects - can implement it: -
--ECMAScriptvar node = getNode(); // Obtain an instance of Node. - -var listener = { - handleEvent: function(event) { - ... - } + +// Interface identifier: "TextField" +interface TextField { + + // Attribute identifier: "const" + attribute boolean _const; + + // Attribute identifier: "value" + attribute DOMString? _value; }; -node.addEventListener("click", listener); // This works. - -node.addEventListener("click", function() { ... }); // As does this.- It is not possible for a user object to implement Node, however: -
-ECMAScript+
+var node = getNode(); // Obtain an instance of Node. - -var newNode = { - nodeName: "span", - parentNode: null, - appendChild: function(newchild) { - ... - }, - addEventListener: function(type, listener) { - ... - } +Note that while the second attribute on the
+TextFieldinterface need not have been escaped with an underscore (because “value” is + not a keyword in the IDL grammar), it is still unescaped + to obtain the attribute’s identifier.3.2. 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 orcallback Interface ) that declares some +state and behavior that an object implementing that interface will expose.interface identifier { + /* interface_members... */ }; -node.appendChild(newNode); // This will throw a TypeError exception.
-- -3.2.1. Constants
- -- A constant is a declaration (matching - Const) used to bind a constant value to a name. - Constants can appear on interfaces. -
--Warning-- Constants have in the past primarily been used to define - named integer codes in the style of an enumeration. The Web platform - is moving away from this design pattern in favor of the use of strings. - Specification authors who wish to define constants are strongly advised to discuss - this on the public-script-coord@w3.org - mailing list before proceeding. -
-const type identifier = value;
-- The identifier of a - constant - MUST NOT be the same as the identifier - of another interface member - defined on the same interface. - The identifier also MUST NOT - be “length”, “name” or “prototype”. -
--Note-- These three names are the names of properties that exist on all - Function objects. -
-- The type of a constant (matching ConstType) - MUST NOT be any type other than - a primitive type - or a nullable primitive type. - If an identifier is used, - it MUST reference a typedef - whose type is a primitive type or a nullable primitive type. -
-- The ConstValue part of a - constant declaration gives the value of the constant, which can be - one of the two boolean literal tokens (
-true- andfalse), - thenulltoken, an - integer token, - a float token, - or one of the three special floating point constant values - (-Infinity,InfinityandNaN). --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
-trueand -falseare the IDL boolean values - true and false. -- The value of an integer token is an integer - whose value is determined as follows: -
--
-
- Let S be the sequence of characters matched by the integer token. -
- Let sign be −1 if S begins with U+002D HYPHEN-MINUS ("-"), and 1 otherwise. -
- Let base be the base of the number based on the characters that follow the optional leading U+002D HYPHEN-MINUS ("-") character:
-
-
-
- U+0030 DIGIT ZERO ("0"), U+0058 LATIN CAPITAL LETTER X ("X") -
- U+0030 DIGIT ZERO ("0"), U+0078 LATIN SMALL LETTER X ("x") -
- The base is 16. -
- U+0030 DIGIT ZERO ("0") -
- The base is 8. -
- Otherwise -
- The base is 10. -
- - Let number be the result of interpreting all remaining characters following the optional leading U+002D HYPHEN-MINUS ("-") - character and any characters indicating the base as an integer specified in base base. -
- Return sign × number. -
- The type of an integer token is the same - as the type of the constant, dictionary member or optional argument it is being used as the value of. - The value of the integer token MUST NOT - lie outside the valid range of values for its type, as given in - section 3.11 below. -
-- The value of a float token is - either an IEEE 754 single-precision floating point number or an IEEE 754 - double-precision floating point number, depending on the type of the - constant, dictionary member or optional argument it is being used as the value for, determined as follows: -
--
-
- Let S be the sequence of characters matched by the float token. -
- Let value be the Mathematical Value that would be obtained if S were - parsed as an ECMAScript NumericLiteral ([ECMA-262], section 11.8.3). -
- - If the float token is being - used as the value for a float or - unrestricted float, then - the value of the float token - is the IEEE 754 single-precision floating point number closest to - result. Otherwise, the float token is being - used as the value for a double or - unrestricted double, and - the value of the float token - is the IEEE 754 double-precision floating point number closest to - result. - [IEEE-754] - -
- The value of a constant value specified as -
-Infinity,-InfinityorNaNis 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 - section 3.11 below. - Also,
-Infinity,-InfinityandNaNMUST NOT - be used as the value of a float - or double. -- The value of the
-nulltoken is the special - null value that is a member of the - nullable types. The type of - thenulltoken is the same as the - type of the constant, dictionary member or optional argument it is being used as the value of. -- If VT is the type of the value assigned to a constant, and DT - is the type of the constant, dictionary member or optional argument itself, then these types MUST - be compatible, which is the case if DT and VT are identical, - or DT is a nullable type - whose inner type is VT. -
-- Constants are not associated with - particular instances of the interface - on which they appear. It is language binding specific whether - constants are exposed on instances. -
--Note-- - The ECMAScript language binding does however - allow constants to be accessed - through objects implementing the IDL interfaces - on which the constants are declared. - For example, with the following IDL: -
--IDLinterface A { - const short rambaldi = 47; -};- the constant value can be accessed in ECMAScript either as -
-A.rambaldiorinstanceOfA.rambaldi. -- The following extended attributes are applicable to constants: - [Exposed], - [SecureContext]. -
- -
-[26] Const → "const" ConstType identifier "=" ConstValue ";" [27] ConstValue → BooleanLiteral
| - FloatLiteral
| - integer
| - "null"[28] BooleanLiteral → "true"
| - "false"[29] FloatLiteral → float
| - "-Infinity"
| - "Infinity"
| - "NaN"[80] ConstType → PrimitiveType Null
| - identifier Null-Example-- The following IDL fragment - demonstrates how constants - of the above types can be defined. -
--IDLinterface Util { - const boolean DEBUG = false; - const octet LF = 10; - const unsigned long BIT_MASK = 0x0000fc00; - const double AVOGADRO = 6.022e23; -};-- -3.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: -
--
-
- regular attributes, which are those
- used to declare that objects implementing the interface
- will have a data field member with the given identifier
-
attribute type identifier;
- - static attributes, which are used
- to declare attributes that are not associated with a particular object implementing the interface
-
static attribute type identifier;
-
- If an attribute has no
-statickeyword, 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
-attributekeyword. - 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 -
- a union type - that has a nullable or non-nullable sequence type or dictionary - as one of its flattened member types -
- The attribute is read only if the -
-readonlykeyword is used before theattributekeyword. - An object that implements the interface on which a read only attribute - is defined will not allow assignment to that attribute. It is language - binding specific whether assignment is simply disallowed by the language, - ignored or an exception is thrown. -readonly attribute type identifier;
-- A regular attribute - that is not read only - can be declared to inherit its getter - from an ancestor interface. This can be used to make a read only attribute - in an ancestor interface be writable on a derived interface. An attribute - inherits its getter if - its declaration includes
-inheritin 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, andinherit- MUST NOT appear on a read only - attribute or a static attribute. -interface Ancestor { - readonly attribute TheType theIdentifier; ++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... */ }; - -interface Derived : Ancestor { - inherit attribute TheType theIdentifier; -};
- -- When the
-stringifierkeyword is used - in a regular attribute - declaration, it indicates that objects implementing the - interface will be stringified to the value of the attribute. See - section 3.2.4.2 - below for details. -stringifier attribute DOMString identifier;
-- If an implementation attempts to get or set the value of an - attribute on a - user object - (for example, when a callback object has been supplied to the implementation), - and that attempt results in an exception being thrown, then, unless otherwise specified, that - exception will be propagated to the user code that caused the - implementation to access the attribute. Similarly, if a value - returned from getting the attribute cannot be converted to - an IDL type, then any exception resulting from this will also - be propagated to the user code that resulted in the implementation - attempting to get the value of the attribute. -
- -- The following extended attributes - are applicable to regular and static attributes: - [Clamp], - [EnforceRange], - [Exposed], - [SameObject], - [SecureContext], - [TreatNullAs]. -
- -- The following extended attributes - are applicable only to regular attributes: - [LenientSetter], - [LenientThis], - [PutForwards], - [Replaceable], - [Unforgeable]. -
- -
- -[39] ReadOnlyMember → "readonly" ReadOnlyMemberRest [40] ReadOnlyMemberRest → AttributeRest
| - ReadWriteMaplike
| - ReadWriteSetlike[41] ReadWriteAttribute → "inherit" ReadOnly AttributeRest
| - AttributeRest[42] AttributeRest → "attribute" Type AttributeName ";" [43] AttributeName → AttributeNameKeyword
| - identifier[44] AttributeNameKeyword → "required" [45] Inherit → "inherit"
| - ε[46] ReadOnly → "readonly"
| - ε-Example-- The following IDL fragment - demonstrates how attributes - can be declared on an interface: -
--IDLinterface 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 B : A { + void f(); + void g(DOMString x); }; - -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; -};-- -3.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: -
--
-
- regular operations, which
- are those used to declare that objects implementing the
- interface will have a method with
- the given identifier
-
return-type identifier(arguments…);
- - special operations,
- which are used to declare special behavior on objects
- implementing the interface, such as object indexing and stringification
-
special-keywords… return-type identifier(arguments…); -special-keywords… return-type (arguments…);
- - static operations,
- which are used to declare operations that are not associated with
- a particular object implementing the interface
-
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 - thestringifierkeyword), - then it declares a special operation. A single operation can declare - both a regular operation and a special operation; see - section 3.2.4 below - 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
-voidindicates that the operation returns no value. - If the return type is an - identifier followed by?, - then the identifier MUST - identify an interface, dictionary, enumeration, - callback function or typedef. -- An operation’s arguments (matching ArgumentList) - are given between the parentheses in the declaration. Each individual argument is specified - as a type (matching Type) followed by an identifier - (matching ArgumentName). -
--Note-For expressiveness, the identifier of an operation argument can also be specified - as one of the keywords matching the ArgumentNameKeyword - symbol without needing to escape it.
-- If the Type of an operation argument is an identifier - followed by
-?, - then the identifier MUST identify an interface, - enumeration, callback function - or typedef. - If the operation argument type is an identifier - not followed by?, then the identifier MUST - identify any one of those definitions or a dictionary. -return-type identifier(type identifier, type identifier, …);
-- The identifier of each argument MUST NOT be the same - as the identifier of another argument in the same operation declaration. -
-- Each argument can be preceded by a list of - extended attributes (matching - ExtendedAttributeList), - which can control how a value passed as the argument will be handled in - language bindings. -
-return-type identifier([extended-attributes] type identifier, [extended-attributes] type identifier, …);
- --Example-- The following IDL fragment - demonstrates how regular operations - can be declared on an interface: -
-IDL+
+interface Dimensions { - attribute unsigned long width; - attribute unsigned long height; +In the ECMAScript language binding, an instance of
+Bwill have a prototype chain that looks like the following:[Object.prototype: the Object prototype object] + ↑ +[A.prototype: interface prototype object for A] + ↑ +[B.prototype: interface prototype object for B] + ↑ +[instanceOfB] +
+Calling
+instanceOfB.f()in ECMAScript will invoke the f defined + onB. However, the f fromAcan still be invoked on an object that implementsBby + callingA.prototype.f.call(instanceOfB).The inherited interfaces of +a given interface A is the set of all interfaces that A inherits from, directly or indirectly. If A does not inherit from another interface, then the set is empty. Otherwise, the set +includes the interface B that A inherits from and all of B’s inherited interfaces.
+An interface must not be declared such that +its inheritance hierarchy has a cycle. That is, an interface A cannot inherit from itself, nor can it inherit from another +interface B that inherits from A, and so on.
+Note that general multiple inheritance of interfaces is not supported, and +objects also cannot implement arbitrary sets of interfaces. +Objects can be defined to implement a single given interface A, +which means that it also implements all of A’s inherited interfaces. In addition, +an implements statement can be +used to define that objects implementing an interface will always +also implement another interface.
+Each interface member can be preceded by a list of extended attributes (matching
+ExtendedAttributeList ), +which can control how the interface member will be handled in language bindings.interface identifier { + + [extended_attributes] + const type constant_identifier = 42; + + [extended_attributes] + attribute type identifier; + + [extended_attributes] + return_type identifier(/* arguments... */); }; - -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. -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. -- -Example-- The following IDL fragment defines an interface that has - two variadic operations: -
--IDLinterface IntegerSet { - readonly attribute unsigned long cardinality; - - void union(long... ints); - void intersection(long... ints); -};- In the ECMAScript binding, variadic operations are implemented by - functions that can accept the subsequent arguments: -
--ECMAScriptvar 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'.- A binding for a language that does not support variadic functions - might specify that an explicit array or list of integers be passed - to such an operation. -
-- An argument is considered to be an optional argument - if it is declared with the
-optionalkeyword. - The final argument of a variadic operation - is also considered to be an optional argument. Declaring an argument - to be optional indicates that the argument value can be omitted - when the operation is invoked. The final argument in an - operation MUST NOT explicitly be declared to be - optional if the operation is variadic. -return-type identifier(type identifier, optional type identifier);
- -- Optional arguments can also have a default value - specified. If the argument’s identifier is followed by a U+003D EQUALS SIGN ("=") - and a value (matching DefaultValue), - then that gives the optional argument its default value. - The implicitly optional final argument of a variadic - operation MUST NOT have a default value specified. - The default value is the value to be assumed when the operation is called with the - corresponding argument omitted. -
-return-type identifier(type identifier, optional type identifier = value);
--Warning-- It is strongly suggested not to use default value - of true for boolean-typed arguments, - as this can be confusing for authors who might otherwise expect the default - conversion of undefined to be used (i.e., false). -
-- If the type of an argument is a dictionary type - or a union type that has a - dictionary type as one of its flattened member types, - and that dictionary type and its ancestors have no required members, - and the argument is either the final argument or is followed only by - optional arguments, then - the argument MUST be specified as optional. - Such arguments are always considered to have a - default value of an empty dictionary, - unless otherwise specified. -
--Note-- This is to encourage API designs that do not require authors to pass an - empty dictionary value when they wish only to use the dictionary’s - default values. -
-- Dictionary types cannot have a default value specified explicitly, so the - “unless otherwise specified” clause above can only be invoked for - a union type that has a - dictionary type as one of its flattened member types. -
-- When a boolean literal token (
-trueorfalse), - thenulltoken, - an integer token, a - float token or one of - the three special floating point literal values (Infinity, --InfinityorNaN) is used as the - default value, - it is interpreted in the same way as for a constant. -- Optional argument default values can also be specified using a string - token, whose value is a string type - determined as follows: -
--
-
- Let S be the sequence of Unicode scalar values matched by the string token with its leading and trailing U+0022 QUOTATION MARK ('"') characters removed. -
- Depending on the type of the argument:
-
-
-
- DOMString -
- an enumeration type -
- The value of the string token is the sequence of 16 bit unsigned integer code units (hereafter referred to just as code units) corresponding to the UTF-16 encoding of S. -
- ByteString -
- The value of the string token is the sequence of 8 bit unsigned integer code units corresponding to the UTF-8 encoding of S. -
- USVString -
- The value of the string token is S. -
-
- 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. -- - -Example-- The following IDL fragment - defines an interface - with a single operation - that can be invoked with two different argument list lengths: -
--IDLinterface ColorCreator { - object createColor(double v1, double v2, double v3, optional double alpha); -};- It is equivalent to an interface - that has two overloaded - operations: -
--IDLinterface 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]. -
- -
-[17] DefaultValue → ConstValue
| - string
| - "[" "]"[47] Operation → ReturnType OperationRest
| - SpecialOperation[48] SpecialOperation → Special Specials ReturnType OperationRest [49] Specials → Special Specials
| - ε[50] Special → "getter"
| - "setter"
| - "deleter"
| - "legacycaller"[51] OperationRest → OptionalIdentifier "(" ArgumentList ")" ";" [52] OptionalIdentifier → identifier
| - ε[53] ArgumentList → Argument Arguments
| - ε[54] Arguments → "," Argument Arguments
| - ε[55] Argument → ExtendedAttributeList OptionalOrRequiredArgument [56] OptionalOrRequiredArgument → "optional" Type ArgumentName Default
| - Type Ellipsis ArgumentName[57] ArgumentName → ArgumentNameKeyword
| - identifier[58] Ellipsis → "..."
| - ε[71] ArgumentNameKeyword → - "attribute"
| - "callback"
| - "const"
| - "deleter"
| - "dictionary" -
| - "enum"
| - "getter"
| - "implements"
| - "inherit"
| - "interface"
| - "iterable" -
| - "legacycaller"
| - "maplike"
| - "namespace"
| - "partial"
| - "required" -
| - "serializer"
| - "setlike"
| - "setter"
| - "static"
| - "stringifier" -
| - "typedef"
| - "unrestricted" -[89] ReturnType → Type
| - "void"-- -3.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: -
--
-- -Special operation -Keyword -Purpose -- -Getters -getterDefines behavior for when an object is indexed for property retrieval. -- -Setters -setterDefines behavior for when an object is indexed for property - assignment or creation. -- -Deleters -deleterDefines behavior for when an object is indexed for property deletion. -- -Legacy callers -legacycallerDefines behavior for when an object is called as if it were a function. -- -Stringifiers -stringifierDefines how an object is converted into a DOMString. -- -Serializers -serializerDefines how an object is converted into a serialized form. -- Not all language bindings support all of the six kinds of special - object behavior. When special operations are declared using - operations with no identifier, then in language bindings that do - not support the particular kind of special operations there simply - will not be such functionality. -
-- -Example-The following IDL fragment defines an interface with a getter and a setter:
--IDLinterface Dictionary { - readonly attribute unsigned long propertyCount; - - getter double (DOMString propertyName); - setter void (DOMString propertyName, double propertyValue); -};In language bindings that do not support property getters and setters, - objects implementing Dictionary will not - have that special behavior.
-- Defining a special operation with an identifier - is equivalent to separating the special operation out into its own - declaration without an identifier. This approach is allowed to - simplify prose descriptions of an interface’s operations. -
-- -Example-The following two interfaces are equivalent:
--IDLinterface Dictionary { - readonly attribute unsigned long propertyCount; - - getter double getProperty(DOMString propertyName); - setter void setProperty(DOMString propertyName, double propertyValue); -};-IDLinterface Dictionary { - readonly attribute unsigned long propertyCount; - - double getProperty(DOMString propertyName); - void setProperty(DOMString propertyName, double propertyValue); - - getter double (DOMString propertyName); - setter void (DOMString propertyName, double propertyValue); -};- A given special keyword MUST NOT - appear twice on an operation. -
-- Getters and setters come in two varieties: ones that - take a DOMString as a property name, - known as - named property getters and - named property setters, - and ones that take an unsigned long - as a property index, known as - indexed property getters and - indexed property setters. - There is only one variety of deleter: - named property deleters. - See section 3.2.4.4 - and section 3.2.4.5 - for details. -
-- On a given interface, - there MUST exist at most one - stringifier, at most one serializer, at most one - named property deleter, - and at most one of each variety of getter and setter. - Multiple legacy callers can exist on an interface - to specify overloaded calling behavior. -
-- If an interface has a setter of a given variety, - then it MUST also have a getter of that - variety. If it has a named property deleter, - then it MUST also have a - named property getter. -
-- Special operations declared using operations MUST NOT - be variadic nor have any - optional arguments. -
-- Special operations MUST NOT be declared on - callback interfaces. -
-- If an object implements more than one interface - that defines a given special operation, then it is undefined which (if any) - special operation is invoked for that operation. -
- --- -3.2.4.1. Legacy 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
-legacycallerkeyword. -legacycaller return-type identifier(arguments…); -legacycaller return-type (arguments…);
-- If multiple legacy callers are specified on an interface, overload resolution - is used to determine which legacy caller is invoked when the object is called - as if it were a function. -
-- Legacy callers MUST NOT be defined to return a - promise type. -
-- -Warning-- Legacy callers are universally recognised as an undesirable feature. They exist - only so that legacy Web platform features can be specified. Legacy callers - SHOULD NOT be used in specifications unless required to - specify the behavior of legacy APIs, and even then this should be discussed on - the public-script-coord@w3.org - mailing list before proceeding. -
--Example-- The following IDL fragment - defines an interface - with a legacy caller. -
--IDLinterface NumberQuadrupler { - // This operation simply returns four times the given number x. - legacycaller double compute(double x); -};- An ECMAScript implementation supporting this interface would - allow a platform object - that implements NumberQuadrupler - to be called as a function: -
--ECMAScriptvar f = getNumberQuadrupler(); // Obtain an instance of NumberQuadrupler. - -f.compute(3); // This evaluates to 12. -f(3); // This also evaluates to 12.-- -3.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
-stringifierkeyword. -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
-stringifierkeyword - is declared using an operation with no identifier, then the - operation’s return type and - argument list can be omitted. -stringifier;
--Example-The following two interfaces are equivalent:
--IDLinterface A { - stringifier DOMString (); -};-IDLinterface A { - stringifier; -};- The
-stringifierkeyword - can also be placed on an attribute. - In this case, the string to convert the object to is the - value of the attribute. Thestringifierkeyword - MUST NOT be placed on an attribute unless - it is declared to be of type DOMString or USVString. - It also MUST NOT be placed on - a static attribute. -stringifier attribute DOMString identifier;
- -
- -[35] Stringifier → "stringifier" StringifierRest [36] StringifierRest → ReadOnly AttributeRest
| - ReturnType OperationRest
| - ";"-Example-- The following IDL fragment - defines an interface that will stringify to the value of its - name attribute: -
--IDL[Constructor] -interface Student { - attribute unsigned long id; - stringifier attribute DOMString name; -};- In the ECMAScript binding, using a Student - object in a context where a string is expected will result in the - value of the object’s “name” property being - used: -
--ECMAScriptvar s = new Student(); -s.id = 12345678; -s.name = '周杰倫'; - -var greeting = 'Hello, ' + s + '!'; // Now greeting == 'Hello, 周杰倫!'.- The following IDL fragment - defines an interface that has custom stringification behavior that is - not specified in the IDL itself. -
--IDL[Constructor] -interface Student { - attribute unsigned long id; - attribute DOMString? familyName; - attribute DOMString givenName; - - stringifier DOMString (); -};- Thus, prose is required to explain the stringification behavior, such - as the following paragraph: -
--
-- Objects that implement the Student - interface must stringify as follows. If the value of the - familyName attribute is - null, the stringification of the - object is the value of the givenName - attribute. Otherwise, if the value of the - familyName attribute is not null, - the stringification of the object is the concatenation of the - value of the givenName attribute, - a single space character, and the value of - the familyName attribute. -
-- An ECMAScript implementation of the IDL would behave as follows: -
--ECMAScriptvar s = new Student(); -s.id = 12345679; -s.familyName = 'Smithee'; -s.givenName = 'Alan'; - -var greeting = 'Hi ' + s; // Now greeting == 'Hi Alan Smithee'.-- -3.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
-serializerkeyword: -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
-toJSONmethod which returns the - serialized value converted - into an ECMAScript value that can be serialized to JSON by the -JSON.stringifyfunction. See section 4.6.7.2 - below for details.- Serialization behavior - can also be specified directly in IDL, rather than separately as prose. - This is done by following the
-serializerkeyword with - a U+003D EQUALS SIGN ("=") character and - a serialization pattern, - which can take one of the following six forms: --
-
-
-
A map with entries corresponding to zero or more attributes from the interface, and optionally - attributes from an inherited interface:
-serializer = { attribute-identifier, attribute-identifier, … }; -serializer = { inherit, attribute-identifier, attribute-identifier, … };-Each identifier MUST be the identifier of an attribute declared - on the interface. The identified attributes all MUST have a - serializable type.
-The
-inheritkeyword 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:
--
-
- Let map be an empty map. -
- If the
inheritkeyword was used, then set map to be the result of - the serialization behavior of the - closest inherited interface that declares a serializer.
- - For each attribute identifier i in the serialization pattern, in order:
-
-
-
- Remove any entry in map with key name i. -
- Let V be the value of the attribute with identifier i. -
- Add an entry to map whose key name is i and whose - value is result of converting - V to a serialized value. -
- - 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:
-serializer = { attribute }; -serializer = { inherit, attribute };-The
-inheritkeyword 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:
--
-
- Let map be an empty map. -
- If the
inheritkeyword was used, then set map to be the result of - the serialization behavior of the - closest inherited interface that declares a serializer.
- - For each identifier i of an attribute on the interface whose type is
- a serializable type, in the order they appear
- on the interface:
-
-
-
- Remove any entry in map with key name i. -
- Let V be the value of the attribute with identifier i. -
- Add an entry to map whose key name is i and whose - value is result of converting - V to a serialized value. -
- - Return map. -
- -
-
A map with entries corresponding to the named properties:
-serializer = { getter };-This form MUST NOT be used unless the interface or one it - inherits from supports named properties and the return type of the named property getter - is a serializable type.
-The serialization behavior for this - form of serialization pattern is as follows:
--
-
- Let map be an empty map. -
- For each supported property name n on the object, in order:
-
-
-
- Let V be the value of the named property with name n. -
- Add an entry to map whose key name is i and whose - value is result of converting - V to a serialized value. -
- - Return map. -
- -
-
A list of value of zero or more attributes on the interface:
-serializer = [ attribute-identifier, attribute-identifier, … ];
-Each identifier MUST be the identifier of an attribute declared - on the interface. The identified attributes all MUST have a - serializable type.
-The serialization behavior for this - form of serialization pattern is as follows:
--
-
- Let list be an empty list. -
- For each attribute identifier i in the serialization pattern:
-
-
-
- Let V be the value of the attribute with identifier i. -
- Append to list the value that is the result of - converting - V to a serialized value. -
- - Return list. -
- -
-
A list with entries corresponding to the indexed properties:
-serializer = [ getter ];
-This form MUST NOT be used unless the interface or one it - inherits from supports indexed properties and the return type of the indexed property getter - is a serializable type.
-The serialization behavior for this - form of serialization pattern is as follows:
--
-
- Let list be an empty list. -
- Let i be 0. -
- While i is less than or equal to the greatest supported property index on the object:
-
-
-
- Let V be the value of the indexed property with index i - if i is a supported property index, or null otherwise. -
- Append to list the value that is the result of - converting - V to a serialized value. -
- Set i to i + 1. -
- - Return map. -
- -
-
A single attribute:
-serializer = attribute-identifier;
-The identifier MUST be the identifier of an attribute declared - on the interface, and this attribute MUST have a - serializable type.
-The serialization behavior for this - form of serialization pattern is as follows:
--
-
- Let V be the value of the attribute with the specified identifier. -
- 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.stringifycan 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
-serializerkeyword: -serializer type identifier();
-- Serializers declared with operations MUST - be declared to take zero arguments and return a serializable type. -
-- The serialization behavior - of the interface with a serializer declared with an operation is the result of - converting - the value returned from invoking the operation to a serialized value. -
- -
- -[30] Serializer → "serializer" SerializerRest [31] SerializerRest → OperationRest
| - "=" SerializationPattern ";"
| - ";"[32] SerializationPattern → "{" SerializationPatternMap "}"
| - "[" SerializationPatternList "]"
| - identifier[33] SerializationPatternMap → "getter"
| - "inherit" Identifiers
| - identifier Identifiers
| - ε[34] SerializationPatternList → "getter"
| - identifier Identifiers
| - ε[91] Identifiers → "," identifier Identifiers
| - ε- -Example-- The following IDL fragment defines - an interface Transaction that has a - serializer defines in prose: -
--IDL
+interface Transaction { - readonly attribute Account from; - readonly attribute Account to; - readonly attribute double amount; - readonly attribute DOMString description; - readonly attribute unsigned long number; - - serializer; +A callback interface is +an interface that uses the
+callbackkeyword 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 §3.10 Objects implementing interfaces.callback interface identifier { + /* interface_members... */ }; - -interface Account { - DOMString name; - unsigned long number; -};
- The serializer could be defined as follows: -
--
-- The serialization behavior - of the Transaction interface is to run the following - algorithm, where O is the object that implements Transaction: -
--
-
- Let map be an empty map. -
- Add an entry to map whose key is “from” and whose value is
- the serialized value of
- the
numberattribute on the Account - object referenced by thefromattribute on O.
- - Add an entry to map whose key is “to” and whose value is
- the serialized value of
- the
numberattribute on the Account - object referenced by thefromattribute on O.
- - For both of the attributes
amountanddescription, - add an entry to map whose key is the - identifier of the attribute - and whose value is the serialized value - of the value of the attribute on O.
- - Return map. -
- If it was acceptable for Account objects to be serializable - on their own, then serialization patterns - could be used to avoid having to define the serialization behavior - in prose: -
--IDL-
+interface Transaction { - readonly attribute Account from; - readonly attribute Account to; - readonly attribute double amount; - readonly attribute DOMString description; - readonly attribute unsigned long number; - - serializer = { from, to, amount, description }; +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.
+++Specification authors should not define callback interfaces that have only a single operation, + unless required to describe the requirements of existing APIs. + Instead, a callback function should be used.
+The definition of
+EventListeneras a callback interface is an example of an existing API that needs to allow user objects with a + given property (in this case “handleEvent”) to be considered to implement the interface. + For new APIs, and those for which there are no compatibility concerns, + using a callback function will allow + only aFunction object (in the ECMAScript + language binding).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.
++Specification authors wanting to define APIs that take ECMAScript objects + as “property bag” like function arguments are suggested to use dictionary types rather than callback interfaces.
+For example, instead of this:
+callback interface Options { + attribute DOMString? option1; + attribute DOMString? option2; + attribute long? option3; }; - -interface Account { - DOMString name; - unsigned long number; - - serializer = number; -};
- In the ECMAScript language binding, there would exist a
-toJSONmethod on - Transaction objects: --ECMAScript// 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);-- -3.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. -
-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. - -
- -Note-- Note that if an indexed property getter or - setter - is specified using an operation with an identifier, - then indexing an object with an integer that is not a supported property index - does not necessarily elicit the same behavior as invoking the operation with that index. The actual behavior in this - case is language binding specific. -
-- In the ECMAScript language binding, a regular property lookup is done. For example, take the following IDL: -
--IDLinterface A { - getter DOMString toWord(unsigned long index); -};- Assume that an object implementing A has supported property indices - in the range 0 ≤ index < 2. Also assume that toWord is defined to return - its argument converted into an English word. The behavior when invoking the - operation with an out of range index - is different from indexing the object directly: -
--ECMAScriptvar 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".-Example-- The following IDL fragment defines an interface - OrderedMap which allows - retrieving and setting values by name or by index number: -
--IDLinterface OrderedMap { - readonly attribute unsigned long size; - - getter any getByIndex(unsigned long index); - setter void setByIndex(unsigned long index, any value); - - getter any get(DOMString name); - setter void set(DOMString name, any value); -};- Since all of the special operations are declared using - operations with identifiers, the only additional prose - that is necessary is that which describes what keys those sets - have. Assuming that the
-get()operation is - defined to return null if an - attempt is made to look up a non-existing entry in the - OrderedMap, then the following - two sentences would suffice: --
-- An object map implementing OrderedMap - supports indexed properties with indices in the range - 0 ≤ index <
-map.size. -- Such objects also support a named property for every name that, - if passed to
-get(), would return a non-null value. -- As described in section 4.8, - an ECMAScript implementation would create - properties on a platform object implementing - OrderedMap that correspond to - entries in both the named and indexed property sets. - These properties can then be used to interact - with the object in the same way as invoking the object’s - methods, as demonstrated below: -
-ECMAScript// Assume map is a 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") ---3.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. -
-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. -
--- -3.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 -
-statickeyword 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. -
- -
- -[37] StaticMember → "static" StaticMemberRest [38] StaticMemberRest → ReadOnly AttributeRest
| - ReturnType OperationRest-Example-- The following IDL fragment defines an interface - Circle that has a static - operation declared on it: -
--IDLinterface Point { /* ... */ }; - -interface Circle { - attribute double cx; - attribute double cy; - attribute double radius; - - static readonly attribute long triangulationCount; - static Point triangulate(Circle c1, Circle c2, Circle c3); -};- In the ECMAScript language binding, the Function object for -
-triangulateand the accessor property fortriangulationCount- will exist on the interface object - for Circle: -- -ECMAScriptvar 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);-- -3.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. -
--Note-- For example, the overloads for both f and g - are disallowed: -
--IDL
+interface A { - void f(); + +interface A { + void doTask(DOMString type, Options options); }; - -partial interface A { - void f(double x); - void g(); +to be used like this:
+var a = getA(); // Get an instance of A. + +a.doTask("something", { option1: "banana", option3: 100 });
+instead write the following:
+dictionary Options { + DOMString? option1; + DOMString? option2; + long? option3; }; - -partial interface A { - void g(DOMString x); -};
Note that the [Constructor] and - [NamedConstructor] - extended attributes are disallowed from appearing - on partial interface definitions, - so there is no need to also disallow overloading for constructors.
-- An effective overload set - represents the allowable invocations for a particular - operation, - constructor (specified with [Constructor] - or [NamedConstructor]), - legacy caller or - callback function. - The algorithm to compute an effective overload set - operates on one of the following six types of IDL constructs, and listed with them below are - the inputs to the algorithm needed to compute the set. -
--
-
- 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. -
-- The algorithm below describes how to compute an effective overload set. - The following input variables are used, if they are required: -
--
-
- the identifier of the operation or named constructor is A -
- the argument count is N -
- the interface is I -
- the callback function is C -
- Whenever an argument of an extended - attribute is mentioned, it is referring to an argument of the - extended attribute’s named argument list. -
--
-
- Initialize S to ∅. -
- Let F be a set with elements as follows, according to the kind of effective overload set:
-
-
-
- For regular operations -
- - The elements of F are the regular operations with - identifier A defined on interface I. - -
- For static operations -
- - The elements of F are the static operations with - identifier A defined on interface I. - -
- For constructors -
- - The elements of F are the - [Constructor] - extended attributes on interface I. - -
- For named constructors -
- - The elements of F are the - [NamedConstructor] - extended attributes on interface I whose - named argument lists’ - identifiers are A. - -
- For legacy callers -
- - The elements of F are the legacy callers - defined on interface I. - -
- For callback functions -
- - The single element of F is the callback function itself, C. - -
-
- -
- Let maxarg be the maximum number of arguments the operations, constructor extended attributes or callback functions in F are declared to take.
- For variadic operations and constructor extended attributes,
- the argument on which the ellipsis appears counts as a single argument.
- -Note-
So
-void f(long x, long... y);is considered to be declared to take two arguments.
- - Let m be the maximum of maxarg and N. -
- For each operation, extended attribute or callback function X in F:
-
-
-
- Let n be the number of arguments X is declared to take. -
- Let t0..n−1 be a list of types, where ti - is the type of X’s argument at index i. -
- Let o0..n−1 be a list of optionality values, where oi - is “variadic” if X’s argument at index i is a final, variadic argument, - “optional” if the argument is optional, - and “required” otherwise. -
- Add to S the tuple <X, t0..n−1, o0..n−1>. -
- If X is declared to be variadic, then:
-
-
-
- For every integer i, such that n ≤ i ≤ m−1:
-
-
-
- Let u0..i be a list of types, where uj = tj (for j < n) and uj = tn−1 (for j ≥ n). -
- Let p0..i be a list of optionality values, where pj = oj (for j < n) and pj = “variadic” (for j ≥ n). -
- Add to S the tuple <X, u0..i, p0..i>. -
-
- - For every integer i, such that n ≤ i ≤ m−1:
-
- Initialize i to n−1. -
- While i ≥ 0:
-
-
-
- If argument i of X is not
- optional
- (i.e., it is not marked as
optionaland is not - a final, variadic argument), then break this loop.
- - Otherwise, add to S the tuple <X, t0..i−1, o0..i−1>. -
- Set i to i−1. -
- - If argument i of X is not
- optional
- (i.e., it is not marked as
- - - The effective overload set is S. - -
- -Example-- For the following interface: -
--IDLinterface 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); -};- assuming Node and Event - are two other interfaces of which no object can implement both, - the effective overload set - for regular operations with - identifier
-fand argument count 4 is: -- { <f1, (DOMString), (required)>,-
- <f2, (Node, DOMString), (required, required)>,
- <f2, (Node, DOMString, double), (required, required, variadic)>,
- <f2, (Node, DOMString, double, double), (required, required, variadic, variadic)>,
- <f3, (), ()>,
- <f4, (Event, DOMString), (required, required)>,
- <f4, (Event, DOMString, DOMString), (required, required, optional)>,
- <f4, (Event, DOMString, DOMString, double), (required, required, optional, variadic)> } -- Two types are distinguishable if - at most one of the two includes a nullable type - or is a dictionary type, - and at least one of the following three conditions is true: -
--
-
-
-
- The two types (taking their inner types - if they are nullable types) appear - in the following table and there is a “●” mark in the corresponding entry - or there is a letter in the corresponding entry and the designated additional - requirement below the table is satisfied:
--
-- -- boolean -numeric types -string types -interface -object -callback -
functiondictionary -sequence<T> -FrozenArray<T> -RegExp -exception types -buffer source types -- -boolean -- ● -● -● -● -● -● -● -● -● -● -● -- -numeric types -- - ● -● -● -● -● -● -● -● -● -● -- -string types -- - - ● -● -● -● -● -● -● -● -● -- -interface -- - - (a) -- (b) -(b) -● -● -● -● -● -- -object -- - - - - - - - - - - - - -callback function -- - - - - - - ● -● -● -● -● -- -dictionary -- - - - - - - ● -● -● -● -● -- -sequence<T> -- - - - - - - - - ● -● -● -- -FrozenArray<T> -- - - - - - - - - ● -● -● -- -RegExp -- - - - - - - - - - ● -● -- -exception types -- - - - - - - - - - - ● -- -buffer source types -- - - - - - - - - - - - -
-
- 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. -
- The interface type is not a callback interface. -
- - - One type is a union type or nullable union type, - the other is neither a union type nor a nullable union type, and each - member type of the first is distinguishable - with the second. - -
- - Both types are either a union type or nullable union type, and each member type of the one - is distinguishable with each member type of the other. - -
-Note-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. -
--Example-- Consider the effective overload set shown in the previous example. - There are multiple entries in the set with type lists 2, 3 and 4. - For each of these type list lengths, the distinguishing - argument index is 0, since Node and - Event are distinguishable. -
-- The following use of overloading however is invalid: -
-- -IDLinterface 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. -
-- -Example-The following is invalid:
--IDLinterface 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); -};- For argument count 4, the effective overload set is: -
-- { <f1, (DOMString), (required)>,-
- <f2, (long, double, Node, Node), (required, required, required, required)>,
- <f3, (double, double, DOMString, Node), (required, required, required, required)> } -- Looking at entries with type list length 4, the - distinguishing argument index - is 2, since Node and - DOMString are distinguishable. - However, since the arguments in these two overloads at index 0 are different, - the overloading is invalid. -
--- -3.2.7. Iterable declarations
- -- An interface can be declared to be - iterable by using an iterable declaration - (matching Iterable) in the body of the interface. -
-iterable<value-type>; -iterable<key-type, value-type>;
-- Objects implementing an interface that is declared to be iterable - support being iterated over to obtain a sequence of values. -
--Note-In the ECMAScript language binding, an interface that is iterable - will have “entries”, “forEach”, “keys”, “values” and @@iterator - properties on its interface prototype object.
-- If a single type parameter is given, then the interface has a - value iterator and provides - values of the specified type. - If two type parameters are given, then the interface has a - pair iterator and provides - value pairs, where the first value is a key and the second is the - value associated with the key. -
-- A value iterator - MUST only be declared on an interface - that supports indexed properties - and has an integer-typed - attribute named “length”. - The value-type of the value iterator - MUST be the same as the type returned by - the indexed property getter. - A value iterator is implicitly - defined to iterate over the object’s indexed properties. -
-- A pair iterator - MUST NOT be declared on an interface - that supports indexed properties. - Prose accompanying an interface with a - pair iterator - MUST define what the list of - value pairs to iterate over - is. -
--Note-- The ECMAScript forEach method that is generated for a - value iterator - invokes its callback like Array.prototype.forEach does, and the forEach - method for a pair iterator - invokes its callback like Map.prototype.forEach does. -
-- Since value iterators - are currently allowed only on interfaces that - support indexed properties, - it makes sense to use an Array-like forEach method. - There may be a need for value iterators - (a) on interfaces that do not - support indexed properties, - or (b) with a forEach method that instead invokes its callback like - Set.protoype.forEach (where the key is the same as the value). - If you’re creating an API that needs such a forEach method, please send a request to - public-script-coord@w3.org. -
--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. -
- -- -Example-Consider the following interface SessionManager, which allows access to - a number of Session objects:
--IDLinterface SessionManager { - Session getSessionForUser(DOMString username); - readonly attribute unsigned long sessionCount; - - iterable<Session>; + +partial interface SomeInterface { + /* interface_members... */ }; - -interface Session { - readonly attribute DOMString username; - // ... -};- The behavior of the iterator could be defined like so: -
--
-- The values to iterate over - are the open Session objects - on the SessionManager sorted by username. -
-- In the ECMAScript language binding, the interface prototype object - for the SessionManager interface - has a
-valuesmethod that is a function, which, when invoked, - returns an iterator object that itself has anextmethod that returns the - next value to be iterated over. It hasvaluesandentries- methods that iterate over the indexes of the list of session objects - and [index, session object] pairs, respectively. It also has - a @@iterator method that allows a SessionManager - to be used in afor..ofloop: --ECMAScript// 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]. -
- - -
-[59] Iterable → "iterable" "<" Type OptionalType ">" ";" [60] OptionalType → "," Type
| - ε-- -3.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. -
-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. -
-
-[39] ReadOnlyMember → "readonly" ReadOnlyMemberRest [40] ReadOnlyMemberRest → AttributeRest
| - ReadWriteMaplike
| - ReadWriteSetlike[61] ReadWriteMaplike → MaplikeRest [63] MaplikeRest → "maplike" "<" Type "," Type ">" ";" - No extended attributes - defined in this specification are applicable to maplike declarations. -
--Editorial noteAdd example.
--3.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. -
-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. -
-
-[39] ReadOnlyMember → "readonly" ReadOnlyMemberRest [40] ReadOnlyMemberRest → AttributeRest
| - ReadWriteMaplike
| - ReadWriteSetlike[62] ReadWriteSetlike → SetlikeRest [64] SetlikeRest → "setlike" "<" Type ">" ";" - No extended attributes - defined in this specification are applicable to setlike declarations. -
--Editorial noteAdd example.
-- -3.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… ++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], +[ImplicitThis], +[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], +[SecureContext] and +[Unforgeable].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], +[ImplicitThis], +[LegacyArrayClass], +[NamedConstructor], +[NoInterfaceObject], +[OverrideBuiltins], +[PrimaryGlobal], +[SecureContext], +[Unforgeable].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 + ε +
++ +- -The following IDL fragment demonstrates the definition of two mutually referential interfaces. + Both
+HumanandDoginherit fromAnimal. Objects that implement + either of those two interfaces will thus have anameattribute.interface Animal { + attribute DOMString name; }; - -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. -
- -
- - -[6] Partial → "partial" PartialDefinition [7] PartialDefinition → PartialInterface
| - PartialDictionary
| - Namespace[97] Namespace → "namespace" identifier "{" NamespaceMembers "}" ";" [98] NamespaceMembers → ExtendedAttributeList NamespaceMember NamespaceMembers
| - ε[99] NamespaceMember → ReturnType OperationRest - -Example-- The following IDL fragment defines an - namespace. -
-- -IDLnamespace VectorUtils { - double dotProduct(Vector x, Vector y); - Vector crossProduct(Vector x, Vector y); -};- An ECMAScript implementation would then expose a global property named -
- -VectorUtilswhich was a simple object (with prototype - %ObjectPrototype%) with enumerable data properties for each declared operation: --ECMAScriptObject.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 }.--3.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… + +interface Human : Animal { + attribute Dog? pet; }; - -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. -
--Warning-- 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 (
-trueorfalse), - thenulltoken, - an integer token, a - float token, - one of the three special floating point literal values (Infinity, --InfinityorNaN), - 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 -
-requiredkeyword, 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… + +interface Dog : Animal { + attribute Human? owner; }; - -partial dictionary SomeDictionary { - dictionary-members… -};--Note-As with partial interface definitions, partial dictionary definitions are intended for use as a specification - editorial aide, allowing the definition of an interface to be separated - over more than one section of the document, and sometimes multiple documents.
-- The order of the dictionary members - on a given dictionary is such that inherited dictionary members are ordered - before non-inherited members, and the dictionary members on the one - dictionary definition (including any partial dictionary definitions) are - ordered lexicographically by the Unicode codepoints that comprise their - identifiers. -
--Note-For example, with the following definitions:
--IDL+
+dictionary B : A { - long b; - long a; ++ ++The following IDL fragment defines + simplified versions of a few DOM interfaces, one of which + is a callback interface.
+interface Node { + readonly attribute DOMString nodeName; + readonly attribute Node? parentNode; + Node appendChild(Node newChild); + void addEventListener(DOMString type, EventListener listener); }; - -dictionary A { - long c; - long g; + +callback interface EventListener { + void handleEvent(Event event); }; - -dictionary C : B { - long e; - long f; +
+Since the
+EventListenerinterface is annotated + callback interface, user objects can implement it: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.
+It is not possible for a user object to implement
+Node, however: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.
+3.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 (trueandfalse), +thenulltoken, aninteger token, +afloat token, +or one of the three special floating point constant values +(-Infinity,InfinityandNaN).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
+trueandfalseare the IDLbooleanvaluestrue andfalse .The value of an
+integer token is an integer +whose value is determined as follows:-
+
-
+
Let S be the sequence of characters matched by the
+integer token. -
+
Let sign be −1 if S begins with U+002D HYPHEN-MINUS ("-"), and 1 otherwise.
+ -
+
Let base be the base of the number based on the characters that follow the optional leading U+002D HYPHEN-MINUS ("-") character:
+-
+
-
+
U+0030 DIGIT ZERO ("0"), U+0058 LATIN CAPITAL LETTER X ("X")
+- +
U+0030 DIGIT ZERO ("0"), U+0078 LATIN SMALL LETTER X ("x")
+ - +
-
+
The base is 16.
+ -
+
U+0030 DIGIT ZERO ("0")
+ -
+
The base is 8.
+ -
+
Otherwise
+ -
+
The base is 10.
+
-
+
-
+
Let number be the result of interpreting all remaining characters following the optional leading U+002D HYPHEN-MINUS ("-") character and any characters indicating the base as an integer specified in base base.
+ -
+
Return sign × number.
+
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 theinteger token must not +lie outside the valid range of values for its type, as given in §3.11 Types.The value of a
+float token is + either an IEEE 754 single-precision floating point number or an IEEE 754 + double-precision floating point number, depending on the type of the + constant, dictionary member or optional argument it is being used as the value for, determined as follows:-
+
-
+
Let S be the sequence of characters matched by the
+float token. -
+
Let value be the Mathematical Value that would be obtained if S were +parsed as an ECMAScript NumericLiteral.
+ -
+
If the
+float token is being +used as the value for afloatorunrestricted float, then +the value of thefloat token +is the IEEE 754 single-precision floating point number closest to result. Otherwise, thefloat token is being +used as the value for adoubleorunrestricted double, and +the value of thefloat token +is the IEEE 754 double-precision floating point number closest to result. [IEEE-754]
The value of a constant value specified as
+Infinity,-InfinityorNaNis 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 valueInfinity -
+
The value is the IEEE 754 single-precision positive infinity value.
+ -
+
Type
+unrestricted double, constant valueInfinity -
+
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 valueNaN -
+
The value is the IEEE 754 single-precision NaN value with the bit pattern 0x7fc00000.
+ -
+
Type
+unrestricted double, constant valueNaN -
+
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 thefloat token must not +lie outside the valid range of values for its type, as given in §3.11 Types. +Also,Infinity,-InfinityandNaNmust not +be used as the value of afloatordouble.The value of the
+nulltoken is the specialnull value that is a member of the nullable types. The type of +thenulltoken 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.
++The ECMAScript language binding does however + allow constants to be accessed + through objects implementing the IDL interfaces on which the constants are declared. + For example, with the following IDL:
+interface A { + const short rambaldi = 47; }; - -partial dictionary A { - long h; - long d; -};
- the order of the dictionary members - of a dictionary value of type C is - c, d, g, h, a, b, e, f. -
-- Dictionaries are required to have their members ordered because - in some language bindings the behavior observed when passing - a dictionary value to a platform object depends on the order - the dictionary members are fetched. For example, consider the - following additional interface: -
--IDLinterface Something { - void f(A a); -};- and this ECMAScript code: -
--ECMAScriptvar 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 order that the dictionary members are fetched in determines - what values they will be taken to have. Since the order for - A is defined to be c then d, - the value for c will be 1 and the value for d will be 2. -
-- The identifier of a dictionary member MUST NOT be - the same as that of another dictionary member defined on the dictionary or - on that dictionary’s inherited dictionaries. -
-- Dictionaries MUST NOT be used as the type of an - attribute or - constant. -
-- The following extended attributes are applicable to dictionaries: - [Constructor], - [Exposed], - [SecureContext], -
-- The following extended attributes are applicable to dictionary members: - [Clamp], - [EnforceRange]. -
-
-[6] Partial → "partial" PartialDefinition [7] PartialDefinition → PartialInterface
| - PartialDictionary
| - Namespace[11] Dictionary → "dictionary" identifier Inheritance "{" DictionaryMembers "}" ";" [12] DictionaryMembers → ExtendedAttributeList DictionaryMember DictionaryMembers
| - ε[13] DictionaryMember → Required Type identifier Default ";" [15] PartialDictionary → "dictionary" identifier "{" DictionaryMembers "}" ";" [16] Default → "=" DefaultValue
| - ε[17] DefaultValue → ConstValue
| - string
| - "[" "]"[18] Inheritance → ":" identifier
| - ε-Example-- One use of dictionary types is to allow a number of optional arguments to - an operation without being - constrained as to the order they are specified at the call site. For example, - consider the following IDL fragment: -
-IDL+
+[Constructor] -interface Point { - attribute double x; - attribute double y; +the constant value can be accessed in ECMAScript either as
+A.rambaldiorinstanceOfA.rambaldi.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 +
++ ++The following IDL fragment demonstrates how constants of the above types can be defined.
+interface Util { + const boolean DEBUG = false; + const octet LF = 10; + const unsigned long BIT_MASK = 0x0000fc00; + const double AVOGADRO = 6.022e23; }; - -dictionary PaintOptions { - DOMString? fillPattern = "black"; - DOMString? strokePattern = null; - Point position; +
+3.2.2. Attributes
+An attribute is an interface member (matching
+inherit ReadOnly AttributeRest ,static ReadOnly AttributeRest ,stringifier ReadOnly AttributeRest , +orReadOnly 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:-
+
-
+
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; }; - -interface GraphicsContext { - void drawRectangle(double width, double height, optional PaintOptions options); -};
- In an ECMAScript implementation of the IDL, an Object - can be passed in for the optional PaintOptions dictionary: -
--ECMAScript// Get an instance of GraphicsContext. -var ctx = getGraphicsContext(); - -// Draw a rectangle. -ctx.drawRectangle(300, 200, { fillPattern: "red", position: new Point(10, 10) });- Both fillPattern and strokePattern are given default values, - so if they are omitted, the definition of drawRectangle can assume that they - have the given default values and not include explicit wording to handle - their non-presence. -
--- -3.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 names: -
--
-
- Error -
- EvalError -
- RangeError -
- ReferenceError -
- TypeError -
- URIError -
- These correspond to all of the ECMAScript error objects ([ECMA-262], section 19.5) (apart from - SyntaxError, which is deliberately omitted as - it is for use only by the ECMAScript parser). - The meaning of - each simple exception matches - its corresponding Error object in the - ECMAScript specification. -
-- The second kind of exception is a DOMException, - which is an exception that encapsulates a name and an optional integer code, - for compatibility with historically defined exceptions in the DOM. -
-- For simple exceptions, - the error name is the name - of the exception. - For a DOMException, - the error name MUST - be one of the names listed in the error names table - below. The table also indicates the DOMException's integer code - for that error name, if it has one. -
-- There are two types that can be used to refer to - exception objects: Error, which encompasses all exceptions, - and DOMException which includes just DOMException objects. - This allows for example an operation - to be declared to have a DOMException - return type or an attribute - to be of type Error. -
-- Exceptions can be created by providing its - error name. - Exceptions can also be thrown, by providing the - same details required to create one. -
-- The resulting behavior from creating and throwing an exception is language binding-specific. -
--Note-- See section 4.14 - below for details on what creating and throwing an exception - entails in the ECMAScript language binding. -
-- -Example-- Here is are some examples of wording to use to create and throw exceptions. - To throw a new simple exception named - TypeError: -
--
-Throw a TypeError.
-- To throw a new DOMException with - error name - IndexSizeError: -
--
-Throw an IndexSizeError.
-- To create a new DOMException with - error name - SyntaxError: -
--
-Let object be a newly created SyntaxError.
---3.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!
-- -
-Name Description Legacy code name and value - -" -IndexSizeError"The index is not in the allowed range. -INDEX_SIZE_ERR(1)- -" -HierarchyRequestError"The operation would yield an incorrect node tree. -HIERARCHY_REQUEST_ERR(3)- -" -WrongDocumentError"The object is in the wrong document. -WRONG_DOCUMENT_ERR(4)- -" -InvalidCharacterError"The string contains invalid characters. -INVALID_CHARACTER_ERR(5)- -" -NoModificationAllowedError"The object can not be modified. -NO_MODIFICATION_ALLOWED_ERR(7)- -" -NotFoundError"The object can not be found here. -NOT_FOUND_ERR(8)- -" -NotSupportedError"The operation is not supported. -NOT_SUPPORTED_ERR(9)- -" -InUseAttributeError"The attribute is in use. -INUSE_ATTRIBUTE_ERR(10)- -" -InvalidStateError"The object is in an invalid state. -INVALID_STATE_ERR(11)- -" -SyntaxError"The string did not match the expected pattern. -SYNTAX_ERR(12)- -" -InvalidModificationError"The object can not be modified in this way. -INVALID_MODIFICATION_ERR(13)- -" -NamespaceError"The operation is not allowed by Namespaces in XML. [XMLNS] -NAMESPACE_ERR(14)- -" -InvalidAccessError"The object does not support the operation or argument. -INVALID_ACCESS_ERR(15)- - -" -SecurityError"The operation is insecure. -SECURITY_ERR(18)- - -" -NetworkError"A network error occurred. -NETWORK_ERR(19)- - -" -AbortError"The operation was aborted. -ABORT_ERR(20)- - -" -URLMismatchError"The given URL does not match another URL. -URL_MISMATCH_ERR(21)- - -" -QuotaExceededError"The quota has been exceeded. -QUOTA_EXCEEDED_ERR(22)- - -" -TimeoutError"The operation timed out. -TIMEOUT_ERR(23)- -" -InvalidNodeTypeError"The supplied node is incorrect or has an incorrect ancestor for this operation. -INVALID_NODE_TYPE_ERR(24)- - -" -DataCloneError"The object can not be cloned. -DATA_CLONE_ERR(25)- - -" -EncodingError"The encoding operation (either encoded or decoding) failed. -— -- - -" -NotReadableError"The I/O read operation failed. -— -- - -" -UnknownError"The operation failed for an unknown transient reason (e.g. out of memory). - -— -- - -" -ConstraintError"A mutation operation in a transaction failed because a constraint was not satisfied. -— -- - -" -DataError"Provided data is inadequate. -— -- - -" -TransactionInactiveError"A request was placed against a transaction which is currently not active, or which is finished. -— -- - -" -ReadOnlyError"The mutating operation was attempted in a "readonly" transaction. -— -- - -" -VersionError"An attempt was made to open a database using a lower version than the existing version. -— -- - -" -OperationError"The operation failed for an operation-specific reason. -— -- - - -" -NotAllowedError"The request is not allowed by the user agent or the platform in the current context, possibly because the user denied permission. -— --- -3.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 { enumeration-values… };-- The enumeration values are specified - as a comma-separated list of string literals. - The list of enumeration values - MUST NOT include duplicates. -
--Warning-- It is strongly suggested that enumeration values be all lowercase, - and that multiple words be separated using dashes or not be - separated at all, unless there is a specific reason to use another - value naming scheme. For example, an enumeration value that - indicates an object should be created could be named -
-"createobject"or"create-object". - Consider related uses of enumeration values when deciding whether - to dash-separate or not separate enumeration value words so that - similar APIs are consistent. -- The behavior when a string value that is not one a valid enumeration value - is used when assigning to an attribute, - or passed as an operation argument, - whose type is the enumeration, is language binding specific. -
--Note-- In the ECMAScript binding, assignment of an invalid string value to an - attribute is ignored, while - passing such a value as an operation argument - results in an exception being thrown. -
-- No extended attributes - defined in this specification are applicable to enumerations. -
- -
- -[19] Enum → "enum" identifier "{" EnumValueList "}" ";" [20] EnumValueList → string EnumValueListComma [21] EnumValueListComma → "," EnumValueListString
| - ε[22] EnumValueListString → string EnumValueListComma
| - ε-Example-- The following IDL fragment - defines an enumeration - that is used as the type of an attribute - and an operation argument: -
--IDLenum MealType { "rice", "noodles", "other" }; - -interface Meal { - attribute MealType type; - attribute double size; // in grams - - void initialize(MealType type, double size); -};- An ECMAScript implementation would restrict the strings that can be - assigned to the type property or passed to the initializeMeal function - to those identified in the enumeration. -
--ECMAScriptvar 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.-- -3.7. Callback functions
- --Editorial note-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]. -
- -
- -[3] CallbackOrInterface → "callback" CallbackRestOrInterface
| - Interface[4] CallbackRestOrInterface → CallbackRest
| - Interface[23] CallbackRest → identifier "=" ReturnType "(" ArgumentList ")" ";" -Example-- The following IDL fragment defines - a callback function used for an API that - invokes a user-defined function when an operation is complete. -
--IDLcallback AsyncOperationCallback = void (DOMString status); - -interface AsyncOperations { - void performOperation(AsyncOperationCallback whenFinished); -};- In the ECMAScript language binding, a Function object is - passed as the operation argument. -
--ECMAScriptvar ops = getAsyncOperations(); // Get an instance of AsyncOperations. - -ops.performOperation(function(status) { - window.alert("Operation finished, status is " + status + "."); -});-- -3.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. -
- -
- -[24] Typedef → "typedef" Type identifier ";" -Example-- The following IDL fragment - demonstrates the use of typedefs - to allow the use of a short - identifier instead of a long - sequence type. -
--IDL
+interface Point { - attribute double x; - attribute double y; +- +
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; }; - -typedef sequence<Point> Points; - -interface Widget { - boolean pointWithinBounds(Point p); - boolean allPointsWithinBounds(Points ps); -};
-- -3.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. -
-Note-- Specification authors are discouraged from writing implements statements - where the interface on the left-hand side - is a supplemental interface. - For example, if author 1 writes: -
--IDLinterface Window { ... }; -interface SomeFunctionality { ... }; -Window implements SomeFunctionality;- and author 2 later writes: -
--IDLinterface Gizmo { ... }; -interface MoreFunctionality { ... }; -SomeFunctionality implements MoreFunctionality; -Gizmo implements SomeFunctionality;- then it might be the case that author 2 is unaware of exactly which - interfaces already are used on the left-hand side of an -
-implements SomeFunctionalitystatement, and so has - required more objects implement MoreFunctionality - than he or she expected. -- Better in this case would be for author 2 to write: -
--IDLinterface 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. -
--Note-For example, that precludes the following:
--IDLinterface 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. -
- -
- -[25] ImplementsStatement → identifier "implements" identifier ";" -Example-- The following IDL fragment - defines two interfaces, stating - that one interface is always implemented on objects implementing the other. -
--IDL
+ +interface Entry { - readonly attribute unsigned short entryType; - // ... +If an attribute has no
+statickeyword, 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 theattributekeyword. +If theType 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 union type that has a nullable or non-nullable sequence type or dictionary +as one of its flattened member types
+
The attribute is read only if the
+readonlykeyword is used before theattributekeyword. +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; }; - -interface Observable { - void addEventListener(DOMString type, - EventListener listener, - boolean useCapture); - // ... +
+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
+inheritin 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, andinheritmust not appear on a read only attribute or a static attribute.interface Ancestor { + readonly attribute TheType theIdentifier; }; - -Entry implements Observable;
- An ECMAScript implementation would thus have an “addEventListener” - property in the prototype chain of every Entry: -
-- -ECMAScriptvar e = getEntry(); // Obtain an instance of Entry. -typeof e.addEventListener; // Evaluates to "function".- Note that it is not the case that all Observable - objects implement Entry. -
--- - - -3.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. -
- In a browser, for example, - the browser-implemented DOM objects (implementing interfaces such as Node and - Document) that provide access to a web page’s contents - to ECMAScript running in the page would be platform objects. These objects might be exotic objects, - implemented in a language like C++, or they might be native ECMAScript objects. Regardless, - an implementation of a given set of IDL fragments needs to be able to recognize all platform objects - that are created by the implementation. This might be done by having some internal state that records whether - a given object is indeed a platform object for that implementation, or perhaps by observing - that the object is implemented by a given internal C++ class. How exactly platform objects - are recognised by a given implementation of a set of IDL fragments is implementation specific. -
-- All other objects in the system would not be treated as platform objects. For example, assume that - a web page opened in a browser loads an ECMAScript library that implements DOM Core. This library - would be considered to be a different implementation from the browser provided implementation. - The objects created by the ECMAScript library that implement the Node interface - will not be treated as platform objects that implement Node by the browser implementation. -
-- User objects are those that authors would create, implementing - callback interfaces that the Web APIs use to be able to invoke author-defined - operations or to send and receive values to the author’s program through - manipulating the object’s attributes. In a web page, an ECMAScript object - that implements the EventListener interface, which is - used to register a callback that the DOM Events implementation invokes, would be considered - to be a user object. -
-- Note that user objects can only implement callback interfaces - and platform objects can only implement non-callback interfaces. -
- --- -3.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, - unresticted float, - double and - unrestricted double. -
-- The primitive types are - boolean and the numeric types. -
-- The string types are - DOMString, all enumeration types, - ByteString and USVString. -
-- The exception types are - Error and DOMException. -
-- The typed array types are - Int8Array, - Int16Array, - Int32Array, - Uint8Array, - Uint16Array, - Uint32Array, - Uint8ClampedArray, - Float32Array and - Float64Array. -
-- The buffer source types - are ArrayBuffer, - DataView, - and the typed array types. -
-- The object type, - all interface types - and the exception types - are known as object types. -
-- Every type has a type name, which - is a string, not necessarily unique, that identifies the type. - Each sub-section below defines what the type name is for each - type. -
-- When conversions are made from language binding specific types to - IDL types in order to invoke an operation - or assign a value to an attribute, - all conversions necessary will be performed before the - specified functionality of the operation or attribute assignment - is carried out. If the conversion cannot - be performed, then the operation will not run or - the attribute will not be updated. In some language bindings, - type conversions could result in an exception being thrown. - In such cases, these exceptions will be propagated to the - code that made the attempt to invoke the operation or - assign to the attribute. -
- --- -3.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.) -
--- -3.11.2. boolean
- -- The boolean type has two values: - true and false. -
-- boolean constant values in IDL are - represented with the
- -trueand -falsetokens. --- -3.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. -
- --- -3.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. -
- --- -3.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. -
- --- -3.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”. -
--- -3.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. -
- --- -3.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”. -
--- -3.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. -
- --- -3.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”. -
--- -3.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. -
- - --- -3.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”. -
--- -3.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. -
- --- -3.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”. -
--- -3.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 - ([DOM3CORE], section 1.2.1), - this document defines DOMString to be an intrinsic type so as to avoid - special casing that sequence type in various situations where a - string is required. -
--Note-- Note also that null - is not a value of type DOMString. - To allow null, a - nullable DOMString, - written as
-DOMString?in IDL, needs to be used. -- Nothing in this specification requires a DOMString - value to be a valid UTF-16 string. For example, a DOMString - value might include unmatched surrogate pair characters. However, authors - of specifications using Web IDL might want to obtain a sequence of - Unicode scalar values given a particular sequence of - code units. - The following algorithm defines a way to - convert a DOMString to a sequence of Unicode scalar values: -
--
-
- Let S be the DOMString value. -
- Let n be the length of S. -
- Initialize i to 0. -
- Initialize U to be an empty sequence of Unicode characters. -
- While i < n:
-
-
-
- Let c be the code unit in S at index i. -
- Depending on the value of c:
-
-
-
- c < 0xD800 or c > 0xDFFF -
- Append to U the Unicode character with code point c. - -
- 0xDC00 ≤ c ≤ 0xDFFF -
- Append to U a U+FFFD REPLACEMENT CHARACTER. - -
- 0xD800 ≤ c ≤ 0xDBFF -
-
-
-
-
- If i = n−1, then append to U a U+FFFD REPLACEMENT CHARACTER. -
- Otherwise, i < n−1:
-
-
-
- Let d be the code unit in S at index - i+1. -
- If 0xDC00 ≤ d ≤ 0xDFFF, then:
-
-
-
- Let a be c & 0x3FF. -
- Let b be d & 0x3FF. -
- Append to U the Unicode character with - code point 216+210a+b. -
- Set i to i+1. -
- - Otherwise, d < 0xDC00 or d > 0xDFFF. - Append to U a U+FFFD REPLACEMENT CHARACTER. -
-
-
- - Set i to i+1. -
- - Return U. -
- 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. -
- --- -3.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”. -
--Warning-- Specifications SHOULD only use - ByteString for interfacing with protocols - that use bytes and strings interchangably, such as HTTP. In general, - strings SHOULD be represented with - DOMString values, even if it is expected - that values of the string will always be in ASCII or some - 8 bit character encoding. Sequences, - frozen arrays or Typed Arrays - with octet or byte - elements SHOULD be used for holding - 8 bit data rather than ByteString. - [TYPEDARRAYS] -
--- -3.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”. -
--Warning-- Specifications SHOULD only use - USVString for APIs that perform - text processing and need a string of Unicode - scalar values to operate on. Most APIs that use strings - should instead be using DOMString, - which does not make any interpretations of the code units - in the string. When in doubt, use DOMString. -
--- -3.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?. -
- --- -3.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 [HTML] at the time the Object value - is converted to an IDL callback interface type value. See section 4.2.20 below.
-- There is no way to represent a constant object reference value for - a particular interface type in IDL. -
-- To denote a type that includes all possible references to objects implementing - the given interface plus the null value, - use a nullable type. -
-- The type name of an interface type - is the identifier of the interface. -
--- -3.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. -
--- -3.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. -
--- -3.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 [HTML] at - the time an ECMAScript Object value is converted to an IDL - callback function type value. See section 4.2.23 below.
-- There is no way to represent a constant callback function - value in IDL. -
-- The type name of a callback function type - is the identifier of the callback function. -
--- -3.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 type as one of its - flattened member types. -
--Note-Although dictionary types can in general be nullable, they cannot when used - as the type of an operation argument or a dictionary member.
-- Nullable type constant values in IDL are represented in the same way that - constant values of their inner type - would be represented, or with the
-nulltoken. -- The type name of a nullable type - is the concatenation of the type name of the inner type T and - the string “OrNull”. -
--Example-- For example, a type that allows the values true, - false and null - is written as boolean?: -
--IDLinterface MyConstants { - const boolean? ARE_WE_THERE_YET = false; -};- The following interface has two - attributes: one whose value can - be a DOMString or the null - value, and another whose value can be a reference to a Node - object or the null value: -
--IDLinterface Node { - readonly attribute DOMString? namespaceURI; - readonly attribute Node? parentNode; - // ... -};-- -3.11.24. Sequences — 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”. -
--- -3.11.25. Promise types — Promise<T>
- -- A promise type is a parameterized type - whose values are references to objects that “is used as a place holder - for the eventual results of a deferred (and possibly asynchronous) computation - result of an asynchronous operation” [ECMA-262]. - See section 25.4 - of the ECMAScript specification for details on the semantics of promise objects. -
-- There is no way to represent a promise value in IDL. -
-- The type name of a promise type - is the concatenation of the type name for T and - the string “Promise”. -
--- -3.11.26. 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
-orkeyword - with a set of surrounding parentheses. - The types which comprise the union type are known as the - union’s member types. --Note-- For example, you might write
-(Node or DOMString)- or(double or sequence<double>). When applying a -?suffix to a - union type - as a whole, it is placed after the closing parenthesis, - as in(Node or DOMString)?. -- Note that the member types - of a union type do not descend into nested union types. So for -
-(double or (sequence<long> or Event) or (Node or DOMString)?)the member types - aredouble,(sequence<long> or Event)and -(Node or DOMString)?. -- Like the any type, values of - union types have a specific type, - which is the particular member type - that matches the value. -
-- The flattened member types - of a union type is a set of types - determined as follows: -
--
-
- Let T be the union type. -
- Initialize S to ∅. -
- For each member type U of T:
-
-
-
- If U is a nullable type, then - set U to be the inner type of U. -
- If U is a union type, then - add to S the flattened member types - of U. -
- Otherwise, U is not a union type. - Add U to S. -
- - Return S. -
-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 typesNode,sequence<long>,Event, -XMLHttpRequest,DOMStringand -sequence<(sequence<double> or NodeList)>. -- The number of nullable member types - of a union type is an integer - determined as follows: -
--
-
- Let T be the union type. -
- Initialize n to 0. -
- For each member type U of T:
-
-
-
- If U is a nullable type, then:
-
-
-
- Set n to n + 1. -
- Set U to be the inner type of U. -
- - If U is a union type, then:
-
-
-
- Let m be the number - of nullable member types of U. -
- Set n to n + m. -
-
- - If U is a nullable type, then:
-
- Return n. -
- The any type MUST NOT - be used as a union member type. -
-- The number of nullable member types - of a union type MUST - be 0 or 1, and if it is 1 then the union type MUST also not have - a dictionary type in its - flattened member types. -
-- A type includes a nullable type if: -
--
-
- 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”. -
-
-[75] UnionType → "(" UnionMemberType "or" UnionMemberType UnionMemberTypes ")" [76] UnionMemberType → NonAnyType
| - UnionType Null[77] UnionMemberTypes → "or" UnionMemberType UnionMemberTypes
| - ε[78] NonAnyType → PrimitiveType Null
| - PromiseType Null
| - "ByteString" Null
| - "DOMString" Null
| - "USVString" Null
| - identifier Null
| - "sequence" "<" Type ">" Null
| - "object" Null
| - "RegExp" Null
| - "Error" Null
| - "DOMException" Null
| - BufferRelatedType Null
| - "FrozenArray" "<" Type ">" Null-- -3.11.27. RegExp
- -- The RegExp type is a type - whose values are references to objects that represent regular expressions. - The particular regular expression language and the features it supports - is language binding specific. -
-- There is no way to represent a constant RegExp - value in IDL. -
- --- -3.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. -
- --- -3.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”. -
--- -3.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. -
--
-Type Kind of buffer ArrayBuffer An object that holds a pointer (which may be null) to a buffer of a fixed number of bytes DataView A view on to an ArrayBuffer that allows typed access to integers and floating point values stored at arbitrary offsets into the buffer - Int8Array, -
- Int16Array,
- Int32ArrayA view on to an ArrayBuffer that exposes it as an array of two’s complement signed integers of the given size in bits - Uint8Array, -
- Uint16Array,
- Uint32ArrayA view on to an ArrayBuffer that exposes it as an array of unsigned integers of the given size in bits Uint8ClampedArray -A view on to an ArrayBuffer that exposes it as an array of unsigned 8 bit integers with clamped conversions - Float32Array, -
- Float64ArrayA view on to an ArrayBuffer that exposes it as an array of IEEE 754 floating point numbers of the given size in bits -Note-These types all correspond to classes defined in ECMAScript.
-- To detach an ArrayBuffer - is to set its buffer pointer to null. -
-- There is no way to represent a constant value of any of these types in IDL. -
-- The type name of all - of these types is the name of the type itself. -
-- At the specification prose level, IDL buffer source types - are simply references to objects. To inspect or manipulate the bytes inside the buffer, - specification prose MUST first either - get a reference to the bytes held by the buffer source - or get a copy of the bytes held by the buffer source. - With a reference to the buffer source’s bytes, specification prose can get or set individual - byte values using that reference. -
--Warning-- Extreme care must be taken when writing specification text that gets a reference - to the bytes held by a buffer source, as the underyling data can easily be changed - by the script author or other APIs at unpredictable times. If you are using a buffer source type - as an operation argument to obtain a chunk of binary data that will not be modified, - it is strongly recommended to get a copy of the buffer source’s bytes at the beginning - of the prose defining the operation. -
-- Requiring prose to explicitly get a reference to or copy of the bytes is intended to - help specification reviewers look for problematic uses of these buffer source types. -
--Note-- When designing APIs that take a buffer, it is recommended to use the - BufferSource typedef rather than ArrayBuffer - or any of the view types. -
-- When designing APIs that create and return a buffer, it is recommended - to use the ArrayBuffer type rather than - Uint8Array. -
-- Attempting to get a reference to or - get a copy of the bytes held by a buffer source - when the ArrayBuffer has been detached - will fail in a language binding-specific manner. -
--Note-See section 4.2.31 below for - how interacting with buffer source types works in the ECMAScript language binding.
--Editorial note-We should include an example of specification text that uses these types and terms.
---3.11.31. Frozen arrays — 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”. -
--- - -3.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: -
--
- -- -Grammar symbol -Form -Example -- -- ExtendedAttributeNoArgs - -- takes no arguments - -- -[Replaceable]-- -- ExtendedAttributeArgList - -- takes an argument list - -- -[Constructor(double x, double y)]-- -- ExtendedAttributeNamedArgList - -- takes a named argument list - -- -[NamedConstructor=Image(DOMString src)]-- -- ExtendedAttributeIdent - -- takes an identifier - -- -[PutForwards=name]-- - -- ExtendedAttributeIdentList - -- takes an identifier list - -- -[Exposed=(Window,Worker)]-- This specification defines a number of extended attributes that - are applicable to the ECMAScript language binding, which are described in - section 4.3. - Each extended attribute definition will state which of the above - six forms are allowed. -
- --- -4. ECMAScript binding
- -- This section describes how definitions written with the IDL defined in - section 3 correspond to particular constructs - in ECMAScript, as defined by the ECMAScript Language Specification 6th Edition - [ECMA-262]. -
-- Objects defined in this section have internal properties as described in - ECMA-262 sections 9.1 and - 9.3.1 unless otherwise specified, in which case one or - more of the following are redefined in accordance with the rules for exotic objects: - [[Call]], - [[Set]], - [[DefineOwnProperty]], - [[GetOwnProperty]], - [[Delete]] and - [[HasInstance]]. -
-- Other specifications MAY override the definitions - of any internal method of a platform object - that is an instance of an interface. -
--Warning-- As overriding internal ECMAScript object methods is a low level operation and - can result in objects that behave differently from ordinary objects, - this facility SHOULD NOT be used unless necessary - for security or compatibility. The expectation is that this will be used - for Location objects - and possibly WindowProxy objects. -
-- Unless otherwise specified, the [[Extensible]] internal property - of objects defined in this section has the value true. -
-- Unless otherwise specified, the [[Prototype]] internal property - of objects defined in this section is the Object prototype object. -
-- Some objects described in this section are defined to have a class string, - which is the string to include in the string returned from Object.prototype.toString. - If an object has a class string, then the object MUST, - at the time it is created, have a property whose name is the @@toStringTag symbol - and whose value is the specified string. -
--Editorial note-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. -
-Editorial note-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. -
-- -Example-- Consider the following algorithm: -
--
-
- Let x be the ECMAScript value passed in to this algorithm. -
- Let y be the result of calling ToString(x). -
- Return y. -
- Since ToString can throw an exception (for example if passed the object -
-({ toString: function() { throw 1 } })), and the exception is - not handled in the above algorithm, if one is thrown then it causes this - algorithm to end and for the exception to propagate out to its caller, if there - is one. --- -4.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 -
- default unforgeable valueOf functions -
- map size getters -
- DOMException constructor objects -
- DOMException prototype objects -
- named properties objects -
- Each ECMAScript global environment ([ECMA-262], section 8.2) - MUST have its own unique set of each of - the initial objects, created - before control enters any ECMAScript execution context associated with the - environment, but after the global object for that environment is created. The [[Prototype]]s - of all initial objects in a given global environment MUST come from - that same global environment. -
--Example-- In an HTML user agent, multiple global environments can exist when - multiple frames or windows are created. Each frame or window will have - its own set of initial objects, - which the following HTML document demonstrates: -
--HTML<!DOCTYPE html> -<title>Different global environments</title> -<iframe id=a></iframe> -<script> -var iframe = document.getElementById("a"); -var w = iframe.contentWindow; // 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 - section 4.6 are - not followed for that interface. -
-- -Note-- This allows, for example, ECMAScript global environments for Web Workers to expose - different sets of supported interfaces from those exposed in environments - for Web pages. -
-- 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. -
--- -4.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. -
- --- -4.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 section 4.2.15, - below. - -
- 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 section 4.2.16, - below. - -
- 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. -
--- -4.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. -
--- -4.2.3. boolean
- -- An ECMAScript value V is - converted - to an IDL boolean value - by running the following algorithm: -
--
-
- Let x be the result of computing ToBoolean(V). -
- Return the IDL boolean value that is the one that represents the same truth value as the ECMAScript Boolean value x. -
- The IDL boolean value true - is converted to - the ECMAScript true value and the IDL boolean - value false is converted to the ECMAScript - false value. -
--- -4.2.4. byte
- -- An ECMAScript value V is - converted - to an IDL byte value - by running the following algorithm: -
--
-
- Initialize x to ToNumber(V). -
- If the conversion to an IDL value is being performed due to any of the following:
-
-
-
- V is being assigned to an attribute annotated with the [EnforceRange] extended attribute, -
- V is being passed as an operation argument annotated with the [EnforceRange] extended attribute, or -
- V is being used as the value of a dictionary member annotated with the [EnforceRange] extended attribute, -
-
-
- If x is NaN, +∞, or −∞, then throw a TypeError. -
- Set x to sign(x) * floor(abs(x)). -
- If x < −27 or x > 27 − 1, then throw a TypeError. -
- Return the IDL byte value that represents the same numeric value as x. -
- - If x is not NaN and the conversion to an IDL value is being performed due to any of the following:
-
-
-
- V is being assigned to an attribute annotated with the [Clamp] extended attribute, -
- V is being passed as an operation argument annotated with the [Clamp] extended attribute, or -
- V is being used as the value of a dictionary member annotated with the [Clamp] extended attribute, -
-
-
- Set x to min(max(x, −27), 27 − 1). -
- Round x to the nearest integer, choosing the even integer if it lies halfway between two, and choosing +0 rather than −0. -
- Return the IDL byte value that represents the same numeric value as x. -
- - If x is NaN, +0, −0, +∞, or −∞, then return the IDL byte value that represents 0. -
- Set x to sign(x) * floor(abs(x)). -
- Set x to x modulo 28. -
- If x ≥ 27, return the IDL byte value that represents the same numeric value as x − 28. - Otherwise, return the IDL byte value that represents the same numeric value as x. -
- The result of converting - an IDL byte value to an ECMAScript - value is a Number that represents - the same numeric value as the IDL byte value. - The Number value will be an integer in the range [−128, 127]. -
--- -4.2.5. octet
- -- An ECMAScript value V is - converted - to an IDL octet value - by running the following algorithm: -
--
-
- Initialize x to ToNumber(V). -
- If the conversion to an IDL value is being performed due to any of the following:
-
-
-
- V is being assigned to an attribute annotated with the [EnforceRange] extended attribute, -
- V is being passed as an operation argument annotated with the [EnforceRange] extended attribute, or -
- V is being used as the value of a dictionary member annotated with the [EnforceRange] extended attribute, -
-
-
- If x is NaN, +∞, or −∞, then throw a TypeError. -
- Set x to sign(x) * floor(abs(x)). -
- If x < 0 or x > 28 − 1, then throw a TypeError. -
- Return the IDL octet value that represents the same numeric value as x. -
- - If x is not NaN and the conversion to an IDL value is being performed due to any of the following:
-
-
-
- V is being assigned to an attribute annotated with the [Clamp] extended attribute, -
- V is being passed as an operation argument annotated with the [Clamp] extended attribute, or -
- V is being used as the value of a dictionary member annotated with the [Clamp] extended attribute, -
-
-
- Set x to min(max(x, 0), 28 − 1). -
- Round x to the nearest integer, choosing the even integer if it lies halfway between two, and choosing +0 rather than −0. -
- Return the IDL octet value that represents the same numeric value as x. -
- - If x is NaN, +0, −0, +∞, or −∞, then return the IDL octet value that represents 0. -
- Set x to sign(x) * floor(abs(x)). -
- Set x to x modulo 28. -
- Return the IDL octet value that represents the same numeric value as x. -
- The result of converting - an IDL octet value to an ECMAScript - value is a Number that represents - the same numeric value as the IDL - octet value. - The Number value will be an integer in the range [0, 255]. -
--- -4.2.6. short
- -- An ECMAScript value V is - converted - to an IDL short value - by running the following algorithm: -
--
-
- Initialize x to ToNumber(V). -
- If the conversion to an IDL value is being performed due to any of the following:
-
-
-
- V is being assigned to an attribute annotated with the [EnforceRange] extended attribute, -
- V is being passed as an operation argument annotated with the [EnforceRange] extended attribute, or -
- V is being used as the value of a dictionary member annotated with the [EnforceRange] extended attribute, -
-
-
- If x is NaN, +∞, or −∞, then throw a TypeError. -
- Set x to sign(x) * floor(abs(x)). -
- If x < −215 or x > 215 − 1, then throw a TypeError. -
- Return the IDL short value that represents the same numeric value as x. -
- - If x is not NaN and the conversion to an IDL value is being performed due to any of the following:
-
-
-
- V is being assigned to an attribute annotated with the [Clamp] extended attribute, -
- V is being passed as an operation argument annotated with the [Clamp] extended attribute, or -
- V is being used as the value of a dictionary member annotated with the [Clamp] extended attribute, -
-
-
- Set x to min(max(x, −215), 215 − 1). -
- Round x to the nearest integer, choosing the even integer if it lies halfway between two, and choosing +0 rather than −0. -
- Return the IDL short value that represents the same numeric value as x. -
- - If x is NaN, +0, −0, +∞, or −∞, then return the IDL short value that represents 0. -
- Set x to sign(x) * floor(abs(x)). -
- Set x to x modulo 216. -
- If x ≥ 215, return the IDL short value that represents the same numeric value as x − 216. - Otherwise, return the IDL short value that represents the same numeric value as x. -
- The result of converting - an IDL short value to an ECMAScript - value is a Number that represents the - same numeric value as the IDL - short value. - The Number value will be an integer in the range [−32768, 32767]. -
--- -4.2.7. unsigned short
- -- An ECMAScript value V is - converted - to an IDL unsigned short value - by running the following algorithm: -
--
-
- Initialize x to ToNumber(V). -
- If the conversion to an IDL value is being performed due to any of the following:
-
-
-
- V is being assigned to an attribute annotated with the [EnforceRange] extended attribute, -
- V is being passed as an operation argument annotated with the [EnforceRange] extended attribute, or -
- V is being used as the value of a dictionary member annotated with the [EnforceRange] extended attribute, -
-
-
- If x is NaN, +∞, or −∞, then throw a TypeError. -
- Set x to sign(x) * floor(abs(x)). -
- If x < 0 or x > 216 − 1, then throw a TypeError. -
- Return the IDL unsigned short value that represents the same numeric value as x. -
- - If x is not NaN and the conversion to an IDL value is being performed due to any of the following:
-
-
-
- V is being assigned to an attribute annotated with the [Clamp] extended attribute, -
- V is being passed as an operation argument annotated with the [Clamp] extended attribute, or -
- V is being used as the value of a dictionary member annotated with the [Clamp] extended attribute, -
-
-
- Set x to min(max(x, 0), 216 − 1). -
- Round x to the nearest integer, choosing the even integer if it lies halfway between two, and choosing +0 rather than −0. -
- Return the IDL unsigned short value that represents the same numeric value as x. -
- - Set x to ToUint16(x). -
- Return the IDL unsigned short value that represents the same numeric value as x. -
- The result of converting - an IDL unsigned short value to an ECMAScript - value is a Number that - represents the same numeric value as the IDL - unsigned short value. - The Number value will be an integer in the range [0, 65535]. -
--- -4.2.8. long
- -- An ECMAScript value V is - converted - to an IDL long value - by running the following algorithm: -
--
-
- Initialize x to ToNumber(V). -
- If the conversion to an IDL value is being performed due to any of the following:
-
-
-
- V is being assigned to an attribute annotated with the [EnforceRange] extended attribute, -
- V is being passed as an operation argument annotated with the [EnforceRange] extended attribute, or -
- V is being used as the value of a dictionary member annotated with the [EnforceRange] extended attribute, -
-
-
- If x is NaN, +∞, or −∞, then throw a TypeError. -
- Set x to sign(x) * floor(abs(x)). -
- If x < −231 or x > 231 − 1, then throw a TypeError. -
- Return the IDL long value that represents the same numeric value as x. -
- - If x is not NaN and the conversion to an IDL value is being performed due to any of the following:
-
-
-
- V is being assigned to an attribute annotated with the [Clamp] extended attribute, -
- V is being passed as an operation argument annotated with the [Clamp] extended attribute, or -
- V is being used as the value of a dictionary member annotated with the [Clamp] extended attribute, -
-
-
- Set x to min(max(x, −231), 231 − 1). -
- Round x to the nearest integer, choosing the even integer if it lies halfway between two, and choosing +0 rather than −0. -
- Return the IDL long value that represents the same numeric value as x. -
- - Set x to ToInt32(x). -
- Return the IDL long value that represents the same numeric value as x. -
- The result of converting - an IDL long value to an ECMAScript - value is a Number that - represents the same numeric value as the IDL - long value. - The Number value will be an integer in the range [−2147483648, 2147483647]. -
--- -4.2.9. unsigned long
- -- An ECMAScript value V is - converted - to an IDL unsigned long value - by running the following algorithm: -
--
-
- Initialize x to ToNumber(V). -
- If the conversion to an IDL value is being performed due to any of the following:
-
-
-
- V is being assigned to an attribute annotated with the [EnforceRange] extended attribute, -
- V is being passed as an operation argument annotated with the [EnforceRange] extended attribute, or -
- V is being used as the value of a dictionary member annotated with the [EnforceRange] extended attribute, -
-
-
- If x is NaN, +∞, or −∞, then throw a TypeError. -
- Set x to sign(x) * floor(abs(x)). -
- If x < 0 or x > 232 − 1, then throw a TypeError. -
- Return the IDL unsigned long value that represents the same numeric value as x. -
- - If x is not NaN and the conversion to an IDL value is being performed due to any of the following:
-
-
-
- V is being assigned to an attribute annotated with the [Clamp] extended attribute, -
- V is being passed as an operation argument annotated with the [Clamp] extended attribute, or -
- V is being used as the value of a dictionary member annotated with the [Clamp] extended attribute, -
-
-
- Set x to min(max(x, 0), 232 − 1). -
- Round x to the nearest integer, choosing the even integer if it lies halfway between two, and choosing +0 rather than −0. -
- Return the IDL unsigned long value that represents the same numeric value as x. -
- - Set x to ToUint32(x). -
- Return the IDL unsigned long value that represents the same numeric value as x. -
- The result of converting - an IDL unsigned long value to an ECMAScript - value is a Number that - represents the same numeric value as the IDL - unsigned long value. - The Number value will be an integer in the range [0, 4294967295]. -
--- -4.2.10. long long
- -- An ECMAScript value V is - converted - to an IDL long long value - by running the following algorithm: -
--
-
- Initialize x to ToNumber(V). -
- If the conversion to an IDL value is being performed due to any of the following:
-
-
-
- V is being assigned to an attribute annotated with the [EnforceRange] extended attribute, -
- V is being passed as an operation argument annotated with the [EnforceRange] extended attribute, or -
- V is being used as the value of a dictionary member annotated with the [EnforceRange] extended attribute, -
-
-
- If x is NaN, +∞, or −∞, then throw a TypeError. -
- Set x to sign(x) * floor(abs(x)). -
- If x < −253 + 1 or x > 253 − 1, then throw a TypeError. -
- Return the IDL long long value that represents the same numeric value as x. -
- - If x is not NaN and the conversion to an IDL value is being performed due to any of the following:
-
-
-
- V is being assigned to an attribute annotated with the [Clamp] extended attribute, -
- V is being passed as an operation argument annotated with the [Clamp] extended attribute, or -
- V is being used as the value of a dictionary member annotated with the [Clamp] extended attribute, -
-
-
- Set x to min(max(x, −253 + 1), 253 − 1). -
- Round x to the nearest integer, choosing the even integer if it lies halfway between two, and choosing +0 rather than −0. -
- Return the IDL long long value that represents the same numeric value as x. -
- - If x is NaN, +0, −0, +∞, or −∞, then return the IDL long long value that represents 0. -
- Set x to sign(x) * floor(abs(x)). -
- Set x to x modulo 264. -
- If x is greater than or equal to 263, then set x to x − 264. -
- Return the IDL long long value that represents the same numeric value as x. -
- The result of converting - an IDL long long value to an ECMAScript - value is a Number value that - represents the closest numeric value to the long long, - choosing the numeric value with an even significand if there are - two equally close values ([ECMA-262], section 6.1.6). - If the long long is in the range - [−253 + 1, 253 − 1], then the Number - will be able to represent exactly the same value as the - long long. -
--- -4.2.11. unsigned long long
- -- An ECMAScript value V is - converted - to an IDL unsigned long long value - by running the following algorithm: -
--
-
- Initialize x to ToNumber(V). -
- If the conversion to an IDL value is being performed due to any of the following:
-
-
-
- V is being assigned to an attribute annotated with the [EnforceRange] extended attribute, -
- V is being passed as an operation argument annotated with the [EnforceRange] extended attribute, or -
- V is being used as the value of a dictionary member annotated with the [EnforceRange] extended attribute, -
-
-
- If x is NaN, +∞, or −∞, then throw a TypeError. -
- Set x to sign(x) * floor(abs(x)). -
- If x < 0 or x > 253 − 1, then throw a TypeError. -
- Return the IDL unsigned long long value that represents the same numeric value as x. -
- - If x is not NaN and the conversion to an IDL value is being performed due to any of the following:
-
-
-
- V is being assigned to an attribute annotated with the [Clamp] extended attribute, -
- V is being passed as an operation argument annotated with the [Clamp] extended attribute, or -
- V is being used as the value of a dictionary member annotated with the [Clamp] extended attribute, -
-
-
- Set x to min(max(x, 0), 253 − 1). -
- Round x to the nearest integer, choosing the even integer if it lies halfway between two, and choosing +0 rather than −0. -
- Return the IDL unsigned long long value that represents the same numeric value as x. -
- - If x is NaN, +0, −0, +∞, or −∞, then return the IDL unsigned long long value that represents 0. -
- Set x to sign(x) * floor(abs(x)). -
- Set x to x modulo 264. -
- Return the IDL unsigned long long value that represents the same numeric value as x. -
- The result of converting - an IDL unsigned long long value to an ECMAScript - value is a Number value that - represents the closest numeric value to the unsigned long long, - choosing the numeric value with an even significand if there are - two equally close values ([ECMA-262], section 6.1.6). - If the unsigned long long is less than or equal to 253 − 1, - then the Number will be able to - represent exactly the same value as the - unsigned long long. -
--- -4.2.12. float
- -- An ECMAScript value V is - converted - to an IDL float value - by running the following algorithm: -
--
-
- Let x be ToNumber(V). -
- If x is NaN, +Infinity or - −Infinity, then throw a TypeError. -
- - Let S be the set of finite IEEE 754 single-precision floating - point values except −0, but with two special values added: 2128 and - −2128. - -
- - Let y be the number in S that is closest - to x, selecting the number with an - even significand if there are two equally close values ([ECMA-262], section 6.1.6). - (The two special values 2128 and −2128 - are considered to have even significands for this purpose.) - -
- - If y is 2128 or −2128, then throw a TypeError. - -
- - If y is +0 and x is negative, return −0. - -
- - Return y. - -
- The result of converting - an IDL float value to an ECMAScript - value is the Number value that represents the same numeric value as the IDL - float value. -
--- -4.2.13. unrestricted float
- -- An ECMAScript value V is - converted - to an IDL unrestricted float value - by running the following algorithm: -
--
-
- Let x be ToNumber(V). -
- If x is NaN, then return the IDL unrestricted float value that represents the IEEE 754 NaN value with the bit pattern 0x7fc00000 [IEEE-754]. -
- - Let S be the set of finite IEEE 754 single-precision floating - point values except −0, but with two special values added: 2128 and - −2128. - -
- - Let y be the number in S that is closest - to x, selecting the number with an - even significand if there are two equally close values ([ECMA-262], section 6.1.6). - (The two special values 2128 and −2128 - are considered to have even significands for this purpose.) - -
- - If y is 2128, return +∞. - -
- - If y is −2128, return −∞. - -
- - If y is +0 and x is negative, return −0. - -
- - Return y. - -
-Note-- Since there is only a single ECMAScript NaN value, - it must be canonicalized to a particular single precision IEEE 754 NaN value. The NaN value - mentioned above is chosen simply because it is the quiet NaN with the lowest - value when its bit pattern is interpreted as an unsigned 32 bit integer. -
-- The result of converting - an IDL unrestricted float value to an ECMAScript - value is a Number: -
--
-
- - If the IDL unrestricted float value is a NaN, - then the Number value is NaN. - -
- - Otherwise, the Number value is - the one that represents the same numeric value as the IDL - unrestricted float value. - -
-- -4.2.14. double
- -- An ECMAScript value V is - converted - to an IDL double value - by running the following algorithm: -
--
-
- Let x be ToNumber(V). -
- If x is NaN, +Infinity or - −Infinity, then throw a TypeError. -
- - Return the IDL double value - that has the same numeric value as x. - -
- The result of converting - an IDL double value to an ECMAScript - value is the Number value that represents the - same numeric value as the IDL double value. -
--- -4.2.15. unrestricted double
- -- An ECMAScript value V is - converted - to an IDL unrestricted double value - by running the following algorithm: -
--
-
- Let x be ToNumber(V). -
- If x is NaN, then return the IDL unrestricted double value that represents the IEEE 754 NaN value with the bit pattern 0x7ff8000000000000 [IEEE-754]. -
- - Return the IDL unrestricted double value - that has the same numeric value as x. - -
-Note-- Since there is only a single ECMAScript NaN value, - it must be canonicalized to a particular double precision IEEE 754 NaN value. The NaN value - mentioned above is chosen simply because it is the quiet NaN with the lowest - value when its bit pattern is interpreted as an unsigned 64 bit integer. -
-- The result of converting - an IDL unrestricted double value to an ECMAScript - value is a Number: -
--
-
- - If the IDL unrestricted double value is a NaN, - then the Number value is NaN. - -
- - Otherwise, the Number value is - the one that represents the same numeric value as the IDL - unrestricted double value. - -
-- -4.2.16. DOMString
- -- An ECMAScript value V is - converted - to an IDL DOMString value - by running the following algorithm: -
--
-
- If V is null
- and the conversion to an IDL value is being performed due
- to any of the following:
-
-
-
- - V is being passed as an operation - argument that is annotated with [TreatNullAs=EmptyString], - -
- - V is being assigned to an attribute - annotated with [TreatNullAs=EmptyString], - -
- - V is being returned from a user object implementation of an - operation annotated with [TreatNullAs=EmptyString], or - -
- - V is being returned from a user object implementation of an - attribute annotated with [TreatNullAs=EmptyString], - -
- - Let x be ToString(V). -
- Return the IDL DOMString value that represents the same sequence of code units as the one the ECMAScript String value x represents. -
- The result of converting - an IDL DOMString value to an ECMAScript - value is the String - value that represents the same sequence of code units that the - IDL DOMString represents. -
--- -4.2.17. ByteString
- -- An ECMAScript value V is - converted - to an IDL ByteString value - by running the following algorithm: -
--
-
- Let x be ToString(V). -
- If the value of any element - of x is greater than 255, then throw a TypeError. -
- Return an IDL ByteString value - whose length is the length of x, and where the value of each element is - the value of the corresponding element of x. -
- The result of converting - an IDL ByteString value to an ECMAScript - value is a String - value whose length is the length of the ByteString, - and the value of each element of which is the value of the corresponding element - of the ByteString. -
--- -4.2.18. USVString
- -- An ECMAScript value V is - converted - to an IDL USVString value - by running the following algorithm: -
--
-
- Let string be the result of converting V - to a DOMString. -
- Return an IDL USVString value - that is the result of converting string to a sequence of Unicode scalar values. -
- An IDL USVString value is - converted - to an ECMAScript value by running the following algorithm: -
--
-
- Let scalarValues be the sequence of Unicode scalar values the USVString represents. -
- Let string be the sequence of code units that results from encoding scalarValues in UTF-16. -
- Return the String value that represents the same sequence of code units as string. -
-- -4.2.19. object
- -- IDL object - values are represented by ECMAScript Object values. -
-- An ECMAScript value V is - converted - to an IDL object value - by running the following algorithm: -
--
-
- If Type(V) is not Object, then throw a TypeError. -
- Return the IDL object value that is a reference to the same object as V. -
- The result of converting - an IDL object value to an ECMAScript - value is the Object value that represents a reference to the same object that the - IDL object represents. -
--- -4.2.20. Interface types
- -- IDL interface type - values are represented by ECMAScript Object or - Function values. -
-- An ECMAScript value V is - converted - to an IDL interface type value - by running the following algorithm (where I is the interface): -
--
-
- If Type(V) is not Object, then throw a TypeError. -
- If V is a platform object that implements I, then return the IDL interface type value that represents a reference to that platform object. -
- If V is a user object - that is considered to implement I according to the rules in section 4.9, then return the IDL interface type value that represents a reference to that - user object, with the incumbent settings object as the callback context. [HTML] -
- Throw a TypeError. -
- The result of converting - an IDL interface type - value to an ECMAScript value is the Object - value that represents a reference to the same object that the IDL - interface type value represents. -
--- -4.2.21. Dictionary types
- -- IDL dictionary type values are represented - by ECMAScript Object values. Properties on - the object (or its prototype chain) correspond to dictionary members. -
-- An ECMAScript value V is - converted - to an IDL dictionary type value - by running the following algorithm (where D is the dictionary): -
--
-
- If Type(V) is not Undefined, Null or Object, then throw a TypeError. -
- If V is a native RegExp object, then throw a TypeError. -
- Let dict be an empty dictionary value of type D; - every dictionary member - is initially considered to be not present. -
- Let dictionaries be a list consisting of D and all of D’s inherited dictionaries, - in order from least to most derived. -
- For each dictionary dictionary in dictionaries, in order:
-
-
-
- For each dictionary member member declared on dictionary, in lexicographical order:
-
-
-
- Let key be the identifier of member. -
- Let value be an ECMAScript value, depending on Type(V):
-
-
-
- Undefined -
- Null -
- value is undefined. -
- anything else -
- value is the result of calling the [[Get]] internal method on V with property name key. -
- - If value is not undefined, then:
-
-
-
- Let idlValue be the result of converting value to an IDL value whose type is the type member is declared to be of. -
- Set the dictionary member on dict with key name key to the value idlValue. This dictionary member is considered to be present. -
- - Otherwise, if value is undefined but the dictionary member has a default value, then:
-
-
-
- Let idlValue be the dictionary member’s default value. -
- Set the dictionary member on dict with key name key to the value idlValue. This dictionary member is considered to be present. -
- - - Otherwise, if value is - undefined and the - dictionary - member is a - required dictionary - member, then throw a TypeError. - -
-
- - For each dictionary member member declared on dictionary, in lexicographical order:
-
- Return dict. -
-Note-- The order that dictionary members are looked - up on the ECMAScript object are not necessarily the same as the object’s property enumeration order. -
-- An IDL dictionary value V is - converted - to an ECMAScript Object value - by running the following algorithm (where D is the dictionary): -
--
-
- Let O be a new Object value created as if by the expression
({}).
- - Let dictionaries be a list consisting of D and all of D’s inherited dictionaries, - in order from least to most derived. -
- For each dictionary dictionary in dictionaries, in order:
-
-
-
- For each dictionary member member declared on dictionary, in lexicographical order:
-
-
-
- Let key be the identifier of member. -
- If the dictionary member named key is present in V, then:
-
-
-
- Let idlValue be the value of member on V. -
- Let value be the result of converting idlValue to an ECMAScript value. -
- Call CreateDataProperty(O, key, value. -
-
-
- - For each dictionary member member declared on dictionary, in lexicographical order:
-
- Return O. -
-- -4.2.22. Enumeration types
- -- IDL enumeration types are represented by ECMAScript String - values. -
-- An ECMAScript value V is - converted - to an IDL enumeration type - value as follows (where E is the enumeration): -
--
-
- Let S be the result of calling ToString(V). -
- If S is not one of E’s enumeration values, then throw a TypeError. -
- Return the enumeration value of type E that is equal to S. -
- The result of converting - an IDL enumeration type value to an ECMAScript - value is the String - value that represents the same sequence of code units as - the enumeration value. -
--- -4.2.23. Callback function types
- -- IDL callback function types are represented by ECMAScript Function - objects, except in the [TreatNonObjectAsNull] case, - when they can be any object. -
-- An ECMAScript value V is - converted - to an IDL callback function type value - by running the following algorithm: -
--
-
- If the result of calling IsCallable(V) is false and the conversion to an IDL value - is not being performed due - to V being assigned to an attribute - whose type is a nullable - callback function - that is annotated with [TreatNonObjectAsNull], - then throw a TypeError. -
- Return the IDL callback function type value - that represents a reference to the same object that V represents, with the - incumbent settings object as the callback context. [HTML]. -
- The result of converting - an IDL callback function type - value to an ECMAScript value is a reference to the same object - that the IDL callback function type value represents. -
--- -4.2.24. Nullable types — T?
- -- IDL nullable type values are represented - by values of either the ECMAScript type corresponding to the inner IDL type, or - the ECMAScript null value. -
-- An ECMAScript value V is - converted - to an IDL nullable type T? - value (where T is the inner type) as follows: -
--
-
- - If Type(V) is not Object, and - the conversion to an IDL value is being performed due - to V being assigned to an attribute - whose type is a nullable - callback function - that is annotated with [TreatNonObjectAsNull], - then return the IDL - nullable type T? - value null. - -
- - Otherwise, if V is null or undefined, then return the IDL - nullable type T? - value null. - -
- - Otherwise, return the result of - converting V - using the rules for the inner IDL type T. - -
- The result of converting - an IDL nullable type value to an ECMAScript value is: -
--
-
- - If the IDL nullable type T? - value is null, - then the ECMAScript value is null. - -
- - Otherwise, the ECMAScript value is the result of - converting - the IDL nullable type value - to the inner IDL type T. - -
-- -4.2.25. Sequences — sequence<T>
- -- IDL sequence<T> values are represented by - ECMAScript Array values. -
-- An ECMAScript value V is converted - to an IDL sequence<T> value as follows: -
--
-
- - If V is not an object, - throw a - TypeError. - -
- - If V is a native RegExp object, - throw a - TypeError. - -
- - Let method be the result of - GetMethod(V, @@iterator). - -
- - ReturnIfAbrupt(method). - -
- - If method is undefined, - throw a - TypeError. - -
- - Return the result of - creating a sequence - of type sequence<T> - from V and method. - -
- An IDL sequence value S of type - sequence<T> is - converted - to an ECMAScript Array object as follows: -
--
-
- Let n be the length of S. -
- Let A be a new Array object created as if by the expression
[].
- - Initialize i to be 0. -
- While i < n:
-
-
-
- Let V be the value in S at index i. -
- Let E be the result of converting - V to an ECMAScript value. -
- Let P be the result of calling ToString(i). -
- Call CreateDataProperty(A, P, E). -
- Set i to i + 1. -
- - Return A. -
--4.2.25.1. Creating a sequence from an iterable
-- To create an IDL value of type sequence<T> given an - iterable iterable and an iterator getter - method, perform the following steps: -
--
-
- - Let iter be - GetIterator(iterable, method). - -
- - ReturnIfAbrupt(iter). - -
- Initialize i to be 0. -
- Repeat
-
-
-
- - Let next be IteratorStep(iter). - -
- ReturnIfAbrupt(next). -
- - If next is false, - then return an IDL sequence value of type - sequence<T> - of length i, where the value of the element - at index j is - Sj. - -
- - Let nextItem be - IteratorValue(next). - -
- ReturnIfAbrupt(nextItem). -
- - Initialize Si to the result of - converting - nextItem to an IDL value of type T. - -
- Set i to i + 1. -
-
- -Example-- The following interface defines - an attribute of a sequence - type as well as an operation - with an argument of a sequence type. -
--IDLinterface Canvas { - - sequence<DOMString> getSupportedImageCodecs(); - - void drawPolygon(sequence<double> coordinates); - sequence<double> getLastDrawnPolygon(); - - // ... -};- In an ECMAScript implementation of this interface, an Array - object with elements of type String is used to - represent a sequence<DOMString>, while an - Array with elements of type Number - represents a sequence<double>. The - Array objects are effectively passed by - value; every time the
-getSupportedImageCodecs()- function is called a new Array is - returned, and whenever an Array is - passed todrawPolygonno reference - will be kept after the call completes. --ECMAScript-// Obtain an instance of Canvas. Assume that getSupportedImageCodecs() -// returns a sequence with two DOMString values: "image/png" and "image/svg+xml". -var canvas = getCanvas(); - -// An Array object of length 2. -var supportedImageCodecs = canvas.getSupportedImageCodecs(); - -// Evaluates to "image/png". -supportedImageCodecs[0]; - -// Each time canvas.getSupportedImageCodecs() is called, it returns a -// new Array object. Thus modifying the returned Array will not -// affect the value returned from a subsequent call to the function. -supportedImageCodecs[0] = "image/jpeg"; - -// Evaluates to "image/png". -canvas.getSupportedImageCodecs()[0]; - -// This evaluates to false, since a new Array object is returned each call. -canvas.getSupportedImageCodecs() == canvas.getSupportedImageCodecs(); - - -// An Array of Numbers... -var a = [0, 0, 100, 0, 50, 62.5]; - -// ...can be passed to a platform object expecting a sequence<double>. -canvas.drawPolygon(a); - -// Each element will be converted to a double by first calling ToNumber(). -// So the following call is equivalent to the previous one, except that -// "hi" will be alerted before drawPolygon() returns. -a = [false, '', - { valueOf: function() { alert('hi'); return 100; } }, 0, - '50', new Number(62.5)]; -canvas.drawPolygon(s); - -// Modifying an Array that was passed to drawPolygon() is guaranteed not to -// have an effect on the Canvas, since the Array is effectively passed by value. -a[4] = 20; -var b = canvas.getLastDrawnPolygon(); -alert(b[4]); // This would alert "50".-- -4.2.26. Promise types — Promise<T>
- -- IDL promise type values are - represented by ECMAScript Promise - objects. -
-- An ECMAScript value V is - converted - to an IDL Promise<T> value as follows: -
--
-
- Let resolve be the original value of %Promise%.resolve.
- -Editorial note-
ECMAScript should grow a %Promise_resolve% well-known intrinsic object that can be referenced here.
-
- - Let promise be the result of calling resolve with %Promise% - as the this value and V as the single argument value. -
- Return the IDL promise type value that is a reference to the - same object as promise. -
- The result of converting - an IDL promise type value to an ECMAScript - value is the Promise value that represents a reference to the same object that the - IDL promise type represents. -
-- One can perform some steps once a promise is settled. - There can be one or two sets of steps to perform, covering when the promise is fulfilled, rejected, or both. - When a specification says to perform some steps once a promise is settled, the following steps - MUST be followed: -
--
-
- Let promise be the promise object of type Promise<T>. -
-
- Let onFulfilled be a new function object whose
- behavior when invoked is as follows:
-
-
-
- If T is void, then:
-
- Return the result of performing any steps that were required to be run if the promise was fulfilled.
- - Otherwise, T is a type other than void:
-
-
-
- Let V be the first argument to onFulfilled. -
- Let value be the result of converting - V to an IDL value of type T. -
- If there are no steps that are required to be run if the promise was fulfilled, then - return undefined. -
- Otherwise, return the result of performing any steps that were required to be run if the promise was fulfilled, - with value as the promise’s value. -
-
- - If T is void, then:
-
-
- Let onRejected be a new function object whose
- behavior when invoked is as follows:
-
-
-
- Let R be the first argument to onRejected. -
- Let reason be the result of converting - R to an IDL value of type any. -
- If there are no steps that are required to be run if the promise was rejected, then - return undefined. -
- Otherwise, return the result of performing any steps that were required to be run if the promise was rejected, - with reason as the rejection reason. -
- - Let then be the result of calling the internal [[Get]] method of promise with property name “then”. -
- If then is not callable, then throw a TypeError. -
- Return the result of calling then with promise as the this value and onFulfilled and onRejected - as its two arguments. -
-Editorial note-Include an example of how to write spec text using this term.
--- -4.2.27. Union types
- -- IDL union type values are - represented by ECMAScript values that correspond to the union’s - member types. -
-- To convert an ECMAScript value V to an IDL union type - value is done as follows: -
--
-
- If the union type - includes a nullable type and - V is null or undefined, - then return the IDL value null. -
- - Let types be the flattened member types - of the union type. - -
- - If V is null or - undefined, and - types includes a - dictionary type, then return the - result of - converting - V to that dictionary type. - -
-
- If V is a platform object, then:
-
-
-
- If types includes an interface type that V - implements, then return the IDL value that is a reference to the object V. -
- If types includes object, then return the IDL value - that is a reference to the object V. -
- -
- If V is a native RegExp object, then:
-
-
-
- If types includes RegExp, then return the - result of converting - V to RegExp. -
- If types includes object, then return the IDL value - that is a reference to the object V. -
- -
- If V is a DOMException platform object, then:
-
-
-
- If types includes DOMException or - Error, then return the - result of converting - V to that type. -
- If types includes object, then return the IDL value - that is a reference to the object V. -
- -
- If V is a native Error object (that is, it has an [[ErrorData]] internal slot), then:
-
-
-
- If types includes Error, then return the - result of converting - V to Error. -
- If types includes object, then return the IDL value - that is a reference to the object V. -
- -
- If V is an object with an [[ArrayBufferData]] internal slot, then:
-
-
-
- If types includes ArrayBuffer, then return the - result of converting - V to ArrayBuffer. -
- If types includes object, then return the IDL value - that is a reference to the object V. -
- -
- If V is an object with a [[DataView]] internal slot, then:
-
-
-
- If types includes DataView, then return the - result of converting - V to DataView. -
- If types includes object, then return the IDL value - that is a reference to the object V. -
- -
- If V is an object with a [[TypedArrayName]] internal slot, then:
-
-
-
- If types includes a typed array type - whose name is the value of V’s [[TypedArrayName]] internal slot, then return the - result of converting - V to that type. -
- If types includes object, then return the IDL value - that is a reference to the object V. -
- -
- If IsCallable(V) is true, then:
-
-
-
- If types includes a callback function - type, then return the result of - converting - V to that callback function type. -
- If types includes object, then return the IDL value - that is a reference to the object V. -
- -
- If V is any kind of object except for
- a native RegExp object, then:
-
-
-
-
- If types includes a sequence type, then
-
-
-
- - Let method be the result of - GetMethod(V, @@iterator). - -
- - ReturnIfAbrupt(method). - -
- - If method is not - undefined, - return the result of - creating a - sequence of that type from V and - method. - -
- -
- If types includes a frozen array type, then
-
-
-
- - Let method be the result of - GetMethod(V, @@iterator). - -
- - ReturnIfAbrupt(method). - -
- - If method is not - undefined, - return the result of - creating a - frozen array of that type from V and - method. - -
- - If types includes a dictionary type, then return the - result of converting - V to that dictionary type. -
- If types includes a callback interface - type, then return the result of - converting - V to that interface type. -
- If types includes object, then return the IDL value - that is a reference to the object V. -
- -
- If types includes a sequence type, then
-
-
- If V is a Boolean value, then:
-
-
-
- - If types includes a boolean, - then return the result of converting - V to boolean. - -
- -
- If V is a Number value, then:
-
-
-
- - If types includes a numeric type, - then return the result of converting - V to that numeric type. - -
- - - If types includes a string type, - then return the result of - converting - V to that type. - -
- - If types includes a numeric type, - then return the result of converting - V to that numeric type. - -
- - If types includes a boolean, - then return the result of converting - V to boolean. - -
- - Throw a TypeError. - -
- An IDL union type value is - converted to an ECMAScript value - as follows. If the value is an object - reference to a special object that represents an ECMAScript undefined - value, then it is converted to the ECMAScript - undefined value. Otherwise, - the rules for converting the specific type - of the IDL union type value as described in this section (4.2). -
--- -4.2.28. RegExp
- -- IDL RegExp values are represented by - ECMAScript RegExp objects. -
-- An ECMAScript value V is - converted - to an IDL RegExp value - by running the following algorithm: -
--
-
- If Type(V) is not Object,
- or V is not a native RegExp object,
- then set V to be a newly created RegExp object created as if by the
- expression
new RegExp(V), whereRegExpis the standard built-in constructor with that name - from the current global environment. --Note-Note that this can result in an exception being thrown, if V, when converted to a string, - does not have valid regular expression syntax.
-
- - Return the IDL RegExp value that is a reference to the same object as V. -
- The result of converting - an IDL RegExp value to an ECMAScript - value is the RegExp value that represents a reference to the same object that the - IDL RegExp represents. -
--- -4.2.29. Error
- -- IDL Error values are represented - by native ECMAScript Error objects and - platform objects for DOMExceptions. -
-- An ECMAScript value V is - converted - to an IDL Error value - by running the following algorithm: -
--
-
- If Type(V) is not Object, - or V does not have an [[ErrorData]] internal slot, then throw a TypeError. -
- Return the IDL Error value that is a reference to the same object as V. -
- The result of converting - an IDL Error value to an ECMAScript - value is the Error value that represents a reference to the same object that the - IDL Error represents. -
--- -4.2.30. DOMException
- -- IDL DOMException values are represented - by platform objects for DOMExceptions. -
-- An ECMAScript value V is - converted - to an IDL DOMException value - by running the following algorithm: -
--
-
- If Type(V) is not Object, - or V is not a platform object that represents a DOMException, then throw a TypeError. -
- Return the IDL DOMException value that is a reference to the same object as V. -
- The result of converting - an IDL DOMException value to an ECMAScript - value is the Object value that represents a reference to the same object that the - IDL DOMException represents. -
--- -4.2.31. Buffer source types
- -- Values of the IDL buffer source types - are represented by objects of the corresponding ECMAScript class. -
-- An ECMAScript value V is - converted - to an IDL ArrayBuffer value - by running the following algorithm: -
--
-
- If Type(V) is not Object, - or V does not have an [[ArrayBufferData]] internal slot, - or IsDetachedBuffer(V) is true, - then throw a TypeError. - -
- Return the IDL ArrayBuffer value that is a reference to the same object as V. -
- An ECMAScript value V is - converted - to an IDL DataView value - by running the following algorithm: -
--
-
- If Type(V) is not Object, - or V does not have a [[DataView]] internal slot, - then throw a TypeError. -
- Return the IDL DataView value that is a reference to the same object as V. -
- An ECMAScript value V is - converted - to an IDL Int8Array, - Int16Array, - Int32Array, - Uint8Array, - Uint16Array, - Uint32Array, - Uint8ClampedArray, - Float32Array or - Float64Array value - by running the following algorithm: -
--
-
- Let T be the IDL type V is being converted to. -
- If Type(V) is not Object, - or V does not have a [[TypedArrayName]] internal slot - with a value equal to the name of T, - then throw a TypeError. -
- Return the IDL value of type T that is a reference to the same object as V. -
- The result of converting - an IDL value of any buffer source type - to an ECMAScript value is the Object value that represents - a reference to the same object that the IDL value represents. -
-- When getting a reference to - or getting a copy of the bytes held by a buffer source - that is an ECMAScript ArrayBuffer, DataView - or typed array object, these steps MUST be followed: -
--
-
- Let O be the ECMAScript object that is the buffer source. -
- Initialize arrayBuffer to O. -
- Initialize offset to 0. -
- Initialize length to 0. -
- If O has a [[ViewedArrayBuffer]] internal slot, then:
-
-
-
- Set arrayBuffer to the value of O’s [[ViewedArrayBuffer]] internal slot. -
- If arrayBuffer is undefined, then - throw a TypeError. -
- Set offset to the value of O’s [[ByteOffset]] internal slot. -
- Set length to the value of O’s [[ByteLength]] internal slot. -
- - Otherwise, set length to the value of O’s [[ArrayBufferByteLength]] internal slot. -
- If IsDetachedBuffer(O), then - throw a TypeError. -
- Let data be the value of O’s [[ArrayBufferData]] internal slot. -
- Return a reference to or copy of (as required) the length bytes in data - starting at byte offset offset. -
- To detach an ArrayBuffer, - these steps MUST be followed: -
--
-
- Let O be the ECMAScript object that is the ArrayBuffer. -
- DetachArrayBuffer(O). -
--4.2.32. Frozen arrays — FrozenArray<T>
- -- Values of frozen array types are represented by frozen ECMAScript - Array object references. -
-- An ECMAScript value V is - converted - to an IDL FrozenArray<T> value - by running the following algorithm: -
--
-
- Let values be the result of - converting - V to IDL type sequence<T>. -
- Return the result of - creating a frozen array - from values. -
- To create a frozen array from a sequence - of values of type T, follow these steps: -
--
-
- Let array be the result of - converting - the sequence of values to an ECMAScript value. -
- Perform SetIntegrityLevel(array,
"frozen").
- - Return array. -
- The result of converting - an IDL FrozenArray<T> value to an ECMAScript - value is the Object value that represents a reference - to the same object that the IDL FrozenArray<T> represents. -
- ---4.2.32.1. Creating a frozen array from an iterable
-- To create an IDL value of type FrozenArray<T> given an - iterable iterable and an iterator getter - method, perform the following steps: -
--
-
- Let values be the result of - creating - a sequence of type sequence<T> - from iterable and method. -
- Return the result of creating a frozen - array from values. -
-- -4.3. ECMAScript-specific extended attributes
- -- This section defines a number of - extended attributes - whose presence affects only the ECMAScript binding. -
- --- -4.3.1. [Clamp]
- -- If the [Clamp] - extended attribute - appears on an operation argument, - writable attribute or - dictionary member - whose type is one of the integer types, - it indicates that when an ECMAScript Number is - converted to the IDL type, out of range values will be clamped to the range - of valid values, rather than using the operators that use a modulo operation - (ToInt32, ToUint32, etc.). -
-- The [Clamp] - extended attribute MUST - take no arguments. -
-- The [Clamp] extended attribute - MUST NOT appear on a read only - attribute, or an attribute, operation argument or dictionary member - that is not of an integer type. It also MUST NOT - be used in conjunction with the [EnforceRange] - extended attribute. -
-- See the rules for converting ECMAScript values to the various IDL integer - types in section 4.2 - for the specific requirements that the use of - [Clamp] entails. -
- --Example-- In the following IDL fragment, - two operations are declared that - take three octet arguments; one uses - the [Clamp] extended attribute - on all three arguments, while the other does not: -
--IDLinterface GraphicsContext { - void setColor(octet red, octet green, octet blue); - void setColorClamped([Clamp] octet red, [Clamp] octet green, [Clamp] octet blue); -};- In an ECMAScript implementation of the IDL, a call to setColorClamped with - Number values that are out of range for an - octet are clamped to the range [0, 255]. -
--ECMAScript// Get an instance of GraphicsContext. -var context = getGraphicsContext(); - -// Calling the non-[Clamp] version uses ToUint8 to coerce the Numbers to octets. -// This is equivalent to calling setColor(255, 255, 1). -context.setColor(-1, 255, 257); - -// Call setColorClamped with some out of range values. -// This is equivalent to calling setColorClamped(0, 255, 255). -context.setColorClamped(-1, 255, 257);-- -4.3.2. [Constructor]
- -- If the [Constructor] - extended attribute - appears on an interface, it indicates that - the interface object for this interface - will have an [[Construct]] internal method, - allowing objects implementing the interface to be constructed. -
-- Multiple [Constructor] extended - attributes may appear on a given interface. -
-- The [Constructor] - extended attribute MUST either - take no arguments or - take an argument list. - The bare form,
-[Constructor], has the same meaning as - using an empty argument list,[Constructor()]. For each - [Constructor] extended attribute - on the interface, there will be a way to construct an object that implements - the interface by passing the specified arguments. -- The prose definition of a constructor MUST - either return an IDL value of a type corresponding to the interface - the [Constructor] - extended attribute appears on, or throw an exception. -
-- The [Constructor] and - [NoInterfaceObject] - extended attributes must not be specified on the same interface. -
-- The [Constructor] extended attribute - MUST NOT be used on a callback interface. -
-- See section 4.6.1.1 - below for details on how a constructor - for an interface is to be implemented. -
- --Example-- The following IDL defines two interfaces. The second has the - [Constructor] extended - attribute, while the first does not. -
--IDLinterface NodeList { - Node item(unsigned long index); - readonly attribute unsigned long length; + +interface Derived : Ancestor { + inherit attribute TheType theIdentifier; }; - -[Constructor, - Constructor(double radius)] -interface Circle { - attribute double r; - attribute double cx; - attribute double cy; - readonly attribute double circumference; -};- An ECMAScript implementation supporting these interfaces would - have a [[Construct]] property on the - Circle interface object which would - return a new object that implements the interface. It would take - either zero or one argument. The - NodeList interface object would not - have a [[Construct]] property. -
--ECMAScriptvar x = new Circle(); // The uses the zero-argument constructor to create a - // reference to a platform object that implements the - // Circle interface. - -var y = new Circle(1.25); // This also creates a Circle object, this time using - // the one-argument constructor. - -var z = new NodeList(); // This would throw a TypeError, since no - // [Constructor] is declared.-- -4.3.3. [EnforceRange]
- -- If the [EnforceRange] - extended attribute - appears on an operation argument, - writable regular attribute or - dictionary member - whose type is one of the integer types, - it indicates that when an ECMAScript Number is - converted to the IDL type, out of range values will cause an exception to - be thrown, rather than converted to being a valid value using the operators that use a modulo operation - (ToInt32, ToUint32, etc.). The Number - will be rounded towards zero before being checked against its range. -
-- The [EnforceRange] - extended attribute MUST - take no arguments. -
-- The [EnforceRange] extended attribute - MUST NOT appear on a read only - attribute, a static attribute, - or an attribute, operation argument or dictionary member - that is not of an integer type. It also MUST NOT - be used in conjunction with the [Clamp] - extended attribute. -
-- See the rules for converting ECMAScript values to the various IDL integer - types in section 4.2 - for the specific requirements that the use of - [EnforceRange] entails. -
- --Example-- In the following IDL fragment, - two operations are declared that - take three octet arguments; one uses - the [EnforceRange] extended attribute - on all three arguments, while the other does not: -
--IDLinterface GraphicsContext { - void setColor(octet red, octet green, octet blue); - void setColorEnforcedRange([EnforceRange] octet red, [EnforceRange] octet green, [EnforceRange] octet blue); -};- In an ECMAScript implementation of the IDL, a call to setColorEnforcedRange with - Number values that are out of range for an - octet will result in an exception being - thrown. -
--ECMAScript// Get an instance of GraphicsContext. -var context = getGraphicsContext(); - -// Calling the non-[EnforceRange] version uses ToUint8 to coerce the Numbers to octets. -// This is equivalent to calling setColor(255, 255, 1). -context.setColor(-1, 255, 257); - -// When setColorEnforcedRange is called, Numbers are rounded towards zero. -// This is equivalent to calling setColor(0, 255, 255). -context.setColorEnforcedRange(-0.9, 255, 255.2); - -// The following will cause a TypeError to be thrown, since even after -// rounding the first and third argument values are out of range. -context.setColorEnforcedRange(-1, 255, 256);-- -4.3.4. [Exposed]
-- If the [Exposed] - extended attribute - appears on an interface, - partial interface, - namespace, - partial namespace, or - an individual interface member or - namespace member, - it indicates that the construct is exposed - on a particular set of global interfaces, rather than the default of - being exposed only on the primary global interface. -
-- The [Exposed] - extended attribute - MUST either - take an identifier or - take an identifier list. - Each of the identifiers mentioned MUST be - a global name. -
-- Every construct that the [Exposed] - extended attribute - can be specified on has an exposure set, - which is a set of interfaces - defining which global environments the construct can be used in. - The exposure set - for a given construct is defined as follows: -
--
-
-
-
If the [Exposed] - extended attribute - is specified on the construct, then the exposure set - is the set of all interfaces that have a global name - that is listed in the extended attribute's argument.
-
- -
-
If the [Exposed] - extended attribute - does not appear on a construct, then its - exposure set is defined - implicitly, depending on the type of construct:
--
-
- interface -
- namespace -
- The exposure set of the - interface or namespace only contains the - primary global interface. -
- partial interface -
- partial namespace -
- The exposure set of the partial - interface or namespace is the exposure - set of the original interface or namespace definition. -
- interface member -
- The exposure set of the interface member - is the exposure set of the interface or - partial interface the member is declared on. -
- namespace member -
- The exposure set of the - namespace member is the exposure - set of the namespace or partial namespace the member is declared on. -
-
- If [Exposed] appears on an - overloaded operation, - then it MUST appear identically on all overloads. -
-- The [Exposed] extended attribute - MUST NOT be specified on both an interface - member and a partial interface definition the interface member is declared on. - Similarly, the [Exposed] extended attribute - MUST NOT be specified on both a namespace - member and a partial namespace definition the namespace member is declared on. -
-- If [Exposed] appears an interface member, then - the interface member's exposure set - MUST be a subset of the exposure set of the interface or partial interface it's a - member of. Similarly, if [Exposed] appears on a - namespace member, then the namespace member's exposure set MUST be a - subset of the exposure set of the - namespace or partial namespace it's a member of. -
-- An interface's exposure set - MUST be a subset of the - exposure set of all - of the interface's consequential - interfaces. -
-- If an interface X - inherits from another interface - Y then the - exposure set of - X MUST be a subset of the - exposure set of - Y. -
-- An interface, namespace, interface member, or namespace member is exposed in a given ECMAScript global environment if the - ECMAScript global object implements an interface that is in the construct's exposure set, and either: -
--
-
- the relevant settings object for the ECMAScript global object is a secure context; or -
- the construct is not available only in secure contexts. -
-Note-Since it is not possible for the relevant settings object - for an ECMAScript global object to change whether it is a - secure context or not over time, an implementation's - decision to create properties for an interface or interface member - can be made once, at the time the - initial objects - are created.
-- See - section 4.6, - section 4.6.5, - section 4.6.6, - section 4.6.7 and - section 4.6.8 - for the specific requirements that the use of - [Exposed] entails. -
--Example-[Exposed] - is intended to be used to control whether interfaces, namespaces, or individual - interface or namespace members are available for use only in workers, only in the - Window, or in both.
-The following IDL fragment shows how that might be achieved:
--IDL
+[PrimaryGlobal] -interface Window { - ... +When the
+stringifierkeyword is used +in a regular attribute declaration, it indicates that objects implementing the +interface will be stringified to the value of the attribute. See §3.2.4.2 Stringifiers for details.interface interface_identifier { + stringifier attribute DOMString identifier; }; - -// By using the same identifier Worker for both SharedWorkerGlobalScope -// and DedicatedWorkerGlobalScope, both can be addressed in an [Exposed] -// extended attribute at once. -[Global=Worker] -interface SharedWorkerGlobalScope : WorkerGlobalScope { - ... +
+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" + ε +
++ ++The following IDL fragment demonstrates how attributes can be declared on an interface:
+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; }; - -[Global=Worker] -interface DedicatedWorkerGlobalScope : WorkerGlobalScope { - ... + +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; }; - -// Dimensions is available for use in workers and on the main thread. -[Exposed=(Window,Worker), Constructor(double width, double height)] -interface Dimensions { - readonly attribute double width; - readonly attribute double height; +
+3.2.3. Operations
+An operation is an interface member (matching
+static OperationRest ,stringifier OperationRest ,serializer OperationRest ,ReturnType OperationRest orSpecialOperation ) +that defines a behavior that can be invoked on objects implementing the interface. +There are three kinds of operation:-
+
-
+
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... */); }; - -// WorkerNavigator is only available in workers. Evaluating WorkerNavigator -// in the global scope of a worker would give you its interface object, while -// doing so on the main thread will give you a ReferenceError. -[Exposed=Worker] -interface WorkerNavigator { - ... +
+ -
+
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... */); }; - -// Node is only available on the main thread. Evaluating Node -// in the global scope of a worker would give you a ReferenceError. -interface Node { - ... +
+ -
+
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... */); }; - -// MathUtils is available for use in workers and on the main thread. -[Exposed=(Window,Worker)] -namespace MathUtils { - double someComplicatedFunction(double x, double y); +
+
If an operation has an identifier but no
+statickeyword, then it declares a regular operation. +If the operation has one or more special keywords used in its declaration (that is, any keyword matchingSpecial , or +thestringifierkeyword), +then it declares a special operation. A single operation can declare +both a regular operation and a special operation; +see §3.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 (matchingType ) followed by an identifier (matchingArgumentName ).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 /* , ... */); }; - -// WorkerUtils is only available in workers. Evaluating WorkerUtils -// in the global scope of a worker would give you its namespace object, while -// doing so on the main thread will give you a ReferenceError. -[Exposed=Worker] -namespace WorkerUtils { - void setPriority(double x); +
+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 /* , ... */); }; - -// NodeUtils is only available in the main thread. Evaluating NodeUtils -// in the global scope of a worker would give you a ReferenceError. -namespace NodeUtils { - DOMString getAllText(Node node); -};
-- -4.3.5. [ImplicitThis]
-- If the [ImplicitThis] - extended attribute - appears on an interface, - it indicates that when a Function corresponding - to one of the interface’s operations - is invoked with the null or undefined - value as the this value, that the ECMAScript global - object will be used as the this value instead. - This is regardless of whether the calling code is in strict mode. -
-- The [ImplicitThis] - extended attribute MUST - take no arguments. -
-- See section 4.6.7 - for the specific requirements that the use of - [ImplicitThis] entails. -
--Note-The [ImplicitThis] - extended attribute - is intended for use on the Window - interface as defined - in HTML5 ([HTML5], section 5.2).
--Example-In the following example, the Window - interface is defined - with the [ImplicitThis] - extended attribute.
--IDL[ImplicitThis] -interface Window { - ... - attribute DOMString name; - void alert(DOMString message); -};Since the Window object is used as - the ECMAScript global object, calls to its functions can be made - without an explicit object, even in strict mode:
--ECMAScript"use strict"; - -window.alert("hello"); // Calling alert with an explicit window object works. -alert("hello"); // This also works, even though we are in strict mode. -alert.call(null, "hello"); // As does passing null explicitly as the this value. - -// This does not apply to getters for attributes on the interface, though. -// The following will throw a TypeError. -Object.getOwnPropertyDescriptor(Window.prototype, "name").get.call(null);-- -4.3.6. [Global] and [PrimaryGlobal]
- -- If the [Global] - or [PrimaryGlobal] - extended attribute - appears on an interface, - it indicates that objects implementing this interface can - be used as the global object in an ECMAScript environment, - and that the structure of the prototype chain and how - properties corresponding to interface members - will be reflected on the prototype objects will be different from other - interfaces. Specifically: -
--
-
- Any named properties - will be exposed on an object in the prototype chain – the - named properties object – - rather than on the object itself. -
- Interface members from the - interface (or - consequential interfaces) - will correspond to properties on the object itself rather than on - interface prototype objects. -
-Note-- Placing named properties on an object in the prototype chain - is done so that variable declarations and bareword assignments - will shadow the named property with a property on the global - object itself. -
-- Placing properties corresponding to interface members on - the object itself will mean that common feature detection - methods like the following will work: -
--ECMAScriptvar indexedDB = window.indexedDB || window.webkitIndexedDB || - window.mozIndexedDB || window.msIndexedDB; - -var requestAnimationFrame = window.requestAnimationFrame || - window.mozRequestAnimationFrame || ...;- Because of the way variable declarations are handled in - ECMAScript, the code above would result in the
-window.indexedDB- andwindow.requestAnimationFrameevaluating - toundefined, as the shadowing variable - property would already have been created before the - assignment is evaluated. -- If the [Global] or - [PrimaryGlobal] - extended attributes - is used on an interface, then: -
--
-
- The interface MUST NOT define a named property setter. -
- The interface MUST NOT also be declared with the [OverrideBuiltins] - extended attribute. -
- The interface MUST NOT inherit from another interface with the - [OverrideBuiltins] extended attribute. -
- Any other interface MUST NOT inherit from it. -
- If [Global] or [PrimaryGlobal] is specified on - a partial interface - definition, then that partial interface definition MUST - be the part of the interface definition that defines - the named property getter. -
-- The [Global] and [PrimaryGlobal] - extended attribute MUST NOT - be used on an interface that can have more - than one object implementing it in the same ECMAScript global environment. -
--Note-This is because the named properties object, - which exposes the named properties, is in the prototype chain, and it would not make - sense for more than one object’s named properties to be exposed on an object that - all of those objects inherit from.
-- If an interface is declared with the [Global] or - [PrimaryGlobal] - extended attribute, then - there MUST NOT be more than one - interface member across - the interface and its consequential interfaces - with the same identifier. - There also MUST NOT be more than - one stringifier, - more than one serializer, - or more than one iterable declaration, - maplike declaration or - setlike declaration - across those interfaces. -
--Note-This is because all of the members of the interface and its consequential - interfaces get flattened down on to the object that implements the interface.
-- The [Global] and - [PrimaryGlobal] extended attributes - can also be used to give a name to one or more global interfaces, - which can then be referenced by the [Exposed] - extended attribute. -
-- The [Global] and - [PrimaryGlobal] - extended attributes MUST either - take no arguments - or take an identifier list. -
-- If the [Global] or - [PrimaryGlobal] - extended attribute - is declared with an identifier list argument, then those identifiers are the interface’s - global names; otherwise, the interface has - a single global name, which is the interface's identifier. -
--Note-The identifier argument list exists so that more than one global interface can - be addressed with a single name in an [Exposed] - extended attribute.
-- The [Global] and - [PrimaryGlobal] - extended attributes - MUST NOT be declared on the same - interface. The [PrimaryGlobal] - extended attribute MUST be declared on - at most one interface. The interface [PrimaryGlobal] - is declared on, if any, is known as the primary global interface. -
-- See section 4.6.4, - section 4.8.3 and - section 4.8.7 - for the specific requirements that the use of - [Global] and [PrimaryGlobal] - entails for named properties, - and section 4.6.5, - section 4.6.6 and - section 4.6.7 - for the requirements relating to the location of properties - corresponding to interface members. -
--Example-- The [PrimaryGlobal] - extended attribute is intended - to be used by the Window interface as defined in - HTML5 ([HTML5], section 5.2). ([Global] - is intended to be used by worker global interfaces.) - The Window interface exposes frames as properties on the Window - object. Since the Window object also serves as the - ECMAScript global object, variable declarations or assignments to the named properties - will result in them being replaced by the new value. Variable declarations for - attributes will not create a property that replaces the existing one. -
--IDL[PrimaryGlobal] -interface Window { - getter any (DOMString name); - attribute DOMString name; - // ... -};- The following HTML document illustrates how the named properties on the - Window object can be shadowed, and how - the property for an attribute will not be replaced when declaring - a variable of the same name: -
--HTML<!DOCTYPE html> -<title>Variable declarations and assignments on Window</title> -<iframe name=abc></iframe> -<!-- Shadowing named properties --> -<script> - window.abc; // Evaluates to the iframe's Window object. - abc = 1; // Shadows the named property. - window.abc; // Evaluates to 1. -</script> - -<!-- Preserving properties for IDL attributes --> -<script> - Window.prototype.def = 2; // Places a property on the prototype. - window.hasOwnProperty("length"); // Evaluates to true. - length; // Evaluates to 1. - def; // Evaluates to 2. -</script> -<script> - var length; // Variable declaration leaves existing property. - length; // Evaluates to 1. - var def; // Variable declaration creates shadowing property. - def; // Evaluates to undefined. -</script>-- -4.3.7. [LegacyArrayClass]
- -- If the [LegacyArrayClass] - extended attribute - appears on an interface - that is not defined to inherit - from another, it indicates that the internal [[Prototype]] - property of its interface prototype object - will be the Array prototype object rather than - the Object prototype object. This allows - Array methods to be used more easily - with objects implementing the interface. -
-- The [LegacyArrayClass] extended attribute - MUST take no arguments. - It MUST NOT be used on an interface that - has any inherited interfaces. -
--Note-- Interfaces using [LegacyArrayClass] will - need to define a “length” attribute - of type unsigned long that exposes the length - of the array-like object, in order for the inherited Array - methods to operate correctly. Such interfaces would typically also - support indexed properties, - which would provide access to the array elements. -
-- See section 4.6.3 for the - specific requirements that the use of [LegacyArrayClass] - entails. -
-- - -Example-- The following IDL fragment - defines two interfaces - that use [LegacyArrayClass]. -
--IDL-
+[LegacyArrayClass] -interface ItemList { - attribute unsigned long length; - getter object getItem(unsigned long index); - setter object setItem(unsigned long index, object item); ++ +The following IDL fragment demonstrates how regular operations can be declared on an interface:
+interface Dimensions { + attribute unsigned long width; + attribute unsigned long height; }; - -[LegacyArrayClass] -interface ImmutableItemList { - readonly attribute unsigned long length; - getter object getItem(unsigned long index); -};
- In an ECMAScript implementation of the above two interfaces, - with appropriate definitions for getItem, setItem and removeItem, - Array methods to inspect and - modify the array-like object can be used. -
--ECMAScriptvar list = getItemList(); // Obtain an instance of ItemList. - -list.concat(); // Clone the ItemList into an Array. -list.pop(); // Remove an item from the ItemList. -list.unshift({ }); // Insert an item at index 0.- ImmutableItemList has a read only - length attribute - and no indexed property setter. The - mutating Array methods will generally not - succeed on objects implementing ImmutableItemList. - The exact behavior depends on the definition of the Array methods - themselves ([ECMA-262], section 22.1.3). -
--- -4.3.8. [LegacyUnenumerableNamedProperties]
- -- If the [LegacyUnenumerableNamedProperties] - extended attribute - appears on a interface - that supports named properties, - it indicates that all the interface's named properties are unenumerable. -
-- The [LegacyUnenumerableNamedProperties] - extended attribute MUST - take no arguments - and MUST NOT appear on an interface - that does not define a named property getter. -
-- If the [LegacyUnenumerableNamedProperties] - extended attribute is specified on an interface, then it applies to all its derived interfaces and - MUST NOT be specified on any of them. -
-- See section 4.8.10 - for the specific requirements that the use of - [LegacyUnenumerableNamedProperties] - entails. -
--- -4.3.9. [LenientSetter]
-- If the [LenientSetter] - extended attribute - appears on a read only - regular attribute, - it indicates that a no-op setter will be generated for the attribute’s - accessor property. This results in erroneous assignments to the property - in strict mode to be ignored rather than causing an exception to be thrown. -
--Warning-- Specifications SHOULD NOT use [LenientSetter] - unless required for compatibility reasons. Pages have been observed - where authors have attempted to polyfill an IDL attribute by assigning - to the property, but have accidentally done so even if the property - exists. In strict mode, this would cause an exception to be thrown, - potentially breaking page. Without [LenientSetter], - this could prevent a browser from shipping the feature. -
-- Specification authors who - wish to use this feature are strongly advised to discuss this on the - public-script-coord@w3.org - mailing list before proceeding. -
-- The [LenientThis] extended attribute - MUST - take no arguments. - It MUST NOT be used on anything other than - a read only - regular attribute. -
-- An attribute with the [LenientSetter] - extended attribute MUST NOT also be declared - with the [PutForwards] - or [Replaceable] extended attributes. -
-- See the Attributes section below for how - [LenientSetter] - is to be implemented. -
--Example-- The following IDL fragment defines an interface that uses the - [LenientSetter] extended - attribute. -
--IDLinterface Example { - [LenientSetter] readonly attribute DOMString x; - readonly attribute DOMString y; -};- An ECMAScript implementation that supports this interface will - have a setter on the accessor property that correspond to x, - which allows any assignment to be ignored in strict mode. -
--ECMAScript"use strict"; - -var example = getExample(); // Get an instance of Example. - -// Fine; while we are in strict mode, there is a setter that is a no-op. -example.x = 1; - -// Throws a TypeError, since we are in strict mode and there is no setter. -example.y = 1;-- -4.3.10. [LenientThis]
-- If the [LenientThis] - extended attribute - appears on a regular attribute, - it indicates that invocations of the attribute’s getter or setter - with a this value that is not an - object that implements the interface - on which the attribute appears will be ignored. -
-- The [LenientThis] extended attribute - MUST - take no arguments. - It MUST NOT be used on a - static attribute. -
--Warning-- Specifications SHOULD NOT use [LenientThis] - unless required for compatibility reasons. Specification authors who - wish to use this feature are strongly advised to discuss this on the - public-script-coord@w3.org - mailing list before proceeding. -
-- See the Attributes section below for how - [LenientThis] - is to be implemented. -
--Example-- The following IDL fragment defines an interface that uses the - [LenientThis] extended - attribute. -
--IDLinterface Example { - [LenientThis] attribute DOMString x; - attribute DOMString y; -};- An ECMAScript implementation that supports this interface will - allow the getter and setter of the accessor property that corresponds - to x to be invoked with something other than an Example - object. -
--ECMAScriptvar example = getExample(); // Get an instance of Example. -var obj = { }; - -// Fine. -example.x; - -// Ignored, since the this value is not an Example object and [LenientThis] is used. -Object.getOwnPropertyDescriptor(Example.prototype, "x").get.call(obj); - -// Also ignored, since Example.prototype is not an Example object and [LenientThis] is used. -Example.prototype.x; - -// Throws a TypeError, since Example.prototype is not an Example object. -Example.prototype.y;-- -4.3.11. [NamedConstructor]
-- If the [NamedConstructor] - extended attribute - appears on an interface, - it indicates that the ECMAScript global object will have a property with the - specified name whose value is a constructor function that can - create objects that implement the interface. - Multiple [NamedConstructor] extended - attributes may appear on a given interface. -
-- The [NamedConstructor] - extended attribute MUST either - take an identifier or - take a named argument list. - The first form,
-[NamedConstructor=identifier], has the same meaning as - using an empty argument list,[NamedConstructor=identifier()]. For each - [NamedConstructor] extended attribute - on the interface, there will be a way to construct an object that implements - the interface by passing the specified arguments to the constructor function - that is the value of the aforementioned property. -- The identifier used for the named constructor MUST NOT - be the same as that used by an [NamedConstructor] - extended attribute on another interface, MUST NOT - be the same as an identifier of an interface - that has an interface object, - and MUST NOT be one of the - reserved identifiers. -
-- The [NamedConstructor] extended attribute - MUST NOT be used on a callback interface. -
-- See section 4.6.2 - below for details on how named constructors - are to be implemented. -
- --Example-- The following IDL defines an interface that uses the - [NamedConstructor] extended - attribute. -
--IDL[NamedConstructor=Audio, - NamedConstructor=Audio(DOMString src)] -interface HTMLAudioElement : HTMLMediaElement { - // ... -};- An ECMAScript implementation that supports this interface will - allow the construction of HTMLAudioElement - objects using the Audio constructor. -
--ECMAScripttypeof Audio; // Evaluates to 'function'. - -var a1 = new Audio(); // Creates a new object that implements - // HTMLAudioElement, using the zero-argument - // constructor. - -var a2 = new Audio('a.flac'); // Creates an HTMLAudioElement using the - // one-argument constructor.-- -4.3.12. [NewObject]
- -- If the [NewObject] - extended attribute - appears on a regular - or static - operation, - then it indicates that when calling the operation, - a reference to a newly created object - MUST always be returned. -
-- The [NewObject] - extended attribute MUST - take no arguments. -
-- The [NewObject] - extended attribute MUST NOT - be used on anything other than a regular - or static - operation - whose return type - is an interface type or - a promise type. -
--Example-- As an example, this extended attribute is suitable for use on - the createElement - operation on the Document - interface ([DOM], section 6.5), - since a new object should always be returned when - it is called. -
--IDLinterface Document : Node { - [NewObject] Element createElement(DOMString localName); - ... -};--4.3.13. [NoInterfaceObject]
- -- If the [NoInterfaceObject] - extended attribute - appears on an interface, - it indicates that an - interface object - will not exist for the interface in the ECMAScript binding. -
--Warning-- The [NoInterfaceObject] extended attribute - SHOULD NOT be used on interfaces that are not - solely used as supplemental interfaces, - unless there are clear Web compatibility reasons for doing so. Specification authors who - wish to use this feature are strongly advised to discuss this on the - public-script-coord@w3.org - mailing list before proceeding. -
-- The [NoInterfaceObject] extended attribute - MUST take no arguments. -
-- If the [NoInterfaceObject] extended attribute - is specified on an interface, then the [Constructor] - extended attribute MUST NOT also be specified on that interface. - A [NamedConstructor] extended attribute is fine, - however. -
-- The [NoInterfaceObject] extended attribute - MUST NOT be specified on an interface that has any - static operations defined on it. -
-- The [NoInterfaceObject] extended attribute - MUST NOT be specified on a callback interface - unless it has a constant declared on it. - This is because callback interfaces without constants never have - interface objects. -
-- An interface that does not have the [NoInterfaceObject] extended - attribute specified MUST NOT inherit - from an interface that has the [NoInterfaceObject] extended - attribute specified. -
-- See section 4.2.20 - for the specific requirements that the use of - [NoInterfaceObject] entails. -
--Example-- The following IDL - fragment defines two interfaces, one whose interface object - is exposed on the ECMAScript global object, and one whose isn’t: -
--IDLinterface Storage { - void addEntry(unsigned long key, any value); + +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); }; - -[NoInterfaceObject] -interface Query { - any lookupEntry(unsigned long key); -};- An ECMAScript implementation of the above IDL would allow - manipulation of Storage’s - prototype, but not Query’s. -
-ECMAScript+
+typeof Storage; // evaluates to "object" - -// Add some tracing alert() call to Storage.addEntry. -var fn = Storage.prototype.addEntry; -Storage.prototype.addEntry = function(key, value) { - alert('Calling addEntry()'); - return fn.call(this, key, value); +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); }; - -typeof Query; // evaluates to "undefined" -var fn = Query.prototype.lookupEntry; // exception, Query isn’t defined -
-- -4.3.14. [OverrideBuiltins]
- -- If the [OverrideBuiltins] - extended attribute - appears on an interface, - it indicates that for a platform object implementing the interface, - properties corresponding to all of - the object’s supported property names - will appear to be on the object, - regardless of what other properties exist on the object or its - prototype chain. This means that named properties will always shadow - any properties that would otherwise appear on the object. - This is in contrast to the usual behavior, which is for named properties - to be exposed only if there is no property with the - same name on the object itself or somewhere on its prototype chain. -
-- The [OverrideBuiltins] - extended attribute MUST - take no arguments - and MUST NOT appear on an interface - that does not define a named property getter - or that also is declared with the [Global] - or [PrimaryGlobal] - extended attribute. If the extended attribute is specified on - a partial interface - definition, then that partial interface definition MUST - be the part of the interface definition that defines - the named property getter. -
-- See section 4.8.1 - and section 4.8.7 - for the specific requirements that the use of - [OverrideBuiltins] entails. -
-- - - -Example-- The following IDL fragment - defines two interfaces, - one that has a named property getter - and one that does not. -
--IDL-
+interface StringMap { - readonly attribute unsigned long length; - getter DOMString lookup(DOMString key); +Extended attributes that take an argument list ([
+Constructor] and +[NamedConstructor], of those +defined in this specification) and callback functions are also considered to be variadic when the...token is used in their argument lists.+ +The following IDL fragment defines an interface that has + two variadic operations:
+interface IntegerSet { + readonly attribute unsigned long cardinality; + + void union(long... ints); + void intersection(long... ints); }; - -[OverrideBuiltins] -interface StringMap2 { - readonly attribute unsigned long length; - getter DOMString lookup(DOMString key); -};
- In an ECMAScript implementation of these two interfaces, - getting certain properties on objects implementing - the interfaces will result in different values: -
--ECMAScript// Obtain an instance of StringMap. Assume that it has "abc", "length" and -// "toString" as supported property names. -var map1 = getStringMap(); - -// This invokes the named property getter. -map1.abc; - -// This fetches the "length" property on the object that corresponds to the -// length attribute. -map1.length; - -// This fetches the "toString" property from the object's prototype chain. -map1.toString; - - -// Obtain an instance of StringMap2. Assume that it also has "abc", "length" -// and "toString" as supported property names. -var map2 = getStringMap2(); - -// This invokes the named property getter. -map2.abc; - -// This also invokes the named property getter, despite the fact that the "length" -// property on the object corresponds to the length attribute. -map2.length; - -// This too invokes the named property getter, despite the fact that "toString" is -// a property in map2's prototype chain. -map2.toString;-- -4.3.15. [PutForwards]
- -- If the [PutForwards] - extended attribute - appears on a read only - regular attribute declaration whose type is - an interface type, - it indicates that assigning to the attribute will have specific behavior. - Namely, the assignment is “forwarded” to the attribute (specified by - the extended attribute argument) on the object that is currently - referenced by the attribute being assigned to. -
-- The [PutForwards] extended - attribute MUST take an identifier. - Assuming that: -
--
-
- - A is the attribute - on which the [PutForwards] - extended attribute appears, - -
- - I is the interface - on which A is declared, - -
- - J is the interface type - that A is declared to be of, and - -
- - N is the identifier - argument of the extended attribute, - -
- then there MUST be another - attribute B - declared on J whose identifier - is N. Assignment of a value to the attribute A - on an object implementing I will result in that value - being assigned to attribute B of the object that A - references, instead. -
-- Note that [PutForwards]-annotated - attributes can be - chained. That is, an attribute with the [PutForwards] - extended attribute - can refer to an attribute that itself has that extended attribute. - There MUST NOT exist a cycle in a - chain of forwarded assignments. A cycle exists if, when following - the chain of forwarded assignments, a particular attribute on - an interface is - encountered more than once. -
-- An attribute with the [PutForwards] - extended attribute MUST NOT also be declared - with the [LenientSetter] or - [Replaceable] extended attributes. -
-- The [PutForwards] - extended attribute MUST NOT be used - on an attribute that - is not read only. -
-- The [PutForwards] extended attribute - MUST NOT be used on a - static attribute. -
-- The [PutForwards] extended attribute - MUST NOT be used on an attribute declared on - a callback interface. -
-- See the Attributes section below for how - [PutForwards] - is to be implemented. -
--Example-- The following IDL fragment defines interfaces for names and people. - The [PutForwards] extended - attribute is used on the name attribute - of the Person interface to indicate - that assignments to that attribute result in assignments to the - full attribute of the - Person object: -
--IDL+
+interface Name { - attribute DOMString full; - attribute DOMString family; - attribute DOMString given; +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" +
+3.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:
++ +
++ Special operation + Keyword + Purpose + + Getters + getter+Defines behavior for when an object is indexed for property retrieval. + + Setters + setter+Defines behavior for when an object is indexed for property + assignment or creation. + + Deleters + deleter+Defines behavior for when an object is indexed for property deletion. + + Legacy callers + legacycaller+Defines behavior for when an object is called as if it were a function. + + Stringifiers + stringifier+Defines how an object is converted into a DOMString. ++ Serializers + serializer+Defines how an object is converted into a serialized form. + Not all language bindings support all of the six kinds of special +object behavior. When special operations are declared using +operations with no identifier, then in language bindings that do +not support the particular kind of special operations there simply +will not be such functionality.
++ +The following IDL fragment defines an interface with a getter and a setter:
+interface Dictionary { + readonly attribute unsigned long propertyCount; + + getter double (DOMString propertyName); + setter void (DOMString propertyName, double propertyValue); }; - -interface Person { - [PutForwards=full] readonly attribute Name name; - attribute unsigned short age; -};
- In the ECMAScript binding, this would allow assignments to the - “name” property: -
--ECMAScriptvar p = getPerson(); // Obtain an instance of Person. - -p.name = 'John Citizen'; // This statement... -p.name.full = 'John Citizen'; // ...has the same behavior as this one.-- -4.3.16. [Replaceable]
- -- If the [Replaceable] - extended attribute - appears on a read only - regular attribute, - it indicates that setting the corresponding property on the - platform object will result in - an own property with the same name being created on the object - which has the value being assigned. This property will shadow - the accessor property corresponding to the attribute, which - exists on the interface prototype object. -
-- The [Replaceable] - extended attribute MUST - take no arguments. -
-- An attribute with the [Replaceable] - extended attribute MUST NOT also be declared - with the [LenientSetter] or - [PutForwards] extended attributes. -
-- The [Replaceable] - extended attribute MUST NOT be used - on an attribute that - is not read only. -
-- The [Replaceable] extended attribute - MUST NOT be used on a - static attribute. -
-- The [Replaceable] extended attribute - MUST NOT be used on an attribute declared on - a callback interface. -
-- See section 4.6.6 - for the specific requirements that the use of - [Replaceable] entails. -
--Example-- The following IDL fragment - defines an interface - with an operation - that increments a counter, and an attribute - that exposes the counter’s value, which is initially 0: -
--IDLinterface Counter { - [Replaceable] readonly attribute unsigned long value; - void increment(); -};- Assigning to the “value” property - on a platform object implementing Counter - will shadow the property that corresponds to the - attribute: -
--ECMAScriptvar counter = getCounter(); // Obtain an instance of Counter. -counter.value; // Evaluates to 0. - -counter.hasOwnProperty("value"); // Evaluates to false. -Object.getPrototypeOf(counter).hasOwnProperty("value"); // Evaluates to true. - -counter.increment(); -counter.increment(); -counter.value; // Evaluates to 2. - -counter.value = 'a'; // Shadows the property with one that is unrelated - // to Counter::value. - -counter.hasOwnProperty("value"); // Evaluates to true. - -counter.increment(); -counter.value; // Evaluates to 'a'. - -delete counter.value; // Reveals the original property. -counter.value; // Evaluates to 3.-- -4.3.17. [SameObject]
- -- If the [SameObject] - extended attribute - appears on a read only - attribute, then it - indicates that when getting the value of the attribute on a given - object, the same value MUST always - be returned. -
-- The [SameObject] - extended attribute MUST - take no arguments. -
-- The [SameObject] - extended attribute MUST NOT - be used on anything other than a read only - attribute - whose type is an interface type - or object. -
--Example-- As an example, this extended attribute is suitable for use on - the implementation - attribute on the Document - interface ([DOM], section 6.5), - since the same object is always returned for a given - Document object. -
--IDLinterface Document : Node { - [SameObject] readonly attribute DOMImplementation implementation; - ... -};-- -4.3.18. [SecureContext]
- -- If the [SecureContext] - extended attribute - appears on an interface, - partial interface, - namespace, - partial namespace, - interface member, or - namespace member, - it indicates that the construct is exposed - only within a - secure context - ([SECURE-CONTEXTS], section 2). -
-- The [SecureContext] - extended attribute MUST - take no arguments. -
-- The [SecureContext] - extended attribute MUST NOT - be used on anything other than an - interface, - partial interface, - namespace, - partial namespace, - interface member, or - namespace member. -
-- Whether a construct that the [SecureContext] - extended attribute - can be specified on is available only in secure contexts - is defined as follows: -
--
-
-
-
If the [SecureContext] - extended attribute - is specified on the construct, then it is - available only in secure contexts.
-
- -
-
Otherwise, if the [SecureContext] - extended attribute - does not appear on a construct, then whether it is - available only in secure contexts - depends on the type of construct:
--
-
- interface -
- namespace -
- The interface or namespace is not - available only in secure contexts. - -
- partial interface -
- partial namespace -
- The partial interface or partial namespace is available only in secure - contexts if and only if the original interface or namespace definition - is. - -
- interface member -
- The interface member is available only in secure contexts - if and only if the interface or partial interface the member is declared on is. - -
- namespace member -
- The namespace member is available only in secure contexts - if and only if the namspace or partial namespace the member is declared on is. -
-
-Note-- Whether a construct is - available only in secure contexts - influences whether it is exposed in a given - ECMAScript global environment. -
-- If [SecureContext] appears on an - overloaded operation, - then it MUST appear on all overloads. -
-- The [SecureContext] extended attribute - MUST NOT be specified on both an interface member and the - interface or partial interface definition the interface member is declared on, or - on both a namespace member and the namespace or partial namespace definition the - namespace member is declared on. -
-- An interface without the [SecureContext] extended attribute - MUST NOT inherit from another interface - that does specify [SecureContext]. -
--Example-The following IDL fragment defines an interface - with one operation that is executable from all - contexts, and two which are executable only from secure contexts.
- -- -IDLinterface PowerfulFeature { - // This call will succeed in all contexts. - Promise <Result> calculateNotSoSecretResult(); - - // This operation will not be exposed to a non-secure context. In such a context, - // there will be no "calculateSecretResult" property on PowerfulFeature.prototype. - [SecureContext] Promise<Result> calculateSecretResult(); - - // The same applies here: the attribute will not be exposed to a non-secure context, - // and in a non-secure context there will be no "secretBoolean" property on - // PowerfulFeature.prototype. - [SecureContext] readonly attribute boolean secretBoolean; -};-- -4.3.19. [TreatNonObjectAsNull]
- -- If the [TreatNonObjectAsNull] - extended attribute - appears on a callback function, - then it indicates that any value assigned to an attribute - whose type is a nullable - callback function - that is not an object will be converted to - the null value. -
--Warning-- Specifications SHOULD NOT use [TreatNonObjectAsNull] - unless required to specify the behavior of legacy APIs or for consistency with these - APIs. Specification authors who - wish to use this feature are strongly advised to discuss this on the - public-script-coord@w3.org - mailing list before proceeding. At the time of writing, the only known - valid use of [TreatNonObjectAsNull] - is for the callback functions used as the type - of event handler IDL attributes - ([HTML5], section 6.1.6.1) - such as
-onclickandonerror. -- See section 4.2.24 - for the specific requirements that the use of - [TreatNonObjectAsNull] entails. -
--Example-- The following IDL fragment defines an interface that has one - attribute whose type is a [TreatNonObjectAsNull]-annotated - callback function and another whose type is a - callback function without the extended attribute: -
--IDLcallback OccurrenceHandler = void (DOMString details); - -[TreatNonObjectAsNull] -callback ErrorHandler = void (DOMString details); - -interface Manager { - attribute OccurrenceHandler? handler1; - attribute ErrorHandler? handler2; -};- In an ECMAScript implementation, assigning a value that is not - an object (such as a Number value) - to handler1 will have different behavior from that when assigning - to handler2: -
--ECMAScriptvar manager = getManager(); // Get an instance of Manager. - -manager.handler1 = function() { }; -manager.handler1; // Evaluates to the function. - -try { - manager.handler1 = 123; // Throws a TypeError. -} catch (e) { -} - -manager.handler2 = function() { }; -manager.handler2; // Evaluates to the function. - -manager.handler2 = 123; -manager.handler2; // Evaluates to null.-- -4.3.20. [TreatNullAs]
- -- If the [TreatNullAs] - extended attribute - appears on an attribute - or operation argument whose type is - DOMString, - it indicates that a null value - assigned to the attribute or passed as the operation argument will be - handled differently from its default handling. Instead of being stringified - to “null”, which is the default, - it will be converted to the empty string “”. -
-- If [TreatNullAs] is specified on - an operation itself, and that operation is on a callback interface, - then it indicates that a user object implementing the interface will have the return - value of the function that implements the operation handled in the same way as for operation arguments - and attributes, as above. -
-- The [TreatNullAs] - extended attribute MUST take the identifier -
-EmptyString. -- The [TreatNullAs] extended attribute - MUST NOT be specified on an operation argument, - attribute or operation return value whose type is not DOMString. -
--Note-This means that even an attribute of type DOMString? must not - use [TreatNullAs], since null - is a valid value of that type.
-- The [TreatNullAs] extended attribute - also MUST NOT be specified on an operation on - a non-callback interface. -
-- See section 4.2.16 - for the specific requirements that the use of - [TreatNullAs] entails. -
--Example-- The following IDL fragment defines an interface that has one - attribute with the [TreatNullAs] - extended attribute, and one operation with an argument that has - the extended attribute: -
--IDLinterface Dog { - attribute DOMString name; - [TreatNullAs=EmptyString] attribute DOMString owner; - - boolean isMemberOfBreed([TreatNullAs=EmptyString] DOMString breedName); -};- An ECMAScript implementation implementing the Dog - interface would convert a null value - assigned to the “owner” property or passed as the - argument to the
-isMemberOfBreedfunction - to the empty string rather than"null": --ECMAScriptvar d = getDog(); // Assume d is a platform object implementing the Dog - // interface. - -d.name = null; // This assigns the string "null" to the .name - // property. - -d.owner = null; // This assigns the string "" to the .owner property. - -d.isMemberOfBreed(null); // This passes the string "" to the isMemberOfBreed - // function.--4.3.21. [Unforgeable]
- -- If the [Unforgeable] - extended attribute - appears on a non-static - attribute - or non-static - operations, it indicates - that the attribute or operation will be reflected as an ECMAScript property in - a way that means its behavior cannot be modified and that performing - a property lookup on the object will always result in the attribute’s - property value being returned. In particular, the property will be - non-configurable and will exist as an own property on the object - itself rather than on its prototype. -
-- If the [Unforgeable] - extended attribute - appears on an interface, - it indicates that all of the non-static - attributes - and non-static - operations declared on - that interface and its consequential interfaces - will be similarly reflected as own ECMAScript properties on objects - that implement the interface, rather than on the prototype. -
-- An attribute or operation is said to be unforgeable - on a given interface A if any of the following are true: -
--
-
- The attribute or operation is declared on A or one - of A’s consequential interfaces, - and is annotated with the [Unforgeable] - extended attribute. -
- The attribute or operation is declared on A or one - of A’s consequential interfaces, - and that interface is annotated with the [Unforgeable] - extended attribute. -
- There exists an interface B, which is either A or one of - A’s consequential interfaces, - B is annotated with the [Unforgeable] - extended attribute, - and the attribute or operation is declared on one of B’s consequential interfaces. -
- The [Unforgeable] - extended attribute MUST - take no arguments. -
-- The [Unforgeable] - extended attribute MUST NOT appear on - anything other than an attribute, - non-static operation - or an interface. If it does - appear on an operation, then - it MUST appear on all operations with - the same identifier on that interface. -
-- If an attribute or operation X is unforgeable - on an interface A, and A is one of the - inherited interfaces - of another interface B, then B and all of its - consequential interfaces - MUST NOT have a non-static attribute or - regular operation with the same - identifier as X. -
--Note-For example, the following is disallowed:
-IDL+
+interface A1 { - [Unforgeable] readonly attribute DOMString x; +In language bindings that do not support property getters and setters, + objects implementing Dictionary will not + have that special behavior.
+Defining a special operation with an identifier is equivalent to separating the special operation out into its own +declaration without an identifier. This approach is allowed to +simplify prose descriptions of an interface’s operations.
++ ++The following two interfaces are equivalent:
+interface Dictionary { + readonly attribute unsigned long propertyCount; + + getter double getProperty(DOMString propertyName); + setter void setProperty(DOMString propertyName, double propertyValue); }; -interface B1 : A1 { - void x(); // Invalid; would be shadowed by A1's x. +
+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); }; - -interface B2 : A1 { }; -B2 implements Mixin; -interface Mixin { - void x(); // Invalid; B2's copy of x would be shadowed by A1's x. +
+A given special keyword must not +appear twice on an operation.
+Getters and setters come in two varieties: ones that +take a
+DOMStringas a property name, +known as named property getters and named property setters, +and ones that take anunsigned longas a property index, known as indexed property getters and indexed property setters. +There is only one variety of deleter: named property deleters. +See §3.2.4.4 Indexed properties and §3.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.
+3.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
+legacycallerkeyword.interface interface_identifier { + legacycaller return_type identifier(/* arguments... */); + legacycaller return_type (/* arguments... */); }; - -[Unforgeable] -interface A2 { - readonly attribute DOMString x; +
+If multiple legacy callers are specified on an interface, overload resolution +is used to determine which legacy caller is invoked when the object is called +as if it were a function.
+Legacy callers must not be defined to return a promise type.
+Legacy callers are universally recognised as an undesirable feature. They exist + only so that legacy Web platform features can be specified. Legacy callers + should not be used in specifications unless required to + specify the behavior of legacy APIs, and even then this should be discussed on + the public-script-coord@w3.org mailing list before proceeding.
++ ++The following IDL fragment defines an interface with a legacy caller.
+interface NumberQuadrupler { + // This operation simply returns four times the given number x. + legacycaller double compute(double x); }; -interface B3 : A2 { - void x(); // Invalid; would be shadowed by A2's x. +
+An ECMAScript implementation supporting this interface would + allow a platform object that implements
+NumberQuadruplerto be called as a function:var f = getNumberQuadrupler(); // Obtain an instance of NumberQuadrupler. + +f.compute(3); // This evaluates to 12. +f(3); // This also evaluates to 12.
+3.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
+stringifierkeyword.interface interface_identifier { + stringifier DOMString identifier(); + stringifier DOMString (); }; - -interface B4 : A2 { }; -B4 implements Mixin; -interface Mixin { - void x(); // Invalid; B4's copy of x would be shadowed by A2's x. +
+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
+stringifierkeyword +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 A3 { }; -A3 implements A2; -interface B5 : A3 { - void x(); // Invalid; would be shadowed by A3's mixed-in copy of A2's x. -};
- See section 4.6.6, - section 4.6.7, - section 4.8, - section 4.8.1 and - section 4.8.7 - for the specific requirements that the use of - [Unforgeable] entails. -
--Example-- The following IDL fragment defines - an interface that has two attributes, - one of which is designated as [Unforgeable]: -
--IDLinterface System { - [Unforgeable] readonly attribute DOMString username; - readonly attribute long long loginTime; -};- In an ECMAScript implementation of the interface, the username attribute will be exposed as a non-configurable property on the - object itself: -
--ECMAScriptvar system = getSystem(); // Get an instance of System. - -system.hasOwnProperty("username"); // Evaluates to true. -system.hasOwnProperty("loginTime"); // Evaluates to false. -System.prototype.hasOwnProperty("username"); // Evaluates to false. -System.prototype.hasOwnProperty("loginTime"); // Evaluates to true. - -try { - // This call would fail, since the property is non-configurable. - Object.defineProperty(system, "username", { value: "administrator" }); -} catch (e) { } - -// This defineProperty call would succeed, because System.prototype.loginTime -// is configurable. -var forgedLoginTime = 5; -Object.defineProperty(System.prototype, "loginTime", { value: forgedLoginTime }); - -system.loginTime; // So this now evaluates to forgedLoginTime.--4.3.22. [Unscopable]
- -- If the [Unscopable] - extended attribute - appears on a regular attribute - or regular operation, it - indicates that an object that implements an interface with the given - interface member will not include its property name in any object - environment record with it as its base object. The result of this is - that bare identifiers matching the property name will not resolve to - the property in a
-withstatement. This is achieved by - including the property name on the - interface prototype object’s - @@unscopables property’s value. -- The [Unscopable] - extended attribute MUST - take no arguments. -
-- The [Unscopable] - extended attribute MUST NOT appear on - anything other than a regular attribute - or regular operation. -
-- See section 4.6.3 - for the specific requirements that the use of - [Unscopable] entails. -
--Note-For example, with the following IDL:
--IDLinterface Thing { - void f(); - [Unscopable] g(); -};the “f” property an be referenced with a bare identifier - in a
-withstatement but the “g” property cannot:-ECMAScriptvar thing = getThing(); // An instance of Thing -with (thing) { - f; // Evaluates to a Function object. - g; // Throws a ReferenceError. -}-- -4.4. Security
- -- Certain algorithms in the sections below are defined to - perform a security check on a given - object. This check is used to determine whether a given - operation invocation or - attribute access should be - allowed. The security check takes the following four inputs: -
--
-
- the platform object on - which the operation invocation or attribute access is being done, -
- the ECMAScript global environment associated with the - Function object that implements the - operation or attribute, -
- the identifier - of the operation or attribute, and -
- the type of the Function object – - “method” (when it corresponds to an IDL operation), or - “getter” or “setter” (when it corresponds to the - getter or setter function of an IDL attribute). -
-Note-The expectation is that the HTML specification defines how a - security check is performed, and that it will either throw an - appropriate exception or return normally. [HTML]
--- -4.5. Overload resolution algorithm
- -- In order to define how overloaded function invocations are resolved, the - overload resolution algorithm - is defined. Its input is an effective overload set, - S, and a list of ECMAScript values, arg0..n−1. - Its output is a pair consisting of the operation or - extended attribute of one of S’s entries - and a list of IDL values or the special value “missing”. The algorithm behaves as follows: -
--
-
- Let maxarg be the length of the longest type list of the entries in S. -
- Initialize argcount to be min(maxarg, n). - -
- Remove from S all entries whose type list is not of length argcount. - -
- If S is empty, then throw a TypeError. - -
- Initialize d to −1. - -
- - Initialize method to - undefined. - - -
- If there is more than one entry in S, then set - d to be the distinguishing argument index - for the entries of S. - -
- Initialize values to be an empty list, where each entry will be either an IDL value or the special value “missing”. - -
- Initialize i to 0. - -
- While i < d:
-
-
-
- Let V be argi. -
- Let type be the type at index i in the type list of any entry in S.
- -Note
All entries in S at this point have the same type and optionality value at index i.
- - Let optionality be the value at index i in the list of optionality values of any entry in S. -
- If optionality is “optional” and V is undefined, then:
-
-
-
- If the argument at index i is declared with a default value, - then append to values that default value. -
- Otherwise, append to values the special value “missing”. -
- - Otherwise, append to values the result of converting - V to IDL type type. -
- Set i to i + 1. -
-
- - If i = d, then:
-
-
-
- Let V be argi.
- Note
This is the argument that will be used to resolve which overload is selected.
-
- - If V is undefined, and there is an entry in S - whose list of optionality values has “optional” at index i, - then remove from S all other entries. - -
- Otherwise: if V is null or undefined,
- and there is an entry in S that has one of the following types at position i of its type list,
-
-
-
- a nullable type -
- a dictionary type -
- a union type that - includes a nullable type or that - has a dictionary type in its flattened members -
-
- -
- Otherwise: if V is a platform object, and
- there is an entry in S that has one of the following types at position i of its type list,
-
-
-
- an interface type that V implements -
- object -
- a nullable version of any of the above types -
- a union type or a nullable union type - that has one of the above types in its flattened member types -
-
- -
- Otherwise: if V is a RegExp object and
- there is an entry in S that has one of the following types at position i of its type list,
-
-
-
- RegExp -
- object -
- a nullable version of either of the above types -
- a union type or nullable union type - that has one of the above types in its flattened member types -
-
- -
- Otherwise: if V is a DOMException platform object and
- there is an entry in S that has one of the following types at position i of its type list,
-
-
-
- DOMException -
- Error -
- object -
- a nullable version of either of the above types -
- a union type or nullable union type - that has one of the above types in its flattened member types -
-
- -
- Otherwise: if V is an Error object (that is, it has an [[ErrorData]] internal slot) and
- there is an entry in S that has one of the following types at position i of its type list,
-
-
-
- Error -
- object -
- a nullable version of either of the above types -
- a union type or nullable union type - that has one of the above types in its flattened member types -
-
- -
- Otherwise: if V is an object with an [[ArrayBufferData]] internal slot and
- there is an entry in S that has one of the following types at position i of its type list,
-
-
-
- ArrayBuffer -
- object -
- a nullable version of either of the above types -
- a union type or nullable union type - that has one of the above types in its flattened member types -
-
- -
- Otherwise: if V is an object with a [[DataView]] internal slot and
- there is an entry in S that has one of the following types at position i of its type list,
-
-
-
- DataView -
- object -
- a nullable version of either of the above types -
- a union type or nullable union type - that has one of the above types in its flattened member types -
-
- -
- Otherwise: if V is an object with a [[TypedArrayName]] internal slot and
- there is an entry in S that has one of the following types at position i of its type list,
-
-
-
- a typed array type whose name - is equal to the value of V’s [[TypedArrayName]] internal slot -
- object -
- a nullable version of either of the above types -
- a union type or nullable union type - that has one of the above types in its flattened member types -
-
- -
- Otherwise: if IsCallable(V) is true,
- and there is an entry in S that has one of the following types at position i of its type list,
-
-
-
- a callback function type -
- object -
- a nullable version of any of the above types -
- a union type or nullable union type - that has one of the above types in its flattened member types -
-
- -
- Otherwise: if V is any kind of object except for
- a native RegExp object, and
- there is an entry in S that has one of the
- following types at position i of its type list,
-
-
-
- a sequence type -
- a frozen array type -
- a nullable version of any of the above types -
- a union type or nullable union type - that has one of the above types in its flattened member types - -
-
-
- - Let method be the result of - GetMethod(V, @@iterator). - -
- - ReturnIfAbrupt(method). - -
-
- -
- Otherwise: if V is any kind of object except for
- a native RegExp object, and
- there is an entry in S that has one of the following types at position i of its type list,
-
-
-
- a callback interface type -
- a dictionary type -
- object -
- a nullable version of any of the above types -
- a union type or nullable union type - that has one of the above types in its flattened member types -
-
- -
- Otherwise: if V is a Boolean value,
- and there is an entry in S that has one of the following types at position i of its type list,
-
-
-
- boolean -
- a nullable boolean -
- a union type or nullable union type - that has one of the above types in its flattened member types -
-
- -
- Otherwise: if V is a Number value,
- and there is an entry in S that has one of the following types at position i of its type list,
-
-
-
- a numeric type -
- a nullable numeric type -
- a union type or nullable union type - that has one of the above types in its flattened member types -
-
- -
- Otherwise: if there is an entry in S that has one of the following types at position i of its type list,
-
-
-
- a string type -
- a nullable version of any of the above types -
- a union type or nullable union type - that has one of the above types in its flattened member types -
-
- -
- Otherwise: if there is an entry in S that has one of the following types at position i of its type list,
-
-
-
- a numeric type -
- a nullable numeric type -
- a union type or nullable union type - that has one of the above types in its flattened member types -
-
- -
- Otherwise: if there is an entry in S that has one of the following types at position i of its type list,
-
-
-
- boolean -
- a nullable boolean -
- a union type or nullable union type - that has one of the above types in its flattened member types -
-
- - - Otherwise: if there is an entry in S that has any at position i - of its type list, - then remove from S all other entries. - - -
- - Otherwise: - throw a TypeError. - -
-
- - Let V be argi.
-
- Let callable be the operation or extended attribute - of the single entry in S. - -
-
- If i = d and method is not undefined, then
-
-
-
- - Let V be argi. - -
- - Let T be the type at index i in the - type list of the remaining entry in S. - -
- - If T is a sequence type, then - append to values the result of - creating a sequence - of type T from - V and method. - -
- - Otherwise, T is a frozen array type. - Append to values the result of - creating a frozen array - of type T from - V and method. - -
- - Set i to i + 1. - -
-
- -
- While i < argcount:
-
-
-
- Let V be argi. -
- Let type be the type at index i in the type list of the remaining entry in S. -
- Let optionality be the value at index i in the list of optionality values of the remaining entry in S. -
- If optionality is “optional” and V is undefined, then:
-
-
-
- If the argument at index i is declared with a default value, - then append to values that default value. -
- Otherwise, append to values the special value “missing”. -
- - Otherwise, append to values the result of - converting V to IDL type type. -
- Set i to i + 1. -
-
- - While i is less than the number of arguments callable is declared to take:
-
-
-
- If callable’s argument at index i is declared with a default value, - then append to values that default value. -
- Otherwise, if callable’s argument at index i is not variadic, then append to values the special value “missing”. -
- Set i to i + 1. -
-
- - Return the pair <callable, values>. -
-Note-- The overload resolution algorithm performs both the identification - of which overloaded operation, constructor, etc. is being called, - and the conversion of the ECMAScript argument values to their - corresponding IDL values. Informally, it operates as follows. -
-First, the selection of valid overloads is done by considering - the number of ECMAScript arguments that were passed in to the function:
--
-
- If there are more arguments passed in than the longest - overload argument list, then they are ignored. -
- After ignoring these trailing arguments, only overloads - that can take this exact number of arguments are considered. - If there are none, then a TypeError is thrown. -
Once we have a set of possible overloads with the right number - of arguments, the ECMAScript values are converted from left to right. - The nature of the restrictions on overloading means that if we - have multiple possible overloads at this point, then there will - be one position in the argument list that will be used to - distinguish which overload we will finally select; this is - the distinguishing - argument index.
-We first convert the arguments to the left of the distinguishing - argument. (There is a requirement that an argument to the left of - the distinguishing argument index has the same type as in the other - overloads, at the same index.) Then we inspect the type of the - ECMAScript value that is passed in at the distinguishing argument - index to determine which IDL type it may correspond to. - This allows us to select the final overload that will - be invoked. If the value passed in is undefined - and there is an overload with an optional argument at this position, then - we will choose that overload. If there is no valid overload for the type of - value passed in here, then we throw a TypeError. - The inspection of the value at the distinguishing argument index does not have any side effects; - the only side effects that come from running the overload resolution - algorithm are those that come from converting the ECMAScript values - to IDL values.
-At this point, we have determined which overload to use. We now - convert the remaining arguments, from the distinguishing argument onwards, - again ignoring any additional arguments that were ignored due to being passed - after the last possible argument.
-When converting an optional argument’s ECMAScript value to its equivalent IDL value, - undefined will be converted into - the optional argument’s default value, - if it has one, or a special value “missing” otherwise.
-Optional arguments corresponding to a final, variadic argument do not treat - undefined as a special “missing” value, however. - The undefined value is converted to the type - of variadic argument as would be done for a non-optional argument.
--- -4.6. Interfaces
- -- For every interface that - is exposed in a given - ECMAScript global environment and: -
--
-
- is a callback interface - that has constants declared on it, or -
- is a non-callback interface - that is not declared with the [NoInterfaceObject] - extended attribute, -
- a corresponding property MUST exist on the - ECMAScript environment's global object. - The name of the property is the identifier of the interface, - and its value is an object called the interface object. -
-- The property has the attributes { [[Writable]]: true, [[Enumerable]]: false, [[Configurable]]: true }. - The characteristics of an interface object are described in section 4.6.1 - below. -
- -- In addition, for every [NamedConstructor] - extended attribute on an exposed interface, a corresponding property MUST - exist on the ECMAScript global object. The name of the property is the - identifier that occurs directly after the - “=”, and its value is an object called a - named constructor, which allows - construction of objects that implement the interface. The property has the - attributes { [[Writable]]: true, [[Enumerable]]: false, [[Configurable]]: true }. - The characteristics of a named constructor are described in - section 4.6.2 - below. -
- --- -4.6.1. Interface object
- -- The interface object for a given non-callback interface - is a function object. - It has properties that correspond to - the constants and - static operations - defined on that interface, as described in sections - 4.6.5 and - 4.6.7 - below. -
-- The [[Prototype]] internal property of - an interface object for a non-callback interface is determined as - follows: -
--
-
- - If the interface inherits from some other interface, the value - of [[Prototype]] is the interface - object for that other interface. - -
- - If the interface doesn't inherit from any other interface, - the value of [[Prototype]] is - %FunctionPrototype%. - -
- An interface object for a non-callback interface MUST have a property named “prototype” - with attributes - { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false } - whose value is an object called the interface prototype object. This object has properties - that correspond to the regular attributes and - regular operations defined on the interface, - and is described in more detail in - section 4.6.3 - below. -
--Note-Since an interface object for a non-callback interface is a function object the
-typeofoperator will return - "function" when applied to - such an interface object.- The internal [[Prototype]] property - of an interface object for a callback interface MUST be - the Object.prototype object. -
-- -Note-Remember that interface objects for callback interfaces only exist if they have - constants declared on them; - when they do exist, they are not function objects.
--- -4.6.1.1. Interface object [[Call]] method
- -- If the interface is declared with a - [Constructor] extended attribute, - then the interface object - can be called as a function to create an object that implements that - interface. Interfaces that do not have a constructor will throw - an exception when called as a function. -
- - -- The internal [[Call]] method - of the interface object behaves as follows, assuming - arg0..n−1 is the list - of argument values passed to the constructor, and I - is the interface: -
--
-
- - If I was not declared with a [Constructor] - extended attribute, then - throw a TypeError. - -
- - Let id be the identifier of interface I. - -
- - Initialize S to the - effective overload set - for constructors with identifier - id on interface - I and with argument count n. - -
- - Let <constructor, values> be the result of passing S and - arg0..n−1 to the - overload resolution algorithm. - -
- - Let R be the result of performing the actions listed in the description of - constructor with values as the argument values. - -
- - Return the result of converting - R to an ECMAScript interface type value - I. - -
- If the internal [[Call]] method - of the interface object - returns normally, then it MUST - return an object that implements interface I. - This object also MUST be - associated with the ECMAScript global environment associated - with the interface object. -
-- Interface objects for non-callback interfaces MUST have a property named “length” - with attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true } - whose value is a Number. - If the [Constructor] - extended attribute - does not appear on the interface definition, then the value is 0. - Otherwise, the value is determined as follows: -
--
-
- - Let id be the identifier of interface I. - -
- - Initialize S to the - effective overload set - for constructors with - identifier - id on interface - I and with argument count 0. - -
- - Return the length of the shortest argument list of the entries in S. - -
- All interface objects MUST have a - property named “name” with attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true } - whose value is the identifier of the corresponding interface. -
---4.6.1.2. Interface object [[HasInstance]] method
- -- The internal [[HasInstance]] method of every - interface object - A MUST behave as follows, - assuming V is the object - argument passed to [[HasInstance]]: -
--
-
- If V is not an object, return false. -
- Let O be the result of calling the [[Get]] method of A with property name “prototype”. -
- If O is not an object, throw a TypeError exception. -
- If V is a platform object that implements the - interface for which O is the interface prototype object, - return true. -
- Repeat:
-
-
-
- Set V to the value of the [[Prototype]] internal property of V. -
- If V is null, return false. -
- If O and V refer to the same object, - return true. -
-
-- -4.6.2. Named constructors
- -- A named constructor - that exists due to one or more - [NamedConstructor] - extended attributes - with a given identifier - is a function object. - It MUST have a [[Call]] - internal property, which allows construction of objects that - implement the interface on which the - [NamedConstructor] - extended attributes appear. It behaves as follows, assuming - arg0..n−1 is the list - of argument values passed to the constructor, id - is the identifier of the constructor specified in the - extended attribute named argument list, - and I is the interface - on which the [NamedConstructor] - extended attribute appears: -
--
-
- - Initialize S to the - effective overload set - for constructors with identifier - id on interface - I and with argument count n. - -
- - Let <constructor, values> be the result of passing S and - arg0..n−1 to the - overload resolution algorithm. - -
- - Let R be the result of performing the actions listed in the description of - constructor with values as the argument values. - -
- - Return the result of converting - R to an ECMAScript - interface type value - I. - -
- If the internal [[Call]] method - of the named constructor - returns normally, then it MUST - return an object that implements interface I. - This object also MUST be - associated with the ECMAScript global environment associated - with the named constructor. -
-- A named constructor MUST have a property named “length” - with attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true } - whose value is a Number determined as follows: -
--
-
- - Initialize S to the - effective overload set - for constructors with - identifier - id on interface - I and with argument count 0. - -
- - Return the length of the shortest argument list of the entries in S. - -
- A named constructor MUST have a property named “name” - with attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true } - whose value is the identifier used for the named constructor. -
-- A named constructor MUST also have a property named - “prototype” with attributes - { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false } - whose value is the interface prototype object - for the interface on which the - [NamedConstructor] - extended attribute - appears. -
--- -4.6.3. Interface prototype object
- -- There MUST exist an - interface prototype - object for every non-callback interface - defined, regardless of whether the interface was declared with the - [NoInterfaceObject] - extended attribute. - The interface prototype object for a particular interface has - properties that correspond to the regular attributes - and regular operations - defined on that interface. These properties are described in more detail in - sections 4.6.6 and - 4.6.7 below. -
-- As with the interface object, - the interface prototype object also has properties that correspond to the - constants defined on that - interface, described in section - 4.6.5 below. -
-- If the [NoInterfaceObject] - extended attribute was not specified on the interface, then - the interface prototype object MUST - also have a property named “constructor” with attributes - { [[Writable]]: true, [[Enumerable]]: false, [[Configurable]]: true } whose value - is a reference to the interface object for the interface. -
- -- The interface prototype object - for a given interface A MUST have an internal - [[Prototype]] property whose value is returned from - the following steps: -
--
-
- If A is declared with the [Global] - or [PrimaryGlobal] - extended attribute, and A - supports named properties, then - return the named properties object - for A, as defined in section 4.6.4 - below. -
- Otherwise, if A is declared to inherit from another - interface, then return the - interface prototype object - for the inherited interface. -
- Otherwise, if A is declared with the [LegacyArrayClass] - extended attribute, then return %ArrayPrototype% ([ECMA-262], section 6.1.7.4). -
- Otherwise, return %ObjectPrototype%. - ([ECMA-262], section 15.2.4). -
- -Note-- The interface prototype object - of an interface that is defined with - the [NoInterfaceObject] - extended attribute - will be accessible if the interface is used as a - non-supplemental interface. - For example, with the following IDL: -
-- -IDL-
+[NoInterfaceObject] -interface Foo { +- it is not possible to access the interface prototype object through - the interface object - (since it does not exist as
-window.Foo). However, an instance - of Foo can expose the interface prototype - object by gettings its internal [[Prototype]] - property value –Object.getPrototypeOf(window.foo)in - this example. -- If the interface is used solely as a - supplemental interface, - then there will be no way to access its interface prototype object, since no - object will have the interface prototype object as its internal - [[Prototype]] property value. In such cases, - it is an acceptable optimization for this object not to exist. -
-- If the interface or any of its consequential interfaces - has any interface member declared with - the [Unscopable] extended attribute, - then there MUST be a property on the - interface prototype object whose name is the @@unscopables symbol - and whose value is an object created as follows: -
--
-
- Let object be a new object created as if by the expression
({}).
- - For each of the aforementioned interface members - declared with the [Unscopable] extended attribute, - call CreateDataProperty(object, - the identifier of the - interface member, true). -
- Return object. -
- If the interface is declared with the [Global] or - [PrimaryGlobal] extended attribute, or the interface is in the set - of inherited interfaces for any - other interface that is declared with one of these attributes, then the interface prototype object - must be an immutable prototype exotic object. -
- -- The class string of an - interface prototype object - is the concatenation of the interface’s - identifier and the string - “Prototype”. -
--- - - -4.6.4. Named properties object
- -- For every interface declared with the - [Global] or - [PrimaryGlobal] - extended attribute - that supports named properties, - there MUST exist an object known as the - named properties object for that - interface. -
-- The named properties object - for a given interface A MUST have an internal - [[Prototype]] property whose value is returned from - the following steps: -
--
-
- If A is declared to inherit from another interface, then return the - interface prototype object - for the inherited interface. -
- Otherwise, if A is declared with the [LegacyArrayClass] - extended attribute, then return %ArrayPrototype% ([ECMA-262], section 6.1.7.4). -
- Otherwise, return %ObjectPrototype%. -
- The class string of a - named properties object - is the concatenation of the interface’s - identifier and the string - “Properties”. -
- --- -4.6.4.1. Named properties object [[GetOwnProperty]] method
- -- When the [[GetOwnProperty]] internal method of a named properties object - O is called with property key P, the following steps are - taken: -
- --
-
- Let A be the interface for the - named properties object O. -
- Let object be the sole object from O’s ECMAScript global environment that implements A. - - -
- If the result of running the named property visibility algorithm with
- property name P and object object is true, then:
-
-
-
- Let operation be the operation used to declare the named property getter. - -
- Let value be an uninitialized variable. -
- If operation was defined without an identifier, then - set value to the result of performing the steps listed in the interface description to - determine the value of a named property - with P as the name. -
- Otherwise, operation was defined with an identifier. Set value to the result - of performing the steps listed in the description of operation with P as the only argument value. - -
- Let desc be a newly created Property Descriptor ([ECMA-262], section 6.2.4) with no fields. -
- Set desc.[[Value]] to the result of converting - value to an ECMAScript value. -
- If A implements an interface with the - [LegacyUnenumerableNamedProperties] - extended attribute, - then set desc.[[Enumerable]] to false, - otherwise set it to true. -
- Set desc.[[Writable]] to true and - desc.[[Configurable]] to true. -
- Return desc. -
-
- - Return OrdinaryGetOwnProperty(O, P). -
-- -4.6.4.2. Named properties object [[DefineOwnProperty]] method
- -- When the [[DefineOwnProperty]] internal method of a named properties object is - called, the following steps are taken: -
- --
-
- Return false. -
-- -4.6.4.3. Named properties object [[Delete]] method
- -- When the [[Delete]] internal method of a named properties object is called, the - following steps are taken: -
- --
-
- Return false. -
--4.6.4.4. Named properties object [[SetPrototypeOf]] method
- -- When the [[SetPrototypeOf]] internal method of a named properties object is - called, the same algorithm must be executed as is defined for the [[SetPrototypeOf]] internal method of an - immutable prototype exotic object. -
--- -4.6.5. Constants
- -- For each exposed - constant defined on - an interface A, there - MUST be a corresponding property. - The property has the following characteristics: -
--
-
- The name of the property is the identifier of the constant. -
-
- The location of the property is determined as follows:
-
-
-
- If the interface was declared with the [Global] or [PrimaryGlobal] extended attribute, - then the property exists on the single object that implements the interface. -
- Otherwise, if the interface is a consequential interface - of a [Global]- or [PrimaryGlobal] annotated interface, then - the property exists on the single object that implements the [Global]- or - [PrimaryGlobal]-annotated interface as well as on - the consequential interface’s interface prototype object. -
- Otherwise, the property exists solely on the interface’s interface prototype object. -
- - The value of the property is that which is obtained by converting the constant’s IDL value to an ECMAScript value. -
- The property has attributes { [[Writable]]: false, [[Enumerable]]: true, [[Configurable]]: false }. -
- In addition, a property with the same characteristics MUST - exist on the interface object, if - that object exists. -
--- -4.6.6. Attributes
- -- For each exposed - attribute of the - interface, whether it - was declared on the interface itself or one of its - consequential interfaces, - there MUST exist a corresponding property. - The characteristics of this property are as follows: -
--
-
- - The name of the property is the identifier of the attribute. - -
-
- The location of the property is determined as follows:
-
-
-
- If the attribute is a static attribute, - then there is a single corresponding property and it exists on the interface’s interface object. -
- Otherwise, if the attribute is unforgeable on - the interface or if the interface was declared with the [Global] or [PrimaryGlobal] extended attribute, - then the property exists on every object that implements the interface. -
- Otherwise, if the interface is a consequential interface - of a [Global]- or [PrimaryGlobal]-annotated interface, then - the property exists on the single object that implements the [Global]- or - [PrimaryGlobal]-annotated interface as well as on - the consequential interface’s interface prototype object. -
- Otherwise, the property exists solely on the interface’s interface prototype object. -
- -
- The property has attributes { [[Get]]: G, [[Set]]: S, [[Enumerable]]: true, [[Configurable]]: configurable },
- where:
-
-
-
- configurable is false if the attribute was - declared with the [Unforgeable] extended attribute and true otherwise; -
- G is the attribute getter, defined below; and -
- S is the attribute setter, also defined below. -
- -
- The attribute getter is a Function
- object whose behavior when invoked is as follows:
-
-
-
- Let idlValue be an IDL value determined as follows. -
- If the attribute is a regular attribute, then:
-
-
-
- Let I be the interface
- whose interface prototype object
- this property corresponding to the attribute appears on.
- -Note-
This means that even if an implements statement was used to make - an attribute available on the interface, I is the interface - on the left hand side of the implements statement, and not the one - that the attribute was originally declared on.
-
- - Let O be the this value. -
- If O is a platform object,
- then perform a security check, passing:
-
-
-
- the platform object O, -
- the ECMAScript global environment associated with this Function that - implements the attribute getter, -
- the identifier of the attribute, and -
- the type “getter”. -
- - If O is not a platform object that implements I, then:
-
-
-
- If the attribute was specified with the - [LenientThis] extended attribute, - then return undefined. -
- Otherwise, throw a TypeError. -
- - - Set idlValue to be the result of performing the actions listed in the description of the attribute that occur when getting - (or those listed in the description of the inherited attribute, if this attribute is declared to - inherit its getter), - with O as the object. - -
- - Let I be the interface
- whose interface prototype object
- this property corresponding to the attribute appears on.
-
- Otherwise, the attribute is a static attribute. - Set idlValue to be the result of performing the actions listed in the description of the attribute that occur when getting. -
- - Let V be the result of converting - idlValue to an ECMAScript value. - -
- - Return V. - -
The value of the Function object’s “length” - property is the Number value 0.
-The value of the Function object’s “name” - property is a String whose value is the - concatenation of “get ” and the identifier of the attribute.
-
- -
- The attribute setter is undefined
- if the attribute is declared
readonlyand does not have a - [LenientThis], [PutForwards] or - [Replaceable] - extended attribute declared on it. - Otherwise, it is a Function object whose behavior when invoked is as follows: --
-
- If no arguments were passed to the Function, then - throw a TypeError. -
- Let V be the value of the first argument passed to the Function. -
- If the attribute is a regular attribute, then:
-
-
-
- Let I be the interface - whose interface prototype object - this property corresponding to the attribute appears on. -
- Let O be the this value. -
- If O is a platform object,
- then perform a security check, passing:
-
-
-
- the platform object O, -
- the ECMAScript global environment associated with this Function that - implements the attribute setter, -
- the identifier of the attribute, and -
- the type “setter”. -
- - Let validThis be true if O is a - platform object that implements I, or - false otherwise. -
- If validThis is false and the - attribute was not specified with the - [LenientThis] extended attribute, - then throw a TypeError. -
- If the attribute is declared with a [Replaceable]
- extended attribute, then:
-
-
-
- Let P be the identifier of the attribute. -
- Call CreateDataProperty(O, P, V). -
- Return undefined. -
- - If validThis is false, then return undefined. -
- If the attribute is declared with a [LenientSetter] - extended attribute, then return undefined. -
- If the attribute is declared with a [PutForwards]
- extended attribute, then:
-
-
-
- Let Q be the result of calling the [[Get]] method - on O using the identifier of the attribute as the property name. -
- If Q is not an object, then throw a TypeError. -
- Let A be the attribute identified by the [PutForwards] extended attribute. -
- Call the [[Put]] method on Q - using the identifier of A as the property name and V as the value. -
- Return undefined. -
-
- - Let idlValue be an IDL value determined as follows:
-
-
-
- If the type of the attribute is an enumeration, then:
-
-
-
- Let S be the result of calling ToString(V). -
- If S is not one of the enumeration’s values, then return undefined. -
- The value of idlValue is the enumeration value equal to S. -
- - Otherwise, the type of the attribute is not an enumeration. - The value of idlValue is the result of converting - V to an IDL value. -
- - If the type of the attribute is an enumeration, then:
-
- If the attribute is a regular attribute, then perform the actions listed in the description of the attribute that occur when setting, - with O as the object and idlValue as the value. -
- Otherwise, the attribute is a static attribute. - Perform the actions listed in the description of the attribute that occur when setting with idlValue as the value. -
- Return undefined. -
The value of the Function object’s “length” - property is the Number value 1.
-The value of the Function object’s “name” - property is a String whose value is the - concatenation of “set ” and the identifier of the attribute.
-
-
-Note-- Although there is only a single property for an IDL attribute, since - accessor property getters and setters are passed a this - value for the object on which property corresponding to the IDL attribute is - accessed, they are able to expose instance-specific data. -
--Note-- Note that attempting to assign to a property corresponding to a - read only attribute - results in different behavior depending on whether the script doing so is in strict mode. - When in strict mode, such an assignment will result in a TypeError - being thrown. When not in strict mode, the assignment attempt will be ignored. -
--- -4.6.7. Operations
- -- For each unique identifier - of an exposed operation - defined on the interface, there - MUST exist a corresponding property, - unless the effective overload set - for that identifier and operation - and with an argument count of 0 has no entries. -
-- The characteristics of this property are as follows: -
--
-
- The name of the property is the identifier. -
-
- The location of the property is determined as follows:
-
-
-
- If the operation is static, then - the property exists on the interface object. -
- Otherwise, if the operation is unforgeable on - the interface or if the interface was declared with the [Global] or [PrimaryGlobal] extended attribute, - then the property exists on every object that implements the interface. -
- Otherwise, if the interface is a consequential interface - of a [Global]- or [PrimaryGlobal]-annotated interface, then - the property exists on the single object that implements the [Global]- or - [PrimaryGlobal]-annotated interface as well as on - the consequential interface’s interface prototype object. -
- Otherwise, the property exists solely on the interface’s interface prototype object. -
- - - The property has attributes - { [[Writable]]: B, [[Enumerable]]: true, [[Configurable]]: B }, - where B is false if the operation is - unforgeable on the interface, - and true otherwise. - -
-
- The value of the property is a Function object whose
- behavior is as follows,
- assuming id is the
- identifier,
- arg0..n−1 is the list
- of argument values passed to the function:
-
-
-
-
- Try running the following steps:
-
-
-
-
- Let I be the interface
- whose interface prototype object
- (or interface object, for a static
- operation) this property corresponding to the operation appears on.
- -Note-
This means that even if an implements statement was used to make - an operation available on the interface, I is the interface - on the left hand side of the implements statement, and not the one - that the operation was originally declared on.
-
- -
- Let O be a value determined as follows:
-
-
-
- - If the operation is a static operation, then O is null. - -
- - Otherwise, if the interface on which the - operation appears has an - [ImplicitThis] extended attribute, - and the this value is null - or undefined, then O is - the ECMAScript global object associated with the Function object. - -
- - Otherwise, if the this value is not null, - then O is the this value. - -
- - Otherwise, throw a TypeError. - -
- - If O is a platform object,
- then perform a security check, passing:
-
-
-
- the platform object O, -
- the ECMAScript global environment associated with this Function that - implements the operation, -
- the identifier of the operation, and -
- the type “method”. -
- - - If O is not null and is also not a platform object - that implements interface I, throw a TypeError. - -
- - Initialize S to the - effective overload set - for regular operations - (if the operation is a regular operation) or for - static operations - (if the operation is a static operation) with - identifier - id on interface - I and with argument count n. - -
- - Let <operation, values> be the result of passing S and - arg0..n−1 to the - overload resolution algorithm. - -
- - Let R be the result of performing (on O, if the operation - is not a static operation) the actions listed in the description of - operation with values as the argument values. - -
- - Return the result of converting - R to an ECMAScript value of - the type op is declared to return. - -
-
-
- If the operation has a return type - that is a promise type, then: - - -
- Otherwise, end these steps and allow the exception to propagate. -
- -
- Let I be the interface
- whose interface prototype object
- (or interface object, for a static
- operation) this property corresponding to the operation appears on.
-
- -
- Try running the following steps:
-
-
- The value of the Function object’s “length”
- property is a Number determined as follows:
-
-
-
- - Let S be the - effective overload set - for regular operations - (if the operation is a regular operation) or for - static operations - (if the operation is a static operation) with - identifier - id on interface - I and with argument count 0. - -
- - Return the length of the shortest argument list of the entries in S. - -
- - The value of the Function object’s “name” - property is a String whose value is the - identifier of the operation. -
We also define creating an operation - function, given an operation - op, a namespace - namespace, and a Realm realm:
- -The astute reader may notice that what follows is very similar to the - above algorithm for operations on interfaces. It is currently only used for namespaces, - but we have near-future plans to generalize it slightly and then replace the above - definition so that this algorithm is useful both for interfaces and namespaces.
- --
-
- - Let id be op's identifier. - - - -
-
- Let steps be the following series of steps, given function argument
- values arg0..n−1:
-
-
-
-
-
- Try running the following steps:
-
-
-
- - Let S be the effective overload set for regular operations with - identifier id on - namespace namespace - and with argument count n. - - -
- - Let <operation, values> be the result of passing - S and arg0..n−1 to the overload resolution - algorithm. - - -
- - Let R be the result of performing the actions listed in the - description of operation with values as the argument - values. - - -
- - Return the result of converting R to - an ECMAScript value of the type op is declared to return. - -
-
-
-
- - If the operation has a return type - that is a promise type, then: - - - -
- - Otherwise, end these steps and allow the exception to propagate. - -
-
- -
- Try running the following steps:
-
- - Let F be ! CreateBuiltinFunction(realm, - steps, the %FunctionPrototype% of realm). - - -
- - Perform ! SetFunctionName(F, id). - - -
- - Let S be the effective overload set for regular operations with identifier id on namespace namespace and with argument count 0. - - -
- - Let length be the length of the shortest argument list in the entries in - S. - - -
-
- Perform ! DefinePropertyOrThrow(F,
"length", - PropertyDescriptor{[[Value]]: length, - [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true}). -
-
-- -4.6.7.1. Stringifiers
- -- If the interface - has an exposed - stringifier, then - there MUST exist a property with - the following characteristics: -
--
-
- The name of the property is “toString”. -
- If the stringifier is - unforgeable on the interface - or if the interface was declared with the [Global] or [PrimaryGlobal] extended attribute, - then the property exists on every object that implements the interface. - Otherwise, the property exists on the interface prototype object. -
- The property has attributes { [[Writable]]: B, [[Enumerable]]: true, [[Configurable]]: B }, - where B is false if the stringifier is - unforgeable on the interface, - and true otherwise. -
-
-
The value of the property is a Function object, which behaves as follows:
--
-
- Let O be the result of calling ToObject on the this value. -
- If O is a platform object,
- then perform a security check, passing:
-
-
-
- the platform object O, -
- the ECMAScript global environment associated with this Function that - implements the stringifier, -
- the identifier of the stringifier, and -
- the type “method”. -
- - If O is not an object that implements the interface - on which the stringifier was declared, then throw a TypeError. -
- Let V be an uninitialized variable. -
- Depending on where
stringifierwas specified: --
-
- on an attribute -
- Set V to the result of performing the actions listed in the description of the attribute that occur when getting - (or those listed in the description of the inherited attribute, if this attribute is declared to - inherit its getter), - with O as the object. -
- on an operation with an identifier -
- Set V to the result of performing the actions listed in the description - of the operation, using O as the this value - and passing no arguments. -
- on an operation with no identifier -
- Set V to the result of performing the stringification behavior - of the interface. -
- - Return the result of converting V to a String value. -
- - The value of the Function object’s “length” - property is the Number value 0. -
- The value of the Function object’s “name” - property is the String value “toString”. -
--4.6.7.2. Serializers
- -- If the interface - has an exposed - serializer, then - a property MUST exist - whose name is “toJSON”, - with attributes { [[Writable]]: true, [[Enumerable]]: true, [[Configurable]]: true } - and whose value is a - Function object. -
-- The location of the property is determined as follows: -
--
-
- If the interface was declared with the [Global] or [PrimaryGlobal] extended attribute, - then the property exists on the single object that implements the interface. -
- Otherwise, if the interface is a consequential interface - of a [Global]- or [PrimaryGlobal]-annotated interface, then - the property exists on the single object that implements the [Global]- or - [PrimaryGlobal]-annotated interface as well as on - the consequential interface’s interface prototype object. -
- Otherwise, the property exists solely on the interface’s interface prototype object. -
- The property’s Function object, when invoked, - MUST behave as follows: -
--
-
- Let O be the result of calling ToObject on the this value. -
- If O is a platform object,
- then perform a security check, passing:
-
-
-
- the platform object O, -
- the ECMAScript global environment associated with this Function that - implements the serializer, -
- the identifier of the serializer, and -
- the type “method”. -
- - If O is not an object that implements the interface - on which the serializer was declared, then throw a TypeError. -
- Depending on how
serializerwas specified: --
-
- on an operation with an identifier -
-
-
-
-
- Return the result of performing the actions listed in the description of the - operation, using O as the this value - and passing no arguments. -
- - as a keyword, either with or without a serialization pattern -
-
-
-
-
- Let S be the serialized value that is the result of invoking the serialization behavior of the - interface for object O. -
- Return the result of converting - S to an ECMAScript value. -
-
-
The value of the Function object’s “length” - property is the Number value 0.
-The value of the Function object’s “name” - property is the String value “toJSON”.
-- The following steps define how to convert a serialized value to an ECMAScript value: -
--
-
- Let S be the serialized value. -
- Depending on the type of S:
-
-
-
- a map -
-
-
-
-
- Let O be a new object created as if by the expression
({}).
- - For each entry in S, in the order they were added to the map:
-
-
-
- Let V be the result of converting - the value of the entry to an ECMAScript value. -
- Let P be the entry’s key. -
- Call CreateDataProperty(O, P, V). -
- - Return O. -
- - Let O be a new object created as if by the expression
- a list -
-
-
-
-
- Let A be a new Array object created as if by the expression
[].
- - Let index be 0. -
- While index is less than the number of elements in S:
-
-
-
- Let V be the result of converting - the value of the element in S at index index to an ECMAScript value. -
- Let P be ToString(index). -
- Call CreateDataProperty(O, P, V). -
- - Return A. -
- - Let A be a new Array object created as if by the expression
- any other serialized value -
-
-
-
-
- Let V be the result of converting - S to an ECMAScript value. -
- Return V. -
-
-
-- -4.6.8. Common iterator behavior
- --- -4.6.8.1. @@iterator
- -- If the interface - has any of the following: -
--
-
- an iterable declaration -
- an indexed property getter - and an integer-typed - attribute named - “length” -
- a maplike declaration -
- a setlike declaration -
- then a property MUST exist - whose name is the @@iterator symbol, - with attributes { [[Writable]]: true, [[Enumerable]]: false, [[Configurable]]: true } - and whose value is a function object. -
-- The location of the property is determined as follows: -
--
-
- If the interface was declared with the [Global] or [PrimaryGlobal] extended attribute, - then the property exists on the single object that implements the interface. -
- Otherwise, if the interface is a consequential interface - of a [Global]- or [PrimaryGlobal]-annotated interface, then - the property exists on the single object that implements the [Global]- or - [PrimaryGlobal]-annotated interface as well as on - the consequential interface’s interface prototype object. -
- Otherwise, the property exists solely on the interface’s interface prototype object. -
- If the interface defines an indexed property getter, - then the Function object is %ArrayProto_values% ([ECMA-262], section 6.1.7.4). -
-- If the interface has a pair iterator, - then the Function, when invoked, - MUST behave as follows: -
--
-
- Let object be the result of calling ToObject on the this value. -
- If object is a platform object,
- then perform a security check, passing:
-
-
-
- the platform object object, -
- the ECMAScript global environment associated with this Function, -
- the identifier “@@iterator”, and -
- the type “method”. -
- - Let interface be the interface - the iterable declaration is on. -
- If object is not a platform object - that implements interface, - then throw a TypeError. -
- Let iterator be a newly created default iterator object - for interface with object as its target and iterator kind “key+value”. -
- Return iterator. -
- If the interface has a maplike declaration - or setlike declaration, - then the Function object that is the value of the @@iterator property, - when invoked, MUST behave as follows: -
--
-
- Let object be the result of calling ToObject on the this value. -
- If object is a platform object,
- then perform a security check, passing:
-
-
-
- the platform object object, -
- the ECMAScript global environment associated with this Function, -
- the identifier “@@iterator”, and -
- the type “method”. -
- - If object is not a platform object - that implements the interface - on which the maplike declaration - or setlike declaration is defined, - then throw a TypeError. -
- If the interface has a maplike declaration, then:
-
-
-
- Let backing be the value of the [[BackingMap]] internal slot of object. -
- Return CreateMapIterator(backing,
"key+value").
-
- - Otherwise:
-
-
-
- Let backing be the value of the [[BackingSet]] internal slot of object. -
- Return CreateSetIterator(backing,
"value").
-
-
- The value of the @@iterator Function object’s “length” - property is the Number value 0. -
-The value of the @@iterator Function object’s “name” - property is the String value “entries” if the interface has a - pair iterator or a - maplike - declaration and the String “values” - if the interface has a - setlike declaration.
---4.6.8.2. forEach
- -- If the interface - has any of the following: -
--
-
- an iterable declaration -
- a maplike declaration -
- a setlike declaration -
- then a property named “forEach” MUST exist - with attributes { [[Writable]]: true, [[Enumerable]]: true, [[Configurable]]: true } - and whose value is a function object. -
-- The location of the property is determined as follows: -
--
-
- If the interface was declared with the [Global] or [PrimaryGlobal] extended attribute, - then the property exists on the single object that implements the interface. -
- Otherwise, if the interface is a consequential interface - of a [Global]- or [PrimaryGlobal]-annotated interface, then - the property exists on the single object that implements the [Global]- or - [PrimaryGlobal]-annotated interface as well as on - the consequential interface’s interface prototype object. -
- Otherwise, the property exists solely on the interface’s interface prototype object. -
- If the interface defines an indexed property getter, - then the Function object is - the initial value of the “forEach” data property of %ArrayPrototype% ([ECMA-262], section 6.1.7.4). -
-- If the interface has a pair iterator, - then the Function MUST - have the same behavior as one that would exist assuming the interface had - this operation instead of the - iterable declaration: -
--IDLvoid forEach(Function callback, optional any thisArg);- with the following prose definition: -
--
-
- Let O be the this value. -
- Let pairs be the list of value pairs to iterate over. -
- Let i be 0. -
- While i is less than the length of pairs:
-
-
-
- Let pair be the entry in pairs at index i. -
- Let key be pair’s key. -
- Let value be pair’s value. -
- Invoke callback with thisArg - (or undefined, if the argument was not supplied) - as the callback this value and - value, key and O as its arguments. -
- Update pairs to the current list of value pairs to iterate over. -
- Set i to i + 1. -
-
- If the interface has a maplike declaration - or setlike declaration - then the Function, when invoked, - MUST behave as follows: -
--
-
- Let object be the result of calling ToObject on the this value. -
- If object is a platform object,
- then perform a security check, passing:
-
-
-
- the platform object object, -
- the ECMAScript global environment associated with this Function, -
- the identifier “forEach”, and -
- the type “method”. -
- - Let interface be the interface - on which the maplike declaration - or setlike declaration is declared. -
- If object is not a platform object - that implements interface, - then throw a TypeError. -
- Let callbackFn be the value of the first argument passed to the function, or undefined if the argument was not supplied. -
- If IsCallable(callbackFn) is false, throw a TypeError. -
- Let thisArg be the value of the second argument passed to the function, or undefined if the argument was not supplied. -
- Let backing be the value of the [[BackingMap]] internal slot of object, - if the interface has a maplike declaration, - or the [[BackingSet]] internal slot of object otherwise. -
- Let callbackWrapper be a Function that, when invoked, behaves as follows:
-
-
-
- Let v and k be the first two arguments passed to the function. -
- Let thisArg be the this value. -
- Call the [[Call]] internal method of callbackFn with thisArg as thisArgument - and v, k and object as argumentsList. -
-Note-The callbackWrapper function simply calls the incoming callbackFn - with object as the third argument rather than its internal [[BackingMap]] or [[BackingSet]] object.
--Editorial note-Can the script author observe that callbackWrapper might be a new function - every time forEach is called? What's the best way of specifying that there's only - one function that has captured an environment?
-
- - Let forEach be the result of calling the [[Get]] internal method of - backing with “forEach” and backing as arguments. -
- If IsCallable(forEach) is false, throw a TypeError. -
- Call the [[Call]] internal method of forEach with backing as thisArgument - and callbackWrapper and thisArg as argumentsList. -
- Return undefined. -
- The value of the Function object’s “length” - property is the Number value 1. -
-The value of the Function object’s “name” - property is the String value “forEach”.
--- -4.6.9. Iterable declarations
- --- -4.6.9.1. entries
- -- If the interface has an - iterable declaration, - then a property named “entries” MUST exist - with attributes { [[Writable]]: true, [[Enumerable]]: true, [[Configurable]]: true } - and whose value is a function object. -
-- The location of the property is determined as follows: -
--
-
- If the interface was declared with the [Global] or [PrimaryGlobal] extended attribute, - then the property exists on the single object that implements the interface. -
- Otherwise, if the interface is a consequential interface - of a [Global]- or [PrimaryGlobal]-annotated interface, then - the property exists on the single object that implements the [Global]- or - [PrimaryGlobal]-annotated interface as well as on - the consequential interface’s interface prototype object. -
- Otherwise, the property exists solely on the interface’s interface prototype object. -
- If the interface has a value iterator, - then the Function object is - the initial value of the “entries” data property of %ArrayPrototype% ([ECMA-262], section 6.1.7.4). -
-- If the interface has a pair iterator, - then the Function object is - the value of the @@iterator property. -
--- -4.6.9.2. keys
- -- If the interface has an - iterable declaration, - then a property named “keys” MUST exist - with attributes { [[Writable]]: true, [[Enumerable]]: true, [[Configurable]]: true } - and whose value is a function object. -
-- The location of the property is determined as follows: -
--
-
- If the interface was declared with the [Global] or [PrimaryGlobal] extended attribute, - then the property exists on the single object that implements the interface. -
- Otherwise, if the interface is a consequential interface - of a [Global]- or [PrimaryGlobal]-annotated interface, then - the property exists on the single object that implements the [Global]- or - [PrimaryGlobal]-annotated interface as well as on - the consequential interface’s interface prototype object. -
- Otherwise, the property exists solely on the interface’s interface prototype object. -
- If the interface has a value iterator, - then the Function object is - the initial value of the “keys” data property of %ArrayPrototype% ([ECMA-262], section 6.1.7.4). -
-- If the interface has a pair iterator, - then the Function, when invoked, MUST behave as follows: -
--
-
- Let object be the result of calling ToObject on the this value. -
- If object is a platform object,
- then perform a security check, passing:
-
-
-
- the platform object object, -
- the ECMAScript global environment associated with this Function, -
- the identifier “keys”, and -
- the type “method”. -
- - Let interface be the interface - on which the iterable declaration is declared on. -
- If object is not a platform object - that implements interface, - then throw a TypeError. -
- Let iterator be a newly created default iterator object - for interface with object as its target and iterator kind “key”. -
- Return iterator. -
The value of the Function object’s “length” property is the Number value 0.
-The value of the Function object’s “name” property is the String value “keys”.
--- -4.6.9.3. values
- -- If the interface has an - iterable declaration, - then a property named “values” MUST exist - with attributes { [[Writable]]: true, [[Enumerable]]: true, [[Configurable]]: true } - and whose value is a function object. -
-- The location of the property is determined as follows: -
--
-
- If the interface was declared with the [Global] or [PrimaryGlobal] extended attribute, - then the property exists on the single object that implements the interface. -
- Otherwise, if the interface is a consequential interface - of a [Global]- or [PrimaryGlobal]-annotated interface, then - the property exists on the single object that implements the [Global]- or - [PrimaryGlobal]-annotated interface as well as on - the consequential interface’s interface prototype object. -
- Otherwise, the property exists solely on the interface’s interface prototype object. -
- If the interface has a value iterator, - then the Function object is - the value of the @@iterator property. -
- -- If the interface has a pair iterator, - then the Function, when invoked, MUST behave as follows: -
--
-
- Let object be the result of calling ToObject on the this value. -
- If object is a platform object,
- then perform a security check, passing:
-
-
-
- the platform object object, -
- the ECMAScript global environment associated with this Function, -
- the identifier “entries”, and -
- the type “method”. -
- - Let interface be the interface - on which the iterable declaration is declared on. -
- If object is not a platform object - that implements interface, - then throw a TypeError. -
- Let iterator be a newly created default iterator object - for interface with object as its target and iterator kind “value”. -
- Return iterator. -
The value of the Function object’s “length” property is the Number value 0.
-The value of the Function object’s “name” property is the String value “values”.
--- -4.6.9.4. Default iterator objects
- -- A default iterator object for a given - interface, target and iteration kind - is an object whose internal [[Prototype]] property is the - iterator prototype object - for the interface. -
-- A default iterator object - has three internal values: -
--
-
- its target, which is an object whose values are to be iterated, -
- its kind, which is the iteration kind, -
- its index, which is the current index into the values value to be iterated. -
-Note-- Default iterator objects are only used for pair iterators; - value iterators, as they are currently - restricted to iterating over an object’s - supported indexed properties, - use standard ECMAScript Array iterator objects. -
-- When a default iterator object is first created, - its index is set to 0. -
-- The class string of a - default iterator object - for a given interface - is the result of concatenting the identifier - of the interface and - the string “ Iterator”. -
---4.6.9.5. Iterator prototype object
- -- The iterator prototype object - for a given interface - is an object that exists for every interface that has a - pair iterator. It serves as the - prototype for default iterator objects - for the interface. -
-- The internal [[Prototype]] property of an iterator prototype object - MUST be %IteratorPrototype% ([ECMA-262], section 6.1.7.4). -
-- An iterator prototype object - MUST have a property named “next” with - attributes { [[Writable]]: true, [[Enumerable]]: true, [[Configurable]]: true } - and whose value is a function object - that behaves as follows: -
--
-
- Let interface be the interface for which the - iterator prototype object exists. -
- Let object be the result of calling ToObject on the this value. -
- If object is a platform object,
- then perform a security check, passing:
-
-
-
- the platform object object, -
- the ECMAScript global environment associated with this Function, -
- the identifier “next”, and -
- the type “method”. -
- - If object is not a default iterator object for interface, - then throw a TypeError. -
- Let target be object’s target. -
- Let index be object’s index. -
- Let kind be object’s kind. -
- Let values be the list of value pairs to iterate over. -
- Let len be the length of values. -
- If object’s index is greater than or equal to len, then - return CreateIterResultObject(undefined, true). -
- Let pair be the entry in values at index index. -
- Let result be a value determined by the value of kind:
-
-
-
- key -
-
-
-
-
- Let idlKey be pair’s key. -
- Let key be the result of converting idlKey to an ECMAScript value. -
- result is key. -
- - value -
-
-
-
-
- Let idlValue be pair’s value. -
- Let value be the result of converting idlValue to an ECMAScript value. -
- result is value. -
- - key+value -
-
-
-
-
- Let idlKey be pair’s key. -
- Let idlValue be pair’s value. -
- Let key be the result of converting idlKey to an ECMAScript value. -
- Let value be the result of converting idlValue to an ECMAScript value. -
- Let array be the result of performing ArrayCreate(2). -
- Call CreateDataProperty(array, "0", key). -
- Call CreateDataProperty(array, "1", value). -
- result is array. -
-
- - Return CreateIterResultObject(result, false). -
- The class string of an - iterator prototype object - for a given interface - is the result of concatenting the identifier - of the interface and - the string “Iterator”. -
--- -4.6.10. Maplike declarations
- -- Any object that implements an interface - that has a maplike declaration - MUST have a [[BackingMap]] internal slot, which is - initially set to a newly created Map object. - This Map object’s [[MapData]] internal slot is - the object’s map entries. -
- -- If an interface A is declared with - a maplike declaration, then - there exists a number of additional properties on A’s - interface prototype object. - These additional properties are described in the sub-sections below. -
- -- Some of the properties below are defined to have a function object value - that forwards to the internal map object - for a given function name. Such functions behave as follows when invoked: -
--
-
- Let O be the this value. -
- Let arguments be the list of arguments passed to this function. -
- Let name be the function name. -
- If O is a platform object,
- then perform a security check, passing:
-
-
-
- the platform object O, -
- the ECMAScript global environment associated with this Function, -
- an identifier equal to name, and -
- the type “method”. -
- - If O is not an object that implements A, then throw a TypeError. -
- Let map be the Map object that is the value of O’s [[BackingMap]] internal slot. -
- Let function be the result of calling the [[Get]] internal method of map passing name and map as arguments. -
- If IsCallable(function) is false, then throw a TypeError. -
- Return the result of calling the [[Call]] internal method of function with map as thisArg and arguments as argumentsList. -
-- -4.6.10.1. size
- -- There MUST exist a property named “size” on - A’s interface prototype object - with the following characteristics: -
--
-
- The property has attributes { [[Get]]: G, [[Enumerable]]: false, [[Configurable]]: true }, - where G is the interface’s map size getter, - defined below. -
The map size getter is - a Function object whose - behavior when invoked is as follows:
--
-
- Let O be the this value. -
- If O is a platform object,
- then perform a security check, passing:
-
-
-
- the platform object O, -
- the ECMAScript global environment associated with this Function, -
- the identifier “size”, and -
- the type “getter”. -
- - If O is not an object that implements A, then throw a TypeError. -
- Let map be the Map object that is the value of O’s [[BackingMap]] internal slot. -
- Return the result of calling the [[Get]] internal method of map passing “size” and map as arguments. -
The value of the Function object’s “length” property is the Number value 0.
-The value of the Function object’s “name” property is the String value “size”.
-
-
-- -4.6.10.2. entries
- -- A property named “entries” MUST exist on - A’s interface prototype object - with attributes { [[Writable]]: true, [[Enumerable]]: false, [[Configurable]]: true } - and whose value is the function object that is the value of - the @@iterator property. -
--- -4.6.10.3. keys and values
- -- For both of “keys” and “values”, there MUST exist a property with that name on - A’s interface prototype object - with the following characteristics: -
--
-
- The property has attributes { [[Writable]]: true, [[Enumerable]]: false, [[Configurable]]: true }. -
- The value of the property is a Function object that forwards that name to the internal map object. -
The value of the Function objects’ “length” properties is the Number value 0.
-The value of the Function object’s “name” property is the String value “keys” or “values”, correspondingly.
--- -4.6.10.4. get and has
- -- For both of “get” and “has”, there MUST exist a property with that name on - A’s interface prototype object - with the following characteristics: -
--
-
- The property has attributes { [[Writable]]: true, [[Enumerable]]: false, [[Configurable]]: true }. -
- The value of the property is a Function object that behaves as follows when invoked:
-
-
-
- Let O be the this value. -
- Let name be the name of the property – “get” or “has”. -
- If O is a platform object,
- then perform a security check, passing:
-
-
-
- the platform object O, -
- the ECMAScript global environment associated with this Function, -
- an identifier equal to name, and -
- the type “method”. -
- - If O is not an object that implements A, then throw a TypeError. -
- Let map be the Map object that is the value of O’s [[BackingMap]] internal slot. -
- Let keyType be the key type specified in the maplike declaration. -
- Let function be the result of calling the [[Get]] internal method of map passing name and map as arguments. -
- Let keyArg be the first argument passed to this function, or undefined if not supplied. -
- Let keyIDL be the result of converting keyArg to an IDL value of type keyType. -
- Let key be the result of converting keyIDL to an ECMAScript value. -
- Return the result of calling the [[Call]] internal method of function with map as thisArg and the single value key as argumentsList. -
-
The value of the Function objects’ “length” properties is the Number value 1.
-The value of the Function object’s “name” property is the String value “get” or “has”, correspondingly.
--- -4.6.10.5. clear
- -- If A and A’s - consequential interfaces - do not declare an interface member - with identifier “clear”, and - A was declared with a read–write maplike declaration, - then a property named “clear” and the following characteristics - MUST exist on A’s - interface prototype object: -
--
-
- The property has attributes { [[Writable]]: true, [[Enumerable]]: false, [[Configurable]]: true }. -
- The value of the property is a Function object that forwards “clear” to the internal map object. -
The value of the Function object’s “length” property is the Number value 0.
-The value of the Function object’s “name” property is the String value “clear”.
--- -4.6.10.6. delete
- -- If A and A’s - consequential interfaces - do not declare an interface member - with identifier “delete”, and - A was declared with a read–write maplike declaration, - then a property named “delete” and the following characteristics - MUST exist on A’s - interface prototype object: -
--
-
- The property has attributes { [[Writable]]: true, [[Enumerable]]: false, [[Configurable]]: true }. -
- The value of the property is a Function object that behaves as follows when invoked:
-
-
-
- Let O be the this value. -
- If O is a platform object,
- then perform a security check, passing:
-
-
-
- the platform object O, -
- the ECMAScript global environment associated with this Function, -
- the identifier “delete”, and -
- the type “method”. -
- - If O is not an object that implements A, then throw a TypeError. -
- Let map be the Map object that is the value of O’s [[BackingMap]] internal slot. -
- Let keyType be the key type specified in the maplike declaration. -
- Let function be the result of calling the [[Get]] internal method of map passing “delete” and map as arguments. -
- Let keyArg be the first argument passed to this function, or undefined if not supplied. -
- Let keyIDL be the result of converting keyArg to an IDL value of type keyType. -
- Let key be the result of converting keyIDL to an ECMAScript value. -
- Return the result of calling the [[Call]] internal method of function with map as thisArg and the single value key as argumentsList. -
-
The value of the Function object’s “length” property is the Number value 1.
-The value of the Function object’s “name” property is the String value “delete”.
---4.6.10.7. set
- -- If A and A’s - consequential interfaces - do not declare an interface member - with identifier “set”, and - A was declared with a read–write maplike declaration, - then a property named “set” and the following characteristics - MUST exist on A’s - interface prototype object: -
--
-
- The property has attributes { [[Writable]]: true, [[Enumerable]]: false, [[Configurable]]: true }. -
- The value of the property is a Function object that behaves as follows when invoked:
-
-
-
- Let O be the this value. -
- If O is a platform object,
- then perform a security check, passing:
-
-
-
- the platform object O, -
- the ECMAScript global environment associated with this Function, -
- the identifier “set”, and -
- the type “method”. -
- - If O is not an object that implements A, then throw a TypeError. -
- Let map be the Map object that is the value of O’s [[BackingMap]] internal slot. -
- Let keyType and valueType be the key and value types specified in the maplike declaration. -
- Let function be the result of calling the [[Get]] internal method of map passing “set” and map as arguments. -
- Let keyArg be the first argument passed to this function, or undefined if not supplied. -
- Let valueArg be the second argument passed to this function, or undefined if not supplied. -
- Let keyIDL be the result of converting keyArg to an IDL value of type keyType. -
- Let valueIDL be the result of converting valueArg to an IDL value of type valueType. -
- Let key be the result of converting keyIDL to an ECMAScript value. -
- Let value be the result of converting valueIDL to an ECMAScript value. -
- Let result be the result of calling the [[Call]] internal method of function with map as thisArg and key and value as argumentsList. -
- Assert: result is not an abrupt completion. -
- Return O. -
-
The value of the Function object’s “length” property is the Number value 2.
-The value of the Function object’s “name” property is the String value “set”.
--- -4.6.11. Setlike declarations
- -- Any object that implements an interface - that has a setlike declaration - MUST have a [[BackingSet]] internal slot, which is - initially set to a newly created Set object. - This Set object’s [[SetData]] internal slot is - the object’s set entries. -
- -- If an interface A is declared with - a setlike declaration, then - there exists a number of additional properties on A’s - interface prototype object. - These additional properties are described in the sub-sections below. -
- -- Some of the properties below are defined to have a function object value - that forwards to the internal set object - for a given function name. Such functions behave as follows when invoked: -
--
-
- Let O be the this value. -
- Let arguments be the list of arguments passed to this function. -
- Let name be the function name. -
- If O is a platform object,
- then perform a security check, passing:
-
-
-
- the platform object O, -
- the ECMAScript global environment associated with this Function, -
- an identifier equal to name, and -
- the type “method”. -
- - If O is not an object that implements A, then throw a TypeError. -
- Let set be the Set object that is the value of O’s [[BackingSet]] internal slot. -
- Let function be the result of calling the [[Get]] internal method of set passing name and set as arguments. -
- If IsCallable(function) is false, then throw a TypeError. -
- Return the result of calling the [[Call]] internal method of function with set as thisArg and arguments as argumentsList. -
-- -4.6.11.1. size
- -- There MUST exist a property named “size” on - A’s interface prototype object - with the following characteristics: -
--
-
- The property has attributes { [[Get]]: G, [[Enumerable]]: false, [[Configurable]]: true }, - where G is the interface’s set size getter, - defined below. -
The set size getter is - a Function object whose - behavior when invoked is as follows:
--
-
- Let O be the this value. -
- If O is a platform object,
- then perform a security check, passing:
-
-
-
- the platform object O, -
- the ECMAScript global environment associated with this Function, -
- the identifier “size”, and -
- the type “getter”. -
- - If O is not an object that implements A, then throw a TypeError. -
- Let set be the Set object that is the value of O’s [[BackingSet]] internal slot. -
- Return the result of calling the [[Get]] internal method of set passing “size” and set as arguments. -
The value of the Function object’s “length” property is the Number value 0.
-The value of the Function object’s “name” property is the String value “size”.
-
-
-- -4.6.11.2. values
- -- A property named “values” MUST exist on - A’s interface prototype object - with attributes { [[Writable]]: true, [[Enumerable]]: false, [[Configurable]]: true } - and whose value is the function object that is the value of - the @@iterator property. -
--- -4.6.11.3. entries and keys
- -- For both of “entries” and “keys”, there MUST exist a property with that name on - A’s interface prototype object - with the following characteristics: -
--
-
- The property has attributes { [[Writable]]: true, [[Enumerable]]: false, [[Configurable]]: true }. -
- The value of the property is a Function object that forwards that name to the internal set object. -
The value of the Function objects’ “length” properties is the Number value 0.
-The value of the Function object’s “name” property is the String value “entries” or “keys”, correspondingly.
--- -4.6.11.4. has
- -- There MUST exist a property with named “has” on - A’s interface prototype object - with the following characteristics: -
--
-
- The property has attributes { [[Writable]]: true, [[Enumerable]]: false, [[Configurable]]: true }. -
- The value of the property is a Function object that behaves as follows when invoked:
-
-
-
- Let O be the this value. -
- If O is a platform object,
- then perform a security check, passing:
-
-
-
- the platform object O, -
- the ECMAScript global environment associated with this Function, -
- the identifier “has”, and -
- the type “method”. -
- - If O is not an object that implements A, then throw a TypeError. -
- Let set be the Set object that is the value of O’s [[BackingSet]] internal slot. -
- Let type be the value type specified in the setlike declaration. -
- Let function be the result of calling the [[Get]] internal method of set passing “has” and set as arguments. -
- Let arg be the first argument passed to this function, or undefined if not supplied. -
- Let idlValue be the result of converting arg to an IDL value of type type. -
- Let value be the result of converting idlValue to an ECMAScript value. -
- Return the result of calling the [[Call]] internal method of function with set as thisArg and the single value value as argumentsList. -
-
The value of the Function object’s “length” property is a Number value 1.
-The value of the Function object’s “name” property is the String value “has”.
--- -4.6.11.5. add and delete
- -- For both of “add” and “delete”, if: -
--
-
- A and A’s - consequential interfaces - do not declare an interface member - with a matching identifier, and -
- A was declared with a read–write setlike declaration, -
- then a property with that name and the following characteristics - MUST exist on A’s - interface prototype object: -
--
-
- The property has attributes { [[Writable]]: true, [[Enumerable]]: false, [[Configurable]]: true }. -
- The value of the property is a Function object that behaves as follows when invoked:
-
-
-
- Let O be the this value. -
- Let name be the name of the property – “add” or “delete”. -
- If O is a platform object,
- then perform a security check, passing:
-
-
-
- the platform object O, -
- the ECMAScript global environment associated with this Function, -
- an identifier equal to name, and -
- the type “method”. -
- - If O is not an object that implements A, then throw a TypeError. -
- Let set be the Set object that is the value of O’s [[BackingSet]] internal slot. -
- Let type be the value type specified in the setlike declaration. -
- Let function be the result of calling the [[Get]] internal method of set passing name and set as arguments. -
- Let arg be the first argument passed to this function, or undefined if not supplied. -
- Let idlValue be the result of converting arg to an IDL value of type type. -
- Let value be the result of converting idlValue to an ECMAScript value. -
- Let result be the result of calling the [[Call]] internal method of function with set as thisArg and the single value value as argumentsList. -
- Assert: result is not an abrupt completion. -
-
- If name is "delete", then:
-
-
-
- Return result. -
- -
- Otherwise:
-
-
-
- Return O. -
-
-
The value of the Function object’s “length” property is the Number value 1.
-The value of the Function object’s “name” property is the String value “add” or “delete”, correspondingly.
---4.6.11.6. clear
- -- If A and A’s - consequential interfaces - do not declare an interface member - with a matching identifier, and - A was declared with a read–write setlike declaration, - then a property named “clear” and the following characteristics - MUST exist on A’s - interface prototype object: -
--
-
- The property has attributes { [[Writable]]: true, [[Enumerable]]: false, [[Configurable]]: true }. -
- The value of the property is a Function object that forwards “clear” to the internal set object. -
The value of the Function object’s “length” property is the Number value 0.
-The value of the Function object’s “name” property is the String value “clear”.
---4.6.12. Initializing objects from iterables
- -- Some objects, which are attempting to emulate map- and set-like interfaces, will want to accept iterables - as constructor parameters and initialize themselves in this way. Here we provide some algorithms that can - be invoked in order to do so in the same way as in the ECMAScript spec, so that those objects behave - the same as the built-in Map and Set objects. -
- -- To add map elements from an iterable iterable to - an object destination with adder method name adder, perform the following steps: -
--
-
- If Type(destination) is not Object, then, throw a TypeError exception. -
- If iterable is not present, let iterable be undefined. -
- If iterable is either undefined or null, then let iter be undefined. -
- Else,
-
-
-
- Let adder be the result of Get(destination, adder). -
- ReturnIfAbrupt(adder). -
- If IsCallable(adder) is false, throw a TypeError exception. -
- Let iter be the result of GetIterator(iterable). -
- ReturnIfAbrupt(iter). -
- - If iter is undefined, then return. -
- Repeat
-
-
-
- Let next be the result of IteratorStep(iter). -
- ReturnIfAbrupt(next). -
- If next is false, then return NormalCompletion(destination). -
- Let nextItem be IteratorValue(next). -
- ReturnIfAbrupt(nextItem). -
- If Type(nextItem) is not Object, then throw a TypeError exception. -
- Let k be the result of Get(nextItem,
'0').
- - ReturnIfAbrupt(k). -
- Let v be the result of Get(nextItem,
'1').
- - ReturnIfAbrupt(v). -
- Let status be the result of calling the [[Call]] internal method of adder with destination as - thisArgument and (k, v) as argumentsList. -
- ReturnIfAbrupt(status). -
-
-- -4.7. Implements statements
- -- The interface prototype object - of an interface A MUST have a copy of - each property that corresponds to one of the - constants, - attributes, - operations, - iterable declarations, - maplike declarations and - setlike declarations - that exist on all of the interface prototype objects of A’s - consequential interfaces. - For operations, where the property is a data property with a Function - object value, each copy of the property MUST have - distinct Function objects. For attributes, each - copy of the accessor property MUST have - distinct Function objects for their getters, - and similarly with their setters. -
--Note-- When invoking an operation by calling - a Function object that is the value of one of the copies that exists - due to an implements statement, the this value is - checked to ensure that it is an object that implements the - interface corresponding to the - interface prototype object - that the property is on. -
-- For example, consider the following IDL: -
--IDL
+interface A { - void f(); +In the ECMAScript binding, using a
+Studentobject in a context where a string is expected will result in the + value of the object’s “name” property being + used:var s = new Student(); +s.id = 12345678; +s.name = '周杰倫'; + +var greeting = 'Hello, ' + s + '!'; // Now greeting == 'Hello, 周杰倫!'.
+The following IDL fragment defines an interface that has custom stringification behavior that is + not specified in the IDL itself.
+[Constructor] +interface Student { + attribute unsigned long id; + attribute DOMString? familyName; + attribute DOMString givenName; + + stringifier DOMString (); }; - -interface B { }; -B implements A; - -interface C { }; -C implements A;
- Attempting to call
-B.prototype.fon an object that implements - A (but not B) or one - that implements C will result in a - TypeError being thrown. However, - callingA.prototype.fon an object that implements - B or one that implements C - would succeed. This is handled by the algorithm in section 4.6.7 - that defines how IDL operation invocation works in ECMAScript. -- Similar behavior is required for the getter and setter Function - objects that correspond to an IDL attributes, - and this is handled in section 4.6.6. -
--- -4.8. Platform objects implementing interfaces
- -- Every platform object is associated with a global environment, just - as the initial objects are. - It is the responsibility of specifications using Web IDL to state - which global environment (or, by proxy, which global object) each platform - object is associated with. -
-- The primary interface of a platform object - that implements one or more interfaces is the most-derived non-supplemental interface - that it implements. The value of the internal [[Prototype]] - property of the platform object is the interface prototype object - of the primary interface - from the platform object’s associated global environment. -
-- The global environment that a given platform object - is associated with can change after it has been created. When - the global environment associated with a platform object is changed, its internal - [[Prototype]] property MUST be immediately - updated to be the interface prototype object - of the primary interface - from the platform object’s newly associated global environment. -
- - - -- Every platform object that implements an [Unforgeable]-annotated - interface and which does not have a stringifier - that is unforgeable on any of the - interfaces it implements MUST have a property with the - following characteristics: -
--
-
- The name of the property is “toString”. -
- The property has attributes { [[Writable]]: false, [[Enumerable]]: true, [[Configurable]]: false }. -
- The value of the property is %ObjProto_toString% ([ECMA-262], section 6.1.7.4), the initial value of Object.prototype.toString. -
- Every platform object that implements an [Unforgeable]-annotated - interface and which does not have a serializer - that is unforgeable on any of the - interfaces it implements MUST have a property with the - following characteristics: -
--
-
- The name of the property is “toJSON”. -
- The property has attributes { [[Writable]]: false, [[Enumerable]]: true, [[Configurable]]: false }. -
- The value of the property is undefined. -
- Every platform object that implements an [Unforgeable]-annotated - interface MUST have a property with the - following characteristics: -
--
-
- The name of the property is “valueOf”. -
- The property has attributes { [[Writable]]: false, [[Enumerable]]: true, [[Configurable]]: false }. -
-
- The value of the property is a Function object whose behavior
- is as follows:
-
-
-
- Return the this value. -
- - The value of the Function object’s “length” - property is the Number value 0. -
- The value of the Function object’s “name” property is the - String value “valueOf”. -
- The class string of - a platform object that implements one or more interfaces - MUST be the identifier of - the primary interface - of the platform object. -
- --- -4.8.1. Indexed and named properties
- -- If a platform object implements an interface that - supports indexed or - named properties, - the object will appear to have additional properties that correspond to the - object’s indexed and named properties. These properties are not “real” own - properties on the object, but are made to look like they are by being exposed - by the [[GetOwnProperty]] internal method. -
-- However, when the [Global] or - [PrimaryGlobal] - extended attribute has been used, - named properties are not exposed on the object but on another object - in the prototype chain, the named properties object. -
-- It is permissible for an object to implement multiple interfaces that support indexed properties. - However, if so, and there are conflicting definitions as to the object’s - supported property indices, - or if one of the interfaces is a supplemental interface for the - platform object, then it is undefined what additional properties the object will appear to - have, or what its exact behavior will be with regard to its indexed properties. - The same applies for named properties. -
-- The indexed property getter - that is defined on the derived-most interface that the - platform object implements is the one that defines the behavior - when indexing the object with an array index. Similarly for - indexed property setters. - This way, the definitions of these special operations from - ancestor interfaces can be overridden. -
- -- Platform objects implementing an interface that supports indexed or named properties cannot be fixed; if
- -Object.freeze,Object.seal- orObject.preventExtensionsis called on one of these objects, the function - MUST throw a TypeError. - Similarly, an interface prototype object - that exposes named properties due to the use of [Global] or - [PrimaryGlobal] - also MUST throw a TypeError - if one of the three functions above is called on it. -- The name of each property that appears to exist due to an object supporting indexed properties - is an array index property name, which is a property - name P such that Type(P) is String - and for which the following algorithm returns true: -
--
-
- Let i be ToUint32(P). -
- Let s be ToString(i). -
- If s ≠ P or i = 232 − 1, then return false. -
- Return true. -
- A property name is an unforgeable property name on a - given platform object if the object implements an interface that - has an interface member with that identifier - and that interface member is unforgeable on any of - the interfaces that O implements. If the object implements an - [Unforgeable]-annotated - interface, then “toString” and “valueOf” are - also unforgeable property names - on that object. -
-- The named property visibility algorithm is used to determine if - a given named property is exposed on an object. Some named properties are not exposed on an object - depending on whether the [OverrideBuiltins] - extended attribute was used. The algorithm - operates as follows, with property name P and object O: -
- --
-
- If P is an unforgeable property name - on O, then return false. -
- If O implements an interface with - an [Unforgeable]-annotated attribute - whose identifier is P, then return false. -
- If P is not a supported property name - of O, then return false. -
- If O implements an interface that has the [OverrideBuiltins] - extended attribute, then return true. -
- If O has an own property named P, then return false. -
- Initialize prototype to be the value of the internal [[Prototype]] property of O. -
- While prototype is not null:
-
-
-
- If prototype is not a named properties object, - and prototype has an own property named P, then return false. -
- Set prototype to be the value of the internal [[Prototype]] property of prototype. -
- - Return true. -
-Note-This should ensure that for objects with named properties, property resolution is done in the following order:
--
-
- Indexed properties. -
- Unforgeable attributes and operations. -
- Then, if [OverrideBuiltins]:
-
-
-
- Named properties. -
- Own properties. -
- Properties from the prototype chain. -
- - Otherwise, if not [OverrideBuiltins]:
-
-
-
- Own properties. - -
- Properties from the prototype chain. - -
- Named properties. -
-
- Support for getters is - handled by the platform object [[GetOwnProperty]] method - defined in section 4.8.3, and - for setters - by the platform object [[DefineOwnProperty]] method - defined in section 4.8.7 and the platform object [[Set]] method - defined in section 4.8.6. -
--- -4.8.2. The PlatformObjectGetOwnProperty abstract operation
- -- The PlatformObjectGetOwnProperty - abstract operation performs the following steps when called with an - object O, a property name P, and a boolean - ignoreNamedProps value: -
- --
-
-
- If O supports indexed properties
- and P is an array index property name, then:
-
-
-
- Let index be the result of calling ToUint32(P). -
- If index is a supported property index, then:
-
-
-
- Let operation be the operation used to declare the indexed property getter. - -
- Let value be an uninitialized variable. -
- If operation was defined without an identifier, then - set value to the result of performing the steps listed in the interface description to - determine the value of an indexed property - with index as the index. -
- Otherwise, operation was defined with an identifier. Set value to the result - of performing the steps listed in the description of operation with index as the only argument value. - -
- Let desc be a newly created Property Descriptor ([ECMA-262], section 6.2.4) with no fields. -
- Set desc.[[Value]] to the result of converting - value to an ECMAScript value. -
- If O implements an interface with an indexed property setter, then set - desc.[[Writable]] to true, otherwise set it to - false. -
- Set desc.[[Enumerable]] and desc.[[Configurable]] to true. -
- Return desc. -
- - Set ignoreNamedProps to true. -
-
- - If O supports named properties, O does not
- implement an interface with the [Global] or [PrimaryGlobal]
- extended attribute, the result of running the named property visibility algorithm with
- property name P and object O is true, and ignoreNamedProps is false, then:
-
-
-
- Let operation be the operation used to declare the named property getter. - -
- Let value be an uninitialized variable. -
- If operation was defined without an identifier, then - set value to the result of performing the steps listed in the interface description to - determine the value of a named property - with P as the name. -
- Otherwise, operation was defined with an identifier. Set value to the result - of performing the steps listed in the description of operation with P as the only argument value. - -
- Let desc be a newly created Property Descriptor ([ECMA-262], section 6.2.4) with no fields. -
- Set desc.[[Value]] to the result of converting - value to an ECMAScript value. -
- If O implements an interface with a named property setter, then set - desc.[[Writable]] to true, otherwise set it to - false. -
- If O implements an interface with the - [LegacyUnenumerableNamedProperties] - extended attribute, - then set desc.[[Enumerable]] to false, - otherwise set it to true. -
- Set desc.[[Configurable]] to true. -
- Return desc. -
-
- - Return OrdinaryGetOwnProperty(O, P). -
-- -4.8.3. Platform object [[GetOwnProperty]] method
- -- The internal [[GetOwnProperty]] method of every - platform object O that implements an interface - which supports indexed or - named properties - MUST behave as follows when called with property name P: -
- --
-
- - Return the result of invoking the PlatformObjectGetOwnProperty - abstract operation with - O, P, and false as - arguments. - -
-- -4.8.4. Invoking a platform object indexed property setter
-- To invoke an indexed property - setter with property name P and ECMAScript value - V, the following steps MUST be performed: -
--
-
- Let index be the result of calling ToUint32(P). -
- Let creating be true if index is not a supported property index, and false otherwise. -
- Let operation be the operation used to declare the indexed property setter. -
- Let T be the type of the second argument of operation. -
- Let value be the result of converting V to an IDL value of type T. -
- If operation was defined without an identifier, then:
-
-
-
- If creating is true, then perform the steps listed in the interface description to - set the value of a new indexed property - with index as the index and value as the value. -
- Otherwise, creating is false. Perform the steps listed in the interface description to - set the value of an existing indexed property - with index as the index and value as the value. -
- - Otherwise, operation was defined with an identifier. Perform the steps listed in the description of - operation with index and value as the two argument values. -
-- -4.8.5. Invoking a platform object named property setter
-- To invoke a named property - setter with property name P and ECMAScript value - V, the following steps MUST be performed: -
--
-
- Let creating be true if P is not a supported property name, and false otherwise. -
- Let operation be the operation used to declare the named property setter. -
- Let T be the type of the second argument of operation. -
- Let value be the result of converting V to an IDL value of type T. -
- If operation was defined without an identifier, then:
-
-
-
- If creating is true, then perform the steps listed in the interface description to - set the value of a new named property - with P as the name and value as the value. -
- Otherwise, creating is false. Perform the steps listed in the interface description to - set the value of an existing named property - with P as the name and value as the value. -
- - Otherwise, operation was defined with an identifier. Perform the steps listed in the description of - operation with index and value as the two argument values. -
-- -4.8.6. Platform object [[Set]] method
- -- The internal [[Set]] method of every - platform object O that implements an interface - which supports indexed or - named properties - MUST behave as follows when called - with property name P, value V, and - ECMAScript language value Receiver: -
- --
-
- If O and Receiver are the same object,
- then:
-
-
-
-
- If O supports indexed
- properties, P is an array index property
- name, and O implements an interface with an indexed
- property setter, then:
-
-
-
- - Invoke the indexed - property setter with P and V. - -
- Return true. -
-
- -
- If O supports named
- properties, Type(P) is String,
- P is not an array index property
- name, and O implements an interface with a named
- property setter, then:
-
-
-
- - Invoke the named - property setter with P and V. - -
- Return true. -
-
- -
- If O supports indexed
- properties, P is an array index property
- name, and O implements an interface with an indexed
- property setter, then:
-
- - Let ownDesc be the result of invoking the PlatformObjectGetOwnProperty - abstract operation with - O, P, and true as - arguments. - -
- - Perform steps 3-11 of the default [[Set]] internal method ([ECMA-262], section 9.1.9). - -
-- -4.8.7. Platform object [[DefineOwnProperty]] method
- -- When the internal [[DefineOwnProperty]] method of a - platform object O that - implements an interface which - supports indexed or - named properties is - called with property key P and Property Descriptor ([ECMA-262], section 6.2.4) - Desc, the following steps MUST be taken: -
- --
-
-
- If O supports indexed properties and
- P is an array index property name, then:
-
-
-
- - If the result of calling IsDataDescriptor(Desc) is - false, then return - false. - -
- - If O does not implement an interface with an - indexed property - setter, then return false. - -
- - Invoke the indexed property setter with - P and Desc.[[Value]]. - -
- - Return true. - -
-
- -
- If O supports named properties,
- O does not implement an interface with the
- [Global] or [PrimaryGlobal] extended attribute
- and P is not an unforgeable property name
- of O, then:
-
-
-
- Let creating be true if P is not a supported property name, and false otherwise. -
- If O implements an interface with the [OverrideBuiltins]
- extended attribute or O does not have an own property
- named P, then:
-
-
-
- - If creating is false and O does not implement an - interface with a named - property setter, then return false. - -
-
- If O implements an interface with a
- named property
- setter, then:
-
-
-
- - If the result of calling IsDataDescriptor(Desc) is - false, then return - false. - -
- - Invoke the named property setter - with P and - Desc.[[Value]]. - -
- - Return true. - -
-
-
-
- - - If O does not implement an - interface with the - [Global] or - [PrimaryGlobal] - extended attribute, then set - Desc.[[Configurable]] to - true. - - -
- - Return OrdinaryDefineOwnProperty(O, P, - Desc). - -
-- -4.8.8. Platform object [[Delete]] method
- -- The internal [[Delete]] method of every - platform object O that implements an interface - which supports indexed or - named properties - MUST behave as follows when called with property name P. -
- --
-
-
- If O supports indexed properties and
- P is an array index property name, then:
-
-
-
- Let index be the result of calling ToUint32(P). -
- If index is not a supported property index, then return true. -
- Return false. -
-
- -
- If O supports named properties,
- O does not implement an interface with the
- [Global] or [PrimaryGlobal] extended attribute
- and the result of calling the named property visibility algorithm
- with property name P and object O is true, then:
-
-
-
- If O does not implement an interface with a named property deleter, then return false. -
- Let operation be the operation used to declare the named property deleter. -
- If operation was defined without an identifier, then:
-
-
-
- Perform the steps listed in the interface description to - delete an existing named property - with P as the name. -
- If the steps indicated that the deletion failed, then return false. -
- - Otherwise, operation was defined with an identifier:
-
-
-
- Perform the steps listed in the description of operation with P as the only argument value. -
- If operation was declared with a return type of boolean - and the steps returned false, then return false. -
- - Return true. -
-
- - If O has an own property with name P, then:
-
-
-
- If the property is not configurable, then return false. -
- Otherwise, remove the property from O. -
- - Return true. -
-- -4.8.9. Platform object [[Call]] method
- -- The internal [[Call]] method of every - platform object O that implements an interface - I with at least one legacy caller - MUST behave as follows, assuming - arg0..n−1 is the list of argument - values passed to [[Call]]: -
--
-
- Initialize S to the effective overload set - for legacy callers on I and with argument count n. -
- - Let <operation, values> be the result of passing S and - arg0..n−1 to the - overload resolution algorithm. - -
- Perform the actions listed in the description of the legacy caller operation with - values as the argument values. -
- Return the result of converting - the return value from those actions to an ECMAScript value of the type - operation is declared to return (or undefined - if operation is declared to return void). -
--4.8.10. Property enumeration
- -- This document does not define a complete property enumeration order - for all platform objects implementing interfaces - (or for platform objects representing exceptions). - However, if a platform object implements an interface that - supports indexed or - named properties, then - properties on the object MUST be - enumerated in the following order: -
--
-
- If the object supports indexed properties, then - the object’s supported property indices are - enumerated first, in numerical order. -
- If the object supports named properties and doesn't implement an interface with the - [LegacyUnenumerableNamedProperties] - extended attribute, then - the object’s supported property names that - are visible according to the named property visibility algorithm - are enumerated next, in the order given in the definition of the set of supported property names. -
- Finally, any enumerable own properties or properties from the object’s prototype chain are then enumerated, - in no defined order. -
-Note-Future versions of the ECMAScript specification may define a total order for property enumeration.
--- -4.9. User objects implementing callback interfaces
- -- As described in section 3.10 above, - callback interfaces can be - implemented in script by an ECMAScript object. - The following cases determine whether and how a given object - is considered to be a user object implementing a callback interface: -
--
-
-
- If the interface is a single operation callback interface
- (defined below) then any object apart from a native RegExp
- object is considered to implement the interface.
- The implementation of the operation (or set of overloaded operations) is
- as follows:
-
-
-
- If the object is callable, - then the implementation of the operation (or set of overloaded operations) is - the callable object itself. -
- Otherwise, the object is not callable. - The implementation of the operation (or set of overloaded operations) is - the result of invoking the internal [[Get]] method - on the object with a property name that is the identifier - of the operation. -
- - - Otherwise, the interface is not a single operation callback interface. - Any object that is not a native - RegExp object is considered to implement the interface. - For each operation declared on the interface with a given identifier, the implementation - is the result of invoking [[Get]] on the object with a - property name that is that identifier. - -
- Note that ECMAScript objects need not have - properties corresponding to constants - on them to be considered as user objects - implementing interfaces that happen - to have constants declared on them. -
- -- A single operation callback interface is - a callback interface that: -
--
-
- is not declared to inherit from another interface, -
- has no attributes, and -
- has one or more regular operations that all have the same identifier, - and no others. -
- To call a user object's - operation, given a callback interface - type value value, sometimes-optional operation name opName, - list of argument values arg0..n−1 each of which is - either an IDL value or the special value “missing” (representing a missing optional - argument), and optional callback this - value thisArg, perform the following steps. These steps will either - return an IDL value or throw an exception. -
- --
-
- Let completion be an uninitialized variable. - -
- If thisArg was not given, let thisArg be undefined. - -
- Let O be the ECMAScript object corresponding to value. - -
- Let realm be O's associated Realm. - -
- Let relevant settings be realm's settings - object. - -
- Let stored settings be value's callback context. - -
- Prepare to run script with relevant settings. - -
- Prepare to run a callback with stored settings. - -
-
- Determine the implementation of the operation, X:
-
-
-
-
- If value's interface is a single operation callback - interface and ! IsCallable(O) is true, then set - X to O. - -
- - Otherwise, opName must be supplied: - - -
-
-
- - If ! IsCallable(X) is false, - then set completion to a new Completion{[[Type]]: throw, [[Value]]: a - newly created TypeError object, [[Target]]: empty}, and jump - to the step labeled return. - -
- If value's interface is not a single operation callback interface, - or if ! IsCallable(O) is false, - set thisArg to O (overriding the provided value). - -
- Let esArgs be an empty List of ECMAScript values. - -
- Let i be 0. - -
- Let count be 0. - -
-
- While i < n:
-
-
-
-
- If argi is the special value “missing”, then - append undefined to esArgs. - -
-
- Otherwise, argi is an IDL value:
-
-
-
-
- Let convertResult be the result of converting - argi to an ECMAScript value. - -
- If convertResult is an abrupt completion, set completion - to convertResult and jump to the step labeled return. - -
- Append convertResult.[[Value]] to esArgs. - -
- Set count to i + 1. -
-
- - Set i to i + 1. -
-
- - Truncate esArgs to have length count. - -
- Let callResult be Call(X, thisArg, - esArgs). - -
- If callResult is an abrupt completion, set completion to - callResult and jump to the step labeled return. - -
- Set completion to the result of converting - callResult.[[Value]] to an IDL value of the same type as the operation’s - return type. - -
-
- Return: at this
- point completion will be set to an ECMAScript completion value.
-
-
-
-
- Clean up after running a callback with stored settings. - -
- Clean up after running script with relevant settings. - -
- If completion is a normal completion, return - completion. - -
- If completion is an abrupt completion and the operation has a return type that is not a promise type, return completion. - -
- Let reject be the initial value of %Promise%.reject. - -
- Let rejectedPromise be the result of calling reject with - %Promise% as the this value and - completion.[[Value]] as the single argument value. - -
- Return the result of converting - rejectedPromise to the operation's return type. -
-
- To get a user object's - attribute value, given a callback - interface type value object and attribute name attributeName, - perform the following steps. These steps will either return an IDL value or throw an - exception. -
- --
-
- Let completion be an uninitialized variable. - -
- Let O be the ECMAScript object corresponding to object. - -
- Let realm be O's associated Realm. - -
- Let relevant settings be realm's settings - object. - -
- Let stored settings be object's callback context. - -
- Prepare to run script with relevant settings. - -
- Prepare to run a callback with stored settings. - -
- Let getResult be Get(O, attributeName). - -
- If getResult is an abrupt completion, set completion to - getResult and jump to the step labeled return. - -
- Set completion to the result of converting - getResult.[[Value]] to an IDL value of the same type as the attribute's - type. - -
-
- Return: at this
- point completion will be set to an ECMAScript completion value.
-
-
-
-
- Clean up after running a callback with stored settings. - -
- Clean up after running script with relevant settings. - -
- If completion is a normal completion, return - completion. - -
- If completion is an abrupt completion and the attribute's type is - not a promise type, return - completion. - -
- Let reject be the initial value of %Promise%.reject. - -
- Let rejectedPromise be the result of calling reject with - %Promise% as the this value and - completion.[[Value]] as the single argument value. - -
- Return the result of converting - rejectedPromise to the attribute's type. -
-
- To set a user object's - attribute value, given a callback - interface type value object, attribute name attributeName, and - IDL value value, perform the following steps. These steps will not return - anything, but could throw an exception. -
- --
-
- Let completion be an uninitialized variable. - -
- Let O be the ECMAScript object corresponding to object. - -
- Let realm be O's associated Realm. - -
- Let relevant settings be realm's settings - object. - -
- Let stored settings be object's callback context. - -
- Prepare to run script with relevant settings. - -
- Prepare to run a callback with stored settings. - -
- Let convertResult be the result of converting value to an - ECMAScript value. - -
- If convertResult is an abrupt completion, set completion to - convertResult and jump to the step labeled return. - -
- Set completion to Set(O, attributeName, - convertResult.[[Value]], true). - -
-
- Return: at this
- point completion will be set to an ECMAScript completion value, which is
- either an abrupt completion or a normal completion for the value true (as returned by Set).
-
-
-
-
- Clean up after running a callback with stored settings. - -
- Clean up after running script with relevant settings. - -
- If completion is an abrupt completion, return - completion. - -
- Return NormalCompletion(void). -
-
-- -4.10. Invoking callback functions
- -- An ECMAScript callable object that is being - used as a callback function value is - called in a manner similar to how operations - on user objects are called (as - described in the previous section). -
- -- To invoke a callback function type value callable with - a list of arguments arg0..n−1, each of which is either - an IDL value or the special value “missing” (representing a missing optional argument), - and with optional callback this - value thisArg, perform the following steps. These steps will either - return an IDL value or throw an exception. -
- --
-
- Let completion be an uninitialized variable. - -
- If thisArg was not given, let thisArg be undefined. - -
- Let F be the ECMAScript object corresponding to value. - -
-
- If ! IsCallable(F) is false:
-
-
-
-
-
-
If the callback function's return type is void, - return.
- --Note-This is only possible when the callback function came from an attribute - marked with [TreatNonObjectAsNull].
-
-
- - Return the result of converting undefined to the callback function's return type. -
-
- -
-
- Let realm be F's associated Realm. - -
- Let relevant settings be realm's settings - object. - -
- Let stored settings be callable's callback context. - -
- Prepare to run script with relevant settings. - -
- Prepare to run a callback with stored settings. - -
- Let esArgs be an empty List of ECMAScript values. - -
- Let i be 0. - -
- Let count be 0. - -
-
- While i < n:
-
-
-
-
- If argi is the special value “missing”, then - append undefined to esArgs. - -
-
- Otherwise, argi is an IDL value:
-
-
-
-
- Let convertResult be the result of converting - argi to an ECMAScript value. - -
- If convertResult is an abrupt completion, set completion - to convertResult and jump to the step labeled return. - -
- Append convertResult.[[Value]] to esArgs. - -
- Set count to i + 1. -
-
- - Set i to i + 1. -
-
- - Truncate esArgs to have length count. - -
- Let callResult be Call(X, thisArg, - esArgs). - -
- If callResult is an abrupt completion, set completion to - callResult and jump to the step labeled return. - -
- Set completion to the result of converting - callResult.[[Value]] to an IDL value of the same type as the operation’s - return type. - -
-
- Return: at this
- point completion will be set to an ECMAScript completion value.
-
-
-
-
- Clean up after running a callback with stored settings. - -
- Clean up after running script with relevant settings. - -
- If completion is a normal completion, return - completion. - -
- If completion is an abrupt completion and the callback function has a - return type that is not a promise type, return completion. - -
- Let reject be the initial value of %Promise%.reject. - -
- Let rejectedPromise be the result of calling reject with - %Promise% as the this value and - completion.[[Value]] as the single argument value. - -
- Return the result of converting - rejectedPromise to the callback function's return type. -
-
-- -4.11. Namespaces
- -- For every namespace that is exposed in a given ECMAScript global environment, - a corresponding property MUST exist on the ECMAScript - environment's global object. The name of the property is the identifier of the namespace, and its value is an object - called the namespace object. -
-- The property has the attributes { [[Writable]]: true, [[Enumerable]]: false, - [[Configurable]]: true }. The characteristics of a - namespace object are described in section 4.11.1 below. -
- ---4.11.1. Namespace object
- -- The namespace object for a given namespace - namespace and Realm realm is created as - follows: -
- --
-
- - Let namespaceObject be - ! ObjectCreate(the %ObjectPrototype% of realm). - - -
-
- For each exposed regular operation op that is a namespace member of this namespace,
-
-
-
-
- - Let F be the result of creating an operation function given - op, namespace, and realm. - - -
- - Perform ! CreateDataProperty(namespaceObject, - op's identifier, - F). - -
-
-- -4.12. Exceptions
- -- There MUST exist a property on the ECMAScript global object - whose name is “DOMException” and value is an object called the - DOMException constructor object, - which provides access to legacy DOMException code constants and allows construction of - DOMException instances. - The property has the attributes { [[Writable]]: true, [[Enumerable]]: false, [[Configurable]]: true }. -
- --- -4.12.1. DOMException constructor object
- -- The DOMException constructor object MUST be a function object - but with a [[Prototype]] value of %Error% ([ECMA-262], section 6.1.7.4). -
-- For every legacy code listed in the error names table, - there MUST be a property on the DOMException constructor object - whose name and value are as indicated in the table. The property has - attributes { [[Writable]]: false, [[Enumerable]]: true, [[Configurable]]: false }. -
-- The DOMException constructor object MUST also have a property named - “prototype” with attributes - { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: false } - whose value is an object called the DOMException prototype object. - This object also provides access to the legacy code values. -
- ---4.12.1.1. DOMException(message, name)
- -When the DOMException function is called with arguments message and name, the following steps are taken:
- --
-
- Let F be the active function object. -
- If NewTarget is undefined, let newTarget be F, else let newTarget be NewTarget. -
- Let super be F.[[GetPrototypeOf]](). -
- ReturnIfAbrupt(super). -
- If IsConstructor(super) is false, throw a TypeError exception. -
- Let O be Construct(super, «message», newTarget). -
- If name is not undefined, then
-
-
-
- Let name be ToString(name). -
- Let status be DefinePropertyOrThrow(O,
"name", PropertyDescriptor{[[Value]]: name, [[Writable]]: true, [[Enumerable]]: false, [[Configurable]]: true}).
- - ReturnIfAbrupt(status). -
- Let code be the legacy code indicated in the error names table for error name name, or 0 if there is none. -
- Let status be DefinePropertyOrThrow(O,
"code", PropertyDescriptor{[[Value]]: code, [[Writable]]: true, [[Enumerable]]: false, [[Configurable]]: true}).
- - ReturnIfAbrupt(status). -
- - Return O. -
--4.12.2. DOMException prototype object
- -- The DOMException prototype object MUST - have an internal [[Prototype]] property whose value is %ErrorPrototype% ([ECMA-262], section 6.1.7.4). -
-- The class string of the - DOMException prototype object - is “DOMExceptionPrototype”. -
-- There MUST be a property named “constructor” - on the DOMException prototype object with attributes - { [[Writable]]: true, [[Enumerable]]: false, [[Configurable]]: true } - and whose value is the DOMException constructor object. -
-- For every legacy code listed in the error names table, - there MUST be a property on the DOMException prototype object - whose name and value are as indicated in the table. The property has - attributes { [[Writable]]: false, [[Enumerable]]: true, [[Configurable]]: false }. -
--- -4.13. Exception objects
- -- Simple exceptions are represented - by native ECMAScript objects of the corresponding type. -
-- DOMExceptions are represented by - platform objects that inherit from - the DOMException prototype object. -
-- Every platform object representing a DOMException in ECMAScript is associated with a global environment, just - as the initial objects are. - When an exception object is created by calling the DOMException constructor object, - either normally or as part of a
-newexpression, then the global environment - of the newly created object is associated with MUST be the same as for the - DOMException constructor object itself. -- The value of the internal [[Prototype]] - property of a DOMException - object MUST be the DOMException prototype object - from the global environment the exception object is associated with. -
-- The class string - of a DOMException object - MUST be “DOMException”. -
--Note-The intention is for DOMException objects to be just like the other - various native Error objects that the - ECMAScript specification defines, apart from responding differently - to being passed to Object.prototype.toString and it having a “code” property. - If an implementation places non-standard properties on native - Error objects, exposing for example - stack traces or error line numbers, then these ought to be exposed - on exception objects too.
--- -4.14. Creating and throwing exceptions
- -- First, we define the current global environment - as the result of running the following algorithm: -
--
-
- - Let F be the Function object used - as the this value in the top-most call - on the ECMAScript call stack where F corresponds to an IDL - attribute, - operation, - indexed property, - named property, - constructor, - named constructor or - stringifier. - -
- - If F corresponds to an attribute, operation or stringifier, then return - the global environment associated with the - interface that definition appears on. - -
- - Otherwise, if F corresponds to an indexed or named property, then return - the global environment associated with the interface that - the indexed or named property getter, setter or deleter was defined on. - -
- - Otherwise, if F is a named constructor for an interface, or is - an interface object for an - interface that is a constructor, then return the global environment - associated with that interface. - -
- - Otherwise, F is an exception field getter. Return - the global environment associated with the exception on which the - exception field was defined. - -
- When a simple exception or - DOMException - E is to be created, - with error name N and - optional user agent-defined message M, - the following steps MUST be followed: -
--
-
- If M was not specified, let M be undefined. Otherwise, let it be the result of converting M to a String value. -
- Let N be the result of converting N to a String value. -
- Let args be a list of ECMAScript values.
-
-
-
- E is DOMException -
- args is (undefined, N). -
- E is a simple exception -
- args is (M) -
- - Let G be the current global environment. -
- Let X be an object determined based on the type of E:
-
-
-
- E is DOMException -
- X is the DOMException constructor object - from the global environment G. -
- E is a simple exception -
- X is the constructor for the corresponding ECMAScript error - from the global environment G. -
- - Let O be the result of calling X as a function - with args as the argument list. -
- Return O. -
- When a simple exception or - DOMException - E is to be thrown, - with error name N and - optional user agent-defined message M, - the following steps MUST be followed: -
--
-
- Let O be the result of creating - the specified exception E with error name N and - optional user agent-defined message M. -
- Throw O. -
-Note-- The above algorithms do not restrict platform objects representing exceptions - propagating out of a Function to be - ones that are associated with the global environment - where that Function object originated. - For example, consider the IDL: -
--IDL+
+interface A { - - /** +Thus, prose is required to explain the stringification behavior, such + as the following paragraph:
++
+Objects that implement the
+Studentinterface must stringify as follows. If the value of thefamilyNameattribute isnull , the stringification of the + object is the value of thegivenNameattribute. Otherwise, if the value of thefamilyNameattribute is notnull , + the stringification of the object is the concatenation of the + value of thegivenNameattribute, + a single space character, and the value of + thefamilyNameattribute.An ECMAScript implementation of the IDL would behave as follows:
+var s = new Student(); +s.id = 12345679; +s.familyName = 'Smithee'; +s.givenName = 'Alan'; + +var greeting = 'Hi ' + s; // Now greeting == 'Hi Alan Smithee'.
+3.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
+serializerkeyword: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
+DOMStringvalues (unique in the map) and the +values are serialized values -
+
a list of serialized values
+ -
+
a
+DOMStringvalue -
+
an
+unrestricted doublevalue -
+
a
+booleanvalue -
+
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
+toJSONmethod which returns the serialized value converted +into an ECMAScript value that can be serialized to JSON by theJSON.stringifyfunction. See §4.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
+serializerkeyword 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
+inheritkeyword 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:
+-
+
-
+
Let map be an empty map.
+ -
+
If the
+inheritkeyword was used, then set map to be the result of +the serialization behavior of the +closest inherited interface that declares a serializer. -
+
For each attribute identifier i in the serialization pattern, in order:
+-
+
-
+
Remove any entry in map with key name i.
+ -
+
Let V be the value of the attribute with identifier i.
+ -
+
Add an entry to map whose key name is i and whose +value is result of converting V to a serialized value.
+
-
+
-
+
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
+inheritkeyword 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:
+-
+
-
+
Let map be an empty map.
+ -
+
If the
+inheritkeyword was used, then set map to be the result of +the serialization behavior of the +closest inherited interface that declares a serializer. -
+
For each identifier i of an attribute on the interface whose type is +a serializable type, in the order they appear +on the interface:
+-
+
-
+
Remove any entry in map with key name i.
+ -
+
Let V be the value of the attribute with identifier i.
+ -
+
Add an entry to map whose key name is i and whose +value is result of converting V to a serialized value.
+
-
+
-
+
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:
+-
+
-
+
Let map be an empty map.
+ -
+
For each supported property name n on the object, in order:
+-
+
-
+
Let V be the value of the named property with name n.
+ -
+
Add an entry to map whose key name is i and whose +value is result of converting V to a serialized value.
+
-
+
-
+
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:
+-
+
-
+
Let list be an empty list.
+ -
+
For each attribute identifier i in the serialization pattern:
+-
+
-
+
Let V be the value of the attribute with identifier i.
+ -
+
Append to list the value that is the result of converting V to a serialized value.
+
-
+
-
+
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:
+-
+
-
+
Let list be an empty list.
+ -
+
Let i be 0.
+ -
+
While i is less than or equal to the greatest supported property index on the object:
+-
+
-
+
Let V be the value of the indexed property with index i if i is a supported property index, or
+null otherwise. -
+
Append to list the value that is the result of converting V to a serialized value.
+ -
+
Set i to i + 1.
+
-
+
-
+
Return map.
+
-
+
-
+
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:
+-
+
-
+
Let V be the value of the attribute with the specified identifier.
+ -
+
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.stringifycan produce.The list of serializable types and how they are converted to serialized values is as follows:
+-
+
- + +
-
+
converted by choosing the closest equivalent
+doublevalue +(as when converting along longto an ECMAScriptNumber value) - + +
-
+
converted by choosing the closest equivalent
+doublevalue +(as when converting aunsigned long longto an ECMAScriptNumber value) -
+
any other integer type
+- + +
-
+
converted by choosing the equivalent
+doublevalue -
+
+
- + +
- + +
- + +
-
+
the same value of the respective type
+ - + +
-
+
the equivalent
+DOMStringvalue - + +
-
+
the
+DOMStringproduced by +encoding the given sequence of Unicode scalar values in +UTF-16 - + +
-
+
the equivalent
+DOMStringvalue 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
+serializerkeyword: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 + ε +
++ ++The following IDL fragment defines + an interface
+Transactionthat has a serializer defines in prose: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; +}; +
+The serializer could be defined as follows:
++
+The serialization behavior of the
+Transactioninterface is to run the following + algorithm, where O is the object that implementsTransaction:-
+
-
+
Let map be an empty map.
+ -
+
Add an entry to map whose key is “from” and whose value is +the serialized value of +the
+numberattribute on theAccountobject referenced by thefromattribute on O. -
+
Add an entry to map whose key is “to” and whose value is +the serialized value of +the
+numberattribute on theAccountobject referenced by thefromattribute on O. -
+
For both of the attributes
+amountanddescription, +add an entry to map whose key is the identifier of the attribute +and whose value is the serialized value of the value of the attribute on O. -
+
Return map.
+
If it was acceptable for
+Accountobjects to be serializable + on their own, then serialization patterns could be used to avoid having to define the serialization behavior in prose: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; +}; +
+In the ECMAScript language binding, there would exist a
+toJSONmethod onTransactionobjects:// 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);
+3.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 longargument. +Indexed property setters must +be declared to take two arguments, where the first is anunsigned 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.
+
++Note that if an indexed property getter or setter is specified using an operation with an identifier, + then indexing an object with an integer that is not a supported property index does not necessarily elicit the same behavior as invoking the operation with that index. The actual behavior in this + case is language binding specific.
+In the ECMAScript language binding, a regular property lookup is done. For example, take the following IDL:
+interface A { + getter DOMString toWord(unsigned long index); +}; +
+Assume that an object implementing
+Ahas supported property indices in the range 0 ≤ index < 2. Also assume that toWord is defined to return + its argument converted into an English word. The behavior when invoking the operation with an out of range index + is different from indexing the object directly: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".
++ ++The following IDL fragment defines an interface
+OrderedMapwhich allows + retrieving and setting values by name or by index number:interface OrderedMap { + readonly attribute unsigned long size; + + getter any getByIndex(unsigned long index); + setter void setByIndex(unsigned long index, any value); + + getter any get(DOMString name); + setter void set(DOMString name, any value); +}; +
+Since all of the special operations are declared using + operations with identifiers, the only additional prose + that is necessary is that which describes what keys those sets + have. Assuming that the
+get()operation is + defined to returnnull if an + attempt is made to look up a non-existing entry in theOrderedMap, then the following + two sentences would suffice:+
+An object map implementing
+OrderedMapsupports indexed properties with indices in the range + 0 ≤ index <map.size.Such objects also support a named property for every name that, + if passed to
+get(), would return a non-null value.As described in §4.8 Platform objects implementing interfaces, + an ECMAScript implementation would create + properties on a platform object implementing
+OrderedMapthat correspond to + entries in both the named and indexed property sets. + These properties can then be used to interact + with the object in the same way as invoking the object’s + methods, as demonstrated below:// Assume map is a 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")
+3.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
+DOMStringargument. +Named property setters must +be declared to take two arguments, where the first is aDOMString.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.
+3.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
+statickeyword 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 +
++ ++The following IDL fragment defines an interface
+Circlethat has a static + operation declared on it:interface Point { /* ... */ }; + +interface Circle { + attribute double cx; + attribute double cy; + attribute double radius; + + static readonly attribute long triangulationCount; + static Point triangulate(Circle c1, Circle c2, Circle c3); +}; +
+In the ECMAScript language binding, the
+Function object fortriangulateand the accessor property fortriangulationCountwill exist on the interface object forCircle: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);
+3.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.
+++For example, the overloads for both f and g are disallowed:
+interface A { + void f(); +}; + +partial interface A { + void f(double x); + void g(); +}; + +partial interface A { + void g(DOMString x); +}; +
+Note that the [
+Constructor] and + [NamedConstructor] extended attributes are disallowed from appearing + on partial interface definitions, + so there is no need to also disallow overloading for constructors.An effective overload set represents the allowable invocations for a particular operation, +constructor (specified with [
+Constructor] +or [NamedConstructor]), legacy caller or callback function. +The algorithm to compute an effective overload set operates on one of the following six types of IDL constructs, and listed with them below are +the inputs to the algorithm needed to compute the set.-
+
-
+
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 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.
+The algorithm below describes how to compute an effective overload set. +The following input variables are used, if they are required:
+-
+
-
+
the identifier of the operation or named constructor is A
+ -
+
the argument count is N
+ -
+
the interface is I
+ -
+
the callback function is C
+
Whenever an argument of an extended +attribute is mentioned, it is referring to an argument of the +extended attribute’s named argument list.
+-
+
-
+
Initialize S to ∅.
+ -
+
Let F be a set with elements as follows, according to the kind of effective overload set:
+-
+
-
+
For regular operations
+ -
+
The elements of F are the regular operations with +identifier A defined on interface I.
+ -
+
For static operations
+ -
+
The elements of F are the static operations with +identifier A defined on interface I.
+ -
+
For constructors
+ -
+
The elements of F are the +[
+Constructor] extended attributes on interface I. -
+
For named constructors
+ -
+
The elements of F are the +[
+NamedConstructor] extended attributes on interface I whose named argument lists’ identifiers are A. -
+
For legacy callers
+ -
+
The elements of F are the legacy callers defined on interface I.
+ -
+
For callback functions
+ -
+
The single element of F is the callback function itself, C.
+
-
+
-
+
Let maxarg be the maximum number of arguments the operations, constructor extended attributes or callback functions in F are declared to take. +For variadic operations and constructor extended attributes, +the argument on which the ellipsis appears counts as a single argument.
+Note: So
+void f(long x, long... y);is considered to be declared to take two arguments. -
+
Let m be the maximum of maxarg and N.
+ -
+
For each operation, extended attribute or callback function X in F:
+-
+
-
+
Let n be the number of arguments X is declared to take.
+ -
+
Let t0..n−1 be a list of types, where ti is the type of X’s argument at index i.
+ -
+
Let o0..n−1 be a list of optionality values, where oi is “variadic” if X’s argument at index i is a final, variadic argument, +“optional” if the argument is optional, +and “required” otherwise.
+ -
+
Add to S the tuple <X, t0..n−1, o0..n−1>.
+ -
+
If X is declared to be variadic, then:
+-
+
-
+
For every integer i, such that n ≤ i ≤ m−1:
+-
+
-
+
Let u0..i be a list of types, where uj = tj (for j < n) and uj = tn−1 (for j ≥ n).
+ -
+
Let p0..i be a list of optionality values, where pj = oj (for j < n) and pj = “variadic” (for j ≥ n).
+ -
+
Add to S the tuple <X, u0..i, p0..i>.
+
-
+
-
+
-
+
Initialize i to n−1.
+ -
+
While i ≥ 0:
+-
+
-
+
If argument i of X is not optional (i.e., it is not marked as
+optionaland is not +a final, variadic argument), then break this loop. -
+
Otherwise, add to S the tuple <X, t0..i−1, o0..i−1>.
+ -
+
Set i to i−1.
+
-
+
-
+
-
+
The effective overload set is S.
+
+ ++For the following interface:
+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); +}; +
+assuming
+NodeandEventare two other interfaces of which no object can implement both, + the effective overload set for regular operations with + identifierfand argument count 4 is:{ <f1, (DOMString), (required)>, + <f2, (Node, DOMString), (required, required)>, + <f2, (Node, DOMString, double), (required, required, variadic)>, + <f2, (Node, DOMString, double, double), (required, required, variadic, variadic)>, + <f3, (), ()>, + <f4, (Event, DOMString), (required, required)>, + <f4, (Event, DOMString, DOMString), (required, required, optional)>, + <f4, (Event, DOMString, DOMString, double), (required, required, optional, variadic)> } ++Two types are distinguishable if +at most one of the two includes a nullable type or is a dictionary type, +and at least one of the following three conditions is true:
+-
+
-
+
The two types (taking their inner types if they are nullable types) appear +in the following table and there is a “●” mark in the corresponding entry +or there is a letter in the corresponding entry and the designated additional +requirement below the table is satisfied:
++ +
++ + + boolean++ numeric types++ string types++ interface++ object++ callback function++ dictionary++ sequence<T>++ FrozenArray<T>++ RegExp++ exception types++ buffer source types++ boolean + + ● + ● + ● + ● + ● + ● + ● + ● + ● + ● + ● + + numeric types + + + ● + ● + ● + ● + ● + ● + ● + ● + ● + ● + + string types + + + + ● + ● + ● + ● + ● + ● + ● + ● + ● + + interface + + + + (a) + + (b) + (b) + ● + ● + ● + ● + ● + + object + + + + + + + + + + + + + + callback function + + + + + + + + ● + ● + ● + ● + ● + + dictionary + + + + + + + + ● + ● + ● + ● + ● + + sequence<T> + + + + + + + + + + ● + ● + ● + + FrozenArray<T> + + + + + + + + + + ● + ● + ● + + RegExp + + + + + + + + + + + ● + ● + + exception types + + + + + + + + + + + + ● + + buffer source types + + + + + + + + + + + + + -
+
-
+
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.
+ -
+
The interface type is not a callback interface.
+
-
+
-
+
One type is a union type or nullable union type, +the other is neither a union type nor a nullable union type, and each member type of the first is distinguishable +with the second.
+ -
+
Both types are either a union type or nullable union type, and each member type of the one +is distinguishable with each member type of the other.
+
Note: Promise types do not appear in the above table, and as a consequence +are not distinguishable with any other type.
+If there is more than one entry in an effective overload set that has a given type list length, then for those entries there +must be an index i such +that for each pair of entries the types at index i are distinguishable. +The lowest such index is termed the distinguishing argument index for the entries of the effective overload set with the given type list length.
++ ++Consider the effective overload set shown in the previous example. + There are multiple entries in the set with type lists 2, 3 and 4. + For each of these type list lengths, the distinguishing argument index is 0, since
+NodeandEventare distinguishable.The following use of overloading however is invalid:
+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.
++ ++The following is invalid:
+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); +}; +
+For argument count 4, the effective overload set is:
+{ <f1, (DOMString), (required)>, + <f2, (long, double, Node, Node), (required, required, required, required)>, + <f3, (double, double, DOMString, Node), (required, required, required, required)> } ++Looking at entries with type list length 4, the distinguishing argument index is 2, since
+NodeandDOMStringare distinguishable. + However, since the arguments in these two overloads at index 0 are different, + the overloading is invalid.3.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.
+++The ECMAScript forEach method that is generated for a value iterator invokes its callback like Array.prototype.forEach does, and the forEach + method for a pair iterator invokes its callback like Map.prototype.forEach does.
+Since value iterators are currently allowed only on interfaces that support indexed properties, + it makes sense to use an Array-like forEach method. + There may be a need for value iterators (a) on interfaces that do not support indexed properties, + or (b) with a forEach method that instead invokes its callback like + Set.protoype.forEach (where the key is the same as the value). + If you’re creating an API that needs such a forEach method, please send a request to public-script-coord@w3.org.
+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.
++ ++Consider the following interface
+SessionManager, which allows access to + a number ofSessionobjects:interface SessionManager { + Session getSessionForUser(DOMString username); + readonly attribute unsigned long sessionCount; + + iterable<Session>; +}; + +interface Session { + readonly attribute DOMString username; + // ... +}; +
+The behavior of the iterator could be defined like so:
++
+The values to iterate over are the open
+Sessionobjects + on theSessionManagersorted by username.Fix reference to removed definition for "values to iterate over".
+In the ECMAScript language binding, the interface prototype object for the
+SessionManagerinterface has avaluesmethod that is a function, which, when invoked, + returns an iterator object that itself has anextmethod that returns the + next value to be iterated over. It hasvaluesandentriesmethods that iterate over the indexes of the list of session objects + and [index, session object] pairs, respectively. It also has + a @@iterator method that allows aSessionManagerto be used in afor..ofloop:// 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 + ε +
+3.2.8. Maplike declarations
+An interface can be declared to be maplike by using a maplike declaration (matching
+ReadWriteMaplike orreadonly 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
+readonlykeyword 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 thereadonlykeyword 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.
+ +3.2.9. Setlike declarations
+An interface can be declared to be setlike by using a setlike declaration (matching
+ReadWriteSetlike orreadonly 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
+readonlykeyword 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 thereadonlykeyword 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.
+ +3.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 +
++ ++The following IDL fragment defines an namespace.
+namespace VectorUtils { + double dotProduct(Vector x, Vector y); + Vector crossProduct(Vector x, Vector y); +}; +
+An ECMAScript implementation would then expose a global property named
+VectorUtilswhich was a simple object (with prototype %ObjectPrototype%) with enumerable data properties for each declared operation: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 }.
+3.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 forboolean-typed dictionary members, + as this can be confusing for authors who might otherwise expect the default + conversion ofundefined to be used (i.e.,false ).Each dictionary member (matching
+DictionaryMember ) is specified +as a type (matchingType ) followed by an identifier (given by anidentifier token following +the type). The identifier is the key name of the key–value pair. +If theType 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 (
+trueorfalse), +thenulltoken, +aninteger token, afloat token, +one of the three special floating point literal values (Infinity,-InfinityorNaN), +astring 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
+requiredkeyword, 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.
+++For example, with the following definitions:
+dictionary B : A { + long b; + long a; +}; + +dictionary A { + long c; + long g; +}; + +dictionary C : B { + long e; + long f; +}; + +partial dictionary A { + long h; + long d; +}; +
+the order of the dictionary members of a dictionary value of type
+Cis + c, d, g, h, a, b, e, f.Dictionaries are required to have their members ordered because + in some language bindings the behavior observed when passing + a dictionary value to a platform object depends on the order + the dictionary members are fetched. For example, consider the + following additional interface:
+interface Something { + void f(A a); +}; +
+and this ECMAScript code:
+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 order that the dictionary members are fetched in determines + what values they will be taken to have. Since the order for
+Ais defined to be c then d, + the value for c will be 1 and the value for d will be 2.The identifier of a dictionary member must not be +the same as that of another dictionary member defined on the dictionary or +on that dictionary’s inherited dictionaries.
+Dictionaries must not be used as the type of an attribute or constant.
+The following extended attributes are applicable to dictionaries: +[
+Constructor], +[Exposed], +[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 + ε +
+ + ++ ++One use of dictionary types is to allow a number of optional arguments to + an operation without being + constrained as to the order they are specified at the call site. For example, + consider the following IDL fragment:
+[Constructor] +interface Point { + attribute double x; + attribute double y; +}; + +dictionary PaintOptions { + DOMString? fillPattern = "black"; + DOMString? strokePattern = null; + Point position; +}; + +interface GraphicsContext { + void drawRectangle(double width, double height, optional PaintOptions options); +}; +
+In an ECMAScript implementation of the IDL, an
+Object can be passed in for the optionalPaintOptionsdictionary:// Get an instance of GraphicsContext. +var ctx = getGraphicsContext(); + +// Draw a rectangle. +ctx.drawRectangle(300, 200, { fillPattern: "red", position: new Point(10, 10) });
+Both fillPattern and strokePattern are given default values, + so if they are omitted, the definition of drawRectangle can assume that they + have the given default values and not include explicit wording to handle + their non-presence.
+3.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 names:
+ +These correspond to all of the ECMAScript error objects (apart from
+SyntaxError , which is deliberately omitted as +it is for use only by the ECMAScript parser). +The meaning of +each simple exception matches +its correspondingError 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 theDOMException'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, +andDOMExceptionwhich includes just DOMException objects. +This allows for example an operation to be declared to have aDOMExceptionreturn type or an attribute to be of typeError.Exceptions can be created by providing its error name. +Exceptions can also be thrown, by providing the +same details required to create one.
+The resulting behavior from creating and throwing an exception is language binding-specific.
+Note: See §4.14 Creating and throwing exceptions for details on what creating and throwing an exception +entails in the ECMAScript language binding.
++ ++Here is are some examples of wording to use to create and throw exceptions. + To throw a new simple exception named
+TypeError:+
+Throw a TypeError.
+To throw a new
+DOMExceptionwith error nameIndexSizeError:+
+Throw an IndexSizeError.
+To create a new
+DOMExceptionwith error nameSyntaxError:+
+Let object be a newly created SyntaxError.
+3.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!
++ +
++ +Name + Description + Legacy codename and value ++ " IndexSizeError" +The index is not in the allowed range. + INDEX_SIZE_ERR(1) ++ " HierarchyRequestError" +The operation would yield an incorrect node tree. + HIERARCHY_REQUEST_ERR(3) ++ " WrongDocumentError" +The object is in the wrong document. + WRONG_DOCUMENT_ERR(4) ++ " InvalidCharacterError" +The string contains invalid characters. + INVALID_CHARACTER_ERR(5) ++ " NoModificationAllowedError" +The object can not be modified. + NO_MODIFICATION_ALLOWED_ERR(7) ++ " NotFoundError" +The object can not be found here. + NOT_FOUND_ERR(8) ++ " NotSupportedError" +The operation is not supported. + NOT_SUPPORTED_ERR(9) ++ " InUseAttributeError" +The attribute is in use. + INUSE_ATTRIBUTE_ERR(10) ++ " InvalidStateError" +The object is in an invalid state. + INVALID_STATE_ERR(11) ++ " SyntaxError" +The string did not match the expected pattern. + SYNTAX_ERR(12) ++ " InvalidModificationError" +The object can not be modified in this way. + INVALID_MODIFICATION_ERR(13) ++ " NamespaceError" +The operation is not allowed by Namespaces in XML. [XML-NAMES] + NAMESPACE_ERR(14) ++ " InvalidAccessError" +The object does not support the operation or argument. + INVALID_ACCESS_ERR(15) ++ " SecurityError" +The operation is insecure. + SECURITY_ERR(18) ++ " NetworkError" +A network error occurred. + NETWORK_ERR(19) ++ " AbortError" +The operation was aborted. + ABORT_ERR(20) ++ " URLMismatchError" +The given URL does not match another URL. + URL_MISMATCH_ERR(21) ++ " QuotaExceededError" +The quota has been exceeded. + QUOTA_EXCEEDED_ERR(22) ++ " TimeoutError" +The operation timed out. + TIMEOUT_ERR(23) ++ " InvalidNodeTypeError" +The supplied node is incorrect or has an incorrect ancestor for this operation. + INVALID_NODE_TYPE_ERR(24) ++ " DataCloneError" +The object can not be cloned. + DATA_CLONE_ERR(25) ++ " EncodingError" +The encoding operation (either encoded or decoding) failed. + — + + " NotReadableError" +The I/O read operation failed. + — + + " UnknownError" +The operation failed for an unknown transient reason (e.g. out of memory). + — + + " ConstraintError" +A mutation operation in a transaction failed because a constraint was not satisfied. + — + + " DataError" +Provided data is inadequate. + — + + " TransactionInactiveError" +A request was placed against a transaction which is currently not active, or which is finished. + — + + " ReadOnlyError" +The mutating operation was attempted in a "readonly" transaction. + — + + " VersionError" +An attempt was made to open a database using a lower version than the existing version. + — + + " OperationError" +The operation failed for an operation-specific reason. + — + + " NotAllowedError" +The request is not allowed by the user agent or the platform in the current context, possibly because the user denied permission. + — + 3.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 possibleDOMStringvalues 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 + ε +
++ ++The following IDL fragment defines an enumeration that is used as the type of an attribute and an operation argument:
+enum MealType { "rice", "noodles", "other" }; + +interface Meal { + attribute MealType type; + attribute double size; // in grams + + void initialize(MealType type, double size); +}; +
+An ECMAScript implementation would restrict the strings that can be + assigned to the type property or passed to the initializeMeal function + to those identified in the enumeration.
+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.
+3.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 andArgumentList ) 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 ")" ";" +++ ++The following IDL fragment defines + a callback function used for an API that + invokes a user-defined function when an operation is complete.
+callback AsyncOperationCallback = void (DOMString status); + +interface AsyncOperations { + void performOperation(AsyncOperationCallback whenFinished); +}; +
+In the ECMAScript language binding, a
+Function object is + passed as the operation argument.var ops = getAsyncOperations(); // Get an instance of AsyncOperations. + +ops.performOperation(function(status) { + window.alert("Operation finished, status is " + status + "."); +});
+3.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
+typedefkeyword (matchingType ), and theidentifier 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 ";" +
++ ++The following IDL fragment demonstrates the use of typedefs to allow the use of a short identifier instead of a long sequence type.
+interface Point { + attribute double x; + attribute double y; +}; + +typedef sequence<Point> Points; + +interface Widget { + boolean pointWithinBounds(Point p); + boolean allPointsWithinBounds(Points ps); +}; +
+3.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.
+
++Specification authors are discouraged from writing implements statements where the interface on the left-hand side + is a supplemental interface. + For example, if author 1 writes:
+interface Window { /* ... */ }; +interface SomeFunctionality { /* ... */ }; +Window implements SomeFunctionality; +
+and author 2 later writes:
+interface Gizmo { /* ... */ }; +interface MoreFunctionality { /* ... */ }; +SomeFunctionality implements MoreFunctionality; +Gizmo implements SomeFunctionality; +
+then it might be the case that author 2 is unaware of exactly which + interfaces already are used on the left-hand side of an
+implements SomeFunctionalitystatement, and so has + required more objects implementMoreFunctionalitythan he or she expected.Better in this case would be for author 2 to write:
+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.
+++For example, that precludes the following:
+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 ";" +
++ ++The following IDL fragment defines two interfaces, stating + that one interface is always implemented on objects implementing the other.
+interface Entry { + readonly attribute unsigned short entryType; + // ... +}; + +interface Observable { + void addEventListener(DOMString type, + EventListener listener, + boolean useCapture); + // ... +}; + +Entry implements Observable; +
+An ECMAScript implementation would thus have an “addEventListener” + property in the prototype chain of every
+Entry:var e = getEntry(); // Obtain an instance of Entry. +typeof e.addEventListener; // Evaluates to "function".
+Note that it is not the case that all
+Observableobjects implementEntry.3.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 representing IDL
+DOMExceptions.
In a browser, for example, +the browser-implemented DOM objects (implementing interfaces such as
+NodeandDocument) 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
+Nodeinterface +will not be treated as platform objects that implementNodeby 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
+EventListenerinterface, which is +used to register a callback that the DOM Events implementation invokes, would be considered +to be a user object.Note that user objects can only implement callback interfaces and platform objects can only implement non-callback interfaces.
+3.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 longandunsigned long long.The following types are known as numeric types: +the integer types,
+float,unrestricted float,doubleandunrestricted double.The primitive types are
+booleanand the numeric types.The string types are
+DOMString, all enumeration types,ByteStringandUSVString.The exception types are
+ErrorandDOMException.The typed array types are
+Int8Array,Int16Array,Int32Array,Uint8Array,Uint16Array,Uint32Array,Uint8ClampedArray,Float32ArrayandFloat64Array.The buffer source types are
+ArrayBuffer,DataView, +and the typed array types.The
+objecttype, +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 + "ByteString" Null + "DOMString" Null + "USVString" Null + identifier Null + "sequence" "<" Type ">" Null + "object" Null + "RegExp" Null + "Error" Null + "DOMException" Null + BufferRelatedType Null + "FrozenArray" "<" Type ">" Null +
+ +PrimitiveType : + UnsignedIntegerType + UnrestrictedFloatType + "boolean" + "byte" + "octet" +
+UnrestrictedFloatType : + "unrestricted" FloatType + FloatType +
+FloatType : + "float" + "double" +
+UnsignedIntegerType : + "unsigned" IntegerType + IntegerType +
+IntegerType : + "short" + "long" OptionalLong +
+OptionalLong : + "long" + ε +
+PromiseType : + "Promise" "<" ReturnType ">" +
+Null : + "?" + ε +
+3.11.1. any
+The
+anytype is the union of all other possible +non-union types. +Its type name is “Any”.The
+anytype is like +a discriminated union type, in that each of its values has a +specific non-anytype +associated with it. For example, one value of theanytype is theunsigned long150, while another is thelong150. +These are distinct values.The particular type of an
+anyvalue is known as its specific type. +(Values of union types also have specific types.)3.11.2. boolean
+The
+booleantype has two values:true andfalse .
+booleanconstant values in IDL are +represented with thetrueandfalsetokens.The type name of the
+booleantype is “Boolean”.3.11.3. byte
+The
+bytetype is a signed integer +type that has values in the range [−128, 127].
+byteconstant values in IDL are +represented withinteger tokens.The type name of the
+bytetype is “Byte”.3.11.4. octet
+The
+octettype is an unsigned integer +type that has values in the range [0, 255].
+octetconstant values in IDL are +represented withinteger tokens.The type name of the
+octettype is “Octet”.3.11.5. short
+The
+shorttype is a signed integer +type that has values in the range [−32768, 32767].
+shortconstant values in IDL are +represented withinteger tokens.The type name of the
+shorttype is “Short”.3.11.6. unsigned short
+The
+unsigned shorttype is an unsigned integer +type that has values in the range [0, 65535].
+unsigned shortconstant values in IDL are +represented withinteger tokens.The type name of the
+unsigned shorttype is “UnsignedShort”.3.11.7. long
+The
+longtype is a signed integer +type that has values in the range [−2147483648, 2147483647].
+longconstant values in IDL are +represented withinteger tokens.The type name of the
+longtype is “Long”.3.11.8. unsigned long
+The
+unsigned longtype is an unsigned integer +type that has values in the range [0, 4294967295].
+unsigned longconstant values in IDL are +represented withinteger tokens.The type name of the
+unsigned longtype is “UnsignedLong”.3.11.9. long long
+The
+long longtype is a signed integer +type that has values in the range [−9223372036854775808, 9223372036854775807].
+long longconstant values in IDL are +represented withinteger tokens.The type name of the
+long longtype is “LongLong”.3.11.10. unsigned long long
+The
+unsigned long longtype is an unsigned integer +type that has values in the range [0, 18446744073709551615].
+unsigned long longconstant values in IDL are +represented withinteger tokens.The type name of the
+unsigned long longtype is “UnsignedLongLong”.3.11.11. float
+The
+floattype is a floating point numeric +type that corresponds to the set of finite single-precision 32 bit +IEEE 754 floating point numbers. [IEEE-754]
+floatconstant values in IDL are +represented withfloat tokens.The type name of the
+floattype is “Float”.Unless there are specific reasons to use a 32 bit floating point type, + specifications should use
+doublerather thanfloat, + since the set of values that adoublecan + represent more closely matches an ECMAScriptNumber .3.11.12. unrestricted float
+The
+unrestricted floattype 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 floatconstant values in IDL are +represented withfloat tokens.The type name of the
+unrestricted floattype is “UnrestrictedFloat”.3.11.13. double
+The
+doubletype is a floating point numeric +type that corresponds to the set of finite double-precision 64 bit +IEEE 754 floating point numbers. [IEEE-754]
+doubleconstant values in IDL are +represented withfloat tokens.The type name of the
+doubletype is “Double”.3.11.14. unrestricted double
+The
+unrestricted doubletype 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 doubleconstant values in IDL are +represented withfloat tokens.The type name of the
+unrestricted doubletype is “UnrestrictedDouble”.3.11.15. DOMString
+The
+DOMStringtype 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. +WhileDOMStringis defined to be +an OMG IDL boxedsequence<unsigned short> valuetype +in DOM Level 3 Core §The DOMString Type, +this document definesDOMStringto 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 typeDOMString. +To allownull , a nullableDOMString, +written asDOMString?in IDL, needs to be used.Nothing in this specification requires a
+DOMStringvalue to be a valid UTF-16 string. For example, aDOMStringvalue might include unmatched surrogate pair characters. However, authors +of specifications using Web IDL might want to obtain a sequence of Unicode scalar values given a particular sequence of code units. +The following algorithm defines a way to convert a DOMString to a sequence of Unicode scalar values:-
+
-
+
Let S be the
+DOMStringvalue. -
+
Let n be the length of S.
+ -
+
Initialize i to 0.
+ -
+
Initialize U to be an empty sequence of Unicode characters.
+ -
+
While i < n:
+-
+
-
+
Let c be the code unit in S at index i.
+ -
+
Depending on the value of c:
+-
+
-
+
c < 0xD800 or c > 0xDFFF
+ -
+
Append to U the Unicode character with code point c.
+ -
+
0xDC00 ≤ c ≤ 0xDFFF
+ -
+
Append to U a U+FFFD REPLACEMENT CHARACTER.
+ -
+
0xD800 ≤ c ≤ 0xDBFF
+ -
+
-
+
-
+
If i = n−1, then append to U a U+FFFD REPLACEMENT CHARACTER.
+ -
+
Otherwise, i < n−1:
+-
+
-
+
Let d be the code unit in S at index i+1.
+ -
+
If 0xDC00 ≤ d ≤ 0xDFFF, then:
+-
+
-
+
Let a be c & 0x3FF.
+ -
+
Let b be d & 0x3FF.
+ -
+
Append to U the Unicode character with +code point 216+210a+b.
+ -
+
Set i to i+1.
+
-
+
-
+
Otherwise, d < 0xDC00 or d > 0xDFFF. +Append to U a U+FFFD REPLACEMENT CHARACTER.
+
-
+
-
+
-
+
-
+
Set i to i+1.
+
-
+
-
+
Return U.
+
There is no way to represent a constant
+DOMStringvalue in IDL, althoughDOMStringdictionary member and operation optional argument default values +can be specified using astring literal.The type name of the
+DOMStringtype is “String”.3.11.16. ByteString
+The
+ByteStringtype +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
+ByteStringvalue in IDL, althoughByteStringdictionary member and operation optional argument default values +can be specified using astring literal.The type name of the
+ByteStringtype is “ByteString”.Specifications should only use
+ByteStringfor interfacing with protocols + that use bytes and strings interchangably, such as HTTP. In general, + strings should be represented withDOMStringvalues, 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 withoctetorbyteelements should be used for holding + 8 bit data rather thanByteString.3.11.17. USVString
+The
+USVStringtype +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
+USVStringvalue in IDL, althoughUSVStringdictionary member and operation optional argument default values +can be specified using astring literal.The type name of the
+USVStringtype is “USVString”.Specifications should only use
+USVStringfor APIs that perform + text processing and need a string of Unicode + scalar values to operate on. Most APIs that use strings + should instead be usingDOMString, + which does not make any interpretations of the code units in the string. When in doubt, useDOMString.3.11.18. object
+The
+objecttype corresponds to the set of +all possible non-null object references.There is no way to represent a constant
+objectvalue in IDL.To denote a type that includes all possible object references plus the
+null value, use the nullable typeobject?.The type name of the
+objecttype is “Object”.3.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 §4.2.20 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.
+3.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.
+3.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 astring literal.The type name of an enumeration type +is the identifier of the enumeration.
+3.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 §4.2.23 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.
+3.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 +beany, +another nullable type, or a union type that itself has includes a nullable type or has a dictionary type as one of its flattened member types.Note: Although dictionary types can in general be nullable, they cannot when used +as the type of an operation argument or a dictionary member.
+Nullable type constant values in IDL are represented in the same way that +constant values of their inner type would be represented, or with the
+nulltoken.The type name of a nullable type +is the concatenation of the type name of the inner type T and +the string “OrNull”.
++ ++For example, a type that allows the values
+true ,false andnull is written asboolean?:interface MyConstants { + const boolean? ARE_WE_THERE_YET = false; +}; +
+The following interface has two attributes: one whose value can + be a
+DOMStringor thenull value, and another whose value can be a reference to aNodeobject or thenull value:interface Node { + readonly attribute DOMString? namespaceURI; + readonly attribute Node? parentNode; + // ... +}; +
+3.11.24. Sequences — 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”.
+3.11.25. Promise types — Promise<T>
+A promise type is a parameterized type +whose values are references to objects that “is used as a place holder +for the eventual results of a deferred (and possibly asynchronous) computation +result of an asynchronous operation”. +See section 25.4 of the ECMAScript specification for details on the semantics of promise objects.
+There is no way to represent a promise value in IDL.
+The type name of a promise type +is the concatenation of the type name for T and +the string “Promise”.
+3.11.26. 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 theorkeyword +with a set of surrounding parentheses. +The types which comprise the union type are known as the +union’s member types.++For example, you might write
+(Node or DOMString)or(double or sequence<double>). When applying a?suffix to a union type as a whole, it is placed after the closing parenthesis, + as in(Node or DOMString)?.Note that the member types of a union type do not descend into nested union types. So for
+(double or (sequence<long> or Event) or (Node or DOMString)?)the member types + aredouble,(sequence<long> or Event)and(Node or DOMString)?.Like the
+anytype, values of +union types have a specific type, +which is the particular member type that matches the value.The flattened member types of a union type is a set of types +determined as follows:
+-
+
-
+
Let T be the union type.
+ -
+
Initialize S to ∅.
+ -
+
For each member type U of T:
+-
+
-
+
If U is a nullable type, then +set U to be the inner type of U.
+ -
+
If U is a union type, then +add to S the flattened member types of U.
+ -
+
Otherwise, U is not a union type. +Add U to S.
+
-
+
-
+
Return S.
+
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 typesNode,sequence<long>,Event,XMLHttpRequest,DOMStringandsequence<(sequence<double> or NodeList)>.The number of nullable member types of a union type is an integer +determined as follows:
+-
+
-
+
Let T be the union type.
+ -
+
Initialize n to 0.
+ -
+
For each member type U of T:
+-
+
-
+
If U is a nullable type, then:
+-
+
-
+
Set n to n + 1.
+ -
+
Set U to be the inner type of U.
+
-
+
-
+
If U is a union type, then:
+-
+
-
+
Let m be the number of nullable member types of U.
+ -
+
Set n to n + m.
+
-
+
-
+
-
+
Return n.
+
The
+anytype must not +be used as a union member type.The number of nullable member types of a union type must +be 0 or 1, and if it is 1 then the union type must also not have +a dictionary type in its flattened member types.
+A type includes a nullable type if:
+-
+
-
+
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”.
+ + + + +3.11.27. RegExp
+The
+RegExptype is a type +whose values are references to objects that represent regular expressions. +The particular regular expression language and the features it supports +is language binding specific.There is no way to represent a constant
+RegExpvalue in IDL.The type name of the
+RegExptype is “RegExp”.3.11.28. Error
+The
+Errortype corresponds to the +set of all possible non-null references to exception objects, including simple exceptions andDOMExceptions.There is no way to represent a constant
+Errorvalue in IDL.The type name of the
+Errortype is “Error”.3.11.29. DOMException
+The
+DOMExceptiontype corresponds to the +set of all possible non-null references to objects +representingDOMExceptions.There is no way to represent a constant
+DOMExceptionvalue in IDL.The type name of the
+DOMExceptiontype is “DOMException”.3.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.
++ +
++ Type + Kind of buffer + + ArrayBuffer + An object that holds a pointer (which may be null) to a buffer of a fixed number of bytes + + DataView + A view on to an ArrayBufferthat allows typed access to integers and floating point values stored at arbitrary offsets into the buffer ++ Int8Array,
Int16Array,
Int32Array +A view on to an ArrayBufferthat exposes it as an array of two’s complement signed integers of the given size in bits ++ Uint8Array,
Uint16Array,
Uint32Array +A view on to an ArrayBufferthat exposes it as an array of unsigned integers of the given size in bits ++ Uint8ClampedArray + A view on to an ArrayBufferthat exposes it as an array of unsigned 8 bit integers with clamped conversions ++ Float32Array,
Float64Array +A view on to an ArrayBufferthat exposes it as an array of IEEE 754 floating point numbers of the given size in bits +Note: These types all correspond to classes defined in ECMAScript.
+To detach an
+ArrayBufferis to set its buffer pointer tonull .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.
+++Extreme care must be taken when writing specification text that gets a reference + to the bytes held by a buffer source, as the underyling data can easily be changed + by the script author or other APIs at unpredictable times. If you are using a buffer source type + as an operation argument to obtain a chunk of binary data that will not be modified, + it is strongly recommended to get a copy of the buffer source’s bytes at the beginning + of the prose defining the operation.
+Requiring prose to explicitly get a reference to or copy of the bytes is intended to + help specification reviewers look for problematic uses of these buffer source types.
+++When designing APIs that take a buffer, it is recommended to use the
+BufferSourcetypedef rather thanArrayBufferor any of the view types.When designing APIs that create and return a buffer, it is recommended + to use the
+ArrayBuffertype rather thanUint8Array.Attempting to get a reference to or get a copy of the bytes held by a buffer source when the
+ArrayBufferhas been detached will fail in a language binding-specific manner.Note: See §4.2.31 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" +
+3.11.31. Frozen arrays — 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”.
+3.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 ofExtendedAttribute s.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:+ +
++ Grammar symbol + Form + Example + + ExtendedAttributeNoArgs +takes no arguments + [Replaceable]++ ExtendedAttributeArgList +takes an argument list + [Constructor(double x, double y)]++ ExtendedAttributeNamedArgList +takes a named argument list + [NamedConstructor=Image(DOMString src)]++ ExtendedAttributeIdent +takes an identifier + [PutForwards=name]++ ExtendedAttributeIdentList +takes an identifier list + [Exposed=(Window,Worker)]+This specification defines a number of extended attributes that +are applicable to the ECMAScript language binding, which are described in §4.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" + "RegExp" + "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 ")" ++4. ECMAScript binding
+This section describes how definitions written with the IDL defined in §3 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 ECMAScriptSomethingError object +and to throw it, just as the algorithms in ECMA-262 do.Note that algorithm steps can call in to other algorithms and abstract operations and +not explicitly handle exceptions that are thrown from them. When an exception +is thrown by an algorithm or abstract operation and it is not explicitly +handled by the caller, then it is taken to end the algorithm and propagate out +to its caller, and so on.
++ ++Consider the following algorithm:
+-
+
-
+
Let x be the ECMAScript value passed in to this algorithm.
+ -
+
Let y be the result of calling ToString(x).
+ -
+
Return y.
+
Since ToString can throw an exception (for example if passed the object
+({ toString: function() { throw 1 } })), and the exception is + not handled in the above algorithm, if one is thrown then it causes this + algorithm to end and for the exception to propagate out to its caller, if there + is one.4.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:
+-
+
- + +
- + +
- + +
- + +
- + +
- + +
- + +
- + +
- + +
- + +
- + +
- + +
- + +
- + +
- + +
- + +
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.
++ ++In an HTML user agent, multiple global environments can exist when + multiple frames or windows are created. Each frame or window will have + its own set of initial objects, + which the following HTML document demonstrates:
+<!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 §4.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.
+4.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.
+4.2.1. any
+Since the IDL
+anytype +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
+anyvalue depends on the type of the + ECMAScript value:-
+
-
+
The
+undefined value -
+
The IDL value is an
+objectreference +to a special object that represents the ECMAScriptundefined value. -
+
The
+null value -
+
The IDL value is the
+null object?reference. -
+
A
+Boolean value -
+
The IDL value is the
+booleanvalue 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 IDLunrestricted doublevalue, +as described in §4.2.15 unrestricted double. -
+
A
+String value -
+
The IDL value is that which is obtained +by following the rules for converting the
+String to an IDLDOMStringvalue, +as described in §4.2.16 DOMString. -
+
An
+objectvalue -
+
The IDL value is an
+objectvalue that +references the same object.
An IDL
+anyvalue is converted to an ECMAScript value as follows. If the value is anobjectreference to a special object that represents an ECMAScriptundefined value, then it is converted to the ECMAScriptundefined value. Otherwise, + the rules for converting the specific type of the IDLanyvalue + as described in the remainder of this section are performed.4.2.2. void
+The only place that the
+voidtype may appear +in IDL is as the return type of an operation. Functions on platform objects that implement an operation whose IDL specifies avoidreturn type must return theundefined value.ECMAScript functions that implement an operation whose IDL +specifies a
+voidreturn type +may return any value, which will be discarded.4.2.3. boolean
+An ECMAScript value V is converted to an IDL
+booleanvalue + by running the following algorithm:-
+
-
+
Let x be the result of computing ToBoolean(V).
+ -
+
Return the IDL
+booleanvalue that is the one that represents the same truth value as the ECMAScriptBoolean value x.
The IDL
+booleanvaluetrue is converted to + the ECMAScripttrue value and the IDLbooleanvaluefalse is converted to the ECMAScriptfalse value.4.2.4. byte
+An ECMAScript value V is converted to an IDL
+bytevalue + by running the following algorithm:-
+
-
+
Initialize x to ToNumber(V).
+ -
+
If the conversion to an IDL value is being performed due to any of the following:
+-
+
-
+
V is being assigned to an attribute annotated with the [
+EnforceRange] extended attribute, -
+
V is being passed as an operation argument annotated with the [
+EnforceRange] extended attribute, or -
+
V is being used as the value of a dictionary member annotated with the [
+EnforceRange] extended attribute,
then:
+-
+
-
+
If x is
+NaN , +∞, or −∞, then throw aTypeError . - + +
-
+
If x < −27 or x > 27 − 1, then throw a
+TypeError . -
+
Return the IDL
+bytevalue that represents the same numeric value as x.
-
+
-
+
If x is not
+NaN and the conversion to an IDL value is being performed due to any of the following:-
+
-
+
V is being assigned to an attribute annotated with the [
+Clamp] extended attribute, -
+
V is being passed as an operation argument annotated with the [
+Clamp] extended attribute, or -
+
V is being used as the value of a dictionary member annotated with the [
+Clamp] extended attribute,
then:
+-
+
-
+
Set x to min(max(x, −27), 27 − 1).
+ -
+
Round x to the nearest integer, choosing the even integer if it lies halfway between two, and choosing +0 rather than −0.
+ -
+
Return the IDL
+bytevalue that represents the same numeric value as x.
-
+
-
+
If x is
+NaN , +0, −0, +∞, or −∞, then return the IDLbytevalue that represents 0. - + +
-
+
Set x to x modulo 28.
+ -
+
If x ≥ 27, return the IDL
+bytevalue that represents the same numeric value as x − 28. +Otherwise, return the IDLbytevalue that represents the same numeric value as x.
The result of converting an IDL
+bytevalue to an ECMAScript + value is aNumber that represents + the same numeric value as the IDLbytevalue. + TheNumber value will be an integer in the range [−128, 127].4.2.5. octet
+An ECMAScript value V is converted to an IDL
+octetvalue + by running the following algorithm:-
+
-
+
Initialize x to ToNumber(V).
+ -
+
If the conversion to an IDL value is being performed due to any of the following:
+-
+
-
+
V is being assigned to an attribute annotated with the [
+EnforceRange] extended attribute, -
+
V is being passed as an operation argument annotated with the [
+EnforceRange] extended attribute, or -
+
V is being used as the value of a dictionary member annotated with the [
+EnforceRange] extended attribute,
then:
+-
+
-
+
If x is
+NaN , +∞, or −∞, then throw aTypeError . - + +
-
+
If x < 0 or x > 28 − 1, then throw a
+TypeError . -
+
Return the IDL
+octetvalue that represents the same numeric value as x.
-
+
-
+
If x is not
+NaN and the conversion to an IDL value is being performed due to any of the following:-
+
-
+
V is being assigned to an attribute annotated with the [
+Clamp] extended attribute, -
+
V is being passed as an operation argument annotated with the [
+Clamp] extended attribute, or -
+
V is being used as the value of a dictionary member annotated with the [
+Clamp] extended attribute,
then:
+-
+
-
+
Set x to min(max(x, 0), 28 − 1).
+ -
+
Round x to the nearest integer, choosing the even integer if it lies halfway between two, and choosing +0 rather than −0.
+ -
+
Return the IDL
+octetvalue that represents the same numeric value as x.
-
+
-
+
If x is
+NaN , +0, −0, +∞, or −∞, then return the IDLoctetvalue that represents 0. - + +
-
+
Set x to x modulo 28.
+ -
+
Return the IDL
+octetvalue that represents the same numeric value as x.
The result of converting an IDL
+octetvalue to an ECMAScript + value is aNumber that represents + the same numeric value as the IDLoctetvalue. + TheNumber value will be an integer in the range [0, 255].4.2.6. short
+An ECMAScript value V is converted to an IDL
+shortvalue + by running the following algorithm:-
+
-
+
Initialize x to ToNumber(V).
+ -
+
If the conversion to an IDL value is being performed due to any of the following:
+-
+
-
+
V is being assigned to an attribute annotated with the [
+EnforceRange] extended attribute, -
+
V is being passed as an operation argument annotated with the [
+EnforceRange] extended attribute, or -
+
V is being used as the value of a dictionary member annotated with the [
+EnforceRange] extended attribute,
then:
+-
+
-
+
If x is
+NaN , +∞, or −∞, then throw aTypeError . - + +
-
+
If x < −215 or x > 215 − 1, then throw a
+TypeError . -
+
Return the IDL
+shortvalue that represents the same numeric value as x.
-
+
-
+
If x is not
+NaN and the conversion to an IDL value is being performed due to any of the following:-
+
-
+
V is being assigned to an attribute annotated with the [
+Clamp] extended attribute, -
+
V is being passed as an operation argument annotated with the [
+Clamp] extended attribute, or -
+
V is being used as the value of a dictionary member annotated with the [
+Clamp] extended attribute,
then:
+-
+
-
+
Set x to min(max(x, −215), 215 − 1).
+ -
+
Round x to the nearest integer, choosing the even integer if it lies halfway between two, and choosing +0 rather than −0.
+ -
+
Return the IDL
+shortvalue that represents the same numeric value as x.
-
+
-
+
If x is
+NaN , +0, −0, +∞, or −∞, then return the IDLshortvalue that represents 0. - + +
-
+
Set x to x modulo 216.
+ -
+
If x ≥ 215, return the IDL
+shortvalue that represents the same numeric value as x − 216. +Otherwise, return the IDLshortvalue that represents the same numeric value as x.
The result of converting an IDL
+shortvalue to an ECMAScript + value is aNumber that represents the + same numeric value as the IDLshortvalue. + TheNumber value will be an integer in the range [−32768, 32767].4.2.7. unsigned short
+An ECMAScript value V is converted to an IDL
+unsigned shortvalue + by running the following algorithm:-
+
-
+
Initialize x to ToNumber(V).
+ -
+
If the conversion to an IDL value is being performed due to any of the following:
+-
+
-
+
V is being assigned to an attribute annotated with the [
+EnforceRange] extended attribute, -
+
V is being passed as an operation argument annotated with the [
+EnforceRange] extended attribute, or -
+
V is being used as the value of a dictionary member annotated with the [
+EnforceRange] extended attribute,
then:
+-
+
-
+
If x is
+NaN , +∞, or −∞, then throw aTypeError . - + +
-
+
If x < 0 or x > 216 − 1, then throw a
+TypeError . -
+
Return the IDL
+unsigned shortvalue that represents the same numeric value as x.
-
+
-
+
If x is not
+NaN and the conversion to an IDL value is being performed due to any of the following:-
+
-
+
V is being assigned to an attribute annotated with the [
+Clamp] extended attribute, -
+
V is being passed as an operation argument annotated with the [
+Clamp] extended attribute, or -
+
V is being used as the value of a dictionary member annotated with the [
+Clamp] extended attribute,
then:
+-
+
-
+
Set x to min(max(x, 0), 216 − 1).
+ -
+
Round x to the nearest integer, choosing the even integer if it lies halfway between two, and choosing +0 rather than −0.
+ -
+
Return the IDL
+unsigned shortvalue that represents the same numeric value as x.
-
+
-
+
Set x to ToUint16(x).
+ -
+
Return the IDL
+unsigned shortvalue that represents the same numeric value as x.
The result of converting an IDL
+unsigned shortvalue to an ECMAScript + value is aNumber that + represents the same numeric value as the IDLunsigned shortvalue. + TheNumber value will be an integer in the range [0, 65535].4.2.8. long
+An ECMAScript value V is converted to an IDL
+longvalue + by running the following algorithm:-
+
-
+
Initialize x to ToNumber(V).
+ -
+
If the conversion to an IDL value is being performed due to any of the following:
+-
+
-
+
V is being assigned to an attribute annotated with the [
+EnforceRange] extended attribute, -
+
V is being passed as an operation argument annotated with the [
+EnforceRange] extended attribute, or -
+
V is being used as the value of a dictionary member annotated with the [
+EnforceRange] extended attribute,
then:
+-
+
-
+
If x is
+NaN , +∞, or −∞, then throw aTypeError . - + +
-
+
If x < −231 or x > 231 − 1, then throw a
+TypeError . -
+
Return the IDL
+longvalue that represents the same numeric value as x.
-
+
-
+
If x is not
+NaN and the conversion to an IDL value is being performed due to any of the following:-
+
-
+
V is being assigned to an attribute annotated with the [
+Clamp] extended attribute, -
+
V is being passed as an operation argument annotated with the [
+Clamp] extended attribute, or -
+
V is being used as the value of a dictionary member annotated with the [
+Clamp] extended attribute,
then:
+-
+
-
+
Set x to min(max(x, −231), 231 − 1).
+ -
+
Round x to the nearest integer, choosing the even integer if it lies halfway between two, and choosing +0 rather than −0.
+ -
+
Return the IDL
+longvalue that represents the same numeric value as x.
-
+
-
+
Set x to ToInt32(x).
+ -
+
Return the IDL
+longvalue that represents the same numeric value as x.
The result of converting an IDL
+longvalue to an ECMAScript + value is aNumber that + represents the same numeric value as the IDLlongvalue. + TheNumber value will be an integer in the range [−2147483648, 2147483647].4.2.9. unsigned long
+An ECMAScript value V is converted to an IDL
+unsigned longvalue + by running the following algorithm:-
+
-
+
Initialize x to ToNumber(V).
+ -
+
If the conversion to an IDL value is being performed due to any of the following:
+-
+
-
+
V is being assigned to an attribute annotated with the [
+EnforceRange] extended attribute, -
+
V is being passed as an operation argument annotated with the [
+EnforceRange] extended attribute, or -
+
V is being used as the value of a dictionary member annotated with the [
+EnforceRange] extended attribute,
then:
+-
+
-
+
If x is
+NaN , +∞, or −∞, then throw aTypeError . - + +
-
+
If x < 0 or x > 232 − 1, then throw a
+TypeError . -
+
Return the IDL
+unsigned longvalue that represents the same numeric value as x.
-
+
-
+
If x is not
+NaN and the conversion to an IDL value is being performed due to any of the following:-
+
-
+
V is being assigned to an attribute annotated with the [
+Clamp] extended attribute, -
+
V is being passed as an operation argument annotated with the [
+Clamp] extended attribute, or -
+
V is being used as the value of a dictionary member annotated with the [
+Clamp] extended attribute,
then:
+-
+
-
+
Set x to min(max(x, 0), 232 − 1).
+ -
+
Round x to the nearest integer, choosing the even integer if it lies halfway between two, and choosing +0 rather than −0.
+ -
+
Return the IDL
+unsigned longvalue that represents the same numeric value as x.
-
+
-
+
Set x to ToUint32(x).
+ -
+
Return the IDL
+unsigned longvalue that represents the same numeric value as x.
The result of converting an IDL
+unsigned longvalue to an ECMAScript + value is aNumber that + represents the same numeric value as the IDLunsigned longvalue. + TheNumber value will be an integer in the range [0, 4294967295].4.2.10. long long
+An ECMAScript value V is converted to an IDL
+long longvalue + by running the following algorithm:-
+
-
+
Initialize x to ToNumber(V).
+ -
+
If the conversion to an IDL value is being performed due to any of the following:
+-
+
-
+
V is being assigned to an attribute annotated with the [
+EnforceRange] extended attribute, -
+
V is being passed as an operation argument annotated with the [
+EnforceRange] extended attribute, or -
+
V is being used as the value of a dictionary member annotated with the [
+EnforceRange] extended attribute,
then:
+-
+
-
+
If x is
+NaN , +∞, or −∞, then throw aTypeError . - + +
-
+
If x < −253 + 1 or x > 253 − 1, then throw a
+TypeError . -
+
Return the IDL
+long longvalue that represents the same numeric value as x.
-
+
-
+
If x is not
+NaN and the conversion to an IDL value is being performed due to any of the following:-
+
-
+
V is being assigned to an attribute annotated with the [
+Clamp] extended attribute, -
+
V is being passed as an operation argument annotated with the [
+Clamp] extended attribute, or -
+
V is being used as the value of a dictionary member annotated with the [
+Clamp] extended attribute,
then:
+-
+
-
+
Set x to min(max(x, −253 + 1), 253 − 1).
+ -
+
Round x to the nearest integer, choosing the even integer if it lies halfway between two, and choosing +0 rather than −0.
+ -
+
Return the IDL
+long longvalue that represents the same numeric value as x.
-
+
-
+
If x is
+NaN , +0, −0, +∞, or −∞, then return the IDLlong longvalue that represents 0. - + +
-
+
Set x to x modulo 264.
+ -
+
If x is greater than or equal to 263, then set x to x − 264.
+ -
+
Return the IDL
+long longvalue that represents the same numeric value as x.
The result of converting an IDL
+long longvalue to an ECMAScript + value is aNumber value that + represents the closest numeric value to thelong long, + choosing the numeric value with an even significand if there are + two equally close values. + If thelong longis in the range + [−253 + 1, 253 − 1], then theNumber will be able to represent exactly the same value as thelong long.4.2.11. unsigned long long
+An ECMAScript value V is converted to an IDL
+unsigned long longvalue + by running the following algorithm:-
+
-
+
Initialize x to ToNumber(V).
+ -
+
If the conversion to an IDL value is being performed due to any of the following:
+-
+
-
+
V is being assigned to an attribute annotated with the [
+EnforceRange] extended attribute, -
+
V is being passed as an operation argument annotated with the [
+EnforceRange] extended attribute, or -
+
V is being used as the value of a dictionary member annotated with the [
+EnforceRange] extended attribute,
then:
+-
+
-
+
If x is
+NaN , +∞, or −∞, then throw aTypeError . - + +
-
+
If x < 0 or x > 253 − 1, then throw a
+TypeError . -
+
Return the IDL
+unsigned long longvalue that represents the same numeric value as x.
-
+
-
+
If x is not
+NaN and the conversion to an IDL value is being performed due to any of the following:-
+
-
+
V is being assigned to an attribute annotated with the [
+Clamp] extended attribute, -
+
V is being passed as an operation argument annotated with the [
+Clamp] extended attribute, or -
+
V is being used as the value of a dictionary member annotated with the [
+Clamp] extended attribute,
then:
+-
+
-
+
Set x to min(max(x, 0), 253 − 1).
+ -
+
Round x to the nearest integer, choosing the even integer if it lies halfway between two, and choosing +0 rather than −0.
+ -
+
Return the IDL
+unsigned long longvalue that represents the same numeric value as x.
-
+
-
+
If x is
+NaN , +0, −0, +∞, or −∞, then return the IDLunsigned long longvalue that represents 0. - + +
-
+
Set x to x modulo 264.
+ -
+
Return the IDL
+unsigned long longvalue that represents the same numeric value as x.
The result of converting an IDL
+unsigned long longvalue to an ECMAScript + value is aNumber value that + represents the closest numeric value to theunsigned long long, + choosing the numeric value with an even significand if there are + two equally close values. + If theunsigned long longis less than or equal to 253 − 1, + then theNumber will be able to + represent exactly the same value as theunsigned long long.4.2.12. float
+An ECMAScript value V is converted to an IDL
+floatvalue + by running the following algorithm:-
+
-
+
Let x be ToNumber(V).
+ -
+
If x is
+NaN ,+Infinity or−Infinity , then throw aTypeError . -
+
Let S be the set of finite IEEE 754 single-precision floating +point values except −0, but with two special values added: 2128 and +−2128.
+ -
+
Let y be the number in S that is closest +to x, selecting the number with an even significand if there are two equally close values. +(The two special values 2128 and −2128 are considered to have even significands for this purpose.)
+ -
+
If y is 2128 or −2128, then throw a
+TypeError . -
+
If y is +0 and x is negative, return −0.
+ -
+
Return y.
+
The result of converting an IDL
+floatvalue to an ECMAScript + value is theNumber value that represents the same numeric value as the IDLfloatvalue.4.2.13. unrestricted float
+An ECMAScript value V is converted to an IDL
+unrestricted floatvalue + by running the following algorithm:-
+
-
+
Let x be ToNumber(V).
+ -
+
If x is
+NaN , then return the IDLunrestricted floatvalue that represents the IEEE 754 NaN value with the bit pattern 0x7fc00000 [IEEE-754]. -
+
Let S be the set of finite IEEE 754 single-precision floating +point values except −0, but with two special values added: 2128 and +−2128.
+ -
+
Let y be the number in S that is closest +to x, selecting the number with an even significand if there are two equally close values. +(The two special values 2128 and −2128 are considered to have even significands for this purpose.)
+ -
+
If y is 2128, return +∞.
+ -
+
If y is −2128, return −∞.
+ -
+
If y is +0 and x is negative, return −0.
+ -
+
Return y.
+
Note: Since there is only a single ECMAScript
+NaN value, +it must be canonicalized to a particular single precision IEEE 754 NaN value. The NaN value +mentioned above is chosen simply because it is the quiet NaN with the lowest +value when its bit pattern is interpreted as an unsigned 32 bit integer.The result of converting an IDL
+unrestricted floatvalue to an ECMAScript + value is aNumber :-
+
-
+
If the IDL
+unrestricted floatvalue is a NaN, +then theNumber value isNaN . -
+
Otherwise, the
+Number value is +the one that represents the same numeric value as the IDLunrestricted floatvalue.
4.2.14. double
+An ECMAScript value V is converted to an IDL
+doublevalue + by running the following algorithm:-
+
-
+
Let x be ToNumber(V).
+ -
+
If x is
+NaN ,+Infinity or−Infinity , then throw aTypeError . -
+
Return the IDL
+doublevalue +that has the same numeric value as x.
The result of converting an IDL
+doublevalue to an ECMAScript + value is theNumber value that represents the + same numeric value as the IDLdoublevalue.4.2.15. unrestricted double
+An ECMAScript value V is converted to an IDL
+unrestricted doublevalue + by running the following algorithm:-
+
-
+
Let x be ToNumber(V).
+ -
+
If x is
+NaN , then return the IDLunrestricted doublevalue that represents the IEEE 754 NaN value with the bit pattern 0x7ff8000000000000 [IEEE-754]. -
+
Return the IDL
+unrestricted doublevalue +that has the same numeric value as x.
Note: Since there is only a single ECMAScript
+NaN value, +it must be canonicalized to a particular double precision IEEE 754 NaN value. The NaN value +mentioned above is chosen simply because it is the quiet NaN with the lowest +value when its bit pattern is interpreted as an unsigned 64 bit integer.The result of converting an IDL
+unrestricted doublevalue to an ECMAScript + value is aNumber :-
+
-
+
If the IDL
+unrestricted doublevalue is a NaN, +then theNumber value isNaN . -
+
Otherwise, the
+Number value is +the one that represents the same numeric value as the IDLunrestricted doublevalue.
4.2.16. DOMString
+An ECMAScript value V is converted to an IDL
+DOMStringvalue + by running the following algorithm:-
+
-
+
If V is
+null and the conversion to an IDL value is being performed due +to any of the following:-
+
-
+
V is being passed as an operation argument that is annotated with [
+TreatNullAs], -
+
V is being assigned to an attribute annotated with [
+TreatNullAs], -
+
V is being returned from a user object implementation of an +operation annotated with [
+TreatNullAs], or -
+
V is being returned from a user object implementation of an +attribute annotated with [
+TreatNullAs],
then return the
+DOMStringvalue that represents the empty string. -
+
-
+
Let x be ToString(V).
+ -
+
Return the IDL
+DOMStringvalue that represents the same sequence of code units as the one the ECMAScriptString value x represents.
The result of converting an IDL
+DOMStringvalue to an ECMAScript + value is theString value that represents the same sequence of code units that the + IDLDOMStringrepresents.4.2.17. ByteString
+An ECMAScript value V is converted to an IDL
+ByteStringvalue + by running the following algorithm:-
+
-
+
Let x be ToString(V).
+ -
+
If the value of any element of x is greater than 255, then throw a
+TypeError . -
+
Return an IDL
+ByteStringvalue +whose length is the length of x, and where the value of each element is +the value of the corresponding element of x.
The result of converting an IDL
+ByteStringvalue to an ECMAScript + value is aString value whose length is the length of theByteString, + and the value of each element of which is the value of the corresponding element + of theByteString.4.2.18. USVString
+An ECMAScript value V is converted to an IDL
+USVStringvalue + by running the following algorithm:-
+
-
+
Let string be the result of converting V to a
+DOMString. -
+
Return an IDL
+USVStringvalue +that is the result of converting string to a sequence of Unicode scalar values.
An IDL
+USVStringvalue is converted to an ECMAScript value by running the following algorithm:-
+
-
+
Let scalarValues be the sequence of Unicode scalar values the
+USVStringrepresents. -
+
Let string be the sequence of code units that results from encoding scalarValues in UTF-16.
+ -
+
Return the
+String value that represents the same sequence of code units as string.
4.2.19. object
+IDL
+objectvalues are represented by ECMAScriptObject values.An ECMAScript value V is converted to an IDL
+objectvalue + by running the following algorithm:-
+
-
+
If Type(V) is not Object, then throw a
+TypeError . -
+
Return the IDL
+objectvalue that is a reference to the same object as V.
The result of converting an IDL
+objectvalue to an ECMAScript + value is theObject value that represents a reference to the same object that the + IDLobjectrepresents.4.2.20. Interface types
+IDL interface type values are represented by ECMAScript
+Object orFunction values.An ECMAScript value V is converted to an IDL interface type value + by running the following algorithm (where I is the interface):
+-
+
-
+
If Type(V) is not Object, then throw a
+TypeError . -
+
If V is a platform object that implements I, then return the IDL interface type value that represents a reference to that platform object.
+ -
+
If V is a user object that is considered to implement I according to the rules in §4.9 User objects implementing callback interfaces, then return the IDL interface type value that represents a reference to that +user object, with the incumbent settings object as the callback context.
+ - + +
The result of converting an IDL interface type value to an ECMAScript value is the
+Object value that represents a reference to the same object that the IDL interface type value represents.4.2.21. Dictionary types
+IDL dictionary type values are represented +by ECMAScript
+Object values. Properties on +the object (or its prototype chain) correspond to dictionary members.An ECMAScript value V is converted to an IDL dictionary type value + by running the following algorithm (where D is the dictionary):
+-
+
-
+
If Type(V) is not Undefined, Null or Object, then throw a
+TypeError . -
+
If V is a native
+RegExp object, then throw aTypeError . -
+
Let dict be an empty dictionary value of type D; +every dictionary member is initially considered to be not present.
+ -
+
Let dictionaries be a list consisting of D and all of D’s inherited dictionaries, +in order from least to most derived.
+ -
+
For each dictionary dictionary in dictionaries, in order:
+-
+
-
+
For each dictionary member member declared on dictionary, in lexicographical order:
+-
+
-
+
Let key be the identifier of member.
+ -
+
Let value be an ECMAScript value, depending on Type(V):
+-
+
-
+
Undefined
+- +
Null
+ - +
-
+
value is
+undefined . -
+
anything else
+ -
+
value is the result of calling the [[Get]] internal method on V with property name key.
+
-
+
-
+
If value is not
+undefined , then:-
+
-
+
Let idlValue be the result of converting value to an IDL value whose type is the type member is declared to be of.
+ -
+
Set the dictionary member on dict with key name key to the value idlValue. This dictionary member is considered to be present.
+
-
+
-
+
Otherwise, if value is
+undefined but the dictionary member has a default value, then:-
+
-
+
Let idlValue be the dictionary member’s default value.
+ -
+
Set the dictionary member on dict with key name key to the value idlValue. This dictionary member is considered to be present.
+
-
+
-
+
Otherwise, if value is
+undefined and the dictionary member is a required dictionary member, then throw aTypeError .
-
+
-
+
-
+
Return dict.
+
Note: The order that dictionary members are looked +up on the ECMAScript object are not necessarily the same as the object’s property enumeration order.
+An IDL dictionary value V is converted to an ECMAScript
+Object value + by running the following algorithm (where D is the dictionary):-
+
-
+
Let O be a new
+Object value created as if by the expression({}). -
+
Let dictionaries be a list consisting of D and all of D’s inherited dictionaries, +in order from least to most derived.
+ -
+
For each dictionary dictionary in dictionaries, in order:
+-
+
-
+
For each dictionary member member declared on dictionary, in lexicographical order:
+-
+
-
+
Let key be the identifier of member.
+ -
+
If the dictionary member named key is present in V, then:
+-
+
-
+
Let idlValue be the value of member on V.
+ -
+
Let value be the result of converting idlValue to an ECMAScript value.
+ -
+
Call CreateDataProperty(O, key, value.
+
-
+
-
+
-
+
-
+
Return O.
+
4.2.22. Enumeration types
+IDL enumeration types are represented by ECMAScript
+String values.An ECMAScript value V is converted to an IDL enumeration type value as follows (where E is the enumeration):
+-
+
-
+
Let S be the result of calling ToString(V).
+ -
+
If S is not one of E’s enumeration values, then throw a
+TypeError . -
+
Return the enumeration value of type E that is equal to S.
+
The result of converting an IDL enumeration type value to an ECMAScript + value is the
+String value that represents the same sequence of code units as + the enumeration value.4.2.23. Callback function types
+IDL callback function types are represented by ECMAScript
+Function objects, except in the [TreatNonObjectAsNull] case, +when they can be any object.An ECMAScript value V is converted to an IDL callback function type value + by running the following algorithm:
+-
+
-
+
If the result of calling IsCallable(V) is
+false and the conversion to an IDL value +is not being performed due +to V being assigned to an attribute whose type is a nullable callback function that is annotated with [TreatNonObjectAsNull], +then throw aTypeError . -
+
Return the IDL callback function type value +that represents a reference to the same object that V represents, with the incumbent settings object as the callback context.
+
The result of converting an IDL callback function type value to an ECMAScript value is a reference to the same object + that the IDL callback function type value represents.
+4.2.24. Nullable types — T?
+IDL nullable type values are represented +by values of either the ECMAScript type corresponding to the inner IDL type, or +the ECMAScript
+null value.An ECMAScript value V is converted to an IDL nullable type
+T?value (where T is the inner type) as follows:-
+
-
+
If Type(V) is not Object, and +the conversion to an IDL value is being performed due +to V being assigned to an attribute whose type is a nullable callback function that is annotated with [
+TreatNonObjectAsNull], +then return the IDL nullable typeT?valuenull . -
+
Otherwise, if V is
+null orundefined , then return the IDL nullable typeT?valuenull . -
+
Otherwise, return the result of converting V using the rules for the inner IDL type
+T.
The result of converting an IDL nullable type value to an ECMAScript value is:
+-
+
-
+
If the IDL nullable type
+T?value isnull , +then the ECMAScript value isnull . -
+
Otherwise, the ECMAScript value is the result of converting the IDL nullable type value +to the inner IDL type
+T.
4.2.25. Sequences — sequence<T>
+IDL sequence<T> values are represented by +ECMAScript
+Array values.An ECMAScript value V is converted to an IDL sequence<T> value as follows:
+-
+
-
+
If V is not an object, throw a
+TypeError . -
+
If V is a native
+RegExp object, throw aTypeError . -
+
Let method be the result of GetMethod(V, @@iterator).
+ -
+
ReturnIfAbrupt(method).
+ -
+
If method is
+undefined , throw aTypeError . -
+
Return the result of +.
+
An IDL sequence value S of type sequence<T> is converted to an ECMAScript
+Array object as follows:-
+
-
+
Let n be the length of S.
+ -
+
Let A be a new
+Array object created as if by the expression[]. -
+
Initialize i to be 0.
+ -
+
While i < n:
+-
+
-
+
Let V be the value in S at index i.
+ -
+
Let E be the result of converting V to an ECMAScript value.
+ -
+
Let P be the result of calling ToString(i).
+ -
+
Call CreateDataProperty(A, P, E).
+ -
+
Set i to i + 1.
+
-
+
-
+
Return A.
+
4.2.25.1. Creating a sequence from an iterable
+To create an IDL value of type sequence<T> given an +iterable iterable and an iterator getter method, perform the following steps:
+-
+
-
+
Let iter be GetIterator(iterable, method).
+ -
+
ReturnIfAbrupt(iter).
+ -
+
Initialize i to be 0.
+ -
+
Repeat
+-
+
-
+
Let next be IteratorStep(iter).
+ -
+
ReturnIfAbrupt(next).
+ -
+
If next is
+false , +then return an IDL sequence value of type sequence<T> of length i, where the value of the element +at index j is Sj. -
+
Let nextItem be IteratorValue(next).
+ -
+
ReturnIfAbrupt(nextItem).
+ -
+
Initialize Si to the result of converting nextItem to an IDL value of type T.
+ -
+
Set i to i + 1.
+
-
+
+ ++The following interface defines + an attribute of a sequence + type as well as an operation with an argument of a sequence type.
+interface Canvas { + + sequence<DOMString> getSupportedImageCodecs(); + + void drawPolygon(sequence<double> coordinates); + sequence<double> getLastDrawnPolygon(); + + // ... +}; +
+In an ECMAScript implementation of this interface, an
+Array object with elements of typeString is used to + represent asequence<DOMString>, while anArray with elements of typeNumber represents asequence<double>. TheArray objects are effectively passed by + value; every time thegetSupportedImageCodecs()function is called a newArray is + returned, and whenever anArray is + passed todrawPolygonno reference + will be kept after the call completes.// Obtain an instance of Canvas. Assume that getSupportedImageCodecs() +// returns a sequence with two DOMString values: "image/png" and "image/svg+xml". +var canvas = getCanvas(); + +// An Array object of length 2. +var supportedImageCodecs = canvas.getSupportedImageCodecs(); + +// Evaluates to "image/png". +supportedImageCodecs[0]; + +// Each time canvas.getSupportedImageCodecs() is called, it returns a +// new Array object. Thus modifying the returned Array will not +// affect the value returned from a subsequent call to the function. +supportedImageCodecs[0] = "image/jpeg"; + +// Evaluates to "image/png". +canvas.getSupportedImageCodecs()[0]; + +// This evaluates to false, since a new Array object is returned each call. +canvas.getSupportedImageCodecs() == canvas.getSupportedImageCodecs(); + +// An Array of Numbers... +var a = [0, 0, 100, 0, 50, 62.5]; + +// ...can be passed to a platform object expecting a sequence<double>. +canvas.drawPolygon(a); + +// Each element will be converted to a double by first calling ToNumber(). +// So the following call is equivalent to the previous one, except that +// "hi" will be alerted before drawPolygon() returns. +a = [false, '', + { valueOf: function() { alert('hi'); return 100; } }, 0, + '50', new Number(62.5)]; +canvas.drawPolygon(s); + +// Modifying an Array that was passed to drawPolygon() is guaranteed not to +// have an effect on the Canvas, since the Array is effectively passed by value. +a[4] = 20; +var b = canvas.getLastDrawnPolygon(); +alert(b[4]); // This would alert "50".
+4.2.26. Promise types — Promise<T>
+IDL promise type values are +represented by ECMAScript
+Promise objects.An ECMAScript value V is converted to an IDL Promise<T> value as follows:
+-
+
-
+
Let resolve be the original value of %Promise%.resolve.
+ECMAScript should grow a %Promise_resolve% well-known intrinsic object that can be referenced here.
+ -
+
Let promise be the result of calling resolve with %Promise% as the
+this value and V as the single argument value. -
+
Return the IDL promise type value that is a reference to the +same object as promise.
+
The result of converting an IDL promise type value to an ECMAScript + value is the
+Promise value that represents a reference to the same object that the + IDL promise type represents.One can perform some steps once a promise is settled. +There can be one or two sets of steps to perform, covering when the promise is fulfilled, rejected, or both. +When a specification says to perform some steps once a promise is settled, the following steps +must be followed:
+-
+
-
+
Let promise be the promise object of type Promise<T>.
+ -
+
Let onFulfilled be a new function object whose +behavior when invoked is as follows:
+-
+
-
+
If T is
+void, then:-
+
-
+
Return the result of performing any steps that were required to be run if the promise was fulfilled.
+
-
+
-
+
Otherwise, T is a type other than
+void:-
+
-
+
Let V be the first argument to onFulfilled.
+ -
+
Let value be the result of converting V to an IDL value of type T.
+ -
+
If there are no steps that are required to be run if the promise was fulfilled, then +return
+undefined . -
+
Otherwise, return the result of performing any steps that were required to be run if the promise was fulfilled, +with value as the promise’s value.
+
-
+
-
+
-
+
Let onRejected be a new function object whose +behavior when invoked is as follows:
+-
+
-
+
Let R be the first argument to onRejected.
+ -
+
Let reason be the result of converting R to an IDL value of type
+any. -
+
If there are no steps that are required to be run if the promise was rejected, then +return
+undefined . -
+
Otherwise, return the result of performing any steps that were required to be run if the promise was rejected, +with reason as the rejection reason.
+
-
+
-
+
Let then be the result of calling the internal [[Get]] method of promise with property name “then”.
+ -
+
If then is not callable, then throw a
+TypeError . -
+
Return the result of calling then with promise as the
+this value and onFulfilled and onRejected as its two arguments.
Include an example of how to write spec text using this term.
+4.2.27. Union types
+IDL union type values are +represented by ECMAScript values that correspond to the union’s member types.
+To convert an ECMAScript value V to an IDL union type value is done as follows:
+-
+
-
+
If the union type includes a nullable type and V is
+null orundefined , +then return the IDL valuenull . -
+
Let types be the flattened member types of the union type.
+ -
+
If V is
+null orundefined , and types includes a dictionary type, then return the +result of converting V to that dictionary type. -
+
If V is a platform object, then:
+-
+
-
+
If types includes an interface type that V implements, then return the IDL value that is a reference to the object V.
+ -
+
If types includes
+object, then return the IDL value +that is a reference to the object V.
-
+
-
+
If V is a native
+RegExp object, then:-
+
-
+
If types includes
+RegExp, then return the +result of converting V toRegExp. -
+
If types includes
+object, then return the IDL value +that is a reference to the object V.
-
+
-
+
If V is a
+DOMExceptionplatform object, then:-
+
-
+
If types includes
+DOMExceptionorError, then return the +result of converting V to that type. -
+
If types includes
+object, then return the IDL value +that is a reference to the object V.
-
+
-
+
If V is a native
+Error object (that is, it has an [[ErrorData]] internal slot), then:-
+
-
+
If types includes
+Error, then return the +result of converting V toError. -
+
If types includes
+object, then return the IDL value +that is a reference to the object V.
-
+
-
+
If V is an object with an [[ArrayBufferData]] internal slot, then:
+-
+
-
+
If types includes
+ArrayBuffer, then return the +result of converting V toArrayBuffer. -
+
If types includes
+object, then return the IDL value +that is a reference to the object V.
-
+
-
+
If V is an object with a [[DataView]] internal slot, then:
+-
+
-
+
If types includes
+DataView, then return the +result of converting V toDataView. -
+
If types includes
+object, then return the IDL value +that is a reference to the object V.
-
+
-
+
If V is an object with a [[TypedArrayName]] internal slot, then:
+-
+
-
+
If types includes a typed array type whose name is the value of V’s [[TypedArrayName]] internal slot, then return the +result of converting V to that type.
+ -
+
If types includes
+object, then return the IDL value +that is a reference to the object V.
-
+
-
+
If IsCallable(V) is true, then:
+-
+
-
+
If types includes a callback function type, then return the result of converting V to that callback function type.
+ -
+
If types includes
+object, then return the IDL value +that is a reference to the object V.
-
+
-
+
If V is any kind of object except for +a native
+RegExp object, then:-
+
-
+
If types includes a sequence type, then
+-
+
-
+
Let method be the result of GetMethod(V, @@iterator).
+ -
+
ReturnIfAbrupt(method).
+ -
+
If method is not
+undefined , +return the result of +.
-
+
-
+
If types includes a frozen array type, then
+-
+
-
+
Let method be the result of GetMethod(V, @@iterator).
+ -
+
ReturnIfAbrupt(method).
+ -
+
If method is not
+undefined , +return the result of creating a frozen array of that type from V and method.
-
+
-
+
If types includes a dictionary type, then return the +result of converting V to that dictionary type.
+ -
+
If types includes a callback interface type, then return the result of converting V to that interface type.
+ -
+
If types includes
+object, then return the IDL value +that is a reference to the object V.
-
+
-
+
If V is a
+Boolean value, then:-
+
-
+
If types includes a
+boolean, +then return the result of converting V toboolean.
-
+
-
+
If V is a
+Number value, then:-
+
-
+
If types includes a numeric type, +then return the result of converting V to that numeric type.
+
-
+
-
+
If types includes a string type, +then return the result of converting V to that type.
+ -
+
If types includes a numeric type, +then return the result of converting V to that numeric type.
+ -
+
If types includes a
+boolean, +then return the result of converting V toboolean. - + +
An IDL union type value is converted to an ECMAScript value as follows. If the value is an
+objectreference to a special object that represents an ECMAScriptundefined value, then it is converted to the ECMAScriptundefined value. Otherwise, + the rules for converting the specific type of the IDL union type value as described in this section (§4.2 ECMAScript type mapping).4.2.28. RegExp
+IDL
+RegExpvalues are represented by +ECMAScriptRegExp objects.An ECMAScript value V is converted to an IDL
+RegExpvalue + by running the following algorithm:-
+
-
+
If Type(V) is not Object, +or V is not a native
+RegExp object, +then set V to be a newly createdRegExp object created as if by the +expressionnew RegExp(V), whereRegExpis the standard built-in constructor with that name +from the current global environment.Note: Note that this can result in an exception being thrown, if V, when converted to a string, +does not have valid regular expression syntax.
+ -
+
Return the IDL
+RegExpvalue that is a reference to the same object as V.
The result of converting an IDL
+RegExpvalue to an ECMAScript + value is theRegExp value that represents a reference to the same object that the + IDLRegExprepresents.4.2.29. Error
+IDL
+Errorvalues are represented +by native ECMAScriptError objects and +platform objects forDOMExceptions.An ECMAScript value V is converted to an IDL
+Errorvalue + by running the following algorithm:-
+
-
+
If Type(V) is not Object, +or V does not have an [[ErrorData]] internal slot, then throw a
+TypeError . -
+
Return the IDL
+Errorvalue that is a reference to the same object as V.
The result of converting an IDL
+Errorvalue to an ECMAScript + value is theError value that represents a reference to the same object that the + IDLErrorrepresents.4.2.30. DOMException
+IDL
+DOMExceptionvalues are represented +by platform objects forDOMExceptions.An ECMAScript value V is converted to an IDL
+DOMExceptionvalue + by running the following algorithm:-
+
-
+
If Type(V) is not Object, +or V is not a platform object that represents a
+DOMException, then throw aTypeError . -
+
Return the IDL
+DOMExceptionvalue that is a reference to the same object as V.
The result of converting an IDL
+DOMExceptionvalue to an ECMAScript + value is theObject value that represents a reference to the same object that the + IDLDOMExceptionrepresents.4.2.31. Buffer source types
+Values of the IDL buffer source types are represented by objects of the corresponding ECMAScript class.
+An ECMAScript value V is converted to an IDL
+ArrayBuffervalue + by running the following algorithm:-
+
-
+
If Type(V) is not Object, +or V does not have an [[ArrayBufferData]] internal slot, +or IsDetachedBuffer(V) is true, +then throw a
+TypeError . -
+
Return the IDL
+ArrayBuffervalue that is a reference to the same object as V.
An ECMAScript value V is converted to an IDL
+DataViewvalue + by running the following algorithm:-
+
-
+
If Type(V) is not Object, +or V does not have a [[DataView]] internal slot, +then throw a
+TypeError . -
+
Return the IDL
+DataViewvalue that is a reference to the same object as V.
An ECMAScript value V is converted to an IDL
+Int8Array,Int16Array,Int32Array,Uint8Array,Uint16Array,Uint32Array,Uint8ClampedArray,Float32ArrayorFloat64Arrayvalue +by running the following algorithm:-
+
-
+
Let T be the IDL type V is being converted to.
+ -
+
If Type(V) is not Object, +or V does not have a [[TypedArrayName]] internal slot with a value equal to the name of T, +then throw a
+TypeError . -
+
Return the IDL value of type T that is a reference to the same object as V.
+
The result of converting an IDL value of any buffer source type to an ECMAScript value is the
+Object value that represents +a reference to the same object that the IDL value represents.When getting a reference to or getting a copy of the bytes held by a buffer source that is an ECMAScript
+ArrayBuffer ,DataView or typed array object, these steps must be followed:-
+
-
+
Let O be the ECMAScript object that is the buffer source.
+ -
+
Initialize arrayBuffer to O.
+ -
+
Initialize offset to 0.
+ -
+
Initialize length to 0.
+ -
+
If O has a [[ViewedArrayBuffer]] internal slot, then:
+-
+
-
+
Set arrayBuffer to the value of O’s [[ViewedArrayBuffer]] internal slot.
+ -
+
If arrayBuffer is
+undefined , then throw aTypeError . -
+
Set offset to the value of O’s [[ByteOffset]] internal slot.
+ -
+
Set length to the value of O’s [[ByteLength]] internal slot.
+
-
+
-
+
Otherwise, set length to the value of O’s [[ArrayBufferByteLength]] internal slot.
+ -
+
If IsDetachedBuffer(O), then throw a
+TypeError . -
+
Let data be the value of O’s [[ArrayBufferData]] internal slot.
+ -
+
Return a reference to or copy of (as required) the length bytes in data starting at byte offset offset.
+
To detach an
+ArrayBuffer, +these steps must be followed:-
+
-
+
Let O be the ECMAScript object that is the
+ArrayBuffer. - + +
4.2.32. Frozen arrays — FrozenArray<T>
+Values of frozen array types are represented by frozen ECMAScript
+Array object references.An ECMAScript value V is converted to an IDL FrozenArray<T> value +by running the following algorithm:
+-
+
-
+
Let values be the result of converting V to IDL type sequence<T>.
+ -
+
Return the result of creating a frozen array from values.
+
To create a frozen array from a sequence +of values of type T, follow these steps:
+-
+
-
+
Let array be the result of converting the sequence of values to an ECMAScript value.
+ -
+
Perform SetIntegrityLevel(array,
+"frozen"). -
+
Return array.
+
The result of converting an IDL FrozenArray<T> value to an ECMAScript +value is the
+Object value that represents a reference +to the same object that the IDL FrozenArray<T> represents.4.2.32.1. Creating a frozen array from an iterable
+To create an IDL value of type FrozenArray<T> given an +iterable iterable and an iterator getter method, perform the following steps:
+-
+
-
+
Let values be the result of +.
+ -
+
Return the result of creating a frozen array from values.
+
4.3. ECMAScript-specific extended attributes
+This section defines a number of extended attributes whose presence affects only the ECMAScript binding.
+4.3.1. [Clamp]
+If the [
+Clamp] extended attribute appears on an operation argument, +writable attribute or dictionary member whose type is one of the integer types, +it indicates that when an ECMAScriptNumber is +converted to the IDL type, out of range values will be clamped to the range +of valid values, rather than using the operators that use a modulo operation +(ToInt32, ToUint32, etc.).The [
+Clamp] +extended attribute must take no arguments.The [
+Clamp] extended attribute +must not appear on a read only attribute, or an attribute, operation argument or dictionary member +that is not of an integer type. It also must not +be used in conjunction with the [EnforceRange] +extended attribute.See the rules for converting ECMAScript values to the various IDL integer +types in §4.2 ECMAScript type mapping for the specific requirements that the use of +[
+Clamp] entails.+ ++In the following IDL fragment, + two operations are declared that + take three
+octetarguments; one uses + the [Clamp] extended attribute on all three arguments, while the other does not:interface GraphicsContext { + void setColor(octet red, octet green, octet blue); + void setColorClamped([Clamp] octet red, [Clamp] octet green, [Clamp] octet blue); +}; +
+In an ECMAScript implementation of the IDL, a call to setColorClamped with
+Number values that are out of range for anoctetare clamped to the range [0, 255].// Get an instance of GraphicsContext. +var context = getGraphicsContext(); + +// Calling the non-[Clamp] version uses ToUint8 to coerce the Numbers to octets. +// This is equivalent to calling setColor(255, 255, 1). +context.setColor(-1, 255, 257); + +// Call setColorClamped with some out of range values. +// This is equivalent to calling setColorClamped(0, 255, 255). +context.setColorClamped(-1, 255, 257);
+4.3.2. [Constructor]
+If the [
+Constructor] extended attribute appears on an interface, it indicates that +the interface object for this interface +will have an [[Construct]] internal method, +allowing objects implementing the interface to be constructed.Multiple [
+Constructor] extended +attributes may appear on a given interface.The [
+Constructor] +extended attribute must either take no arguments or take an argument list. +The bare form,[Constructor], has the same meaning as +using an empty argument list,[Constructor()]. For each +[Constructor] extended attribute +on the interface, there will be a way to construct an object that implements +the interface by passing the specified arguments.The prose definition of a constructor must +either return an IDL value of a type corresponding to the interface +the [
+Constructor] +extended attribute appears on, or throw an exception.The [
+Constructor] and +[NoInterfaceObject] +extended attributes must not be specified on the same interface.The [
+Constructor] extended attribute +must not be used on a callback interface.See §4.6.1.1 Interface object [[Call]] method for details on how a constructor +for an interface is to be implemented.
++ ++The following IDL defines two interfaces. The second has the + [
+Constructor] extended + attribute, while the first does not.interface NodeList { + Node item(unsigned long index); + readonly attribute unsigned long length; +}; + +[Constructor, + Constructor(double radius)] +interface Circle { + attribute double r; + attribute double cx; + attribute double cy; + readonly attribute double circumference; +}; +
+An ECMAScript implementation supporting these interfaces would + have a [[Construct]] property on the
+Circleinterface object which would + return a new object that implements the interface. It would take + either zero or one argument. TheNodeListinterface object would not + have a [[Construct]] property.var x = new Circle(); // The uses the zero-argument constructor to create a + // reference to a platform object that implements the + // Circle interface. + +var y = new Circle(1.25); // This also creates a Circle object, this time using + // the one-argument constructor. + +var z = new NodeList(); // This would throw a TypeError, since no + // [Constructor] is declared.
+4.3.3. [EnforceRange]
+If the [
+EnforceRange] extended attribute appears on an operation argument, +writable regular attribute or dictionary member whose type is one of the integer types, +it indicates that when an ECMAScriptNumber is +converted to the IDL type, out of range values will cause an exception to +be thrown, rather than converted to being a valid value using the operators that use a modulo operation +(ToInt32, ToUint32, etc.). TheNumber will be rounded towards zero before being checked against its range.The [
+EnforceRange] +extended attribute must take no arguments.The [
+EnforceRange] extended attribute +must not appear on a read only attribute, a static attribute, +or an attribute, operation argument or dictionary member +that is not of an integer type. It also must not +be used in conjunction with the [Clamp] +extended attribute.See the rules for converting ECMAScript values to the various IDL integer +types in §4.2 ECMAScript type mapping for the specific requirements that the use of +[
+EnforceRange] entails.+ ++In the following IDL fragment, + two operations are declared that + take three
+octetarguments; one uses + the [EnforceRange] extended attribute on all three arguments, while the other does not:interface GraphicsContext { + void setColor(octet red, octet green, octet blue); + void setColorEnforcedRange([EnforceRange] octet red, [EnforceRange] octet green, [EnforceRange] octet blue); +}; +
+In an ECMAScript implementation of the IDL, a call to setColorEnforcedRange with
+Number values that are out of range for anoctetwill result in an exception being + thrown.// Get an instance of GraphicsContext. +var context = getGraphicsContext(); + +// Calling the non-[EnforceRange] version uses ToUint8 to coerce the Numbers to octets. +// This is equivalent to calling setColor(255, 255, 1). +context.setColor(-1, 255, 257); + +// When setColorEnforcedRange is called, Numbers are rounded towards zero. +// This is equivalent to calling setColor(0, 255, 255). +context.setColorEnforcedRange(-0.9, 255, 255.2); + +// The following will cause a TypeError to be thrown, since even after +// rounding the first and third argument values are out of range. +context.setColorEnforcedRange(-1, 255, 256);
+4.3.4. [Exposed]
+If the [
+Exposed] extended attribute appears on an interface, partial interface, namespace, partial namespace, or +an individual interface member or namespace member, +it indicates that the construct is exposed +on a particular set of global interfaces, rather than the default of +being exposed only on the primary global interface.The [
+Exposed] extended attribute must either take an identifier or take an identifier list. +Each of the identifiers mentioned must be +a global name.Every construct that the [
+Exposed] extended attribute can be specified on has an exposure set, +which is a set of interfaces defining which global environments the construct can be used in. +The exposure set for a given construct is defined as follows:-
+
-
+
If the [
+Exposed] extended attribute is specified on the construct, then the exposure set is the set of all interfaces that have a global name that is listed in the extended attribute’s argument. -
+
If the [
+Exposed] extended attribute does not appear on a construct, then its exposure set is defined +implicitly, depending on the type of construct:-
+
-
+
interface
+- +
namespace
+ - +
-
+
The exposure set of the +interface or namespace only contains the primary global interface.
+ -
+
partial interface
+- +
partial namespace
+ - +
-
+
The exposure set of the partial +interface or namespace is the exposure set of the original interface or namespace definition.
+ -
+
interface member
+ -
+
The exposure set of the interface member +is the exposure set of the interface or +partial interface the member is declared on.
+ -
+
namespace member
+ -
+
The exposure set of the +namespace member is the exposure set of the namespace or partial namespace the member is declared on.
+
-
+
If [
+Exposed] appears on an overloaded operation, +then it must appear identically on all overloads.The [
+Exposed] extended attribute +must not be specified on both an interface +member and a partial interface definition the interface member is declared on. +Similarly, the [Exposed] extended attribute +must not be specified on both a namespace +member and a partial namespace definition the namespace member is declared on.If [
+Exposed] appears an interface member, then +the interface member’s exposure set must be a subset of the exposure set of the interface or partial interface it’s a +member of. Similarly, if [Exposed] appears on a +namespace member, then the namespace member’s exposure set must be a +subset of the exposure set of the +namespace or partial namespace it’s a member of.An interface’s exposure set must be a subset of the exposure set of all +of the interface’s consequential interfaces.
+If an interface X inherits from another interface Y then the exposure set of X must be a subset of the exposure set of Y.
+An interface, namespace, interface member, or namespace member is exposed in a given ECMAScript global environment if the +ECMAScript global object implements an interface that is in the construct’s exposure set, and either:
+-
+
-
+
the relevant settings object for the ECMAScript global object is a secure context; or
+ -
+
the construct is not available only in secure contexts.
+
Note: Since it is not possible for the relevant settings object for an ECMAScript global object to change whether it is a secure context or not over time, an implementation’s +decision to create properties for an interface or interface member +can be made once, at the time the initial objects are created.
+See §4.6 Interfaces, §4.6.5 Constants, §4.6.6 Attributes, §4.6.7 Operations and §4.6.8 Common iterator behavior for the specific requirements that the use of +[
+Exposed] entails.+ ++[
+Exposed] + is intended to be used to control whether interfaces, namespaces, or individual + interface or namespace members are available for use only in workers, only in theWindow, or in both.The following IDL fragment shows how that might be achieved:
+[PrimaryGlobal] +interface Window { + // ... +}; + +// By using the same identifier Worker for both SharedWorkerGlobalScope +// and DedicatedWorkerGlobalScope, both can be addressed in an [Exposed] +// extended attribute at once. +[Global=Worker] +interface SharedWorkerGlobalScope : WorkerGlobalScope { + // ... +}; + +[Global=Worker] +interface DedicatedWorkerGlobalScope : WorkerGlobalScope { + // ... +}; + +// Dimensions is available for use in workers and on the main thread. +[Exposed=(Window,Worker), Constructor(double width, double height)] +interface Dimensions { + readonly attribute double width; + readonly attribute double height; +}; + +// WorkerNavigator is only available in workers. Evaluating WorkerNavigator +// in the global scope of a worker would give you its interface object, while +// doing so on the main thread will give you a ReferenceError. +[Exposed=Worker] +interface WorkerNavigator { + // ... +}; + +// Node is only available on the main thread. Evaluating Node +// in the global scope of a worker would give you a ReferenceError. +interface Node { + // ... +}; + +// MathUtils is available for use in workers and on the main thread. +[Exposed=(Window,Worker)] +namespace MathUtils { + double someComplicatedFunction(double x, double y); +}; + +// WorkerUtils is only available in workers. Evaluating WorkerUtils +// in the global scope of a worker would give you its namespace object, while +// doing so on the main thread will give you a ReferenceError. +[Exposed=Worker] +namespace WorkerUtils { + void setPriority(double x); +}; + +// NodeUtils is only available in the main thread. Evaluating NodeUtils +// in the global scope of a worker would give you a ReferenceError. +namespace NodeUtils { + DOMString getAllText(Node node); +}; +
+4.3.5. [ImplicitThis]
+If the [
+ImplicitThis] extended attribute appears on an interface, +it indicates that when aFunction corresponding +to one of the interface’s operations is invoked with thenull orundefined value as thethis value, that the ECMAScript global +object will be used as thethis value instead. +This is regardless of whether the calling code is in strict mode.The [
+ImplicitThis] +extended attribute must take no arguments.See §4.6.7 Operations for the specific requirements that the use of +[
+ImplicitThis] entails.Note: The [
+ImplicitThis] extended attribute is intended for use on theWindowinterface.+ ++In the following example, the
+Windowinterface is defined + with the [ImplicitThis] extended attribute.[ImplicitThis] +interface Window { + // ... + attribute DOMString name; + void alert(DOMString message); +}; +
+Since the
+Windowobject is used as + the ECMAScript global object, calls to its functions can be made + without an explicit object, even in strict mode:"use strict"; + +window.alert("hello"); // Calling alert with an explicit window object works. +alert("hello"); // This also works, even though we are in strict mode. +alert.call(null, "hello"); // As does passing null explicitly as the this value. + +// This does not apply to getters for attributes on the interface, though. +// The following will throw a TypeError. +Object.getOwnPropertyDescriptor(Window.prototype, "name").get.call(null);
+4.3.6. [Global] and [PrimaryGlobal]
+If the [
+Global] +or [PrimaryGlobal] extended attribute appears on an interface, +it indicates that objects implementing this interface can +be used as the global object in an ECMAScript environment, +and that the structure of the prototype chain and how +properties corresponding to interface members will be reflected on the prototype objects will be different from other +interfaces. Specifically:-
+
-
+
Any named properties will be exposed on an object in the prototype chain – the named properties object – +rather than on the object itself.
+ -
+
Interface members from the interface (or consequential interfaces) +will correspond to properties on the object itself rather than on interface prototype objects.
+
++Placing named properties on an object in the prototype chain + is done so that variable declarations and bareword assignments + will shadow the named property with a property on the global + object itself.
+Placing properties corresponding to interface members on + the object itself will mean that common feature detection + methods like the following will work:
+var indexedDB = window.indexedDB || window.webkitIndexedDB || + window.mozIndexedDB || window.msIndexedDB; + +var requestAnimationFrame = window.requestAnimationFrame || + window.mozRequestAnimationFrame || ...;
+Because of the way variable declarations are handled in + ECMAScript, the code above would result in the
+window.indexedDBandwindow.requestAnimationFrameevaluating + toundefined, as the shadowing variable + property would already have been created before the + assignment is evaluated.If the [
+Global] or +[PrimaryGlobal] extended attributes is used on an interface, then:-
+
-
+
The interface must not define a named property setter.
+ -
+
The interface must not also be declared with the [
+OverrideBuiltins] +extended attribute. -
+
The interface must not inherit from another interface with the +[
+OverrideBuiltins] extended attribute. -
+
Any other interface must not inherit from it.
+
If [
+Global] or [PrimaryGlobal] is specified on +a partial interface definition, then that partial interface definition must +be the part of the interface definition that defines +the named property getter.The [
+Global] and [PrimaryGlobal] extended attribute must not +be used on an interface that can have more +than one object implementing it in the same ECMAScript global environment.Note: This is because the named properties object, +which exposes the named properties, is in the prototype chain, and it would not make +sense for more than one object’s named properties to be exposed on an object that +all of those objects inherit from.
+If an interface is declared with the [
+Global] or +[PrimaryGlobal] extended attribute, then +there must not be more than one interface member across +the interface and its consequential interfaces with the same identifier. +There also must not be more than +one stringifier, +more than one serializer, +or more than one iterable declaration, maplike declaration or setlike declaration across those interfaces.Note: This is because all of the members of the interface and its consequential +interfaces get flattened down on to the object that implements the interface.
+The [
+Global] and +[PrimaryGlobal] extended attributes +can also be used to give a name to one or more global interfaces, +which can then be referenced by the [Exposed] +extended attribute.The [
+Global] and +[PrimaryGlobal] +extended attributes must either take no arguments or take an identifier list.If the [
+Global] or +[PrimaryGlobal] extended attribute is declared with an identifier list argument, then those identifiers are the interface’s global names; otherwise, the interface has +a single global name, which is the interface’s identifier.Note: The identifier argument list exists so that more than one global interface can +be addressed with a single name in an [
+Exposed] extended attribute.The [
+Global] and +[PrimaryGlobal] extended attributes must not be declared on the same +interface. The [PrimaryGlobal] +extended attribute must be declared on +at most one interface. The interface [PrimaryGlobal] +is declared on, if any, is known as the primary global interface.See §4.6.4 Named properties object, §4.8.3 Platform object [[GetOwnProperty]] method and §4.8.7 Platform object [[DefineOwnProperty]] method for the specific requirements that the use of +[
+Global] and [PrimaryGlobal] +entails for named properties, +and §4.6.5 Constants, §4.6.6 Attributes and §4.6.7 Operations for the requirements relating to the location of properties +corresponding to interface members.+ ++The [
+PrimaryGlobal] extended attribute is intended + to be used by theWindowinterface. + ([Global] is intended to be used by worker global interfaces.) + TheWindowinterface exposes frames as properties on theWindowobject. Since theWindowobject also serves as the + ECMAScript global object, variable declarations or assignments to the named properties + will result in them being replaced by the new value. Variable declarations for + attributes will not create a property that replaces the existing one.[PrimaryGlobal] +interface Window { + getter any (DOMString name); + attribute DOMString name; + // ... +}; +
+The following HTML document illustrates how the named properties on the
+Windowobject can be shadowed, and how + the property for an attribute will not be replaced when declaring + a variable of the same name:<!DOCTYPE html> +<title>Variable declarations and assignments on Window</title> +<iframe name=abc></iframe> +<!-- Shadowing named properties --> +<script> + window.abc; // Evaluates to the iframe’s Window object. + abc = 1; // Shadows the named property. + window.abc; // Evaluates to 1. +</script> + +<!-- Preserving properties for IDL attributes --> +<script> + Window.prototype.def = 2; // Places a property on the prototype. + window.hasOwnProperty("length"); // Evaluates to true. + length; // Evaluates to 1. + def; // Evaluates to 2. +</script> +<script> + var length; // Variable declaration leaves existing property. + length; // Evaluates to 1. + var def; // Variable declaration creates shadowing property. + def; // Evaluates to undefined. +</script>
+4.3.7. [LegacyArrayClass]
+If the [
+LegacyArrayClass] extended attribute appears on an interface that is not defined to inherit from another, it indicates that the internal [[Prototype]] +property of its interface prototype object will be theArray prototype object rather than +theObject prototype object. This allowsArray methods to be used more easily +with objects implementing the interface.The [
+LegacyArrayClass] extended attribute +must take no arguments. +It must not be used on an interface that +has any inherited interfaces.Note: Interfaces using [
+LegacyArrayClass] will +need to define a “length” attribute of typeunsigned longthat exposes the length +of the array-like object, in order for the inheritedArray methods to operate correctly. Such interfaces would typically also support indexed properties, +which would provide access to the array elements.See §4.6.3 Interface prototype object for the +specific requirements that the use of [
+LegacyArrayClass] +entails.+ ++The following IDL fragment defines two interfaces that use [
+LegacyArrayClass].[LegacyArrayClass] +interface ItemList { + attribute unsigned long length; + getter object getItem(unsigned long index); + setter object setItem(unsigned long index, object item); +}; + +[LegacyArrayClass] +interface ImmutableItemList { + readonly attribute unsigned long length; + getter object getItem(unsigned long index); +}; +
+In an ECMAScript implementation of the above two interfaces, + with appropriate definitions for getItem, setItem and removeItem,
+Array methods to inspect and + modify the array-like object can be used.var list = getItemList(); // Obtain an instance of ItemList. + +list.concat(); // Clone the ItemList into an Array. +list.pop(); // Remove an item from the ItemList. +list.unshift({ }); // Insert an item at index 0.
+
+ImmutableItemListhas a read only + length attribute and no indexed property setter. The + mutatingArray methods will generally not + succeed on objects implementingImmutableItemList. + The exact behavior depends on the definition of the Array methods themselves.4.3.8. [LegacyUnenumerableNamedProperties]
+If the [
+LegacyUnenumerableNamedProperties] extended attribute appears on a interface that supports named properties, +it indicates that all the interface’s named properties are unenumerable.The [
+LegacyUnenumerableNamedProperties] +extended attribute must take no arguments and must not appear on an interface +that does not define a named property getter.If the [
+LegacyUnenumerableNamedProperties] +extended attribute is specified on an interface, then it applies to all its derived interfaces and +must not be specified on any of them.See §4.8.10 Property enumeration for the specific requirements that the use of +[
+LegacyUnenumerableNamedProperties] +entails.4.3.9. [LenientSetter]
+If the [
+LenientSetter] extended attribute appears on a read only regular attribute, +it indicates that a no-op setter will be generated for the attribute’s +accessor property. This results in erroneous assignments to the property +in strict mode to be ignored rather than causing an exception to be thrown.++Specifications should not use [
+LenientSetter] + unless required for compatibility reasons. Pages have been observed + where authors have attempted to polyfill an IDL attribute by assigning + to the property, but have accidentally done so even if the property + exists. In strict mode, this would cause an exception to be thrown, + potentially breaking page. Without [LenientSetter], + this could prevent a browser from shipping the feature.Specification authors who + wish to use this feature are strongly advised to discuss this on the public-script-coord@w3.org mailing list before proceeding.
+The [
+LenientThis] extended attribute +must take no arguments. +It must not be used on anything other than +a read only regular attribute.An attribute with the [
+LenientSetter] +extended attribute must not also be declared +with the [PutForwards] +or [Replaceable] extended attributes.See the Attributes section for how +[
+LenientSetter] +is to be implemented.+ ++The following IDL fragment defines an interface that uses the + [
+LenientSetter] extended + attribute.interface Example { + [LenientSetter] readonly attribute DOMString x; + readonly attribute DOMString y; +}; +
+An ECMAScript implementation that supports this interface will + have a setter on the accessor property that correspond to x, + which allows any assignment to be ignored in strict mode.
+"use strict"; + +var example = getExample(); // Get an instance of Example. + +// Fine; while we are in strict mode, there is a setter that is a no-op. +example.x = 1; + +// Throws a TypeError, since we are in strict mode and there is no setter. +example.y = 1;
+4.3.10. [LenientThis]
+If the [
+LenientThis] extended attribute appears on a regular attribute, +it indicates that invocations of the attribute’s getter or setter +with athis value that is not an +object that implements the interface on which the attribute appears will be ignored.The [
+LenientThis] extended attribute +must take no arguments. +It must not be used on a static attribute.Specifications should not use [
+LenientThis] + unless required for compatibility reasons. Specification authors who + wish to use this feature are strongly advised to discuss this on the public-script-coord@w3.org mailing list before proceeding.See the Attributes section for how +[
+LenientThis] +is to be implemented.+ ++The following IDL fragment defines an interface that uses the + [
+LenientThis] extended + attribute.interface Example { + [LenientThis] attribute DOMString x; + attribute DOMString y; +}; +
+An ECMAScript implementation that supports this interface will + allow the getter and setter of the accessor property that corresponds + to x to be invoked with something other than an
+Exampleobject.var example = getExample(); // Get an instance of Example. +var obj = { }; + +// Fine. +example.x; + +// Ignored, since the this value is not an Example object and [LenientThis] is used. +Object.getOwnPropertyDescriptor(Example.prototype, "x").get.call(obj); + +// Also ignored, since Example.prototype is not an Example object and [LenientThis] is used. +Example.prototype.x; + +// Throws a TypeError, since Example.prototype is not an Example object. +Example.prototype.y;
+4.3.11. [NamedConstructor]
+If the [
+NamedConstructor] extended attribute appears on an interface, +it indicates that the ECMAScript global object will have a property with the +specified name whose value is a constructor function that can +create objects that implement the interface. +Multiple [NamedConstructor] extended +attributes may appear on a given interface.The [
+NamedConstructor] +extended attribute must either take an identifier or take a named argument list. +The first form,[NamedConstructor=, has the same meaning as +using an empty argument list,identifier ][NamedConstructor=. For each +[identifier ()]NamedConstructor] extended attribute +on the interface, there will be a way to construct an object that implements +the interface by passing the specified arguments to the constructor function +that is the value of the aforementioned property.The identifier used for the named constructor must not +be the same as that used by an [
+NamedConstructor] +extended attribute on another interface, must not +be the same as an identifier of an interface +that has an interface object, +and must not be one of the reserved identifiers.The [
+NamedConstructor] extended attribute +must not be used on a callback interface.See §4.6.2 Named constructors for details on how named constructors +are to be implemented.
++ ++The following IDL defines an interface that uses the + [
+NamedConstructor] extended + attribute.[NamedConstructor=Audio, + NamedConstructor=Audio(DOMString src)] +interface HTMLAudioElement : HTMLMediaElement { + // ... +}; +
+An ECMAScript implementation that supports this interface will + allow the construction of
+HTMLAudioElementobjects using theAudioconstructor.typeof Audio; // Evaluates to 'function'. + +var a1 = new Audio(); // Creates a new object that implements + // HTMLAudioElement, using the zero-argument + // constructor. + +var a2 = new Audio('a.flac'); // Creates an HTMLAudioElement using the + // one-argument constructor.
+4.3.12. [NewObject]
+If the [
+NewObject] extended attribute appears on a regular or static operation, +then it indicates that when calling the operation, +a reference to a newly created object +must always be returned.The [
+NewObject] +extended attribute must take no arguments.The [
+NewObject] +extended attribute must not +be used on anything other than a regular or static operation whose return type is an interface type or +a promise type.+ ++As an example, this extended attribute is suitable for use on + the createElement operation on the
+Documentinterface ([DOM], section 6.5), + since a new object should always be returned when + it is called.interface Document : Node { + [NewObject] Element createElement(DOMString localName); + // ... +}; +
+4.3.13. [NoInterfaceObject]
+If the [
+NoInterfaceObject] extended attribute appears on an interface, +it indicates that an interface object will not exist for the interface in the ECMAScript binding.The [
+NoInterfaceObject] extended attribute + should not be used on interfaces that are not + solely used as supplemental interfaces, + unless there are clear Web compatibility reasons for doing so. Specification authors who + wish to use this feature are strongly advised to discuss this on the public-script-coord@w3.org mailing list before proceeding.The [
+NoInterfaceObject] extended attribute +must take no arguments.If the [
+NoInterfaceObject] extended attribute +is specified on an interface, then the [Constructor] +extended attribute must not also be specified on that interface. +A [NamedConstructor] extended attribute is fine, +however.The [
+NoInterfaceObject] extended attribute +must not be specified on an interface that has any static operations defined on it.The [
+NoInterfaceObject] extended attribute +must not be specified on a callback interface unless it has a constant declared on it. +This is because callback interfaces without constants never have interface objects.An interface that does not have the [
+NoInterfaceObject] extended +attribute specified must not inherit +from an interface that has the [NoInterfaceObject] extended +attribute specified.See §4.6 Interfaces for the specific requirements that the use of +[
+NoInterfaceObject] entails.+ ++The following IDL fragment defines two interfaces, one whose interface object + is exposed on the ECMAScript global object, and one whose isn’t:
+interface Storage { + void addEntry(unsigned long key, any value); +}; + +[NoInterfaceObject] +interface Query { + any lookupEntry(unsigned long key); +}; +
+An ECMAScript implementation of the above IDL would allow + manipulation of
+Storage’s + prototype, but notQuery’s.typeof Storage; // evaluates to "object" + +// Add some tracing alert() call to Storage.addEntry. +var fn = Storage.prototype.addEntry; +Storage.prototype.addEntry = function(key, value) { + alert('Calling addEntry()'); + return fn.call(this, key, value); +}; + +typeof Query; // evaluates to "undefined" +var fn = Query.prototype.lookupEntry; // exception, Query isn’t defined
+4.3.14. [OverrideBuiltins]
+If the [
+OverrideBuiltins] extended attribute appears on an interface, +it indicates that for a platform object implementing the interface, +properties corresponding to all of +the object’s supported property names will appear to be on the object, +regardless of what other properties exist on the object or its +prototype chain. This means that named properties will always shadow +any properties that would otherwise appear on the object. +This is in contrast to the usual behavior, which is for named properties +to be exposed only if there is no property with the +same name on the object itself or somewhere on its prototype chain.The [
+OverrideBuiltins] +extended attribute must take no arguments and must not appear on an interface +that does not define a named property getter or that also is declared with the [Global] +or [PrimaryGlobal] +extended attribute. If the extended attribute is specified on +a partial interface definition, then that partial interface definition must +be the part of the interface definition that defines +the named property getter.See §4.8.1 Indexed and named properties and §4.8.7 Platform object [[DefineOwnProperty]] method for the specific requirements that the use of +[
+OverrideBuiltins] entails.+ ++The following IDL fragment defines two interfaces, + one that has a named property getter and one that does not.
+interface StringMap { + readonly attribute unsigned long length; + getter DOMString lookup(DOMString key); +}; + +[OverrideBuiltins] +interface StringMap2 { + readonly attribute unsigned long length; + getter DOMString lookup(DOMString key); +}; +
+In an ECMAScript implementation of these two interfaces, + getting certain properties on objects implementing + the interfaces will result in different values:
+// Obtain an instance of StringMap. Assume that it has "abc", "length" and +// "toString" as supported property names. +var map1 = getStringMap(); + +// This invokes the named property getter. +map1.abc; + +// This fetches the "length" property on the object that corresponds to the +// length attribute. +map1.length; + +// This fetches the "toString" property from the object’s prototype chain. +map1.toString; + +// Obtain an instance of StringMap2. Assume that it also has "abc", "length" +// and "toString" as supported property names. +var map2 = getStringMap2(); + +// This invokes the named property getter. +map2.abc; + +// This also invokes the named property getter, despite the fact that the "length" +// property on the object corresponds to the length attribute. +map2.length; + +// This too invokes the named property getter, despite the fact that "toString" is +// a property in map2’s prototype chain. +map2.toString;
+4.3.15. [PutForwards]
+If the [
+PutForwards] extended attribute appears on a read only regular attribute declaration whose type is +an interface type, +it indicates that assigning to the attribute will have specific behavior. +Namely, the assignment is “forwarded” to the attribute (specified by +the extended attribute argument) on the object that is currently +referenced by the attribute being assigned to.The [
+PutForwards] extended +attribute must take an identifier. +Assuming that:-
+
-
+
A is the attribute on which the [
+PutForwards] +extended attribute appears, -
+
I is the interface on which A is declared,
+ -
+
J is the interface type that A is declared to be of, and
+ -
+
N is the identifier argument of the extended attribute,
+
then there must be another attribute B declared on J whose identifier is N. Assignment of a value to the attribute A on an object implementing I will result in that value +being assigned to attribute B of the object that A references, instead.
+Note that [
+PutForwards]-annotated attributes can be +chained. That is, an attribute with the [PutForwards] extended attribute can refer to an attribute that itself has that extended attribute. +There must not exist a cycle in a +chain of forwarded assignments. A cycle exists if, when following +the chain of forwarded assignments, a particular attribute on +an interface is +encountered more than once.An attribute with the [
+PutForwards] +extended attribute must not also be declared +with the [LenientSetter] or +[Replaceable] extended attributes.The [
+PutForwards] +extended attribute must not be used +on an attribute that +is not read only.The [
+PutForwards] extended attribute +must not be used on a static attribute.The [
+PutForwards] extended attribute +must not be used on an attribute declared on +a callback interface.See the Attributes section for how +[
+PutForwards] +is to be implemented.+ ++The following IDL fragment defines interfaces for names and people. + The [
+PutForwards] extended + attribute is used on thenameattribute + of thePersoninterface to indicate + that assignments to that attribute result in assignments to thefullattribute of thePersonobject:interface Name { + attribute DOMString full; + attribute DOMString family; + attribute DOMString given; +}; + +interface Person { + [PutForwards=full] readonly attribute Name name; + attribute unsigned short age; +}; +
+In the ECMAScript binding, this would allow assignments to the + “name” property:
+var p = getPerson(); // Obtain an instance of Person. + +p.name = 'John Citizen'; // This statement... +p.name.full = 'John Citizen'; // ...has the same behavior as this one.
+4.3.16. [Replaceable]
+If the [
+Replaceable] extended attribute appears on a read only regular attribute, +it indicates that setting the corresponding property on the platform object will result in +an own property with the same name being created on the object +which has the value being assigned. This property will shadow +the accessor property corresponding to the attribute, which +exists on the interface prototype object.The [
+Replaceable] +extended attribute must take no arguments.An attribute with the [
+Replaceable] +extended attribute must not also be declared +with the [LenientSetter] or +[PutForwards] extended attributes.The [
+Replaceable] +extended attribute must not be used +on an attribute that +is not read only.The [
+Replaceable] extended attribute +must not be used on a static attribute.The [
+Replaceable] extended attribute +must not be used on an attribute declared on +a callback interface.See §4.6.6 Attributes for the specific requirements that the use of +[
+Replaceable] entails.+ ++The following IDL fragment defines an interface with an operation that increments a counter, and an attribute that exposes the counter’s value, which is initially 0:
+interface Counter { + [Replaceable] readonly attribute unsigned long value; + void increment(); +}; +
+Assigning to the “value” property + on a platform object implementing
+Counterwill shadow the property that corresponds to the attribute:var counter = getCounter(); // Obtain an instance of Counter. +counter.value; // Evaluates to 0. + +counter.hasOwnProperty("value"); // Evaluates to false. +Object.getPrototypeOf(counter).hasOwnProperty("value"); // Evaluates to true. + +counter.increment(); +counter.increment(); +counter.value; // Evaluates to 2. + +counter.value = 'a'; // Shadows the property with one that is unrelated + // to Counter::value. + +counter.hasOwnProperty("value"); // Evaluates to true. + +counter.increment(); +counter.value; // Evaluates to 'a'. + +delete counter.value; // Reveals the original property. +counter.value; // Evaluates to 3.
+4.3.17. [SameObject]
+If the [
+SameObject] extended attribute appears on a read only attribute, then it +indicates that when getting the value of the attribute on a given +object, the same value must always +be returned.The [
+SameObject] +extended attribute must take no arguments.The [
+SameObject] +extended attribute must not +be used on anything other than a read only attribute whose type is an interface type orobject.+ ++As an example, this extended attribute is suitable for use on + the implementation attribute on the
+Documentinterface ([DOM], section 6.5), + since the same object is always returned for a givenDocumentobject.interface Document : Node { + [SameObject] readonly attribute DOMImplementation implementation; + // ... +}; +
+4.3.18. [SecureContext]
+If the [
+SecureContext] extended attribute appears on an interface, partial interface, namespace, partial namespace, interface member, or namespace member, +it indicates that the construct is exposed +only within a secure context.The [
+SecureContext] +extended attribute must take no arguments.The [
+SecureContext] +extended attribute must not +be used on anything other than an interface, partial interface, namespace, partial namespace, interface member, or namespace member.Whether a construct that the [
+SecureContext] extended attribute can be specified on is available only in secure contexts is defined as follows:-
+
-
+
If the [
+SecureContext] extended attribute is specified on the construct, then it is available only in secure contexts. -
+
Otherwise, if the [
+SecureContext] extended attribute does not appear on a construct, then whether it is available only in secure contexts depends on the type of construct:-
+
-
+
interface
+- +
namespace
+ - +
-
+
The interface or namespace is not available only in secure contexts.
+ -
+
partial interface
+- +
partial namespace
+ - +
-
+
The partial interface or partial namespace is available only in secure contexts if and only if the original interface or namespace definition +is.
+ -
+
interface member
+ -
+
The interface member is available only in secure contexts if and only if the interface or partial interface the member is declared on is.
+ -
+
namespace member
+ -
+
The namespace member is available only in secure contexts if and only if the namspace or partial namespace the member is declared on is.
+
-
+
Note: Whether a construct is available only in secure contexts influences whether it is exposed in a given +ECMAScript global environment.
+If [
+SecureContext] appears on an overloaded operation, +then it must appear on all overloads.The [
+SecureContext] extended attribute +must not be specified on both an interface member and the +interface or partial interface definition the interface member is declared on, or +on both a namespace member and the namespace or partial namespace definition the +namespace member is declared on.An interface without the [
+SecureContext] extended attribute +must not inherit from another interface +that does specify [SecureContext].+ ++The following IDL fragment defines an interface + with one operation that is executable from all + contexts, and two which are executable only from secure contexts.
+interface PowerfulFeature { + // This call will succeed in all contexts. + Promise <Result> calculateNotSoSecretResult(); + + // This operation will not be exposed to a non-secure context. In such a context, + // there will be no "calculateSecretResult" property on PowerfulFeature.prototype. + [SecureContext] Promise<Result> calculateSecretResult(); + + // The same applies here: the attribute will not be exposed to a non-secure context, + // and in a non-secure context there will be no "secretBoolean" property on + // PowerfulFeature.prototype. + [SecureContext] readonly attribute boolean secretBoolean; +}; +
+4.3.19. [TreatNonObjectAsNull]
+If the [
+TreatNonObjectAsNull] extended attribute appears on a callback function, +then it indicates that any value assigned to an attribute whose type is a nullable callback function that is not an object will be converted to +thenull value.Specifications should not use [
+TreatNonObjectAsNull] + unless required to specify the behavior of legacy APIs or for consistency with these + APIs. Specification authors who + wish to use this feature are strongly advised to discuss this on the public-script-coord@w3.org mailing list before proceeding. At the time of writing, the only known + valid use of [TreatNonObjectAsNull] + is for the callback functions used as the type + of event handler IDL attributes such asonclickandonerror.See §4.2.24 Nullable types — T? for the specific requirements that the use of +[
+TreatNonObjectAsNull] entails.+ ++The following IDL fragment defines an interface that has one + attribute whose type is a [
+TreatNonObjectAsNull]-annotated callback function and another whose type is a callback function without the extended attribute:callback OccurrenceHandler = void (DOMString details); + +[TreatNonObjectAsNull] +callback ErrorHandler = void (DOMString details); + +interface Manager { + attribute OccurrenceHandler? handler1; + attribute ErrorHandler? handler2; +}; +
+In an ECMAScript implementation, assigning a value that is not + an object (such as a
+Number value) + to handler1 will have different behavior from that when assigning + to handler2:var manager = getManager(); // Get an instance of Manager. + +manager.handler1 = function() { }; +manager.handler1; // Evaluates to the function. + +try { + manager.handler1 = 123; // Throws a TypeError. +} catch (e) { +} + +manager.handler2 = function() { }; +manager.handler2; // Evaluates to the function. + +manager.handler2 = 123; +manager.handler2; // Evaluates to null.
+4.3.20. [TreatNullAs]
+If the [
+TreatNullAs] extended attribute appears on an attribute or operation argument whose type isDOMString, +it indicates that anull value +assigned to the attribute or passed as the operation argument will be +handled differently from its default handling. Instead of being stringified +to “null”, which is the default, +it will be converted to the empty string “”.If [
+TreatNullAs] is specified on +an operation itself, and that operation is on a callback interface, +then it indicates that a user object implementing the interface will have the return +value of the function that implements the operation handled in the same way as for operation arguments +and attributes, as above.The [
+TreatNullAs] +extended attribute must take the identifierEmptyString.The [
+TreatNullAs] extended attribute +must not be specified on an operation argument, +attribute or operation return value whose type is notDOMString.Note: This means that even an attribute of type
+DOMString?must not +use [TreatNullAs], sincenull is a valid value of that type.The [
+TreatNullAs] extended attribute +also must not be specified on an operation on +a non-callback interface.See §4.2.16 DOMString for the specific requirements that the use of +[
+TreatNullAs] entails.+ ++The following IDL fragment defines an interface that has one + attribute with the [
+TreatNullAs] + extended attribute, and one operation with an argument that has + the extended attribute:interface Dog { + attribute DOMString name; + [TreatNullAs=EmptyString] attribute DOMString owner; + + boolean isMemberOfBreed([TreatNullAs=EmptyString] DOMString breedName); +}; +
+An ECMAScript implementation implementing the
+Doginterface would convert anull value + assigned to the “owner” property or passed as the + argument to theisMemberOfBreedfunction + to the empty string rather than"null":var d = getDog(); // Assume d is a platform object implementing the Dog + // interface. + +d.name = null; // This assigns the string "null" to the .name + // property. + +d.owner = null; // This assigns the string "" to the .owner property. + +d.isMemberOfBreed(null); // This passes the string "" to the isMemberOfBreed + // function.
+4.3.21. [Unforgeable]
+If the [
+Unforgeable] extended attribute appears on a non-static attribute or non-static operations, it indicates +that the attribute or operation will be reflected as an ECMAScript property in +a way that means its behavior cannot be modified and that performing +a property lookup on the object will always result in the attribute’s +property value being returned. In particular, the property will be +non-configurable and will exist as an own property on the object +itself rather than on its prototype.If the [
+Unforgeable] extended attribute appears on an interface, +it indicates that all of the non-static attributes and non-static operations declared on +that interface and its consequential interfaces will be similarly reflected as own ECMAScript properties on objects +that implement the interface, rather than on the prototype.An attribute or operation is said to be unforgeable on a given interface A if any of the following are true:
+-
+
-
+
The attribute or operation is declared on A or one +of A’s consequential interfaces, +and is annotated with the [
+Unforgeable] extended attribute. -
+
The attribute or operation is declared on A or one +of A’s consequential interfaces, +and that interface is annotated with the [
+Unforgeable] extended attribute. -
+
There exists an interface B, which is either A or one of A’s consequential interfaces, B is annotated with the [
+Unforgeable] extended attribute, +and the attribute or operation is declared on one of B’s consequential interfaces.
The [
+Unforgeable] +extended attribute must take no arguments.The [
+Unforgeable] +extended attribute must not appear on +anything other than an attribute, +non-static operation or an interface. If it does +appear on an operation, then +it must appear on all operations with +the same identifier on that interface.If an attribute or operation X is unforgeable on an interface A, and A is one of the inherited interfaces of another interface B, then B and all of its consequential interfaces must not have a non-static attribute or regular operation with the same identifier as X.
+++For example, the following is disallowed:
+interface A1 { + [Unforgeable] readonly attribute DOMString x; +}; +interface B1 : A1 { + void x(); // Invalid; would be shadowed by A1’s x. +}; + +interface B2 : A1 { }; +B2 implements Mixin; +interface Mixin { + void x(); // Invalid; B2’s copy of x would be shadowed by A1’s x. +}; + +[Unforgeable] +interface A2 { + readonly attribute DOMString x; +}; +interface B3 : A2 { + void x(); // Invalid; would be shadowed by A2’s x. +}; + +interface B4 : A2 { }; +B4 implements Mixin; +interface Mixin { + void x(); // Invalid; B4’s copy of x would be shadowed by A2’s x. +}; + +interface A3 { }; +A3 implements A2; +interface B5 : A3 { + void x(); // Invalid; would be shadowed by A3’s mixed-in copy of A2’s x. +}; +
+See §4.6.6 Attributes, §4.6.7 Operations, §4.8 Platform objects implementing interfaces, §4.8.1 Indexed and named properties and §4.8.7 Platform object [[DefineOwnProperty]] method for the specific requirements that the use of +[
+Unforgeable] entails.+ ++The following IDL fragment defines + an interface that has two attributes, + one of which is designated as [
+Unforgeable]:interface System { + [Unforgeable] readonly attribute DOMString username; + readonly attribute long long loginTime; +}; +
+In an ECMAScript implementation of the interface, the username attribute will be exposed as a non-configurable property on the + object itself:
+var system = getSystem(); // Get an instance of System. + +system.hasOwnProperty("username"); // Evaluates to true. +system.hasOwnProperty("loginTime"); // Evaluates to false. +System.prototype.hasOwnProperty("username"); // Evaluates to false. +System.prototype.hasOwnProperty("loginTime"); // Evaluates to true. + +try { + // This call would fail, since the property is non-configurable. + Object.defineProperty(system, "username", { value: "administrator" }); +} catch (e) { } + +// This defineProperty call would succeed, because System.prototype.loginTime +// is configurable. +var forgedLoginTime = 5; +Object.defineProperty(System.prototype, "loginTime", { value: forgedLoginTime }); + +system.loginTime; // So this now evaluates to forgedLoginTime.
+4.3.22. [Unscopable]
+If the [
+Unscopable] extended attribute appears on a regular attribute or regular operation, it +indicates that an object that implements an interface with the given +interface member will not include its property name in any object +environment record with it as its base object. The result of this is +that bare identifiers matching the property name will not resolve to +the property in awithstatement. This is achieved by +including the property name on the interface prototype object’s @@unscopables property’s value.The [
+Unscopable] +extended attribute must take no arguments.The [
+Unscopable] +extended attribute must not appear on +anything other than a regular attribute or regular operation.See §4.6.3 Interface prototype object for the specific requirements that the use of +[
+Unscopable] entails.++For example, with the following IDL:
+interface Thing { + void f(); + [Unscopable] g(); +}; +
+the “f” property an be referenced with a bare identifier + in a
+withstatement but the “g” property cannot:var thing = getThing(); // An instance of Thing +with (thing) { + f; // Evaluates to a Function object. + g; // Throws a ReferenceError. +}
+4.4. Security
+Certain algorithms in the sections below are defined to perform a security check on a given +object. This check is used to determine whether a given operation invocation or attribute access should be +allowed. The security check takes the following four inputs:
+-
+
-
+
the platform object on +which the operation invocation or attribute access is being done,
+ -
+
the ECMAScript global environment associated with the
+Function object that implements the +operation or attribute, -
+
the identifier of the operation or attribute, and
+ -
+
the type of the
+Function object – +“method” (when it corresponds to an IDL operation), or +“getter” or “setter” (when it corresponds to the +getter or setter function of an IDL attribute).
Note: The expectation is that the HTML specification defines how a +security check is performed, and that it will either throw an +appropriate exception or return normally. [HTML]
+4.5. Overload resolution algorithm
+In order to define how overloaded function invocations are resolved, the overload resolution algorithm is defined. Its input is an effective overload set, S, and a list of ECMAScript values, arg0..n−1. +Its output is a pair consisting of the operation or extended attribute of one of S’s entries +and a list of IDL values or the special value “missing”. The algorithm behaves as follows:
+-
+
-
+
Let maxarg be the length of the longest type list of the entries in S.
+ -
+
Initialize argcount to be min(maxarg, n).
+ -
+
Remove from S all entries whose type list is not of length argcount.
+ -
+
If S is empty, then throw a
+TypeError . -
+
Initialize d to −1.
+ -
+
Initialize method to
+undefined . -
+
If there is more than one entry in S, then set d to be the distinguishing argument index for the entries of S.
+ -
+
Initialize values to be an empty list, where each entry will be either an IDL value or the special value “missing”.
+ -
+
Initialize i to 0.
+ -
+
While i < d:
+-
+
-
+
Let V be argi.
+ -
+
Let type be the type at index i in the type list of any entry in S.
+Note: All entries in S at this point have the same type and optionality value at index i.
+ -
+
Let optionality be the value at index i in the list of optionality values of any entry in S.
+ -
+
If optionality is “optional” and V is
+undefined , then:-
+
-
+
If the argument at index i is declared with a default value, +then append to values that default value.
+ -
+
Otherwise, append to values the special value “missing”.
+
-
+
-
+
Otherwise, append to values the result of converting V to IDL type type.
+ -
+
Set i to i + 1.
+
-
+
-
+
If i = d, then:
+-
+
-
+
Let V be argi.
+Note: This is the argument that will be used to resolve which overload is selected.
+ -
+
If V is
+undefined , and there is an entry in S whose list of optionality values has “optional” at index i, +then remove from S all other entries. -
+
Otherwise: if V is
+null orundefined , +and there is an entry in S that has one of the following types at position i of its type list,-
+
- + +
- + +
-
+
a union type that includes a nullable type or that +has a dictionary type in its flattened members
+
then remove from S all other entries.
+ -
+
Otherwise: if V is a platform object, and +there is an entry in S that has one of the following types at position i of its type list,
+-
+
-
+
an interface type that V implements
+ - + +
-
+
a nullable version of any of the above types
+ -
+
a union type or a nullable union type +that has one of the above types in its flattened member types
+
then remove from S all other entries.
+ -
+
-
+
Otherwise: if V is a
+RegExp object and +there is an entry in S that has one of the following types at position i of its type list,-
+
- + +
- + +
-
+
a nullable version of either of the above types
+ -
+
a union type or nullable union type +that has one of the above types in its flattened member types
+
then remove from S all other entries.
+ -
+
Otherwise: if V is a
+DOMExceptionplatform object and +there is an entry in S that has one of the following types at position i of its type list,-
+
- + +
- + +
- + +
-
+
a nullable version of either of the above types
+ -
+
a union type or nullable union type +that has one of the above types in its flattened member types
+
then remove from S all other entries.
+ -
+
Otherwise: if V is an
+Error object (that is, it has an [[ErrorData]] internal slot) and +there is an entry in S that has one of the following types at position i of its type list,-
+
- + +
- + +
-
+
a nullable version of either of the above types
+ -
+
a union type or nullable union type +that has one of the above types in its flattened member types
+
then remove from S all other entries.
+ -
+
Otherwise: if V is an object with an [[ArrayBufferData]] internal slot and +there is an entry in S that has one of the following types at position i of its type list,
+-
+
- + +
- + +
-
+
a nullable version of either of the above types
+ -
+
a union type or nullable union type +that has one of the above types in its flattened member types
+
then remove from S all other entries.
+ -
+
Otherwise: if V is an object with a [[DataView]] internal slot and +there is an entry in S that has one of the following types at position i of its type list,
+-
+
- + +
- + +
-
+
a nullable version of either of the above types
+ -
+
a union type or nullable union type +that has one of the above types in its flattened member types
+
then remove from S all other entries.
+ -
+
Otherwise: if V is an object with a [[TypedArrayName]] internal slot and +there is an entry in S that has one of the following types at position i of its type list,
+-
+
-
+
a typed array type whose name +is equal to the value of V’s [[TypedArrayName]] internal slot
+ - + +
-
+
a nullable version of either of the above types
+ -
+
a union type or nullable union type +that has one of the above types in its flattened member types
+
then remove from S all other entries.
+ -
+
-
+
Otherwise: if IsCallable(V) is true, +and there is an entry in S that has one of the following types at position i of its type list,
+-
+
-
+
a callback function type
+ - + +
-
+
a nullable version of any of the above types
+ -
+
a union type or nullable union type +that has one of the above types in its flattened member types
+
then remove from S all other entries.
+ -
+
-
+
Otherwise: if V is any kind of object except for +a native
+RegExp object, and +there is an entry in S that has one of the +following types at position i of its type list,-
+
- + +
- + +
-
+
a nullable version of any of the above types
+ -
+
a union type or nullable union type +that has one of the above types in its flattened member types
+
and after performing the following steps,
+-
+
-
+
Let method be the result of GetMethod(V, @@iterator).
+ -
+
ReturnIfAbrupt(method).
+
method is not
+undefined , then remove from S all +other entries. -
+
Otherwise: if V is any kind of object except for +a native
+RegExp object, and +there is an entry in S that has one of the following types at position i of its type list,-
+
-
+
a callback interface type
+ - + +
- + +
-
+
a nullable version of any of the above types
+ -
+
a union type or nullable union type +that has one of the above types in its flattened member types
+
then remove from S all other entries.
+ -
+
-
+
Otherwise: if V is a
+Boolean value, +and there is an entry in S that has one of the following types at position i of its type list,-
+
- + +
- + +
-
+
a union type or nullable union type +that has one of the above types in its flattened member types
+
then remove from S all other entries.
+ -
+
Otherwise: if V is a
+Number value, +and there is an entry in S that has one of the following types at position i of its type list,-
+
- + +
- + +
-
+
a union type or nullable union type +that has one of the above types in its flattened member types
+
then remove from S all other entries.
+ -
+
Otherwise: if there is an entry in S that has one of the following types at position i of its type list,
+-
+
- + +
-
+
a nullable version of any of the above types
+ -
+
a union type or nullable union type +that has one of the above types in its flattened member types
+
then remove from S all other entries.
+ -
+
Otherwise: if there is an entry in S that has one of the following types at position i of its type list,
+-
+
- + +
- + +
-
+
a union type or nullable union type +that has one of the above types in its flattened member types
+
then remove from S all other entries.
+ -
+
Otherwise: if there is an entry in S that has one of the following types at position i of its type list,
+-
+
- + +
- + +
-
+
a union type or nullable union type +that has one of the above types in its flattened member types
+
then remove from S all other entries.
+ -
+
Otherwise: if there is an entry in S that has
+anyat position i of its type list, +then remove from S all other entries. -
+
Otherwise: throw a
+TypeError .
-
+
-
+
Let callable be the operation or extended attribute of the single entry in S.
+ -
+
If i = d and method is not
+undefined , then-
+
-
+
Let V be argi.
+ -
+
Let T be the type at index i in the +type list of the remaining entry in S.
+ -
+
If T is a sequence type, then +append to values the result of +.
+ -
+
Otherwise, T is a frozen array type. +Append to values the result of creating a frozen array of type T from V and method.
+ -
+
Set i to i + 1.
+
-
+
-
+
While i < argcount:
+-
+
-
+
Let V be argi.
+ -
+
Let type be the type at index i in the type list of the remaining entry in S.
+ -
+
Let optionality be the value at index i in the list of optionality values of the remaining entry in S.
+ -
+
If optionality is “optional” and V is
+undefined , then:-
+
-
+
If the argument at index i is declared with a default value, +then append to values that default value.
+ -
+
Otherwise, append to values the special value “missing”.
+
-
+
-
+
Otherwise, append to values the result of converting V to IDL type type.
+ -
+
Set i to i + 1.
+
-
+
-
+
While i is less than the number of arguments callable is declared to take:
+-
+
-
+
If callable’s argument at index i is declared with a default value, +then append to values that default value.
+ -
+
Otherwise, if callable’s argument at index i is not variadic, then append to values the special value “missing”.
+ -
+
Set i to i + 1.
+
-
+
-
+
Return the pair <callable, values>.
+
++The overload resolution algorithm performs both the identification + of which overloaded operation, constructor, etc. is being called, + and the conversion of the ECMAScript argument values to their + corresponding IDL values. Informally, it operates as follows.
+First, the selection of valid overloads is done by considering + the number of ECMAScript arguments that were passed in to the function:
+-
+
-
+
If there are more arguments passed in than the longest +overload argument list, then they are ignored.
+ -
+
After ignoring these trailing arguments, only overloads +that can take this exact number of arguments are considered. +If there are none, then a
+TypeError is thrown.
Once we have a set of possible overloads with the right number + of arguments, the ECMAScript values are converted from left to right. + The nature of the restrictions on overloading means that if we + have multiple possible overloads at this point, then there will + be one position in the argument list that will be used to + distinguish which overload we will finally select; this is + the distinguishing argument index.
+We first convert the arguments to the left of the distinguishing + argument. (There is a requirement that an argument to the left of + the distinguishing argument index has the same type as in the other + overloads, at the same index.) Then we inspect the type of the + ECMAScript value that is passed in at the distinguishing argument + index to determine which IDL type it may correspond to. + This allows us to select the final overload that will + be invoked. If the value passed in is
+undefined and there is an overload with an optional argument at this position, then + we will choose that overload. If there is no valid overload for the type of + value passed in here, then we throw aTypeError . + The inspection of the value at the distinguishing argument index does not have any side effects; + the only side effects that come from running the overload resolution + algorithm are those that come from converting the ECMAScript values + to IDL values.At this point, we have determined which overload to use. We now + convert the remaining arguments, from the distinguishing argument onwards, + again ignoring any additional arguments that were ignored due to being passed + after the last possible argument.
+When converting an optional argument’s ECMAScript value to its equivalent IDL value,
+undefined will be converted into + the optional argument’s default value, + if it has one, or a special value “missing” otherwise.Optional arguments corresponding to a final, variadic argument do not treat
+undefined as a special “missing” value, however. + Theundefined value is converted to the type + of variadic argument as would be done for a non-optional argument.4.6. Interfaces
+For every interface that +is exposed in a given +ECMAScript global environment and:
+-
+
-
+
is a callback interface that has constants declared on it, or
+ -
+
is a non-callback interface that is not declared with the [
+NoInterfaceObject] extended attribute,
a corresponding property must exist on the +ECMAScript environment’s global object. +The name of the property is the identifier of the interface, +and its value is an object called the interface object.
+The property has the attributes { [[Writable]]:
+true , [[Enumerable]]:false , [[Configurable]]:true }. +The characteristics of an interface object are described in §4.6.1 Interface object.In addition, for every [
+NamedConstructor] +extended attribute on an exposed interface, a corresponding property must +exist on the ECMAScript global object. The name of the property is theidentifier that occurs directly after the +“= ”, and its value is an object called a named constructor, which allows +construction of objects that implement the interface. The property has the +attributes { [[Writable]]:true , [[Enumerable]]:false , [[Configurable]]:true }. +The characteristics of a named constructor are described in §4.6.2 Named constructors.4.6.1. Interface object
+The interface object for a given non-callback interface is a function object. +It has properties that correspond to +the constants and static operations defined on that interface, as described in sections §4.6.5 Constants and §4.6.7 Operations.
+The [[Prototype]] internal property of +an interface object for a non-callback interface is determined as +follows:
+-
+
-
+
If the interface inherits from some other interface, the value +of [[Prototype]] is the interface +object for that other interface.
+ -
+
If the interface doesn’t inherit from any other interface, +the value of [[Prototype]] is %FunctionPrototype%.
+
An interface object for a non-callback interface must have a property named “prototype” +with attributes { [[Writable]]:
+false , [[Enumerable]]:false , [[Configurable]]:false } whose value is an object called the interface prototype object. This object has properties +that correspond to the regular attributes and regular operations defined on the interface, +and is described in more detail in §4.6.3 Interface prototype object.Note: Since an interface object for a non-callback interface is a function object the
+typeofoperator will return +"function" when applied to +such an interface object.The internal [[Prototype]] property +of an interface object for a callback interface must be +the Object.prototype object.
+Note: Remember that interface objects for callback interfaces only exist if they have constants declared on them; +when they do exist, they are not function objects.
+4.6.1.1. Interface object [[Call]] method
+If the interface is declared with a +[
+Constructor] extended attribute, +then the interface object can be called as a function to create an object that implements that +interface. Interfaces that do not have a constructor will throw +an exception when called as a function.The internal [[Call]] method +of the interface object behaves as follows, assuming arg0..n−1 is the list +of argument values passed to the constructor, and I is the interface:
+-
+
-
+
If I was not declared with a [
+Constructor] extended attribute, then throw aTypeError . -
+
Let id be the identifier of interface I.
+ -
+
Initialize S to the effective overload set for constructors with identifier id on interface I and with argument count n.
+ -
+
Let <constructor, values> be the result of passing S and arg0..n−1 to the overload resolution algorithm.
+ -
+
Let R be the result of performing the actions listed in the description of constructor with values as the argument values.
+ -
+
Return the result of converting R to an ECMAScript interface type value I.
+
If the internal [[Call]] method +of the interface object returns normally, then it must +return an object that implements interface I. +This object also must be +associated with the ECMAScript global environment associated +with the interface object.
+Interface objects for non-callback interfaces must have a property named “length” +with attributes { [[Writable]]:
+false , [[Enumerable]]:false , [[Configurable]]:true } whose value is aNumber . +If the [Constructor] extended attribute does not appear on the interface definition, then the value is 0. +Otherwise, the value is determined as follows:-
+
-
+
Let id be the identifier of interface I.
+ -
+
Initialize S to the effective overload set for constructors with identifier id on interface I and with argument count 0.
+ -
+
Return the length of the shortest argument list of the entries in S.
+
All interface objects must have a +property named “name” with attributes { [[Writable]]:
+false , [[Enumerable]]:false , [[Configurable]]:true } whose value is the identifier of the corresponding interface.4.6.1.2. Interface object [[HasInstance]] method
+The internal [[HasInstance]] method of every interface object A must behave as follows, +assuming V is the object +argument passed to [[HasInstance]]:
+-
+
-
+
If V is not an object, return
+false . -
+
Let O be the result of calling the [[Get]] method of A with property name “prototype”.
+ -
+
If O is not an object, throw a
+TypeError exception. -
+
If V is a platform object that implements the +interface for which O is the interface prototype object, +return
+true . -
+
Repeat:
+-
+
-
+
Set V to the value of the [[Prototype]] internal property of V.
+ -
+
If V is
+null , returnfalse . -
+
If O and V refer to the same object, +return
+true .
-
+
4.6.2. Named constructors
+A named constructor that exists due to one or more +[
+NamedConstructor] extended attributes with a given identifier is a function object. +It must have a [[Call]] +internal property, which allows construction of objects that +implement the interface on which the +[NamedConstructor] +extended attributes appear. It behaves as follows, assuming arg0..n−1 is the list +of argument values passed to the constructor, id is the identifier of the constructor specified in the +extended attribute named argument list, +and I is the interface on which the [NamedConstructor] +extended attribute appears:-
+
-
+
Initialize S to the effective overload set for constructors with identifier id on interface I and with argument count n.
+ -
+
Let <constructor, values> be the result of passing S and arg0..n−1 to the overload resolution algorithm.
+ -
+
Let R be the result of performing the actions listed in the description of constructor with values as the argument values.
+ -
+
Return the result of converting R to an ECMAScript interface type value I.
+
If the internal [[Call]] method +of the named constructor returns normally, then it must +return an object that implements interface I. +This object also must be +associated with the ECMAScript global environment associated +with the named constructor.
+A named constructor must have a property named “length” +with attributes { [[Writable]]:
+false , [[Enumerable]]:false , [[Configurable]]:true } whose value is aNumber determined as follows:-
+
-
+
Initialize S to the effective overload set for constructors with identifier id on interface I and with argument count 0.
+ -
+
Return the length of the shortest argument list of the entries in S.
+
A named constructor must have a property named “name” +with attributes { [[Writable]]:
+false , [[Enumerable]]:false , [[Configurable]]:true } whose value is the identifier used for the named constructor.A named constructor must also have a property named +“prototype” with attributes { [[Writable]]:
+false , [[Enumerable]]:false , [[Configurable]]:false } whose value is the interface prototype object for the interface on which the +[NamedConstructor] extended attribute appears.4.6.3. Interface prototype object
+There must exist an interface prototype object for every non-callback interface defined, regardless of whether the interface was declared with the +[
+NoInterfaceObject] extended attribute. +The interface prototype object for a particular interface has +properties that correspond to the regular attributes and regular operations defined on that interface. These properties are described in more detail in +sections §4.6.6 Attributes and §4.6.7 Operations.As with the interface object, +the interface prototype object also has properties that correspond to the constants defined on that +interface, described in §4.6.7 Operations.
+If the [
+NoInterfaceObject] +extended attribute was not specified on the interface, then +the interface prototype object must +also have a property named “constructor” with attributes { [[Writable]]:true , [[Enumerable]]:false , [[Configurable]]:true } whose value +is a reference to the interface object for the interface.The interface prototype object for a given interface A must have an internal +[[Prototype]] property whose value is returned from +the following steps:
+-
+
-
+
If A is declared with the [
+Global] +or [PrimaryGlobal] extended attribute, and A supports named properties, then +return the named properties object for A, as defined in §4.6.4 Named properties object. -
+
Otherwise, if A is declared to inherit from another +interface, then return the interface prototype object for the inherited interface.
+ -
+
Otherwise, if A is declared with the [
+LegacyArrayClass] +extended attribute, then return %ArrayPrototype%. -
+
Otherwise, return %ObjectPrototype%.
+
++The interface prototype object of an interface that is defined with + the [
+NoInterfaceObject] extended attribute will be accessible if the interface is used as a non-supplemental interface. + For example, with the following IDL:[NoInterfaceObject] +interface Foo { +}; + +partial interface Window { + attribute Foo foo; +}; +
+it is not possible to access the interface prototype object through + the interface object (since it does not exist as
+window.Foo). However, an instance + ofFoocan expose the interface prototype + object by gettings its internal [[Prototype]] + property value –Object.getPrototypeOf(window.foo)in + this example.If the interface is used solely as a supplemental interface, + then there will be no way to access its interface prototype object, since no + object will have the interface prototype object as its internal + [[Prototype]] property value. In such cases, + it is an acceptable optimization for this object not to exist.
+If the interface or any of its consequential interfaces has any interface member declared with +the [
+Unscopable] extended attribute, +then there must be a property on the +interface prototype object whose name is the @@unscopables symbol +and whose value is an object created as follows:-
+
-
+
Let object be a new object created as if by the expression
+({}). -
+
For each of the aforementioned interface members declared with the [
+Unscopable] extended attribute, +call CreateDataProperty(object, +the identifier of the +interface member,true ). -
+
Return object.
+
If the interface is declared with the [
+Global] or +[PrimaryGlobal] extended attribute, or the interface is in the set +of inherited interfaces for any +other interface that is declared with one of these attributes, then the interface prototype object must be an immutable prototype exotic object.The class string of an interface prototype object is the concatenation of the interface’s identifier and the string +“Prototype”.
+4.6.4. Named properties object
+For every interface declared with the +[
+Global] or +[PrimaryGlobal] extended attribute that supports named properties, +there must exist an object known as the named properties object for that +interface.The named properties object for a given interface A must have an internal +[[Prototype]] property whose value is returned from +the following steps:
+-
+
-
+
If A is declared to inherit from another interface, then return the interface prototype object for the inherited interface.
+ -
+
Otherwise, if A is declared with the [
+LegacyArrayClass] +extended attribute, then return %ArrayPrototype%. -
+
Otherwise, return %ObjectPrototype%.
+
The class string of a named properties object is the concatenation of the interface’s identifier and the string +“Properties”.
+4.6.4.1. Named properties object [[GetOwnProperty]] method
+When the [[GetOwnProperty]] internal method of a named properties object O is called with property key P, the following steps are +taken:
+-
+
-
+
Let A be the interface for the named properties object O.
+ -
+
Let object be the sole object from O’s ECMAScript global environment that implements A.
+Note: For example, if the interface is the
+Windowinterface, +then the sole object will be this global environment’s window object. -
+
If the result of running the named property visibility algorithm with +property name P and object object is true, then:
+-
+
-
+
Let operation be the operation used to declare the named property getter.
+ -
+
Let value be an uninitialized variable.
+ -
+
If operation was defined without an identifier, then +set value to the result of performing the steps listed in the interface description to determine the value of a named property with P as the name.
+ -
+
Otherwise, operation was defined with an identifier. Set value to the result +of performing the steps listed in the description of operation with P as the only argument value.
+ -
+
Let desc be a newly created Property Descriptor with no fields.
+ -
+
Set desc.[[Value]] to the result of converting value to an ECMAScript value.
+ -
+
If A implements an interface with the +[
+LegacyUnenumerableNamedProperties] extended attribute, +then set desc.[[Enumerable]] tofalse , +otherwise set it totrue . -
+
Set desc.[[Writable]] to
+true and desc.[[Configurable]] totrue . -
+
Return desc.
+
-
+
-
+
Return OrdinaryGetOwnProperty(O, P).
+
4.6.4.2. Named properties object [[DefineOwnProperty]] method
+When the [[DefineOwnProperty]] internal method of a named properties object is +called, the following steps are taken:
+-
+
-
+
Return
+false .
4.6.4.3. Named properties object [[Delete]] method
+When the [[Delete]] internal method of a named properties object is called, the +following steps are taken:
+-
+
-
+
Return
+false .
4.6.4.4. Named properties object [[SetPrototypeOf]] method
+When the [[SetPrototypeOf]] internal method of a named properties object is +called, the same algorithm must be executed as is defined for the [[SetPrototypeOf]] internal method of an immutable prototype exotic object.
+4.6.5. Constants
+For each exposed constant defined on +an interface A, there +must be a corresponding property. +The property has the following characteristics:
+-
+
-
+
The name of the property is the identifier of the constant.
+ -
+
The location of the property is determined as follows:
+-
+
-
+
If the interface was declared with the [
+Global] or [PrimaryGlobal] extended attribute, +then the property exists on the single object that implements the interface. -
+
Otherwise, if the interface is a consequential interface of a [
+Global]- or [PrimaryGlobal] annotated interface, then +the property exists on the single object that implements the [Global]- or +[PrimaryGlobal]-annotated interface as well as on +the consequential interface’s interface prototype object. -
+
Otherwise, the property exists solely on the interface’s interface prototype object.
+
-
+
-
+
The value of the property is that which is obtained by converting the constant’s IDL value to an ECMAScript value.
+ -
+
The property has attributes { [[Writable]]:
+false , [[Enumerable]]:true , [[Configurable]]:false }.
In addition, a property with the same characteristics must +exist on the interface object, if +that object exists.
+4.6.6. Attributes
+For each exposed attribute of the interface, whether it +was declared on the interface itself or one of its consequential interfaces, +there must exist a corresponding property. +The characteristics of this property are as follows:
+-
+
-
+
The name of the property is the identifier of the attribute.
+ -
+
The location of the property is determined as follows:
+-
+
-
+
If the attribute is a static attribute, +then there is a single corresponding property and it exists on the interface’s interface object.
+ -
+
Otherwise, if the attribute is unforgeable on +the interface or if the interface was declared with the [
+Global] or [PrimaryGlobal] extended attribute, +then the property exists on every object that implements the interface. -
+
Otherwise, if the interface is a consequential interface of a [
+Global]- or [PrimaryGlobal]-annotated interface, then +the property exists on the single object that implements the [Global]- or +[PrimaryGlobal]-annotated interface as well as on +the consequential interface’s interface prototype object. -
+
Otherwise, the property exists solely on the interface’s interface prototype object.
+
-
+
-
+
The property has attributes { [[Get]]: G, [[Set]]: S, [[Enumerable]]:
+true , [[Configurable]]: configurable }, +where:-
+
-
+
configurable is
+false if the attribute was +declared with the [Unforgeable] extended attribute andtrue otherwise; -
+
G is the attribute getter, defined below; and
+ -
+
S is the attribute setter, also defined below.
+
-
+
-
+
The attribute getter is a
+Function object whose behavior when invoked is as follows:-
+
-
+
Let idlValue be an IDL value determined as follows.
+ -
+
If the attribute is a regular attribute, then:
+-
+
-
+
Let I be the interface whose interface prototype object this property corresponding to the attribute appears on.
+Note: This means that even if an implements statement was used to make +an attribute available on the interface, I is the interface +on the left hand side of the implements statement, and not the one +that the attribute was originally declared on.
+ -
+
Let O be the this value.
+ -
+
If O is a platform object, +then perform a security check, passing:
+-
+
-
+
the platform object O,
+ -
+
the ECMAScript global environment associated with this
+Function that +implements the attribute getter, -
+
the identifier of the attribute, and
+ -
+
the type “getter”.
+
-
+
-
+
If O is not a platform object that implements I, then:
+-
+
-
+
If the attribute was specified with the +[
+LenientThis] extended attribute, +then returnundefined . -
+
Otherwise, throw a
+TypeError .
-
+
-
+
Set idlValue to be the result of performing the actions listed in the description of the attribute that occur when getting +(or those listed in the description of the inherited attribute, if this attribute is declared to inherit its getter), +with O as the object.
+
-
+
-
+
Otherwise, the attribute is a static attribute. +Set idlValue to be the result of performing the actions listed in the description of the attribute that occur when getting.
+ -
+
Let V be the result of converting idlValue to an ECMAScript value.
+ -
+
Return V.
+
The value of the
+Function object’s “length” +property is theNumber value0 .The value of the
+Function object’s “name” +property is aString whose value is the +concatenation of “get ” and the identifier of the attribute. -
+
-
+
The attribute setter is
+undefined if the attribute is declaredreadonlyand does not have a +[LenientThis], [PutForwards] or +[Replaceable] extended attribute declared on it. +Otherwise, it is aFunction object whose behavior when invoked is as follows:-
+
-
+
If no arguments were passed to the
+Function , then throw aTypeError . -
+
Let V be the value of the first argument passed to the
+Function . -
+
If the attribute is a regular attribute, then:
+-
+
-
+
Let I be the interface whose interface prototype object this property corresponding to the attribute appears on.
+ -
+
Let O be the this value.
+ -
+
If O is a platform object, +then perform a security check, passing:
+-
+
-
+
the platform object O,
+ -
+
the ECMAScript global environment associated with this
+Function that +implements the attribute setter, -
+
the identifier of the attribute, and
+ -
+
the type “setter”.
+
-
+
-
+
Let validThis be
+true if O is a platform object that implements I, orfalse otherwise. -
+
If validThis is
+false and the attribute was not specified with the +[LenientThis] extended attribute, +then throw aTypeError . -
+
If the attribute is declared with a [
+Replaceable] +extended attribute, then:-
+
-
+
Let P be the identifier of the attribute.
+ -
+
Call CreateDataProperty(O, P, V).
+ -
+
Return
+undefined .
-
+
-
+
If validThis is
+false , then returnundefined . -
+
If the attribute is declared with a [
+LenientSetter] +extended attribute, then returnundefined . -
+
If the attribute is declared with a [
+PutForwards] +extended attribute, then:-
+
-
+
Let Q be the result of calling the [[Get]] method +on O using the identifier of the attribute as the property name.
+ -
+
If Q is not an object, then throw a
+TypeError . -
+
Let A be the attribute identified by the [
+PutForwards] extended attribute. -
+
Call the [[Put]] method on Q using the identifier of A as the property name and V as the value.
+ -
+
Return
+undefined .
-
+
-
+
-
+
Let idlValue be an IDL value determined as follows:
+-
+
-
+
If the type of the attribute is an enumeration, then:
+-
+
-
+
Let S be the result of calling ToString(V).
+ -
+
If S is not one of the enumeration’s values, then return
+undefined . -
+
The value of idlValue is the enumeration value equal to S.
+
-
+
-
+
Otherwise, the type of the attribute is not an enumeration. +The value of idlValue is the result of converting V to an IDL value.
+
-
+
-
+
If the attribute is a regular attribute, then perform the actions listed in the description of the attribute that occur when setting, +with O as the object and idlValue as the value.
+ -
+
Otherwise, the attribute is a static attribute. +Perform the actions listed in the description of the attribute that occur when setting with idlValue as the value.
+ -
+
Return
+undefined .
The value of the
+Function object’s “length” +property is theNumber value1 .The value of the
+Function object’s “name” +property is aString whose value is the +concatenation of “set ” and the identifier of the attribute. -
+
Note: Although there is only a single property for an IDL attribute, since +accessor property getters and setters are passed a
+this value for the object on which property corresponding to the IDL attribute is +accessed, they are able to expose instance-specific data.Note: Note that attempting to assign to a property corresponding to a read only attribute results in different behavior depending on whether the script doing so is in strict mode. +When in strict mode, such an assignment will result in a
+TypeError being thrown. When not in strict mode, the assignment attempt will be ignored.4.6.7. Operations
+For each unique identifier of an exposed operation defined on the interface, there +must exist a corresponding property, +unless the effective overload set for that identifier and operation and with an argument count of 0 has no entries.
+The characteristics of this property are as follows:
+-
+
-
+
The name of the property is the identifier.
+ -
+
The location of the property is determined as follows:
+-
+
-
+
If the operation is static, then +the property exists on the interface object.
+ -
+
Otherwise, if the operation is unforgeable on +the interface or if the interface was declared with the [
+Global] or [PrimaryGlobal] extended attribute, +then the property exists on every object that implements the interface. -
+
Otherwise, if the interface is a consequential interface of a [
+Global]- or [PrimaryGlobal]-annotated interface, then +the property exists on the single object that implements the [Global]- or +[PrimaryGlobal]-annotated interface as well as on +the consequential interface’s interface prototype object. -
+
Otherwise, the property exists solely on the interface’s interface prototype object.
+
-
+
-
+
The property has attributes { [[Writable]]: B, [[Enumerable]]:
+true , [[Configurable]]: B }, +where B isfalse if the operation is unforgeable on the interface, +andtrue otherwise. -
+
The value of the property is a
+Function object whose +behavior is as follows, +assuming id is the identifier, arg0..n−1 is the list +of argument values passed to the function:-
+
-
+
Try running the following steps:
+-
+
-
+
Let I be the interface whose interface prototype object (or interface object, for a static +operation) this property corresponding to the operation appears on.
+Note: This means that even if an implements statement was used to make +an operation available on the interface, I is the interface +on the left hand side of the implements statement, and not the one +that the operation was originally declared on.
+ -
+
Let O be a value determined as follows:
+-
+
-
+
If the operation is a static operation, then O is
+null . -
+
Otherwise, if the interface on which the operation appears has an +[
+ImplicitThis] extended attribute, +and thethis value isnull orundefined , then O is +the ECMAScript global object associated with theFunction object. -
+
Otherwise, if the
+this value is notnull , +then O is thethis value. -
+
Otherwise, throw a
+TypeError .
-
+
-
+
If O is a platform object, +then perform a security check, passing:
+-
+
-
+
the platform object O,
+ -
+
the ECMAScript global environment associated with this
+Function that +implements the operation, -
+
the identifier of the operation, and
+ -
+
the type “method”.
+
-
+
-
+
If O is not
+null and is also not a platform object that implements interface I, throw aTypeError . -
+
Initialize S to the effective overload set for regular operations (if the operation is a regular operation) or for static operations (if the operation is a static operation) with identifier id on interface I and with argument count n.
+ -
+
Let <operation, values> be the result of passing S and arg0..n−1 to the overload resolution algorithm.
+ -
+
Let R be the result of performing (on O, if the operation +is not a static operation) the actions listed in the description of operation with values as the argument values.
+ -
+
Return the result of converting R to an ECMAScript value of +the type op is declared to return.
+
And then, if an exception was thrown:
+-
+
-
+
If the operation has a return type that is a promise type, then:
+ + -
+
Otherwise, end these steps and allow the exception to propagate.
+
-
+
-
+
-
+
The value of the
+Function object’s “length” +property is aNumber determined as follows:-
+
-
+
Let S be the effective overload set for regular operations (if the operation is a regular operation) or for static operations (if the operation is a static operation) with identifier id on interface I and with argument count 0.
+ -
+
Return the length of the shortest argument list of the entries in S.
+
-
+
-
+
The value of the
+Function object’s “name” +property is aString whose value is the +identifier of the operation.
We also define creating an operation function, given an operation op, a namespace namespace, and a Realm realm:
+Note: The astute reader may notice that what follows is very similar to the +above algorithm for operations on interfaces. It is currently only used for namespaces, +but we have near-future plans to generalize it slightly and then replace the above +definition so that this algorithm is useful both for interfaces and namespaces.
+-
+
-
+
Let id be op’s identifier.
+ -
+
Let steps be the following series of steps, given function argument +values arg0..n−1:
+-
+
-
+
Try running the following steps:
+-
+
-
+
Let S be the effective overload set for regular operations with identifier id on namespace namespace and with argument count n.
+ -
+
Let <operation, values> be the result of passing S and arg0..n−1 to the overload resolution algorithm.
+ -
+
Let R be the result of performing the actions listed in the +description of operation with values as the argument +values.
+ -
+
Return the result of converting R to +an ECMAScript value of the type op is declared to return.
+
-
+
And then, if an exception was thrown:
+-
+
-
+
If the operation has a return type that is a promise type, then:
+ + -
+
Otherwise, end these steps and allow the exception to propagate.
+
-
+
-
+
Let F be ! CreateBuiltinFunction(realm, steps, the %FunctionPrototype% of realm).
+ -
+
Perform ! SetFunctionName(F, id).
+ -
+
Let S be the effective overload set for regular operations with identifier id on namespace namespace and with argument count 0.
+ -
+
Let length be the length of the shortest argument list in the entries in S.
+ -
+
Perform ! DefinePropertyOrThrow(F,
+"length", +PropertyDescriptor{[[Value]]: length, +[[Writable]]:false , [[Enumerable]]:false , [[Configurable]]:true }).
4.6.7.1. Stringifiers
+If the interface has an exposed stringifier, then +there must exist a property with +the following characteristics:
+-
+
-
+
The name of the property is “toString”.
+ -
+
If the stringifier is unforgeable on the interface +or if the interface was declared with the [
+Global] or [PrimaryGlobal] extended attribute, +then the property exists on every object that implements the interface. +Otherwise, the property exists on the interface prototype object. -
+
The property has attributes { [[Writable]]: B, [[Enumerable]]:
+true , [[Configurable]]: B }, +where B isfalse if the stringifier is unforgeable on the interface, +andtrue otherwise. -
+
The value of the property is a
+Function object, which behaves as follows:-
+
-
+
Let O be the result of calling ToObject on the
+this value. -
+
If O is a platform object, +then perform a security check, passing:
+-
+
-
+
the platform object O,
+ -
+
the ECMAScript global environment associated with this
+Function that +implements the stringifier, -
+
the identifier of the stringifier, and
+ -
+
the type “method”.
+
-
+
-
+
If O is not an object that implements the interface on which the stringifier was declared, then throw a
+TypeError . -
+
Let V be an uninitialized variable.
+ -
+
Depending on where
+stringifierwas specified:-
+
-
+
on an attribute
+ -
+
Set V to the result of performing the actions listed in the description of the attribute that occur when getting +(or those listed in the description of the inherited attribute, if this attribute is declared to inherit its getter), +with O as the object.
+ -
+
on an operation with an identifier
+ -
+
Set V to the result of performing the actions listed in the description +of the operation, using O as the
+this value +and passing no arguments. -
+
on an operation with no identifier
+ -
+
Set V to the result of performing the stringification behavior of the interface.
+
-
+
-
+
Return the result of converting V to a
+String value.
-
+
-
+
The value of the
+Function object’s “length” +property is theNumber value0 . -
+
The value of the
+Function object’s “name” +property is theString value “toString”.
4.6.7.2. Serializers
+If the interface has an exposed serializer, then +a property must exist +whose name is “toJSON”, +with attributes { [[Writable]]:
+true , [[Enumerable]]:true , [[Configurable]]:true } and whose value is aFunction object.The location of the property is determined as follows:
+-
+
-
+
If the interface was declared with the [
+Global] or [PrimaryGlobal] extended attribute, +then the property exists on the single object that implements the interface. -
+
Otherwise, if the interface is a consequential interface of a [
+Global]- or [PrimaryGlobal]-annotated interface, then +the property exists on the single object that implements the [Global]- or +[PrimaryGlobal]-annotated interface as well as on +the consequential interface’s interface prototype object. -
+
Otherwise, the property exists solely on the interface’s interface prototype object.
+
The property’s
+Function object, when invoked, +must behave as follows:-
+
-
+
Let O be the result of calling ToObject on the
+this value. -
+
If O is a platform object, +then perform a security check, passing:
+-
+
-
+
the platform object O,
+ -
+
the ECMAScript global environment associated with this
+Function that +implements the serializer, -
+
the identifier of the serializer, and
+ -
+
the type “method”.
+
-
+
-
+
If O is not an object that implements the interface on which the serializer was declared, then throw a
+TypeError . -
+
Depending on how
+serializerwas specified:-
+
-
+
on an operation with an identifier
+ -
+
-
+
-
+
Return the result of performing the actions listed in the description of the +operation, using O as the
+this value +and passing no arguments.
-
+
-
+
as a keyword, either with or without a serialization pattern
+ -
+
-
+
-
+
Let S be the serialized value that is the result of invoking the serialization behavior of the interface for object O.
+ -
+
Return the result of converting S to an ECMAScript value.
+
-
+
-
+
The value of the
+Function object’s “length” +property is theNumber value0 .The value of the
+Function object’s “name” +property is theString value “toJSON”.The following steps define how to convert a serialized value to an ECMAScript value:
+-
+
-
+
Let S be the serialized value.
+ -
+
Depending on the type of S:
+-
+
-
+
a map
+ -
+
-
+
-
+
Let O be a new object created as if by the expression
+({}). -
+
For each entry in S, in the order they were added to the map:
+-
+
-
+
Let V be the result of converting the value of the entry to an ECMAScript value.
+ -
+
Let P be the entry’s key.
+ -
+
Call CreateDataProperty(O, P, V).
+
-
+
-
+
Return O.
+
-
+
-
+
a list
+ -
+
-
+
-
+
Let A be a new
+Array object created as if by the expression[]. -
+
Let index be 0.
+ -
+
While index is less than the number of elements in S:
+-
+
-
+
Let V be the result of converting the value of the element in S at index index to an ECMAScript value.
+ -
+
Let P be ToString(index).
+ -
+
Call CreateDataProperty(O, P, V).
+
-
+
-
+
Return A.
+
-
+
-
+
any other serialized value
+ -
+
-
+
-
+
Let V be the result of converting S to an ECMAScript value.
+ -
+
Return V.
+
-
+
-
+
4.6.8. Common iterator behavior
+4.6.8.1. @@iterator
+If the interface has any of the following:
+-
+
- + +
-
+
an indexed property getter and an integer-typed attribute named +“length”
+ - + +
- + +
then a property must exist +whose name is the @@iterator symbol, +with attributes { [[Writable]]:
+true , [[Enumerable]]:false , [[Configurable]]:true } and whose value is a function object.The location of the property is determined as follows:
+-
+
-
+
If the interface was declared with the [
+Global] or [PrimaryGlobal] extended attribute, +then the property exists on the single object that implements the interface. -
+
Otherwise, if the interface is a consequential interface of a [
+Global]- or [PrimaryGlobal]-annotated interface, then +the property exists on the single object that implements the [Global]- or +[PrimaryGlobal]-annotated interface as well as on +the consequential interface’s interface prototype object. -
+
Otherwise, the property exists solely on the interface’s interface prototype object.
+
If the interface defines an indexed property getter, +then the
+Function object is %ArrayProto_values%.If the interface has a pair iterator, +then the
+Function , when invoked, +must behave as follows:-
+
-
+
Let object be the result of calling ToObject on the
+this value. -
+
If object is a platform object, +then perform a security check, passing:
+-
+
-
+
the platform object object,
+ -
+
the ECMAScript global environment associated with this
+Function , -
+
the identifier “@@iterator”, and
+ -
+
the type “method”.
+
-
+
-
+
Let interface be the interface the iterable declaration is on.
+ -
+
If object is not a platform object that implements interface, +then throw a
+TypeError . -
+
Let iterator be a newly created default iterator object for interface with object as its target and iterator kind “key+value”.
+ -
+
Return iterator.
+
If the interface has a maplike declaration or setlike declaration, +then the
+Function object that is the value of the @@iterator property, +when invoked, must behave as follows:-
+
-
+
Let object be the result of calling ToObject on the
+this value. -
+
If object is a platform object, +then perform a security check, passing:
+-
+
-
+
the platform object object,
+ -
+
the ECMAScript global environment associated with this
+Function , -
+
the identifier “@@iterator”, and
+ -
+
the type “method”.
+
-
+
-
+
If object is not a platform object that implements the interface on which the maplike declaration or setlike declaration is defined, +then throw a
+TypeError . -
+
If the interface has a maplike declaration, then:
+-
+
-
+
Let backing be the value of the [[BackingMap]] internal slot of object.
+ -
+
Return CreateMapIterator(backing,
+"key+value").
-
+
-
+
Otherwise:
+-
+
-
+
Let backing be the value of the [[BackingSet]] internal slot of object.
+ -
+
Return CreateSetIterator(backing,
+"value").
-
+
The value of the @@iterator
+Function object’s “length” +property is theNumber value0 .The value of the @@iterator
+Function object’s “name” +property is theString value “entries” if the interface has a pair iterator or a maplike declaration and theString “values” +if the interface has a setlike declaration.4.6.8.2. forEach
+If the interface has any of the following:
+-
+
- + +
- + +
- + +
then a property named “forEach” must exist +with attributes { [[Writable]]:
+true , [[Enumerable]]:true , [[Configurable]]:true } and whose value is a function object.The location of the property is determined as follows:
+-
+
-
+
If the interface was declared with the [
+Global] or [PrimaryGlobal] extended attribute, +then the property exists on the single object that implements the interface. -
+
Otherwise, if the interface is a consequential interface of a [
+Global]- or [PrimaryGlobal]-annotated interface, then +the property exists on the single object that implements the [Global]- or +[PrimaryGlobal]-annotated interface as well as on +the consequential interface’s interface prototype object. -
+
Otherwise, the property exists solely on the interface’s interface prototype object.
+
If the interface defines an indexed property getter, +then the
+Function object is +the initial value of the “forEach” data property of %ArrayPrototype%.If the interface has a pair iterator, +then the
+Function must +have the same behavior as one that would exist assuming the interface had +this operation instead of the iterable declaration:interface Iterable { + void forEach(Function callback, optional any thisArg); +}; +
+with the following prose definition:
+-
+
-
+
Let O be the this value.
+ -
+
Let pairs be the list of value pairs to iterate over.
+ -
+
Let i be 0.
+ -
+
While i is less than the length of pairs:
+-
+
-
+
Let pair be the entry in pairs at index i.
+ -
+
Let key be pair’s key.
+ -
+
Let value be pair’s value.
+ -
+
Invoke callback with thisArg (or
+undefined , if the argument was not supplied) +as the callback this value and value, key and O as its arguments. -
+
Update pairs to the current list of value pairs to iterate over.
+ -
+
Set i to i + 1.
+
-
+
If the interface has a maplike declaration or setlike declaration then the
+Function , when invoked, +must behave as follows:-
+
-
+
Let object be the result of calling ToObject on the
+this value. -
+
If object is a platform object, +then perform a security check, passing:
+-
+
-
+
the platform object object,
+ -
+
the ECMAScript global environment associated with this
+Function , -
+
the identifier “forEach”, and
+ -
+
the type “method”.
+
-
+
-
+
Let interface be the interface on which the maplike declaration or setlike declaration is declared.
+ -
+
If object is not a platform object that implements interface, +then throw a
+TypeError . -
+
Let callbackFn be the value of the first argument passed to the function, or
+undefined if the argument was not supplied. -
+
If IsCallable(callbackFn) is
+false , throw aTypeError . -
+
Let thisArg be the value of the second argument passed to the function, or
+undefined if the argument was not supplied. -
+
Let backing be the value of the [[BackingMap]] internal slot of object, +if the interface has a maplike declaration, +or the [[BackingSet]] internal slot of object otherwise.
+ -
+
Let callbackWrapper be a
+Function that, when invoked, behaves as follows:-
+
-
+
Let v and k be the first two arguments passed to the function.
+ -
+
Let thisArg be the
+this value. -
+
Call the [[Call]] internal method of callbackFn with thisArg as thisArgument and v, k and object as argumentsList.
+
Note: The callbackWrapper function simply calls the incoming callbackFn with object as the third argument rather than its internal [[BackingMap]] or [[BackingSet]] object.
+Can the script author observe that callbackWrapper might be a new function + every time forEach is called? What’s the best way of specifying that there’s only + one function that has captured an environment?
+ -
+
-
+
Let forEach be the result of calling the [[Get]] internal method of backing with “forEach” and backing as arguments.
+ -
+
If IsCallable(forEach) is
+false , throw aTypeError . -
+
Call the [[Call]] internal method of forEach with backing as thisArgument and callbackWrapper and thisArg as argumentsList.
+ -
+
Return
+undefined .
The value of the
+Function object’s “length” +property is theNumber value1 .The value of the
+Function object’s “name” +property is theString value “forEach”.4.6.9. Iterable declarations
+4.6.9.1. entries
+If the interface has an iterable declaration, +then a property named “entries” must exist +with attributes { [[Writable]]:
+true , [[Enumerable]]:true , [[Configurable]]:true } and whose value is a function object.The location of the property is determined as follows:
+-
+
-
+
If the interface was declared with the [
+Global] or [PrimaryGlobal] extended attribute, +then the property exists on the single object that implements the interface. -
+
Otherwise, if the interface is a consequential interface of a [
+Global]- or [PrimaryGlobal]-annotated interface, then +the property exists on the single object that implements the [Global]- or +[PrimaryGlobal]-annotated interface as well as on +the consequential interface’s interface prototype object. -
+
Otherwise, the property exists solely on the interface’s interface prototype object.
+
If the interface has a value iterator, +then the
+Function object is +the initial value of the “entries” data property of %ArrayPrototype%.If the interface has a pair iterator, +then the
+Function object is +the value of the @@iterator property.4.6.9.2. keys
+If the interface has an iterable declaration, +then a property named “keys” must exist +with attributes { [[Writable]]:
+true , [[Enumerable]]:true , [[Configurable]]:true } and whose value is a function object.The location of the property is determined as follows:
+-
+
-
+
If the interface was declared with the [
+Global] or [PrimaryGlobal] extended attribute, +then the property exists on the single object that implements the interface. -
+
Otherwise, if the interface is a consequential interface of a [
+Global]- or [PrimaryGlobal]-annotated interface, then +the property exists on the single object that implements the [Global]- or +[PrimaryGlobal]-annotated interface as well as on +the consequential interface’s interface prototype object. -
+
Otherwise, the property exists solely on the interface’s interface prototype object.
+
If the interface has a value iterator, +then the
+Function object is +the initial value of the “keys” data property of %ArrayPrototype%.If the interface has a pair iterator, +then the
+Function , when invoked, must behave as follows:-
+
-
+
Let object be the result of calling ToObject on the
+this value. -
+
If object is a platform object, +then perform a security check, passing:
+-
+
-
+
the platform object object,
+ -
+
the ECMAScript global environment associated with this
+Function , -
+
the identifier “keys”, and
+ -
+
the type “method”.
+
-
+
-
+
Let interface be the interface on which the iterable declaration is declared on.
+ -
+
If object is not a platform object that implements interface, +then throw a
+TypeError . -
+
Let iterator be a newly created default iterator object for interface with object as its target and iterator kind “key”.
+ -
+
Return iterator.
+
The value of the
+Function object’s “length” property is theNumber value0 .The value of the
+Function object’s “name” property is theString value “keys”.4.6.9.3. values
+If the interface has an iterable declaration, +then a property named “values” must exist +with attributes { [[Writable]]:
+true , [[Enumerable]]:true , [[Configurable]]:true } and whose value is a function object.The location of the property is determined as follows:
+-
+
-
+
If the interface was declared with the [
+Global] or [PrimaryGlobal] extended attribute, +then the property exists on the single object that implements the interface. -
+
Otherwise, if the interface is a consequential interface of a [
+Global]- or [PrimaryGlobal]-annotated interface, then +the property exists on the single object that implements the [Global]- or +[PrimaryGlobal]-annotated interface as well as on +the consequential interface’s interface prototype object. -
+
Otherwise, the property exists solely on the interface’s interface prototype object.
+
If the interface has a value iterator, +then the
+Function object is +the value of the @@iterator property.If the interface has a pair iterator, +then the
+Function , when invoked, must behave as follows:-
+
-
+
Let object be the result of calling ToObject on the
+this value. -
+
If object is a platform object, +then perform a security check, passing:
+-
+
-
+
the platform object object,
+ -
+
the ECMAScript global environment associated with this
+Function , -
+
the identifier “entries”, and
+ -
+
the type “method”.
+
-
+
-
+
Let interface be the interface on which the iterable declaration is declared on.
+ -
+
If object is not a platform object that implements interface, +then throw a
+TypeError . -
+
Let iterator be a newly created default iterator object for interface with object as its target and iterator kind “value”.
+ -
+
Return iterator.
+
The value of the
+Function object’s “length” property is theNumber value0 .The value of the
+Function object’s “name” property is theString value “values”.4.6.9.4. Default iterator objects
+A default iterator object for a given interface, target and iteration kind +is an object whose internal [[Prototype]] property is the iterator prototype object for the interface.
+A default iterator object has three internal values:
+-
+
-
+
its target, which is an object whose values are to be iterated,
+ -
+
its kind, which is the iteration kind,
+ -
+
its index, which is the current index into the values value to be iterated.
+
Note: Default iterator objects are only used for pair iterators; value iterators, as they are currently +restricted to iterating over an object’s supported indexed properties, +use standard ECMAScript Array iterator objects.
+When a default iterator object is first created, +its index is set to 0.
+The class string of a default iterator object for a given interface is the result of concatenting the identifier of the interface and +the string “ Iterator”.
+4.6.9.5. Iterator prototype object
+The iterator prototype object for a given interface is an object that exists for every interface that has a pair iterator. It serves as the +prototype for default iterator objects for the interface.
+The internal [[Prototype]] property of an iterator prototype object must be %IteratorPrototype%.
+An iterator prototype object must have a property named “next” with +attributes { [[Writable]]:
+true , [[Enumerable]]:true , [[Configurable]]:true } and whose value is a function object that behaves as follows:-
+
-
+
Let interface be the interface for which the iterator prototype object exists.
+ -
+
Let object be the result of calling ToObject on the
+this value. -
+
If object is a platform object, +then perform a security check, passing:
+-
+
-
+
the platform object object,
+ -
+
the ECMAScript global environment associated with this
+Function , -
+
the identifier “next”, and
+ -
+
the type “method”.
+
-
+
-
+
If object is not a default iterator object for interface, +then throw a
+TypeError . -
+
Let target be object’s target.
+ -
+
Let index be object’s index.
+ -
+
Let kind be object’s kind.
+ -
+
Let values be the list of value pairs to iterate over.
+ -
+
Let len be the length of values.
+ -
+
If object’s index is greater than or equal to len, then +return CreateIterResultObject(
+undefined ,true ). -
+
Let pair be the entry in values at index index.
+ -
+
Let result be a value determined by the value of kind:
+-
+
-
+
key
+ -
+
-
+
-
+
Let idlKey be pair’s key.
+ -
+
Let key be the result of converting idlKey to an ECMAScript value.
+ -
+
result is key.
+
-
+
-
+
value
+ -
+
-
+
-
+
Let idlValue be pair’s value.
+ -
+
Let value be the result of converting idlValue to an ECMAScript value.
+ -
+
result is value.
+
-
+
-
+
key+value
+ -
+
-
+
-
+
Let idlKey be pair’s key.
+ -
+
Let idlValue be pair’s value.
+ -
+
Let key be the result of converting idlKey to an ECMAScript value.
+ -
+
Let value be the result of converting idlValue to an ECMAScript value.
+ -
+
Let array be the result of performing ArrayCreate(2).
+ -
+
Call CreateDataProperty(array, "0", key).
+ -
+
Call CreateDataProperty(array, "1", value).
+ -
+
result is array.
+
-
+
-
+
-
+
Return CreateIterResultObject(result,
+false ).
The class string of an iterator prototype object for a given interface is the result of concatenting the identifier of the interface and +the string “Iterator”.
+4.6.10. Maplike declarations
+Any object that implements an interface that has a maplike declaration must have a [[BackingMap]] internal slot, which is +initially set to a newly created
+Map object. +ThisMap object’s [[MapData]] internal slot is +the object’s map entries.If an interface A is declared with +a maplike declaration, then +there exists a number of additional properties on A’s interface prototype object. +These additional properties are described in the sub-sections below.
+Some of the properties below are defined to have a function object value +that forwards to the internal map object for a given function name. Such functions behave as follows when invoked:
+-
+
-
+
Let O be the
+this value. -
+
Let arguments be the list of arguments passed to this function.
+ -
+
Let name be the function name.
+ -
+
If O is a platform object, +then perform a security check, passing:
+-
+
-
+
the platform object O,
+ -
+
the ECMAScript global environment associated with this
+Function , -
+
an identifier equal to name, and
+ -
+
the type “method”.
+
-
+
-
+
If O is not an object that implements A, then throw a
+TypeError . -
+
Let map be the
+Map object that is the value of O’s [[BackingMap]] internal slot. -
+
Let function be the result of calling the [[Get]] internal method of map passing name and map as arguments.
+ -
+
If IsCallable(function) is
+false , then throw aTypeError . -
+
Return the result of calling the [[Call]] internal method of function with map as thisArg and arguments as argumentsList.
+
4.6.10.1. size
+There must exist a property named “size” on A’s interface prototype object with the following characteristics:
+-
+
-
+
The property has attributes { [[Get]]: G, [[Enumerable]]:
+false , [[Configurable]]:true }, +where G is the interface’s map size getter, +defined below. -
+
The map size getter is +a
+Function object whose +behavior when invoked is as follows:-
+
-
+
Let O be the
+this value. -
+
If O is a platform object, +then perform a security check, passing:
+-
+
-
+
the platform object O,
+ -
+
the ECMAScript global environment associated with this
+Function , -
+
the identifier “size”, and
+ -
+
the type “getter”.
+
-
+
-
+
If O is not an object that implements A, then throw a
+TypeError . -
+
Let map be the
+Map object that is the value of O’s [[BackingMap]] internal slot. -
+
Return the result of calling the [[Get]] internal method of map passing “size” and map as arguments.
+
The value of the
+Function object’s “length” property is theNumber value0 .The value of the
+Function object’s “name” property is theString value “size”. -
+
4.6.10.2. entries
+A property named “entries” must exist on A’s interface prototype object with attributes { [[Writable]]:
+true , [[Enumerable]]:false , [[Configurable]]:true } and whose value is the function object that is the value of +the @@iterator property.4.6.10.3. keys and values
+For both of “keys” and “values”, there must exist a property with that name on A’s interface prototype object with the following characteristics:
+-
+
-
+
The property has attributes { [[Writable]]:
+true , [[Enumerable]]:false , [[Configurable]]:true }. -
+
The value of the property is a
+Function object that forwards that name to the internal map object.
The value of the
+Function objects’ “length” properties is theNumber value0 .The value of the
+Function object’s “name” property is theString value “keys” or “values”, correspondingly.4.6.10.4. get and has
+For both of “get” and “has”, there must exist a property with that name on A’s interface prototype object with the following characteristics:
+-
+
-
+
The property has attributes { [[Writable]]:
+true , [[Enumerable]]:false , [[Configurable]]:true }. -
+
The value of the property is a
+Function object that behaves as follows when invoked:-
+
-
+
Let O be the
+this value. -
+
Let name be the name of the property – “get” or “has”.
+ -
+
If O is a platform object, +then perform a security check, passing:
+-
+
-
+
the platform object O,
+ -
+
the ECMAScript global environment associated with this
+Function , -
+
an identifier equal to name, and
+ -
+
the type “method”.
+
-
+
-
+
If O is not an object that implements A, then throw a
+TypeError . -
+
Let map be the
+Map object that is the value of O’s [[BackingMap]] internal slot. -
+
Let keyType be the key type specified in the maplike declaration.
+ -
+
Let function be the result of calling the [[Get]] internal method of map passing name and map as arguments.
+ -
+
Let keyArg be the first argument passed to this function, or
+undefined if not supplied. -
+
Let keyIDL be the result of converting keyArg to an IDL value of type keyType.
+ -
+
Let key be the result of converting keyIDL to an ECMAScript value.
+ -
+
Return the result of calling the [[Call]] internal method of function with map as thisArg and the single value key as argumentsList.
+
-
+
The value of the
+Function objects’ “length” properties is theNumber value1 .The value of the
+Function object’s “name” property is theString value “get” or “has”, correspondingly.4.6.10.5. clear
+If A and A’s consequential interfaces do not declare an interface member with identifier “clear”, and A was declared with a read–write maplike declaration, +then a property named “clear” and the following characteristics +must exist on A’s interface prototype object:
+-
+
-
+
The property has attributes { [[Writable]]:
+true , [[Enumerable]]:false , [[Configurable]]:true }. -
+
The value of the property is a
+Function object that forwards “clear” to the internal map object.
The value of the
+Function object’s “length” property is theNumber value0 .The value of the
+Function object’s “name” property is theString value “clear”.4.6.10.6. delete
+If A and A’s consequential interfaces do not declare an interface member with identifier “delete”, and A was declared with a read–write maplike declaration, +then a property named “delete” and the following characteristics +must exist on A’s interface prototype object:
+-
+
-
+
The property has attributes { [[Writable]]:
+true , [[Enumerable]]:false , [[Configurable]]:true }. -
+
The value of the property is a
+Function object that behaves as follows when invoked:-
+
-
+
Let O be the
+this value. -
+
If O is a platform object, +then perform a security check, passing:
+-
+
-
+
the platform object O,
+ -
+
the ECMAScript global environment associated with this
+Function , -
+
the identifier “delete”, and
+ -
+
the type “method”.
+
-
+
-
+
If O is not an object that implements A, then throw a
+TypeError . -
+
Let map be the
+Map object that is the value of O’s [[BackingMap]] internal slot. -
+
Let keyType be the key type specified in the maplike declaration.
+ -
+
Let function be the result of calling the [[Get]] internal method of map passing “delete” and map as arguments.
+ -
+
Let keyArg be the first argument passed to this function, or
+undefined if not supplied. -
+
Let keyIDL be the result of converting keyArg to an IDL value of type keyType.
+ -
+
Let key be the result of converting keyIDL to an ECMAScript value.
+ -
+
Return the result of calling the [[Call]] internal method of function with map as thisArg and the single value key as argumentsList.
+
-
+
The value of the
+Function object’s “length” property is theNumber value1 .The value of the
+Function object’s “name” property is theString value “delete”.4.6.10.7. set
+If A and A’s consequential interfaces do not declare an interface member with identifier “set”, and A was declared with a read–write maplike declaration, +then a property named “set” and the following characteristics +must exist on A’s interface prototype object:
+-
+
-
+
The property has attributes { [[Writable]]:
+true , [[Enumerable]]:false , [[Configurable]]:true }. -
+
The value of the property is a
+Function object that behaves as follows when invoked:-
+
-
+
Let O be the
+this value. -
+
If O is a platform object, +then perform a security check, passing:
+-
+
-
+
the platform object O,
+ -
+
the ECMAScript global environment associated with this
+Function , -
+
the identifier “set”, and
+ -
+
the type “method”.
+
-
+
-
+
If O is not an object that implements A, then throw a
+TypeError . -
+
Let map be the
+Map object that is the value of O’s [[BackingMap]] internal slot. -
+
Let keyType and valueType be the key and value types specified in the maplike declaration.
+ -
+
Let function be the result of calling the [[Get]] internal method of map passing “set” and map as arguments.
+ -
+
Let keyArg be the first argument passed to this function, or
+undefined if not supplied. -
+
Let valueArg be the second argument passed to this function, or
+undefined if not supplied. -
+
Let keyIDL be the result of converting keyArg to an IDL value of type keyType.
+ -
+
Let valueIDL be the result of converting valueArg to an IDL value of type valueType.
+ -
+
Let key be the result of converting keyIDL to an ECMAScript value.
+ -
+
Let value be the result of converting valueIDL to an ECMAScript value.
+ -
+
Let result be the result of calling the [[Call]] internal method of function with map as thisArg and key and value as argumentsList.
+ -
+
Assert: result is not an abrupt completion.
+ -
+
Return O.
+
-
+
The value of the
+Function object’s “length” property is theNumber value2 .The value of the
+Function object’s “name” property is theString value “set”.4.6.11. Setlike declarations
+Any object that implements an interface that has a setlike declaration must have a [[BackingSet]] internal slot, which is +initially set to a newly created
+Set object. +ThisSet object’s [[SetData]] internal slot is +the object’s set entries.If an interface A is declared with +a setlike declaration, then +there exists a number of additional properties on A’s interface prototype object. +These additional properties are described in the sub-sections below.
+Some of the properties below are defined to have a function object value +that forwards to the internal set object for a given function name. Such functions behave as follows when invoked:
+-
+
-
+
Let O be the
+this value. -
+
Let arguments be the list of arguments passed to this function.
+ -
+
Let name be the function name.
+ -
+
If O is a platform object, +then perform a security check, passing:
+-
+
-
+
the platform object O,
+ -
+
the ECMAScript global environment associated with this
+Function , -
+
an identifier equal to name, and
+ -
+
the type “method”.
+
-
+
-
+
If O is not an object that implements A, then throw a
+TypeError . -
+
Let set be the
+Set object that is the value of O’s [[BackingSet]] internal slot. -
+
Let function be the result of calling the [[Get]] internal method of set passing name and set as arguments.
+ -
+
If IsCallable(function) is
+false , then throw aTypeError . -
+
Return the result of calling the [[Call]] internal method of function with set as thisArg and arguments as argumentsList.
+
4.6.11.1. size
+There must exist a property named “size” on A’s interface prototype object with the following characteristics:
+-
+
-
+
The property has attributes { [[Get]]: G, [[Enumerable]]:
+false , [[Configurable]]:true }, +where G is the interface’s set size getter, +defined below. -
+
The set size getter is +a
+Function object whose +behavior when invoked is as follows:-
+
-
+
Let O be the
+this value. -
+
If O is a platform object, +then perform a security check, passing:
+-
+
-
+
the platform object O,
+ -
+
the ECMAScript global environment associated with this
+Function , -
+
the identifier “size”, and
+ -
+
the type “getter”.
+
-
+
-
+
If O is not an object that implements A, then throw a
+TypeError . -
+
Let set be the
+Set object that is the value of O’s [[BackingSet]] internal slot. -
+
Return the result of calling the [[Get]] internal method of set passing “size” and set as arguments.
+
The value of the
+Function object’s “length” property is theNumber value0 .The value of the
+Function object’s “name” property is theString value “size”. -
+
4.6.11.2. values
+A property named “values” must exist on A’s interface prototype object with attributes { [[Writable]]:
+true , [[Enumerable]]:false , [[Configurable]]:true } and whose value is the function object that is the value of +the @@iterator property.4.6.11.3. entries and keys
+For both of “entries” and “keys”, there must exist a property with that name on A’s interface prototype object with the following characteristics:
+-
+
-
+
The property has attributes { [[Writable]]:
+true , [[Enumerable]]:false , [[Configurable]]:true }. -
+
The value of the property is a
+Function object that forwards that name to the internal set object.
The value of the
+Function objects’ “length” properties is theNumber value0 .The value of the
+Function object’s “name” property is theString value “entries” or “keys”, correspondingly.4.6.11.4. has
+There must exist a property with named “has” on A’s interface prototype object with the following characteristics:
+-
+
-
+
The property has attributes { [[Writable]]:
+true , [[Enumerable]]:false , [[Configurable]]:true }. -
+
The value of the property is a
+Function object that behaves as follows when invoked:-
+
-
+
Let O be the
+this value. -
+
If O is a platform object, +then perform a security check, passing:
+-
+
-
+
the platform object O,
+ -
+
the ECMAScript global environment associated with this
+Function , -
+
the identifier “has”, and
+ -
+
the type “method”.
+
-
+
-
+
If O is not an object that implements A, then throw a
+TypeError . -
+
Let set be the
+Set object that is the value of O’s [[BackingSet]] internal slot. -
+
Let type be the value type specified in the setlike declaration.
+ -
+
Let function be the result of calling the [[Get]] internal method of set passing “has” and set as arguments.
+ -
+
Let arg be the first argument passed to this function, or
+undefined if not supplied. -
+
Let idlValue be the result of converting arg to an IDL value of type type.
+ -
+
Let value be the result of converting idlValue to an ECMAScript value.
+ -
+
Return the result of calling the [[Call]] internal method of function with set as thisArg and the single value value as argumentsList.
+
-
+
The value of the
+Function object’s “length” property is aNumber value1 .The value of the
+Function object’s “name” property is theString value “has”.4.6.11.5. add and delete
+For both of “add” and “delete”, if:
+-
+
-
+
A and A’s consequential interfaces do not declare an interface member with a matching identifier, and
+ -
+
A was declared with a read–write setlike declaration,
+
then a property with that name and the following characteristics +must exist on A’s interface prototype object:
+-
+
-
+
The property has attributes { [[Writable]]:
+true , [[Enumerable]]:false , [[Configurable]]:true }. -
+
The value of the property is a
+Function object that behaves as follows when invoked:-
+
-
+
Let O be the
+this value. -
+
Let name be the name of the property – “add” or “delete”.
+ -
+
If O is a platform object, +then perform a security check, passing:
+-
+
-
+
the platform object O,
+ -
+
the ECMAScript global environment associated with this
+Function , -
+
an identifier equal to name, and
+ -
+
the type “method”.
+
-
+
-
+
If O is not an object that implements A, then throw a
+TypeError . -
+
Let set be the
+Set object that is the value of O’s [[BackingSet]] internal slot. -
+
Let type be the value type specified in the setlike declaration.
+ -
+
Let function be the result of calling the [[Get]] internal method of set passing name and set as arguments.
+ -
+
Let arg be the first argument passed to this function, or
+undefined if not supplied. -
+
Let idlValue be the result of converting arg to an IDL value of type type.
+ -
+
Let value be the result of converting idlValue to an ECMAScript value.
+ -
+
Let result be the result of calling the [[Call]] internal method of function with set as thisArg and the single value value as argumentsList.
+ -
+
Assert: result is not an abrupt completion.
+ -
+
If name is "delete", then:
+-
+
-
+
Return result.
+
-
+
-
+
Otherwise:
+-
+
-
+
Return O.
+
-
+
-
+
The value of the
+Function object’s “length” property is theNumber value1 .The value of the
+Function object’s “name” property is theString value “add” or “delete”, correspondingly.4.6.11.6. clear
+If A and A’s consequential interfaces do not declare an interface member with a matching identifier, and A was declared with a read–write setlike declaration, +then a property named “clear” and the following characteristics +must exist on A’s interface prototype object:
+-
+
-
+
The property has attributes { [[Writable]]:
+true , [[Enumerable]]:false , [[Configurable]]:true }. -
+
The value of the property is a
+Function object that forwards “clear” to the internal set object.
The value of the
+Function object’s “length” property is theNumber value0 .The value of the
+Function object’s “name” property is theString value “clear”.4.6.12. Initializing objects from iterables
+Some objects, which are attempting to emulate map- and set-like interfaces, will want to accept iterables +as constructor parameters and initialize themselves in this way. Here we provide some algorithms that can +be invoked in order to do so in the same way as in the ECMAScript spec, so that those objects behave +the same as the built-in
+Map andSet objects.To add map elements from an iterable iterable to +an object destination with adder method name adder, perform the following steps:
+-
+
-
+
If Type(destination) is not Object, then, throw a
+TypeError . -
+
If iterable is not present, let iterable be
+undefined . -
+
If iterable is either
+undefined ornull , then let iter beundefined . -
+
Else,
+-
+
-
+
Let adder be the result of Get(destination, adder).
+ -
+
ReturnIfAbrupt(adder).
+ -
+
If IsCallable(adder) is
+false , throw aTypeError . -
+
Let iter be the result of GetIterator(iterable).
+ -
+
ReturnIfAbrupt(iter).
+
-
+
-
+
If iter is
+undefined , then return. -
+
Repeat
+-
+
-
+
Let next be the result of IteratorStep(iter).
+ -
+
ReturnIfAbrupt(next).
+ -
+
If next is
+false , then return NormalCompletion(destination). -
+
Let nextItem be IteratorValue(next).
+ -
+
ReturnIfAbrupt(nextItem).
+ -
+
If Type(nextItem) is not Object, then throw a
+TypeError . -
+
Let k be the result of Get(nextItem,
+"0"). -
+
ReturnIfAbrupt(k).
+ -
+
Let v be the result of Get(nextItem,
+"1"). -
+
ReturnIfAbrupt(v).
+ -
+
Let status be the result of calling the [[Call]] internal method of adder with destination as thisArgument and (k, v) as argumentsList.
+ -
+
ReturnIfAbrupt(status).
+
-
+
4.7. Implements statements
+The interface prototype object of an interface A must have a copy of +each property that corresponds to one of the constants, attributes, operations, iterable declarations, maplike declarations and setlike declarations that exist on all of the interface prototype objects of A’s consequential interfaces. +For operations, where the property is a data property with a
+Function object value, each copy of the property must have +distinctFunction objects. For attributes, each +copy of the accessor property must have +distinctFunction objects for their getters, +and similarly with their setters.++When invoking an operation by calling + a
+Function object that is the value of one of the copies that exists + due to an implements statement, thethis value is + checked to ensure that it is an object that implements the interface corresponding to the interface prototype object that the property is on.For example, consider the following IDL:
+interface A { + void f(); +}; + +interface B { }; +B implements A; + +interface C { }; +C implements A; +
+Attempting to call
+B.prototype.fon an object that implementsA(but notB) or one + that implementsCwill result in aTypeErrorbeing thrown. However, + callingA.prototype.fon an object that implementsBor one that implementsCwould succeed. This is handled by the algorithm in §4.6.7 Operations that defines how IDL operation invocation works in ECMAScript.Similar behavior is required for the getter and setter
+Function objects that correspond to an IDL attributes, + and this is handled in §4.6.6 Attributes.4.8. Platform objects implementing interfaces
+Every platform object is associated with a global environment, just +as the initial objects are. +It is the responsibility of specifications using Web IDL to state +which global environment (or, by proxy, which global object) each platform +object is associated with.
+The primary interface of a platform object +that implements one or more interfaces is the most-derived non-supplemental interface that it implements. The value of the internal [[Prototype]] +property of the platform object is the interface prototype object of the primary interface from the platform object’s associated global environment.
+The global environment that a given platform object is associated with can change after it has been created. When +the global environment associated with a platform object is changed, its internal +[[Prototype]] property must be immediately +updated to be the interface prototype object of the primary interface from the platform object’s newly associated global environment.
+Every platform object that implements an [
+Unforgeable]-annotated +interface and which does not have a stringifier that is unforgeable on any of the +interfaces it implements must have a property with the +following characteristics:-
+
-
+
The name of the property is “toString”.
+ -
+
The property has attributes { [[Writable]]:
+false , [[Enumerable]]:true , [[Configurable]]:false }. -
+
The value of the property is %ObjProto_toString%, the initial value of Object.prototype.toString.
+
Every platform object that implements an [
+Unforgeable]-annotated +interface and which does not have a serializer that is unforgeable on any of the +interfaces it implements must have a property with the +following characteristics:-
+
-
+
The name of the property is “toJSON”.
+ -
+
The property has attributes { [[Writable]]:
+false , [[Enumerable]]:true , [[Configurable]]:false }. -
+
The value of the property is
+undefined .
Every platform object that implements an [
+Unforgeable]-annotated +interface must have a property with the +following characteristics:-
+
-
+
The name of the property is “valueOf”.
+ -
+
The property has attributes { [[Writable]]:
+false , [[Enumerable]]:true , [[Configurable]]:false }. -
+
The value of the property is a
+Function object whose behavior +is as follows:-
+
-
+
Return the
+this value.
This
+Function object is the default unforgeable valueOf function. -
+
-
+
The value of the
+Function object’s “length” +property is theNumber value0 . -
+
The value of the
+Function object’s “name” property is theString value “valueOf”.
The class string of +a platform object that implements one or more interfaces +must be the identifier of +the primary interface of the platform object.
+4.8.1. Indexed and named properties
+If a platform object implements an interface that supports indexed or named properties, +the object will appear to have additional properties that correspond to the +object’s indexed and named properties. These properties are not “real” own +properties on the object, but are made to look like they are by being exposed +by the [[GetOwnProperty]] internal method.
+However, when the [
+Global] or +[PrimaryGlobal] extended attribute has been used, +named properties are not exposed on the object but on another object +in the prototype chain, the named properties object.It is permissible for an object to implement multiple interfaces that support indexed properties. +However, if so, and there are conflicting definitions as to the object’s supported property indices, +or if one of the interfaces is a supplemental interface for the +platform object, then it is undefined what additional properties the object will appear to +have, or what its exact behavior will be with regard to its indexed properties. +The same applies for named properties.
+The indexed property getter that is defined on the derived-most interface that the +platform object implements is the one that defines the behavior +when indexing the object with an array index. Similarly for indexed property setters. +This way, the definitions of these special operations from +ancestor interfaces can be overridden.
+Platform objects implementing an interface that supports indexed or named properties cannot be fixed; if
+Object.freeze,Object.sealorObject.preventExtensionsis called on one of these objects, the function +must throw aTypeError . +Similarly, an interface prototype object that exposes named properties due to the use of [Global] or +[PrimaryGlobal] +also must throw aTypeError if one of the three functions above is called on it.The name of each property that appears to exist due to an object supporting indexed properties +is an array index property name, which is a property +name P such that Type(P) is String +and for which the following algorithm returns
+true :-
+
-
+
Let i be ToUint32(P).
+ -
+
Let s be ToString(i).
+ -
+
If s ≠ P or i = 232 − 1, then return
+false . -
+
Return
+true .
A property name is an unforgeable property name on a +given platform object if the object implements an interface that +has an interface member with that identifier +and that interface member is unforgeable on any of +the interfaces that O implements. If the object implements an +[
+Unforgeable]-annotated interface, then “toString” and “valueOf” are +also unforgeable property names on that object.The named property visibility algorithm is used to determine if +a given named property is exposed on an object. Some named properties are not exposed on an object +depending on whether the [
+OverrideBuiltins] extended attribute was used. The algorithm +operates as follows, with property name P and object O:-
+
-
+
If P is an unforgeable property name on O, then return false.
+ -
+
If O implements an interface with +an [
+Unforgeable]-annotated attribute whose identifier is P, then return false. -
+
If P is not a supported property name of O, then return false.
+ -
+
If O implements an interface that has the [
+OverrideBuiltins] extended attribute, then return true. -
+
If O has an own property named P, then return false.
+ -
+
Initialize prototype to be the value of the internal [[Prototype]] property of O.
+ -
+
While prototype is not null:
+-
+
-
+
If prototype is not a named properties object, +and prototype has an own property named P, then return false.
+ -
+
Set prototype to be the value of the internal [[Prototype]] property of prototype.
+
-
+
-
+
Return true.
+
++This should ensure that for objects with named properties, property resolution is done in the following order:
+-
+
-
+
Indexed properties.
+ -
+
Unforgeable attributes and operations.
+ -
+
Then, if [
+OverrideBuiltins]:-
+
-
+
Named properties.
+ -
+
Own properties.
+ -
+
Properties from the prototype chain.
+
-
+
-
+
Otherwise, if not [
+OverrideBuiltins]:-
+
-
+
Own properties.
+ -
+
Properties from the prototype chain.
+ -
+
Named properties.
+
-
+
Support for getters is +handled by the platform object [[GetOwnProperty]] method defined in section §4.8.3 Platform object [[GetOwnProperty]] method, and +for setters by the platform object [[DefineOwnProperty]] method defined in section §4.8.7 Platform object [[DefineOwnProperty]] method and the platform object [[Set]] method defined in section §4.8.6 Platform object [[Set]] method.
+4.8.2. The PlatformObjectGetOwnProperty abstract operation
+The PlatformObjectGetOwnProperty +abstract operation performs the following steps when called with an +object O, a property name P, and a boolean ignoreNamedProps value:
+-
+
-
+
If O supports indexed properties and P is an array index property name, then:
+-
+
-
+
Let index be the result of calling ToUint32(P).
+ -
+
If index is a supported property index, then:
+-
+
-
+
Let operation be the operation used to declare the indexed property getter.
+ -
+
Let value be an uninitialized variable.
+ -
+
If operation was defined without an identifier, then +set value to the result of performing the steps listed in the interface description to determine the value of an indexed property with index as the index.
+ -
+
Otherwise, operation was defined with an identifier. Set value to the result +of performing the steps listed in the description of operation with index as the only argument value.
+ -
+
Let desc be a newly created Property Descriptor with no fields.
+ -
+
Set desc.[[Value]] to the result of converting value to an ECMAScript value.
+ -
+
If O implements an interface with an indexed property setter, then set desc.[[Writable]] to
+true , otherwise set it tofalse . -
+
Set desc.[[Enumerable]] and desc.[[Configurable]] to
+true . -
+
Return desc.
+
-
+
-
+
Set ignoreNamedProps to true.
+
-
+
-
+
If O supports named properties, O does not +implement an interface with the [
+Global] or [PrimaryGlobal] extended attribute, the result of running the named property visibility algorithm with +property name P and object O is true, and ignoreNamedProps is false, then:-
+
-
+
Let operation be the operation used to declare the named property getter.
+ -
+
Let value be an uninitialized variable.
+ -
+
If operation was defined without an identifier, then +set value to the result of performing the steps listed in the interface description to determine the value of a named property with P as the name.
+ -
+
Otherwise, operation was defined with an identifier. Set value to the result +of performing the steps listed in the description of operation with P as the only argument value.
+ -
+
Let desc be a newly created Property Descriptor with no fields.
+ -
+
Set desc.[[Value]] to the result of converting value to an ECMAScript value.
+ -
+
If O implements an interface with a named property setter, then set desc.[[Writable]] to
+true , otherwise set it tofalse . -
+
If O implements an interface with the +[
+LegacyUnenumerableNamedProperties] extended attribute, +then set desc.[[Enumerable]] tofalse , +otherwise set it totrue . -
+
Set desc.[[Configurable]] to
+true . -
+
Return desc.
+
-
+
-
+
Return OrdinaryGetOwnProperty(O, P).
+
4.8.3. Platform object [[GetOwnProperty]] method
+The internal [[GetOwnProperty]] method of every platform object O that implements an interface which supports indexed or named properties must behave as follows when called with property name P:
+-
+
-
+
Return the result of invoking the PlatformObjectGetOwnProperty abstract operation with O, P, and
+false as +arguments.
4.8.4. Invoking a platform object indexed property setter
+To invoke an indexed property setter with property name P and ECMAScript value V, the following steps must be performed:
+-
+
-
+
Let index be the result of calling ToUint32(P).
+ -
+
Let creating be true if index is not a supported property index, and false otherwise.
+ -
+
Let operation be the operation used to declare the indexed property setter.
+ -
+
Let T be the type of the second argument of operation.
+ -
+
Let value be the result of converting V to an IDL value of type T.
+ -
+
If operation was defined without an identifier, then:
+-
+
-
+
If creating is true, then perform the steps listed in the interface description to set the value of a new indexed property with index as the index and value as the value.
+ -
+
Otherwise, creating is false. Perform the steps listed in the interface description to set the value of an existing indexed property with index as the index and value as the value.
+
-
+
-
+
Otherwise, operation was defined with an identifier. Perform the steps listed in the description of operation with index and value as the two argument values.
+
4.8.5. Invoking a platform object named property setter
+To invoke a named property setter with property name P and ECMAScript value V, the following steps must be performed:
+-
+
-
+
Let creating be true if P is not a supported property name, and false otherwise.
+ -
+
Let operation be the operation used to declare the named property setter.
+ -
+
Let T be the type of the second argument of operation.
+ -
+
Let value be the result of converting V to an IDL value of type T.
+ -
+
If operation was defined without an identifier, then:
+-
+
-
+
If creating is true, then perform the steps listed in the interface description to set the value of a new named property with P as the name and value as the value.
+ -
+
Otherwise, creating is false. Perform the steps listed in the interface description to set the value of an existing named property with P as the name and value as the value.
+
-
+
-
+
Otherwise, operation was defined with an identifier. Perform the steps listed in the description of operation with index and value as the two argument values.
+
4.8.6. Platform object [[Set]] method
+The internal [[Set]] method of every platform object O that implements an interface which supports indexed or named properties must behave as follows when called +with property name P, value V, and +ECMAScript language value Receiver:
+-
+
-
+
If O and Receiver are the same object, +then:
+-
+
-
+
If O supports indexed properties, P is an array index property name, and O implements an interface with an indexed property setter, then:
+-
+
-
+
Invoke the indexed +property setter with P and V.
+ -
+
Return
+true .
-
+
-
+
If O supports named properties, Type(P) is String, P is not an array index property name, and O implements an interface with a named property setter, then:
+-
+
-
+
Invoke the named +property setter with P and V.
+ -
+
Return
+true .
-
+
-
+
-
+
Let ownDesc be the result of invoking the PlatformObjectGetOwnProperty abstract operation with O, P, and
+true as +arguments. -
+
Perform steps 3-11 of the default [[Set]] internal method.
+
4.8.7. Platform object [[DefineOwnProperty]] method
+When the internal [[DefineOwnProperty]] method of a platform object O that +implements an interface which supports indexed or named properties is +called with property key P and Property Descriptor Desc, the following steps must be taken:
+-
+
-
+
If O supports indexed properties and P is an array index property name, then:
+-
+
-
+
If the result of calling IsDataDescriptor(Desc) is
+false , then returnfalse . -
+
If O does not implement an interface with an indexed property setter, then return
+false . -
+
Invoke the indexed property setter with P and Desc.[[Value]].
+ -
+
Return
+true .
-
+
-
+
If O supports named properties, O does not implement an interface with the +[
+Global] or [PrimaryGlobal] extended attribute and P is not an unforgeable property name of O, then:-
+
-
+
Let creating be true if P is not a supported property name, and false otherwise.
+ -
+
If O implements an interface with the [
+OverrideBuiltins] extended attribute or O does not have an own property +named P, then:-
+
-
+
If creating is false and O does not implement an +interface with a named property setter, then return
+false . -
+
If O implements an interface with a named property setter, then:
+-
+
-
+
If the result of calling IsDataDescriptor(Desc) is
+false , then returnfalse . -
+
Invoke the named property setter with P and Desc.[[Value]].
+ -
+
Return
+true .
-
+
-
+
-
+
-
+
If O does not implement an interface with the +[
+Global] or +[PrimaryGlobal] extended attribute, then set Desc.[[Configurable]] totrue . -
+
Return OrdinaryDefineOwnProperty(O, P, Desc).
+
4.8.8. Platform object [[Delete]] method
+The internal [[Delete]] method of every platform object O that implements an interface which supports indexed or named properties must behave as follows when called with property name P.
+-
+
-
+
If O supports indexed properties and P is an array index property name, then:
+-
+
-
+
Let index be the result of calling ToUint32(P).
+ -
+
If index is not a supported property index, then return
+true . -
+
Return
+false .
-
+
-
+
If O supports named properties, O does not implement an interface with the +[
+Global] or [PrimaryGlobal] extended attribute and the result of calling the named property visibility algorithm with property name P and object O is true, then:-
+
-
+
If O does not implement an interface with a named property deleter, then return
+false . -
+
Let operation be the operation used to declare the named property deleter.
+ -
+
If operation was defined without an identifier, then:
+-
+
-
+
Perform the steps listed in the interface description to delete an existing named property with P as the name.
+ -
+
If the steps indicated that the deletion failed, then return
+false .
-
+
-
+
Otherwise, operation was defined with an identifier:
+-
+
-
+
Perform the steps listed in the description of operation with P as the only argument value.
+ -
+
If operation was declared with a return type of
+booleanand the steps returnedfalse , then returnfalse .
-
+
-
+
Return
+true .
-
+
-
+
If O has an own property with name P, then:
+-
+
-
+
If the property is not configurable, then return
+false . -
+
Otherwise, remove the property from O.
+
-
+
-
+
Return
+true .
4.8.9. Platform object [[Call]] method
+The internal [[Call]] method of every platform object O that implements an interface I with at least one legacy caller must behave as follows, assuming arg0..n−1 is the list of argument +values passed to [[Call]]:
+-
+
-
+
Initialize S to the effective overload set for legacy callers on I and with argument count n.
+ -
+
Let <operation, values> be the result of passing S and arg0..n−1 to the overload resolution algorithm.
+ -
+
Perform the actions listed in the description of the legacy caller operation with values as the argument values.
+ -
+
Return the result of converting the return value from those actions to an ECMAScript value of the type operation is declared to return (or
+undefined if operation is declared to returnvoid).
4.8.10. Property enumeration
+This document does not define a complete property enumeration order +for all platform objects implementing interfaces (or for platform objects representing exceptions). +However, if a platform object implements an interface that supports indexed or named properties, then +properties on the object must be +enumerated in the following order:
+-
+
-
+
If the object supports indexed properties, then +the object’s supported property indices are +enumerated first, in numerical order.
+ -
+
If the object supports named properties and doesn’t implement an interface with the +[
+LegacyUnenumerableNamedProperties] extended attribute, then +the object’s supported property names that +are visible according to the named property visibility algorithm are enumerated next, in the order given in the definition of the set of supported property names. -
+
Finally, any enumerable own properties or properties from the object’s prototype chain are then enumerated, +in no defined order.
+
Note: Future versions of the ECMAScript specification may define a total order for property enumeration.
+4.9. User objects implementing callback interfaces
+As described in §3.10 Objects implementing interfaces, callback interfaces can be +implemented in script by an ECMAScript object. +The following cases determine whether and how a given object +is considered to be a user object implementing a callback interface:
+-
+
-
+
If the interface is a single operation callback interface (defined below) then any object apart from a native
+RegExp object is considered to implement the interface. +The implementation of the operation (or set of overloaded operations) is +as follows:-
+
-
+
If the object is callable, +then the implementation of the operation (or set of overloaded operations) is +the callable object itself.
+ -
+
Otherwise, the object is not callable. +The implementation of the operation (or set of overloaded operations) is +the result of invoking the internal [[Get]] method +on the object with a property name that is the identifier of the operation.
+
-
+
-
+
Otherwise, the interface is not a single operation callback interface. +Any object that is not a native
+RegExp object is considered to implement the interface. +For each operation declared on the interface with a given identifier, the implementation +is the result of invoking [[Get]] on the object with a +property name that is that identifier.
Note that ECMAScript objects need not have +properties corresponding to constants on them to be considered as user objects implementing interfaces that happen +to have constants declared on them.
+A single operation callback interface is +a callback interface that:
+-
+
-
+
is not declared to inherit from another interface,
+ -
+
has no attributes, and
+ -
+
has one or more regular operations that all have the same identifier, +and no others.
+
To call a user object’s operation, given a callback interface type value value, sometimes-optional operation name opName, +list of argument values arg0..n−1 each of which is +either an IDL value or the special value “missing” (representing a missing optional +argument), and optional callback this value thisArg, perform the following steps. These steps will either +return an IDL value or throw an exception.
+-
+
-
+
Let completion be an uninitialized variable.
+ -
+
If thisArg was not given, let thisArg be
+undefined . -
+
Let O be the ECMAScript object corresponding to value.
+ -
+
Let realm be O’s associated Realm.
+ -
+
Let relevant settings be realm’s settings object.
+ -
+
Let stored settings be value’s callback context.
+ -
+
Prepare to run script with relevant settings.
+ -
+
Prepare to run a callback with stored settings.
+ -
+
Determine the implementation of the operation, X:
+-
+
-
+
If value’s interface is a single operation callback interface and ! IsCallable(O) is true, then set X to O.
+ -
+
Otherwise, opName must be supplied:
+ +
-
+
-
+
If ! IsCallable(X) is
+false , +then set completion to a new Completion{[[Type]]: throw, [[Value]]: a +newly createdTypeError object, [[Target]]: empty}, and jump +to the step labeled return. -
+
If value’s interface is not a single operation callback interface, +or if ! IsCallable(O) is
+false , +set thisArg to O (overriding the provided value). -
+
Let esArgs be an empty List of ECMAScript values.
+ -
+
Let i be 0.
+ -
+
Let count be 0.
+ -
+
While i < n:
+-
+
-
+
If argi is the special value “missing”, then +append
+undefined to esArgs. -
+
Otherwise, argi is an IDL value:
+-
+
-
+
Let convertResult be the result of converting argi to an ECMAScript value.
+ -
+
If convertResult is an abrupt completion, set completion to convertResult and jump to the step labeled return.
+ -
+
Append convertResult.[[Value]] to esArgs.
+ -
+
Set count to i + 1.
+
-
+
-
+
Set i to i + 1.
+
-
+
-
+
Truncate esArgs to have length count.
+ -
+
Let callResult be Call(X, thisArg, esArgs).
+ -
+
If callResult is an abrupt completion, set completion to callResult and jump to the step labeled return.
+ -
+
Set completion to the result of converting callResult.[[Value]] to an IDL value of the same type as the operation’s +return type.
+ -
+
Return: at this +point completion will be set to an ECMAScript completion value.
+-
+
-
+
Clean up after running a callback with stored settings.
+ -
+
Clean up after running script with relevant settings.
+ -
+
If completion is a normal completion, return completion.
+ -
+
If completion is an abrupt completion and the operation has a return type that is not a promise type, return completion.
+ -
+
Let reject be the initial value of %Promise%.reject.
+ -
+
Let rejectedPromise be the result of calling reject with %Promise% as the
+this value and completion.[[Value]] as the single argument value. -
+
Return the result of converting rejectedPromise to the operation’s return type.
+
-
+
To get a user object’s attribute value, given a callback interface type value object and attribute name attributeName, +perform the following steps. These steps will either return an IDL value or throw an +exception.
+-
+
-
+
Let completion be an uninitialized variable.
+ -
+
Let O be the ECMAScript object corresponding to object.
+ -
+
Let realm be O’s associated Realm.
+ -
+
Let relevant settings be realm’s settings object.
+ -
+
Let stored settings be object’s callback context.
+ -
+
Prepare to run script with relevant settings.
+ -
+
Prepare to run a callback with stored settings.
+ -
+
Let getResult be Get(O, attributeName).
+ -
+
If getResult is an abrupt completion, set completion to getResult and jump to the step labeled return.
+ -
+
Set completion to the result of converting getResult.[[Value]] to an IDL value of the same type as the attribute’s +type.
+ -
+
Return: at this +point completion will be set to an ECMAScript completion value.
+-
+
-
+
Clean up after running a callback with stored settings.
+ -
+
Clean up after running script with relevant settings.
+ -
+
If completion is a normal completion, return completion.
+ -
+
If completion is an abrupt completion and the attribute’s type is not a promise type, return completion.
+ -
+
Let reject be the initial value of %Promise%.reject.
+ -
+
Let rejectedPromise be the result of calling reject with %Promise% as the
+this value and completion.[[Value]] as the single argument value. -
+
Return the result of converting rejectedPromise to the attribute’s type.
+
-
+
To set a user object’s attribute value, given a callback interface type value object, attribute name attributeName, and +IDL value value, perform the following steps. These steps will not return +anything, but could throw an exception.
+-
+
-
+
Let completion be an uninitialized variable.
+ -
+
Let O be the ECMAScript object corresponding to object.
+ -
+
Let realm be O’s associated Realm.
+ -
+
Let relevant settings be realm’s settings object.
+ -
+
Let stored settings be object’s callback context.
+ -
+
Prepare to run script with relevant settings.
+ -
+
Prepare to run a callback with stored settings.
+ -
+
Let convertResult be the result of converting value to an +ECMAScript value.
+ -
+
If convertResult is an abrupt completion, set completion to convertResult and jump to the step labeled return.
+ -
+
Set completion to Set(O, attributeName, convertResult.[[Value]],
+true ). -
+
Return: at this +point completion will be set to an ECMAScript completion value, which is +either an abrupt completion or a normal completion for the value
+true (as returned by Set).-
+
-
+
Clean up after running a callback with stored settings.
+ -
+
Clean up after running script with relevant settings.
+ -
+
If completion is an abrupt completion, return completion.
+ -
+
Return NormalCompletion(
+void).
-
+
4.10. Invoking callback functions
+An ECMAScript callable object that is being +used as a callback function value is +called in a manner similar to how operations on user objects are called (as +described in the previous section).
+To invoke a callback function type value callable with +a list of arguments arg0..n−1, each of which is either +an IDL value or the special value “missing” (representing a missing optional argument), +and with optional callback this value thisArg, perform the following steps. These steps will either +return an IDL value or throw an exception.
+-
+
-
+
Let completion be an uninitialized variable.
+ -
+
If thisArg was not given, let thisArg be
+undefined . -
+
Let F be the ECMAScript object corresponding to value.
+ -
+
If ! IsCallable(F) is
+false :-
+
-
+
If the callback function’s return type is
+void, +return.Note: This is only possible when the callback function came from an attribute +marked with [
+TreatNonObjectAsNull]. -
+
Return the result of converting
+undefined to the callback function’s return type.
-
+
-
+
Let realm be F’s associated Realm.
+ -
+
Let relevant settings be realm’s settings object.
+ -
+
Let stored settings be callable’s callback context.
+ -
+
Prepare to run script with relevant settings.
+ -
+
Prepare to run a callback with stored settings.
+ -
+
Let esArgs be an empty List of ECMAScript values.
+ -
+
Let i be 0.
+ -
+
Let count be 0.
+ -
+
While i < n:
+-
+
-
+
If argi is the special value “missing”, then +append
+undefined to esArgs. -
+
Otherwise, argi is an IDL value:
+-
+
-
+
Let convertResult be the result of converting argi to an ECMAScript value.
+ -
+
If convertResult is an abrupt completion, set completion to convertResult and jump to the step labeled return.
+ -
+
Append convertResult.[[Value]] to esArgs.
+ -
+
Set count to i + 1.
+
-
+
-
+
Set i to i + 1.
+
-
+
-
+
Truncate esArgs to have length count.
+ -
+
Let callResult be Call(X, thisArg, esArgs).
+ -
+
If callResult is an abrupt completion, set completion to callResult and jump to the step labeled return.
+ -
+
Set completion to the result of converting callResult.[[Value]] to an IDL value of the same type as the operation’s +return type.
+ -
+
Return: at this +point completion will be set to an ECMAScript completion value.
+-
+
-
+
Clean up after running a callback with stored settings.
+ -
+
Clean up after running script with relevant settings.
+ -
+
If completion is a normal completion, return completion.
+ -
+
If completion is an abrupt completion and the callback function has a return type that is not a promise type, return completion.
+ -
+
Let reject be the initial value of %Promise%.reject.
+ -
+
Let rejectedPromise be the result of calling reject with %Promise% as the
+this value and completion.[[Value]] as the single argument value. -
+
Return the result of converting rejectedPromise to the callback function’s return type.
+
-
+
4.11. Namespaces
+For every namespace that is exposed in a given ECMAScript global environment, +a corresponding property must exist on the ECMAScript +environment’s global object. The name of the property is the identifier of the namespace, and its value is an object +called the namespace object.
+The property has the attributes { [[Writable]]:
+true , [[Enumerable]]:false , +[[Configurable]]:true }. The characteristics of a +namespace object are described in §4.11.1 Namespace object.4.11.1. Namespace object
+The namespace object for a given namespace namespace and Realm realm is created as +follows:
+-
+
-
+
Let namespaceObject be ! ObjectCreate(the %ObjectPrototype% of realm).
+ -
+
For each exposed regular operation op that is a namespace member of this namespace,
+-
+
-
+
Let F be the result of creating an operation function given op, namespace, and realm.
+ -
+
Perform ! CreateDataProperty(namespaceObject, op’s identifier, F).
+
-
+
4.12. Exceptions
+There must exist a property on the ECMAScript global object +whose name is “DOMException” and value is an object called the DOMException constructor object, +which provides access to legacy DOMException code constants and allows construction of +DOMException instances. +The property has the attributes { [[Writable]]:
+true , [[Enumerable]]:false , [[Configurable]]:true }.4.12.1. DOMException constructor object
+The DOMException constructor object must be a function object but with a [[Prototype]] value of %Error%.
+For every legacy code listed in the error names table, +there must be a property on the DOMException constructor object +whose name and value are as indicated in the table. The property has +attributes { [[Writable]]:
+false , [[Enumerable]]:true , [[Configurable]]:false }.The DOMException constructor object must also have a property named +“prototype” with attributes { [[Writable]]:
+false , [[Enumerable]]:false , [[Configurable]]:false } whose value is an object called the DOMException prototype object. +This object also provides access to the legacy code values.4.12.1.1. DOMException(message, name)
+When the DOMException function is called with arguments message and name, the following steps are taken:
+-
+
-
+
Let F be the active function object.
+ -
+
If NewTarget is
+undefined , let newTarget be F, else let newTarget be NewTarget. -
+
Let super be F.[[GetPrototypeOf]]().
+ -
+
ReturnIfAbrupt(super).
+ -
+
If IsConstructor(super) is
+false , throw aTypeError exception. -
+
Let O be Construct(super, «message», newTarget).
+ -
+
If name is not
+undefined , then-
+
-
+
Let name be ToString(name).
+ -
+
Let status be DefinePropertyOrThrow(O,
+"name", PropertyDescriptor{[[Value]]: name, [[Writable]]:true , [[Enumerable]]:false , [[Configurable]]:true }). -
+
ReturnIfAbrupt(status).
+ -
+
Let code be the legacy code indicated in the error names table for error name name, or
+0 if there is none. -
+
Let status be DefinePropertyOrThrow(O,
+"code", PropertyDescriptor{[[Value]]: code, [[Writable]]:true , [[Enumerable]]:false , [[Configurable]]:true }). -
+
ReturnIfAbrupt(status).
+
-
+
-
+
Return O.
+
4.12.2. DOMException prototype object
+The DOMException prototype object must +have an internal [[Prototype]] property whose value is %ErrorPrototype%.
+The class string of the DOMException prototype object is “DOMExceptionPrototype”.
+There must be a property named “constructor” +on the DOMException prototype object with attributes { [[Writable]]:
+true , [[Enumerable]]:false , [[Configurable]]:true } and whose value is the DOMException constructor object.For every legacy code listed in the error names table, +there must be a property on the DOMException prototype object +whose name and value are as indicated in the table. The property has +attributes { [[Writable]]:
+false , [[Enumerable]]:true , [[Configurable]]:false }.4.13. Exception objects
+Simple exceptions are represented +by native ECMAScript objects of the corresponding type.
+
+DOMExceptionsare represented by platform objects that inherit from +the DOMException prototype object.Every platform object representing a DOMException in ECMAScript is associated with a global environment, just +as the initial objects are. +When an exception object is created by calling the DOMException constructor object, +either normally or as part of a
+newexpression, then the global environment +of the newly created object is associated with must be the same as for the DOMException constructor object itself.The value of the internal [[Prototype]] +property of a
+DOMExceptionobject must be the DOMException prototype object from the global environment the exception object is associated with.The class string of a
+DOMExceptionobject +must be “DOMException”.Note: The intention is for DOMException objects to be just like the other +various native
+Error objects that the +ECMAScript specification defines, apart from responding differently +to being passed to Object.prototype.toString and it having a “code” property. +If an implementation places non-standard properties on nativeError objects, exposing for example +stack traces or error line numbers, then these ought to be exposed +on exception objects too.4.14. Creating and throwing exceptions
+First, we define the current global environment as the result of running the following algorithm:
+-
+
-
+
Let F be the
+Function object used +as thethis value in the top-most call +on the ECMAScript call stack where F corresponds to an IDL attribute, operation, indexed property, named property, constructor, named constructor or stringifier. -
+
If F corresponds to an attribute, operation or stringifier, then return +the global environment associated with the interface that definition appears on.
+ -
+
Otherwise, if F corresponds to an indexed or named property, then return +the global environment associated with the interface that +the indexed or named property getter, setter or deleter was defined on.
+ -
+
Otherwise, if F is a named constructor for an interface, or is +an interface object for an +interface that is a constructor, then return the global environment +associated with that interface.
+ -
+
Otherwise, F is an exception field getter. Return +the global environment associated with the exception on which the +exception field was defined.
+
When a simple exception or
+DOMExceptionE is to be created, +with error name N and +optional user agent-defined message M, +the following steps must be followed:-
+
-
+
If M was not specified, let M be
+undefined . Otherwise, let it be the result of converting M to aString value. -
+
Let N be the result of converting N to a
+String value. -
+
Let args be a list of ECMAScript values.
+-
+
-
+
E is
+DOMException -
+
args is (
+undefined , N). -
+
E is a simple exception
+ -
+
args is (M)
+
-
+
-
+
Let G be the current global environment.
+ -
+
Let X be an object determined based on the type of E:
+-
+
-
+
E is
+DOMException -
+
X is the DOMException constructor object from the global environment G.
+ -
+
E is a simple exception
+ -
+
X is the constructor for the corresponding ECMAScript error +from the global environment G.
+
-
+
-
+
Let O be the result of calling X as a function +with args as the argument list.
+ -
+
Return O.
+
When a simple exception or
+DOMExceptionE is to be thrown, +with error name N and +optional user agent-defined message M, +the following steps must be followed:-
+
-
+
Let O be the result of creating the specified exception E with error name N and +optional user agent-defined message M.
+ -
+
Throw O.
+
+The above algorithms do not restrict platform objects representing exceptions propagating out of a
+Function to be + ones that are associated with the global environment + where thatFunction object originated. + For example, consider the IDL:interface A { + + /** * Calls computeSquareRoot on m, passing x as its argument. - */ - double doComputation(MathUtils m, double x); + */ + double doComputation(MathUtils m, double x); }; - -interface MathUtils { - /** - * If x is negative, throws a NotSupportedError. Otherwise, returns + +interface MathUtils { + /** + * If x is negative, throws a NotSupportedError. Otherwise, returns * the square root of x. - */ - double computeSquareRoot(double x); -};
- If we pass a MathUtils object from - a different global environment to doComputation, then the exception - thrown will be from that global environment: -
--ECMAScriptvar a = getA(); // An A object from this global environment. -var m = otherWindow.getMathUtils(); // A MathUtils object from a different global environment. - -a instanceof Object; // Evaluates to true. -m instanceof Object; // Evaluates to false. -m instanceof otherWindow.Object; // Evaluates to true. - -try { - a.doComputation(m, -1); -} catch (e) { - e instanceof DOMException; // Evaluates to false. - e instanceof otherWindow.DOMException; // Evaluates to true. -}- Any requirements in this document to throw an instance of an ECMAScript built-in - Error MUST use - the built-in from the current global environment. -
---4.15. Handling exceptions
- -- None of the algorithms or processing requirements in the - ECMAScript language binding catch ECMAScript exceptions. Whenever - an ECMAScript Function is invoked due - to requirements in this section and that Function - ends due to an exception being thrown, that exception - MUST propagate to the caller, and if - not caught there, to its caller, and so on. -
--Example-- The following IDL fragment - defines two interfaces - and an exception. - The
-valueOfattribute on ExceptionThrower - is defined to throw an exception whenever an attempt is made - to get its value. --IDLinterface Dahut { - attribute DOMString type; + */ + double computeSquareRoot(double x); }; - -interface ExceptionThrower { - // This attribute always throws a NotSupportedError and never returns a value. - attribute long valueOf; -};- Assuming an ECMAScript implementation supporting this interface, - the following code demonstrates how exceptions are handled: -
--ECMAScriptvar d = getDahut(); // Obtain an instance of Dahut. -var et = getExceptionThrower(); // Obtain an instance of ExceptionThrower. - -try { - d.type = { toString: function() { throw "abc"; } }; -} catch (e) { - // The string "abc" is caught here, since as part of the conversion - // from the native object to a string, the anonymous function - // was invoked, and none of the [[DefaultValue]], ToPrimitive or - // ToString algorithms are defined to catch the exception. -} - -try { - d.type = { toString: { } }; -} catch (e) { - // An exception is caught here, since an attempt is made to invoke - // [[Call]] on the native object that is the value of toString - // property. -} - -d.type = et; -// An uncaught NotSupportedError DOMException is thrown here, since the -// [[DefaultValue]] algorithm attempts to get the value of the -// "valueOf" property on the ExceptionThrower object. The exception -// propagates out of this block of code.-- -5. Common definitions
- -- This section specifies some common definitions that all - conforming implementations - MUST support. -
- --- -5.1. ArrayBufferView
- --IDLtypedef (Int8Array or Int16Array or Int32Array or - Uint8Array or Uint16Array or Uint32Array or Uint8ClampedArray or - Float32Array or Float64Array or DataView) ArrayBufferView;- The ArrayBufferView typedef is used to represent - objects that provide a view on to an ArrayBuffer. -
--- -5.2. BufferSource
- --IDLtypedef (ArrayBufferView or ArrayBuffer) BufferSource;- The BufferSource typedef is used to represent objects - that are either themselves an ArrayBuffer or which - provide a view on to an ArrayBuffer. -
--- -5.3. DOMTimeStamp
- --IDLtypedef unsigned long long DOMTimeStamp;- The DOMTimeStamp type is used for representing - a number of milliseconds, either as an absolute time (relative to some epoch) - or as a relative amount of time. Specifications that use this type will need - to define how the number of milliseconds is to be interpreted. -
--- -5.4. Function
- --IDLcallback Function = any (any... arguments);- The Function callback function - type is used for representing function values with no restriction on what arguments - are passed to it or what kind of value is returned from it. -
---5.5. VoidFunction
- --IDLcallback VoidFunction = void ();- The VoidFunction callback function - type is used for representing function values that take no arguments and do not - return any value. -
--- -6. Extensibility
- -This section is informative.
- -- Extensions to language binding requirements can be specified - using extended attributes - that do not conflict with those defined in this document. Extensions for - private, project-specific use should not be included in - IDL fragments - appearing in other specifications. It is recommended that extensions - that are required for use in other specifications be coordinated - with the group responsible for work on Web IDL, which - at the time of writing is the - W3C Web Platform Working Group, - for possible inclusion in a future version of this document. -
-- Extensions to any other aspect of the IDL language are - strongly discouraged. -
--- -7. Referencing this specification
- -This section is informative.
- -- It is expected that other specifications that define Web platform interfaces - using one or more IDL fragments - will reference this specification. It is suggested - that those specifications include a sentence such as the following, - to indicate that the IDL is to be interpreted as described in this - specification: -
--
-- The IDL fragment in Appendix A of this specification must, in conjunction - with the IDL fragments defined in this specification's normative references, - be interpreted as required for conforming sets of IDL fragments, as described in the - “Web IDL” specification. [WEBIDL] -
-- In addition, it is suggested that the conformance class for user - agents in referencing specifications be linked to the - conforming - implementation class from this specification: -
--
-- A conforming FooML user agent must also be a - conforming implementation of the IDL fragment in Appendix A - of this specification, as described in the - “Web IDL” specification. [WEBIDL] -
---8. Acknowledgements
- -This section is informative.
- -- The editor would like to thank the following people for contributing - to this specification: - Glenn Adams, - David Andersson, - L. David Baron, - Art Barstow, - Nils Barth, - Robin Berjon, - David Bruant, - Jan-Ivar Bruaroey, - Marcos Cáceres, - Giovanni Campagna, - Domenic Denicola, - Chris Dumez, - Michael Dyck, - Brendan Eich, - João Eiras, - Gorm Haug Eriksen, - Sigbjorn Finne, - David Flanagan, - Aryeh Gregor, - Dimitry Golubovsky, - James Graham, - Aryeh Gregor, - Kartikaya Gupta, - Marcin Hanclik, - Jed Hartman, - Stefan Haustein, - Dominique Hazaël-Massieux, - Ian Hickson, - Björn Höhrmann, - Kyle Huey, - Lachlan Hunt, - Oliver Hunt, - Jim Jewett, - Wolfgang Keller, - Anne van Kesteren, - Olav Junker Kjær, - Magnus Kristiansen, - Takeshi Kurosawa, - Yves Lafon, - Travis Leithead, - Jim Ley, - Kevin Lindsey, - Jens Lindström, - Peter Linss, - 呂康豪 (Kang-Hao Lu), - Kyle Machulis, - Mark Miller, - Ms2ger, - Andrew Oakley, - 岡坂 史紀 (Shiki Okasaka), - Jason Orendorff, - Olli Pettay, - Simon Pieters, - Andrei Popescu, - François Remy, - Tim Renouf, - Alex Russell, - Takashi Sakamoto, - Doug Schepers, - Jonas Sicking, - Garrett Smith, - Geoffrey Sneddon, - Jungkee Song, - Josh Soref, - Maciej Stachowiak, - Anton Tayanovskyy, - Peter Van der Beken, - Jeff Walden, - Allen Wirfs-Brock, - Jeffrey Yasskin and - Collin Xu. -
-- Special thanks also go to Sam Weinig for maintaining this document - while the editor was unavailable to do so. -
--- - + +-- -A. IDL grammar
- -- This section defines an LL(1) grammar whose start symbol, - Definitions, matches an - entire IDL fragment. -
- -- Each production in the grammar has on its right hand side either a - non-zero sequence of terminal and non-terminal symbols, or an - epsilon (ε) which indicates no symbols. Symbols that begin with - an uppercase letter are non-terminal symbols. Symbols within quotes - are terminal symbols that are matched with the exact text between - the quotes. Symbols that begin with a lowercase letter are terminal - symbols that are matched by the regular expressions (using Perl 5 regular - expression syntax [PERLRE]) as follows: -
--
- -- -integer -= -/-?([1-9][0-9]*|0[Xx][0-9A-Fa-f]+|0[0-7]*)/ -- -float -= -/-?(([0-9]+\.[0-9]*|[0-9]*\.[0-9]+)([Ee][+-]?[0-9]+)?|[0-9]+[Ee][+-]?[0-9]+)/ -- -identifier -= -/_?[A-Za-z][0-9A-Z_a-z-]*/ -- -string -= -/"[^"]*"/ -- -whitespace -= -/[\t\n\r ]+/ -- -comment -= -/\/\/.*|\/\*(.|\n)*?\*\// -- -other -= -/[^\t\n\r 0-9A-Za-z]/ -- The tokenizer operates on a sequence of Unicode characters - [UNICODE]. - When tokenizing, the longest possible match MUST be used. For example, if the input - text is “a1”, it is tokenized as a single identifier, - and not as a separate identifier and integer. - If the longest possible match could match one of the above named terminal symbols or - one of the quoted terminal symbols from the grammar, it MUST be tokenized as the quoted - terminal symbol. Thus, the input text “long” is tokenized as the quoted terminal symbol - "long" rather than an identifier called “long”, - and “.” is tokenized as the quoted terminal symbol - "." rather than an other. -
-- The IDL syntax is case sensitive, both for the quoted terminal symbols - used in the grammar and the values used for - identifier terminals. Thus, for - example, the input text “Const” is tokenized as - an identifier rather than the quoted - terminal symbol "const", an - interface with - identifier - “A” is distinct from one named “a”, and an - extended attribute - [constructor] will not be recognized as - the [Constructor] - extended attribute. -
-- Implicitly, any number of whitespace and - comment terminals are allowed between every other terminal - in the input text being parsed. Such whitespace and - comment terminals are ignored while parsing. -
- -- The following LL(1) grammar, starting with Definitions, - matches an IDL fragment: -
- --Note-- The Other - non-terminal matches any single terminal symbol except for - "(", ")", - "[", "]", - "{", "}" - and ",". -
-- While the ExtendedAttribute - non-terminal matches any non-empty sequence of terminal symbols (as long as any - parentheses, square brackets or braces are balanced, and the - "," token appears only within those balanced brackets), - only a subset of those - possible sequences are used by the extended attributes - defined in this specification — see - section 3.12 - for the syntaxes that are used by these extended attributes. -
--- - - -B. References
- --- -B.1. Normative references
- --
-
- [ECMA-262] -
-
- ECMAScript Language Specification.
- Ecma International.
-
Available at https://tc39.github.io/ecma262/. -
- - [IEEE-754] -
- - IEEE Standard for Binary Floating-Point Arithmetic (ANSI/IEEE Std 754-1985). - Institute of Electrical and Electronics Engineers, 1985. - -
- [PERLRE] -
-
- Perl regular expressions (Perl 5.8.8).
- The Perl Foundation, February 2006.
-
Available at http://www.perl.com/doc/manual/html/pod/perlre.html. -
- - [RFC2119] -
-
- Key words for use in RFCs to Indicate Requirement Levels,
- S. Bradner. IETF, March 1997.
-
Available at http://tools.ietf.org/html/rfc2119. -
- - [RFC2781] -
-
- UTF-16, an encoding of ISO 10646,
- P. Hoffmann and F. Yergeau. IETF, February 2000.
-
Available at http://tools.ietf.org/html/rfc2781. -
- - [RFC3629] -
-
- UTF-8, a transformation format of ISO 10646,
- F. Yergeau. IETF, November 2003.
-
Available at http://tools.ietf.org/html/rfc3629. -
- - [SECURE-CONTEXTS] -
-
- Secure Contexts.
- M. West and Y. Zhu, Editors. World Wide Web Consortium, October 2015.
-
Available at https://w3c.github.io/webappsec-secure-contexts/. -
- - [TYPEDARRAYS] -
-
- Typed Array Specification,
- V. Vukicevic and K. Russell, eds. The Khronos Group, 08 February 2011.
-
Available at https://www.khronos.org/registry/typedarray/specs/1.0/. -
- - [UNICODE] -
-
- The Unicode Standard,
- Version 6.0 or later. The Unicode Consortium. Mountain View, California, 2011.
- ISBN 978-1-936213-01-6.
-
Available at http://www.unicode.org/versions/Unicode6.0.0/. -
-
--B.2. Informative references
- --
-
- [DOM] -
-
- DOM Standard.
- A. van Kesteren, A. Gregor and Ms2ger, Editors. WHATWG, 22 July 2013.
-
Available at http://dom.spec.whatwg.org/. -
- - [DOM3CORE] -
-
- Document Object Model (DOM) Level 3 Core Specification.
- A. Le Hors, et al., Editors. World Wide Web Consortium, April 2004.
-
Available at http://www.w3.org/TR/2004/REC-DOM-Level-3-Core-20040407/. -
- - [HTML5] -
-
- HTML5.
- I. Hickson, Editor. World Wide Web Consortium, May 2011.
-
Available at http://www.w3.org/TR/2011/WD-html5-20110525/. -
- - [OMGIDL] -
-
- CORBA 3.1 – OMG IDL Syntax and Semantics chapter.
- Object Management Group, January 2008.
-
Available at http://www.omg.org/cgi-bin/doc?formal/08-01-04.pdf. -
- - [WEBIDL-JAVA] -
-
- Java langage binding for Web IDL.
- World Wide Consortium, work in progress.
-
Available at http://dev.w3.org/2006/webapi/WebIDL/java.html. -
- - [XMLNS] -
-
- Namespaces in XML 1.0 (Third Edition),
- T. Bray, D. Hollander, A. Layman, R. Tobin, H. Thompson, eds.
- World Wide Web Consortium, 8 December 2009.
-
Available at http://www.w3.org/TR/2009/REC-xml-names-20091208/. -
-
--C. Changes
- -This section is informative.
- -- The following is a list of substantial changes to the document on each publication. - For the list of changes during the development of the First Edition of this - specification, see - that document's - Changes appendix. -
--
-
- Current editor’s draft -
-
-
-
-
-
-
- Fixed unions containing a sequence and a dictionary to try the - sequence first when given an object, just like overload - resolution does. -
-
- -
-
- Removed support for [Constructor] on dictionaries. -
-
- -
-
- Added the [LenientSetter] extended attribute. -
-
- -
-
- Added the [SecureContext] extended attribute. -
-
- -
-
- Changed from [Unscopeable] to - [Unscopable] to match ES6 better. -
-
- -
-
- Removed the term "unenumerable" and its associated prose and replaced it by the - extended attribute [LegacyUnenumerableNamedProperties]. -
-
- -
-
- Allowed object internal methods to be overridden by other specifications. -
-
- -
-
- Added some more parameters to the “perform a security check” hook. -
-
- -
-
- Defined the “name” property for all Function - objects (including those for operations and attribute getters and setters). -
-
- -
-
- Removed the Date type. -
-
- -
-
- Disallowed “length” and “name” from being used as identifiers of - constants. -
-
- -
-
- Added a FrozenArray<T> type. -
-
- -
-
- Renamed [ArrayClass] to [LegacyArrayClass]. -
-
- -
-
- Removed T[] array types. -
-
- -
-
- Allowed [NewObject] to be used on things with - a promise type. -
-
- -
-
- Fix various cases in which maplike/setlike were operating on the wrong objects. -
-- Disallow maplike, setlike and iterable declarations from appearing more than - once on an interface and its inherited and consequential interfaces. - Also disallow the relevant restricted member names (such as “entries” and “values”) - on the inherited and consequential interfaces. -
-
- -
-
- Allowed stringifier attributes to have type USVString. -
-
- -
-
- Gave interface objects, named constructors, and dictionary - constructors a "name" property to match ES6. -
-
- -
-
- Made the "length" property on dictionary constructors - configurable. -
-
- -
-
- Added types for ArrayBuffer, DataView - and typed array objects. -
-
- -
-
- Added USVString and allowed string literals in IDL to - be used to give values for all string-typed optional argument and dictionary - member default values. -
-
- -
-
- Made sequences distinguishable from dictionaries, callback - functions, and all interface types. -
-
- -
-
- Removed IDL exceptions, baked in DOMException, - and added Error and DOMException - as types. -
-
- -
-
- Removed [MapLike] and added - iterable, maplike and setlike declarations. -
-
- -
-
- Removed the custom Object.prototype.toString definition and instead - defined class strings to influence the @@toStringTag property - on objects. -
-
- -
-
- Added the [Unscopeable] extended attribute. -
-
- -
-
- Rewrote ES to IDL sequence conversion so that any iterable is - convertible to a sequence. -
-
- -
-
- Added grammar production for Promise<T> types - and allowed T to be void. -
-
- -
-
- Added a definition to "initialize an object from an iterable", - which behaves like the Map constructor. -
-
- -
-
- Added a default value
-[]that can be used for - sequence-typed operation argument default values and - dictionary member default values. -
- -
-
- Added promise types. -
-
- -
-
- Added the [NewObject] and - [SameObject] extended attributes. -
-
- -
-
- Allowed [Constructor] to be specified - on dictionaries. -
-
- -
-
- Added a RegExp type. -
-
- -
-
- Added iterators that can be declared on interfaces. -
-
- -
-
- Added an @@iterator method to objects with indexed - properties. -
-
- -
-
- Updated to ECMAScript 6th Edition. -
-
- -
-
- Added serializers. -
-
- -
-
- Added a ByteString type, for representing - 8 bit strings without a particular encoding as ECMAScript - String values. -
-
- -
-
- Added static attributes. -
-
-
- -
-
- Make it clear that an interface can't be exposed in a global - where its parent interface is not exposed. -
-
- -
-
- Allow dictionary-typed trailing-position operation arguments not to - be optional, if and only if the dictionary type has a required - dictionary member. -
-
- -
-
- Added a platform object [[Set]] internal method to handle - named and indexed setters better. -
-
- -
-
- Removed the concept of creators; setters are always also - creators. -
-
- -
-
- Disallowed an interface without [NoInterfaceObject] - inheriting from a [NoInterfaceObject] interface. -
-
- -
-
- Removed indexed deleters. -
-
- -
-
- Made the prototype of an interface object of a non-root - interface be the interface object of its ancestor interface. -
-
- -
-
- Clarified the property attributes of the "prototype" property - of non-callback interface objects. -
-
- -
-
- Made the "length" property on interface objects and named - constructors configurable. -
-
- -
-
- Added a way to mark dictionary members as required. -
-
- -
-
- Allowed hyphens in identifiers after the first character. -
-
- -
-
- Fix [Exposed] text to make it - clear that the value on the interface, if any, is used as the - value for its members by default. -
-
- -
-
- Fixed the grammar for extended attributes that take an identifier list, - such as [Exposed]. -
-
- -
-
- Add a term "unenumerable" to allow named properties to be exposed as - properties with [[Enumerable]] set to false. -
-
- -
-
- Added the [Exposed] and - [PrimaryGlobal] extended attributes and - allowed an identifier to be used with [Global]. -
-
- -
-
- Removed [TreatUndefinedAs]. -
-
- -
-
- Renamed [TreatNonCallableAsNull] to [TreatNonObjectAsNull] - and changed its semantics to allow any object. Changed - callback function invocation to be a no-op when the object is - not callable, which can now happen in the - [TreatNonObjectAsNull] case. -
-
- -
-
- Changed the default this value for callbacks from null to undefined. -
-
- -
-
- Removed the requirement for named properties objects to be function objects. -
-
- -
-
- Disallowed properties from being defined on a named properties object. -
-
- -
-
- Fixed infinite loop in named property visibility algorithm. -
-
- -
-
- Made stringifiers and serializers not use [[Get]] or [[Call]] - for the their attribute or operation delegated behavior. -
-
- -
-
- Allowed trailing optional comma in enum lists. -
-
- -
-
- Disallowed static interface members from being defined on a callback interface. -
-
- -
-
- Added a hook to do a security check when invoking an operation - or accessing an attribute. -
-
- -
-
- Defined how callbacks influence the incumbent script. -
-
- -
-
- Changed how callback functions are invoked to support missing - optional arguments. -
-
- -
-
- Renamed [NamedPropertiesObject] to - [Global], which now also causes - properties for interface members to appear on the object - itself rather than on the interface prototype object. -
-
- -
-
- Split out boolean from the other - primitive types. Made boolean, - numeric types and DOMString distinguishable. -
-
- -
-
- Required a getter to be present on an interface if it has a - setter, creator or delete. -
-
- -
-
- Extended [Unforgeable] to apply to operations - and interfaces. -
-
- -
-
- Allowed all operation arguments to be specified as being optional and - changed back to the behavior of undefined - being treated as a missing optional argument value. Modified the - effective overload set and overload resolution algorithms to - take this into account, as well as allowing an undefined - value passed as the argument value at the distinguishing index to select the overload - with an optional argument at that index. - Also removed [TreatUndefinedAs=Missing]. -
-
- -
-
- Changed the ECMAScript to IDL dictionary conversion algorithm - to treat a property with the value undefined - as missing. -
-
- -
-
- Removed the ability to put extended attributes after the -
-typedefkeyword, as that feature is unused. -
- -
-
- Fixed the long long and unsigned long long - conversion algorithms to correctly identify the range of contiguous, - exactly, uniquely representable integers you can get from a Number. -
-
- -
-
- Clarified that Function objects for - operations and attribute getters and setters are distinct on each - interface they are mixed in to using an implements statement, - and that each copy of the Function works - only on objects that implement the interface whose interface - prototype object the Function object - is on. -
-
- -
-
- Mention the named properties object in the list of initial objects. -
-
- -
-
- Added back a custom [[HasInstance]] on interface objects to allow objects - from other windows to be considered instanceof them. -
-
- -
-
- Fixed conversion of Number values - to any by using the - conversion algorithm for unrestricted double. -
-
- -
-
- Allowed an identifier to be “prototype” for any construct except - constants and static operations. -
-
- -
-
- Fixed a bug in the user object definition where the internal [[Call]] - method would be treated as the implementation of an operation even if - the callback interface had more than one operation. -
-
- -
-
- Further tweaked the overload resolution algorithm and union type conversion - algorithm for consistency. -
-
- -
-
- Lifted the restriction on [Unforgeable] appearing - on an IDL attribute if another interface inherits from the one the attribute - is declared on, but required that the inheriting interface not have an - attribute with the same identifier. -
-
- -
-
- Made attribute setters throw if no argument was passed to them, instead of - assuming undefined. -
-
- -
-
- Prevented dictionaries from referencing themselves. -
-
- -
-
- Made sequences, arrays and dictionaries undistingishable again, thereby allowing - non-Array ECMAScript objects to be converted - to sequence and array types. -
-
- -
-
- Added a requirement to state what the values of an exception’s fields are - when throwing it. -
-
- -
-
- Changed the “length” property on Function - objects for IDL operations to return the smallest number of required arguments. -
-
- -
-
- Clarified that dictionaries may not be nullable when used as - the type of an operation argument or dictionary member. -
-
- -
-
- Specify the value of the “length” property on interface objects - that do not have constructors. -
-
- -
-
- Do not treat array index properties as named properties if an object supports - both indexed and named properties. -
-
- -
-
- Require that dictionary type arguments followed by optional arguments - must also be optional, and that such optional arguments always are - assumed to have a default value of an empty dictionary. Also disallow - dictionary types from being used inside nullable types and from being - considered distinguishable from nullable types. -
-
- -
-
- Always consider dictionary members with default values as present. -
-
- -
-
- Tweak [Clamp] algorithms for clarity. -
-
- -
-
- Require exception objects to have [[Class]] “Error” and suggest that they - have any non-standard properties that native Error objects do. -
-
- -
-
- Fixed a bug in the whitespace token regular expression. -
-
- -
-
- Explicitly disallow dictionaries from being used inside union types - as the type of an attribute or exception field. -
-
- -
-
- Fixed a bug in the definition of distinguishability where a nullable - union type and a non-nullable union type that has a nullable member type - were considered distinguishable. -
-
- -
-
- Disallowed callback interfaces from being used in implements statements. -
-
- -
-
- Renamed “exception types” to “exception names”. -
-
- -
-
- Disallowed non-callback interfaces from inheriting from callback interfaces. -
-
- -
-
- Changed the algorithm for conversion from a platform object with indexed - properties to a sequence type to use its internal knowledge of the - set of property indexes rather than getting the "length" property, which - may not even exist. -
-
- -
-
- Added a warning to prefer the use of double - to float, unless there are good - reasons to choose the 32 bit type. -
-
- -
-
- Changed the restriction on operation argument default values - so that all optional arguments to the left of one with a - default value must also have default values. (Previously, - this was to the right.) -
-
-
- -
-
If we pass a
+MathUtilsobject from + a different global environment to doComputation, then the exception + thrown will be from that global environment:var a = getA(); // An A object from this global environment. +var m = otherWindow.getMathUtils(); // A MathUtils object from a different global environment. + +a instanceof Object; // Evaluates to true. +m instanceof Object; // Evaluates to false. +m instanceof otherWindow.Object; // Evaluates to true. + +try { + a.doComputation(m, -1); +} catch (e) { + e instanceof DOMException; // Evaluates to false. + e instanceof otherWindow.DOMException; // Evaluates to true. +}
+ +Any requirements in this document to throw an instance of an ECMAScript built-in
+Error must use +the built-in from the current global environment.4.15. Handling exceptions
+None of the algorithms or processing requirements in the +ECMAScript language binding catch ECMAScript exceptions. Whenever +an ECMAScript
+Function is invoked due +to requirements in this section and thatFunction ends due to an exception being thrown, that exception +must propagate to the caller, and if +not caught there, to its caller, and so on.+ ++The following IDL fragment defines two interfaces and an exception. + The
+valueOfattribute onExceptionThroweris defined to throw an exception whenever an attempt is made + to get its value.interface Dahut { + attribute DOMString type; +}; + +interface ExceptionThrower { + // This attribute always throws a NotSupportedError and never returns a value. + attribute long valueOf; +}; +
+Assuming an ECMAScript implementation supporting this interface, + the following code demonstrates how exceptions are handled:
+var d = getDahut(); // Obtain an instance of Dahut. +var et = getExceptionThrower(); // Obtain an instance of ExceptionThrower. + +try { + d.type = { toString: function() { throw "abc"; } }; +} catch (e) { + // The string "abc" is caught here, since as part of the conversion + // from the native object to a string, the anonymous function + // was invoked, and none of the [[DefaultValue]], ToPrimitive or + // ToString algorithms are defined to catch the exception. +} + +try { + d.type = { toString: { } }; +} catch (e) { + // An exception is caught here, since an attempt is made to invoke + // [[Call]] on the native object that is the value of toString + // property. +} + +d.type = et; +// An uncaught NotSupportedError DOMException is thrown here, since the +// [[DefaultValue]] algorithm attempts to get the value of the +// "valueOf" property on the ExceptionThrower object. The exception +// propagates out of this block of code.
+5. Common definitions
+This section specifies some common definitions that all conforming implementations must support.
+5.1. ArrayBufferView
+typedef (Int8Array or Int16Array or Int32Array or + Uint8Array or Uint16Array or Uint32Array or Uint8ClampedArray or + Float32Array or Float64Array or DataView) ArrayBufferView; +
+The
+ArrayBufferViewtypedef is used to represent +objects that provide a view on to anArrayBuffer.5.2. BufferSource
+typedef (ArrayBufferView or ArrayBuffer) BufferSource;
+The
+BufferSourcetypedef is used to represent objects +that are either themselves anArrayBufferor which +provide a view on to anArrayBuffer.5.3. DOMTimeStamp
+typedef unsigned long long DOMTimeStamp;
+The
+DOMTimeStamptype is used for representing +a number of milliseconds, either as an absolute time (relative to some epoch) +or as a relative amount of time. Specifications that use this type will need +to define how the number of milliseconds is to be interpreted.5.4. Function
+callback Function = any (any... arguments);
+The
+Functioncallback function type is used for representing function values with no restriction on what arguments +are passed to it or what kind of value is returned from it.5.5. VoidFunction
+callback VoidFunction = void ();
+The
+VoidFunctioncallback function type is used for representing function values that take no arguments and do not +return any value.6. Extensibility
+This section is informative.
+Extensions to language binding requirements can be specified +using extended attributes that do not conflict with those defined in this document. Extensions for +private, project-specific use should not be included in IDL fragments appearing in other specifications. It is recommended that extensions +that are required for use in other specifications be coordinated +with the group responsible for work on Web IDL, which +at the time of writing is the W3C Web Platform Working Group, +for possible inclusion in a future version of this document.
+Extensions to any other aspect of the IDL language are +strongly discouraged.
+7. Referencing this specification
+This section is informative.
+It is expected that other specifications that define Web platform interfaces +using one or more IDL fragments will reference this specification. It is suggested +that those specifications include a sentence such as the following, +to indicate that the IDL is to be interpreted as described in this +specification:
++
+The IDL fragment in Appendix A of this specification must, in conjunction + with the IDL fragments defined in this specification’s normative references, + be interpreted as required for conforming sets of IDL fragments, as described in the + “Web IDL” specification. [WEBIDL]
+In addition, it is suggested that the conformance class for user +agents in referencing specifications be linked to the conforming implementation class from this specification:
++
+A conforming FooML user agent must also be a conforming implementation of the IDL fragment in Appendix A + of this specification, as described in the + “Web IDL” specification. [WEBIDL]
+8. Acknowledgements
+This section is informative.
+The editor would like to thank the following people for contributing +to this specification: +Glenn Adams, +David Andersson, +L. David Baron, +Art Barstow, +Nils Barth, +Robin Berjon, +David Bruant, +Jan-Ivar Bruaroey, +Marcos Cáceres, +Giovanni Campagna, +Domenic Denicola, +Chris Dumez, +Michael Dyck, +Brendan Eich, +João Eiras, +Gorm Haug Eriksen, +Sigbjorn Finne, +David Flanagan, +Aryeh Gregor, +Dimitry Golubovsky, +James Graham, +Aryeh Gregor, +Kartikaya Gupta, +Marcin Hanclik, +Jed Hartman, +Stefan Haustein, +Dominique Hazaël-Massieux, +Ian Hickson, +Björn Höhrmann, +Kyle Huey, +Lachlan Hunt, +Oliver Hunt, +Jim Jewett, +Wolfgang Keller, +Anne van Kesteren, +Olav Junker Kjær, +Magnus Kristiansen, +Takeshi Kurosawa, +Yves Lafon, +Travis Leithead, +Jim Ley, +Kevin Lindsey, +Jens Lindström, +Peter Linss, +呂康豪 (Kang-Hao Lu), +Kyle Machulis, +Mark Miller, +Ms2ger, +Andrew Oakley, +岡坂 史紀 (Shiki Okasaka), +Jason Orendorff, +Olli Pettay, +Simon Pieters, +Andrei Popescu, +François Remy, +Tim Renouf, +Alex Russell, +Takashi Sakamoto, +Doug Schepers, +Jonas Sicking, +Garrett Smith, +Geoffrey Sneddon, +Jungkee Song, +Josh Soref, +Maciej Stachowiak, +Anton Tayanovskyy, +Peter Van der Beken, +Jeff Walden, +Allen Wirfs-Brock, +Jeffrey Yasskin and +Collin Xu.
+Special thanks also go to Sam Weinig for maintaining this document +while the editor was unavailable to do so.
+IDL grammar
+This section defines an LL(1) grammar whose start symbol,
+Definitions , matches an +entire IDL fragment.Each production in the grammar has on its right hand side either a +non-zero sequence of terminal and non-terminal symbols, or an +epsilon (ε) which indicates no symbols. +Symbols that begin with an uppercase letter are non-terminal symbols. +Symbols in monospaced fonts are terminal symbols. +Symbols in sans-serif font that begin with a lowercase letter are terminal +symbols that are matched by the regular expressions (using Perl 5 regular +expression syntax [PERLRE]) as follows:
++ +
++ integer +=+/-?([1-9][0-9]*|0[Xx][0-9A-Fa-f]+|0[0-7]*)/++ float +=+/-?(([0-9]+\.[0-9]*|[0-9]*\.[0-9]+)([Ee][+-]?[0-9]+)?|[0-9]+[Ee][+-]?[0-9]+)/++ identifier +=+/_?[A-Za-z][0-9A-Z_a-z-]*/++ string +=+/"[^"]*"/++ whitespace +=+/[\t\n\r ]+/++ comment +=+/\/\/.*|\/\*(.|\n)*?\*\//++ other +=+/[^\t\n\r 0-9A-Za-z]/+The tokenizer operates on a sequence of Unicode characters [UNICODE]. +When tokenizing, the longest possible match must be used. For example, if the input +text is “a1”, it is tokenized as a single
+identifier , +and not as a separateidentifier andinteger . +If the longest possible match could match one of the above named terminal symbols or +one of the other terminal symbols from the grammar, it must be tokenized as the latter. +Thus, the input text “long” is tokenized as the quoted terminal symbollong rather than anidentifier called “long”, +and “.” is tokenized as the quoted terminal symbol. rather than another .The IDL syntax is case sensitive, both for the quoted terminal symbols +used in the grammar and the values used for
+identifier terminals. Thus, for +example, the input text “Const” is tokenized as +anidentifier rather than the +terminal symbolconst , an interface with identifier “A” is distinct from one named “a”, and an extended attribute [constructor] will not be recognized as +the [Constructor] +extended attribute.Implicitly, any number of
+whitespace andcomment terminals are allowed between every other terminal +in the input text being parsed. Suchwhitespace andcomment terminals are ignored while parsing.The following LL(1) grammar, starting with
+ +Definitions , +matches an IDL fragment:Note: The
+Other non-terminal matches any single terminal symbol except for( ,) ,[ ,] ,{ ,} and, .While the
+ExtendedAttribute non-terminal matches any non-empty sequence of terminal symbols (as long as any +parentheses, square brackets or braces are balanced, and the, token appears only within those balanced brackets), +only a subset of those +possible sequences are used by the extended attributes defined in this specification — see §3.12 Extended attributes for the syntaxes that are used by these extended attributes.Changes
+This section is informative.
+The following is a list of substantial changes to the document on each publication. +For the list of changes during the development of the First Edition of this +specification, see that document’s +Changes appendix.
+-
+
-
+
Fixed unions containing a sequence and a dictionary to try the +sequence first when given an object, just like overload +resolution does.
+ -
+
Removed support for [
+Constructor] on dictionaries. -
+
Added the [
+LenientSetter] extended attribute. -
+
Added the [
+SecureContext] extended attribute. -
+
Changed from [
+Unscopeable] to +[Unscopable] to match ES6 better. -
+
Removed the term "unenumerable" and its associated prose and replaced it by the +extended attribute [LegacyUnenumerableNamedProperties].
+ -
+
Allowed object internal methods to be overridden by other specifications.
+ -
+
Added some more parameters to the “perform a security check” hook.
+ -
+
Defined the “name” property for all
+Function objects (including those for operations and attribute getters and setters). -
+
Removed the Date type.
+ -
+
Disallowed “length” and “name” from being used as identifiers of +constants.
+ -
+
Added a FrozenArray<T> type.
+ -
+
Renamed [
+ArrayClass] to [LegacyArrayClass]. -
+
Removed
+T[]array types. -
+
Allowed [
+NewObject] to be used on things with +a promise type. -
+
Fix various cases in which maplike/setlike were operating on the wrong objects.
+Disallow maplike, setlike and iterable declarations from appearing more than +once on an interface and its inherited and consequential interfaces. +Also disallow the relevant restricted member names (such as “entries” and “values”) +on the inherited and consequential interfaces.
+ -
+
Allowed stringifier attributes to have type
+USVString. -
+
Gave interface objects, named constructors, and dictionary +constructors a "name" property to match ES6.
+ -
+
Made the "length" property on dictionary constructors +configurable.
+ -
+
Added types for
+ArrayBuffer,DataViewand typed array objects. -
+
Added
+USVStringand allowed string literals in IDL to +be used to give values for all string-typed optional argument and dictionary +member default values. -
+
Made sequences distinguishable from dictionaries, callback +functions, and all interface types.
+ -
+
Removed IDL exceptions, baked in
+DOMException, +and addedErrorandDOMExceptionas types. -
+
Removed [
+MapLike] and added +iterable, maplike and setlike declarations. -
+
Removed the custom Object.prototype.toString definition and instead +defined class strings to influence the @@toStringTag property +on objects.
+ -
+
Added the [
+Unscopeable] extended attribute. -
+
Rewrote ES to IDL sequence conversion so that any iterable is +convertible to a sequence.
+ -
+
Added grammar production for Promise<T> types +and allowed T to be
+void. -
+
Added a definition to "initialize an object from an iterable", +which behaves like the
+Map constructor. -
+
Added a default value
+[]that can be used for +sequence-typed operation argument default values and +dictionary member default values. -
+
Added promise types.
+ -
+
Added the [
+NewObject] and +[SameObject] extended attributes. -
+
Allowed [
+Constructor] to be specified +on dictionaries. -
+
Added a
+RegExp type. -
+
Added iterators that can be declared on interfaces.
+ -
+
Added an @@iterator method to objects with indexed +properties.
+ -
+
Updated to ECMAScript 6th Edition.
+ -
+
Added serializers.
+ -
+
Added a
+ByteStringtype, for representing +8 bit strings without a particular encoding as ECMAScriptString values. -
+
Added static attributes.
+ -
+
Make it clear that an interface can’t be exposed in a global +where its parent interface is not exposed.
+ -
+
Allow dictionary-typed trailing-position operation arguments not to +be optional, if and only if the dictionary type has a required +dictionary member.
+ -
+
Added a platform object [[Set]] internal method to handle +named and indexed setters better.
+ -
+
Removed the concept of creators; setters are always also +creators.
+ -
+
Disallowed an interface without [NoInterfaceObject] +inheriting from a [NoInterfaceObject] interface.
+ -
+
Removed indexed deleters.
+ -
+
Made the prototype of an interface object of a non-root +interface be the interface object of its ancestor interface.
+ -
+
Clarified the property attributes of the "prototype" property +of non-callback interface objects.
+ -
+
Made the "length" property on interface objects and named +constructors configurable.
+ -
+
Added a way to mark dictionary members as required.
+ -
+
Allowed hyphens in identifiers after the first character.
+ -
+
Fix [
+Exposed] text to make it +clear that the value on the interface, if any, is used as the +value for its members by default. -
+
Fixed the grammar for extended attributes that take an identifier list, +such as [
+Exposed]. -
+
Add a term "unenumerable" to allow named properties to be exposed as +properties with [[Enumerable]] set to false.
+ -
+
Added the [
+Exposed] and +[PrimaryGlobal] extended attributes and +allowed an identifier to be used with [Global]. -
+
Removed [
+TreatUndefinedAs]. -
+
Renamed [TreatNonCallableAsNull] to [TreatNonObjectAsNull] +and changed its semantics to allow any object. Changed +callback function invocation to be a no-op when the object is +not callable, which can now happen in the +[TreatNonObjectAsNull] case.
+ -
+
Changed the default this value for callbacks from null to undefined.
+ -
+
Removed the requirement for named properties objects to be function objects.
+ -
+
Disallowed properties from being defined on a named properties object.
+ -
+
Fixed infinite loop in named property visibility algorithm.
+ -
+
Made stringifiers and serializers not use [[Get]] or [[Call]] +for the their attribute or operation delegated behavior.
+ -
+
Allowed trailing optional comma in enum lists.
+ -
+
Disallowed static interface members from being defined on a callback interface.
+ -
+
Added a hook to do a security check when invoking an operation +or accessing an attribute.
+ -
+
Defined how callbacks influence the incumbent script.
+ -
+
Changed how callback functions are invoked to support missing +optional arguments.
+ -
+
Renamed [
+NamedPropertiesObject] to +[Global], which now also causes +properties for interface members to appear on the object +itself rather than on the interface prototype object. -
+
Split out
+booleanfrom the other +primitive types. Madeboolean, +numeric types andDOMStringdistinguishable. -
+
Required a getter to be present on an interface if it has a +setter, creator or delete.
+ -
+
Extended [
+Unforgeable] to apply to operations +and interfaces. -
+
Allowed all operation arguments to be specified as being optional and +changed back to the behavior of
+undefined being treated as a missing optional argument value. Modified the +effective overload set and overload resolution algorithms to +take this into account, as well as allowing anundefined value passed as the argument value at the distinguishing index to select the overload +with an optional argument at that index. +Also removed [TreatUndefinedAs=Missing]. -
+
Changed the ECMAScript to IDL dictionary conversion algorithm +to treat a property with the value
+undefined as missing. -
+
Removed the ability to put extended attributes after the
+typedefkeyword, as that feature is unused. -
+
Fixed the
+long longandunsigned long longconversion algorithms to correctly identify the range of contiguous, +exactly, uniquely representable integers you can get from aNumber . -
+
Clarified that
+Function objects for +operations and attribute getters and setters are distinct on each +interface they are mixed in to using an implements statement, +and that each copy of theFunction works +only on objects that implement the interface whose interface +prototype object theFunction object +is on. -
+
Mention the named properties object in the list of initial objects.
+ -
+
Added back a custom [[HasInstance]] on interface objects to allow objects +from other windows to be considered instanceof them.
+ -
+
Fixed conversion of
+Number values +toanyby using the +conversion algorithm forunrestricted double. -
+
Allowed an identifier to be “prototype” for any construct except +constants and static operations.
+ -
+
Fixed a bug in the user object definition where the internal [[Call]] +method would be treated as the implementation of an operation even if +the callback interface had more than one operation.
+ -
+
Further tweaked the overload resolution algorithm and union type conversion +algorithm for consistency.
+ -
+
Lifted the restriction on [
+Unforgeable] appearing +on an IDL attribute if another interface inherits from the one the attribute +is declared on, but required that the inheriting interface not have an +attribute with the same identifier. -
+
Made attribute setters throw if no argument was passed to them, instead of +assuming
+undefined . -
+
Prevented dictionaries from referencing themselves.
+ -
+
Made sequences, arrays and dictionaries undistingishable again, thereby allowing +non-
+Array ECMAScript objects to be converted +to sequence and array types. -
+
Added a requirement to state what the values of an exception’s fields are +when throwing it.
+ -
+
Changed the “length” property on
+Function objects for IDL operations to return the smallest number of required arguments. -
+
Clarified that dictionaries may not be nullable when used as +the type of an operation argument or dictionary member.
+ -
+
Specify the value of the “length” property on interface objects +that do not have constructors.
+ -
+
Do not treat array index properties as named properties if an object supports +both indexed and named properties.
+ -
+
Require that dictionary type arguments followed by optional arguments +must also be optional, and that such optional arguments always are +assumed to have a default value of an empty dictionary. Also disallow +dictionary types from being used inside nullable types and from being +considered distinguishable from nullable types.
+ -
+
Always consider dictionary members with default values as present.
+ -
+
Tweak [
+Clamp] algorithms for clarity. -
+
Require exception objects to have [[Class]] “Error” and suggest that they +have any non-standard properties that native Error objects do.
+ -
+
Fixed a bug in the whitespace token regular expression.
+ -
+
Explicitly disallow dictionaries from being used inside union types +as the type of an attribute or exception field.
+ -
+
Fixed a bug in the definition of distinguishability where a nullable +union type and a non-nullable union type that has a nullable member type +were considered distinguishable.
+ -
+
Disallowed callback interfaces from being used in implements statements.
+ -
+
Renamed “exception types” to “exception names”.
+ -
+
Disallowed non-callback interfaces from inheriting from callback interfaces.
+ -
+
Changed the algorithm for conversion from a platform object with indexed +properties to a sequence type to use its internal knowledge of the +set of property indexes rather than getting the "length" property, which +may not even exist.
+ -
+
Added a warning to prefer the use of
+doubletofloat, unless there are good +reasons to choose the 32 bit type. -
+
Changed the restriction on operation argument default values +so that all optional arguments to the left of one with a +default value must also have default values. (Previously, +this was to the right.)
+ +
-
- For named definitions,
- the identifier token that appears
- directly after the