From df8c9c4ef7e32298ea3b8b13eed73790957468da Mon Sep 17 00:00:00 2001 From: Domenic Denicola Date: Thu, 25 Aug 2016 15:07:22 -0400 Subject: [PATCH] Add namespaces (#121) * Add namespaces This adds the concept of namespaces, as discussed in https://github.com/whatwg/console/issues/3 (starting especially around https://github.com/whatwg/console/issues/3#issuecomment-214586757). They can only contain regular operations. The ES binding for namespaces here is written in a fully modern style, and so differs slightly from similar prose for interfaces' ES binding. It is hoped that it can provide a template for eventually updating interfaces' ES binding to modern ES. * Address most code review comments: - Missing some [SecureContext] stuff - Not yet addressed the operation-creation stuff * Stick with "declared on" instead of "declared within" It doesn't read quite right to me, but let's keep it as-is for now and investigate any issues in https://github.com/heycam/webidl/issues/153. * Move "creating an operation function" out to #es-operations --- index.html | 514 +++++++++++++++++++++++++++++++++++++++++------------ index.xml | 435 ++++++++++++++++++++++++++++++++++++++++----- 2 files changed, 791 insertions(+), 158 deletions(-) diff --git a/index.html b/index.html index 849a0480..d8010d3b 100644 --- a/index.html +++ b/index.html @@ -19,7 +19,7 @@ -
W3C

Web IDL (Second Edition)

W3C Editor’s Draft 23 August 2016

This Version:
http://heycam.github.io/webidl/
Latest Version:
http://www.w3.org/TR/WebIDL/
Previous Versions:
http://www.w3.org/TR/2012/CR-WebIDL-20120419/
http://www.w3.org/TR/2012/WD-WebIDL-20120207/
http://www.w3.org/TR/2011/WD-WebIDL-20110927/
http://www.w3.org/TR/2011/WD-WebIDL-20110712/
http://www.w3.org/TR/2010/WD-WebIDL-20101021/
http://www.w3.org/TR/2008/WD-WebIDL-20081219/
http://www.w3.org/TR/2008/WD-WebIDL-20080829/
http://www.w3.org/TR/2008/WD-DOM-Bindings-20080410/
http://www.w3.org/TR/2007/WD-DOM-Bindings-20071017/
Participate:
+
@@ -72,7 +72,7 @@

Status of This Document

report can be found in the W3C technical reports index at http://www.w3.org/TR/.

- This document is the 23 August 2016 Editor’s Draft of the + This document is the 25 August 2016 Editor’s Draft of the Web IDL (Second Edition) specification. Please send comments about this document to @@ -123,7 +123,7 @@

Status of This Document

Table of Contents

-
+
@@ -286,6 +286,8 @@

3. Interface definition language

IDL fragment are: interfaces, partial interface definitions, + namespaces, + partial namespace definitions, dictionaries, partial dictionary definitions, typedefs and @@ -300,7 +302,7 @@

3. Interface definition language

ExtendedAttributeList), which can control how the definition will be handled in language bindings. The extended attributes defined by this specification that are language binding - agnostic are discussed in section 3.11, + agnostic are discussed in section 3.12, while those specific to the ECMAScript language binding are discussed in section 4.3.

@@ -312,6 +314,7 @@

3. Interface definition language

[1]DefinitionsExtendedAttributeList Definition Definitions
 | ε
[2]DefinitionCallbackOrInterface
 | + Namespace
 | Partial
 | Dictionary
 | Enum
 | @@ -391,6 +394,8 @@

3.1. Names

Every interface, partial interface definition, + namespace, + partial namespace definition, dictionary, partial dictionary definition, enumeration, @@ -409,12 +414,14 @@

3.1. Names

  • For named definitions, the identifier token that appears - directly after the interface, + directly after the interface, namespace, dictionary, enum or callback keyword determines the identifier of that definition.
    interface interface-identifier { interface-members… };
     partial interface interface-identifier { interface-members… };
    +namespace namespace-identifier { namespace-members… };
    +partial namespace namespace-identifier { namespace-members… };
     dictionary dictionary-identifier { dictionary-members… };
     partial dictionary dictionary-identifier { dictionary-members… };
     enum enumeration-identifier { enumeration-values… };
    @@ -533,6 +540,7 @@ 

    3.1. Names

    that a given implementation supports, the identifier of every interface, + namespace, dictionary, enumeration, callback function and @@ -540,6 +548,7 @@

    3.1. Names

    MUST NOT be the same as the identifier of any other interface, + namespace, dictionary, enumeration, callback function or @@ -664,8 +673,7 @@

    3.2. Interfaces

    interface-members… };

    - The order that members appear in has no significance except in the - case of overloading. + 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 @@ -783,7 +791,7 @@

    3.2. Interfaces

    its definition. Callback interfaces are ones that can be implemented by user objects and not by platform objects, - as described in section 3.9 + as described in section 3.10 below.

    callback interface identifier {
    @@ -985,7 +993,8 @@ 

    3.2. Interfaces

    [3]CallbackOrInterface"callback" CallbackRestOrInterface
     | Interface
    [4]CallbackRestOrInterfaceCallbackRest
     | Interface
    [5]Interface"interface" identifier Inheritance "{" InterfaceMembers "}" ";"
    [6]Partial"partial" PartialDefinition
    [7]PartialDefinitionPartialInterface
     | - PartialDictionary
    [8]PartialInterface"interface" identifier "{" InterfaceMembers "}" ";"
    [9]InterfaceMembersExtendedAttributeList InterfaceMember InterfaceMembers
     | + PartialDictionary
     | + Namespace
    [8]PartialInterface"interface" identifier "{" InterfaceMembers "}" ";"
    [9]InterfaceMembersExtendedAttributeList InterfaceMember InterfaceMembers
     | ε
    [10]InterfaceMemberConst
     | Operation
     | Serializer
     | @@ -1175,7 +1184,7 @@

    3.2.1. Constants

    as the type of the constant, dictionary member or optional argument it is being used as the value of. The value of the integer token MUST NOT lie outside the valid range of values for its type, as given in - section 3.10 below. + section 3.11 below.

    The value of a float token is @@ -1229,7 +1238,7 @@

    3.2.1. Constants

    as the type of the constant, dictionary member or optional argument it is being used as the value of. The value of the float token MUST NOT lie outside the valid range of values for its type, as given in - section 3.10 below. + section 3.11 below. Also, Infinity, -Infinity and NaN MUST NOT be used as the value of a float or double. @@ -1533,7 +1542,7 @@

    3.2.3. Operations

    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. + 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, @@ -3942,8 +3951,93 @@

    3.2.9. 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. +

    + +
    [6]Partial"partial" PartialDefinition
    [7]PartialDefinitionPartialInterface
     | + PartialDictionary
     | + Namespace
    [97]Namespace"namespace" identifier "{" NamespaceMembers "}" ";"
    [98]NamespaceMembersExtendedAttributeList NamespaceMember NamespaceMembers
     | + ε
    [99]NamespaceMemberReturnType OperationRest
    + + +
    Example
    +

    + The following IDL fragment defines an + namespace. +

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

    + An ECMAScript implementation would then expose a global property named + VectorUtils which was a simple object (with prototype + %ObjectPrototype%) with enumerable data properties for each declared operation: +

    + +
    ECMAScript
    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.3. Dictionaries

    +

    3.4. Dictionaries

    A dictionary is a definition (matching @@ -4194,7 +4288,8 @@

    3.3. Dictionaries

    [EnforceRange].

    [6]Partial"partial" PartialDefinition
    [7]PartialDefinitionPartialInterface
     | - PartialDictionary
    [11]Dictionary"dictionary" identifier Inheritance "{" DictionaryMembers "}" ";"
    [12]DictionaryMembersExtendedAttributeList DictionaryMember DictionaryMembers
     | + PartialDictionary
     | + Namespace
    [11]Dictionary"dictionary" identifier Inheritance "{" DictionaryMembers "}" ";"
    [12]DictionaryMembersExtendedAttributeList DictionaryMember DictionaryMembers
     | ε
    [13]DictionaryMemberRequired Type identifier Default ";"
    [15]PartialDictionary"dictionary" identifier "{" DictionaryMembers "}" ";"
    [16]Default"=" DefaultValue
     | ε
    [17]DefaultValueConstValue
     | string
     | @@ -4241,7 +4336,7 @@

    3.3. Dictionaries

    -

    3.4. Exceptions

    +

    3.5. Exceptions

    An exception is a type of object that @@ -4313,7 +4408,7 @@

    3.4. Exceptions

    Note

    - See section 4.13 + See section 4.14 below for details on what creating and throwing an exception entails in the ECMAScript language binding.

    @@ -4346,7 +4441,7 @@

    3.4. Exceptions

    -

    3.4.1. Error names

    +

    3.5.1. Error names

    The error names table below lists all the allowed error names @@ -4542,7 +4637,7 @@

    3.4.1. Error names

    -

    3.5. Enumerations

    +

    3.6. Enumerations

    An enumeration is a definition (matching @@ -4632,7 +4727,7 @@

    3.5. Enumerations

    -

    3.6. Callback functions

    +

    3.7. Callback functions

    Editorial note

    The “Custom DOM Elements” spec wants to use callback function types for @@ -4691,7 +4786,7 @@

    3.6. Callback functions

    -

    3.7. Typedefs

    +

    3.8. Typedefs

    A typedef is a definition (matching @@ -4741,7 +4836,7 @@

    3.7. Typedefs

    -

    3.8. Implements statements

    +

    3.9. Implements statements

    An implements statement is a definition @@ -4903,7 +4998,7 @@

    3.8. Implements statements

    -

    3.9. Objects implementing interfaces

    +

    3.10. Objects implementing interfaces

    In a given implementation of a set of IDL fragments, @@ -5021,7 +5116,7 @@

    Valuetypes

    -->
    -

    3.10. Types

    +

    3.11. Types

    This section lists the types supported by Web IDL, the set of values @@ -5135,7 +5230,7 @@

    3.10. Types

    ε
    -

    3.10.1. any

    +

    3.11.1. any

    The any type is the union of all other possible @@ -5161,7 +5256,7 @@

    3.10.1. any

    -

    3.10.2. boolean

    +

    3.11.2. boolean

    The boolean type has two values: @@ -5179,7 +5274,7 @@

    3.10.2. boolean

    -

    3.10.3. byte

    +

    3.11.3. byte

    The byte type is a signed integer @@ -5197,7 +5292,7 @@

    3.10.3. byte

    -

    3.10.4. octet

    +

    3.11.4. octet

    The octet type is an unsigned integer @@ -5215,7 +5310,7 @@

    3.10.4. octet

    -

    3.10.5. short

    +

    3.11.5. short

    The short type is a signed integer @@ -5233,7 +5328,7 @@

    3.10.5. short

    -

    3.10.6. unsigned short

    +

    3.11.6. unsigned short

    The unsigned short type is an unsigned integer @@ -5251,7 +5346,7 @@

    3.

    -

    3.10.7. long

    +

    3.11.7. long

    The long type is a signed integer @@ -5269,7 +5364,7 @@

    3.10.7. long

    -

    3.10.8. unsigned long

    +

    3.11.8. unsigned long

    The unsigned long type is an unsigned integer @@ -5287,7 +5382,7 @@

    3.10

    -

    3.10.9. long long

    +

    3.11.9. long long

    The long long type is a signed integer @@ -5305,7 +5400,7 @@

    3.10.9. long

    -

    3.10.10. unsigned long long

    +

    3.11.10. unsigned long long

    The unsigned long long type is an unsigned integer @@ -5323,7 +5418,7 @@

    -

    3.10.11. float

    +

    3.11.11. float

    The float type is a floating point numeric @@ -5351,7 +5446,7 @@

    3.10.11. float

    -

    3.10.12. unrestricted float

    +

    3.11.12. unrestricted float

    The unrestricted float type is a floating point numeric @@ -5370,7 +5465,7 @@

    -

    3.10.13. double

    +

    3.11.13. double

    The double type is a floating point numeric @@ -5389,7 +5484,7 @@

    3.10.13. double
    -

    3.10.14. unrestricted double

    +

    3.11.14. unrestricted double

    The unrestricted double type is a floating point numeric @@ -5408,7 +5503,7 @@

    -

    3.10.15. DOMString

    +

    3.11.15. DOMString

    The DOMString type @@ -5501,7 +5596,7 @@

    3.10.15. DO

    -

    3.10.16. ByteString

    +

    3.11.16. ByteString

    The ByteString type @@ -5538,7 +5633,7 @@

    3.10.16.

    -

    3.10.17. USVString

    +

    3.11.17. USVString

    The USVString type @@ -5571,7 +5666,7 @@

    3.10.17. US

    -

    3.10.18. object

    +

    3.11.18. object

    The object type corresponds to the set of @@ -5593,7 +5688,7 @@

    3.10.18. object
    -

    3.10.19. Interface types

    +

    3.11.19. Interface types

    An identifier that @@ -5630,7 +5725,7 @@

    3.10.19. Interface types

    -

    3.10.20. Dictionary types

    +

    3.11.20. Dictionary types

    An identifier that @@ -5648,7 +5743,7 @@

    3.10.20. Dictionary types

    -

    3.10.21. Enumeration types

    +

    3.11.21. Enumeration types

    An identifier that @@ -5671,7 +5766,7 @@

    3.10.21. Enumeration types

    -

    3.10.22. Callback function types

    +

    3.11.22. Callback function types

    An identifier that identifies @@ -5699,7 +5794,7 @@

    3.10.22. Callback function types

    -

    3.10.23. Nullable types — T?

    +

    3.11.23. Nullable types — T?

    A nullable type is an IDL type constructed @@ -5753,7 +5848,7 @@

    3.10.23. Nullable types — T?

    -

    3.10.24. Sequences — sequence<T>

    +

    3.11.24. Sequences — sequence<T>

    The sequence<T> @@ -5794,7 +5889,7 @@

    -

    3.10.25. Promise types — Promise<T>

    +

    3.11.25. Promise types — Promise<T>

    A promise type is a parameterized type @@ -5815,7 +5910,7 @@

    -

    3.10.26. Union types

    +

    3.11.26. Union types

    A union type is a type whose set of values @@ -5959,7 +6054,7 @@

    3.10.26. Union types

    -

    3.10.27. RegExp

    +

    3.11.27. RegExp

    The RegExp type is a type @@ -5978,7 +6073,7 @@

    3.10.27. RegExp
    -

    3.10.28. Error

    +

    3.11.28. Error

    The Error type corresponds to the set of all possible non-null references to exception objects, including @@ -5995,7 +6090,7 @@

    3.10.28. Error

    -

    3.10.29. DOMException

    +

    3.11.29. DOMException

    The DOMException type corresponds to the set of all possible non-null references to objects @@ -6011,7 +6106,7 @@

    3.10.29. DOMException

    -

    3.10.30. Buffer source types

    +

    3.11.30. Buffer source types

    There are a number of types that correspond to sets of all possible non-null @@ -6104,7 +6199,7 @@

    3.10.30. Buffer source types

    -

    3.10.31. Frozen arrays — FrozenArray<T>

    +

    3.11.31. Frozen arrays — FrozenArray<T>

    A frozen array type is a parameterized @@ -6128,13 +6223,14 @@

    -

    3.11. Extended attributes

    +

    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. @@ -6380,7 +6476,7 @@

    4. ECMAScript binding

    @@ -8720,13 +8825,18 @@

    4.3.4. [Exposed]

    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 on both an interface - and one of its interface members, then the interface member's - exposure set - MUST be a subset of the interface's - exposure set. + 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 @@ -8745,17 +8855,12 @@

    4.3.4. [Exposed]

    Y.

    - An interface or - interface member - is exposed in a given ECMAScript global environment if - the ECMAScript global object implements an interface that is in the - interface or interface member's - exposure set, - and either: + 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:

    Note

    Since it is not possible for the relevant settings object @@ -8778,9 +8883,9 @@

    4.3.4. [Exposed]

    Example

    [Exposed] - is intended to be used to control whether interfaces or individual interface - members are available for use only in workers, only in the Window, - or in both.

    + 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 {
    @@ -8800,24 +8905,45 @@ 

    4.3.4. [Exposed]

    ... }; -// MathUtils is available for use in workers and on the main thread. -[Exposed=(Window,Worker)] -interface MathUtils { - static double someComplicatedFunction(double x, double y); +// 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; }; -// WorkerUtils is only available in workers. Evaluating WorkerUtils +// 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 WorkerUtils { - static void setPriority(double x); +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); };
    @@ -9965,8 +10091,11 @@

    4.3.18. [SecureContext]

    extended attribute appears on an interface, partial interface, - an individual interface member, - it indicates that the interface or interface member is exposed + namespace, + partial namespace, + interface member, or + namespace member, + it indicates that the construct is exposed only within a secure context ([SECURE-CONTEXTS], section 2). @@ -9981,8 +10110,11 @@

    4.3.18. [SecureContext]

    extended attribute MUST NOT be used on anything other than an interface, - partial interface, or - an individual interface member. + partial interface, + namespace, + partial namespace, + interface member, or + namespace member.

    Whether a construct that the [SecureContext] @@ -10005,14 +10137,23 @@

    4.3.18. [SecureContext]

    depends on the type of construct:

    interface
    -
    The interface or dictionary is not +
    namespace
    +
    The interface or namespace is not available only in secure contexts.
    +
    partial interface
    -
    The partial interface is available only in secure contexts - if and only if the original interface definition is.
    +
    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.
    @@ -10031,9 +10172,10 @@

    4.3.18. [SecureContext]

    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. + 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 @@ -10928,7 +11070,7 @@

    4.6.1. Interface object

  • If the interface doesn't inherit from any other interface, the value of [[Prototype]] is - %FunctionPrototype% ([ECMA-262], section 6.1.7.4). + %FunctionPrototype%.
  • @@ -11237,7 +11379,7 @@

    4.6.3. 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 6.1.7.4). +
  • Otherwise, return %ObjectPrototype%. ([ECMA-262], section 15.2.4).
  • Note
    @@ -11327,7 +11469,7 @@

    4.6.4. Named properties 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 6.1.7.4).
  • +
  • Otherwise, return %ObjectPrototype%.
  • The class string of a @@ -11885,6 +12027,105 @@

    4.6.7. Operations

    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.

    + +
      +
    1. + Let id be op's identifier. +
    2. + + +
    3. + Let steps be the following series of steps, given function argument + values arg0..n−1: + +
        +
      1. + Try running the following steps: +
          +
        1. + Let S be the effective overload set for regular operations with + identifier id on + namespace namespace + and with argument count n. +
        2. + +
        3. + Let <operation, values> be the result of passing + S and arg0..n−1 to the overload resolution + algorithm. +
        4. + +
        5. + Let R be the result of performing the actions listed in the + description of operation with values as the argument + values. +
        6. + +
        7. + Return the result of converting R to + an ECMAScript value of the type op is declared to return. +
        8. +
        +
      2. +
      + + And then, if an exception was thrown: + +
        +
      1. + If the operation has a return type + that is a promise type, then: + +
          +
        1. + Let reject be the initial value of %Promise%.reject. +
        2. +
        3. + Return the result of calling reject with %Promise% as the this object + and the exception as the single argument value. +
        4. +
        +
      2. +
      3. + Otherwise, end these steps and allow the exception to propagate. +
      4. +
      +
    4. + +
    5. + Let F be ! CreateBuiltinFunction(realm, + steps, the %FunctionPrototype% of realm). +
    6. + +
    7. + Perform ! SetFunctionName(F, id). +
    8. + +
    9. + Let S be the effective overload set for regular operations with identifier id on namespace namespace and with argument count 0. +
    10. + +
    11. + Let length be the length of the shortest argument list in the entries in + S. +
    12. + +
    13. + Perform ! DefinePropertyOrThrow(F, "length", + PropertyDescriptor{[[Value]]: length, + [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true}). +
    14. +
    +
    4.6.7.1. Stringifiers
    @@ -13975,7 +14216,7 @@

    4.8.10. Property enumeration

    4.9. User objects implementing callback interfaces

    - As described in section 3.9 above, + 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 @@ -14398,8 +14639,58 @@

    4.10. Invoking callback functions

    +
    +

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

    + +
      +
    1. + Let namespaceObject be + ! ObjectCreate(the %ObjectPrototype% of realm). +
    2. + +
    3. + For each exposed regular operation op that is a namespace member of this namespace, + +
        +
      1. + Let F be the result of creating an operation function given + op, namespace, and realm. +
      2. + +
      3. + Perform ! CreateDataProperty(namespaceObject, + op's identifier, + F). +
      4. +
      +
    4. +
    +
    +
    +
    -

    4.11. Exceptions

    +

    4.12. Exceptions

    There MUST exist a property on the ECMAScript global object @@ -14411,7 +14702,7 @@

    4.11. Exceptions

    -

    4.11.1. DOMException constructor object

    +

    4.12.1. DOMException constructor object

    The DOMException constructor object MUST be a function object @@ -14432,7 +14723,7 @@

    4.11.1. DOMException constructor object

    -
    4.11.1.1. DOMException(message, name)
    +
    4.12.1.1. DOMException(message, name)

    When the DOMException function is called with arguments message and name, the following steps are taken:

    @@ -14459,7 +14750,7 @@
    4.11.1.1. DOMException(message, name)
    -

    4.11.2. DOMException prototype object

    +

    4.12.2. DOMException prototype object

    The DOMException prototype object MUST @@ -14486,7 +14777,7 @@

    4.11.2. DOMException prototype object

    -

    4.12. Exception objects

    +

    4.13. Exception objects

    Simple exceptions are represented @@ -14529,7 +14820,7 @@

    4.12. Exception objects

    -

    4.13. Creating and throwing exceptions

    +

    4.14. Creating and throwing exceptions

    First, we define the current global environment @@ -14668,7 +14959,7 @@

    4.13. Creating and throwing exceptions

    -

    4.14. Handling exceptions

    +

    4.15. Handling exceptions

    None of the algorithms or processing requirements in the @@ -15044,6 +15335,7 @@

    A. IDL grammar

    [1]DefinitionsExtendedAttributeList Definition Definitions
     | ε
    [2]DefinitionCallbackOrInterface
     | + Namespace
     | Partial
     | Dictionary
     | Enum
     | @@ -15051,7 +15343,8 @@

    A. IDL grammar

    ImplementsStatement
    [3]CallbackOrInterface"callback" CallbackRestOrInterface
     | Interface
    [4]CallbackRestOrInterfaceCallbackRest
     | Interface
    [5]Interface"interface" identifier Inheritance "{" InterfaceMembers "}" ";"
    [6]Partial"partial" PartialDefinition
    [7]PartialDefinitionPartialInterface
     | - PartialDictionary
    [8]PartialInterface"interface" identifier "{" InterfaceMembers "}" ";"
    [9]InterfaceMembersExtendedAttributeList InterfaceMember InterfaceMembers
     | + PartialDictionary
     | + Namespace
    [8]PartialInterface"interface" identifier "{" InterfaceMembers "}" ";"
    [9]InterfaceMembersExtendedAttributeList InterfaceMember InterfaceMembers
     | ε
    [10]InterfaceMemberConst
     | Operation
     | Serializer
     | @@ -15241,7 +15534,8 @@

    A. IDL grammar

    ε
    [87]PromiseType"Promise" "<" ReturnType ">"
    [88]Null"?"
     | ε
    [89]ReturnTypeType
     | "void"
    [90]IdentifierListidentifier Identifiers
    [91]Identifiers"," identifier Identifiers
     | - ε
    [92]ExtendedAttributeNoArgsidentifier
    [93]ExtendedAttributeArgListidentifier "(" ArgumentList ")"
    [94]ExtendedAttributeIdentidentifier "=" identifier
    [95]ExtendedAttributeIdentListidentifier "=" "(" IdentifierList ")"
    [96]ExtendedAttributeNamedArgListidentifier "=" identifier "(" ArgumentList ")"
    + ε

    [92]ExtendedAttributeNoArgsidentifier
    [93]ExtendedAttributeArgListidentifier "(" ArgumentList ")"
    [94]ExtendedAttributeIdentidentifier "=" identifier
    [95]ExtendedAttributeIdentListidentifier "=" "(" IdentifierList ")"
    [96]ExtendedAttributeNamedArgListidentifier "=" identifier "(" ArgumentList ")"
    [97]Namespace"namespace" identifier "{" NamespaceMembers "}" ";"
    [98]NamespaceMembersExtendedAttributeList NamespaceMember NamespaceMembers
     | + ε
    [99]NamespaceMemberReturnType OperationRest
    Note

    The Other @@ -15260,7 +15554,7 @@

    A. IDL grammar

    only a subset of those possible sequences are used by the extended attributes defined in this specification — see - section 3.11 + section 3.12 for the syntaxes that are used by these extended attributes.

    diff --git a/index.xml b/index.xml index d559f5f4..692337d6 100644 --- a/index.xml +++ b/index.xml @@ -76,11 +76,11 @@ - + - + @@ -151,6 +151,14 @@ href='https://tc39.github.io/ecma262/#sec-completion-record-specification-type'/> + + + +
  • IDL fragment are: interfaces, partial interface definitions, + namespaces, + partial namespace definitions, dictionaries, partial dictionary definitions, typedefs and @@ -506,6 +516,8 @@ interface GraphicalWindow {

    Every interface, partial interface definition, + namespace, + partial namespace definition, dictionary, partial dictionary definition, enumeration, @@ -524,12 +536,14 @@ interface GraphicalWindow {

  • For named definitions, the identifier token that appears - directly after the interface, + directly after the interface, namespace, dictionary, enum or callback keyword determines the identifier of that definition.
    interface interface-identifier { interface-members… };
     partial interface interface-identifier { interface-members… };
    +namespace namespace-identifier { namespace-members… };
    +partial namespace namespace-identifier { namespace-members… };
     dictionary dictionary-identifier { dictionary-members… };
     partial dictionary dictionary-identifier { dictionary-members… };
     enum enumeration-identifier { enumeration-values… };
    @@ -622,6 +636,7 @@ dictionary identifier {
                 that a given implementation supports,
                 the identifier of every
                 interface,
    +            namespace,
                 dictionary,
                 enumeration,
                 callback function and
    @@ -629,6 +644,7 @@ dictionary identifier {
                 MUST NOT
                 be the same as the identifier of any other
                 interface,
    +            namespace,
                 dictionary,
                 enumeration,
                 callback function or
    @@ -753,8 +769,8 @@ interface TextField {
       interface-members…
     };

    - The order that members appear in has no significance except in the - case of overloading. + 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 @@ -1594,7 +1610,9 @@ interface Person : Animal { then it declares a special operation. A single operation can declare both a regular operation and a special operation; see section - for details on 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, @@ -3945,6 +3963,98 @@ setlike<type>; +

    +

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

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

    + + + + +
    +

    + 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 + VectorUtils which 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 }. +
    + +
    +

    Dictionaries

    @@ -6091,6 +6201,7 @@ interface Person { 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. @@ -8555,9 +8666,12 @@ context.setColorEnforcedRange(-1, 255, 256); If the [Exposed] extended attribute appears on an interface, - partial interface, or - an individual interface member, - it indicates that the interface or interface member is exposed + 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.

    @@ -8595,17 +8709,23 @@ context.setColorEnforcedRange(-1, 255, 256); implicitly, depending on the type of construct:

    interface
    -
    The exposure set of the interface - only contains the +
    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 is the exposure set of the original - interface definition.
    + 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.
  • @@ -8618,13 +8738,20 @@ context.setColorEnforcedRange(-1, 255, 256); 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 on both an interface - and one of its interface members, then the interface member's - exposure set - MUST be a subset of the interface's - exposure set. + 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 @@ -8644,17 +8771,17 @@ context.setColorEnforcedRange(-1, 255, 256); Y.

    - An interface or - interface member - is exposed in a given ECMAScript global environment if - the ECMAScript global object implements an interface that is in the - interface or interface member's - exposure set, - and either: + 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:

    Since it is not possible for the relevant settings object @@ -8677,9 +8804,9 @@ context.setColorEnforcedRange(-1, 255, 256);

    [Exposed] - is intended to be used to control whether interfaces or individual interface - members are available for use only in workers, only in the Window, - or in both.

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

    [PrimaryGlobal] interface Window { @@ -8699,24 +8826,45 @@ interface DedicatedWorkerGlobalScope : WorkerGlobalScope { ... }; -// MathUtils is available for use in workers and on the main thread. -[Exposed=(Window,Worker)] -interface MathUtils { - static double someComplicatedFunction(double x, double y); +// 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; }; -// WorkerUtils is only available in workers. Evaluating WorkerUtils +// 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 WorkerUtils { - static void setPriority(double x); +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); };
    @@ -9866,8 +10014,11 @@ counter.value; / extended attribute appears on an interface, partial interface, - an individual interface member, - it indicates that the interface or interface member is exposed + namespace, + partial namespace, + interface member, or + namespace member, + it indicates that the construct is exposed only within a secure context ([SECURE-CONTEXTS], section 2). @@ -9882,8 +10033,11 @@ counter.value; / extended attribute MUST NOT be used on anything other than an interface, - partial interface, or - an individual interface member. + partial interface, + namespace, + partial namespace, + interface member, or + namespace member.

    Whether a construct that the [SecureContext] @@ -9906,14 +10060,24 @@ counter.value; / depends on the type of construct:

    interface
    -
    The interface or dictionary is not +
    namespace
    +
    The interface or namespace is not available only in secure contexts.
    +
    partial interface
    -
    The partial interface is available only in secure contexts - if and only if the original interface definition is.
    +
    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.
    @@ -9932,9 +10096,10 @@ counter.value; /

    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. + 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 @@ -11792,6 +11957,118 @@ interface 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.

    + +
      +
    1. + Let id be op's identifier. +
    2. + + +
    3. + Let steps be the following series of steps, given function argument + values arg0..n−1: + +
        +
      1. + Try running the following steps: +
          +
        1. + Let S be the effective overload set for regular operations with + identifier id on + namespace namespace + and with argument count n. +
        2. + +
        3. + Let <operation, values> be the result of passing + S and arg0..n−1 to the overload resolution + algorithm. +
        4. + +
        5. + Let R be the result of performing the actions listed in the + description of operation with values as the argument + values. +
        6. + +
        7. + Return the result of converting R to + an ECMAScript value of the type op is declared to return. +
        8. +
        +
      2. +
      + + And then, if an exception was thrown: + +
        +
      1. + If the operation has a return type + that is a promise type, then: + +
          +
        1. + Let reject be the initial value of %Promise%.reject. +
        2. +
        3. + Return the result of calling reject with %Promise% as the this object + and the exception as the single argument value. +
        4. +
        +
      2. +
      3. + Otherwise, end these steps and allow the exception to propagate. +
      4. +
      +
    4. + +
    5. + Let F be ! CreateBuiltinFunction(realm, + steps, the %FunctionPrototype% of realm). +
    6. + +
    7. + Perform ! SetFunctionName(F, id). +
    8. + +
    9. + Let S be the effective overload set for regular operations with identifier id on namespace namespace and with argument count 0. +
    10. + +
    11. + Let length be the length of the shortest argument list in the entries in + S. +
    12. + +
    13. + Perform ! DefinePropertyOrThrow(F, "length", + PropertyDescriptor{[[Value]]: length, + [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true}). +
    14. +
    +
    Stringifiers
    @@ -14360,6 +14637,63 @@ C implements A;
    +
    +

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

    + +
    +

    Namespace object

    + +

    + The namespace object for a given namespace + namespace and Realm realm is created as + follows: +

    + +
      +
    1. + Let namespaceObject be + ! ObjectCreate(the %ObjectPrototype% of realm). +
    2. + +
    3. + For each exposed regular operation op that is a namespace member of this namespace, + +
        +
      1. + Let F be the result of creating an operation function given + op, namespace, and realm. +
      2. + +
      3. + Perform ! CreateDataProperty(namespaceObject, + op's identifier, + F). +
      4. +
      +
    4. +
    +
    +
    +

    Exceptions

    @@ -15006,12 +15340,12 @@ d.type = et; ExtendedAttributeList Definition Definitions | ε - CallbackOrInterface | Partial | Dictionary | Enum | Typedef | ImplementsStatement + CallbackOrInterface | Namespace | Partial | Dictionary | Enum | Typedef | ImplementsStatement "callback" CallbackRestOrInterface | Interface CallbackRest | Interface "interface" identifier Inheritance "{" InterfaceMembers "}" ";" "partial" PartialDefinition - PartialInterface | PartialDictionary + PartialInterface | PartialDictionary | Namespace "interface" identifier "{" InterfaceMembers "}" ";" ExtendedAttributeList InterfaceMember InterfaceMembers | ε Const | Operation | Serializer | Stringifier | StaticMember | Iterable | ReadOnlyMember | ReadWriteAttribute | ReadWriteMaplike | ReadWriteSetlike @@ -15144,6 +15478,11 @@ d.type = et; identifier "=" "(" IdentifierList ")" identifier "=" identifier "(" ArgumentList ")" + "namespace" identifier "{" NamespaceMembers "}" ";" + + ExtendedAttributeList NamespaceMember NamespaceMembers | ε + ReturnType OperationRest +