diff --git a/index.bs b/index.bs index 31c78b05..75bac32a 100644 --- a/index.bs +++ b/index.bs @@ -818,12 +818,25 @@ across [=IDL fragments=].

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 InterfaceRest) that declares some -state and behavior that an object implementing that interface will expose. +Web IDL is 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 an entity that can be implemented by +particular objects and that describes the behavior of the objects that implement it. +The objects implement a single primary interface, as well as any interface that the primary +interface [=interface/inherits=] from. + +In bindings for object oriented languages, it is expected that an object that implements a +particular [=interface=] provides ways to inspect and modify the object's state and to invoke the +behavior described by the [=interface=]. +The relevant language binding determines how [=interfaces=] correspond to constructs in the +language. + +An [=interface=] must exist for every [=definition=] matching interface +InterfaceRest in an [=IDL fragment=] supported +by the implementation. +This [=definition=] defines the [=interface's=] [=identifier=]. 
     [extended_attributes]
@@ -832,25 +845,126 @@ state and behavior that an object implementing that interface will expose.
     };
-An interface is a specification of a set of -interface members -(matching InterfaceMembers). -These are the [=members=] that appear between the braces in the interface declaration. +The following [=extended attributes=] are applicable to interface [=definitions=]: +[{{Exposed}}], +[{{Global}}], +[{{LegacyNamespace}}], +[{{LegacyWindowAlias}}], +[{{NamedConstructor}}], +[{{NoInterfaceObject}}], +[{{OverrideBuiltins}}], and +[{{SecureContext}}]. + +If an interface [=definition=] is annotated with an [=extended attribute=], the [=interface=] +itself is also considered to be annotated with that [=extended attribute=] + +[=Interfaces=] which are not annotated with a [{{NoInterfaceObject}}] [=extended attribute=] must +be annotated with an [{{Exposed}}] [=extended attribute=]. + + +
+ +The qualified name of an [=interface=] |interface| is defined as follows: + +1. Let |identifier| be the [=identifier=] of |interface|. +1. If |interface| has a [{{LegacyNamespace}}] [=extended attribute=], then: + 1. Let |namespace| be the identifier argument of the [{{LegacyNamespace}}] + [=extended attribute=]. + 1. Return the [=concatenation=] of « |namespace|, |identifier| » with + separator U+002E FULL STOP ("."). +1. Return |identifier|. + +
+ + +

Members

+ +An [=interface=] contains a [=list=] of [=interface members=], which define most of the behavior +of the objects that implement it. These can be declared in several locations: + +* as part of the initial interface [=definition=]; +* as part of a [=partial interface=] [=definition=]; +* as part of an [=interface mixin=] or a [=partial interface mixin=] [=definition=], using an + [=includes statement=] to associate them with the [=interface=]. + +
+ +The interface members of an +[=interface=] |I| are given by the following algorithm: + +1. Let |members| be « ». +1. Let |initialDefinition| be the [=definition=] that matches interface + InterfaceRest, and whose [=identifier=] + matches |I|'s. +1. Let |initialMembers| be the [=list=] of [=members=] defined by the + InterfaceMembers non-terminal in + |initialDefinition|. +1. [=list/Extend=] |members| with |initialMembers|. +1. Let |partialDefinitions| be the unordered [=/set=] of [=definitions=] that match + partial interface + PartialInterfaceRest, and whose + [=identifier=] matches |I|'s. +1. [=set/For each=] |partialDefinition| of |partialDefinitions|: + 1. Let |partialMembers| be the [=list=] of [=members=] defined by the + InterfaceMembers non-terminal in + |partialDefinition|. + 1. [=list/Extend=] |members| with |partialMembers|. +1. Let |mixins| be the unordered [=/set=] of [=interface mixins=] that |I| [=includes=]. +1. [=set/For each=] |mixin| of |mixins|: + 1. Let |mixinMembers| be |mixin|'s [=interface mixin members=]. + + Note: This includes any [=members=] defined in [=partial interface mixins=]. + 1. [=list/For each=] |member| of |mixinMembers|: + 1. Let |hostMember| be a copy of |member|. + 1. Set |hostMember|'s [=host interface=] to |I|. + 1. [=list/Append=] |hostMember| to |members|. +1. Return |members|. + +Note: The [=interface members=] of [=interface=] that |I| [=interface/inherits=] from are not +included. + +Note: The order that members appear in has significance for property enumeration in the +ECMAScript binding. + +Note: There are web compatibility requirements for the order of the members within a particular +[=definition=] (involving {{CanvasPath/arc()}} and {{CanvasPath/arcTo()}}). We are not +currently aware of any other web compatibility requirements. + +Issue(heycam/webidl#432): The order of the members is yet to be defined precisely. +
+ +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. + +
+    [extended_attributes]
+    interface identifier {
+      [extended_attributes]
+      const type constant_identifier = 42;
+
+      [extended_attributes]
+      attribute type identifier;
+
+      [extended_attributes]
+      return_type identifier(/* arguments... */);
+    };
+
+ + +

Inheritance

+ +If the Inheritance production of this +[=definition=] matches : +identifier, this [=interface=] +inherits from the [=interface=] +whose [=identifier=] matches the identifier. +There must be such an [=interface=]. -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. +An object that implements an [=interface=] that [=interface/inherits=] from another is also +considered to implement that inherited [=interface=]. + +Note: General multiple inheritance is not supported. 
     interface identifier : identifier_of_inherited_interface {
@@ -858,8 +972,6 @@ have members that correspond to the interface members from the inherited interfa
     };
-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 @@ -929,33 +1041,8 @@ interface |B| that inherits from |A|, and so on. 1. Return |result|. -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 [=includes statement=] can be used -to define that objects implementing an [=interface=] |A| -will always also include the [=interface mixin member|members=] -of the [=interface mixins=] |A| [=includes=]. - -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. - -
-    [extended_attributes]
-    interface identifier {
-
-      [extended_attributes]
-      const type constant_identifier = 42;
 
-      [extended_attributes]
-      attribute type identifier;
-
-      [extended_attributes]
-      return_type identifier(/* arguments... */);
-    };
-
+

Partial interfaces

The IDL for interfaces can be split into multiple parts by using partial interface definitions @@ -963,9 +1050,7 @@ The IDL for interfaces can be split into multiple parts by using PartialInterfaceRest). 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. +as the identifier of an interface definition. 
     interface SomeInterface {
@@ -990,40 +1075,13 @@ Note: A partial interface definition cannot specify that the interface
 Inheritance must be specified on the original [=interface=]
 definition.
 
-The relevant language binding determines how interfaces correspond to constructs
-in the language.
-
-The following extended attributes are applicable to interfaces:
-[{{Exposed}}],
-[{{Global}}],
-[{{LegacyWindowAlias}}],
-[{{NamedConstructor}}],
-[{{NoInterfaceObject}}],
-[{{OverrideBuiltins}}], and
-[{{SecureContext}}].
-
-The following extended attributes are applicable to [=partial interfaces=]:
+The following extended attributes are applicable to [=partial interface=] [=definitions=]:
 [{{Exposed}}],
 [{{OverrideBuiltins}}], and
 [{{SecureContext}}].
 
-[=Interfaces=] which are not annotated
-with a [{{NoInterfaceObject}}] [=extended attribute=]
-must be annotated with an [{{Exposed}}] [=extended attribute=].
-
-

-
-The qualified name of an [=interface=] |interface| is defined as follows:
-
-1.  Let |identifier| be the [=identifier=] of |interface|.
-1.  If |interface| has a [{{LegacyNamespace}}] [=extended attribute=], then:
-    1.  Let |namespace| be the identifier argument of the [{{LegacyNamespace}}]
-        [=extended attribute=].
-    1.  Return the [=concatenation=] of « |namespace|, |identifier| » with
-        separator U+002E FULL STOP (".").
-1. Return |identifier|.
 
-

+
Syntax

 
 
     CallbackOrInterfaceOrMixin :
@@ -1188,11 +1246,16 @@ The qualified name of an [=interface=] |interface| is defined as foll
 
 
Interface mixins

 
-An interface mixin is a definition (matching interface MixinRest)
-that declares state and behavior that can be [=included=] by one or more [=interfaces=],
+An interface mixin is an entity that declares state and behavior in the form of
+[=interface mixin members=] that can be [=included=] by one or more [=interfaces=],
 and that are exposed by objects that implement an [=interface=]
 that [=includes=] the [=interface mixin=].
 
+An [=interface mixin=] must exist for every [=definition=] matching interface
+MixinRest in an [=IDL fragment=] supported by the
+implementation.
+This [=definition=] defines the [=interface mixin's=] [=identifier=].
+
 
     interface mixin identifier {
       /* mixin_members... */
@@ -1207,28 +1270,89 @@ They are not meant to be exposed through language bindings.
 Guidance on when to choose [=partial interfaces=], [=interface mixins=],
 or [=partial interface mixins=] can be found in [[#using-mixins-and-partials]].
 
-An [=interface mixin=] is a specification of a set of interface mixin members
-(matching MixinMembers),
-which are the [=constants=], [=regular operations=], [=regular attributes=], and [=stringifiers=]
-that appear between the braces in the [=interface mixin=] declaration.
+Note: Unlike [=interfaces=] or [=dictionaries=], [=interface mixins=] do not create types.
+
+Of the extended attributes defined in this specification,
+only the [{{Exposed}}] and [{{SecureContext}}] extended attributes
+are applicable to [=interface mixins=].
 
-These [=constants=], [=regular operations=], [=regular attributes=], and [=stringifiers=]
-describe the behaviors that can be implemented by an object,
-as if they were specified on the [=interface=] that [=includes=] them.
 
-[=Static attributes=], [=static operations=], [=special operations=] except for [=stringifiers=], and
-[=iterable declaration|iterable=], [=asynchronously iterable declaration|asynchronously iterable=],
-[=maplike declaration|maplike=], and [=setlike declarations=] cannot appear in [=interface mixin=]
-declarations.
+
Members

+
+An [=interface mixin=] contains a [=list=] of [=interface mixin members=], which define most of its
+behavior. These can be declared in the initial interface mixin [=definition=] as well as in a
+[=partial interface mixin=] [=definition=].
+
+

+
+The interface mixin members of an [=interface mixin=]
+|M| are given by the following algorithm:
+
+1.  Let |members| be « ».
+1.  Let |initialDefinition| be the [=definition=] that matches interface
+    MixinRest, and whose [=identifier=] matches
+    |M|'s.
+1.  Let |initialMembers| be the [=list=] of [=members=] defined by the
+    MixinMembers non-terminal in
+    |initialDefinition|.
+1.  [=list/Extend=] |members| with |initialMembers|.
+1.  Let |partialDefinitions| be the unordered [=/set=] of [=definitions=] that match
+    partial interface
+    MixinRest.
+1.  [=set/For each=] |partialDefinition| of |partialDefinitions|:
+    1.  Let |partialMembers| be the [=list=] of [=members=] defined by the
+        MixinMembers non-terminal in
+        |partialDefinition|.
+    1.  [=list/Extend=] |members| with |partialMembers|.
+1.  Return |members|.
+
+Note: The result includes [=constants=], [=regular operations=], [=regular attributes=], and
+[=stringifiers=].
+[=Static attributes=], [=static operations=], [=special operations=] except for
+[=stringifiers=], and [=iterable declaration|iterable=],
+[=asynchronously iterable declaration|asynchronously iterable=],
+[=maplike declaration|maplike=], and [=setlike declarations=] cannot be included in the
+MixinMembers non-terminal.
+
+Note: The order that members appear in has significance for property enumeration
+in the ECMAScript binding.
+
+Issue(heycam/webidl#432): The order of the members is yet to be defined precisely.
+

+
+[=Interface mixin members=] have a host interface, which is initially unset.
+
+Note: The [=host interface=] of an [=interface mixin member=] is used to decide whether the
+[=interface mixin member|member=] is [=exposed=].
+
+Note: When an [=interface=] |I| [=interface/includes=] an [=interface mixin=] |M|, |I|'s [=list=]
+of [=interface members=] has a copy of each of the [=interface mixin member|members=] of |M|,
+with their [=host interface=] set to |I|.
+In particular, if two [=interfaces=] [=interface/include=] a single [=interface mixin=], each
+[=interface=] gets an independent copy of the [=interface mixin members|members=].
+
+Note: In ECMAScript, this implies that each [=regular operation=]
+declared as a [=interface mixin member|member=] of [=interface mixin=] |M|,
+and exposed as a data property with a [=built-in function object=] value,
+is a distinct [=built-in function object=]
+in each [=interface prototype object=]
+whose associated [=interface=] [=includes=] |M|.
+Similarly, for [=attributes=], each copy of the accessor property has
+distinct [=built-in function objects=] for its getters and setters.
+
+
+
Partial interface mixins

 
 As with interfaces, the IDL for [=interface mixins=] can be split into multiple parts by using
 partial interface mixin definitions
 (matching partial interface MixinRest).
 The [=identifier=] of a [=partial interface mixin=] [=definition=] must
 be the same as the [=identifier=] of an [=interface mixin=] [=definition=].
-All of the [=interface mixin member|members=] that appear on each of the [=partial interface mixin=] [=definitions=]
-are considered to be [=members=] of the [=interface mixin=] itself,
-and—by extension—of the [=interfaces=] that [=include=] the [=interface mixin=].
+
+Note: All of the [=interface mixin member|members=] that appear on each of the
+[=partial interface mixin=] [=definitions=] are considered to be [=interface mixin member|members=]
+of the [=interface mixin=] itself, and—by extension—[=interface members=] of the [=interfaces=]
+that [=include=] the [=interface mixin=].
 
 
     interface mixin SomeMixin {
@@ -1240,20 +1364,14 @@ and—by extension—of the [=interfaces=] that [=include=] the [=interface mixi
     };
 

 
-The order that members appear in has significance for property enumeration
-in the ECMAScript binding.
 
-Note that unlike [=interfaces=] or [=dictionaries=], [=interface mixins=] do not create types.
-
-Of the extended attributes defined in this specification,
-only the [{{Exposed}}] and [{{SecureContext}}] extended attributes
-are applicable to [=interface mixins=].
+
Includes statements

 
 An includes statement is a definition
 (matching IncludesStatement)
-used to declare that all objects implementing an [=interface=] |I|
+used to declare that the [=interface members|members=] of an [=interface=] |I|
 (identified by the first [=identifier=])
-must additionally include the [=interface mixin member|members=] of [=interface mixin=] |M|
+will additionally include the [=interface mixin member|members=] of [=interface mixin=] |M|
 (identified by the second identifier).
 [=Interface=] |I| is said to include
 [=interface mixin=] |M|.
@@ -1265,32 +1383,6 @@ must additionally include the [=interface mixin member|members=] of [=interface
 The first [=identifier=] must reference a [=interface=] |I|.
 The second identifier must reference an [=interface mixin=] |M|.
 
-Each [=interface mixin member|member=] of |M| is considered to be
-a [=member=] of each [=interface=] |I|, |J|, |K|, … that [=includes=] |M|,
-as if a copy of each [=interface mixin member|member=] had been made.
-So for a given member m of |M|,
-interface |I| is considered to have a [=member=] mI,
-interface |J| is considered to have a [=member=] mJ,
-interface |K| is considered to have a [=member=] mK, and so on.
-The host interfaces of mI, mJ,
-and mK, are |I|, |J|, and |K| respectively.
-
-Note: In ECMAScript, this implies that each [=regular operation=]
-declared as a [=interface mixin member|member=] of [=interface mixin=] |M|,
-and exposed as a data property with a [=built-in function object=] value,
-is a distinct [=built-in function object=]
-in each [=interface prototype object=]
-whose associated [=interface=] [=includes=] |M|.
-Similarly, for [=attributes=], each copy of the accessor property has
-distinct [=built-in function objects=] for its getters and setters.
-
-The order of appearance of [=includes statements=] affects the order in which [=interface mixin=]
-are [=included=] by their [=host interface=].
-
-Issue: [=interface mixin member|Member=] order isn't clearly specified,
-in particular when [=interface mixins=] are defined in separate documents.
-It is discussed in issue #432.
-
 No [=extended attributes=] defined in this specification are applicable to [=includes statements=].
 
 

@@ -1327,6 +1419,8 @@ No [=extended attributes=] defined in this specification are applicable to [=inc
 
 

 
+
Syntax

+
 

 
 

@@ -1337,6 +1431,8 @@ No [=extended attributes=] defined in this specification are applicable to [=inc
 
 

 
+

+
 
     MixinRest :
         "mixin" identifier "{" MixinMembers "}" ";"