1. 序論
◎非規範的この標準は、 ~Web~IDLを定義する — それは、[ ~Web~browserが実装するものと意図される~ifc ]を記述するために利用できる,~ifc定義~言語である。 ~Web~IDLは,~IDLの変種であり、[ ~Web~platformにおいて共通な~script~objに対し, その挙動を より容易に指定する ]ことを許容するための,いくつもの特能を備える。 また、[ ~Web~IDLで記述される~ifcが,~JS実行~環境の構成子にどう対応するか ]についての詳細も述べられる。 ◎ This standard defines an interface definition language, Web IDL, that can be used to describe interfaces that are intended to be implemented in web browsers. Web IDL is an IDL variant with a number of features that allow the behavior of common script objects in the web platform to be specified more readily. How interfaces described with Web IDL correspond to constructs within JavaScript execution environments is also detailed here.
具象的には、 ~Web~IDLは,[ ~web~platform~objの表面を成す~APIを指定するための構文 ]とともに[ それらの~APIを~JS構成子として どう具体化するか詳細を与える,~JS言語束縛 ]を供する。 これは、[ 大域的な~propの~install法, 数量-入力の処理-法, 反復の挙動の公開-法 ]などの共通的な~taskが, 各~web~platform仕様にまたがって一様であり続けることを確保する。 そのような各~仕様は、 ~Web~IDLを利用して自身の~ifcを記述してから, 注釈文を利用して~APIに特有な詳細を指定することになる。 ◎ Concretely, Web IDL provides a syntax for specifying the surface APIs of web platform objects, as well as JavaScript bindings that detail how those APIs manifest as JavaScript constructs. This ensures common tasks, such as installing global properties, processing numeric inputs, or exposing iteration behavior, remain uniform across web platform specifications: such specifications describe their interfaces using Web IDL, and then use prose to specify API-specific details.
注記: 用語 “JavaScript” は、 `ECMA-262^cite を指す。 その公式的な用語は ECMAScript であるが、 ~JSの方が広く知られているので。 ◎ The term "JavaScript" is used to refer to ECMA-262, rather than the official term ECMAScript, since the term JavaScript is more widely known.
【この訳に特有な表記規約】
◎表記記号`~THROW$ の意味は、 この仕様に定義され(~link先を見よ),もっぱら `~JS言語束縛@~WEBIDLjs#js-interfaces$ にて利用される。
この仕様~自身にも,`表記規約@#conventions$がある。
2. ~ifc定義~言語
この節では、 ~Web~platform~API用の~ifcを定義するために利用できる言語, `~Web~IDL^em について述べる。 ~Web~APIを定義する仕様は、[ その仕様が定義する~API用の~ifc (~objが表出し得る状態と挙動) ]を記述する, 1 個~以上の `~IDL片@ ( `IDL fragment^en )を含み得る。 `~IDL片$は、 いくつかの[ 文法~記号 `Definitions$g に合致する定義 ]たちが成す連列である。 実装が~supportする `~IDL片$たちが成す集合は、 順序付けられない。 完全な文法と利用される記法の説明については、 `~IDL文法@#idl-grammar§を見よ。 ◎ 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.
`~IDL片$に現れ得る `定義@ ( `definition^en )には、 次に挙げる種類があり,すべて後続の節にて定義される ⇒# `~ifc$ / `部分的な~ifc定義$ / `~ifc~mixin$ / `部分的な~ifc~mixin定義$ / `~callback関数$ / `~callback~ifc$ / `~ns$ / `部分的な~ns定義$ / `辞書$ / 【`列挙$ /】 `部分的な辞書~定義$ / `~typedef$ / `~includes文$ ◎ The different kinds of definitions that can appear in an IDL fragment are: interfaces, partial interface definitions, interface mixins, partial mixin definitions, callback functions, callback interfaces, namespaces, partial namespace definitions, dictionaries, partial dictionary definitions, typedefs and includes statements. These are all defined in the following sections.
各`定義$ ( `Definition$g に合致-) の前には、[ `拡張d属性$たちが成す~list ( `ExtendedAttributeList$g に合致-) ]を置ける — それらは、[ 当の定義が,言語束縛において どう取扱われるか ]を制御する。 この仕様が定義する拡張d属性の[ 言語束縛に不問な~~側面は、 `拡張d属性@#idl-extended-attributes§にて/ ~JS言語束縛に特有な~~側面は、 `拡張d属性@~WEBIDLjs#js-extended-attributes§にて ]論じられる。 ◎ Each definition (matching Definition) can be preceded by a list of extended attributes (matching ExtendedAttributeList), which can control how the definition will be handled in language bindings. The extended attributes defined by this specification that are language binding agnostic are discussed in § 2.14 Extended attributes, while those specific to the JavaScript language binding are discussed in § 3.3 Extended attributes.
[`extended_attributes^mk] interface `identifier^i { /* interface_members... */ };
`~IDL片$の例を示す: ◎ The following is an example of an IDL fragment.
[Exposed=Window] interface Paint { }; [Exposed=Window] interface SolidColor : Paint { attribute double red; attribute double green; attribute double blue; }; [Exposed=Window] interface Pattern : Paint { attribute DOMString imageURL; }; [Exposed=Window] interface GraphicalWindow { constructor(); readonly attribute unsigned long width; readonly attribute unsigned long height; attribute Paint currentPaint; undefined drawRectangle(double %x, double %y, double %width, double %height); undefined drawText(double %x, double %y, DOMString %text); };
ここでは、 4 個の`~ifc$が定義されている。 `GraphicalWindow^T ~ifcには、 2 個の`読専$な`属性$, 1 個の~writableな属性, 2 個の`演算$ が定義されている。 `GraphicalWindow^T ~ifcを実装する~objは、 利用されている 特定0の言語に適切な方式で,これらの属性と演算を公開することになる。 ◎ 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.
~JSにおいては、 ~IDL~ifcの属性/演算は、 すべての `GraphicalWindow^T ~objにおいて,その原型~objの[ `組込みの関数~obj$を値とする~data~propとして与えられる[ ~accessor~prop / 演算 ]]として,公開されることになる。 `GraphicalWindow^T を実装する各~JS~objは、 その原型鎖の中にその原型~objを有することになる。 ◎ In JavaScript, the attributes on the IDL interfaces will be exposed as accessor properties and the operations as data properties whose value is a built-in function object on a prototype object for all GraphicalWindow objects; each JavaScript object that implements GraphicalWindow will have that prototype object in its prototype chain.
`GraphicalWindow^T 上に現れる`構築子~演算$により、[ `new GraphicalWindow()^c の~callに対し,この~ifcを実装する新たな~objを返す`構築子$ ]が,~JS実装に存在することになる。 ◎ The constructor operation that appears on GraphicalWindow causes a constructor to exist in JavaScript implementations, so that calling new GraphicalWindow() would return a new object that implemented the interface.
どの`~ifc$にも `Exposed$x `拡張d属性$があり、 ~ifcは[ `大域~obj$が `Window$T ~objである`~realm$ ]内に限り可用になることを確保する。 ◎ All interfaces have the [Exposed] extended attribute, which ensures the interfaces are only available in realms whose global object is a Window object.
2.1. 名前(識別子)
次に挙げるものは、 `識別子@ ( `identifier^en )を有する:
- `有名~定義@ ( `named definition^en )と総称される,次に挙げるもの ⇒# `~ifc$ / `部分的な~ifc定義$ / `~ns$ / `部分的な~ns定義$ / `辞書$ / `部分的な辞書~定義$ / `列挙$ / `~callback関数$ / `~callback~ifc$ / `~typedef$
- `定数$
- `属性$
- `辞書~mb$
- 一部の`演算$ 【`特殊~演算$以外の演算/一部の特殊~演算】
- 【演算~引数】
これらの識別子は、 当の宣言~内のどこかに在る `identifier$g ~tokenから決定される: ◎ The identifier is determined by an identifier token somewhere in the declaration:
-
`有名~定義$に対しては、 ~keyword[ `interface^sym / `namespace^sym / `dictionary^sym / `enum^sym / `callback^sym ]の直後に現れる `identifier$g ~tokenがその定義の識別子を決定する。 ◎ For named definitions, the identifier token that appears directly after the interface, namespace, dictionary, enum or callback keyword determines the identifier of that definition.
interface `interface_identifier^mk { /* interface_members... */ }; partial interface `interface_identifier^mk { /* interface_members... */ }; namespace `namespace_identifier^mk { /* namespace_members... */ }; partial namespace `namespace_identifier^mk { /* namespace_members... */ }; dictionary `dictionary_identifier^mk { /* dictionary_members... */ }; partial dictionary `dictionary_identifier^mk { /* dictionary_members... */ }; enum `enumeration_identifier^mk { "enum", "values" /* , ... */ }; callback `callback_identifier^mk = return_type (/* arguments... */); callback interface `callback_interface_identifier^mk { /* interface_members... */ };
-
`属性$, `~typedef$, `辞書~mb$ に対しては、 宣言の末尾の~semicolonの前に在る最後の `identifier$g ~tokenが識別子を決定する。 ◎ For attributes, typedefs and dictionary members, the final identifier token before the semicolon at the end of the declaration determines the identifier.
[`extended_attributes^i] interface `identifier^i { attribute `type^i `attribute_identifier^mk; }; typedef `type^i `typedef_identifier^mk; dictionary `identifier^i { `type^i `dictionary_member_identifier^mk; };
-
`定数$に対しては、 等号の前に在る `identifier$g ~tokenが識別子を決定する。 ◎ For constants, the identifier token before the equals sign determines the identifier.
const `type^i `constant_identifier^mk = 42;
-
`演算$に対しては、 返り値~型の後,かつ左~丸括弧の前に現れる `identifier$g ~token ( `OperationRest$g の中の文法~記号 `OptionalOperationName$g が成す部分に合致-) が、 その演算の識別子を決定する。 そのような `identifier$g ~tokenが無い場合、 その演算は識別子を有さない。 ◎ 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 OptionalOperationName grammar symbol in an OperationRest) determines the identifier of the operation. If there is no such identifier token, then the operation does not have an identifier.
interface interface_identifier { `return_type^i `operation_identifier^mk(/* arguments... */); };
注記: [ 取得子や設定子などの, `特殊な種類の演算@#idl-special-operations$ ]を宣言する演算は、 識別子を有さないことがある。 ◎ Note: Operations can have no identifier when they are being used to declare a special kind of operation, such as a getter or setter.
これらの構成子~すべてにおいて、 `識別子$は, `identifier$g ~tokenから先頭の `005F^U1 を(もし在れば)除去した結果になる。 ◎ For all of these constructs, the identifier is the value of the identifier token with any leading U+005F (_) removed.
注記: 先頭の `005F^U1 は、 識別子を~escapeして,予約-済みな語と見誤られなくするために利用される。 例えば、 `interface^l と命名される~ifcも定義できる。 先頭の `005F^U1 は、 識別子の~escapeを外す際に落とされる。 ◎ Note: A leading U+005F (_) 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 U+005F (_) is dropped to unescape the identifier.
演算~引数がとり得る識別子は、 もう少し広い集合になる。 演算の宣言においては、 引数の識別子は,その型の直後に指定され、[ `identifier$g ~token/ `ArgumentNameKeyword$g 記号に合致する~keyword ]として与えられる。 これらの~keywordいずれかが利用される場合、 先頭の~underscoreによる~escapeは不要である。 ◎ Operation arguments can take a slightly wider set of identifiers. In an operation declaration, the identifier of an argument is specified immediately after its type and is given by either an identifier token or by one of the keywords that match the ArgumentNameKeyword symbol. If one of these keywords is used, it need not be escaped with a leading underscore.
interface interface_identifier { `return_type^i `operation_identifier^i(argument_type `argument_identifier^mk /* , ... */); };
演算~引数の`識別子$は: ◎ ↓
- `identifier$g ~tokenが利用された場合、 その`識別子$は,その~tokenから先頭の文字 `005F^U1 を除去した結果になる。 ◎ If an identifier token is used, then the identifier of the operation argument is the value of that token with any leading U+005F (_) removed.\
- 代わりに いずれかの `ArgumentNameKeyword$g ~keyword~tokenが利用された場合、 単にその~tokenになる。 ◎ If instead one of the ArgumentNameKeyword keyword token is used, then the identifier of the operation argument is simply that token.
上で言及したどの~IDL構成子も,(演算~引数を除いて)その`識別子$は[ `constructor^l / `toString^l ]になってはナラナイ。 また、 `005F^U1 から始まってはナラナイ。 これらは `予約-済み識別子@ ( `reserved identifier^en )と呼ばれる。 ◎ The identifier of any of the abovementioned IDL constructs (except operation arguments) must not be "constructor", "toString", or begin with a U+005F (_). These are known as reserved identifiers.
`識別子$ `toJSON^l は`予約-済み識別子$ではないが、 `~toJSON@#idl-tojson-operation§に述べるとおり,利用されるのは[ ~objを`~JSON型$に変換する`正則~演算$ ]に限らなければナラナイ。 ◎ Although the "toJSON" identifier is not a reserved identifier, it must only be used for regular operations that convert objects to JSON types, as described in § 2.5.3.1 toJSON.
注記: 後の節にて、 一部の特定0の構成子に対しては,識別子の名前に更なる制約が課され得る。 ◎ Note: Further restrictions on identifier names for particular constructs can be made in later sections.
所与の実装が~supportする`~IDL片$たちが成す集合に属する、 どの[ `~ifc$ / `~ns$ / `辞書$ / `列挙$ / `~callback関数$ / `~callback~ifc$ / `~typedef$ ]の`識別子$も,他のそれと互いに同じになってはナラナイ — 同じ~~種別に限らず。 ◎ Within the set of IDL fragments that a given implementation supports, the identifier of every interface, namespace, dictionary, enumeration, callback function, callback interface and typedef must not be the same as the identifier of any other interface, namespace, dictionary, enumeration, callback function, callback interface or typedef.
`~IDL片$の中では、 `定義$への参照は,参照~先の定義の宣言より後に現れる必要はない。 参照は複数の`~IDL片$をまたがることもできる。 ◎ 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.
したがって,次の`~IDL片$は妥当である: ◎ Therefore, the following IDL fragment is valid:
[Exposed=Window] interface B : A { undefined f(SequenceOfLongs %x); }; [Exposed=Window] interface A { }; typedef sequence<long> SequenceOfLongs;
次の`~IDL片$は、[ `定義$/`~ifc~mb$ ]に`識別子$をどう与えるかをデモる: ◎ The following IDL fragment demonstrates how identifiers are given to definitions and interface members.
/* ~typedef識別子: `number^l ◎ Typedef identifier: "number" */ typedef double number; /* ~ifc識別子: `System^l ◎ Interface identifier: "System" */ [Exposed=Window] interface System { /* 演算~識別子: `createObject^l ◎ Operation identifier: "createObject" */ /* 演算~引数~識別子: `interface^l ◎ Operation argument identifier: "interface" */ object createObject(DOMString _interface); /* 演算~引数~識別子: `interface^l ◎ Operation argument identifier: "interface" */ sequence<object> getObjects(DOMString interface); /* 演算は識別子を有さない。 取得子を宣言する。 ◎ Operation has no identifier; it declares a getter. */ getter DOMString (DOMString keyName); }; /* ~ifc識別子: `TextField^l ◎ Interface identifier: "TextField" */ [Exposed=Window] interface TextField { /* 属性~識別子: `const^l ◎ Attribute identifier: "const" */ attribute boolean _const; /* 属性~識別子: `value^l ◎ Attribute identifier: "value" */ attribute DOMString? _value; };
`TextField^T `~ifc$の 2 個目の`属性$は ( `value^l は~IDL文法の~keywordではないので) ~underscoreで~escapeする必要はないが、 属性の`識別子$を得する際には,依然として~escapeは外される。 ◎ 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.
2.2. ~ifc
`~IDL片$は~obj指向~systemの記述に利用される。 その種の~systemにおいては、 ~objは同一性( `identity^en )を備える実体であり, 状態と挙動の~capsule化である。 `~ifc@ は、[ その~ifcを実装する~objが公開することになる,何らかの状態や挙動 ]を宣言する,`定義$ ( `interface^sym `InterfaceRest$g に合致-) である。 ◎ 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.
[`extended_attributes^i] interface `identifier^i { /* interface_members... */ };
~ifcは、 その宣言における波括弧の合間に現れる,`~mb$たちが成す集合 ( `InterfaceMembers$g に合致-) の指定である。 これらの~mbは、 `~ifc~mb@ と称される。 ◎ 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.
~Web~IDLの~ifcは,その~ifcを実装する~objが どう挙動するかを記述する。 ~obj指向~言語~用の言語束縛においては、 特定0の~IDL~ifcを実装する~objは,[ ~objの状態を検分したり改変する仕方,~ifcに記述された挙動を呼出す仕方 ]を供することが期待されている。 ◎ 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.
~ifcは,別の~ifc(の~mb)を `継承-@ するようにも定義できる。 ~ifcの識別子に `003A^U1 と`識別子$が後続している場合、 後者の識別子が,継承される~ifcを識別する。 ある~ifc %I を継承する~ifcを実装する~objは, %I も実装する。 ~objはしたがって, %I からの~ifc~mbに対応する~mbも有することになる。 ◎ An interface can be defined to inherit from another interface. If the identifier of the interface is followed by a U+003A (:) 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^i : `identifier_of_inherited_interface^mk { /* interface_members... */ };
~mbたちが現れる順序は、 `~JS言語束縛@~WEBIDLjs#js-interfaces$における~prop列挙に,有意になる。 ◎ The order that members appear in has significance for property enumeration in the JavaScript binding.
~ifcは、 継承される~ifcの~mbと同じ名前を有する,~ifc~mbを指定してもよい。 派生~ifcを実装する~objは、 派生~ifc上でそれらの~mbを公開することになる。 その~obj上で上書きされた~mbに~accessできるかどうかは、 言語束縛に特有になる。 ◎ 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.
次の 2 つの~ifcを考える ◎ Consider the following two interfaces.
[Exposed=Window] interface A { undefined f(); undefined g(); }; [Exposed=Window] interface B : A { undefined f(); undefined g(DOMString %x); };
~JS言語束縛においては、 `B^T の~instanceは,次の様な原型鎖を有することになる: ◎ In the JavaScript language binding, an instance of B will have a prototype chain that looks like the following:
~JSにおける `instanceOfB.f()^c の~callは、 `B^T 上で定義された `f^M を呼出すことになる。【! * f】 しかしながら, `A^T の `f^M も、 依然として `A.prototype.f.call(instanceOfB)^c の~callにより, `B^T を実装する~obj上で呼出せる。 ◎ Calling instanceOfB.f() in JavaScript will invoke the f defined on B. However, the f from A can still be invoked on an object that implements B by calling A.prototype.f.call(instanceOfB).
所与の~ifc %A が `継承した~ifc群@ は、[ %A が直接間接に継承する,すべての~ifc ]たちが成す集合である — すなわち、 %A の`自身も含む継承した~ifc群$から %A を除いたものからなる。 ◎ 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.
~ifcは、 その継承~階層が循環するように宣言してはナラナイ。 すなわち、 ~ifc %A は自身を継承することも, %A を継承する別の~ifc %B を継承することもできない,等々。 ◎ 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.
所与の`~ifc$ %I の `自身も含む継承した~ifc群@ は、 次に従って定義される`~list$である: ◎ The list of inclusive inherited interfaces of an interface I is defined as follows:
- %結果 ~LET « %I » ◎ Let result be « ». ◎ ↓
-
~WHILE [ %I が`継承-$する`~ifc$は在る ]:
- %I ~SET %I が`継承-$する`~ifc$
- %結果 に %I を`付加する$
- ~RET %結果 ◎ Return result.
~ifcの一般的な多重~継承は~supportされず,~objは~ifcの任意な集合を実装することはできないことに注意。 ~objは、 所与の~ifc %A を実装するように — すなわち、[ %A の`自身も含む継承した~ifc群$を成す すべての~ifc ]を実装するように — 定義できる。 加えて,`~includes文$を利用すれば、[ ある~ifc %A を実装している~objが,常に[ %A が`内包-$する各`~ifc~mixin$を成す各`~ifc~mixin~mb$を内包する ]]ように定義することもできる。 ◎ 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 members of the interface mixins A includes.
各~ifc~mbの前には、 `拡張d属性$たちが成す~list ( `ExtendedAttributeList$g に合致-) を置くことができる — それらは、 その~ifc~mbが,言語束縛において どう取扱われるかを制御する。 ◎ 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^i] interface `identifier^i { [`extended_attributes^mk] const `type^i `constant_identifier^i = 42; [`extended_attributes^mk] attribute `type^i `identifier^i; [`extended_attributes^mk] `return_type^i `identifier^i(/* arguments... */); };
~ifc用の~IDLは、 `部分的な~ifc定義@ ( `partial^sym `interface^sym `PartialInterfaceRest$g に合致-) を利用して,複数の部分に分割できる。 部分的な~ifc定義の`識別子$は、 その~ifc定義の識別子と同じでなければナラナイ。 各 部分的な~ifcに現れる,すべての~mbは、 その~ifc自身を成す~mbと見なされる。 ◎ The IDL for interfaces can be split into multiple parts by using partial interface definitions (matching partial interface 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.
interface `SomeInterface^mk { /* interface_members... */ }; partial interface `SomeInterface^mk { /* interface_members... */ };
注記: 部分的な~ifc定義に意図される用途は、 ~ifcの定義を文書の複数の節, ときには複数の文書に分離できるようにして, 仕様の編集を補佐することである。 ◎ 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.
`~ifc$定義, およびその`部分的な~ifc定義$が現れる順序は~~問題にされない。 ◎ The order of appearance of an interface definition and any of its partial interface definitions does not matter.
注記: 部分的な~ifc定義においては、 別の~ifcからの`継承-$は指定できない。 継承は元の`~ifc$定義に指定されることになる。 ◎ Note: A partial interface definition cannot specify that the interface inherits from another interface. Inheritance is to be specified on the original interface definition.
関連な言語束縛が,~ifcと[ 言語の構成子 ]とがどう対応するかを決定する。 ◎ The relevant language binding determines how interfaces correspond to constructs in the language.
`~ifc$に適用-可能な拡張d属性は ⇒# `Exposed$x, `Global$x, `CrossOriginIsolated$x, `LegacyFactoryFunction$x, `LegacyNoInterfaceObject$x, `LegacyOverrideBuiltIns$x, `LegacyWindowAlias$x, `SecureContext$x ◎ The following extended attributes are applicable to interfaces: [CrossOriginIsolated], [Exposed], [Global], [LegacyFactoryFunction], [LegacyNoInterfaceObject], [LegacyOverrideBuiltIns], [LegacyWindowAlias], and [SecureContext].
`部分的な~ifc$に適用-可能な拡張d属性は ⇒# `CrossOriginIsolated$x, `Exposed$x, `LegacyOverrideBuiltIns$x, `SecureContext$x ◎ The following extended attributes are applicable to partial interfaces: [CrossOriginIsolated], [Exposed], [LegacyOverrideBuiltIns], and [SecureContext].
どの`~ifc$も、 `Exposed$x `拡張d属性$で注釈されなければナラナイ。 ◎ Interfaces must be annotated with an [Exposed] extended attribute.
`~ifc$ %~ifc の `有修飾~名@ ( `qualified name^en ) は、 次に従って定義される: ◎ The qualified name of an interface interface is defined as follows:
- %識別子 ~LET %~ifc の`識別子$ ◎ Let identifier be the identifier of interface.
-
~IF[ %~ifc は `LegacyNamespace$x `拡張d属性$を伴う ]: ◎ If interface has a [LegacyNamespace] extended attribute, then:
- %~ns ~LET `LegacyNamespace$x `拡張d属性$の識別子~引数 ◎ Let namespace be the identifier argument of the [LegacyNamespace] extended attribute.
- ~RET 次を `002E^U1 で順に`連結する$ ⇒# %~ns, %識別子 ◎ Return the concatenation of « namespace, identifier » with separator U+002E (.).
- ~RET %識別子 ◎ Return identifier.
次の`~IDL片$は、 相互に参照しあう`~ifc$ — `Human^T と `Dog^T — の定義をデモる。 両~ifcとも `Animal^T を継承するので、 そのいずれかを実装する~objは, `name^M 属性も有することになる。 ◎ The following IDL fragment demonstrates the definition of two mutually referential interfaces. Both Human and Dog inherit from Animal. Objects that implement either of those two interfaces will thus have a name attribute.
[Exposed=Window] interface Animal { attribute DOMString name; }; [Exposed=Window] interface Human : Animal { attribute Dog? pet; }; [Exposed=Window] interface Dog : Animal { attribute Human? owner; };
次の`~IDL片$は、 ある~DOM`~ifc$と`~callback~ifc$を単純~化した~versionを定義する。 ◎ The following IDL fragment defines simplified versions of a DOM interfaces and a callback interface.
[Exposed=Window] interface Node { readonly attribute DOMString nodeName; readonly attribute Node? parentNode; Node appendChild(Node %newChild); undefined addEventListener(DOMString %type, EventListener %listener); }; callback interface EventListener { undefined handleEvent(Event %event); };
素な~objは、 `EventListener$T の様な`~callback~ifc$を実装できる: ◎ Plain objects can implement a callback interface like EventListener:
var %node = getNode(); /* `Node^T の~instanceを得する。 ◎ Obtain an instance of Node. */ var %listener = { handleEvent: function(%event) { /* ... */ } }; %node.addEventListener("click", %listener); /* これは働く。 ◎ This works. */ %node.addEventListener("click", function() { ... }); /* これと同様に。 ◎ As does this. */
しかしながら,そのような~objが `Node^T の様な`~ifc$を実装することはアリでない: ◎ It is not possible for such an object to implement an interface like Node, however:
var %node = getNode(); /* */
var %newNode = {
nodeName: "span",
parentNode: null,
appendChild: function(%newchild) {
/* ... */
},
addEventListener: function(%type, %listener) {
/* ... */
}
};
%node.appendChild(%newNode); /*
`TypeError^jE 例外が投出されることになる。
◎
This will throw a TypeError exception.
*/
2.3. ~ifc~mixin
`~ifc~mixin@ は、[ それを`内包-$する`~ifc$を実装する各~obj ]により公開される状態や挙動を宣言する,`定義$ ( `interface^sym `MixinRest$g に合致-) である。 `~ifc~mixin$は、 複数の`~ifc$に`内包-$され得る。 ◎ An interface mixin is a definition (matching interface MixinRest) that declares state and behavior that can be included by one or more interfaces, and that are exposed by objects that implement an interface that includes the interface mixin.
interface mixin `identifier^i { /* mixin_members... */ };
注記: `~ifc~mixin$に意図されている用途は、 `部分的な~ifc$と同様に,[ 複数の~ifcに — 場合によっては複数の文書にわたって — 内包されるような,首尾一貫した機能性たちが成す集合 ]を一つに~group化できるようにして, 仕様の編集を補佐することである。 それには、 言語束縛を通して公開されることは意味されていない。 [ `部分的な~ifc$, `~ifc~mixin$, `部分的な~ifc~mixin$ ]のどれを選ぶかについての目安は、 `~mixinと~partialの利用-法@#using-mixins-and-partials§に見出せる。 ◎ Note: Interface mixins, much like partial interfaces, are intended for use as a specification editorial aide, allowing a coherent set of functionalities to be grouped together, and included in multiple interfaces, possibly across documents. 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 § 2.3.1 Using mixins and partials.
`~ifc~mixin$は、 その宣言を成す波括弧の合間に現れる`~mb$たち — [ `定数$, `正則~演算$, `正則~属性$, `文字列化子$ ] — が成す集合 ( `MixinMembers$g に合致-) の指定である。 これらの~mbは、 `~ifc~mixin~mb@ と称され、 それぞれが[ 当の`~ifc~mixin$を`内包-$する`~ifc$ ]に指定されていたかのように,~objに実装できる挙動を述べる。 ◎ 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. ◎ 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.
`~ifc~mixin$の宣言には、 次に挙げるものは現れ得ない ⇒# `静的~属性$ / `静的~演算$ / `特殊~演算$ / `可反復~宣言$ / `非同期に可反復な宣言$/ `~maplike宣言$ / `~setlike宣言$ ◎ Static attributes, static operations, special operations, and iterable, asynchronously iterable, maplike, and setlike declarations cannot appear in interface mixin declarations.
~ifcのときと同じく,`~ifc~mixin$用の~IDLは、 `部分的な~ifc~mixin@ 定義 ( `partial^sym `interface^sym `MixinRest$g に合致-) を利用して,複数の部分に分割できる。 `部分的な~ifc~mixin$`定義$の`識別子$は、 `~ifc~mixin$`定義$の`識別子$と同じでなければナラナイ。 各`部分的な~ifc~mixin$`定義$に現れる どの`~ifc~mixin~mb$も,[ `~ifc~mixin$自身に加え,当の`~ifc~mixin$を — 拡張により — `内包-$している`~ifc$ ]を成す`~mb$と見なされる。 ◎ 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 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.
interface mixin `SomeMixin^mk { /* mixin_members... */ }; partial interface mixin `SomeMixin^mk { /* mixin_members... */ };
~mbたちが現れる順序は、 `~JS言語束縛@~WEBIDLjs#js-interfaces$における~prop列挙に,有意になる。 ◎ The order that members appear in has significance for property enumeration in the JavaScript binding.
`~ifc$や`辞書$と違って、 `~ifc~mixin$は,型を作成しないことに注意。 ◎ Note that unlike interfaces or dictionaries, interface mixins do not create types.
この仕様に定義される拡張d属性のうち,`~ifc~mixin$に適用-可能な拡張d属性は、 次に限られる ⇒# `CrossOriginIsolated$x, `Exposed$x, `SecureContext$x ◎ Of the extended attributes defined in this specification, only the [CrossOriginIsolated], [Exposed], and [SecureContext] extended attributes are applicable to interface mixins.
`~includes文@ は、 ( 1 個目の`識別子$により識別される)`~ifc$ %I が ( 2 個目の`識別子$により識別される)`~ifc~mixin$ %M を `内包-@ ( `include^en )すること — すなわち,[ %I を実装している すべての~objは、 %M を成す各~mbも内包するモノトスル ]こと — を宣言するために利用される,`定義$ ( `IncludesStatement$g に合致-) である。 ◎ An includes statement is a definition (matching IncludesStatement) used to declare that all objects implementing an interface I (identified by the first identifier) must additionally include the members of interface mixin M (identified by the second identifier). Interface I is said to include interface mixin M.
`interface_identifier^i includes `mixin_identifier^i;
1 個目の`識別子$は `~ifc$ %I を参照しなければナラナイ。 2 個目の識別子は `~ifc~mixin$ %M を参照しなければナラナイ。 ◎ The first identifier must reference a interface I. The second identifier must reference an interface mixin M.
%M を成す各`~ifc~mixin~mb$は、 %M を`内包-$する各`~ifc$[ %I, %J, %K, … ]を成す`~mb$と見なされる — 各~ifcごとに,`~ifc~mixin~mb$の複製が作られたかのように。 すなわち, %M のある~mb %m に対し、 ~ifc[ %I / %J / %K / … ]は`~mb$[ %m%I / %m%J / %m%K / … ]を有すると見なされ,[ %m%I / %m%J / %m%K / … ]の `~host~ifc@ は[ %I / %J / %K / … ]になる。 ◎ Each member of M is considered to be a member of each interface I, J, K, … that includes M, as if a copy of each 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.
注記: このことは,~JSにおいては、 次のことを含意する — `~ifc~mixin$ %M にて`~ifc~mixin~mb$として宣言された各 %m に対し: ◎ Note: In JavaScript, this implies that\
- %m は[ `正則~演算$であって, `組込みの関数~obj$値を伴うものとして公開される~data~propになる ]ならば、 各[ %M を`内包-$する 各`~ifc$に結付けられる`~ifc原型~obj$ ]に対し,他と別個な`組込みの関数~obj$がある。 ◎ each regular operation declared as a 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.\
- %m は`属性$ならば、 その~accessor~propの各~複製に対し,他と別個な`組込みの関数~obj$が[ 取得子/設定子 ]用にある。 ◎ Similarly, for attributes, each copy of the accessor property has distinct built-in function objects for its getters and setters.
`~includes文$が現れる順序は、 それらの`~ifc~mixin$が`~host~ifc$に`内包-$される順序に影響する。 ◎ The order of appearance of includes statements affects the order in which interface mixin are included by their host interface.
【 そのような順序は — 同じ~host~ifcを指定する複数の~includes文が,同じ~IDL片の中に現れる場合を除き — きちんと定義できない (次に述べる課題)。 これは、 ~JS言語束縛における~prop列挙に影響する。 】
`~ifc~mixin~mb$の順序は、 まだ明瞭に指定されていない — 特に、 `~ifc~mixin$が別々な文書~内に定義されている場合には。 `課題 #432@~WEBIDLissue/432$ にて論じられている。 ◎ Member order isn’t clearly specified, in particular when interface mixins are defined in separate documents. It is discussed in issue #432.
`~includes文$に適用-可能な`拡張d属性$は、 この仕様には定義されていない。 ◎ No extended attributes defined in this specification are applicable to includes statements.
次の`~IDL片$は、[ `~ifc$ `Entry^T, `~ifc~mixin$ `Observable^T ]を定義する。 `~includes文$は、[ `Observable^T の`~ifc~mixin~mb$は, `Entry^T を実装している~objに常に内包される ]ことを指定する。 ◎ The following IDL fragment defines an interface, Entry, and an interface mixin, Observable. The includes statement specifies that Observable’s members are always included on objects implementing Entry.
interface Entry { readonly attribute unsigned short entryType; /* ... */ }; interface mixin Observable { undefined addEventListener(DOMString %type, EventListener %listener, boolean %useCapture); /* ... */ }; Entry includes Observable;
~JS実装は、 各 `Entry^T ごとに,その原型鎖~内に `addEventListener^jp ~propを有することになる: ◎ A JavaScript implementation would thus have an addEventListener property in the prototype chain of every Entry:
var %e = getEntry(); /* `Entry^T の~instanceを得する。 ◎ Obtain an instance of Entry. */ typeof %e.addEventListener; /* `function^l に評価される。 ◎ Evaluates to "function" */
2.3.1. ~mixinと~partialの利用-法
◎非規範的`~ifc~mixin$は、[ `属性$ / `定数$ / `演算$ ]を,`複数^emの`~ifc$から共有できるようにする。 単独の~ifcを拡張したければ、 代わりに`部分的な~ifc$の利用を考えるであろう。 ◎ Interface mixins allow the sharing of attributes, constants, and operations across multiple interfaces. If you’re only planning to extend a single interface, you might consider using a partial interface instead.
例えば,次に代えて: ◎ For example, instead of:
interface mixin WindowSessionStorage { readonly attribute Storage sessionStorage; }; Window includes WindowSessionStorage;
次にするなど: ◎ do:
partial interface Window { readonly attribute Storage sessionStorage; };
加えて,共通的な利用事例 — [ `属性$, `定数$, `演算$ ]たちが成す集合を[ ~window, ~worker ]両~文脈に`公開され$るようにするなど — を~~対象にするため、 他の仕様により公開される`~ifc~mixin$を拡張することに依拠できる。 ◎ Additionally, you can rely on extending interface mixins exposed by other specifications to target common use cases, such as exposing a set of attributes, constants, or operations across both window and worker contexts.
例えば、 共通的にあるが冗漫な,次に挙げるものに代えて: ◎ For example, instead of the common but verbose:
interface mixin GlobalCrypto { readonly attribute Crypto crypto; }; Window includes GlobalCrypto; WorkerGlobalScope includes GlobalCrypto;
`部分的な~ifc~mixin$を利用すれば, `WindowOrWorkerGlobalScope$T `~ifc~mixin$を拡張できる: ◎ you can extend the WindowOrWorkerGlobalScope interface mixin using a partial interface mixin:
partial interface mixin WindowOrWorkerGlobalScope { readonly attribute Crypto crypto; };
2.4. ~callback~ifc
`~callback~ifc@
は、
`callback^sym `interface^sym `identifier$g { `CallbackInterfaceMembers$g } ;
に合致する`定義$であり
— `~ifcを実装している~obj@#idl-objects§にて述べるように —
どの~objもそれを実装し得る。
◎
A callback interface is a definition matching callback interface identifier { CallbackInterfaceMembers } ;. It can be implemented by any object, as described in § 2.12 Objects implementing interfaces.
注記: `~callback~ifc$は、 `~ifc$ではない。 この名前と構文にされているのは、 その概念がもっと共通的にあった,この標準の早期の~versionによる~~名残である。 ◎ Note: A callback interface is not an interface. The name and syntax are left over from earlier versions of this standard, where these concepts had more in common.
`~callback~ifc$は、 その宣言における波括弧の合間に現れる`~mb$たちが成す集合 ( `CallbackInterfaceMembers$g に合致-) の指定である。 これらの~mbは、 `~callback~ifc~mb@ と称される。 ◎ A callback interface is a specification of a set of callback interface members (matching CallbackInterfaceMembers). These are the members that appear between the braces in the interface declaration.
callback interface `identifier^i { /* interface_members... */ };
注記: 似た命名の`~callback関数$定義も見よ。 ◎ Note: See also the similarly named callback function definition.
`~callback~ifc$は、 正確に 1 個の`正則~演算$を定義しなければナラナイ。 ◎ Callback interfaces must define exactly one regular operation.
仕様~策定者は、 既存の~APIの要件を述べるために要求されない限り,`~callback~ifc$を定義するべきでない。 代わりに,`~callback関数$を利用するべきである。 ◎ Specification authors should not define callback interfaces unless required to describe the requirements of existing APIs. Instead, a callback function should be used.
`~callback~ifc$である `EventListener$T の定義は、[ その~ifcを[ 所与の~prop(この場合は `handleEvent^jp )を伴う~obj ]により実装できるようにする必要がある ]ものと見なされている,既存の~APIの例である。 新たな~API, あるいは互換性の心配がない~API用の`~callback関数$には、 (~JS言語束縛においては)`関数~obj$のみが許容されることになる。 ◎ The definition of EventListener as a callback interface is an example of an existing API that needs to allow 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 JavaScript language binding).
`定数$を宣言する`~callback~ifc$は、 `Exposed$r `拡張d属性$で注釈されなければナラナイ。 ◎ Callback interfaces which declare constants must be annotated with an [Exposed] extended attribute.
2.5. ~mb
[ `~ifc$ / `~ifc~mixin$ / `~ns$ ] %A は、 その宣言を成す波括弧の合間に現れる `~mb@ ([ `InterfaceMembers$g / `MixinMembers$g / `NamespaceMembers$g ]に合致-) — [ `定数$, `属性$, `演算$, その他の宣言 ] — たちが成す集合の指定である。 %A を実装している~objを %O とするとき ⇒# `属性$は、 %O が公開することになる状態を述べる。 `演算$は、 %O 上で呼出せる挙動を述べる。 `定数$は、 %O に公開される有名~定数~値を宣言する — ~systemにおける %O の利用者~用の便利として。 ◎ Interfaces, interface mixins, and namespaces are specifications of a set of members (respectively matching InterfaceMembers, MixinMembers, and NamespaceMembers), which are the constants, attributes, operations, and other declarations that appear between the braces of their declarations. Attributes describe the state that an object implementing the interface, interface mixin, or namespace 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.
注記: 所与の`~ifc$ %A が,ある`~ifc~mixin$を`内包-$している場合、 その`~ifc~mixin~mb$も %A の~mbと見なされる。 対照的に, %A が`継承-$している`~ifc~mb$は、 %A の~mbとは見なされない。 ◎ When an interface includes an interface mixin, each member of the interface mixin is also considered a member of the interface. In contrast, inherited interface members are not considered members of the interface.
[ `~ifc$/`~ifc~mixin$ ] %A 上に定義された各`~mb$用の[ `構築子~手続き$/ `取得子~手続き$/ `設定子~手続き$/ `~method手続き$ ](順不同)は、 `this@V 値への~accessを有する — それは、[ %A 型 / %A を`内包-$する【いずれかの】~ifc型 ]の~IDL値である。 ◎ The constructor steps, getter steps, setter steps, and method steps for the various members defined on an interface or interface mixin have access to a this value, which is an IDL value of the interface type that the member is declared on or that includes the interface mixin the member is declared on.
【 `概ね^em,~JS `this^jv 値に対応する。 他の仕様の和訳においては “コレ” と記される。 】【 `this$V は、 当の~ifcを`実装-$する 特定0の~instanceを指すので,[ `静的~属性$/`静的~演算$ ]用の手続きには利用し得ない。 】
`設定子~手続き$は、 `所与の値@ ( `given value^en )への~accessを有する。 それは、 当の`属性$に宣言された型の~IDL値である。 【すなわち、設定子に渡された値を適切な型の`~IDL値に変換-$した結果。】 ◎ Setter steps also have access to the given value, which is an IDL value of the type the attribute is declared as.
[ `~ifc$, `~ifc~mixin$, `~callback~ifc$, `~ns$ ]が~supportする`~mb$の~~種類は、 それぞれに異なる — それらは順に[ `~ifc@#idl-interfaces§, `~ifc~mixin@#idl-interface-mixins§, `~callback~ifc@#idl-callback-interfaces§, `~ns@#idl-namespaces§ ]にて指定され,次の表t(参考)に要約される: ◎ Interfaces, interface mixins, callback interfaces and namespaces each support a different set of members, which are specified in § 2.2 Interfaces, § 2.3 Interface mixins, § 2.4 Callback interfaces, and § 2.6 Namespaces, and summarized in the following informative table:
`~ifc$ | `~callback~ifc$ | `~ifc~mixin$ | `~ns$ | |
---|---|---|---|---|
`定数$ | ● | ● | ● | |
`正則~属性$ | ● | ● | `読専$な属性に限る | |
`静的~属性$ | ● | |||
`正則~演算$ | ● | ● | ● | ● |
`文字列化子$ | ● | ● | ||
`特殊~演算$ | ● | |||
`静的~演算$ | ● | |||
`非同期に可反復な宣言$ | ● | |||
`可反復~宣言$ | ● | |||
`~maplike宣言$ | ● | |||
`~setlike宣言$ | ● |
2.5.1. 定数
`定数@ ( `constant^en )は、 定数~値を名前に束縛するために利用される,宣言 ( `Const$g に合致-) である。 定数は[ `~ifc$/`~callback~ifc$ ]に現れ得る。 ◎ A constant is a declaration (matching Const) used to bind a constant value to a name. Constants can appear on interfaces and callback interfaces.
過去においては,定数は、 主に,有名~整数~codeを列挙する~styleで定義されていた。 ~Web~platformは、 文字列の利用の支持を受けて,この設計~patternから離れつつある。 この特能を利用したいと望む編集者には、 先に進む前に `Intent to use Constants$fI した上で論交することを,強く勧める。 ◎ 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. Editors who wish to use this feature are strongly advised to discuss this by filing an issue before proceeding.
const `type^i `constant_identifier^i = 42;
`定数$の`識別子$は、 同じ[ `~ifc$/`~callback~ifc$ ]上で定義される別の[ `~ifc~mb$/`~callback~ifc~mb$ ]の識別子と同じになってはナラナイ。 また、 識別子が[ `length^l / `name^l / `prototype^l ]になってはナラナイ。 ◎ The identifier of a constant must not be the same as the identifier of another interface member or callback interface member defined on the same interface or callback interface. The identifier also must not be "length", "name" or "prototype".
注記: これらの名前は、 ~JS言語束縛においては,`~ifc~obj$上に定義される~propの名前である。 ◎ Note: These three names are the names of properties that are defined on the interface object in the JavaScript language binding.
定数の型 ( `ConstType$g に合致-) は、 `~primitive型$でなければナラナイ。 `識別子$を利用する場合、 その識別子は~primitive型の`~typedef$を参照しなければナラナイ。 ◎ The type of a constant (matching ConstType) must not be any type other than a primitive type. If an identifier is used, it must reference a typedef whose type is a primitive type.
定数~宣言の `ConstValue$g 部は、 定数の値を次に挙げるいずれかとして与える:
- 真偽-~literal: `true^sym / `false^sym
- `integer$g
- `decimal$g
- 特別な浮動小数点~定数~値: `-Infinity^sym / `Infinity^sym / `NaN^sym
注記: 文字列や空~連列に加え,これらの値も[ 辞書~mbの`既定~値$diC / `随意~引数$の`既定~値$ ]を指定するために利用できる。 [ 文字列 / 空~連列 `[]^sym / 既定の辞書 `{}^sym ]は、 `定数$の値として利用できないことに注意。 ◎ 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, the empty sequence [], and the default dictionary {} cannot be used as the value of a constant.
真偽-~literal~token[ `true^sym / `false^sym ]は、 ~IDL `boolean$T 値[ `true^V / `false^V ]になる。 ◎ The value of the boolean literal tokens true and false are the IDL boolean values true and false.
`integer$g ~tokenの値は、 それを成す`~scalar値$たちが成す連列 %S に対し,次に従って決定される整数~値になる: ◎ The value of an integer token is an integer whose value is determined as follows: • Let S be the sequence of scalar values matched by the integer token.
- %符号 ~LET 1 ◎ ↓
- ~IF[ %S の先頭の`~scalar値$ ~EQ `002D^U1 ] ⇒# %符号 ~SET −1; %S から先頭の`~scalar値$を除去する ◎ Let sign be −1 if S begins with U+002D (-), and 1 otherwise.
-
%基数 ~LET %S の頭部を成す`~scalar値$列に応じて ⇒# `0X^l ( `0030^U1 `0058^U1 )ならば 16 / `0x^l ( `0030^U1 `0078^U1 )ならば 16 / `0030^U1 ならば 8 / ~ELSE_ 10 ◎ Let base be the base of the number based on the scalar values that follow the optional leading U+002D (-): ◎ U+0030 (0), U+0058 (X) U+0030 (0), U+0078 (x) • The base is 16. U+0030 (0) • The base is 8. Otherwise • The base is 10.
- ~IF[ %基数 ~EQ 16 ] ⇒ %S の先頭から 2 個の`~scalar値$を除去する ◎ ↓
- %数 ~LET %S を基数 %基数 に基づいて整数に解釈した結果 ◎ Let number be the result of interpreting all remaining scalar values following the optional leading U+002D (-) character and any scalar values indicating the base as an integer specified in base base.
- ~RET %符号 ~MUL %数 ◎ Return sign × number.
`integer$g ~tokenの型は、 それを値に利用している[ 定数/辞書~mb/随意~引数 ]の型と同じである。 `integer$g ~tokenの値は、 `型@#idl-types§にて与えられる,その型の値として妥当な範囲に入らなければナラナイ。 ◎ The type of an integer token is the same as the type of the constant, dictionary member or optional argument it is being used as the value of. The value of the integer token must not lie outside the valid range of values for its type, as given in § 2.13 Types.
`decimal$g ~tokenの値は、 それを値に利用している[ 定数/辞書~mb/随意~引数 ]の型に依存して,単精度, 倍精度 いずれかの IEEE 754 浮動小数点数になり、 次に従って決定される: ◎ The value of a decimal 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:
- %S ~LET `decimal$g ~tokenに合致する[ `~scalar値$たちが成す連列 ] ◎ Let S be the sequence of scalar values matched by the decimal token.
- %結果 ~LET %S を~JS `NumericLiteral$i として構文解析して得される `Mathematical Value^i ◎ Let result be the Mathematical Value that would be obtained if S were parsed as a JavaScript NumericLiteral.
-
`decimal$g ~tokenは どの型の値として利用されているかに応じて:
- `float$T
- `unrestricted float$T
- ~RET %結果 に最も近い IEEE 754 単精度 浮動小数点数
- `double$T
- `unrestricted double$T
- ~RET %結果 に最も近い IEEE 754 倍精度 浮動小数点数
`IEEE-754$r
◎ If the decimal token is being used as the value for a float or unrestricted float, then the value of the decimal token is the IEEE 754 single-precision floating point number closest to result. ◎ Otherwise, the decimal token is being used as the value for a double or unrestricted double, and the value of the decimal token is the IEEE 754 double-precision floating point number closest to result. [IEEE-754]
`Infinity^sym, `-Infinity^sym, `NaN^sym のいずれかとして指定された定数~値は、 それを値に利用している[ 定数/辞書~mb/随意~引数 ]の型に依存して,単精度, 倍精度 いずれかの IEEE 754 浮動小数点数になり、 次に従って決定される: ◎ The value of a constant value specified as Infinity, -Infinity, or NaN is either an IEEE 754 single-precision floating point number or an IEEE 754 double-precision floating point number, depending on the type of the constant, dictionary member, or optional argument it is being used as the value for:
- `unrestricted float$T 型の定数~値 `Infinity^sym ◎ Type unrestricted float, constant value Infinity
- 値は IEEE 754 単精度,正な無限大~値 ◎ The value is the IEEE 754 single-precision positive infinity value.
- `unrestricted double$T 型の定数~値 `Infinity^sym ◎ Type unrestricted double, constant value Infinity
- 値は IEEE 754 倍精度,正な無限大~値 ◎ The value is the IEEE 754 double-precision positive infinity value.
- `unrestricted float$T 型の定数~値 `-Infinity^sym ◎ Type unrestricted float, constant value -Infinity
- 値は IEEE 754 単精度,負な無限大~値 ◎ The value is the IEEE 754 single-precision negative infinity value.
- `unrestricted double$T 型の定数~値 `-Infinity^sym ◎ Type unrestricted double, constant value -Infinity
- 値は IEEE 754 倍精度,負な無限大~値 ◎ The value is the IEEE 754 double-precision negative infinity value.
- `unrestricted float$T 型の定数~値 `NaN^sym ◎ Type unrestricted float, constant value NaN
- 値は~bit~pattern `7fc00000^X の, IEEE 754 単精度 NaN ◎ The value is the IEEE 754 single-precision NaN value with the bit pattern 0x7fc00000.
- `unrestricted double$T 型の定数~値 `NaN^sym ◎ Type unrestricted double, constant value NaN
- 値は~bit~pattern `7ff8000000000000^X の, IEEE 754 倍精度 NaN ◎ The value is the IEEE 754 double-precision NaN value with the bit pattern 0x7ff8000000000000.
`decimal$g ~tokenの型は、 それを値に利用している[ 定数/辞書~mb/随意~引数 ]の型と同じになる。 `decimal$g ~tokenの値は、 `型@#idl-types§にて与えられる,その型の値として妥当な範囲に入らなければナラナイ。 また、[ `Infinity^sym, `-Infinity^sym, `NaN^sym ]が[ `float$T や `double$T ]の値として利用してはナラナイ。 ◎ The type of a decimal 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 decimal token must not lie outside the valid range of values for its type, as given in § 2.13 Types. Also, Infinity, -Infinity and NaN must not be used as the value of a float or double.
`null^sym ~tokenの値は、 `~nullable型$に属する特別な `null^V 値である。 `null^sym ~tokenの型は、 それを値に利用している[ 定数/辞書~mb/随意~引数 ]の型と同じになる。 ◎ The value of the null token is the special null value that is a member of the nullable types. The type of the null token is the same as the type of the constant, dictionary member or optional argument it is being used as the value of.
定数にアテガわれる値の型 %VT, [ 定数/辞書~mb/随意~引数 ]自身の型 %DT は、 互換,すなわち次を満たしていなければナラナイ ⇒ [ %DT と %VT は一致する ]~OR[ %DT は`~nullable型$であって,その`内縁~型$は %VT に一致する ] ◎ 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.
`定数$は、 それが現れる[ `~ifc$/`~callback~ifc$ ]の特定0の~instanceには結付けられない。 `定数$が~instanceにも公開されるかどうかは、 言語束縛に特有になる。 ◎ Constants are not associated with particular instances of the interface or callback interface on which they appear. It is language binding specific whether constants are exposed on instances.
注記: ~JS言語束縛においては、 `定数$が宣言されている~IDL`~ifc$を実装する~objを通して,`定数$への~accessが許容される。 例えば次の~IDLでは: ◎ The JavaScript 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:
[Exposed=Window] interface A { const short rambaldi = 47; };
~JSにおいては、 この定数~値は,[ `A.rambaldi^c および (`A^T の~instance)`.rambaldi^c ]として~accessできる。 ◎ the constant value can be accessed in JavaScript either as A.rambaldi or instanceOfA.rambaldi.
定数に適用-可能な拡張d属性は ⇒# `CrossOriginIsolated$x, `Exposed$x, `SecureContext$x ◎ The following extended attributes are applicable to constants: [CrossOriginIsolated], [Exposed], and [SecureContext].
次の`~IDL片$は、 上の型の`定数$をどう定義するかをデモる。 ◎ The following IDL fragment demonstrates how constants of the above types can be defined.
[Exposed=Window] interface Util { const boolean DEBUG = false; const octet LF = 10; const unsigned long BIT_MASK = 0x0000fc00; const double AVOGADRO = 6.022e23; };
2.5.2. 属性
`属性@ ( `attribute^en ) ( `inherit^sym `AttributeRest$g, `static^sym `OptionalReadOnly$g `AttributeRest$g, `stringifier^sym `OptionalReadOnly$g `AttributeRest$g, `OptionalReadOnly$g `AttributeRest$g, `AttributeRest$g いずれかに合致-) は、[ `~ifc~mb$/`~ns~mb$ ]であり,[ 所与の[ 型, `識別子$ ]を伴い,値を[ 検索取得できる/(一部の事例では)変更できる ]]ような~data~fieldを宣言するために利用される。 ◎ An attribute is an interface member or namespace member (matching inherit AttributeRest, static OptionalReadOnly AttributeRest, stringifier OptionalReadOnly AttributeRest, OptionalReadOnly AttributeRest, or AttributeRest) that is used to declare data fields with a given type and identifier whose value can be retrieved and (in some cases) changed.\
`属性$は、 次の 2 種類に分けられる: ◎ There are two kinds of attributes:
-
`正則~属性$は、 次を宣言するために利用される ⇒ 当の[ ~ifc/~ns ]を実装している~objは、 所与の`識別子$を伴う~data~field~mbを有する ◎ 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^i { attribute `type^i `identifier^i; };
-
`静的~属性$は、 次を宣言するために利用される ⇒ 当の~ifcを実装している特定0の~objには結付けられない属性 ◎ static attributes, which are used to declare attributes that are not associated with a particular object implementing the interface
interface `interface_identifier^i { static attribute `type^i `identifier^i; };
`static^sym ~keywordを伴わない属性は `正則~属性@ ( `regular attribute^en ) を宣言する。 そうでなければ,`静的~属性$を宣言する。 `読専$な`正則~属性$には、 `~ifc~mb$の他に,`~ns~mb$もあることに注意。 ◎ If an attribute has no static keyword, then it declares a regular attribute. Otherwise, it declares a static attribute. Note that in addition to being interface members, read only regular attributes can be namespace members as well.
属性 %attr の `取得子~手続き@ は、 次の形による~textを利用して導入されるベキである ⇒ “%attr 取得子~手続きは…” ([ ~listまたは~inline ]による記述が後続する) ◎ The getter steps of an attribute attr should be introduced using text of the form “The attr getter steps are:” followed by a list, or “The attr getter steps are to” followed by an inline description.
属性 %attr の `設定子~手続き@ は、 次の形による~textを利用して導入されるベキである ⇒ “%attr 設定子~手続きは…” ([ ~listまたは~inline ]による記述が後続する) ◎ The setter steps of an attribute attr should be introduced using text of the form “The attr setter steps are:” followed by a list, or “The attr setter steps are to” followed by an inline description.
注記: `取得子~手続き$を定義するときは、 暗黙的に`this$V への~accessを有することになる。 `設定子~手続き$を定義するときは、 暗黙的に `this$V, `所与の値$への~accessを有することになる。 ◎ Note: When defining getter steps, you implicitly have access to this. When defining setter steps, you implicitly have access to this and the given value.
`属性$の`識別子$は[ 同じ`~ifc$上に定義される別の`~ifc~mb$の識別子 ]と同じになってはナラナイ。 静的~属性の識別子が `prototype^l になってはナラナイ。 ◎ 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".
属性の型は、 `attribute^sym ~keywordの後に現れる型 ( `Type$g に合致-) で与えられる。 `Type$g が[ `識別子$, または `?^sym が後続する識別子 ]である場合、 その識別子は[ `~ifc$/`列挙$/`~callback関数$/`~callback~ifc$/`~typedef$ ]を識別しなければナラナイ。 ◎ The type of the attribute is given by the type (matching Type) that appears after the attribute keyword. If the Type is an identifier or an identifier followed by ?, then the identifier must identify an interface, enumeration, callback function, callback interface or typedef.
属性の型は、 ~typedefの解決-後に,次に挙げる型, あるいはその`~nullable型$になってはナラナイ。 ◎ The type of the attribute, after resolving typedefs, must not be a nullable or non-nullable version of any of the following types:
- `連列~型$ ◎ a sequence type
- `辞書~型$ ◎ a dictionary type
- `~record型$ ◎ a record type
- `共用体~型$のうち,その`平坦~化~mb型~群$に[ `~nullable$/非~nullable ]な[ 連列~型 / 辞書 / ~record【!区切り?】 ](順不同)を含んでいるもの 【平坦~化~mb型~群は~nullableを含み得ないので,この “~nullable” の記述は不要では?】 ◎ a union type that has a nullable or non-nullable sequence type, dictionary, or record as one of its flattened member types
`attribute^sym ~keywordの前に `readonly^sym ~keywordが利用されている場合、 属性は `読専@ ( `read only^en, 読み取りのみ) になる。 [ 読専な属性が定義されている~ifc ]を実装する~objにおいては、 その属性に対する代入は許容されないことになる。 代入が[ 単に言語において許容されないのか, 無視されるのか, あるいは例外が投出されるのか ]については、 言語束縛に特有になる。 ◎ The attribute is read only if the readonly keyword is used before the attribute keyword. An object that implements the interface on which a read only attribute is defined will not allow assignment to that attribute. It is language binding specific whether assignment is simply disallowed by the language, ignored or an exception is thrown.
interface `interface_identifier^i { readonly attribute `type^i `identifier^i; };
`~promise型$である属性は、 `読専$でなければナラナイ。 加えて、 次の`拡張d属性$を有せない ⇒ `LegacyLenientSetter$x, `PutForwards$x, `Replaceable$x, `SameObject$x ◎ Attributes whose type is a promise type must be read only. Additionally, they cannot have any of the extended attributes [LegacyLenientSetter], [PutForwards], [Replaceable], or [SameObject].
`読専$でない`正則~属性$は、 先祖~ifcからその `取得子を継承する@ ように宣言できる。 これにより、 先祖~ifcの読専な属性を,派生~ifc上で~writableにできる。 属性は、 その宣言が `inherit^sym を伴うとき,`取得子を継承する$ものとされる。 その属性が取得子を継承する読専な属性は、[ 同じ識別子の属性が定義されている,先祖~ifc ]のうち,最も末端の~ifcに属する属性である。 【!readonlyとは限らない?】 取得子を[ 継承する側, される側 ]の属性の型は同じでなければナラナイ。 ◎ A regular attribute that is not read only can be declared to inherit its getter from an ancestor interface. This can be used to make a read only attribute in an ancestor interface be writable on a derived interface. An attribute inherits its getter if its declaration includes inherit in the declaration. The read only attribute from which the attribute inherits its getter is the attribute with the same identifier on the closest ancestor interface of the one on which the inheriting attribute is defined. The attribute whose getter is being inherited must be of the same type as the inheriting attribute.
注記: `inherit^sym が[ `読専$な属性/`静的~属性$ ]に現れることはない — それは、 文法により確保される。 ◎ Note: The grammar ensures that inherit does not appear on a read only attribute or a static attribute.
[Exposed=Window] interface `Ancestor^i { readonly attribute `TheType^i `theIdentifier^i; }; [Exposed=Window] interface `Derived^i : `Ancestor^i { inherit attribute `TheType^i `theIdentifier^i; };
`正則~属性$の宣言に `stringifier^sym ~keywordが利用されている場合、[ その~ifcを実装している~objを文字列~化するときは、 その属性の値になる ]ことを指示する。 詳細は、 `文字列化子@#idl-stringifiers§を見よ。 ◎ When the stringifier keyword is used in a regular attribute declaration, it indicates that objects implementing the interface will be stringified to the value of the attribute. See § 2.5.5 Stringifiers for details.
interface `interface_identifier^i { stringifier attribute DOMString `identifier^i; };
[ `正則~属性$/`静的~属性$ ]に適用-可能な拡張d属性は ⇒# `CrossOriginIsolated$x, `Exposed$x, `SameObject$x, `SecureContext$x ◎ The following extended attributes are applicable to regular and static attributes: [CrossOriginIsolated], [Exposed], [SameObject], and [SecureContext].
次の`拡張d属性$は、 `正則~属性$にしか適用-可能でない ⇒ `LegacyLenientSetter$x, `LegacyLenientThis$x, `PutForwards$x, `Replaceable$x, `LegacyUnforgeable$x ◎ The following extended attributes are applicable only to regular attributes: [LegacyLenientSetter], [LegacyLenientThis], [PutForwards], [Replaceable], [LegacyUnforgeable].
次の`~IDL片$は、 `~ifc$上にて`属性$を どう宣言するかをデモる: ◎ The following IDL fragment demonstrates how attributes can be declared on an interface:
[Exposed=Window] 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; }; [Exposed=Window] interface Person : Animal { /* 取得子の挙動を `Animal^T から継承する属性。 `Person^T の記述にて指定する必要はない。 ◎ An attribute whose getter behavior is inherited from Animal, and need not be specified in the description of Person. */ inherit attribute DOMString name; };
2.5.3. 演算
`演算@ ( `operation^en ) ( `static^sym `RegularOperation$g, `stringifier^sym, `RegularOperation$g, `SpecialOperation$g いずれかに合致-) は、[ `~ifc~mb$/`~callback~ifc~mb$/`~ns~mb$ ]であり,当の[ `~ifc$/`~callback~ifc$/`~ns$ ]を実装している~obj上で呼出せる挙動を定義する。 ◎ An operation is an interface member, callback interface member or namespace member (matching static RegularOperation, stringifier, RegularOperation or SpecialOperation) that defines a behavior that can be invoked on objects implementing the interface.\
演算には次の 3 種類がある: ◎ There are three kinds of operation:
-
`正則~演算$は、 次を宣言するために利用される ⇒ 当の[ ~ifc/~ns ]を実装している~objは、 所与の`識別子$を伴う~methodを有する ◎ regular operations, which are those used to declare that objects implementing the interface will have a method with the given identifier
interface `interface_identifier^i { `return_type^i `identifier^i(/* arguments... */); };
-
`特殊~演算$は、 次を宣言するために利用される ⇒ ~objの~index法や文字列~化などの,当の~ifcを実装している~obj上の特殊な挙動 ◎ special operations, which are used to declare special behavior on objects implementing the interface, such as object indexing and stringification
interface `interface_identifier^i { /* special_keyword */ `return_type^i `identifier^i(/* arguments... */); /* special_keyword */ `return_type^i (/* arguments... */); };
-
`静的~演算$は、 次を宣言するために利用される ⇒ 当の~ifcを実装している特定0の~objには結付けられない演算 ◎ static operations, which are used to declare operations that are not associated with a particular object implementing the interface
interface `interface_identifier^i { static `return_type^i `identifier^i(/* arguments... */); };
演算のうち,[ 識別子を有する ]~AND[ `static^sym ~keywordは伴わない ]ものは、 `正則~演算@ ( `regular operation^en )を宣言する。 `特殊~keyword$ (すなわち、 `Special$g に合致する~keyword, または `stringifier^sym ) が宣言に利用されている演算は、 `特殊~演算$を宣言する。 演算を,正則~演算と特殊~演算を兼ねるように宣言することもできる。 特殊~演算についての詳細は、 `特殊~演算@#idl-special-operations§を見よ。 `正則~演算$には、 `~ifc~mb$以外にも,`~callback~ifc~mb$や`~ns~mb$であるものもあることに注意。 ◎ If an operation has an identifier but no static keyword, then it declares a regular operation. If the operation has a special keyword used in its declaration (that is, any keyword matching Special, or the stringifier keyword), then it declares a special operation. A single operation can declare both a regular operation and a special operation; see § 2.5.6 Special operations for details on special operations. Note that in addition to being interface members, regular operations can also be callback interface members and namespace members.
識別子が無い演算は、 いずれかの特殊~keywordを利用して,`特殊~演算$として宣言されなければナラナイ。 ◎ If an operation has no identifier, then it must be declared to be a special operation using one of the special keywords.
`正則~演算$や`静的~演算$の識別子は、 同じ[ `~ifc$/`~callback~ifc$/`~ns$ ]上に定義される`定数$や`属性$の識別子と同じになってはナラナイ。 静的~演算の識別子は `prototype^l になってはナラナイ。 ◎ 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, callback interface or namespace. The identifier of a static operation must not be "prototype".
注記: しかしながら,~ifc上では、 複数の演算の識別子を同じにすることはできる。 演算の多重定義は、 これにより指定される。 ◎ Note: The identifier can be the same as that of another operation on the interface, however. This is how operation overloading is specified.
注記: `静的~演算$の`識別子$は、 同じ`~ifc$上に定義される`正則~演算$の識別子と同じにすることもできる。 ◎ Note: The identifier of a static operation can be the same as the identifier of a regular operation defined on the same interface..
演算の `返り値~型@ ( `return type^en ) ( `Type$g に合致-) は、 随意な[ 演算の`識別子$ ]の前に現れる型で与えられる。 返り値~型が `?^sym 付きの`識別子$である場合、 その識別子は[ `~ifc$/`辞書$/`列挙$/`~callback関数$/`~callback~ifc$/`~typedef$ ]を識別しなければナラナイ。 ◎ The return type of the operation is given by the type (matching Type) that appears before the operation’s optional identifier. If the return type is an identifier followed by ?, then the identifier must identify an interface, dictionary, enumeration, callback function, callback interface or typedef.
演算の引数たち ( `ArgumentList$g に合致-) は、 宣言の中の丸括弧の合間にて与えられる。 各 引数は、 型 ( `Type$g に合致-) の後に, `識別子$ ( `ArgumentName$g に合致-) を続けて指定される。 ◎ 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).
注記: 表出力のため、 演算~引数の識別子には, `ArgumentNameKeyword$g 記号に合致する~keywordも — ~escapeを要することなく — 指定できる。 【!*】 ◎ 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.
演算~引数の型を与える `Type$g が:
- `?^sym が後続する`識別子$である場合、 その識別子は,次に挙げるいずれかを識別しなければナラナイ ⇒# `~ifc$ / `列挙$ / `~callback関数$ / `~callback~ifc$ / `~typedef$
- `?^sym が後続しない`識別子$である場合、 その識別子は,次に挙げるいずれかを識別しなければナラナイ ⇒# `辞書$ / 前項に挙げたいずれかの`定義$
演算~引数の型が`~typedef$の解決-後に`~nullable型$になる場合、 その`内縁~型$は`辞書~型$になってはナラナイ。 ◎ If the operation argument type, after resolving typedefs, is a nullable type, its inner type must not be a dictionary type.
interface `interface_identifier^i { `return_type^i `identifier^i(`type^i `identifier^i, `type^i `identifier^i /* , ... */); };
各~引数の識別子は、 同じ演算~宣言~内の他の引数の識別子と同じになってはナラナイ。 ◎ The identifier of each argument must not be the same as the identifier of another argument in the same operation declaration.
各~引数の前には、 `拡張d属性$たちが成す~list ( `ExtendedAttributeList$g に合致-) を置くことができる — それらは、 その引数として渡された値が,言語束縛において どう取扱われるかを制御する。 ◎ 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^i { `return_type^i `identifier^i([`extended_attributes^mk] `type^i `identifier^i, [`extended_attributes^mk] `type^i `identifier^i /* , ... */); };
次の`~IDL片$は、 `~ifc$上で`正則~演算$をどう宣言するかをデモる: ◎ The following IDL fragment demonstrates how regular operations can be declared on an interface:
[Exposed=Window] interface Dimensions { attribute unsigned long width; attribute unsigned long height; }; [Exposed=Window] interface Button { /* 引数をとらず, `boolean^T を返す演算 ◎ An operation that takes no arguments and returns a boolean. */ boolean isMouseOver(); /* 多重定義された演算。 ◎ Overloaded operations. */ undefined setDimensions(Dimensions %size); undefined setDimensions(unsigned long %width, unsigned long %height); };
[ 演算/`構築子~演算$ ]の 最後の引数 の引数~型の直後に `...^sym ~tokenが利用されている場合、 その演算は `可変個的な@ もの( `variadic^en )と見なされ, その最後の引数を指して `可変個~引数@ という 【この用語は、参照し易くするため,この訳に導入している】 。 そのように宣言された演算は: ◎ An operation or constructor 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.\
- `可変個~引数$以外の引数は、 `...^sym ~tokenを伴って宣言してはナラナイ。 ◎ An argument must not be declared with the ... token unless it is the final argument in the operation’s argument list.
interface `interface_identifier^i { `return_type^i `identifier^i(`type^i`...^em `identifier^i); `return_type^i `identifier^i(`type^i `identifier^i, `type^i`...^em `identifier^i); };
【!原文誤*`引数~listを引数にとる$】 `有名~引数~listを引数にとる$`拡張d属性$ (この仕様に定義される `LegacyFactoryFunction$x ), および`~callback関数$についても、 その引数~listに `...^sym ~tokenが利用されているならば,`可変個的な$ものと見なされる。 【以下の記述における可変個的な演算の “演算” には,これらの(構築子を与える)拡張d属性や~callbackも含まれる。】 ◎ Extended attributes that take an argument list ([LegacyFactoryFunction], of those defined in this specification) and callback functions are also considered to be variadic when the ... token is used in their argument lists.
次の`~IDL片$は,可変個的な演算を 2 つ有する~ifcを定義する: ◎ The following IDL fragment defines an interface that has two variadic operations:
[Exposed=Window] interface IntegerSet { readonly attribute unsigned long cardinality; undefined union(long... %ints); undefined intersection(long... %ints); };
~JS言語束縛においては、 可変個的な演算は,後続な引数を受容できる関数により実装される: ◎ In the JavaScript binding, variadic operations are implemented by functions that can accept the subsequent arguments:
var %s = getIntegerSet(); /* `IntegerSet^T の~instanceを得する。 ◎ Obtain an instance of IntegerSet. */ %s.union(); /* `ints^l に対応する引数を~~省略。 ◎ Passing no arguments corresponding to 'ints'. */ %s.union(1, 4, 7); /* `ints^l に対応する 3 個の引数を渡す。 ◎ Passing three arguments corresponding to 'ints'. */
可変個的な関数を~supportしない言語~用の言語束縛においては、 その種の演算には,整数の 配列または~list を明示的に渡すように指定することになるであろう。 ◎ 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.
`optional^sym ~keywordを伴って宣言された引数は、 `随意~引数@ であるものと見なされる。 `可変個的な$演算の`可変個~引数$も随意~引数と見なされる。 随意として宣言された引数は、[ 演算を呼出すときに,その値を省略できる ]ことを指示する。 `可変個~引数$は、 明示的に随意として宣言してはナラナイ。 ◎ An argument is considered to be an optional argument if it is declared with the optional keyword. The final argument of a variadic operation is also considered to be an optional argument. Declaring an argument to be optional indicates that the argument value can be omitted when the operation is invoked. The final argument in an operation must not explicitly be declared to be optional if the operation is variadic.
interface `interface_identifier^i { `return_type^i `identifier^i(`type^i `identifier^i, optional `type^i `identifier^i); };
随意~引数には `既定~値@ を指定できる。 引数の識別子に `003D^U1 と値 ( `DefaultValue$g に合致-) が後続している場合、 その値がその随意~引数の`既定~値$を与える。 ただし,`可変個的な$演算の`可変個~引数$には、 既定~値を指定してはナラナイ。 既定~値は、 対応する引数が省略されて演算が~callされたときに,その引数がとる値と見做される。 ◎ Optional arguments can also have a default value specified. If the argument’s identifier is followed by a U+003D (=) and a value (matching DefaultValue), then that gives the optional argument its default value. The implicitly optional final argument of a variadic operation must not have a default value specified. The default value is the value to be assumed when the operation is called with the corresponding argument omitted.
interface `interface_identifier^i { `return_type^i `identifier^i(`type^i `identifier^i, optional `type^i `identifier^i = "`value^i"); };
`boolean$T 型の引数には、 `既定~値$として `true^V を利用しないことが強く示唆される。 さもなければ、 `undefined^jv に既定の変換(すなわち, `false^V )が利用されると期待する作者たちを惑わすことになるので。 `API-DESIGN-PRINCIPLES$r ◎ It is strongly suggested not to use a 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). [API-DESIGN-PRINCIPLES]
~AND↓ を満たす引数は、 随意として指定した上で,既定~値も供さなければナラナイ。 ◎ ↓
- 引数の型は、 次を満たす ⇒ [ `辞書~型$である ]~OR[ `共用体~型$であって,その`平坦~化~mb型~群$に ある`辞書~型$を含んでいる ] ◎ 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\
- 前項の辞書~型, その先祖たちには、 `要求され$diCる`辞書~mb$は無い ◎ that dictionary type and its ancestors have no required members, and\
- [ 引数は最後の引数である ]~OR[ 引数に後続するどの引数も`随意~引数$である ] ◎ the argument is either the final argument or is followed only by optional arguments,\ then the argument must be specified as optional and have a default value provided.
【 そのような辞書~引数が省略された場合、 その各~mbは,`既定~値$diCが指定されていれば それをとるものと扱われることになる。 】
注記: これは、 作者が辞書の既定~値のみの利用を望むときでも,空な辞書~値を渡さずに済むような~APIの設計を促すためにある。 ◎ 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.
注記: 通例的に,引数に供される既定~値は `{}^sym になるが、[ 引数が`共用体~型$であって,その`平坦~化~mb型~群$が`辞書~型$を含んでいる事例 ]では,[ 共用体の他の何らかの~mbを初期化する既定~値 ]を供することもできる。 ◎ Usually the default value provided will be {}, but in the case of a union type that has a dictionary type as one of its flattened member types a default value could be provided that initializes some other member of the union.
`既定~値$に[ `ConstValue$g / `null^sym ]が利用された場合、 `定数$に対するときと同じ仕方で解釈される。 ◎ When a boolean literal token (true or false), the null token, an integer token, a decimal token or one of the three special floating point literal values (Infinity, -Infinity or NaN) is used as the default value, it is interpreted in the same way as for a constant.
`undefined^sym ~tokenが`既定~値$として利用されたときは、 その値は,~IDL `undefined$T 値になる。 ◎ When the undefined token is used as the default value, the value is the IDL undefined value.
随意~引数の既定~値には、 `string$g ~tokenも指定できる。 それは、 次に従って決定される`文字列~型$の `値@stR をとる: ◎ Optional argument default values can also be specified using a string token, whose value is a string type determined as follows:
- %S ~LET `string$g ~tokenに合致する[ `~scalar値$たちが成す連列 ]から,先頭と末尾の`~scalar値$ `0022^U1 を除去した結果 ◎ Let S be the sequence of scalar values matched by the string token with its leading and trailing U+0022 (") scalar values removed.
-
当の引数の型に応じて: ◎ Depending on the type of the argument:
- `DOMString$T
- `USVString$T
- `列挙$ 型
- ~RET %S ◎ The value of the string token is S.
- `ByteString$T
- ~Assert: %S は, `00FF^U を超える`符号位置$を包含しない。 ◎ Assert: S doesn’t contain any code points higher than U+00FF.
- ~RET `同型に符号化する$( %S ) ◎ The value of the string token is the isomorphic encoding of 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.
`連列~型$(`~nullable$も含む)の随意~引数の既定~値には、[ 2 個の~tokenが成す値 `[]^sym ]を利用して,[ その型と同じ型の空~連列~値 ]を表現する値も指定できる。 この既定~値の型は、 次のいずれかでなければナラナイ ⇒# `連列~型$ / `~nullable$であって その`内縁~型$は`連列~型$であるもの / `共用体~型$または`~nullable$なそれであって その`平坦~化~mb型~群$は`連列~型$を含むもの ◎ 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 as the type of the optional argument it is being used as the default value of. That type must be a sequence type, a nullable type whose inner type is a sequence type or a union type or nullable union type that has a sequence type in its flattened member types.
`辞書~型$の随意~引数の既定~値には、[ 2 個の~tokenが成す値 `{}^sym ]を利用して,[ その型と同じ型の辞書~値であって,既定に【各~mbが既定~値に】初期化されるもの 【!(as if from ES null or an object with no properties)】 ]を表現する値も指定できる。 この既定~値の型は、 次のいずれかでなければナラナイ ⇒# `辞書~型$ / `共用体~型$であって その`平坦~化~mb型~群$は`辞書~型$を含むもの ◎ Optional argument default values can also be specified using the two token value {}, which represents a default-initialized (as if from ES null or an object with no properties) dictionary value. The type of this value is the same as the type of the optional argument it is being used as the default value of. That type must be a dictionary type, or a union type that has a dictionary type in its flattened member types.
次の`~IDL片$が定義する`~ifc$は、[ 2 通りの引数~list長さで呼出せる, 1 個の`演算$ ]を伴う: ◎ The following IDL fragment defines an interface with a single operation that can be invoked with two different argument list lengths:
[Exposed=Window] interface ColorCreator { object createColor(double %v1, double %v2, double %v3, optional double %alpha); };
それは、[ `多重定義$された 2 個の`演算$ ]を伴う,次の`~ifc$と等価になる: ◎ It is equivalent to an interface that has two overloaded operations:
[Exposed=Window] interface ColorCreator { object createColor(double %v1, double %v2, double %v3); object createColor(double %v1, double %v2, double %v3, double %alpha); };
次の`~IDL片$は、 辞書~引数をとる演算を伴う`~ifc$を定義する: ◎ The following IDL fragment defines an interface with an operation that takes a dictionary argument:
dictionary LookupOptions { boolean caseSensitive = false; }; [Exposed=Window] interface AddressBook { boolean hasAddressForName(USVString %name, optional LookupOptions %options = {}); };
`hasAddressForName()^M が 1 個の引数のみで~callされた場合、 2 個目の引数は,既定に初期化される `LookupOptions^T 辞書になり,その `caseSensitive^M は `false^V に設定されることになる。 ◎ If hasAddressForName is called with only one argument, the second argument will be a default-initialized LookupOptions dictionary, which will cause caseSensitive to be set to false.
演算に適用-可能な拡張d属性は ⇒# `CrossOriginIsolated$x, `Default$x, `Exposed$x, `LegacyUnforgeable$x `NewObject$x, `SecureContext$x, ◎ The following extended attributes are applicable to operations: [CrossOriginIsolated], [Default], [Exposed], [LegacyUnforgeable], [NewObject], and [SecureContext].
演算 %演算 の
`~method手続き@
は、
次の形による~textを利用して導入されるベキである
⇒
“%演算(%arg1, %arg2, ...)
~method手続きは…”
([
~listまたは~inline
]による記述が後続する)
◎
The method steps of an operation operation should be introduced using text of the form “The operation(arg1, arg2, ...) method steps are:” followed by a list, or “The operation(arg1, arg2, ...) method steps are to” followed by an inline description.
注記: `~method手続き$を定義するときは、 暗黙的に `this$V への~accessを有することになる。 ◎ Note: When defining method steps, you implicitly have access to this.
【 値を返さないように定義される`~method手続き$は、 暗黙的に, `undefined$T 型の値を返すものと見なされる。 】
2.5.3.1. ~toJSON
~toJSON`正則~演算$を宣言することにより、 `~ifc$は,それを実装する~objを`~JSON型$に変換する方法を指定する。 ◎ By declaring a toJSON regular operation, an interface specifies how to convert the objects that implement it to JSON types.
~toJSON`正則~演算$は、 この用法のために予約される。 それは、 0 個の引数をとり,`~JSON型$の値を返さなければナラナイ。 ◎ The toJSON regular operation is reserved for this usage. It must take zero arguments and return a JSON type.
次に挙げる型が `~JSON型@ とされる: ◎ The JSON types are:
- `数量-型$ ◎ numeric types,
- `boolean$T 型 ◎ boolean,
- `文字列~型$ ◎ string types,
- 次を満たす`~nullable型$ ⇒ その`内縁~型$は`~JSON型$である ◎ nullable types whose inner type is a JSON type,
- 次を満たす`注釈された型$ ⇒ その`内縁~型$anOは`~JSON型$である ◎ annotated types whose inner type is a JSON type,
- 次を満たす`共用体~型$ ⇒ それを成す`~mb型$は どれも`~JSON型$である ◎ union types whose member types are JSON types,
- 次を満たす`~typedef$ ⇒ それにより`新たな名前が与えられる型$は`~JSON型$である ◎ typedefs whose type being given a new name is a JSON type,
- 次を満たす`連列~型$ ⇒ その~parameter化される型は`~JSON型$である ◎ sequence types whose parameterized type is a JSON type,
- 次を満たす`凍結d配列~型$ ⇒ その~parameter化される型は`~JSON型$である ◎ frozen array types whose parameterized type is a JSON type,
- 次を満たす`辞書~型$ ⇒ [ 自身, 自身が`継承した辞書~群$ ]を成す各`辞書$にて宣言された`辞書~mb$は、 どれも`~JSON型$である ◎ dictionary types where the types of all members declared on the dictionary and all its inherited dictionaries are JSON types,
- 次を満たす`~record型$ ⇒ それを成すどの`~entry$mapも,その`値$mapは`~JSON型$である ◎ records where all of their values are JSON types,
- `object$T 型 ◎ object,
- 次を満たす`~ifc型$ ⇒ [ その`自身も含む継承した~ifc群$ ]を成す いずれかの~ifcにおいて, ~toJSON演算が宣言されている ◎ interface types that have a toJSON operation declared on themselves or one of their inherited interfaces.
[ 言語束縛において~toJSON`正則~演算$を~obj上でどう可用にするか ]および[ `~JSON型$を~JSON文字列に正確にどう変換するか ]は、 言語束縛に特有になる。 ◎ How the toJSON regular operation is made available on an object in a language binding, and how exactly the JSON types are converted into a JSON string, is language binding specific.
注記: ~JS言語束縛においては、 これは,~toJSON~methodを公開することにより行われる — この~methodは、 `~JSON型$を[ `JSON.stringify()$c 関数により~JSON文字列に転換できるような,~JS値 ]に変換して返す。 加えて,~JS言語束縛においては、 ~toJSON演算は `Default$x `拡張d属性$をとり得る — その事例では、 代わりに`既定の~toJSON手続き$が公開される。 ◎ Note: In the JavaScript language binding, this is done by exposing a toJSON method which returns the JSON type converted into a JavaScript value that can be turned into a JSON string by the JSON.stringify() function. Additionally, in the JavaScript language binding, the toJSON operation can take a [Default] extended attribute, in which case the default toJSON steps are exposed instead.
次の`~IDL片$は、 ~toJSON~methodを有するような `Transaction^T ~ifcを定義する — ~methodは注釈文にて定義されることになる: ◎ The following IDL fragment defines an interface Transaction that has a toJSON method defined in prose:
[Exposed=Window] interface Transaction { readonly attribute DOMString from; readonly attribute DOMString to; readonly attribute double amount; readonly attribute DOMString description; readonly attribute unsigned long number; TransactionJSON toJSON(); }; dictionary TransactionJSON { Account from; Account to; double amount; DOMString description; };
`Transaction^T `~ifc$の~toJSON`正則~演算$は、 次のように定義することもできる: ◎ The toJSON regular operation of Transaction interface could be defined as follows:
`toJSON()^M ~method手続きは: ◎ The toJSON() method steps are:
- %~JSON ~LET 新たな`~map$ ◎ Let json be a new map.
- « `from^l, `to^l, `amount^l, `description^l » を成す ~EACH( %識別子 ) に対し ⇒ %~JSON[ %識別子 ] ~SET `this$V の[ %識別子 を`識別子$とする`属性$ ]`取得子~手続き$を走らせた結果 ◎ For each attribute identifier attr in « "from", "to", "amount", "description" »: • Let value be the result of running the getter steps of attr on this. • Set json[attr] to value.
- ~RET %~JSON ◎ Return json.
~JS言語束縛においては、 `Transaction^T ~obj上に `toJSON()^M ~methodが存在することになる: ◎ In the JavaScript language binding, there would exist a toJSON() method on Transaction objects:
/* `Transaction^T の~instanceを取得する: ◎ Get an instance of Transaction. */ var %txn = getTransaction(); /* 次の様な~objに評価される: ◎ Evaluates to an object like this: */ { from: "Bob", to: "Alice", amount: 50, description: "books" } */ %txn.toJSON(); /* 次の様な文字列に評価される: ◎ Evaluates to a string like this: */ '{"from":"Bob","to":"Alice","amount":50,"description":"books"}' */ JSON.stringify(%txn);
2.5.4. 構築子~演算
`~ifc$の~mbとして`構築子~演算$ ( `Constructor$g に合致-) がある場合、[ `構築子$を利用して`~ifc$を`実装-$する~objを作成する ]ことがアリになることを指示する。 ◎ If an interface has a constructor operation member (matching Constructor), it indicates that it is possible to create objects that implement the interface using a constructor.
所与の`~ifc$上に複数の`構築子~演算$が現れてもヨイ。 `~ifc$の各`構築子~演算$ごとに,指定された引数を渡して~instanceを構築しようと試みる仕方があることになる。 ◎ Multiple constructor operations may appear on a given interface. For each constructor operation on the interface, there will be a way to attempt to construct an instance by passing the specified arguments.
名前 %Example の~ifcの~mbである`構築子~演算$の
`構築子~手続き@
は、
次の形による~textを利用して導入されるベキである
⇒
“new %Example(%arg1, %arg2, ...)
構築子~手続きは…”
([
~listまたは~inline
]による記述が後続する)
◎
The constructor steps of a constructor operation that is a member of an interface named interface should be introduced using text of the form “The new interface(arg1, arg2, ...) constructor steps are:” followed by a list, or “The new interface(arg1, arg2, ...) constructor steps are to” followed by an inline description.
`構築子~手続き$は、 次のいずれかをしなければナラナイ ⇒# 何もしない/ `this$V として渡された値を初期化する/ 例外を投出する ◎ The constructor steps must do nothing, initialize the value passed as this, or throw an exception.
【 構築子~手続きは,一般に、 当の~ifcの~instanceの作成まで受持つことはなく,初期化のみを行う — ~instanceを作成するためには、 それが属する`~realm$(それは、構築子の引数には無い)を指定する必要があるので (多くの事例では,`現在の~realm$がその用を成すが、 明示的に指定する必要がある事例も多々ある)。 】
当の構築子が `this$V を初期化しない場合、
次のように書ける
⇒
“new Example(%init)
構築子~手続きは何もしない”
◎
If the constructor does not initialize this, one can write “The new Example(init) constructor steps are to do nothing.”
`構築子~演算$がどう実装されるかの詳細は、 `~ifc~obj@~WEBIDLjs#interface-object§を見よ。 ◎ See § 3.7.1 Interface object for details on how a constructor operation is to be implemented.
次の~IDLは 2 つの~ifcを定義する。 2 個目のものには`構築子~演算$がある一方, 1 個目のものにはない。 ◎ The following IDL defines two interfaces. The second has constructor operations, while the first does not.
[Exposed=Window] interface NodeList { Node item(unsigned long index); readonly attribute unsigned long length; }; [Exposed=Window] interface Circle { constructor(); constructor(double radius); attribute double r; attribute double cx; attribute double cy; readonly attribute double circumference; };
これらの~ifcを~supportする~JS実装は、 `Circle^T ~ifc~obj上に,[ その~ifcを`実装-$する新たな~obj ]を返す `Construct^sl 内部~methodを実装することになる。 それは 0 個または 1 個の引数をとる。 ◎ A JavaScript implementation supporting these interfaces would implement a [[Construct]] internal method on the Circle interface object which would return a new object that implements the interface. It would take either zero or one argument.
`NodeList^T ~ifc~objが `Construct^sl 内部~methodを実装するかどうか不明瞭である。 いずれにせよ,それを構築子として利用しようと試行すると、 `TypeError$jE が投出されることになる。 【 `課題 #698@~WEBIDLissue/698$ 】 ◎ It is unclear whether the NodeList interface object would implement a [[Construct]] internal method. In any case, trying to use it as a constructor will cause a TypeError to be thrown.
var %x = new Circle(); /* これは,引数なしの構築子を利用して `Circle^T ~ifcを実装する~platform~objへの参照を作成する。 ◎ This uses the zero-argument constructor to create a reference to a platform object that implements the Circle interface. */ var %y = new Circle(1.25); /* 今度は 1 個の引数をとる構築子を利用して `Circle^T ~objを作成する。 ◎ This also creates a Circle object, this time using the one-argument constructor. */ var %z = new NodeList(); /* 構築子が宣言されていないので `TypeError^jE が投出されることになる。 ◎ This would throw a TypeError, since no constructor is declared. */
2.5.5. 文字列化子
`~ifc$に `文字列化子@ がある場合、[ 当の~ifcを実装する~objは、 文字列への既定でない変換を有する ]ことを指示する。 文字列化子は、 `stringifier^sym ~keywordを利用して指定できる — それは、 それのみで利用されたときは,文字列化子~演算を作成する。 ◎ When an interface has a stringifier, it indicates that objects that implement the interface have a non-default conversion to a string. Stringifiers can be specified using a stringifier keyword, which creates a stringifier operation when used alone.
interface `interface_identifier^i { stringifier; };
そのような~ifcに付随する注釈文は、 当の~ifcの `文字列~化の挙動@ を定義しなければナラナイ。 ◎ Prose accompanying the interface must define the stringification behavior of the interface.
`stringifier^sym ~keywordは、 `属性$に置くこともできる。 この場合、 その属性の値が,~objから文字列への変換-を与える。 `stringifier^sym ~keywordは、[ `静的~属性$ /[ `DOMString$T/`USVString$T ]として宣言されていない属性 ]に置かれてはナラナイ。 ◎ The stringifier keyword can also be placed on an attribute. In this case, the string to convert the object to is the value of the attribute. The stringifier keyword must not be placed on an attribute unless it is declared to be of type DOMString or USVString. It also must not be placed on a static attribute.
interface `interface_identifier^i { stringifier attribute DOMString `identifier^i; };
所与の`~ifc$上に存在する文字列化子は、 高々 1 個まででなければナラナイ。 ◎ On a given interface, there must exist at most one stringifier.
次の`~IDL片$は、 `name^M 属性の値に文字列~化する~ifcを定義する: ◎ The following IDL fragment defines an interface that will stringify to the value of its name attribute:
[Exposed=Window] interface Student { constructor(); attribute unsigned long id; stringifier attribute DOMString name; };
~JS言語束縛においては、 文字列が期待されている文脈において `Student^T ~objが利用されたときの結果は、 その~objの `name^jp ~propの値になる: ◎ In the JavaScript 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:
var %s = new Student();
%s.id = 12345678;
%s.name = '周杰倫';
var %挨拶 = 'こんにちは、 ' + %s + ' さん。';
/*
`こんにちは、 周杰倫 さん。^l になる。
◎
Now greeting == 'Hello, 周杰倫!'.
*/
次の`~IDL片$は、 ~IDL自身には指定されない~customな文字列~化の挙動を備える~ifcを定義する。 ◎ The following IDL fragment defines an interface that has custom stringification behavior that is not specified in the IDL itself.
[Exposed=Window] interface Student { constructor(); attribute unsigned long id; attribute DOMString? familyName; attribute DOMString givenName; stringifier; };
したがって、 文字列~化の挙動を説明する注釈文が必要になる。 [ `familyName^M / `givenName^M ]属性は、[ `family name^i / `given name^i ]の概念により~backされていると見做すなら: ◎ Thus, there needs to be prose to explain the stringification behavior. We assume that the familyName and givenName attributes are backed by family name and given name concepts, respectively.
`文字列~化の挙動$の手続きは: ◎ The stringification behavior steps are:
- ~IF[ `this$V の `family name^i ~EQ ~NULL ] ⇒ ~RET `this$V の `family name^i ◎ If this's family name is null, then return this's given name.
- ~RET 次を順に`連結する$ ⇒# `this$V の `given name^i, `0020^U ~SPACE, `this$V の `family name^i ◎ Return the concatenation of this's given name, followed by U+0020 SPACE, followed by this's family name.
この~IDLの~JS実装は、 次に従って挙動することになる: ◎ A JavaScript implementation of the IDL would behave as follows:
var %s = new Student();
%s.id = 12345679;
%s.familyName = 'Smithee';
%s.givenName = 'Alan';
var %挨拶 = 'こんにちは、 ' + %s + ' さん。';
/*
`こんにちは、 Alan Smithee さん^l になる。
◎
Now greeting == 'Hi Alan Smithee'.
*/
2.5.6. 特殊~演算
`特殊~演算@ ( `special operation^en )は、[ その特殊~演算~宣言が現れる~ifcを実装する~obj ]上の[ 一定の種類の特殊な挙動 ]の宣言である。 `特殊~演算$は,演算~宣言において `特殊~keyword@ を利用して宣言される。 ◎ 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 a special keyword in an operation declaration.
`特殊~演算$には、 次の表tに挙げる 3 種類がある。 表tには、 各~特殊~演算に対し, それを宣言するために利用される特殊~keyword, および 演算の目的も示す: ◎ There are three 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 ◎ Keyword | 目的 ◎ Purpose |
---|---|---|
`取得子@ | `getter^sym | ~propの検索取得~用に~objが~index-される際の挙動を定義する。 ◎ Defines behavior for when an object is indexed for property retrieval. |
`設定子@ | `setter^sym | ~prop[ 代入/作成 ]用に~objが~index-される際の挙動を定義する。 ◎ Defines behavior for when an object is indexed for property assignment or creation. |
`削除子@ | `deleter^sym | ~prop削除 用に~objが~index-される際の挙動を定義する。 ◎ Defines behavior for when an object is indexed for property deletion. |
すべての言語束縛が、 これら 3【!four】 種類の[ ~objの特殊な挙動 ]すべてを~supportするわけではない。 `特殊~演算$が,識別子を伴わない演算を利用して宣言された場合、 その特定0の種類の特殊~演算を~supportしない言語束縛においては,単にその機能性が存在しないことになる。 ◎ Not all language bindings support all of the four 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.
次の~IDL片は、 取得子と設定子を伴う~ifcを定義する: ◎ The following IDL fragment defines an interface with a getter and a setter:
[Exposed=Window] interface Dictionary { readonly attribute unsigned long propertyCount; getter double (DOMString %propertyName); setter undefined (DOMString %propertyName, double %propertyValue); };
~propの取得子や設定子を~supportしない言語束縛においては、 `Dictionary^T を実装している~objには,この特殊な挙動は無いことになる。 ◎ In language bindings that do not support property getters and setters, objects implementing Dictionary will not have that special behavior.
`特殊~演算$を`識別子$を伴わせて定義することは、 その宣言から識別子のない特殊~演算を分離することと,等価である。 この書き方は、 ~ifcの演算を成す`~method手続き$を単純~化するために許容されている。 ◎ 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 method steps of an interface’s operations.
次の 2 つの~ifcは等価である: ◎ The following two interfaces are equivalent:
[Exposed=Window] interface Dictionary { readonly attribute unsigned long propertyCount; getter double getProperty(DOMString %propertyName); setter undefined setProperty(DOMString %propertyName, double %propertyValue); };
[Exposed=Window] interface Dictionary { readonly attribute unsigned long propertyCount; double getProperty(DOMString %propertyName); undefined setProperty(DOMString %propertyName, double %propertyValue); getter double (DOMString %propertyName); setter undefined (DOMString %propertyName, double %propertyValue); };
1 つの演算に同じ`特殊~keyword$が複数~回 現れてはナラナイ。 ◎ A given special keyword must not appear twice on an operation.
取得子, 設定子, 削除子は 2 種の系列に分類される: ◎ Getters and setters come in two varieties:\
- `有名~prop取得子@, `有名~prop設定子@, `有名~prop削除子@ と呼ばれる,~prop名として `DOMString$T をとるもの。 ◎ ones that take a DOMString as a property name, known as named property getters and named property setters, and\
- `有index~prop取得子@, `有index~prop設定子@ と呼ばれる,~prop~indexとして `unsigned long$T をとるもの — 有index~propには,`削除子は無い^em。 ◎ 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.\
詳細は、 `有index~prop@#idl-indexed-properties§, `有名~prop@#idl-named-properties§ を見よ。 ◎ See § 2.5.6.1 Indexed properties and § 2.5.6.2 Named properties for details.
所与の`~ifc$上に存在する[ `削除子$ および, 各~系列の[ `取得子$, `設定子$ ]]は、 それぞれ,高々 1 個まででなければナラナイ。 ◎ On a given interface, there must exist at most one named property deleter, and at most one of each variety of getter and setter.
~ifcが[ いずれかの系列の`設定子$, あるいは`有名~prop削除子$ ]を有する場合、 同じ系列の`取得子$も有さなければナラナイ。 ◎ 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.
~objが,所与の`特殊~演算$を定義する複数の`~ifc$を実装する場合、 その演算に対し,どの特殊~演算が呼出されるかは 未定義である。 ◎ If an object implements more than one interface that defines a given special operation, then it is undefined which (if any) special operation is invoked for that operation.
2.5.6.1. 有index~prop
`有index~prop取得子$を定義する`~ifc$は、 `有index~propを~support@ するという。 そのような~ifcを実装する`~platform~obj$もまた,`有index~propを~support$するという。 ◎ An interface that defines an indexed property getter is said to support indexed properties. By extension, a platform object is said to support indexed properties if it implements an interface that itself does.
~ifcが`有index~propを~support$する場合、 その~ifc定義には,所与の任意の時点で~objに~index-できる~indexについての記述も付随していなければナラナイ。 これらの~indexは、 ~objが `~supportする~prop~index@ と呼ばれる。 ◎ 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.
`有index~propを~support$する~ifcは、 `整数~型$である 名前 `length^l の属性を定義しなければナラナイ。 ◎ Interfaces that support indexed properties must define an integer-typed attribute named "length".
`有index~prop取得子$は、 1 個の `unsigned long$T 引数をとるように宣言されなければナラナイ。 有index~propの設定子は、 2 個の引数をとり, 1 個目の引数が `unsigned long$T をとるように宣言されなければナラナイ。 ◎ Indexed property getters must be declared to take a single unsigned long argument. Indexed property setters must be declared to take two arguments, where the first is an unsigned long.
interface `interface_identifier^i { getter `type^i `identifier^i(unsigned long `identifier^i); setter `type^i `identifier^i(unsigned long `identifier^i, `type^i `identifier^i); getter `type^i (unsigned long `identifier^i); setter `type^i (unsigned long `identifier^i, `type^i `identifier^i); };
次に挙げる要件が[ `有index~prop取得子$/`有index~prop設定子$ ]の定義に適用される — 以下における[ %A は それを宣言した~ifc, %O は %A を`実装-$する~obj ]を表すとする: ◎ The following requirements apply to the definitions of indexed property getters and setters:
-
`有index~prop取得子$の宣言に利用された`演算$ %演算 が`識別子$を: ◎ ↓
- 有する場合: %O に対し,所与の ( %O が`~supportする~prop~index$ %~index ) で~index-したときの返り値は、 %演算 を引数 ( %~index ) を渡して呼出したときと同じになる。 ◎ 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.\
- 有さない場合: %A の定義には, `有index~propの値を決定する手続き@ も付随していなければナラナイ — それは、 所与の ( %O が`~supportする~prop~index$ %~index ) に対し, %~index に対応する~propの値を決定する方法を述べる。 ◎ 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.
-
`有index~prop設定子$の宣言に利用された`演算$ %演算 が`識別子$を: ◎ ↓
- 有する場合: %O に対し,所与の ( %O が`~supportする~prop~index$ %~index, 値 %値 ) で~prop代入~用に~index-したときの挙動は、 %演算 を引数 ( %~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.\
- 有さない場合: %A の定義には,[ `既存の有index~propを設定する手続き@ , `新たな有index~propを設定する手続き@ ]も付随していなければナラナイ — それらは、 所与の ( 負でない整数 %~index, 値 %値 ) に対し, %~index に対応する~propに %値 を設定する方法を述べる。 ◎ 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.
注記: `有index~prop$の[ 取得子/設定子 ]が,`識別子$を伴う`演算$を利用して指定された場合、[ %O が`~supportする~prop~index$でない整数 %~index ]で~index-したときの挙動は, 当の演算に %~index を渡して呼出したときと同じになるとは限らない。 この事例における実際の挙動は、 言語束縛に特有になる。 ◎ 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.
~JS言語束縛においては,定例の~prop検索が行われる。 例えば次の~IDLでは: ◎ In the JavaScript language binding, a regular property lookup is done. For example, take the following IDL:
[Exposed=Window] interface A { getter DOMString toWord(unsigned long %index); };
`A^T を実装している~objが`~supportする~prop~index$は、 0 以上 2 未満とする。 また、 `toWord^M は,引数の数を英単語に変換した文字列を返すように定義されているとする。 範囲~外の~indexで`演算$を呼出したときの挙動は、 ~objを直に~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:
var %a = getA(); %a.toWord(0); /* `zero^l に評価される。 ◎ Evaluates to "zero". */ %a[0]; /* これも `zero^l に評価される。 ◎ Also evaluates to "zero". */ %a.toWord(5); /* `five^l に評価される。 ◎ Evaluates to "five". */ %a[5]; /* ~prop `5^l は存在しないので `undefined^jv に評価される。 ◎ Evaluates to undefined, since there is no property "5". */
次の`~IDL片$は、 名前または~indexにより値を[ 検索取得できる/設定できる ]ようにする `OrderedMap^T ~ifcを定義する: ◎ The following IDL fragment defines an interface OrderedMap which allows retrieving and setting values by name or by index number:
[Exposed=Window] interface OrderedMap { readonly attribute unsigned long size; getter any getByIndex(unsigned long %index); setter undefined setByIndex(unsigned long %index, any %value); getter any get(DOMString %name); setter undefined set(DOMString %name, any %value); };
どの特殊~演算も識別子を伴う演算を利用して宣言されているので、 必要yな唯一の注釈文は,これらの集合が有する~keyを与える記述になる。 `get()^M 演算が[ `OrderedMap^T 内に存在しない~itemを検索しようと試みられたときは, `null^V を返す ]ように定義されているとするとき、 次の 2 つの~~文で足りるであろう: ◎ 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:
`OrderedMap^T を実装する~obj %map は、 範囲 { 0 〜 `map.size^c ~MINUS 1 } の`有index~propを~support$する。 ◎ An object map implementing OrderedMap supports indexed properties with indices in the range 0 ≤ index < map.size.
そのような~objは、[ `get()^M に渡されたとき,非 `null^V 値を返す ]ような どの名前に対しても,有名~propを~supportする。 ◎ Such objects also support a named property for every name that, if passed to get(), would return a non-null value.
~JS実装は — `旧来の~platform~obj@~WEBIDLjs#js-legacy-platform-objects§にて述べられるように — [ 有名, 有index ]どちらの~prop集合に対しても,その集合に属する各項に対応する~propを[ `OrderedMap^T を実装している`旧来の~platform~obj$ ]上に作成することになる。 下にデモられるように、 これらの~propは,[ ~objの~methodの呼出ngと同じ仕方で,~objとヤリトリする ]ために利用できる: ◎ As described in § 3.9 Legacy platform objects, a JavaScript implementation would create properties on a legacy 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:
/* %map は `OrderedMap^T ~ifcを実装する旧来の~platform~objであるとする: ◎ Assume map is a legacy platform object implementing the OrderedMap interface. */ var %map = getOrderedMap(); var %x, %y; %x = %map[0]; /* `map.length^c ~GT 0 ならば、 これは `x = map.getByIndex(0)^c と等価になる (名前 `0^l の~propが %map 上に置かれるので)。 他の場合、 名前 `0^l の~propは %map 上にないので, %x は `undefined^jv に設定されることになる。 ◎ 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; /* これは、 `map.setByIndex(1, false)^c と等価な動作になる。 ◎ This will do the equivalent of: map.setByIndex(1, false) */ %y = %map.apple; /* 名前 `apple^l の有名~propが存在する場合、 %map 上には名前 `apple^l の~propがあり, `y = map.get('apple')^c と等価な動作になる。 他の場合、 %map 上に名前 `apple^l の~propはないので, %y は `undefined^jv に設定されることになる。 ◎ 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; /* これは、 `map.set('berry', 123)^c と等価な動作になる。 ◎ This will do the equivalent of: map.set('berry', 123) */ delete %map.cake; /* 有名~prop `cake^l が存在するならば、 `cake^jp ~propは削除され, `map.remove("cake")^c と等価な動作になる。 ◎ If a named property named "cake" exists, then the "cake" property will be deleted, and then the equivalent to the following will be performed: map.remove("cake") */
2.5.6.2. 有名~prop
`有名~prop取得子$を定義する`~ifc$は、 `有名~propを~support@ するという。 そのような~ifcを実装する`~platform~obj$も,`有名~propを~support$するという。 ◎ An interface that defines a named property getter is said to support named properties. By extension, a platform object is said to support named properties if it implements an interface that itself does.
`有名~propを~support$する~ifcの~ifc定義には、[ 所与の任意の時点で~objに~index-できる名前たちが成す有順序~集合 ]についての記述も付随していなければナラナイ。 これらの名前は、 ~objが `~supportする~prop名@ と呼ばれる。 ◎ 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.
有名~propの取得子と削除子は、 1 個の `DOMString$T 引数をとるように宣言されなければナラナイ。 有名~propの設定子は、 2 個の引数をとり, 1 個目の引数に `DOMString$T をとるように宣言されなければナラナイ。 ◎ Named property getters and deleters must be declared to take a single DOMString argument. Named property setters must be declared to take two arguments, where the first is a DOMString.
interface `interface_identifier^i { getter `type^i `identifier^i(DOMString `identifier^i); setter `type^i `identifier^i(DOMString `identifier^i, `type^i `identifier^i); deleter `type^i `identifier^i(DOMString `identifier^i); getter `type^i (DOMString `identifier^i); setter `type^i (DOMString `identifier^i, `type^i `identifier^i); deleter `type^i (DOMString `identifier^i); };
次に挙げる要件が[ `有名~prop取得子$/`有名~prop設定子$/`有名~prop削除子$ ]の定義に適用される — 以下における[ %A は それを宣言した~ifc, %O は %A を`実装-$する~obj ]を表すとする: ◎ The following requirements apply to the definitions of named property getters, setters and deleters:
-
`有名~prop取得子$の宣言に利用された`演算$ %演算 が`識別子$を: ◎ ↓
- 有する場合: %O に対し,所与の ( %O が`~supportする~prop名$ %名前 ) で~index-したときは、 %演算 を引数 ( %名前 ) を渡して呼出したときと結果を返す。 ◎ 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.\
- 有さない場合: %A の定義には, `有名~propの値を決定する手続き@ も付随していなければナラナイ — それは、 所与の ( %O が`~supportする~prop名$ %名前 ) に対し, %名前 に対応する~propの値を決定する方法を述べる。 ◎ 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.
-
`有名~prop設定子$の宣言に利用された`演算$ %演算 が`識別子$を: ◎ ↓
- 有する場合: %O に対し,所与の ( %O が`~supportする~prop名$ %名前, 値 %値 ) で~prop代入~用に~index-した ときの挙動は、 %演算 を引数 ( %名前, %値 ) を渡して呼出したときと同じになる。 ◎ 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.\
- 有さない場合: %A の定義には,[ `既存の有名~propを設定する手続き@ , `新たな有名~propを設定する手続き@ ]も付随していなければナラナイ — それらは、 所与の ( ~prop名 %名前, 値 %値 ) に対し, %名前 に対応する~propに %値 を設定する方法を述べる。 ◎ 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.
-
`有名~prop削除子$の宣言に利用された`演算$ %演算 が`識別子$を: ◎ ↓
- 有する場合: %O に対し,所与の ( %O が`~supportする~prop名$ %名前 ) で~prop削除~用に~index-したときの挙動は、 %演算 を引数 ( %名前 ) を渡して呼出したときと同じになる。 ◎ 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.\
- 有さない場合: %A の定義には, `既存の有名~propを削除する手続き@ も付随していなければナラナイ — それは、 所与の ( %O が`~supportする~prop名$ %名前 ) に対し, %名前 に対応する~propを削除する方法を述べる。 ◎ 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.
注記: `有index~prop$のときと同じく,`有名~prop$の[ 取得子/設定子/削除子 ]が`識別子$を伴う`演算$を利用して指定された場合、 ~objに対し[ ~objが`~supportする~prop名$でない名前で~index-した ]ときの挙動は[ 当の演算を同じ名前で呼出した ]ときと同じになるとは限らない。 挙動は、 言語束縛に特有になる。 ◎ Note: As with indexed properties, if an named property getter, setter or deleter is specified using an operation with an identifier, then indexing an object with a name that is not a supported property name does not necessarily elicit the same behavior as invoking the operation with that name; the behavior is language binding specific.
2.5.7. 静的~属性と静的~演算
[ `静的~属性@ ( `static attribute^en )/ `静的~演算@ ( `static operation^en ) ]は、 それが宣言される`~ifc$の特定0の~instanceには結付けられないものであり、 代わりに,当の~ifc自身に結付けられる。 [ 静的~属性/静的~演算 ]は、 自身の宣言の中で `static^sym ~keywordを利用して宣言される。 ◎ Static attributes and static operations are ones that are not associated with a particular instance of the interface on which it is declared, and is instead associated with the interface itself. Static attributes and operations are declared by using the static keyword in their declarations.
[ 静的~演算を呼出す/ 静的~属性を取得する/ 静的~属性を設定する ]ことが,~ifcの~instanceへの参照を通してアリかどうかは、 言語束縛に特有になる。 ◎ 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.
次の`~IDL片$は、 静的~演算が宣言されている `Circle^T ~ifcを定義する: ◎ The following IDL fragment defines an interface Circle that has a static operation declared on it:
[Exposed=Window] interface Point { /* ... */ }; [Exposed=Window] 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); };
~JS言語束縛においては、 `Circle^T 用の`~ifc~obj$上に, `triangulate^M に対応する`関数~obj$, および `triangulationCount^M に対応する~accessor~prop が存在することになる: ◎ In the JavaScript language binding, the function object for triangulate and the accessor property for triangulationCount will exist on the interface object for Circle:
var %circles = getCircles(); /* `Circle^T ~objの `Array^jt ◎ an Array of Circle objects */ typeof Circle.triangulate; /* */ typeof Circle.triangulationCount; /* `number^l に評価される。 ◎ Evaluates to "number" */ Circle.prototype.triangulate; /* `undefined^jv に評価される。 ◎ Evaluates to undefined */ Circle.prototype.triangulationCount; /* これも `undefined^jv に評価される。 ◎ Also evaluates to undefined */ %circles[0].triangulate; /* これも。 ◎ As does this */ %circles[0].triangulationCount; /* これも。 ◎ And this */ /* 静的~演算の~call: ◎ Call the static operation */ var %triangulationPoint = Circle.triangulate(%circles[0], %circles[1], %circles[2]); /* `triangulate^M を呼んだ回数を調べる: ◎ Find out how many triangulations we have done */ window.alert(Circle.triangulationCount);
2.5.8. 多重定義
`~ifc$上に定義される[ `正則~演算$/`静的~演算$ ]が,その~ifcの同じ種類の別の(正則/静的)演算と同じ`識別子$を有する場合、 その演算は `多重定義@ ( `overload^en )されているという。 その~ifcを実装する~obj上で[ それらの演算のどれかを呼出すために[ 多重定義された演算の識別子 ]が利用された ]ときに,どの演算が実際に呼出されるかは、 演算に渡された ( 引数の個数, それらの各 型 ) により決定される。 `構築子~演算$も多重定義され得る。 多重定義された[ 演算/構築子 ]がとれるものと指定される引数には,一定の制約があり、 これらの制約を記述するため,`有効-多重定義~集合$の観念が利用される。 ◎ 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. Constructor operations can be overloaded too. There are some restrictions on the arguments that overloaded operations and constructors can be specified to take, and in order to describe these restrictions, the notion of an effective overload set is used.
多重定義された`演算$が成す集合は、 次のいずれかでなければナラナイ ⇒# どの`演算$も`返り値~型$は`~promise型$でない/ どの`演算$も`返り値~型$は`~promise型$である ◎ A set of overloaded operations must either: • contain no operations whose return type is a promise type; • only contain operations whose return type is a promise type.
`演算$は、 複数の[ `~ifc$, `部分的な~ifc$, `~ifc~mixin$, `部分的な~ifc~mixin$ ]にまたがって多重定義してはナラナイ。 ◎ Operations must not be overloaded across interface, partial interface, interface mixin, and partial interface mixin definitions.
注記: 例えば,次の様な `f^T, `g^T の多重定義は許容されない: ◎ For example, the overloads for both f and g are disallowed:
[Exposed=Window] interface A { undefined f(); }; partial interface A { undefined f(double %x); undefined g(); }; partial interface A { undefined g(DOMString %x); };
構築子の多重定義については、 元々`部分的な~ifc定義$上には[ `構築子~演算$ / `LegacyFactoryFunction$x `拡張d属性$ ]の出現が許容されていないので,同様の制約は~~自動的に満たされることに注意。 ◎ Note that constructor operations and [LegacyFactoryFunction] extended attributes are disallowed from appearing on partial interface definitions, so there is no need to also disallow overloading for constructors.
`有効-多重定義~集合@ ( `effective overload set^en )は、 特定0の `関数類@ — [ `演算$ / 構築子 (`構築子~演算$, または `LegacyFactoryFunction$x により指定される`旧来の~factory関数$) / `~callback関数$† ] — に許容され得る呼出nを表現する。
【 “関数類(引数を伴って~callできる~IDL構成子)” は、 簡潔に総称できるよう,この訳にて導入した用語である。 】【† `~callback関数$は、 `多重定義できないものとされた@https://github.com/whatwg/webidl/commit/b47c90c9c503b56d05bcfc30c12e2285ebe63a28$ 。 】
`有効-多重定義~集合を算出する$ための~algoは、 次に挙げる~IDL構成子いずれかに対し演算する。 算出するために必要な入力は、 渡される引数の個数, および`関数類$の~~種別に応じて, 以下に示されるものになる:
◎ An effective overload set represents the allowable invocations for a particular operation, constructor (specified with a constructor operation or [LegacyFactoryFunction]), or callback function. The algorithm to compute the effective overload set operates on one of the following four 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
- `演算$が見出される`~ifc$, および 演算の`識別子$ ◎ the interface on which the operations are to be found ◎ the identifier of the operations ◎ the number of arguments to be passed
- `構築子~演算$ ◎ For constructors
- `構築子~演算$が見出される`~ifc$ ◎ the interface on which the constructor operations are to be found ◎ the number of arguments to be passed
- `旧来の~factory関数$ ◎ For legacy factory functions
- `LegacyFactoryFunction$x `拡張d属性$が見出される`~ifc$, および 当の旧来の~factory関数の`識別子$ ◎ the interface on which the [LegacyFactoryFunction] extended attributes are to be found ◎ the identifier of the legacy factory function ◎ the number of arguments to be passed
`有効-多重定義~集合$は、 ~ifc上に多重定義された`関数類$たちに多義性があるかどうかを — 他と伴に — 決定するために利用される。 ◎ An effective overload set is used, among other things, to determine whether there are ambiguities in the overloaded operations and constructors specified on an interface.
`有効-多重定義~集合$は、 `有順序~集合$であり,それを成す各`~item$は ( `~callable$oL, `型~list$oL, `省略可否~list$oL ) の形をとる`~tuple$である — この~tupleを成す各`~item$sctは: ◎ The items of an effective overload set are tuples of the form (callable, type list, optionality list) whose items are described below:
- `~callable@oL
-
`関数類$の~~種別に応じて,次で与えられる:
- `正則~演算$
- `静的~演算$
- `構築子~演算$
- 【同じ識別子を共有する】いずれかの`演算$
- `旧来の~factory関数$
- 【同じ識別子を共有する】いずれかの`拡張d属性$
- `型~list@oL
- ~IDL型たちが成す`~list$ — `~callable$oL の引数たちにあてがわれているそれらになる。 ◎ A type list is a list of IDL types.
- `省略可否~list@oL
- `省略可否 値@ たちが成す`~list$。 各 `省略可否 値$にアリな値は、 次のいずれかであり,所与の~indexに位置する引数について指示する ⇒# `必須^C — 引数は省略できない / `省略可^C — `随意~引数$である / `可変個^C — `可変個~引数$である ◎ An 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.
各`~tuple$は、 当の`関数類$に対する[ 所与の型の引数~値たちが成す~listを伴う呼出n ]として許容-可能なものを表現する。 [ `随意~引数$/[ `可変個的な$`関数類$ (すなわち,演算または構築子) ]]の利用に因り、 `有効-多重定義~集合$内には,同じ種類の`関数類$を識別する複数個の~itemが存在し得る。 ◎ Each tuple represents an allowable invocation of the operation, constructor, 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 items in an effective overload set identifying the same operation or constructor.
`有効-多重定義~集合を算出する@ 方法は、 以下の~algoに述べられる。 必要に応じて,上述の入力~変数が利用される: ◎ The algorithm below describes how to compute the effective overload set. The following input variables are used, if they are required:
- %A は[ 演算/旧来の~factory関数 ]の識別子 ◎ the identifier of the operation or legacy factory function is A
- %N は引数~個数 ◎ the argument count is N
- %I は~ifc ◎ the interface is I
以下において言及される,拡張d属性の引数は、 その`有名~引数~list$の引数を指すとする。 ◎ Whenever an argument of an extended attribute is mentioned, it is referring to an argument of the extended attribute’s named argument list.
- %S ~LET 新たな`有順序~集合$ ◎ Let S be an ordered set.
-
%F ~LET [ `有効-多重定義~集合$の種類に応じて,次で与えられる~itemたち ]が成す新たな`有順序~集合$: ◎ Let F be an ordered set with items as follows, according to the kind of effective overload set:
- 正則~演算 ⇒ %I 上で定義された`正則~演算$のうち,[ その識別子 ~EQ %A ]なるもの ◎ For regular operations • The elements of F are the regular operations with identifier A defined on interface I.
- 静的~演算 ⇒ %I 上で定義された`静的~演算$のうち,[ その識別子 ~EQ %A ]なるもの ◎ For static operations • The elements of F are the static operations with identifier A defined on interface I.
- 構築子 ⇒ %I の`構築子~演算$たち ◎ For constructors • The elements of F are the constructor operations on interface I.
- 旧来の~factory関数 ⇒ %I の `LegacyFactoryFunction$x `拡張d属性$のうち,[ その`有名~引数~list$の識別子 ~EQ %A ]なるもの ◎ For legacy factory functions • The elements of F are the [LegacyFactoryFunction] extended attributes on interface I whose named argument lists' identifiers are A.
-
%最大~引数~個数 ~LET [ %F 内の各~item(`関数類$)が宣言している引数~個数 ]の最大 — ただし,`可変個的な$`関数類$の中の`可変個~引数$は、 1 個の引数に数える ◎ Let maxarg be the maximum number of arguments the operations, legacy factory functions, or callback functions in F are declared to take. For variadic operations and legacy factory functions, the argument on which the ellipsis appears counts as a single argument.
注記: したがって `undefined f(long x, long... y);^c が宣言している引数~個数は 2 個と見なされる。 ◎ Note: So undefined f(long x, long... y); is considered to be declared to take two arguments.
- %最大 ~LET `max$op( %最大~引数~個数, %N ) ◎ Let max be max(maxarg, N).
-
%F を成す ~EACH( %X ) に対し: ◎ For each operation or extended attribute X in F:
- %引数~群 ~LET %X がとるよう宣言されている引数たちが成す`~list$ ◎ Let arguments be the list of arguments X is declared to take.
- %n ~LET %引数~群 の`~size$ (したがって %n ~LTE %最大 ) ◎ Let n be the size of arguments.
- %型~list ~LET 新たな`~list$ (これは、 `型~list$oLを与えることになる) ◎ Let types be a type list.
- %省略可否~list ~LET 新たな`~list$ (これは、 `省略可否~list$oLを与えることになる) ◎ Let optionalityValues be an optionality list.
-
%引数~群 を成す ~EACH( %引数 ) に対し: ◎ For each argument in arguments:
- %型~list に %引数 の型を`付加する$ ◎ Append the type of argument to types.
- %省略可否~list に[ %引数 に応じて,次で与えられる値 ]を`付加する$ ⇒# `可変個~引数$ならば `可変個^C / ~ELSE_ `随意~引数$ならば `省略可^C / ~ELSE_ `必須^C ◎ Append "variadic" to optionalityValues if argument is a final, variadic argument, "optional" if argument is optional, and "required" otherwise.
- %S に `~tuple$( %X, %型~list, %省略可否~list ) を`付加する$set ◎ Append the tuple (X, types, optionalityValues) to S.
-
~IF[ %X は `可変個的な$ものと宣言されている ]: ◎ If X is declared to be variadic, then:
-
~EACH( 整数 %i ~IN { %n, %最大 ~MINUS 1 }) に対し,~~昇順に: ◎ For each i in the range n to max − 1, inclusive:
- %t ~LET %型~list の複製 ◎ Let t be a type list.
- %o ~LET %省略可否~list の複製 ◎ Let o be an optionality list. ◎ For each j in the range 0 to n − 1, inclusive: • Append types[j] to t. • Append optionalityValues[j] to o.
-
~EACH( 整数 %j ~IN { %n 〜 %i } ) に対し: ◎ For each j in the range n to i, inclusive:
- %t に %型~list[ %n ~MINUS 1 ] を`付加する$ ◎ Append types[n − 1] to t.
- %o に `可変個^C を`付加する$ ◎ Append "variadic" to o.
- %S に`~tuple$( %X, %t, %o ) を`付加する$set ◎ Append the tuple (X, t, o) to S.
-
-
~EACH( 整数 %i ~IN { 0 〜 %n ~MINUS 1 } ) に対し,~~降順に: ◎ Let i be n − 1. ◎ While i ≥ 0:
- ~IF[ %省略可否~list[ %i ] ~EQ `必須^C ] ⇒ ~BREAK ◎ If arguments[i] is not optional (i.e., it is not marked as "optional" and is not a final, variadic argument), then break.
- [ %t, %o ] ~LET 順に[ %型~list, %省略可否~list ]の複製 ◎ ↓
- [ %t, %o ]それぞれに対し,その尾部から 0 個~以上の~itemたちを[ その`~size$ ~EQ %i ]になるよう除去する ◎ Let t be a type list. ◎ Let o be an optionality list. ◎ For each j in the range 0 to i − 1, inclusive: • Append types[j] to t. • Append optionalityValues[j] to o.
-
%S に`~tuple$( %X, %t, %o ) を`付加する$set ◎ Append the tuple (X, t, o) to S.
注記: %i ~EQ 0 ならば %t, %o は`空$になる。 ◎ Note: if i is 0, this means to add to S the tuple (X, « », « »); (where "« »" represents an empty list). ◎ Set i to i − 1.
- ~RET %S ◎ Return S.
次の~ifcに対し: ◎ For the following interface:
[Exposed=Window] interface A { /* f1 */ undefined f(DOMString %a); /* f2 */ undefined f(Node %a, DOMString %b, double... %c); /* f3 */ undefined f(); /* f4 */ undefined f(Event %a, DOMString %b, optional DOMString %c, double... %d); };
`Node^T と `Event^T は、 どの~objからも両方同時には実装できない,別々な~ifcとする。 [ 識別子 `f^sym, 引数~個数 4 ]の`正則~演算$たちが成す`有効-多重定義~集合$は: ◎ assuming Node and Event are two other interfaces of which no object can implement both, the effective overload set for regular operations with identifier f and argument count 4 is:
« (f1, « DOMString », « `必須^C »), (f2, « Node, DOMString », « `必須^C, `必須^C »), (f2, « Node, DOMString, double », « `必須^C, `必須^C, `可変個^C »), (f2, « Node, DOMString, double, double », « `必須^C, `必須^C, `可変個^C, `可変個^C »), (f3, « », « »), (f4, « Event, DOMString », « `必須^C, `必須^C »), (f4, « Event, DOMString, DOMString », « `必須^C, `必須^C, `省略可^C »), (f4, « Event, DOMString, DOMString, double », « `必須^C, `必須^C, `省略可^C, `可変個^C ») »
2 つの型は、 次の~algoが ~T を返すならば, `判別-可能@ であるとされる: ◎ Two types are distinguishable if the following algorithm returns true.
-
~IF[ 一方の型は`~nullable型を内包する$ ]~AND[ 他方の型は ~OR↓ を満たす ]…
- `~nullable型を内包する$
- [ `共用体~型$である ]~AND[ その`平坦~化~mb型~群$に`辞書~型$が含まれている ]
- `辞書~型$である
…ならば ⇒ ~RET ~F
◎ If one type includes a nullable type and the other type either includes a nullable type, is a union type with flattened member types including a dictionary type, or is a dictionary type, return false.次に挙げる各~pairは、 どれも判別-可能でない:
- `double?^T と `Dictionary1^T
- `(Interface1 or long)?^T と `(Interface2 or DOMString)?^T
- `(Interface1 or long?)^T と `(Interface2 or DOMString)?^T
- `(Interface1 or long?)^T と `(Interface2 or DOMString?)^T
- `(Dictionary1 or long)^T と `(Interface2 or DOMString)?^T
- `(Dictionary1 or long)^T と `(Interface2 or DOMString?)^T
( `Interface1^T, `Interface2^T は ~ifc型, `Dictionary1^T は 辞書~型とする)
◎ None of the following pairs are distinguishable: • double? and Dictionary1 • (Interface1 or long)? and (Interface2 or DOMString)? • (Interface1 or long?) and (Interface2 or DOMString)? • (Interface1 or long?) and (Interface2 or DOMString?) • (Dictionary1 or long) and (Interface2 or DOMString)? • (Dictionary1 or long) and (Interface2 or DOMString?) - ~IF[ どちらの型も[ `共用体~型$ /`~nullable$な`共用体~型$ ]である ] ⇒ ~RET ~IS[ 両者のどの`~mb型$どうしも互いに判別-可能である ] ◎ If both types are either a union type or nullable union type, return true if each member type of the one is distinguishable with each member type of the other, or false otherwise.
- ~IF[ 一方の型は[ `共用体~型$ /~nullable共用体~型 ]である ] ⇒ ~RET ~IS[ その共用体のどの`~mb型$も 他方の型と`判別-可能$である ] ◎ If one type is a union type or nullable union type, return true if each member type of the union type is distinguishable with the non-union type, or false otherwise.
-
~IF[ どちらの型も,その`最も内縁な型$は[ 下の表tに現れるか, 下の表tに現れる分類に入る ]~AND[[ それらに対応する欄に “●” 印がある ]~OR[ 対応する欄に英字が在って,表tの下に指定される追加的な要件を満たす ]] ⇒ ~RET ~T
ここで、 所与の型 %T の `最も内縁な型@ は,次に従って決定される型とする:
- ~IF[ %T は`注釈された型$である ] ⇒ %T ~SET %T の`内縁~型$anO
- ~IF[ %T は`~nullable型$である ] ⇒ %T ~SET %T の`内縁~型$
- ~RET %T
下の表tに現れる分類は、 次で定義される: ◎ Categories:
- ~ifc類 ⇒# `~ifc型$ / `~buffer~source型$ ◎ interface-like • interface types • buffer source types
- 辞書~類 ⇒# `辞書~型$ / `~record型$ / `~callback~ifc型$ ◎ dictionary-like • dictionary types • record types • callback interface types
- 連列~類 ⇒# `連列~型$ / `凍結d配列~型$ ◎ sequence-like • sequence types • frozen array types
`undefined$T `boolean$T `数量-型$ `bigint$T `文字列~型$ `object$T `symbol$T ~ifc類 `~callback関数$ 辞書~類 連列~類 `undefined$T ● ● ● ● ● ● ● ● ● `boolean$T ● ● ● ● ● ● ● ● ● `数量-型$ (b) ● ● ● ● ● ● ● `bigint$T ● ● ● ● ● ● ● `文字列~型$ ● ● ● ● ● ● `object$T ● `symbol$T ● ● ● ● ~ifc~類 (a) ● ● ● ~callback関数 (c) ● 辞書~類 ● 連列~類 - (a) — 識別される 2 つの~ifc類の型が同じ`~platform~obj$に実装されることは、 起こり得ない(特に, 2 つは同じ~ifcでない)。 ◎ The two identified interface-like types are not the same, and no single platform object implements both interface-like types.
- (b) — これら 2 つの型は`判別-可能$ではあるが 【すなわち,この段の目的においては無条件であるが】、 `多重定義するときの利用には,別々な制約がある@#limit-bigint-numeric-overloading$。 `これらの型が成す共用体を利用する際の助言@#limit-bigint-numeric-unions$にも注意されたし。 ◎ The types are distinguishable, but there is a separate restriction on their use in overloading below. Please also note the advice about using unions of these types.
-
(c) — `~callback関数$の方が `LegacyTreatNonObjectAsNull$x 拡張d属性を伴わない。 ◎ A callback function that does not have [LegacyTreatNonObjectAsNull] extended attribute is distinguishable from a type in the dictionary-like category.
注記: 例えば,~JS【!ECMAScript】値を[ ある`~callback関数$, ある辞書~類 ]を含んでいる`共用体~型$へ変換するとき、 当の値は,[ それが`~callable$である場合は`~callback関数$/ ~ELSE_ 辞書~類の型 ]へ変換される。 ◎ For example, when converting an ECMAScript value to union type which includes a callback function and a dictionary-like type, if the value is callable, then it is converted to a callback function. Otherwise, it is converted to a dictionary-like type.
- ~RET ~F ◎ ↑
- `double$T と `DOMString$T とは判別-可能になる — `数量-型$と`文字列~型$の交差する欄に ● 印があるので。 ◎ double and DOMString are distinguishable because there is a ● at the intersection of numeric types with string types.
- `double$T と `long$T は判別-可能でない — 両者とも`数量-型$であり,`数量-型$と`数量-型$の交差する欄に ● 印はないので ◎ double and long are not distinguishable because they are both numeric types, and there is no ● or letter at the intersection of numeric types with numeric types.
-
次の~IDL片が与えられたとするとき: ◎ Given:
callback interface CBIface { undefined handle(); }; [Exposed=Window] interface Iface { attribute DOMString attr2; }; dictionary Dict { DOMString field1; };
`CBIface^T は、 `Iface^T とは 判別-可能になるが (辞書~類 と ~ifc類が交差する欄に ● があるので), `Dict^T とは判別-可能にならない (辞書~類どうしが交差する欄に ● がないので) ◎ CBIface is distinguishable from Iface because there’s a ● at the intersection of dictionary-like and interface-like, but it is not distinguishable from Dict because there’s no ● at the intersection of dictionary-like and itself.
- `~promise型$は、 上の表tには現れていないので,他のどの型とも判別-可能でない。 ◎ Promise types do not appear in the above table, and as a consequence are not distinguishable with any other type.
所与の ( 負でない整数 %~size 【すなわち,引数~個数】, `有効-多重定義~集合$ %S ) に対し、 %T は %S を成す`~item$のうち[ その`型~list$oLの`~size$ ~EQ %~size ]を満たすものたちが成す集合とするとき, %T が複数個の~itemからなるならば: ◎ If there is more than one item in an effective overload set that has a given type list size,\
- 次を満たす~index %i ~IN { 0 〜 %~size ~MINUS 1 } が存在しなければナラナイ ⇒ どの[ %A, %B ~IN %T ]に対しても,次が満たされる ⇒ [ %A ~EQ %B ]~OR[ %A の`型~list$oL[ %i ], %B の`型~list$oL[ %i ] は`判別-可能$である ] ◎ then for those items there must be an index i such that for each pair of items the types at index i are distinguishable.\
-
前項の条件を満たす~indexのうち最小なものを, %~size に対する `判別~引数~index@ という。 ◎ The lowest such index is termed the distinguishing argument index for the items of the effective overload set with the given type list size.
%j を`判別~引数~index$とするとき、 どの[ %A, %B ~IN %T ]に対しても,次が満たされてはナラナイ ⇒ [ %A の`型~list$oL[ %j ] ~EQ `bigint$T ]~AND[ %B の`型~list$oL[ %j ] は`数量-型$である ] ◎ An effective overload set must not contain more than one item with the same type list size, where one item has a bigint argument at the distinguishing argument index and another has a numeric type argument at the distinguishing argument index.
前の例に示された`有効-多重定義~集合$を考える。 `型~list$oL ~size %~size ~IN { 2, 3, 4 } に対するそれは、 いずれも複数の~itemを含む。 これらいずれの %~size に対しても、[ `Node^T, `Event^T ]は`判別-可能$になるので,`判別~引数~index$は 0 になる。 ◎ Consider the effective overload set shown in the previous example. There are multiple items in the set with type lists 2, 3 and 4. For each of these type list size, the distinguishing argument index is 0, since Node and Event are distinguishable.
しかしながら,次の多重定義の利用は妥当でない: ◎ The following use of overloading however is invalid:
[Exposed=Window] interface B { undefined f(DOMString %x); undefined f(USVString %x); };
`DOMString$T と `USVString$T は判別-可能でないので。 ◎ since DOMString and USVString are not distinguishable.
-
加えて,どの %j ~IN { 0 〜 ( %~size に対する`判別~引数~index$ ~MINUS 1 ) } に対しても、 次が満たされなければナラナイ ⇒ どの[ %A, %B ~IN %T ]に対しても,次が満たされる ⇒ [ %A の`型~list$oL[ %i ] ~EQ† %B の`型~list$oL[ %i ] ]~AND[ %A の`省略可否~list$oL[ %i ] ~EQ %B の`省略可否~list$oL[ %i ] ] ◎ In addition, for each index j, where j is less than the distinguishing argument index for a given type list size, the types at index j in all of the items' type lists must be the same, and the optionality values at index j in all of the items' optionality lists must be the same.
【† `注釈された型$とその`内縁~型$anOが,この比較において区別されるのかどうか、 はっきりしない 】
次は妥当でない: ◎ The following is invalid:
[Exposed=Window] interface B { /* f1 */ undefined f(DOMString %w); /* f2 */ undefined f(long %w, double %x, Node %y, Node %z); /* f3 */ undefined f(double %w, double %x, DOMString %y, Node %z); };
引数~個数 4 に対する`有効-多重定義~集合$は: ◎ For argument count 4, the effective overload set is:
« (f1, « DOMString », « `必須^C »), (f2, « long, double, Node, Node », « `必須^C, `必須^C, `必須^C, `必須^C »), (f3, « double, double, DOMString, Node », « `必須^C, `必須^C, `必須^C, `必須^C ») »
であり、 `型~list$oL ~size 4 の~itemを調べると, `Node^T と `DOMString$T は`判別-可能$なので、 `判別~引数~index$は 2 になる。 しかしながら,これらの 2 つの多重定義の~index 0 に位置する引数~型は異なるので、 この多重定義は妥当でない。 ◎ Looking at items with type list size 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.
【 ~~複雑な条件だが,概念的には、 共用体~型を利用して,多重定義された宣言を等価な単独の宣言に併合するために必要な条件が意図されている様に見られる。 例えば、 `先に挙げられた例@#_dist-example-1_$は,次のように書き換え得る: 】
[Exposed=Window] interface A { /*---f4----*/ /*-f2-*/ /*---f1----*/ /*-f3-*/ undefined f( optional ( Event or Node or DOMString ) %a, /*----*/ optional DOMString %b, /*---------------------*/ optional ( DOMString or double ) %c, /*---------------------*/ double... %d /*---------------------*/ ); };
【 これらの書き方の相違は、 `多重定義 vs. 共用体~型@#idl-overloading-vs-union§に述べられている。 】
2.5.8.1. 多重定義 vs. 共用体~型
◎非規範的~IDL`演算$を定義している仕様にとって、 `多重定義$と[[ `共用体~型$, `随意~引数$ ]の組合n ]とは,特能が~~重複しているように見えるかもしれない。 ◎ For specifications defining IDL operations, it might seem that overloads and a combination of union types and optional arguments have some feature overlap.
先ず,重要な点として、 `多重定義$の挙動は[ `共用体~型$, `随意~引数$ ]の間で相違するので,他方を利用しても 全部的には`定義できない^emことに注意 (もちろん、 ~Web~IDL型~systemの目的を無為にしかねない追加的な注釈文が供されない限り)。 例えば `CanvasDrawPath$T ~ifcに定義される `stroke()@~HEcanvas#dom-context-2d-stroke$M 演算 `HTML$r を考える: ◎ It is first important to note that overloads have different behaviors than union types or optional arguments, and one cannot be fully defined using the other (unless, of course, additional prose is provided, which can defeat the purpose of the Web IDL type system). For example, consider the stroke() operations defined on the CanvasDrawPath interface [HTML]:
interface CanvasDrawPathExcerpt { undefined stroke(); undefined stroke(Path2D %path); };
~JS言語束縛により、 `CanvasDrawPathExcerpt^T を実装している~obj上で `stroke(undefined)^c を~callした場合, 2 個目の多重定義を~callしようと試みる結果 `TypeError$jE になる — `undefined^jv は `Path2D$T に`変換-@~WEBIDLjs#js-to-interface$できないので。 しかしながら~~仮に、 演算が,`随意~引数$を伴って定義されていて,一つに併合されていた場合: ◎ Per the JavaScript language binding, calling stroke(undefined) on an object implementing CanvasDrawPathExcerpt would attempt to call the second overload, yielding a TypeError since undefined cannot be converted to a Path2D. However, if the operations were instead defined with optional arguments and merged into one,
interface CanvasDrawPathExcerptOptional { undefined stroke(optional Path2D %path); };
`多重定義~解決~algo$は、 同じ `stroke(undefined)^c ~callに対し, %path 引数 を `missing$C として扱うことになり、 例外は投出されない。 ◎ the overload resolution algorithm would treat the path argument as missing given the same call stroke(undefined), and not throw any exceptions.
注記: この特定0の例では、 後者の挙動が,実際に~Web開発者たちが一般に期待するものである。 今日 `CanvasDrawPath$T を設計するなら、 `stroke()^M には`随意~引数$を利用することになるであろう。 ◎ Note: For this particular example, the latter behavior is actually what Web developers would generally expect. If CanvasDrawPath were to be designed today, optional arguments would be used for stroke().
加えて,意味論上の相違点もある。 `共用体~型$は、 通例的に “どの型もおよそ同じ仕方で働く” ようなイミで利用される。 対照的に,`多重定義$された演算は、 C++ の多重定義などの言語~特能にきちんと対応付けられるように設計されており、 通例的に,引数の型に応じて,何を行うかが かなり相違する演算たちに、 より良く収まる。 しかしながら,ほとんどの事例では、 そのような相違点がある各~演算には異なる名前を伴わせて, ~Web開発者からの混同を避けるのが最上策になる — ~JS言語は、 言語~levelの多重定義を供さないので。 そのため,多重定義は、 新たな~API用に適切になるのは稀であり,旧来の~APIや特化された状況下で現れることが多い。 ◎ Additionally, there are semantic differences as well. Union types are usually used in the sense that "any of the types would work in about the same way". In contrast, overloaded operations are designed to map well to language features such as C++ overloading, and are usually a better fit for operations with more substantial differences in what they do given arguments of different types. However, in most cases, operations with such substantial differences are best off with different names to avoid confusion for Web developers, since the JavaScript language does not provide language-level overloading. As such, overloads are rarely appropriate for new APIs, instead often appearing in legacy APIs or in specialized circumstances.
どの~Web~IDL言語~特能を利用するか決定するのは困難な事例のために、 次の推奨と例を提供する: ◎ That being said, we offer the following recommendations and examples in case of difficulties to determine what Web IDL language feature to use:
-
演算の返り値~型を 引数の型に応じて違える必要があるような,通例的でない事例では、 `多重定義$の方が,より表出力のある~IDL片になる。 ◎ In the unusual case where the operation needs to return values of different types for different argument types, overloading will result in more expressive IDL fragments.\
注記: これが適切な~API設計になることは、 まずない。 そのような事例では、 別個な名前を伴う別々な演算にする方が,通例的に良くなる。 ◎ This is almost never appropriate API design, and separate operations with distinct names usually are a better choice for such cases.
演算 `calculate()^M は,[ `long$T, `DOMString$T, `CalculatableInterface^T ( `~ifc型$ ) ]を受容する引数を 1 個だけとり,引数と同じ型の値を返すとする。 この場合、 `多重定義$された演算を利用して~IDL片を書く方が明瞭になるであろう: ◎ Suppose there is an operation calculate() that accepts a long, DOMString, or CalculatableInterface (an interface type) as its only argument, and returns a value of the same type as its argument. It would be clearer to write the IDL fragment using overloaded operations as
interface A { long calculate(long %input); DOMString calculate(DOMString %input); CalculatableInterface calculate(CalculatableInterface %input); };
`~typedef$を伴う`共用体~型$を利用するよりも: ◎ than using a union type with a typedef as
typedef (long or DOMString or CalculatableInterface) Calculatable; interface A { Calculatable calculate(Calculatable %input); };
これは、 返り値が常に %input と同じ型になる事実を伝達しないので。 ◎ which does not convey the fact that the return value is always of the same type as input.
仕様~化する `calculate()^M が新たな~APIで,互換性の懸念はない場合、 多重定義される演算に対しては,互いに異なる名前を利用することが示唆される — おそらく,次のように: ◎ If the specified calculate() is a new API and does not have any compatibility concerns, it is suggested to use different names for the overloaded operations, perhaps as
interface A { long calculateNumber(long %input); DOMString calculateString(DOMString %input); CalculatableInterface calculateCalculatableInterface(CalculatableInterface %input); };
こうすれば、 ~Web開発者は,明示的かつ一義的な~codeを書けるようになる。 ◎ which allows Web developers to write explicit and unambiguous code.
-
【 他にも、 演算ごとに異なる拡張d属性や特殊~演算を指定する場合も,多重定義する他にないであろう — 例えば: 】
interface A { `NewObject$x X calculate(B %a); X calculate(C %a); };
【 (このように指定される演算は,ほぼないと思われるが、 このような指定-法を総じて禁止している箇所は,この仕様の中には見当たらない。) 】
-
演算の意味論が,引数の型や個数ごとに有意に異なる場合、 `多重定義$が選好される。 ここでも,そのような局面では、 別個な名前を伴わせた別々な演算を作成する方が通例的には良いが、 旧来の~APIには,この~patternに従うものもある。 ◎ When the operation has significantly different semantics for different argument types or lengths, overloading is preferred. Again, in such scenarios, it is usually better to create separate operations with distinct names, but legacy APIs sometimes follow this pattern.
例として, `CSS$T ~ifc 【現在は`~ns$に変更されている】 の `supports()@~CSSCOND#the-css-namespace$M 演算 【!~CSSCOND#dom-css-supports/~CSSCOND#dom-css-supports-conditiontext】 `CSS3-CONDITIONAL$r `CSSOM$r は、 次の~IDL片として定義されている: ◎ As an example, the supports(property, value) and supports(conditionText) operations of the CSS interface are defined as the following IDL fragment [CSS3-CONDITIONAL] [CSSOM].
partial interface CSS { static boolean supports(CSSOMString %property, CSSOMString %value); static boolean supports(CSSOMString %conditionText); };
この~IDL片は、 `随意~引数$を利用して,次のように書き直すこともできる: ◎ Using optional arguments one can rewrite the IDL fragment as follows:
partial interface CSSExcerptOptional { static boolean supports(CSSOMString %propertyOrConditionText, optional CSSOMString %value); };
この~versionの~IDLは、 最初のそれより短くなっているが, 1 個目の引数に全く異なる 2 つの概念が~~併合されている。 `多重定義$しない場合、 演算の`~method手続き$を読むことなく, “ %property / %conditionText は %value と~pairになるのか? ” のような問いに答えるのは、 はるかに困難になる。 そのため、 この~versionは,最初のものより著しく読み取り難くなっている。 ◎ Even though the IDL is shorter in the second version, two distinctively different concepts are conflated in the first argument. Without overloads, the question "is property or conditionText paired with value?" is much more difficult to answer without reading the method steps of the operation. This makes the second version remarkably less readable than the first.
別の考慮点として、 `多重定義$された演算~用の`~method手続き$は,演算ごとに別々な~block内に指定できるので、 仕様を読むときにも書くときにも援助になることが挙げられる — このことは、 `随意~引数$には該当しない。 すなわち,最初の事例に対しては、 仕様~策定者は,演算の`~method手続き$を 次のように書ける: ◎ Another consideration is that the method steps for overloaded operations can be specified in separate blocks, which can aid in both reading and writing specifications. This is not the case for optional arguments. This means that in the first case the specification author can write the method steps of the operations as:
supports(%property, %value)
~method手続きは: ◎ The supports(property, value) method steps are:- …
supports(%conditionText)
~method手続きは: ◎ The supports(conditionText) method steps are:- …
それでも`随意~引数$として %value を利用する場合、 仕様~策定者は,[ 実質的に`多重定義~解決~algo$を再現するような,~~模範的~style ]で~textを書く必要がある。 ◎ Yet using value as an optional argument, the specification author has to use more boilerplate-style text to effectively replicate the overload resolution algorithm.
supports(%propertyOrConditionText, %value)
~method手続きは: ◎ The supports(propertyOrConditionText, value) method steps are:-
~IF[ %value は与えられている ]: ◎ If value is given, then:
- %property ~LET %propertyOrConditionText ◎ Let property be propertyOrConditionText.
- …
-
~ELSE: ◎ Otherwise:
- %conditionText ~LET %propertyOrConditionText ◎ Let conditionText be propertyOrConditionText.
- …
2 つの多重定義が共有する部分が少ししかないなら、 多重定義~解決を~IDLの仕組みに委ねる方が良い。 ◎ If the two overloads have little to no shared parts, it is better to leave overload resolution to the IDL mechanism.
-
演算が 複数の引数をとり,その それぞれが複数の型を受容していて,異なる引数どうしの型が組にされていない場合、 `共用体~型$の他は~~実現できそうにないこともある。 ◎ If the operation accepts multiple types for multiple arguments with no coupling between types of different arguments, union types can sometimes be the only viable solution.
typedef (long long or DOMString or CalculatableInterface) SupportedArgument; interface A { undefined add(SupportedArgument %operand1, SupportedArgument %operand2); };
上の `add()^M 演算を,`多重定義$を利用して指定しようとした場合、 次が要求されることになる: ◎ For the add() operation above, to specify it using overloads would require
interface A { undefined add(long long %operand1, long long %operand2); undefined add(long long %operand1, DOMString %operand2); undefined add(long long %operand1, CalculatableInterface %operand2); undefined add(DOMString %operand1, long long %operand2); undefined add(DOMString %operand1, DOMString %operand2); undefined add(DOMString %operand1, CalculatableInterface %operand2); undefined add(CalculatableInterface %operand1, long long %operand2); undefined add(CalculatableInterface %operand1, DOMString %operand2); undefined add(CalculatableInterface %operand1, CalculatableInterface %operand2); };
対応する注釈文も, 9 回重ねることになる。 ◎ and nine times the corresponding prose!
-
仕様~策定者には、 `missing$C 引数と `undefined^jv 引数とを, ~JS言語束縛において同じ仕方で扱うことが奨励される。 ◎ Specification authors are encouraged to treat missing argument and undefined argument the same way in the JavaScript language binding.
次の~IDL片が与えられたとき: ◎ Given the following IDL fragment:
interface A { undefined foo(); undefined foo(Node? %arg); };
~JS言語束縛を利用する下で, `foo()^M を~callするとき、 引数に[ `undefined^jv / `null^jv ]を渡した場合は, %arg を ~NULL に設定した上で 2 個目の `foo()^M 演算に対応する手続きを走らすことになる。 一方で、 引数を省いた場合は, 1 個目の多重定義に行くことになり、 多くの~API利用者にとって意外な挙動になるであろう。 仕様~策定者には、 代わりに,`随意~引数$を利用することが奨励される — そうすれば、 引数が省かれたときも `undefined^jv のときも, “%arg ~EQ `missing$C” に分類されることになる。 ◎ Using the JavaScript language binding, calling foo(undefined) and foo(null) would both run the steps corresponding to the foo(arg) operation, with arg set to null, while foo() alone would go to the first overload. This can be a surprising behavior for many API users. Instead, specification authors are encouraged to use an optional argument, which would categorize both foo() and foo(undefined) as "arg is missing".
interface A { undefined foo(optional Node? %arg); };
一般に,随意~性は、 多重定義は利用せず, `optional^sym ~keywordを利用して表出するのが最善になる。 ◎ In general, optionality is best expressed using the optional keyword, and not using overloads.
上のどの分類にも収まらない事例で,どの~styleを選ぶかは、 仕様~策定者に委ねられる — ほとんどの場合、 どちらの~styleでも,意図される挙動を簡便に述べるに足るので。 しかしながら、[ `共用体~型$, `随意~引数$ ]の定義と`変換~algo@~WEBIDLjs#js-to-union$の方が,`多重定義$と`多重定義~解決~algo$よりも実装して選り分けるのは単純であり、 通例的に,~JS言語束縛においては より成句的な~APIになる。 したがって,他の考慮点が適用されない限り、 `共用体~型$や`随意~引数$を選ぶ方が既定になる。 ◎ When the case fits none of the categories above, it is up to the specification author to choose the style, since it is most likely that either style would sufficiently and conveniently describe the intended behavior. However, the definition and conversion algorithms of union types and optional arguments are simpler to implement and reason about than those of overloads, and usually result in more idiomatic APIs in the JavaScript language binding. Thus, unless any other considerations apply, union types, optional arguments, or both are the default choice.
仕様~策定者は、 適切かつ簡便であると見出したなら,共用体~型と多重定義を混ぜ合わせてもかまわない。 ◎ Specifications are also free to mix and match union types and overloads, if the author finds it appropriate and convenient.
2.5.9. 可反復~宣言
~ifcは `可反復@ ( `iterable^en )になるように宣言できる。 そのためには、 `~ifc$の本体~内で `可反復~宣言@ (`Iterable$g に合致-) を利用すること。 ◎ An interface can be declared to be iterable by using an iterable declaration (matching Iterable) in the body of the interface.
interface `interface_identifier^i { iterable<`value_type^i>; iterable<`key_type^i, `value_type^i>; };
可反復として宣言された~ifcを実装している~objは、 値の連列を得するために反復できるようになる。 ◎ Objects implementing an interface that is declared to be iterable support being iterated over to obtain a sequence of values.
注記: ~JS言語束縛においては、 可反復な~ifcは,その`~ifc原型~obj$上に[ `entries^jp, `forEach^jp, `keys^jp, `values^jp, `Symbol.iterator$jI ]~propを有することになる。 ◎ Note: In the JavaScript language binding, an interface that is iterable will have entries, forEach, keys, values, and %Symbol.iterator% properties on its interface prototype object.
~parameterに与えられた型の個数が: ◎ ↓
- 1 個ならば,~ifcは `値~反復子@ ( `value iterator^en )を有することになる — それは、 所与の型の値たちを供する。 ◎ If a single type parameter is given, then the interface has a value iterator and provides values of the specified type.\
- 2 個ならば,~ifcは `~pair反復子@ ( `pair iterator^en )を有することになる — それは、[ 所与の ( ~key型, 値~型 ) の値たちが成す`値~pair$ ]たちを供する。 ◎ If two type parameters are given, then the interface has a pair iterator and provides value pairs with the given types.
各 `値~pair@ は、 2 つの`~item$sct ( `~key$vP, `値$vP ) からなる`構造体$である: ◎ A value pair, given a key type and a value type, is a struct with two items:
- `~key@vP は、 ~key型の~IDL値を値にとる,[ `名前$sct ~EQ `key^l ]なる`~item$sctである ◎ an item whose name is "key", which is referred to as the value pair's key, and whose value is an IDL value of the key type;
- `値@vP は、 値~型の~IDL値を値にとる,[ `名前$sct ~EQ `value^l ]なる`~item$sctである ◎ an item whose name is "value", which is referred to as the value pair's value, and whose value is an IDL value of the value type.
`値~反復子$は、 `有index~propを~support$する~ifc上を除き,宣言してはナラナイ。 `値~反復子$の値~型は、 `有index~prop取得子$が返す型と同じでなければナラナイ。 `値~反復子$は、 暗黙的に,当の~objの有index~prop上を反復するように定義される。 ◎ A value iterator must only be declared on an interface that supports indexed properties. 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.
`~pair反復子$は、 `有index~propを~support$する~ifc上に宣言してはナラナイ。 ◎ A pair iterator must not be declared on an interface that supports indexed properties.
`~pair反復子$を伴う`~ifc$は、 付随する注釈文にて,`~ifc$の各~instanceごとに[ `反復される値~pair群@ と称される,`値~pair$の`~list$ ]を定義しなければナラナイ。 ◎ Prose accompanying an interface with a pair iterator must define a list of value pairs for each instance of the interface, which is the list of value pairs to iterate over.
注記: `値~反復子$に対し生成される~JS `forEach^jp ~methodは、 `Array.prototype.forEach^c が行うように,その~callbackを呼出す。 `~pair反復子$用の `forEach^jp ~methodは、 `Map.prototype.forEach^c が行うように,その~callbackを呼出す。 ◎ The JavaScript 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.
現在,`値~反復子$は`有index~propを~support$する~ifcに限り許容されているので、 `forEach^jp ~methodを配列のように利用することもイミを成す。 `値~反復子$は、 次に該当する `forEach^jp ~methodにも必要になり得る ⇒# (a) `有index~propを~support$しない~ifc上のもの/ (b) ~callbackを,代わりに `Set.prototype.forEach^c のように呼出すもの(ここでの~keyは、値と同じ)。 ◎ Since value iterators are currently allowed only on interfaces that support indexed properties, it makes sense to use an Array-like forEach method. There could 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.prototype.forEach (where the key is the same as the value).\
そのような `forEach^jp ~methodを必要とする~APIを再~作成している策定者は、 `Enhancement request for Iterables$fIされたし。 ◎ If you’re creating an API that needs such a forEach method, please file an issue.
注記: `配列~反復子~obj$は,このように働く。 `有index~propを~support$する ~ifcに対しては、[ `entries^jp / `keys^jp / `values^jp / `Symbol.iterator$jI ]から返される反復子~objは,実際の`配列~反復子~obj$である。 ◎ Note: This is how array iterator objects work. For interfaces that support indexed properties, the iterator objects returned by entries, keys, values, and %Symbol.iterator% are actual array iterator objects.
`可反復~宣言$を伴う`~ifc$の`自身も含む継承した~ifc群$を成す どの~ifcにおいても、 次に挙げる名前の[ `属性$/`定数$/`正則~演算$ ]が在ってはナラナイ ⇒# `entries^l, `forEach^l, `keys^l, `values^l ◎ Interfaces with an iterable declaration must not have any attributes, constants, or regular operations named "entries", "forEach", "keys", or "values", or have any inherited interfaces that have attributes, constants, or regular operations with these names.
次の~ifcを考える。 `SessionManager^T は、 文字列 %username を~keyに,一連の `Session^T ~objに~accessできるようにする: ◎ Consider the following interface SessionManager, which allows access to a number of Session objects keyed by username:
[Exposed=Window] interface SessionManager { Session getSessionForUser(DOMString %username); iterable<DOMString, Session>; }; [Exposed=Window] interface Session { readonly attribute DOMString username; /* ... */ };
反復子の挙動は、 次の様に定義することもできる: ◎ The behavior of the iterator could be defined like so:
`反復される値~pair群$を成す各`値~pair$の ( `~key$vP / `値$vP ) ~pairは, ( `username^M / [ `SessionManager^T ~obj上で open している `Session^T ~obj ] ) で与えられ、 ~listは `username^M の昇順で~sortされる。 ◎ The value pairs to iterate over are the list of value pairs with the key being the username and the value being the open Session object on the SessionManager object corresponding to that username, sorted by username.
~JS言語束縛においては、 `SessionManager^T `~ifc$用の`~ifc原型~obj$は,次に挙げる~methodを有することになる: ◎ In the JavaScript language binding, the interface prototype object for the SessionManager interface\
- `values^jp ~method ⇒ [ 次回に反復される値を返す `next^jp ~method ]を有する反復子~objを返す関数 ◎ has a values method that is a function, which, when invoked, returns an iterator object that itself has a next method that returns the next value to be iterated over.\
- `keys^jp ~method ⇒ 一連の `Session^T ~objの `username^M を反復する。 ◎ ↓
- `entries^jp ~method ⇒ 一連の ( `username^M / `Session^T ~obj ) ~pairを反復する。 ◎ It has keys and entries methods that iterate over the usernames of session objects and username/Session object pairs, respectively.\
- `Symbol.iterator$jI ~method ⇒ `entries^jp ~methodと同じ値をとり, `SessionManager^T を `for … of^c ~loopの中でも利用できるようする。 ◎ It also has a %Symbol.iterator% method that allows a SessionManager to be used in a for..of loop that has the same value as the entries method:
/* `SessionManager^T の~instanceを取得する。 2 人の利用者 `anna^l, `brian^l 用の session があるとする: ◎ Get an instance of SessionManager. Assume that it has sessions for two users, "anna" and "brian". */ var %sm = getSessionManager(); typeof SessionManager.prototype.values; /* */ var %it = %sm.values(); /* `values()^c は反復子~objを返す。 ◎ values() returns an iterator object */ String(%it); /* `[object SessionManager Iterator]^l に評価される。 ◎ Evaluates to "[object SessionManager Iterator]" */ typeof %it.next; /* */ /* 次の~loopは、 順に `anna^l, `brian^l を log することになる: ◎ This loop will log "anna" and then "brian". */ for (;;) { let %result = %it.next(); if (%result.done) { break; } let %session = %result.value; console.log(%session.username); } /* 次の~loopも、 順に `anna^l, `brian^l を log することになる: ◎ This loop will also log "anna" and then "brian". */ for (let %username of %sm.keys()) { console.log(%username); } /* 同じことを成遂げる別の仕方: ◎ Yet another way of accomplishing the same. */ for (let [%username, %session] of %sm) { console.log(%username); }
`可反復~宣言$を伴う~ifcの`自身も含む継承した~ifc群$を成す どの~ifcにおいても、 次に挙げるものを宣言してはナラナイ ⇒# 別の`可反復~宣言$, `非同期に可反復な宣言$, `~maplike宣言$, `~setlike宣言$ ◎ An interface must not have more than one iterable declaration. The inherited interfaces of an interface with an iterable declaration must not also have an iterable declaration. An interface with an iterable declaration and its inherited interfaces must not have a maplike declaration, setlike declaration, or asynchronously iterable declaration.
`可反復~宣言$に適用-可能な拡張d属性は ⇒# `CrossOriginIsolated$x, `Exposed$x, `SecureContext$x ◎ The following extended attributes are applicable to iterable declarations: [CrossOriginIsolated], [Exposed], and [SecureContext].
2.5.10. 非同期に可反復な宣言
`~ifc$は、 非同期に可反復( `asynchronously iterable^en )になるように宣言できる。 そのためには、 `~ifc$の本体~内で `非同期に可反復な宣言@ ( `AsyncIterable$g に合致-) を利用する。 ◎ An interface can be declared to be asynchronously iterable by using an asynchronously iterable declaration (matching AsyncIterable) in the body of the interface.
interface `interface_identifier^i { async iterable<`value_type^i>; async iterable<`value_type^i>(/* arguments... */); async iterable<`key_type^i, `value_type^i>; async iterable<`key_type^i, `value_type^i>(/* arguments... */); };
非同期に可反復になるよう宣言された`~ifc$を`実装-$する~objは、 非同期に値の連列を得するように反復できるようになる。 ◎ Objects that implement an interface that is declared to be asynchronously iterable support being iterated over asynchronously to obtain a sequence of values.
~parameterに与えられた型の個数が: ◎ ↓
- 1 個ならば,~ifcは `値を非同期に可反復な宣言@ を有することになる — それは、 指定された型の値たちを非同期に供する。 ◎ If a single type parameter is given, then the interface has a value asynchronously iterable declaration and asynchronously provides values of the specified type.\
- 2 個ならば,~ifcは `~pairを非同期に可反復な宣言@ を有することになる — それは、[ 所与の ( ~key型, 値~型 ) の値たちが成す`値~pair$ ]たちを非同期に供する。 ◎ If two type parameters are given, then the interface has a pair asynchronously iterable declaration and asynchronously provides value pairs with the given types.
`非同期に可反復な宣言$の引数たち ( `ArgumentList$g に合致-) は、 どれも`随意~引数$でなければナラナイ。 ◎ If given, an asynchronously iterable declaration's arguments (matching ArgumentList) must all be optional arguments.
注記: ~JS言語~束縛においては、 非同期に可反復な~ifcは、 `Symbol.asyncIterator$jI を有することに加え, `~ifc原型~obj$上に `values^jp ~propを有することになる。 ~ifcは`~pairを非同期に可反復な宣言$を有する場合、 それは `entries^jp, `keys^jp ~propも追加的に有することになる。 これらの~methodには、 どれも,随意~引数たちが渡され得る — それらは、 `非同期に可反復な宣言$内の引数~listに対応し,存在するならば`非同期~反復子の初期化~手続き$により処理される。 ◎ In the JavaScript language binding, an interface that is asynchronously iterable will have %Symbol.asyncIterator% and values properties on its interface prototype object. If the interface has a pair asynchronously iterable declaration, it will additionally have entries and keys properties. All of these methods can be passed optional arguments, which correspond to the argument list in the asynchronously iterable declaration, and are processed by the asynchronous iterator initialization steps, if any exist.
このことを念頭に,すべての引数は随意とする要件は、 ~JS束縛においては[ `for await … of^c ]が~ifcの~instanceに対し直に働けることを確保する — `for await … of^c は、 引数なしで `Symbol.asyncIterator$jI ~methodを~callするので。 ◎ With this in mind, the requirement that all arguments be optional ensures that, in the JavaScript binding, for-await-of can work directly on instances of the interface, since for-await-of calls the %Symbol.asyncIterator% method with no arguments.
`非同期に可反復な宣言$を伴う`~ifc$ %I は、 付随する注釈文にて: ◎ Prose accompanying an interface with an asynchronously iterable declaration\
-
`次回の反復~結果を取得する@ ~algoを定義しなければナラナイ。 それは、 所与の ⇒# 反復-中にある %I の~instance, 非同期c反復子~自身(状態を格納するとき有用になる) ◎ must define a get the next iteration result algorithm. This algorithm receives the instance of the interface that is being iterated, as well as the async iterator itself (which can be useful for storing state).\
に対し, `Promise$T を返さなければナラナイ — この`~promiseを解決する$ときの充足~値は、 次の いずれかでなければナラナイ: ◎ It must return a Promise that either rejects,\
- 反復の終了を通達する特別な値 `反復~終了@C ◎ resolves with a special end of iteration value to signal the end of the iteration, or\
-
次のいずれか: ◎ resolves with one of the following:
- `値を非同期に可反復な宣言$用には ⇒ 当の宣言~内に与えられた型の値 ◎ for value asynchronously iterable declarations: • a value of the type given in the declaration;
- `~pairを非同期に可反復な宣言$用には ⇒ 当の宣言に与えられた ( 1 個目の型の値, 2 個目の型の値 ) からなる`~tuple$ ◎ for pair asynchronously iterable declarations: • a tuple containing a value of the first type given in the declaration, and a value of the second type given in the declaration.
-
`非同期~反復子の~return@ ~algoを定義してもヨイ。 それは、 非同期c反復子が尚早に終了される事例において呼出され,所与の ⇒# 反復-中にある %I の~instance, 非同期c反復子~自身, `any$T 型の値をとる 1 個の引数 ◎ The prose may also define an asynchronous iterator return algorithm. This algorithm receives the instance of the interface that is being iterated, the async iterator itself, and a single argument value of type any. This algorithm is invoked in the case of premature termination of the async iterator.\
に対し, `Promise$T を返さなければナラナイ — この~promiseは、 充足された場合,その充足~値は無視されるが、 却下された場合,その失敗は非同期c反復子~APIの利用元へ渡されることになる。 ◎ It must return a Promise; if that promise fulfills, its fulfillment value will be ignored, but if it rejects, that failure will be passed on to users of the async iterator API.
注記: この~algoは、 ~JS言語束縛においては[ 非同期c反復子の `return()^M ~methodが呼出されるときの挙動 ]を~custom化することを許容する。 これが最も共通的に生じるのは、 `break^c や `return^c 文により[ `for await … of^c ]~loopから抜出たときである。 ◎ In the JavaScript binding, this algorithm allows customizing the behavior when the async iterator’s return() method is invoked. This most commonly occurs when a break or return statement causes an exit from a for-await-of loop.
注記: 類似な~hookを `throw()^M 用に追加することもできたが、 今の所,その必要性はない。 そのような能力が必要になる~APIを作成しているなら,`Enhancement request for Async Iterables$fIされたし。 ◎ We could add a similar hook for throw(). So far there has been no need, but if you are creating an API that needs such capabilities, please file an issue.
- `非同期~反復子の初期化~手続き@ を定義してもヨイ。 それは、 次を受取ることになる ⇒# 反復-中にある %I の~instance, 新たに作成された反復子~obj, 渡された引数たちを表現する~IDL値たちが成す`~list$ ◎ The prose may also define asynchronous iterator initialization steps. These receive the instance of the interface being iterated, the newly-created iterator object, and a list of IDL values representing the arguments passed, if any.
`非同期に可反復な宣言$を伴う`~ifc$の`自身も含む継承した~ifc群$を成す どの~ifcにおいても、 次に挙げる名前の[ `属性$/`定数$/`正則~演算$ ]が在ってはナラナイ ⇒# `entries^l, `keys^l, `values^l ◎ Interfaces with an asynchronously iterable declaration must not have any attributes, constants, or regular operations named "entries", "keys", or "values", or have any inherited interfaces that have attributes, constants, or regular operations with these names.
次の~ifcを考える。 `SessionManager^T は、 文字列 %username を~keyに,一連の `Session^T ~objに~accessできるようにする: ◎ Consider the following interface SessionManager, which allows access to a number of Session objects keyed by username:
[Exposed=Window] interface SessionManager { Session getSessionForUser(DOMString %username); async iterable<DOMString, Session>; }; [Exposed=Window] interface Session { readonly attribute DOMString username; // ... };
反復子の挙動は、 次の様に定義することもできる: ◎ The behavior of the iterator could be defined like so:
`SessionManager^T の非同期c反復子 %反復子 用の`非同期~反復子の初期化~手続き$は: ◎ The asynchronous iterator initialization steps for a SessionManager async iterator iterator are:
- %反復子 の `現在の状態@sM ~SET `まだ開始されてない^C ◎ Set iterator’s current state to "not yet started".
`次回の反復~結果を取得する$ときは、 所与の ( `SessionManager^T %manager, その非同期c反復子 %反復子 ) に対し: ◎ To get the next iteration result for a SessionManager manager and its async iterator iterator:
- %~promise ~LET 新たな~promise ◎ Let promise be a new promise.
- %状態 ~LET %反復子 の`現在の状態$sM ◎ ↓
%~key ~LET [ 次に該当するものが存在するならば それ / ~ELSE_ ~NULL ] ⇒ %manager 内の各[ ~open中の~sessionの `username^M ]のうち,辞書式~順序で ⇒# %状態 ~EQ `まだ開始されてない^C ならば最初のもの/ ~ELSE_ %状態 より後, かつ最初のもの ◎ Let key be the following value, if it exists, or null otherwise: • If iterator’s current state is "not yet started" •• the smallest username in manager’s open sessions, in lexicographical order • Otherwise •• the smallest username in manager’s open sessions that is greater than iterator’s current state, in lexicographical order
注記: %状態 に対応する~sessionは、 もはや~open中でないこともある。 ◎ Note: iterator’s current state might no longer be present in the open sessions.
- ~IF[ %~key ~EQ ~NULL ] ⇒ `~promiseを解決する$( %~promise, `反復~終了$C ) ◎ If key is null, then: • Resolve promise with end of iteration.
~ELSE: ◎ Otherwise:
- %session ~LET %~key に対応する `Session^T ~obj ◎ Let session be the Session object corresponding to key.
- `~promiseを解決する$( %~promise, ( %username, %session ) ) ◎ Resolve promise with (username, session).
- %反復子 の`現在の状態$sM ~SET %username ◎ Set iterator’s current state to username.
- ~RET %~promise ◎ Return promise.
~JS言語束縛においては、 `SessionManager^T `~ifc$用の`~ifc原型~obj$は,次に挙げる~methodを有することになる: ◎ In the JavaScript language binding, the interface prototype object for the SessionManager interface has\
- `values^jp ~method ⇒ [ 次回に反復される値を返す `next^jp ~method ]を有する非同期~反復子~objを返す関数 ◎ a values method that is a function, which, when invoked, returns an asynchronous iterator object that itself has a next method that returns the next value to be iterated over.\
- `keys^jp ~method ⇒ 一連の `Session^T ~objの `username^M を反復する。 ◎ ↓
- `entries^jp ~method ⇒ 一連の ( `username^M / `Session^T ~obj ) ~pairを反復する。 ◎ It has keys and entries methods that iterate over the usernames of session objects and (username, Session) object pairs, respectively.\
- `Symbol.asyncIterator$jI ~method ⇒ `entries^jp ~methodと同じ値をとり, `SessionManager^T を `for await … of^c ~loopの中でも利用できるようする。 ◎ It also has a %Symbol.asyncIterator% method that allows a SessionManager to be used in a for await..of loop that has the same value as the entries method:
/* `SessionManager^T の~instanceを取得する。 2 人の利用者 `anna^l, `brian^l 用の session があるとする: ◎ Get an instance of SessionManager. Assume that it has sessions for two users, "anna" and "brian". */ var %sm = getSessionManager(); typeof SessionManager.prototype.values; /* */ var %it = %sm.values(); /* `values()^c は反復子~objを返す。 ◎ values() returns an iterator object */ typeof %it.next; /* */ /* 次の~loopは、 順に `anna^l, `brian^l を log することになる: ◎ This loop will log "anna" and then "brian". */ for await (let %username of %sm.keys()) { console.log(%username); } /* 同じことを成遂げる別の仕方: ◎ Yet another way of accomplishing the same. */ for await (let [%username, %session] of %sm) { console.log(%username); }
`非同期に可反復な宣言$を伴う~ifcの`自身も含む継承した~ifc群$を成す どの~ifcにおいても、 次に挙げるものを宣言してはナラナイ ⇒# `可反復~宣言$, 別の`非同期に可反復な宣言$, `~maplike宣言$, `~setlike宣言$ ◎ An interface must not have more than one asynchronously iterable declaration. The inherited interfaces of an interface with an asynchronously iterable declaration must not also have an asynchronously iterable declaration. An interface with an asynchronously iterable declaration and its inherited interfaces must not have a maplike declaration, setlike declaration, or iterable declaration.
`非同期に可反復な宣言$に適用-可能な拡張d属性は ⇒# `CrossOriginIsolated$x, `Exposed$x, `SecureContext$x ◎ The following extended attributes are applicable to asynchronously iterable declarations: [CrossOriginIsolated], [Exposed], and [SecureContext].
これらの`拡張d属性$は、 現時点では まだ【他の仕様に】織り込まれていない。 織り込まれたときには、 その効果は,期待されるものになることになる。 ◎ these extended attributes are not currently taken into account. When they are, the effect will be as you would expect.
2.5.11. ~maplike宣言
~ifcは `~maplike@ ( `maplike^en / “~mapの様なもの” )になるように宣言できる。 そのためには、 `~ifc$の本体~内で `~maplike宣言@ ( `ReadWriteMaplike$g, `readonly^sym `MaplikeRest$g いずれかに合致-) を利用する。 ◎ An interface can be declared to be maplike by using a maplike declaration (matching ReadWriteMaplike or readonly MaplikeRest) in the body of the interface.
interface `interface_identifier^i { readonly maplike<`key_type^i, `value_type^i>; maplike<`key_type^i, `value_type^i>; };
`~maplike$になるように宣言された~ifcを実装する~objは、[ `~map~entry群@ と称される,初期~時は空な`有順序~map$ ]を表現する。 この~mapを成す各`~entry$mapの[ ~key, 値 ]に利用される型は,~maplike宣言の山括弧の中で順に与えられる。 各~keyは,~map内で一意になることが要求される。 ◎ Objects implementing an interface that is declared to be maplike represent an ordered map of key–value pairs, initially empty, known as that object’s 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.
仕様~策定者は、 `~map~entry群$の内容を改変できる — それは、 ~JS~codeにより観測されるに伴い, 当の~objの内容~内に自動的に反映されることになる。 ◎ Specification authors can modify the contents of the map entries, which will automatically be reflected in the contents of the object as observed by JavaScript code.
~maplike~ifcは、 `~map~entry群$を~queryするための,言語束縛に適切な~APIを~supportする。 非読専な~maplike — `readonly^sym ~keywordを伴わずに宣言されたそれ — は、 `~map~entry群$を改変するための~APIも~supportする。 ◎ 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.
注記: ~JS言語束縛においては、 `~map~entry群$とヤリトリするための~APIは, ~JSにて可用な `Map$jt ~objに類似する。 `readonly^sym ~keywordが利用された場合、 それは[ `entries^jp, `forEach^jp, `get^jp, `has^jp, `keys^jp, `values^jp, `Symbol.iterator$jI ]~method, および `size^jp 取得子を含む。 非読専な~maplikeに対しては、 更に[ `clear^jp, `delete^jp, `set^jp ]~methodも含む。 ◎ Note: In the JavaScript language binding, the API for interacting with the map entries is similar to that available on JavaScript Map objects. If the readonly keyword is used, this includes entries, forEach, get, has, keys, values, %Symbol.iterator% methods, and a size getter. For read–write maplikes, it also includes clear, delete, and set methods.
~maplike~ifcの`自身も含む継承した~ifc群$を成す どの~ifcにおいても、 次に挙げる名前の[ `属性$/`定数$/`正則~演算$ ]が在ってはナラナイ ⇒# `entries^l, `forEach^l, `get^l, `has^l, `keys^l, `size^l, `values^l ◎ Maplike interfaces must not have any attributes, constants, or regular operations named "entries", "forEach", "get", "has", "keys", "size", or "values", or have any inherited interfaces that have attributes, constants, or regular operations with these names.
非読専な~maplike~ifcの`自身も含む継承した~ifc群$を成す どの~ifcにおいても、 次に挙げる名前の[ `属性$/`定数$ ]が在ってはナラナイ ⇒# `clear^l, `delete^l, `set^l ◎ Read–write maplike interfaces must not have any attributes or constants named "clear", "delete", or "set", or have any inherited interfaces that have attributes or constants with these names.
注記: 非読専な~maplike~ifcは、[ `clear^l / `delete^l / `set^l ]と命名される`正則~演算$を`伴い得る^em — それぞれは、 その~methodの既定の実装 ( `~maplike宣言@~WEBIDLjs#js-maplike§にて定義される) を上書きすることになる。 そのような正則~演算を定義する場合、 それは,[ 各自の~methodの既定の実装~節に定義される,入力と出力に対する期待 ]に合致しなければならない。 ◎ Note: Read-write maplike interfaces can have regular operations named "clear", "delete", or "set", which will override the default implementation of those methods (defined in § 3.7.11 Maplike declarations). If such regular operations are defined, they must match the input and output expectations of each method, defined in their default implementation sections.
~maplike~ifcの`自身も含む継承した~ifc群$を成す どの~ifcにおいても、 次に挙げるものを宣言してはナラナイ ⇒# `可反復~宣言$, `非同期に可反復な宣言$, 別の`~maplike宣言$, `~setlike宣言$, `有index~prop取得子$ ◎ An interface must not have more than one maplike declaration. The inherited interfaces of a maplike interface must not also have a maplike declaration. A maplike interface and its inherited interfaces must not have an iterable declaration, an asynchronously iterable declaration, a setlike declaration, or an indexed property getter.
`~maplike宣言$に適用-可能な`拡張d属性$は、 この仕様では定義されない。 ◎ No extended attributes defined in this specification are applicable to maplike declarations.
例を追加する。 ◎ Add example.
2.5.12. ~setlike宣言
~ifcは `~setlike@ ( `setlike^en / “集合の様なもの” )になるように宣言できる。 そのためには、 `~ifc$の本体~内で `~setlike宣言@ ( `ReadWriteSetlike$g, `readonly^sym `SetlikeRest$g いずれかに合致-) を利用する。 ◎ An interface can be declared to be setlike by using a setlike declaration (matching ReadWriteSetlike or readonly SetlikeRest) in the body of the interface.
interface `interface_identifier^i { readonly setlike<`type^i>; setlike<`type^i>; };
~setlikeになるように宣言された~ifcを実装する~objは、[ `~set~entry群@ と称される,初期~時は空な`有順序~集合$ ]を表現する。 この集合を成す各~値に利用される型は、 ~setlike宣言の山括弧の中で与えられる。 それらの値は一意になることが要求される。 ◎ Objects implementing an interface that is declared to be setlike represent an ordered set of values, initially empty, known as that object’s set entries. The type of the values is given in the angle brackets of the setlike declaration. Values are required to be unique.
仕様~策定者は、 `~set~entry群$の内容を改変できる — それは、 ~JS~codeにより観測されるに伴い, 当の~objの内容~内に自動的に反映されることになる。 ◎ Specification authors can modify the contents of the set entries, which will automatically be reflected in the contents of the object as observed by JavaScript code.
~setlike~ifcは、 `~set~entry群$を~queryするための,言語束縛に適切な~APIを~supportする。 非読専な~setlike — `readonly^sym ~keywordを伴わずに宣言されたそれ — は、 `~set~entry群$を改変するための API も~supportする。 ◎ 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.
注記: ~JS言語束縛においては、 `~set~entry群$とヤリトリするための~APIは, ~JSにて可用な `Set$jt ~objに類似する。 `readonly^sym ~keywordが利用された場合、 それは[ `entries^jp, `forEach^jp, `has^jp, `keys^jp, `values^jp, `Symbol.iterator$jI ]~method, および `size^jp 取得子を含む。 非読専な~setlikeに対しては、 更に[ `add^jp, `clear^jp, `delete^jp ]~methodも含む。 ◎ Note: In the JavaScript language binding, the API for interacting with the set entries is similar to that available on JavaScript Set objects. If the readonly keyword is used, this includes entries, forEach, has, keys, values, %Symbol.iterator% methods, and a size getter. For read–write setlikes, it also includes add, clear, and delete methods.
~setlike~ifcの`自身も含む継承した~ifc群$を成す どの~ifcにおいても、 次に挙げる名前の[ `属性$/`定数$/`正則~演算$ ]が在ってはナラナイ ⇒# `entries^l, `forEach^l, `has^l, `keys^l, `size^l, `values^l ◎ Setlike interfaces must not have any attributes, constants, or regular operations named "entries", "forEach", "has", "keys", "size", or "values", or have any inherited interfaces that have attributes, constants, or regular operations with these names.
非読専な~setlike~ifcの`自身も含む継承した~ifc群$を成す どの~ifcにおいても、 次に挙げる名前の[ `属性$/`定数$ ]が在ってはナラナイ ⇒# `add^l, `clear^l, `delete^l ◎ Read–write setlike interfaces must not have any attributes or constants named "add", "clear", or "delete", or have any inherited interfaces that have attributes or constants with these names.
注記: 非読専な~setlike~ifcは、[ `add^l / `clear^l / `delete^l ]と命名される`正則~演算$を`伴い得る^em — それぞれは、 その~methodの既定の実装 ( `~setlike宣言@~WEBIDLjs#js-setlike§にて定義される) を上書きすることになる。 そのような正則~演算を定義する場合、 それは,[ 各自の~methodの既定の実装~節に定義される,入力と出力に対する期待 ]に合致しなければならない。 ◎ Note: Read-write setlike interfaces can have regular operations named "add", "clear", or "delete", which will override the default implementation of those methods (defined in § 3.7.12 Setlike declarations). If such regular operations are defined, they must match the input and output expectations of each method, defined in their default implementation sections.
~setlike~ifcの`自身も含む継承した~ifc群$を成す どの~ifcにおいても、 次に挙げるものを宣言してはナラナイ ⇒# `可反復~宣言$, `非同期に可反復な宣言$, `~maplike宣言$, 別の`~setlike宣言$, `有index~prop取得子$ ◎ An interface must not have more than one setlike declaration. The inherited interfaces of a setlike interface must not also have a setlike declaration. A setlike interface and its inherited interfaces must not have an iterable declaration, an asynchronously iterable declaration, a maplike declaration, or an indexed property getter.
`~setlike宣言$に適用-可能な`拡張d属性$は、 この仕様では定義されない。 ◎ No extended attributes defined in this specification are applicable to setlike declarations.
例を追加する。 ◎ Add example.
2.6. ~ns
`~ns@ ( `namespace^en )は、 いくつかの挙動が結付けられた 大域~singletonを宣言する,`定義$ ( `Namespace$g に合致-) である。 ◎ A namespace is a definition (matching Namespace) that declares a global singleton with associated behaviors.
【 すなわち、 ~instanceは 1 個しか存在し得ない(かつ,その 1 個は常に存在する)ような~ifcのようなものと捉えればよいであろう。 】
namespace `identifier^i { /* namespace_members... */ };
`~ns$は、 その宣言を成す波括弧の合間に現れる[ `正則~演算$, `読専$な`正則~属性$, `定数$ ]が成す集合 ( `NamespaceMembers$g に合致-) の指定である — これらの[ 演算/属性【/定数?】 ]~mbは、 `~ns~mb@ と称され,~nsの中に梱包された挙動を述べる。 ◎ A namespace is a specification of a set of namespace members (matching NamespaceMembers), which are the regular operations, read only regular attributes, and constants that appear between the braces in the namespace declaration. These operations and attributes describe the behaviors packaged into the namespace.
~ifcのときと同じく,~ns用の~IDLは、 `部分的な~ns定義@ ( `partial^sym `Namespace$g に合致-) を利用して,複数の部分に分割できる。 部分的な~ns定義の`識別子$は、 その~ns定義の識別子と同じでなければナラナイ。 各 部分的な~nsに現れる,すべての~mbは、 その~ns自身を成す~mbと見なされる。 ◎ 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^mk { /* namespace_members... */ }; partial namespace `SomeNamespace^mk { /* namespace_members... */ };
注記: 部分的な~ifc定義のときと同じく,部分的な~ns定義に意図される用途は、 ~nsの定義を文書の複数の節, ときには複数の文書に分離できるようにして, 仕様の編集を補佐することである。 ◎ 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.
~mbたちが現れる順序は、 `~JS言語束縛@~WEBIDLjs#js-namespaces$における~prop列挙に,有意になる。 ◎ The order that members appear in has significance for property enumeration in the JavaScript binding.
~ifcや辞書と違って、 ~nsは型を作成しないことに注意。 ◎ Note that unlike interfaces or dictionaries, namespaces do not create types.
この仕様に定義される拡張d属性のうち,~nsに適用-可能なのは、 次に限られる ⇒# `CrossOriginIsolated$x, `Exposed$x, `SecureContext$x ◎ Of the extended attributes defined in this specification, only the [CrossOriginIsolated], [Exposed], and [SecureContext] extended attributes are applicable to namespaces.
`~ns$は、 `Exposed$x `拡張d属性$で注釈されなければナラナイ。 ◎ Namespaces must be annotated with the [Exposed] extended attribute.
次の`~IDL片$は、 `~ns$を定義する: ◎ The following IDL fragment defines a namespace.
[Exposed=Window]【!*原文抜け】 namespace VectorUtils { readonly attribute Vector unit; double dotProduct(Vector %x, Vector %y); Vector crossProduct(Vector %x, Vector %y); };
~JS実装は、 (原型 `Object.prototype$jI を伴う)単純~objであった `VectorUtils^jp ~data~propを, 宣言された各[ 演算~用の列挙-可能な~data~prop / 属性~用の列挙-可能な取得-のみの~accessor ]たちで公開することになる: ◎ A JavaScript implementation would then expose a global VectorUtils data property which was a simple object (with prototype %Object.prototype%) with enumerable data properties for each declared operation, and enumerable get-only accessors for each declared attribute:
Object.getPrototypeOf(VectorUtils); /* `Object.prototype^c に評価される。 ◎ Evaluates to Object.prototype. */ Object.keys(VectorUtils); /* [`dotProduct^l, `crossProduct^l] に評価される。 ◎ Evaluates to ["dotProduct", "crossProduct"]. */ Object.getOwnPropertyDescriptor(VectorUtils, "dotProduct"); /* { value: <ある関数>, enumerable: true, configurable: true, writable: true } に評価される。 ◎ Evaluates to { value: <a function>, enumerable: true, configurable: true, writable: true }. */ Object.getOwnPropertyDescriptor(VectorUtils, "unit"); /* { get: <ある関数>, enumerable: true, configurable: true } に評価される。 ◎ Evaluates to { get: <a function>, enumerable: true, configurable: true }. */
2.7. 辞書
`辞書@ ( `dictionary^en )は、 ~AND↓ を満たす~data型を定義するために利用される`定義$ ( `Dictionary$g に合致-) である:
- `有順序~map$である
- その`~key群$mapは固定的である
- それ成す各`~entry$mapは、 `辞書~mb@ と称され,次を満たす ⇒ [ その`~key$mapは文字列である ]~AND[ その`値$mapは当の定義において指定された型の値である ]
dictionary `identifier^i { /* dictionary_members... */ };
辞書~instanceは、 言語~特有な その表現(例:対応する~JS~obj)への参照は維持しない。 例えば,`演算$から返される辞書は、[ 当の辞書を成す現在の値たちから作成される,新たな~JS~obj ]になる。 引数として辞書を受容する演算は、 所与の~JS値から辞書への変換を — 各回ごとに,~JS~objを成す現在の~propに基づいて — 遂行することになる。 辞書に対する改変は、 対応する~JS~objには反映されず,その逆も同様になる。 ◎ Dictionary instances do not retain a reference to their language-specific representations (e.g., the corresponding JavaScript object). So for example, returning a dictionary from an operation will result in a new JavaScript object being created from the current values of the dictionary. And, an operation that accepts a dictionary as an argument will perform a one-time conversion from the given JavaScript value into the dictionary, based on the current properties of the JavaScript object. Modifications to the dictionary will not be reflected in the corresponding JavaScript object, and vice-versa.
辞書は、[ `属性$/`定数$ ]の型として利用してはナラナイ。 ◎ Dictionaries must not be used as the type of an attribute or constant.
`辞書$は 別の`辞書$を `継承-@diC するように定義できる。 辞書の識別子に[ ~colon, `識別子$ ]が後続する場合、 後者の識別子が,継承される辞書を識別する。 この識別子は、 ある`辞書$を識別するものでなければナラナイ。 ◎ 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.
`辞書$は、 その継承~階層が循環するように宣言してはナラナイ。 すなわち,辞書 %D は、 %D を継承することも, %D を継承する別の辞書を継承することもできない,等々。 ◎ 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^mk { /* dictionary_members... */ }; dictionary `Derived^i : `Base^mk { /* dictionary_members... */ };
所与の辞書~型 %D が `継承した辞書~群@ とは、 %D が直接間接に継承した すべての辞書が成す集合である。 この集合は、 %D が他の辞書を`継承-$diCしない場合は空になり, 他の場合は[ %D が`継承-$diCした辞書 %E, %E が`継承した辞書~群$を成すすべての辞書 ]からなる。 ◎ 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.
`辞書~mb$は、 `要求され@diC るものと指定できる — すなわち,言語~特有な値から辞書へ変換するときは、 その~mb用の値を供することが要求される。 `要求され$diCない辞書~mbは、 `随意@diC になる。 ◎ Dictionary members can be specified as required, meaning that converting a language-specific value to a dictionary requires providing a value for that member. Any dictionary member that is not required is optional.
`辞書~mb$を`要求され$diCるものと指定することによる観測-可能な効果は、 当の辞書を成す他の表現(`演算$への引数として給された~JS値など)を~IDL辞書へ変換するときに限られることに注意。 仕様~策定者は、 他のすべての事例においては — 当の辞書~型が,もっぱら`演算$の`返り値~型$として利用されるときも含め — ~mbを`随意$diCのままにするベキである。 ◎ Note that specifying dictionary members as required only has an observable effect when converting other representations of dictionaries (like a JavaScript value supplied as an argument to an operation) to an IDL dictionary. Specification authors should leave the members optional in all other cases, including when a dictionary type is used solely as the return type of operations.
所与の型 %D の辞書~値 %V は、[ %D, および %D が`継承した辞書~群$を成す各~辞書 ]上に定義された各~辞書~mb用に`~entry$mapを有し得る — それら辞書~mbのうち: ◎ A given dictionary value of type D can have entries for each of the dictionary members defined on D and on any of D’s inherited dictionaries.\
- [ `要求され$diCる/`既定~値$diCを有する ]ものと指定されたものには、 常に,対応する`~entry$mapが %V 内に`存在-$することになる。 ◎ Dictionary members that are specified as required, or that are specified as having a default value, will always have such corresponding entries.\
- 他の~mb用の`~entry$mapは、 %V 内に`存在-$しないこともある。 ◎ Other members' entries might or might not exist in the dictionary value.
注記: ~JS束縛においては、 `辞書~mb$に対応する【すなわち,同じ名前の】~prop用の値 `undefined^jv は、 その~propを省略したのと同じに扱われる。 したがって,当の~mbが ⇒# `要求され$diCているならば ~errorを生じさせる/ `既定~値$diCが指定されたならば それがあてがわれる/ 他の場合は %V 内には対応する`~entry$mapは存在しない結果になる ◎ In the JavaScript binding, a value of undefined for the property corresponding to a dictionary member is treated the same as omitting that property. Thus, it will cause an error if the member is required, or will trigger the default value if one is present, or will result in no entry existing in the dictionary value otherwise.
演算~引数の`既定~値$のときと同じく, `boolean$T 型の`辞書~mb$用には、 `既定~値$diCとして `true^V を利用しないことが強く奨励される。 さもなければ、 `undefined^jv に既定の変換(すなわち, `false^V )が利用されると期待する作者たちを惑わすことになるので。 `API-DESIGN-PRINCIPLES$r ◎ As with operation argument default values, it is strongly encouraged not to use 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). [API-DESIGN-PRINCIPLES]
`有順序~map$ %M は、 ~AND↓ を満たすならば,暗黙的に特定の辞書~型 %D の値として扱える:
- %M を成す どの`~entry$mapも,その`~key$mapは文字列である
-
%M を成す どの`~entry$map %~entry に対しても, %D を成す`辞書~mb$ %~mb が在って ~AND↓ が満たされる
- %~entry の`~key$map ~EQ %~mb の`識別子$
- %~entry の`値$mapは %~mb に宣言された型の値である
- %D を成す`辞書~mb$のうち[ `要求され$diCるもの/ `既定~値$diCが指定されたもの ]に対しては, %M を成す`~entry$mapとして 前項のように対応するものが在る
dictionary Descriptor { DOMString name; sequence<unsigned long> serviceIdentifiers; };
`Descriptor^T 辞書は、 次のような手続きで作成することもできる: ◎ A Descriptor dictionary could be created as in the following steps:
- %識別子~群 ~LET « 1, 3, 7 » ◎ Let identifiers be « 1, 3, 7 ».
- ~RET «[ `name^l → `test^l, `serviceIdentifiers^l → %識別子~群 ]» ◎ Return «[ "name" → "test", "serviceIdentifiers" → identifiers ]».
各`辞書~mb$ ( `DictionaryMember$g に合致-) は、 型( `Type$g に合致-) %型, それに後続する`識別子$( `identifier$g ~tokenにより与えられる) %識別子 により指定される: ◎ Each dictionary member (matching DictionaryMember) is specified as a type (matching Type) followed by an identifier (given by an identifier token following the type).\
- %識別子 が当の~mbの`~key$map【!key name of the key–value pair】になる。 ◎ The identifier is the key name of the key–value pair.\
- %型 は[ `?^sym が後続する`識別子$ ]である場合、 その識別子は,次に挙げるいずれかを識別しなければナラナイ ⇒# `~ifc$, `列挙$, `~callback関数$, `~callback~ifc$, `~typedef$ ◎ If the Type is an identifier followed by ?, then the identifier must identify an interface, enumeration, callback function, callback interface or typedef.\
- %型 は[ `?^sym が後続しない`識別子$ ]である場合、 その識別子は[ `辞書$/前項に挙げたいずれかの定義 ]を識別しなければナラナイ。 ◎ If the dictionary member type is an identifier not followed by ?, then the identifier must identify any one of those definitions or a dictionary.
`辞書~mb$の型が`~typedef$の解決-後に`~nullable型$になる場合、 その`内縁~型$は,`辞書~型$になってはナラナイ。 ◎ If the type of the dictionary member, after resolving typedefs, is a nullable type, its inner type must not be a dictionary type.
dictionary `identifier^i { `type^i `identifier^i; };
`随意$diCな`辞書~mb$用の識別子に[ `003D^U1, 値 ( `DefaultValue$g に合致-) ]が順に後続している場合、 それが当の辞書~mbの `既定~値@diC を与える。 それは、[ 作者~code/仕様~text ]が当の~mb用に値を供さなかったとき,既定で利用される値になる。 ◎ If the identifier for an optional dictionary member is followed by a U+003D (=) and a value (matching DefaultValue), then that gives the dictionary member its default value, which is the value used by default when author code or specification text does not provide a value for that member.
dictionary `identifier^i { `type^i `identifier^i = "value"; };
`既定~値$diCに[ `ConstValue$g / `null^sym / `string$g ~token / 2 個の~tokenが成す連列 `[]^sym / 2 個の~tokenが成す連列 `{}^sym ]が利用された場合、 `演算$の引数の`既定~値$のときと同じ仕方で解釈される。 ◎ When a boolean literal token (true or false), the null token, an integer token, a decimal token, one of the three special floating point literal values (Infinity, -Infinity or NaN), a string token, the two token sequence [], or the two token sequence {} is used as the default value, it is interpreted in the same way as for an operation's optional argument default value.
`辞書~mb$の型が`列挙$である場合、 その`既定~値$diCに指定される値は,その`列挙~値$のいずれかでなければナラナイ。 ◎ If the type of the dictionary member is an enumeration, then its default value if specified must be one of the enumeration’s values.
辞書~mbの型の前に `required^sym ~keywordが置かれた場合、 その~mbは,`要求され$diCる辞書~mbと見なされる。 ◎ If the type of the dictionary member is preceded by the required keyword, the member is considered a required dictionary member.
dictionary `identifier^i { required `type^i `identifier^i; };
辞書を成すどの~mbも、 その型は,当の`辞書~型$を`内包して^iはナラナイ — 型 %T が辞書~型 %D を`内包して^iいるとは、 ~OR↓ を満たすことをいう: ◎ 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:
- %T ~EQ %D ◎ the type is D
- [ %T は辞書である ]~AND[ %T は %D を`継承-$diCしている ] ◎ the type is a dictionary that inherits from D
- [ %T は`~nullable型$である ]~AND[ %T の`内縁~型$は %D を`内包して^iいる ] ◎ the type is a nullable type whose inner type includes D
- [ %T は[ `連列~型$/`凍結d配列~型$ ]である ]~AND[ %T の要素~型は %D を`内包して^iいる ] ◎ the type is a sequence type or frozen array whose element type includes D
- [ %T は`共用体~型$である ]~AND[ %T を成す いずれかの`~mb型$は %D を`内包して^iいる ] ◎ the type is a union type, one of whose member types includes D
- [ %T は辞書である ]~AND[ %T を成す~mb — %T が`継承した辞書~群$を成す各~辞書の~mbも含む — として %D を`内包して^iいるものがある ] ◎ the type is a dictionary, one of whose members or inherited members has a type that includes D
- [ %T は `~record_KV$ である ]~AND[ %V は %D を`内包して^iいる ] ◎ the type is record<K, V> where V includes D
~ifcのときと同じく、 辞書~用の~IDLは `部分的な辞書~定義@ ( `partial^sym `Dictionary$g に合致-) を利用して複数の部分に分割できる。 部分的な辞書~定義の`識別子$は、 当の辞書~定義の識別子と同じでなければナラナイ。 各 部分的な辞書~定義に現れるすべての~mbは、 辞書~自身を成す~mbと見なされる。 ◎ 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^mk { /* dictionary_members... */ }; partial dictionary `SomeDictionary^mk { /* dictionary_members... */ };
注記: `部分的な~ifc定義$のときと同じく,`部分的な辞書~定義$に意図される用途は、 辞書の定義を文書の複数の節, ときには複数の文書に分離できるようにして, 仕様の編集を補佐することである。 ◎ 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.
所与の辞書の`辞書~mb$は、 継承された辞書~mbが継承してない~mbより前に位置するように順序付けられる。 同じ辞書~定義の(`部分的な辞書~定義$もすべて含めた)すべての辞書~mbは、 それらの識別子を構成する~Unicode符号位置により,辞書式に順序付けられる。 ◎ 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; };
型 `C^T の辞書~値を成す`辞書~mb$の順序は[ `c^M, `d^M, `g^M, `h^M, `a^M, `b^M, `e^M, `f^M ]になる。 ◎ the order of the dictionary members of a dictionary value of type C is c, d, g, h, a, b, e, f.
辞書の~mbは順序付けられる必要がある。 一部の言語束縛においては、 ~platform~objに辞書~値を渡した際に観測される挙動が,辞書~mbを取りに行く順序に依存するので。 例えば,次の追加的な~ifc: ◎ Dictionaries need 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:
[Exposed=Window] interface Something { undefined f(A %a); };
および,次の~JS~codeを考えるとき: ◎ and this JavaScript code:
var %something = getSomething(); /*
`Something^T の~instanceを取得する。
◎
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);
辞書~mbを取りに行く順序が、 それらがとることになる値を決定する。 `A^T における順序は, `c^M の次が `d^M と定義されるので、 `c^M 用の値は 1 に, `d^M 用の値は 2 になる。 ◎ 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.
辞書~mbの識別子は、[ 当の辞書, または それが`継承した辞書~群$を成すいずれかの辞書 ]上で定義される,別の辞書~mbの識別子と同じになってはナラナイ。 ◎ 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.
`辞書$には、 適用-可能な`拡張d属性$はない。 ◎ No extended attributes are applicable to dictionaries.
辞書~型の利用の一つは、 `演算$に対し,随意~引数をいくつでも — 呼出ng~codeの所で指定される順序に制約を課すことなく — 与えられるようにすることである。 例えば,次の`~IDL片$を考える: ◎ 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:
[Exposed=Window] interface Point { constructor(); attribute double x; attribute double y; }; dictionary PaintOptions { DOMString fillPattern = "black"; DOMString strokePattern; Point position; }; [Exposed=Window] interface GraphicsContext { undefined drawRectangle(double %width, double %height, optional PaintOptions %options); };
この~IDLの~JS実装においては、 随意な `PaintOptions^T 辞書~用に `Object^jt を渡せる: ◎ In a JavaScript implementation of the IDL, an Object can be passed in for the optional PaintOptions dictionary:
/* `GraphicsContext^T の~instanceを取得する。 ◎ Get an instance of GraphicsContext. */ var %ctx = getGraphicsContext(); /* 矩形を描く。 ◎ Draw a rectangle. */ %ctx.drawRectangle( 300, 200, { fillPattern: "red", position: new Point(10, 10) } );
`PaintOptions^T の~mbは、 いずれも`随意$diCである。 `drawRectangle()^M の定義は、 `fillPattern^M が省略された場合を取扱うための明示的な言い回しを含める必要はない — その場合、 所与の`既定~値$diCをとるものと見做せるので。 一方で、[ `strokePattern^M / `position^M ]が省略された事例は,明示的に取扱う必要がある。 ◎ The members of PaintOptions are optional. If fillPattern is omitted, the definition of drawRectangle can assume that it has the given default values and not include explicit wording to handle its omission. drawRectangle needs to explicitly handle the case where strokePattern and position are omitted.
2.8. 例外
`例外@ ( `exception^en )とは、 ~errorを表現する~objを成す型であり,実装により[ 投出される, または `first^en ~class値として扱われる ]ものである。 ~Web~IDLには、 いくつもの定義済みな例外がある — 各~仕様は、 それらを参照して,自身の[ 演算, 属性, 等々 ]の定義にて投出できる。 各~仕様は、 ~customな例外~型も, `DOMException$T を`継承-$する`~ifc$として定義できる。 ◎ 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 has a number of pre-defined exceptions that specifications can reference and throw in their definition of operations, attributes, and so on. Custom exception types can also be defined, as interfaces that inherit from DOMException.
例外は、 次に挙げる種類に大別される:
- `単純~例外@ ◎ A simple exception\
- 次に挙げるいずれかの型として識別される ⇒# `EvalError@jE, `RangeError@jE, `ReferenceError@jE, `TypeError@jE, `URIError@jE ◎ is identified by one of the following types: • EvalError • RangeError • ReferenceError • TypeError • URIError
- これらは、 ~JS`~error~obj$に対応する (ただし,[ `SyntaxError$jt / `Error$jt ]は、[ ~JS構文解析器/作者 ]用に予約-済みなので,故意に省略されている)。 各 `単純~例外$の意味は、 ~JS仕様における対応する~error~objに合致する。 ◎ These correspond to all of the JavaScript error objects (apart from SyntaxError and Error, which are deliberately omitted as they are reserved for use by the JavaScript parser and by authors, respectively). The meaning of each simple exception matches its corresponding error object in the JavaScript specification.
- `DOMException$T ◎ The second kind of exception is a DOMException,\
- これらは、 `名前$eXを与えることにより,[ 生じた~errorについて~program的に更に自己検分-可能な詳細 ]を供する。 そのような`名前$eXは、 下に与える`~DOMException用の名前~表t$から~~選ばれる。 ◎ which provides further programmatically-introspectable detail on the error that occurred by giving a name. Such names are drawn from the DOMException names table below.
- 注記: `DOMException$T は、 `~ifc型$なので,~IDLにおいて型として利用できる。 したがって、 例えば`演算$の`返り値~型$を `DOMException$T として宣言することも許容される。 しかしながら、 これは,一般には不良な~patternである — 例外は、[ 返されるものではなく,投出されされるもの ]であることが意味されるので。 ◎ As DOMException is an interface type, it can be used as a type in IDL. This allows for example an operation to be declared to have a DOMException return type. This is generally a bad pattern, however, as exceptions are meant to be thrown and not returned.
- `DOMException$T の派生~ifc ◎ The final kind of exception is a derived interface of DOMException.\
- これらは、 より複雑なので,専用な `~DOMException派生~ifc@#idl-DOMException-derived-interfaces§ にて述べられる。 ◎ These are more complicated, and thus described in the dedicated section § 2.8.2 DOMException derived interfaces.
`例外を作成する@ ときは、[ `単純~例外$に対しては,その型~名/ `DOMException$T に対しては,その`名前$eXに加えて `DOMException$T ]を供して表記する。 例外は、 `例外を作成する$ために要求される詳細を供して `例外を投出する@ よう表記することもできる。 どちらの事例でも、 ~call元は,[ 当の例外が何を指示するかについての追加的な情報 ]を供してもヨイ — それは、 当の例外の~messageを構築するときに有用になる。 ◎ Simple exceptions can be created by providing their type name. A DOMException can be created by providing its name followed by DOMException. Exceptions can also be thrown, by providing the same details required to create one. In both cases, the caller may provide additional information about what the exception indicates, which is useful when constructing the exception’s message.
例外を作成して投出する言い回しの用例を以下に示す 【各~用例の直後には、和訳における表記も併記する】。 ◎ Here is are some examples of wording to use to create and throw exceptions.\
-
型 `TypeError$jE の新たな `単純~例外$を投出するときは: ◎ To throw a new simple exception whose type is TypeError:
`Throw@~WEBIDLjs#javascript-throw$ a `TypeError$jE.
`~THROW$ `TypeError$jE
-
`名前$eX `NotAllowedError$E を伴う新たな `DOMException$T を投出するときは: ◎ To throw a new DOMException with name "NotAllowedError":
`Throw@~WEBIDLjs#javascript-throw$ a "`NotAllowedError^E" `DOMException^T.
`~THROW$ `NotAllowedError$jE
-
`名前$eX "`SyntaxError$E" を伴う新たな `DOMException$T を作成するときは: ◎ To create a new DOMException with name "SyntaxError":
Let %object be a newly `created@#dfn-create-exception^ "`SyntaxError^E" `DOMException^T.
%object ~LET 新たな `SyntaxError$E 例外
-
`名前$eX "`OperationError$E" を伴う新たな `DOMException$T で`~promiseを却下する$ときは: ◎ To reject a promise with a new DOMException with name "OperationError":
Reject %p with an "`OperationError^E" `DOMException^T.
`~promiseを却下する$( %p, `OperationError$E 例外 )
【 この~siteの和訳における例外の[ 投出-/作成- ]用の表記では、 `DOMException$T (および引用符)を省略している。 `単純~例外$のときと同じ形になるが、 単純~例外は一握りしかない上, これらが同じ名前を共有することは(将来も含めて)まずないと考えられるので (詳細は、 `~algoに共通して利用される表記@index.html#common-algo-symbols$を~~参照されたし)。 】
例外~messageを構築するために利用される追加的な情報を含める例: ◎ An example of including additional information used to construct the exception message would be:
`Throw@~WEBIDLjs#javascript-throw$ a "`SyntaxError^E" `DOMException^T indicating that the given value had disallowed trailing spaces.
`~THROW$ 次を指示している "`SyntaxError$E" ⇒ 所与の値の末尾には~spaceは許容されない
そのような追加的な文脈は、 当の例外がなぜ投出されたか一目瞭然でないとき,実装者にとって最も助けになる — 例: 当の~algo内に "`SyntaxError$E" `DOMException$T を投出する段がいくつもあるなど。 対照的に,ある仕様が[ 利用者は所与の特能を利用する許可を供したか否か ]を検査した直後に "`NotAllowedError$E" `DOMException$T を投出する場合、 実装が どの類の~messageを構築すべきかは相応に明白なので, それを指定することは必要yでない。 ◎ Such additional context is most helpful to implementers when it is not immediately obvious why the exception is being thrown, e.g., because there are many different steps in the algorithm which throw a "SyntaxError" DOMException. In contrast, if your specification throws a "NotAllowedError" DOMException immediately after checking if the user has provided permission to use a given feature, it’s fairly obvious what sort of message the implementation ought to construct, and so specifying it is not necessary.
例外を作成したり, 作成した例外を投出した結果の挙動は、 言語束縛に特有になる。 ◎ The resulting behavior from creating and throwing an exception is language binding specific.
注記: ~JS言語束縛の場合にどうなるかについては、 `例外の作成-法と投出-法@~WEBIDLjs#js-creating-throwing-exceptions§を見よ。 ◎ See § 3.14.3 Creating and throwing exceptions for details on what creating and throwing an exception entails in the JavaScript language binding.
2.8.1. 基底 `DOMException$T ~errorの名前
下に与える `~DOMException用の名前~表t@ にて,基底 `DOMException$T ~ifcの~instance用に許容される`名前$eXを — [ そのような各~名前が何を意味するかについての記述 ]および[ 旧来の数量-~error~code値 ]と伴に — すべて挙げる。 ◎ The DOMException names table below lists all the allowed names for instances of the base DOMException interface, along with a description of what such names mean, and legacy numeric error code values.
注記: `DOMException$T を`継承-$する~ifcは、 `~DOMException派生~ifc@#idl-DOMException-derived-interfaces§ に述べられる方式で,各自の自前の名前 — この表tに挙げられていない名前 — を有することになる。 ◎ Interfaces inheriting from DOMException, in the manner described in § 2.8.2 DOMException derived interfaces, will have their own names, not listed in this table.
各~仕様は、 `DOMException$T 型の[ `例外を作成する$/`例外を投出する$ ]ときは,[ これらの名前のうち いずれか ]を利用しなければナラナイ。 仕様~策定者は、[ これらの名前には,自身の事例に良く収まるものが無い ]と予見する場合には, 新たな名前を共有される名前空間に追加することについて — 当の~communityがそのような労に協調できるよう — 論交するための`DOMException name proposal$fIしなければナラナイ。 利用事例に特有な新たな名前を追加することが重要になるのは、[ ~web開発者たちが、 単独の~APIから発生した複数の~error条件を差別化することになる ]ものと予見される場合に限られることに注意。 ◎ When creating or throwing a DOMException, specifications must use one of these names. If a specification author believes none of these names are a good fit for their case, they must file an issue to discuss adding a new name to the shared namespace, so that the community can coordinate such efforts. Note that adding new use-case-specific names is only important if you believe web developers will discriminate multiple error conditions arising from a single API.
“非推奨d” と~markされた `DOMException$T 名は、 旧来の目的~用に保たれたものであり,その利用eは忌避される。 ◎ The DOMException names marked as deprecated are kept for legacy purposes, but their usage is discouraged.
注記: ここに定義される "`SyntaxError$E" `DOMException$T 例外と ~JSの `SyntaxError$jt とを混同しないこと。 前者は — 例えば,選択子を構文解析するときなど — ~Web~APIにおける構文解析-時の~errorを報告するために利用される一方で、 後者は~JS構文解析器~用に予約されている。 これをより一義化し易くするため、 単に `SyntaxError$E を利用せずに,常に[ "`SyntaxError$E" `DOMException$T ]と表記して `DOMException$T を指す方が好ましい。 【!`DOM$r】 ◎ Note: Don’t confuse the "SyntaxError" DOMException defined here with JavaScript’s SyntaxError. "SyntaxError" DOMException is used to report parsing errors in web APIs, for example when parsing selectors, while the JavaScript SyntaxError is reserved for the JavaScript parser. To help disambiguate this further, always favor the "SyntaxError" DOMException notation over just using SyntaxError to refer to the DOMException. [DOM]
【 が,この~siteの各~仕様の和訳では、 上述したとおり, `DOMException^T を省略している — それらの仕様には、 ~JS `SyntaxError^jt は現れないので。 】
名前 ◎ Name | 記述 ◎ Description | 旧来の~code名(括弧内は数値) ◎ Legacy code name and value |
---|---|---|
`IndexSizeError@E | 非推奨d。 `RangeError$jE を利用すること。 ◎ Deprecated. Use RangeError instead. | `INDEX_SIZE_ERR@Ec (1) |
`HierarchyRequestError@E | 演算から不正な`~node~tree$が得られることになる。 `DOM$r ◎ The operation would yield an incorrect node tree. [DOM] | `HIERARCHY_REQUEST_ERR@Ec (3) |
`WrongDocumentError@E | ~objが属している`文書$は間違っている。 `DOM$r ◎ The object is in the wrong document. [DOM] | `WRONG_DOCUMENT_ERR@Ec (4) |
`InvalidCharacterError@E | 文字列に妥当でない文字が含まれている。 ◎ The string contains invalid characters. | `INVALID_CHARACTER_ERR@Ec (5) |
`NoModificationAllowedError@E | ~objは改変できない。 ◎ The object can not be modified. | `NO_MODIFICATION_ALLOWED_ERR@Ec (7) |
`NotFoundError@E | ~objは見出せなかった。 ◎ The object can not be found here. | `NOT_FOUND_ERR@Ec (8) |
`NotSupportedError@E | 演算は~supportされていない。 ◎ The operation is not supported. | `NOT_SUPPORTED_ERR@Ec (9) |
`InUseAttributeError@E | 属性は別の`要素$により利用-中にある。 `DOM$r ◎ The attribute is in use by another element. [DOM] | `INUSE_ATTRIBUTE_ERR@Ec (10) |
`InvalidStateError@E | ~objは不正な状態にある。 ◎ The object is in an invalid state. | `INVALID_STATE_ERR@Ec (11) |
`SyntaxError@E | 文字列は期待される~patternに合致していない。 ◎ The string did not match the expected pattern. | `SYNTAX_ERR@Ec (12) |
`InvalidModificationError@E | ~objはこの仕方では改変できない。 ◎ The object can not be modified in this way. | `INVALID_MODIFICATION_ERR@Ec (13) |
`NamespaceError@E | 演算は `Namespaces in XML^cite において許容されない。 `XML-NAMES$r ◎ The operation is not allowed by Namespaces in XML. [XML-NAMES] | `NAMESPACE_ERR@Ec (14) |
`InvalidAccessError@E | 非推奨d。 代わりに、[ 妥当でない引数に対しては `TypeError$jE / 未~supportな演算に対しては `NotSupportedError$E / 否認された要請に対しては `NotAllowedError$E ]を利用すること。 ◎ Deprecated. Use TypeError for invalid arguments, "NotSupportedError" DOMException for unsupported operations, and "NotAllowedError" DOMException for denied requests instead. | `INVALID_ACCESS_ERR@Ec (15) |
`TypeMismatchError@E | 非推奨d。 代わりに、 `TypeError$jE を利用すること。 ◎ Deprecated. Use TypeError instead. | `TYPE_MISMATCH_ERR@Ec (17) |
`SecurityError@E | 演算は~secureでない。 ◎ The operation is insecure. | `SECURITY_ERR@Ec (18) |
`NetworkError@E | ~network~errorが生じた。 ◎ A network error occurred. | `NETWORK_ERR@Ec (19) |
`AbortError@E | 演算は中止された。 ◎ The operation was aborted. | `ABORT_ERR@Ec (20) |
`URLMismatchError@E | 非推奨d。 ◎ Deprecated. | `URL_MISMATCH_ERR@Ec (21) |
`QuotaExceededError@E | ~quotaを超過した。 ◎ The quota has been exceeded. | `QUOTA_EXCEEDED_ERR@Ec (22) |
`TimeoutError@E | 演算は時間切れになった。 ◎ The operation timed out. | `TIMEOUT_ERR@Ec (23) |
`InvalidNodeTypeError@E | 給された`~node$bpは、 不正であるか,この演算において不正な先祖がある。 `DOM$r ◎ The supplied node is incorrect or has an incorrect ancestor for this operation. [DOM] | `INVALID_NODE_TYPE_ERR@Ec (24) |
`DataCloneError@E | ~objは~cloneできない。 ◎ The object can not be cloned. | `DATA_CLONE_ERR@Ec (25) |
`EncodingError@E | 符号化する演算に失敗した (符号化-時, 復号-時どちらも含む)。 ◎ The encoding operation (either encoded or decoding) failed. | — |
`NotReadableError@E | I/O 読み取り演算に失敗した。 ◎ The I/O read operation failed. | — |
`UnknownError@E | 未知な一過性の事由により,演算に失敗した (例:~memoryを使い果たした)。 ◎ The operation failed for an unknown transient reason (e.g. out of memory). | — |
`ConstraintError@E | ~transactionにおける変異~演算は、 拘束を満たせないため,失敗した。 `INDEXEDDB$r ◎ A mutation operation in a transaction failed because a constraint was not satisfied. [INDEXEDDB] | — |
`DataError@E | 供された~dataは、 必要十分でない。 ◎ Provided data is inadequate. | — |
`TransactionInactiveError@E | 現在~作動中でない/すでに完遂した ~transactionに対し,要請が行われた。 `INDEXEDDB$r ◎ A request was placed against a transaction which is currently not active, or which is finished. [INDEXEDDB] | — |
`ReadOnlyError@E | “読専” ( `readonly^l ~mode)の~transactionにおいて,変異させようとする演算が試みられた。 `INDEXEDDB$r ◎ The mutating operation was attempted in a "readonly" transaction. [INDEXEDDB] | — |
`VersionError@E | 既存の~versionより低い~versionを利用して~databaseを open しようとした。 `INDEXEDDB$r ◎ An attempt was made to open a database using a lower version than the existing version. [INDEXEDDB] | — |
`OperationError@E | 演算に特有な事由により,演算に失敗した。 ◎ The operation failed for an operation-specific reason. | — |
`NotAllowedError@E | 要請された演算は、 現在の文脈においては ~UA/~platform からは — 場合によっては,利用者が否認したことにより — 許容されない。 ◎ The request is not allowed by the user agent or the platform in the current context, possibly because the user denied permission. | — |
`OptOutError@E | 利用者は、 当の処理nを~opt-outした。 ◎ The user opted out of the process. | — |
2.8.2. ~DOMException派生~ifc
ある例外が[ `DOMException$T の`名前$eXで供せるもの ]を超える[ ~program的に自己検分-可能な,追加的な情報 ]を運ぶ必要があるときは、 仕様~策定者は, `DOMException$T を`継承-$する`~ifc$を作成できる。 そのような`~ifc$ %~ifc は、 開発者から予測-可能な~~形をとるようにするため, 次に挙げる規則に従う必要がある: ◎ When an exception needs to carry additional programmatically-introspectable information, beyond what can be provided with a DOMException's name, specification authors can create an interface which inherits from DOMException. Such interfaces need to follow certain rules, in order to have a predictable shape for developers. Specifically:
-
%~ifc の`識別子$は、 次に従わなければナラナイ ⇒# `Error^c で終端する。 `~DOMException用の名前~表t$に挙げられた名前ではない。 ◎ The identifier of the interface must end with Error, and must not be any of the names in the DOMException names table.
- %~ifc は、 `構築子~演算$ — 以下 %構築子 — を有していなければナラナイ。 ◎ The interface must have a constructor operation\
- %構築子 は、 次を遂行しなければナラナイ ⇒ `this$V の`名前$eX ~SET %~ifc の`識別子$ ◎ which sets the instance’s name to the interface’s identifier.
- %構築子 は 1 個目の~parameterとして,次に従うものをとらなければナラナイ ⇒# %message と命名される。 `DOMString$T 型である。 `随意~引数$であり,既定では空~文字列になる。 ◎ Their constructor operation must take as its first parameter an optional DOMString named message defaulting to the empty string,\
- %構築子 は、 次を遂行しなければナラナイ ⇒ `this$V の`~message$eX ~SET %message ◎ and must set the instance’s message to message.
- %構築子 は、 2 個目の~parameterとして,[ 公開される必要がある追加的な情報 ]を包含している`辞書$をとるベキである — そのような辞書を成す各~mbに対し、 %~ifc は,次に従う`属性$を有するベキである ⇒# 同じ名前を伴う。 `読専$である。 %構築子 により受容された値を返す。 ◎ Their constructor operation should take as its second parameter a dictionary containing the additional information that needs to be exposed. ◎ They should have read only attributes, whose names are the same as the members of the constructor dictionary, which return the values accepted by the constructor operation.
- %~ifc の~instanceは、 `直列化-可能$になるベキである — その[ `直列化~手続き$/`逆直列化~手続き$ ]が当の追加的な情報を保全するように。 ◎ They should be serializable objects, whose serialization steps and deserialization steps preserve the additional information.
注記: これらの要件は、 次を意味する ⇒ そのような~ifcが継承した `code$M ~propは、 常に 0 を返す。 ◎ These requirements mean that the inherited code property of these interfaces will always return 0.
`DOMException$T 派生~ifc用の定義は、 それが追加的な情報として “~protocol~error~code” — ある~network~protocol( "ProtocolX" )越しに~serverから送信されて来た何かから導出される~code — を運ぶとするなら,次の様な見かけにもなろう: ◎ The definition for a DOMException derived interface which carries along an additional "protocol error code", which is derived from what the server sent over some some hypothetical network protocol "protocol X", could look something like this:
[Exposed=Window, Serializable] interface ProtocolXError : DOMException { constructor(optional DOMString %message = "", ProtocolXErrorOptions %options); readonly attribute unsigned long long errorCode; }; dictionary ProtocolXErrorOptions { required [EnforceRange] unsigned long long errorCode; };
各 `ProtocolXError^T ~instanceは、 整数をとる `~error~code@ を有する。 ◎ Every ProtocolXError instance has an error code, a number.
new `ProtocolXError^M(%message, %options)
構築子~手続きは:
◎
The new ProtocolXError(message, options) constructor steps are:
- `this$V の`名前$eX ~SET `ProtocolXError^l ◎ Set this's name to "ProtocolXError".
- `this$V の`~message$eX ~SET %message ◎ Set this's message to message.
- `this$V の`~error~code$ ~SET %options[ `errorCode^l ] ◎ Set this's error code to options["errorCode"].
`errorCode^M 取得子~手続きは ⇒ ~RET `this$V の`~error~code$ ◎ The errorCode getter steps are to return this's error code.
`ProtocolXError^T ~objは`直列化-可能$である: ◎ ProtocolXError objects are serializable objects.
-
その`直列化~手続き$は、 所与の ( %値, %直列形 ) に対し: ◎ Their serialization steps, given value and serialized, are:
- `DOMException$T 用の`直列化~手続き$( %値, %直列形 ) ◎ Run the DOMException serialization steps given value and serialized.
- %直列形 .`ErrorCode^sl ~SET %値 の`~error~code$ ◎ Set serialized.[[ErrorCode]] to value’s error code.
-
その`逆直列化~手続き$は、 所与の ( %直列形, %値 ) に対し: ◎ Their deserialization steps, given serialized and value, are:
- `DOMException$T 用の`逆直列化~手続き$( %直列形, %値 ) ◎ Run the DOMException deserialization steps given serialized and value.
- %値 の`~error~code$ ~SET %直列形 .`ErrorCode^sl ◎ Set value’s error code to serialized.[[ErrorCode]].
`DOMException$T 派生~ifc用に[ `例外を作成する$/`例外を投出する$ ]ときは、 次を給する ⇒# その`~ifc$の`識別子$, それを構築するために必要な追加的な情報 ◎ To create or throw a DOMException derived interface, supply its interface identifier as well as the additional information needed to construct it.
`上の例@#example-domexception-derived-interface$による `ProtocolXError^T の~instanceを投出するときは: ◎ To throw an instance of the ProtocolXError exemplified above:
`~THROW$ `ProtocolXError^T — その ⇒ `~error~code$ ~SET 42 ◎ Throw a ProtocolXError whose error code is 42.
2.9. 列挙
`列挙@ ( `enumeration^en )は、[ 妥当な値たちが成す集合が,定義済みな文字列たちが成す集合になる ]ような型を宣言するために利用される,`定義$ ( `Enum$g に合致-) である。 `属性$に代入できる/`演算$に渡せる `DOMString$T 値を制約する用途に,列挙を利用できる。 ◎ 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^i { "enum", "values" /* , ... */ };
`列挙~値@ たちは、[ 1 個以上の `string$g ~literalを~commaで分離した~list ]として指定される。 `列挙~値$たちが成す~list内に重複が在ってはナラナイ。 ◎ The enumeration values are specified as a comma-separated list of string literals. The list of enumeration values must not include duplicates.
別の命名法を利用する理由が特にない限り、 列挙~値は,すべて小文字にすることが強く示唆される — 複数の単語は,~dashで分離するか全く分離しないことにして。 例えば、 ~objが作成される( `create^en される)べきであることを指示する列挙~値は, `createobject^l や `create-object^l などと命名することもできる。 列挙~値の単語を~dashで分離するかどうか裁定するときは、 類似な他の~APIと一貫するよう,関係する列挙~値の利用を考慮すること。 ◎ 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 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.
注記: ~JS言語束縛においては、 `属性$への妥当でない文字列~値の代入は無視される一方, 他の文脈(例えば`演算$の引数)にて そのような値を渡したときは例外が投出される。 ◎ Note: In the JavaScript binding, assignment of an invalid string value to an attribute is ignored, while passing such a value in other contexts (for example as an operation argument) results in an exception being thrown.
`列挙$に適用-可能な`拡張d属性$は、 この仕様では定義されない。 ◎ No extended attributes defined in this specification are applicable to enumerations.
次の`~IDL片$は、[ 1 個の`属性$, 1 個の`演算$引数 ]の型として利用される`列挙$を定義する ◎ The following IDL fragment defines an enumeration that is used as the type of an attribute and an operation argument:
enum MealType { "米", "麺", "その他" };
[Exposed=Window]
interface Meal {
attribute MealType type;
attribute double size; /*
グラム~~単位
◎
in grams
*/
undefined initialize(MealType %type, double %size);
};
~JS実装は、 `type^M ~propに代入され得る文字列や `initialize^M 関数に渡され得る文字列を[ `列挙$内で識別されるもの ]に制約することになる。 ◎ A JavaScript 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(); /* `Meal^T の~instanceを取得する。 ◎ Get an instance of Meal. */ %meal.initialize("米", 200); /* 演算は通常通り呼出される。 ◎ Operation invoked as normal. */ try { %meal.initialize("肉", 100); /* `TypeError^jE が投出される。 ◎ Throws a TypeError. */ } catch (%e) { } %meal.type = "麺"; /* 属性は通常通り代入される。 ◎ Attribute assigned as normal. */ %meal.type = "魚"; /* 属性~代入は無視される。 ◎ Attribute assignment ignored. */ %meal.type == "麺"; /* `true^jv に評価される。 ◎ Evaluates to true. */
2.10. ~callback関数
“`Custom DOM Elements^cite” 仕様からは、 `~callback関数~型$を,~platform~objから供される関数に利用することが求まれている。 “~callback関数” を — 両方の目的に利用できることが明瞭になるよう — 単に “関数” へ改称するべきか? ◎ 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?
`~callback関数@ は、 関数~型を宣言するときに利用される,`定義$ ( `callback^sym `CallbackRest$g に合致-) である。 ◎ A callback function is a definition (matching callback CallbackRest) used to declare a function type.
callback `identifier^i = `return_type^i (/* arguments... */);
注記: 似た命名の`~callback~ifc$も見よ。 ◎ Note: See also the similarly named callback interfaces.
等号の左側の`識別子$が `~callback関数$の名前を与える。 等号の右側の[ 返り値~型 ( `Type$g に合致-) と[ 引数~list ( `ArgumentList$g に合致-) 【による型たち】 ]]が,`~callback関数~型$の~signatureを与える。 ◎ The identifier on the left of the equals sign gives the name of the callback function and the return type and argument list (matching Type and ArgumentList) on the right side of the equals sign gives the signature of the callback function type.
`~callback関数$は、 `定数$の型として利用してはナラナイ。 ◎ Callback functions must not be used as the type of a constant.
`~callback関数$に適用-可能な拡張d属性は ⇒# `LegacyTreatNonObjectAsNull$x ◎ The following extended attribute is applicable to callback functions: [LegacyTreatNonObjectAsNull].
次の`~IDL片$は、 演算の完了-時に利用者~定義な関数を呼出す~API用に利用される,`~callback関数$を定義する。 ◎ 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 = undefined (DOMString %status); [Exposed=Window] interface AsyncOperations { undefined performOperation(AsyncOperationCallback %whenFinished); };
~JS言語束縛においては、 `関数~obj$は演算~引数として渡される。 ◎ In the JavaScript language binding, a function object is passed as the operation argument.
var %ops = getAsyncOperations(); /*
`AsyncOperations^T の~instanceを取得する。
◎
Get an instance of AsyncOperations.
*/
%ops.performOperation(function(%status) {
window.alert("Operation finished, status is " + %status + ".");
});
2.11. ~typedef
`~typedef@ は、 ある型に対し 新たな名前を宣言するために利用される,`定義$ ( `Typedef$g に合致-) である。 この新たな名前は、 言語束縛からは公開されない。 これはもっぱら,~IDLにおいて型を参照するための略記として利用される。 ◎ 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^i `identifier^i;
`新たな名前が与えられる型@ ( `TypeWithExtendedAttributes$g に合致-) は, `typedef^sym ~keywordの後に指定され、 型に後続する `identifier$g ~tokenが,その新たな名前を与える。 ◎ The type being given a new name is specified after the typedef keyword (matching TypeWithExtendedAttributes), and the identifier token following the type gives the name.
`Type$g は、 同じまたは別の`~typedef$の識別子にしてはナラナイ。 ◎ The Type must not be the identifier of the same or another typedef.
`~typedef$に適用-可能な`拡張d属性$は、 この仕様では定義されない。 ◎ No extended attributes defined in this specification are applicable to typedefs.
次の`~IDL片$は、 長い`連列~型$の代わりに短い`識別子$の利用を許容する,`~typedef$の利用をデモる。 ◎ The following IDL fragment demonstrates the use of typedefs to allow the use of a short identifier instead of a long sequence type.
[Exposed=Window] interface Point { attribute double x; attribute double y; }; typedef sequence<Point> Points; [Exposed=Window] interface Widget { boolean pointWithinBounds(Point %p); boolean allPointsWithinBounds(Points %ps); };
2.12. ~ifcを実装している~obj
`~IDL片$たちが成す集合の実装においては、 ~objは,`~platform~obj$であるものとして述べれる。 ◎ In a given implementation of a set of IDL fragments, an object can be described as being a platform object.
`~platform~obj@ は、 ある`~ifc$を実装する~objである。 ◎ Platform objects are objects that implement an interface.
`旧来の~platform~obj@ とは、 ~AND↓ を満たす`~platform~obj$である:
- `Global$x `拡張d属性$を伴わない`~ifc$を実装する
- [ `有index~propを~support$する ]~OR[ `有名~propを~support$する ]
~browserにおいては、 例えば[ ~page内で走らせている~JSに対し,~page内容への~accessを供する ]ために~browserが実装した ( `Node^T や `Document^T などの~ifcを実装している) ~DOM~objが,`~platform~obj$になる。 これらの~objは、[ C++ などの言語で実装される~exotic~obj ]になることも[ ~nativeな~JS~obj ]になることもあろう。 いずれにせよ,所与の~IDL片たちが成す集合の実装は、 自身が作成したすべての`~platform~obj$を認識-可能になる必要がある。 これは、 所与の~objに対し[ 何らかの内部~状態 — 当の~objは実装における~platform~objであるかどうかを記録するそれ — を~~実際に伴わせる ]か[ たぶん,~objが ある種の内部 C++ ~classを実装しているかどうかを見る ]ことにより,~~実現できるであろう。 ~platform~objが[ 正確に,どう実装から認識されるか ]については、 実装に特有になる。 ◎ 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 JavaScript 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 JavaScript 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 recognized by a given implementation of a set of IDL fragments is implementation specific.
~system内の他のすべての~objは、 ~platform~objとしては扱われないことになる。 例えば、 ~browserが開いた~Web~pageが, DOM Core を実装する~JS~libraryを読込んだとする。 この~libraryは、 ~browserが供する実装とは異なる実装と見なされることになる。 ~JS~libraryにより作成された[ `Node^T ~ifcを実装する~obj ]は、 ~browser実装による[ `Node^T を実装する~platform~obj ]としては扱われないことになる。 ◎ 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 a JavaScript 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 JavaScript library that implement the Node interface will not be treated as platform objects that implement Node by the browser implementation.
他方,`~callback~ifc$は、 どの~JS~objも実装できる。 これは、 作者が定義する演算を~Web~APIから呼出すことを許容する。 例えば, DOM Events 実装は、[ `EventListener$T ~ifcを実装する~objを供する ]ことにより[ ~callbackを登録すること ]を作者に許容する。 ◎ Callback interfaces, on the other hand, can be implemented by any JavaScript object. This allows Web APIs to invoke author-defined operations. For example, the DOM Events implementation allows authors to register callbacks by providing objects that implement the EventListener interface.
2.13. 型
この節では、 次について挙げていく ⇒# ~Web~IDLで~supportされる型, 各 型に対応する値たちが成す集合, 各 型に対応する `INFRA$r 型, その型の`定数$は どう表現されるか ◎ This section lists the types supported by Web IDL, the set of values or Infra type corresponding to each type, and how constants of that type are represented.
互いに類似な型たちには、 次に挙げる総称が付与されている:
- `整数~型@ ⇒# `byte$T, `octet$T, `short$T, `unsigned short$T, `long$T, `unsigned long$T, `long long$T, `unsigned long long$T ◎ The following types are known as integer types: byte, octet, short, unsigned short, long, unsigned long, long long and unsigned long long.
- `数量-型@ ⇒# すべての`整数~型$, `float$T, `unrestricted float$T, `double$T, `unrestricted double$T ◎ The following types are known as numeric types: the integer types, float, unrestricted float, double and unrestricted double.
- `~primitive型@ ⇒# `bigint$T, `boolean$T, すべての`数量-型$ ◎ The primitive types are bigint, boolean and the numeric types.
- `文字列~型@ ⇒# `DOMString$T, すべての`列挙~型$, `ByteString$T, `USVString$T ◎ The string types are DOMString, all enumeration types, ByteString and USVString.
- `~buffer型@ ⇒# `ArrayBuffer$T, `SharedArrayBuffer$T ◎ The buffer types are ArrayBuffer and SharedArrayBuffer.
- `有型~配列~型@ ⇒# `Int8Array$T, `Int16Array$T, `Int32Array$T, `Uint8Array$T, `Uint16Array$T, `Uint32Array$T, `Uint8ClampedArray$T, `BigInt64Array$T, `BigUint64Array$T, `Float16Array$T, `Float32Array$T, `Float64Array$T ◎ The typed array types are Int8Array, Int16Array, Int32Array, Uint8Array, Uint16Array, Uint32Array, Uint8ClampedArray, BigInt64Array, BigUint64Array, Float16Array, Float32Array, and Float64Array.
- `~buffer~view型@ ⇒# `DataView$T, `有型~配列~型$ ◎ The buffer view types are DataView and the typed array types.
- `~buffer~source型@ ⇒# `~buffer型$, `~buffer~view型$ ◎ The buffer source types are the buffer types and the buffer view types.
- `~obj型@ ⇒# `object$T 型, すべての`~ifc型$, すべての`~callback~ifc型$ ◎ The object type, all interface types, and all callback interface types are known as object types.
[ `演算$を呼出すとき/`属性$に値を代入するとき ]には,言語束縛に特有な型から~IDL型への変換が必要yあるが、 それらすべては[ 演算に指定された機能性/属性~代入 ]が遂げられる前に遂行される。 変換を遂行できない場合、[ 演算は走らない/属性は更新されない ]ことになる。 一部の言語束縛では、 この型~変換により,例外が投出され得る。 そのような場合、 これらの例外は[ 演算を呼出す/属性に代入する ]よう試みた~codeへ伝播することになる。 ◎ 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.
2.13.1. `any^T
`any$T 型は、 `共用体~型$以外の,アリなすべての型の和集合である。 ◎ The any type is the union of all other possible non-union types.
`any$T 型は、 その各 値ごとに特有な非 `any$T 型が結付けられる~~点で,~~特別な共用体~型のようなものである。 例えば, `any$T 型のある値は `unsigned long$T 150 をとり得る一方、 別の値は `long$T 150 をとり得る。 これらは別個な型の値になる。 ◎ 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.
`any$T 型のある値を成す特定0の型は、 その値の `特有~型@ と呼ばれる。 (`共用体~型$の値も`特有~型$を有する。) ◎ The particular type of an any value is known as its specific type. (Values of union types also have specific types.)
【 `any^T 型は、 `any@~WEBIDLjs#js-any§T に見られるように `null^V 値もとり得るが (~JS `null^jv 値を受容し, `object?^T 型の `null^V に変換される), “`~nullable$型である” ものとは定義されていない。 】
2.13.2. `undefined^T
`undefined$T 型は、 一意な値をとる。 【値も `undefined^V と記される。】 ◎ The undefined type has a unique value.
~IDLにおける `undefined$T 定数~値は、 `undefined^sym ~tokenで表現される。 ◎ undefined constant values in IDL are represented with the undefined token.
`undefined$T は、 次に挙げるものの型として利用してはナラナイ:
- 引数 — どの状況下においても (`演算$, `~callback関数$, `構築子~演算$, 等々 内で)。 代わりに,`随意~引数$を利用すること。
- `辞書~mb$ — 共用体~内であっても 【すなわち、~mbの型が`共用体~型$の場合は,その`平坦~化~mb型~群$を成すすべての型】。 代わりに,`要求され$diCない`辞書~mb$を利用すること。
注記: この値は、 以前は `void^T と綴られ,許容される利用-法は もっと制限されていた。 ◎ Note: This value was previously spelled void, and more limited in how it was allowed to be used.
2.13.3. `boolean^T
`boolean$T 型は 2 つの値: `true^V と `false^V をとり得る。 ◎ The boolean type has two values: true and false.
~IDLにおいては、 `boolean$T 定数~値は[ `true^sym / `false^sym ]~tokenで表現される。 ◎ boolean constant values in IDL are represented with the true and false tokens.
2.13.4〜11. 整数~型
【 この訳では、 原文の § 2.12.4 〜 § 2.12.11 の内容 — 各種~IDL整数~型の定義を集約して,一括して与える。 】
各種[ 有符号/無符号 ]`整数~型$が とり得る値の範囲は、 次の表tで与えられる: ◎ The (byte|short|long|long long/octet|unsigned short|unsigned long|unsigned long long) type is a (signed/unsigned) integer type that has values in the range [xxx, xxx]. ◎ xxx constant values in IDL are represented with integer tokens.
~IDL型 | 最小~値 | 最大~値 |
---|---|---|
`byte@T | −2`7^sup | 2`7^sup ~MINUS 1 |
`octet@T | 0 | 2`8^sup ~MINUS 1 |
`short@T | −2`15^sup | 2`15^sup ~MINUS 1 |
`unsigned short@T | 0 | 2`16^sup ~MINUS 1 |
`long@T | −2`31^sup | 2`31^sup ~MINUS 1 |
`unsigned long@T | 0 | 2`32^sup ~MINUS 1 |
`long long@T | −2`63^sup | 2`63^sup ~MINUS 1 |
`unsigned long long@T | 0 | 2`64^sup ~MINUS 1 |
~IDLにおいては、 どの`整数~型$も,その定数~値は `integer$g ~tokenで表現される。
2.13.12〜15. 浮動小数点数~型
【 この訳では、 原文の § 2.12.12 〜 § 2.12.15 の内容 — 各種~IDL浮動小数点数~型の定義を集約して,一括して与える。 】
各種 “浮動小数点数 型” — `整数~型$でない`数量-型$ — に対応する値の範囲は、 次の表tで与えられる:
~IDL型 | 値の範囲 `IEEE-754$r |
---|---|
`float@T | すべての有限[ 単精度 32 ~bit IEEE 754 浮動小数点数 ]が成す集合 ◎ 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] |
`unrestricted float@T | アリなすべての有限, 非~有限[ 単精度 32 ~bit IEEE 754 浮動小数点数 ]が成す集合に,各種 NaN( “`not a number^en /非数” )を加えた集合 ◎ 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, non-finite, and special "not a number" values (NaNs). [IEEE-754] |
`double@T | すべての有限[ 倍精度 64 ~bit IEEE 754 浮動小数点数 ]が成す集合 ◎ 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] |
`unrestricted double@T | アリなすべての有限, 非~有限[ 倍精度 64 ~bit IEEE 754 浮動小数点数 ]が成す集合に,各種 NaN( “`not a number^en /非数” )を加えた集合 ◎ 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, non-finite, and special "not a number" values (NaNs). [IEEE-754] |
~IDLにおいては、 どの浮動小数点数 型も, その定数~値は `decimal$g ~tokenで表現される。 ◎ (unrestricted )?(float|double) constant values in IDL are represented with decimal tokens.
32 ~bit浮動小数点~型を特に利用する理由が無い限り,仕様は、 `float$T ではなく`double$T を利用するべきである。 `double$T が表現できる値~集合は,より近く~JS `Number^jt に合致するので。 ◎ Unless there are specific reasons to use a 32-bit floating point type, specifications should use double rather than float, since the set of values that a double can represent more closely matches a JavaScript Number.
2.13.16. `bigint^T
`bigint$T 型は、 範囲が制約されない任意な整数をとり得る。 ◎ The bigint type is an arbitrary integer type, unrestricted in range.
~IDLにおける `bigint$T 定数~値は、 `integer$g ~tokenで表現される。 ◎ bigint constant values in IDL are represented with integer tokens.
2.13.17. `DOMString^T
`DOMString$T 型は、 `文字列$たちに対応する。 ◎ The DOMString type corresponds to strings.
注記: `null^V は `DOMString$T 型の値ではないことに注意。 ~IDLにおいて `null^V を許容するためには、[ `DOMString?^sym と記される`~nullable$ `DOMString$T ]を利用する必要がある。 ◎ Note: null is not a value of type DOMString. To allow null, a nullable DOMString, written as DOMString? in IDL, needs to be used.
注記: `DOMString$T 値は、 対を成さない`~surrogate符号位置$も含み得る。 それが望ましくない場合は、 `USVString$T を利用すること。 ◎ Note: A DOMString value might include unmatched surrogate code points. Use USVString if this is not desirable.
~IDLにおいては、 `DOMString$T 値を定数として表現する仕方は無い。 `DOMString$T 型の[ `辞書~mb$ / 演算の`随意~引数$ ]に対し,その[ `既定~値$diC / `既定~値$ ]を[ `string$g ~literalによる`値$stR ]に設定することはできるが。 ◎ There is no way to represent a constant DOMString value in IDL, although DOMString dictionary member default values and operation optional argument default values can be set to the value of a string literal.
2.13.18. `ByteString^T
`ByteString$T 型は、 `~byte列$たちに対応する。 ◎ The ByteString type corresponds to byte sequences.
~IDLにおいては、 `ByteString$T 値を定数として表現する仕方は無い。 `ByteString$T 型の[ `辞書~mb$ / 演算の`随意~引数$ ]に対し,その[ `既定~値$diC / `既定~値$ ]を[ `string$g ~literalによる`値$stR ]に設定することはできるが。 ◎ There is no way to represent a constant ByteString value in IDL, although ByteString dictionary member default values and operation optional argument default values can be set to the value of a string literal.
仕様は、[ HTTP など,~byteと文字列を交換-可能に利用する~protocol ]を~ifc化するときに限り, `ByteString$T を利用するべきである。 一般に,文字列は、 その値が[ 常に ASCII または 何らかの 8 ~bit文字~符号化法 ]になることが期待されているとしても, `DOMString$T 値で表現するべきである。 8 ~bit~dataを保持するためには、 `ByteString$T ではなく,[ `octet$T か `byte$T ]を要素とする[ `連列~型$ / `凍結d配列~型$ / `Uint8Array$T / `Int8Array$T ]を利用するべきである。 ◎ Specifications should only use ByteString for interfacing with protocols that use bytes and strings interchangeably, such as HTTP. In general, strings should be represented with DOMString values, even if it is expected that values of the string will always be in ASCII or some 8-bit character encoding. Sequences or frozen arrays with octet or byte elements, Uint8Array, or Int8Array should be used for holding 8-bit data rather than ByteString.
2.13.19. `USVString^T
`USVString$T 型は、 `~scalar値~文字列$たちに対応する。 これらは、 文脈に依存して,[ ( 16 ~bit無符号~整数をとる)`符号単位$たちが成す連列 / `~scalar値$たちが成す連列 ]どちらにも扱われ得る。 ◎ The USVString type corresponds to scalar value strings. Depending on the context, these can be treated as sequences of either 16-bit unsigned integer code units or scalar values.
~IDLにおいては、 `USVString$T 値を定数として表現する仕方は無い。 `USVString$T 型の[ `辞書~mb$ / 演算の`随意~引数$ ]に対し,その[ `既定~値$diC / `既定~値$ ]を[ `string$g ~literalによる`値$stR ]に設定することはできるが。 ◎ There is no way to represent a constant USVString value in IDL, although USVString dictionary member default values and operation optional argument default values can be set to the value of a string literal.
仕様は、[ ~text処理を遂行する際に,`~scalar値$たちが成す文字列に対する演算が必要になる ]ときに限り, `USVString$T を~APIに利用するべきである。 文字列を利用する ほとんどの~APIは、 文字列~内の`符号単位$に いかなる解釈も行わない `DOMString$T を利用するべきである。 疑わしい場合は `DOMString$T を利用すること。 ◎ Specifications should only use USVString for APIs that perform text processing and need a string of scalar values to operate on. Most APIs that use strings should instead be using DOMString, which does not make any interpretations of the code units in the string. When in doubt, use DOMString.
2.13.20. `object^T
`object$T 型は、 アリなすべての[ 非 `null^V ~obj参照 ]が成す集合に対応する。 ◎ The object type corresponds to the set of all possible non-null object references.
~IDLにおいては、 `object$T 値を定数として表現する仕方は無い。 ◎ There is no way to represent a constant object value in IDL.
アリなすべての~obj参照に加えて, `null^V 値も内包する型を表すためには、 `~nullable型$ `object?^T を利用すること。 ◎ To denote a type that includes all possible object references plus the null value, use the nullable type object?.
2.13.21. `symbol^T
`symbol$T 型は、 アリなすべての~symbol値が成す集合に対応する。 ~symbol値は、 不透明かつ `object$T でない値であるが, 同一性( `identity^en )は備える(すなわち、自身のみに等しい)。 ◎ The symbol type corresponds to the set of all possible symbol values. Symbol values are opaque, non-object values which nevertheless have identity (i.e., are only equal to themselves).
~IDLにおいては、 `symbol$T 値を定数として表現する仕方は無い。 ◎ There is no way to represent a constant symbol value in IDL.
2.13.22. ~ifc型
`~ifc$を識別する`識別子$は、 その~ifcを実装する[ アリなすべての非 `null^V ~obj参照が成す集合 ]に対応する型を指すために利用される。 ◎ 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.
~ifc型の~IDL値は,単に~obj参照により表現される。 ◎ An IDL value of the interface type is represented just by an object reference.
~IDLにおいて,特定0の~ifc型~用の~obj参照~値を定数として表現する仕方は無い。 ◎ There is no way to represent a constant object reference value for a particular interface type in IDL.
[ 所与の~ifcを実装する アリなすべての~obj参照に加え, `null^V 値も内包する ]ような型を表すためには、 `~nullable型$を利用すること。 ◎ To denote a type that includes all possible references to objects implementing the given interface plus the null value, use a nullable type.
2.13.23. ~callback~ifc型
`~callback~ifc$を識別する`識別子$は、[ アリなすべての非 `null^V ~obj参照が成す集合 ]に対応する型を指すために利用される。 ◎ An identifier that identifies a callback interface is used to refer to a type that corresponds to the set of all possible non-null references to objects.
この~ifc型の~IDL値は[ ~obj参照, `~callback文脈$ ]の組により表現される。 `~callback文脈@ とは、 言語束縛に特有な値であり,[ 言語束縛に特有な~obj参照が`~IDL値に変換-$される時点 ]における[ 実行~文脈についての情報 ]を格納するために利用される。 ◎ 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.
注記: ~JS~objに対しては、 `~callback文脈$は,[ `Object^jt 値が~IDL~callback~ifc型の値に変換される時点の,`現任な設定群~obj$ ]への参照を保持するために利用される。 `~callback~ifc型@~WEBIDLjs#js-callback-interface§を見よ。 ◎ Note: For JavaScript objects, the callback context is used to hold a reference to the incumbent settings object at the time the Object value is converted to an IDL callback interface type value. See § 3.2.16 Callback interface types.
~IDLにおいては、 特定0の`~callback~ifc型$用の~obj参照~値を定数として表現する仕方は無い。 ◎ There is no way to represent a constant object reference value for a particular callback interface type in IDL.
[ アリなすべての~obj参照に加え, `null^V 値も内包する ]ような型を表すためには、 `~nullable型$を利用すること。 ◎ To denote a type that includes all possible references to objects plus the null value, use a nullable type.
2.13.24. 辞書~型
`辞書$を識別する`識別子$は、[ 当の辞書~定義を固守する,すべての辞書が成す集合 ]に対応する型を指すために利用される。 ◎ 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.
`有順序~map$用の~literal構文も,辞書を表現するために利用できる — 文脈から暗黙的に[ 当の~mapは、 特定の辞書~型の~instanceとして扱われる ]ものと解されるならば。 しかしながら、 ~IDL片の内側では,辞書~値を定数として表現する仕方は無い。 ◎ The literal syntax for ordered maps may also be used to represent dictionaries, when it is implicitly understood from context that the map is being treated as an instance of a specific dictionary type. However, there is no way to represent a constant dictionary value inside IDL fragments.
2.13.25. 列挙~型
`列挙$を識別する`識別子$は、[ その`列挙~値$に属する文字列 ( `DOMString$T と同じく,`符号単位$たちが成す連列) ]を値にとる型を指すために利用される。 ◎ 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.
`DOMString$T と同様に, ~IDLにおいては、 `列挙$値を定数として表現する仕方は無い。 列挙~型の[ `辞書~mb$ / 演算の`随意~引数$ ]に対し,その[ `既定~値$diC / `既定~値$ ]を[ `string$g ~literalによる`値$stR ]に設定することはできるが。 ◎ Like DOMString, there is no way to represent a constant enumeration value in IDL, although enumeration-typed dictionary member default values and operation optional argument default values can be set to the value of a string literal.
2.13.26. ~callback関数~型
`~callback関数$を識別する`識別子$は、[ 所与の~signatureを伴う関数~objへの参照 ]を値にとる型を指すために利用される。 ◎ 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.
注記: `~callback関数$の定義に `LegacyTreatNonObjectAsNull$x 拡張d属性が指定された場合、 関数でない~objへの参照も値にとり得る。 ◎ Note: If the [LegacyTreatNonObjectAsNull] extended attribute is specified on the definition of the callback function, the values can be references to objects that are not functions.
~callback関数~型の~IDL値は,[ ~obj参照, `~callback文脈$ ]の組により表現される。 ◎ An IDL value of the callback function type is represented by a tuple of an object reference and a callback context.
注記: `~callback~ifc型$のときと同じく,`~callback文脈$は、[ ~JS `Object^jt 値が~IDL~callback~ifc型の値に変換される時点の,`現任な設定群~obj$への参照 ]を保持するために利用される。 `~callback関数~型@~WEBIDLjs#js-callback-function§を見よ。 ◎ Note: As with callback interface types, the callback context is used to hold a reference to the incumbent settings object at the time a JavaScript Object value is converted to an IDL callback function type value. See § 3.2.19 Callback function types.
~IDLにおいては、 `~callback関数$値を定数として表現する仕方は無い。 ◎ There is no way to represent a constant callback function value in IDL.
2.13.27. ~nullable型 — `T?^T
`~nullable型@ は、 (その `内縁~型@ と呼ばれる) 既存の型から構築される~IDL型であり、 とり得る値が成す集合は,内縁~型がとり得る値に値 `null^V のみを~~追加したものになる。 ~IDLにおいては、 `~nullable型$は,既存の型の後に文字 `003F^U1 を置いて表現される。 `内縁~型$は、 次に挙げるもの以外でなければナラナイ: ◎ 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 (?) character after an existing type. The inner type must not be:
- `any$T 型
- `~promise型$
- `観測-可能な配列~型$
- 別の~nullable型
- 次を満たす`共用体~型$ ⇒ [ `~nullable型を内包する$ ]~OR[ その`平坦~化~mb型~群$を成す ある型は`辞書~型$である ]
注記: 辞書~型は,一般には~nullableになれるが、 その場合,演算~引数や辞書~mbの型には利用できない。 ◎ Note: Although dictionary types can in general be nullable, they cannot when used as the type of an operation argument or a dictionary member.
~IDLにおいては、 ~nullable型の定数~値は,その`内縁~型$の定数~値と同じ仕方で表現されるか, または `null^sym ~tokenで表現される。 ◎ Nullable type constant values in IDL are represented in the same way that constant values of their inner type would be represented, or with the null token.
例えば、 値 `true^V, `false^V, `null^V をとり得る型は, `boolean?^T と記される: ◎ For example, a type that allows the values true, false and null is written as boolean?:
[Exposed=Window] interface NetworkFetcher { undefined get(optional boolean? areWeThereYet = false); };
次の`~ifc$は 2 個の`属性$を有する。 一方は `DOMString$T または `null^V 値を値にとり得る。 他方は `Node^T ~objへの参照または `null^V 値を値にとり得る: ◎ 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:
[Exposed=Window] interface Node { readonly attribute DOMString? namespaceURI; readonly attribute Node? parentNode; /* ... */ };
2.13.28. 連列~型 — ~sequence_T
`連列~型@ — ~sequence_T — は、 ~parameter化された型であり, 型 %T の値たちが成す`~list$を値にとる。 ◎ The sequence<T> type is a parameterized type whose values are (possibly zero-length) lists of values of type T.
連列は常に値渡しである。 連列が何らかの種類の~objで表現される言語束縛においても、 `~platform~obj$に連列が渡された際に,当の連列への参照が~objに保有されることはない。 同様に,~platform~objから返されるどの連列も複製であり、 それに対する改変は~platform~objからは可視にならないことになる。 ◎ 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.
`~list$用の~literal構文も,連列を表現するために利用できる — 文脈から暗黙的に[ 当の~listは、 ある連列の~instanceとして扱われる ]ものと解されるならば。 しかしながら、 ~IDL片の内側では,連列~値を定数として表現する仕方は無い。 ◎ The literal syntax for lists may also be used to represent sequences, when it is implicitly understood from context that the list is being treated as a sequences. However, there is no way to represent a constant sequence value inside IDL fragments.
連列は、[ `属性$/`定数$ ]の型として利用してはナラナイ。 ◎ Sequences must not be used as the type of an attribute or constant.
注記: この制約は、[ `連列~型$は、 その参照が渡し回されるものではなく,複製されるものである ]ことを,仕様の[ 策定者/利用者 ]から見て明瞭にするためにある。 連列~型の~writableな`属性$には、 代わりに,連列を[ 取得する, 設定する ]`演算$~pairの利用が示唆される。 ◎ 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.
`~list$は、 次を満たすならば,暗黙的に ~sequence_T 型の値として扱える ⇒ ~listを成すどの`~item$も %T 型である ◎ Any list can be implicitly treated as a sequence<T>, as long as it contains only items that are of type T.
2.13.29. ~record型 — ~record_KV
`~record型@ — ~record_KV — は、 ~parameter化された型であり, 次を満たす`有順序~map$を値にとる ⇒ それを成す各`~entry$mapは、 次を満たす ⇒ [ その`~key$mapは型 %K の ある~instanceである ]~AND[ その`値$mapは型 %V の ある~instanceである ] ◎ A record type is a parameterized type whose values are ordered maps with keys that are instances of K and values that are instances of V.\
%K は、[ `DOMString$T / `USVString$T / `ByteString$T ]でなければナラナイ。 ◎ K must be one of DOMString, USVString, or ByteString.
`有順序~map$用の~literal構文も,~recordを表現するために利用できる — 文脈から暗黙的に[ 当の~mapは、 ~record型の~instanceとして扱われる ]ものと解されるならば。 しかしながら、 ~IDL片の内側では,~record値を定数として表現する仕方は無い。 ◎ The literal syntax for ordered maps may also be used to represent records, when it is implicitly understood from context that the map is being treated as a record. However, there is no way to represent a constant record value inside IDL fragments.
~recordは常に値渡しである。 ~recordが何らかの種類の~objで表現される言語束縛においても、 `~platform~obj$に~recordが渡された際に,当の~recordへの参照が~objに保有されることはない。 同様に,~platform~objから返されるどの~recordも複製であり、 それに対する改変は~platform~objからは可視にならないことになる。 ◎ Records are always passed by value. In language bindings where a record is represented by an object of some kind, passing a record to a platform object will not result in a reference to the record being kept by that object. Similarly, any record returned from a platform object will be a copy and modifications made to it will not be visible to the platform object.
~recordは、[ `属性$/`定数$ ]の型として利用してはナラナイ。 ◎ Records must not be used as the type of an attribute or constant.
`有順序~map$は、 次を満たすならば,暗黙的に ~record_KV 型の値として扱える ⇒ ~mapを成すどの`~entry$mapも,その[ `~key$mapは %K 型, `値$mapは %V 型 ]である ◎ Any ordered map can be implicitly treated as a record<K, V>, as long as it contains only entries whose keys are all of of type K and whose values are all of type V.
2.13.30. ~promise型 — ~promise_T
`~promise型@ — ~promise_T — は、 ~parameter化された型であり, 次として利用される~objへの参照を値にとる ⇒ “[ 非同期な演算において,先送りされ得る(非同期にもなり得る)算出 ]の最終的な結果†を保持するための場( `place holder^en )” `ECMA-262$r 【† %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”.\
~promise~objの意味論についての詳細は、 ~JS仕様 `25.4@~TC39#sec-promise-objects§ を見よ。 ◎ See section 25.4 of the JavaScript specification for details on the semantics of promise objects.
~promise型は~nullableでないが、 %T は~nullableでもヨイ。 ◎ Promise types are non-nullable, but T may be nullable.
~IDLにおいては、 ~promise値を表現する仕方は無い。 ◎ There is no way to represent a promise value in IDL.
2.13.31. 共用体~型
`共用体~型@ ( `union^en )は、 とり得る値が成す集合が[ 複数の型の,それぞれがとり得る値が成す集合 ]の和集合であるような,型である。 共用体~型 ( `UnionType$g に合致-) は、 ~keyword `or^sym で分離された型たちを丸括弧で括って記される。 共用体~型を構成する各~型は、 共用体の `~mb型@ と呼ばれる。 ◎ A union type is a type whose set of values is the union of those in two or more other types. Union types (matching UnionType) are written as a series of types separated by the or keyword with a set of surrounding parentheses. The types which comprise the union type are known as the union’s member types.
注記: 例えば, `(Node or DOMString)^c や `(double or sequence<double>)^c などのように記す。 `共用体~型$に全体として `?^sym 接尾辞を適用するときは, `(Node or DOMString)?^c のように,右~丸括弧の後に置く。 ◎ 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)?.
共用体~型の`~mb型$は、 入子な共用体~型にまでは掘り下げられないことに注意。 したがって, `(double or (sequence<long> or Event) or (Node or DOMString)?)^T の~mb型は、 次に挙げる型からなる ⇒# `double^T, `(sequence<long> or Event)^T, `(Node or DOMString)?^T ◎ Note that the member types of a union type do not descend into nested union types. So for (double or (sequence<long> or Event) or (Node or DOMString)?) the member types are double, (sequence<long> or Event) and (Node or DOMString)?.
`any$T 型と同様、 共用体~型の値は,その値に合致する特定0の`~mb型$を`特有~型$として有する。 ◎ Like the any type, values of union types have a specific type, which is the particular member type that matches the value.
`共用体~型$ %T — `注釈された型$にもなり得る — の `平坦~化~mb型~群@ とは、 次の手続きで決定される型たちが成す集合である: ◎ The flattened member types of a union type, possibly annotated, is a set of types determined as follows:
- %S ~LET 空~集合 ◎ Let T be the union type. ◎ Initialize S to ∅.
-
%T を成す ~EACH( `~mb型$ %U ) に対し: ◎ For each member type U of T:
- %U ~SET %U の`最も内縁な型$ ◎ If U is an annotated type, then set U to be the inner type of U. ◎ If U is a nullable type, then set U to be the inner type of U.
- ~IF[ %U は `共用体~型$である ] ⇒ %U の`平坦~化~mb型~群$に属するすべての型を %S に追加する ◎ If U is a union type, then add to S the flattened member types of U.
- ~ELSE ⇒ %U を %S に追加する ◎ Otherwise, U is not a union type. Add U to S.
- ~RET %S ◎ Return S.
注記: 例えば,`共用体~型$ `(Node or (sequence<long> or Event) or (XMLHttpRequest or DOMString)? or sequence<(sequence<double> or NodeList)>)^T の`平坦~化~mb型~群$は、 次に挙げる 6 つの型からなる ⇒# `Node^T, `sequence<long>^T, `Event^T, `XMLHttpRequest^T, `DOMString^T, `sequence<(sequence<double> or NodeList)>^T ◎ Note: For example, the flattened member types of the union type (Node or (sequence<long> or Event) or (XMLHttpRequest or DOMString)? or sequence<(sequence<double> or NodeList)>) are the six types Node, sequence<long>, Event, XMLHttpRequest, DOMString and sequence<(sequence<double> or NodeList)>.
`共用体~型$ %T の `~nullable~mb型の個数@ とは、 次の手続きで決定される整数である: ◎ The number of nullable member types of a union type is an integer determined as follows:
- %n ~LET 0 ◎ Let T be the union type. ◎ Initialize n to 0.
-
-
~IF[ %U は `~nullable型$である ]: ◎ If U is a nullable type, then:
- %n ~INCBY 1 ◎ Set n to n + 1.
- %U ~SET %U の`内縁~型$ ◎ Set U to be the inner type of U.
-
~IF[ %U は `共用体~型$である ]: ◎ If U is a union type, then:
- %m ~LET %U の`~nullable~mb型の個数$ ◎ Let m be the number of nullable member types of U.
- %n ~INCBY %m ◎ Set n to n + m.
-
- ~RET %n ◎ Return n.
`~mb型$には、 `any$T 型を利用してはナラナイ。 ◎ The any type must not be used as a union member type.
`共用体~型$の`~nullable~mb型の個数$は 0 か 1 でなければナラナイ。 1 の場合、 その共用体~型は`平坦~化~mb型~群$に`辞書~型$を含んではナラナイ。 ◎ 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.
~OR↓ を満たす型は `~nullable型を内包する@ とされる。 ◎ A type includes a nullable type if:
- `~nullable型$である ◎ the type is a nullable type, or
- [ `注釈された型$である ]~AND[ その`内縁~型$anOは`~nullable型$である ] ◎ the type is an annotated type and its inner type is a nullable type, or
- [ `共用体~型$である ]~AND[ その `~nullable~mb型の個数$は 0 でない( 1 である) ] ◎ the type is a union type and its number of nullable member types is 1.
【 概念的には, `null^V を値にとり得る型と考えられる。 ただし、 この定義では `any$T 型は含まれないことになる。 】
`共用体~型$の`平坦~化~mb型~群$に属する どの 2 つの型も`判別-可能$でなければナラナイ。 ◎ Each pair of flattened member types in a union type, T and U, must be distinguishable.
[ `bigint$T, `数量-型$ ]が成す共用体を作成することはアリであるが、 一般に,その利用は、 `NumberFormat$jt などの[ それを計算には利用せず,値を整形するような~ifc ]用に限られるものと想定されている。 そのような共用体を受容しつつ,`数量-型$の値に対しては単に `bigint$T に変換してから処理するのは、 適切でない — それは、 精度~errorを導入する~riskを冒すことになるので。 この特能を利用するときは、 その前に, `Intent to use bigint/numeric union$fIされたし。 ◎ It is possible to create a union of bigint and a numeric type. However, this is generally only supposed to be used for interfaces such as NumberFormat, which formats the values rather than using them in calculations. It would not be appropriate to accept such a union, only to then convert values of the numeric type to a bigint for further processing, as this runs the risk of introducing precision errors. Please file an issue before using this feature.
~OR↓ を満たす型は、 `~undefinedを内包する@ とされる: ◎ A type includes undefined if:
- `undefined$T 型である ◎ the type is undefined, or
- [ `~nullable型$である ]~AND[ その`内縁~型$は`~undefinedを内包する$ ] ◎ the type is a nullable type and its inner type includes undefined, or
- [ `注釈された型$である ]~AND[ その`内縁~型$anOは`~undefinedを内包する$ ] ◎ the type is an annotated type and its inner type includes undefined, or
- [ `共用体~型$である ]~AND[ その`~mb型$のうちいずれかは、 `~undefinedを内包する$ ] ◎ the type is a union type and one of its member types includes undefined.
~IDLにおいては、 `共用体~型$の定数~値は,それらの`~mb型$の定数~値と同じ仕方で表現される。 ◎ Union type constant values in IDL are represented in the same way that constant values of their member types would be represented.
2.13.32. 注釈された型
既存の型に ある種の`拡張d属性$を指定することにより,追加的な型を作成できる。 そのような型は, `注釈された型@ ( `annotated type^en )と呼ばれ、 注釈された~~元の型は,その `内縁~型@anO ( `inner type^en )と呼ばれる。 ◎ Additional types can be created from existing ones by specifying certain extended attributes on the existing types. Such types are called annotated types, and the types they annotate are called inner types.
`[Clamp] long^c は、 新たな`注釈された型$を定義する — その挙動は `内縁~型$anO `long$T に基づくが, `Clamp$x 拡張d属性に指定されるように改変される。 ◎ [Clamp] long defines a new annotated type, whose behavior is based on that of the inner type long, but modified as specified by the [Clamp] extended attribute.
次のものが `型に適用-可能@ な拡張d属性とされる ⇒ `AllowResizable$x, `AllowShared$x, `Clamp$x, `EnforceRange$x, `LegacyNullToEmptyString$x ◎ The following extended attributes are applicable to types: [AllowResizable], [AllowShared], [Clamp], [EnforceRange], and [LegacyNullToEmptyString].
所与の~IDL型 %型 に `結付けられた拡張d属性@ は、 次に従って決定される: ◎ The extended attributes associated with an IDL type type are determined as follows:
- %拡張d属性~群 ~LET 新たな`集合$ ◎ Let extended attributes be a new empty set.
-
~IF[ %型 は `TypeWithExtendedAttributes$g 生成規則 %P の一部として現れている ] ⇒ %P の中の `ExtendedAttributeList$g 内に在る ~EACH( `拡張d属性$ %X ) に対し ⇒ %拡張d属性~群 に %X を`付加する$set ◎ If type appears as part of a TypeWithExtendedAttributes production, append each of the extended attributes present in the production’s ExtendedAttributeList to extended attributes.
[Exposed=Window] interface I { attribute [XAttr] long attrib; undefined f1(sequence<[XAttr] long> %arg); undefined f2(optional [XAttr] long %arg); maplike<[XAttr2] DOMString, [XAttr3] long>; }; dictionary D { required [XAttr] long member; };
【 `XAttr*^x が該当する拡張d属性を表す。以下の例も同様。】 -
~IF[ %型 は`共用体~型$ %U の`~mb型$である ] ⇒ ~EACH( %U に`結付けられた拡張d属性$ %X ) に対し ⇒ %拡張d属性~群 に %X を`付加する$set ◎ If type is a member type of a union type U, append each of the extended attributes associated with U to extended attributes.
[Exposed=Window] interface I { attribute [XAttr] (long or Node) attrib; };
-
~IF[ %型 は[ `Argument$g 生成規則 %P の中に直に現れる `Type$g 生成規則 ]の一部として現れている ] ⇒ %P の中の `ExtendedAttributeList$g 内に在る ~EACH( `拡張d属性$ %X ) に対し ⇒ ~IF[ %X は`型に適用-可能$である ] ⇒ %拡張d属性~群 に %X を`付加する$set ◎ If type appears as part of a Type production directly within an Argument production, append to extended attributes all of the extended attributes present in the production’s ExtendedAttributeList that are applicable to types.
[Exposed=Window] interface I { undefined f([XAttr] long %attrib); };
この例の `XAttr^x は、 `型に適用-可能$な場合に限り,引数の型に結付けられる (他の場合、 `XAttr^x は,引数に適用される)。 ◎ Note that this is an example of this step only if [XAttr] is applicable to types; otherwise [XAttr] applies to the argument, and not the argument’s type.
-
~IF[ %型 は[ `DictionaryMember$g 生成規則 %P の中に直に現れる `Type$g 生成規則 ]の一部として現れている ] ⇒ %P の中の `ExtendedAttributeList$g 内に在る ~EACH( `拡張d属性$ %X ) に対し ⇒ ~IF[ %X は`型に適用-可能$である ] ⇒ %拡張d属性~群 に %X を`付加する$set ◎ If type appears as part of a Type production directly within a DictionaryMember production, append to extended attributes all of the extended attributes present in the production’s ExtendedAttributeList that are applicable to types.
dictionary D { [XAttr] long member; };
この例の `XAttr^x は、 `型に適用-可能$な場合に限り,辞書~mbの型に結付けられる (他の場合、 `XAttr^x は,辞書~mbに適用される)。 ◎ Note that this is an example of this step only if [XAttr] is applicable to types; otherwise [XAttr] applies to the dictionary member, and not the member’s type.
-
~IF[ %型 は`~typedef$である ] ⇒ ~EACH( %型 により`新たな名前が与えられる型$に`結付けられた拡張d属性$ %X ) に対し ⇒ %拡張d属性~群 に %X を`付加する$set ◎ If type is a typedef, append the extended attributes associated with the type being given a new name to extended attributes.
typedef [XAttr] long xlong;
- ~RET %拡張d属性~群 ◎ Return extended attributes.
どの型に対しても,それに`結付けられた拡張d属性$は、 `型に適用-可能$でなければナラナイ。 ◎ For any type, the extended attributes associated with it must only contain extended attributes that are applicable to types.
2.13.33. ~buffer~source型
アリなすべての[[[ ~dataの~buffer, または[ ~dataの~bufferの~view ]]を表現する~obj ]への非 `null^V 参照 ]が成す集合に対応する,いくつかの型がある。 下の表tに、 それらの型, および それらが表現する[ ~bufferまたは その~view ]の種類を挙げる。 ◎ 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 | ~bufferの種類 ◎ Kind of buffer |
---|---|
`ArrayBuffer@T | 固定的な個数の~byteたちが成す~bufferへの~pointer( `null^V もとり得る)を保持する~obj。 ◎ An object that holds a pointer (which can be null) to a buffer of a fixed number of bytes |
`SharedArrayBuffer@T | 固定的な個数の~byteたちが成す共用~bufferへの~pointer( `null^V はとり得ない)を保持する~obj。 ◎ An object that holds a pointer (which cannot be null) to a shared buffer of a fixed number of bytes |
`DataView@T | `~buffer型$の~instanceへの~viewであって、 ~bufferの中の,任意な~offsetに格納されている[ 整数/浮動小数点 ]値への~accessを可能にするもの。 ◎ A view on to a buffer type instance that allows typed access to integers and floating point values stored at arbitrary offsets into the buffer |
`Int8Array@T | `~buffer型$の~instanceへの~viewであって、[ 所与の~bit~sizeの 2 の補数による有符号~整数からなる配列 ]を公開するもの。 ◎ A view on to a buffer type instance that exposes it as an array of two’s complement signed integers of the given size in bits |
`Int16Array@T | |
`Int32Array@T | |
`BigInt64Array@T | |
`Uint8Array@T | `~buffer型$の~instanceへの~viewであって、[ 所与の~bit~sizeの無符号~整数 ]からなる配列を公開するもの。 ◎ A view on to a buffer type instance that exposes it as an array of unsigned integers of the given size in bits |
`Uint16Array@T | |
`Uint32Array@T | |
`BigUint64Array@T | |
`Uint8ClampedArray@T | `~buffer型$の~instanceへの~viewであって、[ 値を切詰める変換も伴われるような, 8~bit無符号~整数 ]からなる配列を公開するもの。 ◎ A view on to a buffer type instance that exposes it as an array of unsigned 8-bit integers with clamped conversions |
`Float16Array@T | `~buffer型$の~instanceへの~viewであって、[ 所与の~bit~sizeの IEEE 754 浮動小数点数 ]からなる配列を公開するもの。 `Float16Array^T は、 ECMAScript 提案 `PROPOSAL-FLOAT16ARRAY$r に対応する。 ◎ A view on to a buffer type instance that exposes it as an array of IEEE 754 floating point numbers of the given size in bits; Float16Array corresponds to the ECMAScript proposal [PROPOSAL-FLOAT16ARRAY]. |
`Float32Array@T | |
`Float64Array@T |
注記: これらの型はすべて、 ~JSにて定義される~classに対応する。 ◎ Note: These types all correspond to classes defined in JavaScript.
これらのどの型も, ~IDLにおいては、 その型の値を定数として表現する仕方は無い。 ◎ There is no way to represent a constant value of any of these types in IDL.
仕様の中の注釈文~levelにおいては、 ~IDL`~buffer~source型$は,単純に~objへの参照である。 仕様の注釈文は、 ~buffer内の~byte列を検分したり操作するときは, `~buffer~source型@~WEBIDLjs#js-buffer-source-types§にて与える~algoを利用する必要がある。 ◎ 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 needs to use the algorithms in § 3.2.25 Buffer source types.
2.13.34. 凍結d配列~型 — ~FrozenArray_T
`凍結d配列~型@ — ~FrozenArray_T — は、 ~parameter化された型であり,[ 型 %T の値たちが成す,長さが固定的かつ改変-不能な配列 ]を保持する~objへの参照を値にとる。 ◎ 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.
`凍結d配列~型$は、 `~ifc$上に定義される[ `正則~属性$/`静的~属性$ ]の型として利用でき, それら以外に利用してはナラナイ。 ◎ Frozen array types must only be used as the type of regular attributes or static attributes defined on an interface.
次の`~IDL片$は、 2 つの凍結d配列~属性を伴う`~ifc$を定義する — うち一つは`読専$, もう一つはそうでない。 ◎ The following IDL fragment defines an interface with two frozen array attributes, one read only and one not.
[Exposed=Window] interface PersonalPreferences { readonly attribute FrozenArray<DOMString> favoriteColors; attribute FrozenArray<DOMString> favoriteFoods; undefined randomizeFavoriteColors(); };
これらの属性の挙動は、 次の様に定義することもできる: ◎ The behavior of these attributes could be defined like so:
各 `PersonalPreferences^T には、 次に挙げるものが結付けられる: ◎ ↓
- 好みな色~群 ⇒ `DOMString$T 型の値たちが成す凍結d配列 — 初期~時は,次の結果に等しくなるとする ⇒ `凍結d配列を作成する$( « `purple^l, `aquamarine^l » ) ◎ Each PersonalPreferences has associated favorite colors, a FrozenArray<DOMString>, initially equal to the result of creating a frozen array from « "purple", "aquamarine" ».
- 好みな食品~群 ⇒ `DOMString$T 型の値たちが成す凍結d配列 — 初期~時は,次の結果に等しくなるとする ⇒ `凍結d配列を作成する$( « » ) ◎ Each PersonalPreferences has an associated favorite foods, a FrozenArray<DOMString>, initially equal to the result of creating a frozen array from the empty list.
`favoriteColors^M `取得子~手続き$は ⇒ ~RET `this$V の好みな色~群 ◎ The favoriteColors getter steps are to return this's favorite colors.`favoriteFoods^M `取得子~手続き$は ⇒ ~RET `this$V の好みな食品~群 ◎ The favoriteFoods getter steps are to return this's favorite foods.`favoriteFoods^M `設定子~手続き$は ⇒ `this$V の好みな食品~群 ~SET `所与の値$ ◎ The favoriteFoods setter steps are to set this's favorite foods to the given value.`randomizeFavoriteColors()^M `~method手続き$は: ◎ The randomizeFavoriteColors() method steps are:
- %新たな好みな色~群 ~LET [ ~randomに選ばれた 2 個の色 ]を表現する文字列たちが成す~list ◎ Let newFavoriteColors be a list of two strings representing colors, chosen randomly.
- `this$V の好みな色~群 ~SET `凍結d配列を作成する$( %新たな好みな色~群 ) ◎ Set this's favorite colors to the result of creating a frozen array from newFavoriteColors.
`~FrozenArray_T$ 値は、 `連列~型$ (それは、値たちが成す~listであり,値渡しである) と違って,参照である。 ◎ Since FrozenArray<T> values are references, they are unlike sequence types, which are lists of values that are passed by value.
~IDLにおいては、 凍結d配列~値を定数として表現する仕方は無い。 ◎ There is no way to represent a constant frozen array value in IDL.
2.13.35. 観測-可能な配列~型 — ~ObservableArray_T
`観測-可能な配列~型@ は、 ~parameter化された型であり, 次の組合nへの参照を値にとる ⇒# 0 個以上の型 %T の~objからなる変異-可能な~list【 “観測-可能な配列” 】, 作者~codeがこの~listの内容を改変したときに遂行する挙動 ◎ An observable array type is a parameterized type whose values are references to a combination of a mutable list of objects of type T, as well as behavior to perform when author code modifies the contents of the list.
【 “観測-可能な” は、 “配列~型” ではなく,“配列” を形容する (他の “観測-可能な配列〜” も同様) — “観測-可能~配列” と記すこともできたが、 過度な漢字の連続は視覚的に認識しづらいので。 】
この~parameter化される型 %T は、[ `辞書~型$/`連列~型$/`~record型$/`観測-可能な配列~型$ ]であってはナラナイが,`~nullable$でもヨイ。 ◎ The parameterized type T must not be a dictionary type, sequence type, record type, or observable array type. However, T may be nullable.
観測-可能な配列~型は — `連列~型$, `凍結d配列~型$と同様に — ~JS配列~型を包装して,その用法に対し追加的な意味論を課す。 ◎ Similar to sequence types and frozen array types, observable array types wrap around JavaScript array types, imposing additional semantics on their usage.
観測-可能な配列~型は、[ `~ifc$上に定義された`正則~属性$ ]の型~以外には,利用してはナラナイ。 ◎ Observable array types must only be used as the type of regular attributes defined on an interface.
仕様~策定者は、 観測-可能な配列~型である属性~用に,次に挙げる~algoを指定できる: ◎ For an attribute whose type is an observable array type, specification authors can specify a series of algorithms:
- `観測-可能な配列~属性の有index値を設定する@ ◎ set an indexed value,\
- ( %値, %~index ) を受容する — %値 は、 当の観測-可能な配列~内の~index %~index に設定されようとしている~IDL値を与える。 ◎ which accepts an IDL value that is about to be set in the observable array, and the index at which it is being set;
- `観測-可能な配列~属性の有index値を削除する@ ◎ delete an indexed value,\
- ( %値, %~index ) を受容する — %値 は、 当の観測-可能な配列~内の~index %~index から除去されようとしている~IDL値を与える。 ◎ which accepts an IDL value that is about to be removed from the observable array, and the index from which it is being removed.
どちらの~algoも:
- 任意選択であり、 供されない場合の既定の挙動は,何もしないことになる。
- 例外を投出してヨイ — 例:無効な値を却下するなど。
~JS~codeが既存の~indexを新たな値に設定するとき、 これは,まず[ `観測-可能な配列~属性の有index値を削除する$~algoを~callして既存の値を除去して ]から[ 新たな値で`観測-可能な配列~属性の有index値を設定する$~algoを~callする ]ことに注意。 ◎ Note that when JavaScript code sets an existing index to a new value, this will first call the delete an indexed value algorithm to remove the existing value, and then the set an indexed value algorithm with the new value.
各`正則~属性$のうち,その型は`観測-可能な配列~型$であるものには、 それを `~backしている~list@ がある。 それは、 `~list$であり,初期~時には空とする。 仕様~策定者は、 ~backしている~listの内容を改変できる — それは、 ~JS~codeにより観測されるに伴い,自動的に観測-可能な配列の内容に反映されることになる。 同様に、 この観測-可能な配列の内容に対する,~JS~codeによる どの改変も — [ `観測-可能な配列~属性の有index値を設定する$, `観測-可能な配列~属性の有index値を削除する$ ]~algoを通過した後に — ~backしている~listの中へ【!back into】反映されることになる。 ◎ Every regular attribute whose type is an observable array type has a backing list, which is a list, initially empty. Specification authors can modify the contents of the backing list, which will automatically be reflected in the contents of the observable array as observed by JavaScript code. Similarly, any modifications by JavaScript code to the contents of the observable array will be reflected back into the backing list, after passing through the set an indexed value and delete an indexed value algorithms.
~IDLにおいては、 観測-可能な配列~値を定数として表現する仕方は無い。 ◎ There is no way to represent a constant observable array value in IDL.
次の`~IDL片$は、 観測-可能な配列~属性を伴う`~ifc$を定義する: ◎ The following IDL fragment defines an interface with an observable array attribute:
[Exposed=Window] interface Building { attribute ObservableArray<Employee> employees; };
属性の挙動は、 次の様に定義することもできる: ◎ The behavior of the attribute could be defined like so:
`Building^T ~obj %building の `employees^M 属性に対し,`観測-可能な配列~属性の有index値を設定する$ときは、 所与の ( %employee, %~index ) に対し: ◎ The set an indexed value algorithm for Building’s employees attribute, given employee and index, is:
- ~IF[ 今日, %employee が %building に~~入場することは、 許容されない ] ⇒ ~THROW `NotAllowedError$E ◎ If employee is not allowed to enter the building today, then throw a "NotAllowedError" DOMException.
- ~IF[ %~index ~GT 200 ] ⇒ ~THROW `QuotaExceededError$E ◎ If index is greater than 200, then throw a "QuotaExceededError" DOMException.
- %employee を作業につかせる ◎ Put employee to work!
`Building^T ~obj %building の `employees^M 属性に対し,`観測-可能な配列~属性の有index値を削除する$ときは、 所与の ( %employee, %~index ) に対し: ◎ The delete an indexed value algorithm for Building’s employees attribute, given employee and index, is:
- %employee は %building から~~退場したことを~~警備に~~通報する ◎ Alert security that employee has left the building.
~JS~codeは、 `employees^jp ~propを様々な仕方で操作することもできる: ◎ Then, JavaScript code could manipulate the employees property in various ways:
/* `Building^T の~instanceを取得する。 ◎ Get an instance of Building. */ const %building = getBuilding(); %building.employees.push(new Employee("A")); %building.employees.push(new Employee("B")); %building.employees.push(new Employee("C")); %building.employees.splice(2, 1); const employeeB = %building.employees.pop(); %building.employees = [new Employee("D"), employeeB, new Employee("C")]; %building.employees.length = 0; /* 次は例外を投出することになる: ◎ Will throw: */ %building.employees.push("Employee ではなく文字列");
これらの操作を成すすべては、 上に定義した`観測-可能な配列~属性の有index値を設定する$~algoを通過し, そこに述べられた条件の下で例外を投出し得る。 それらはまた,適切な副作用 — [ そこ,および`観測-可能な配列~属性の有index値を削除する$~algo内 ]に挙げられたそれ — も遂行することになる。 ◎ All of these manipulations would pass through the above-defined set an indexed value algorithm, potentially throwing if the conditions described there were met. They would also perform the appropriate side effects listed there and in the delete an indexed value algorithm.
上の~code例についての別の注記は、 `Array.prototype$jI からの~JS配列~methodすべてが,観測-可能な配列に対し どう働くかである。 それは~~実際、 全部的に `Array^jt ~instanceの様に挙動する: ◎ Another thing to note about the above code example is how all of the JavaScript array methods from %Array.prototype% work on the observable array. Indeed, it fully behaves like an Array instance:
const %normalArray = []; /* `employees^M の型を`有index~prop取得子$を伴う~ifcとして定義した場合、 %normalArray は 1 個の~item — `employees^M の値 — を包含することになろう。 観測-可能な配列~型(あるいは凍結d配列~型)であれば、 %normalArray は `employees^M の内側にある すべての~itemを包含することになる。 ◎ If building.employees were defined as an indexed property getter interface: normalArray would contains a single item, building.employees. ◎ For observable arrays (and frozen arrays): normalArray contains all of the items inside of building.employees. */ %normalArray.concat(%building.employees); /* %names は~JS `Array^jt 。 ◎ names is a JavaScript Array. */ const %names = %building.employees.map(%employee => %employee.name); /* 各種~brand検査にも合格する: ◎ Passes various brand checks: */ console.assert(%building.employees instanceof Array); console.assert(Array.isArray(%building.employees)); console.assert(%building.employees.constructor === Array); /* `JSON.stringify^c においてさえ配列として扱われる(外縁の `[]^c に注意): ◎ Even is treated as an array by JSON.stringify! (Note the outer []s.) */ console.assert(JSON.stringify(%building.employees) === ``^[{}]``^);
2.14. 拡張d属性
`拡張d属性@ ( `extended attribute^en )は、[ `定義$/ `注釈された型$としての型/ `~ifc~mb$/ `~ifc~mixin~mb$/ `~callback~ifc~mb$/ `~ns~mb$/ `辞書~mb$/ `演算$引数 ]上に現れ得る `注釈^em ( `annotation^en )であり,[ 言語束縛がこれらの構成子をどう取扱うことになるか ]を制御するために利用される。 拡張d属性は `ExtendedAttributeList$g により指定される。 それは、 全体が角括弧で括られた, 1 個以上の `ExtendedAttribute$g を~commaで分離した~listである。 ◎ An extended attribute is an annotation that can appear on definitions, types as annotated types, interface members, interface mixin members, callback 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.
文法~記号 `ExtendedAttribute$g は,ほとんどの[ ~tokenたちが成す連列 ]にも合致するが、 この文書で定義される`拡張d属性$は,より制約された構文のみを受容する。 `~IDL片$に~~現れるどの拡張d属性も、 次の表tに挙げる文法~記号いずれかへの合致-により,それが属する( 1 個~以上の)形が決定される: ◎ 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 five grammar symbols to determine which form (or forms) it is in:
文法~記号 | 形 | 例 |
---|---|---|
`ExtendedAttributeNoArgs$g | `引数をとらない@ | `[Replaceable]^c |
`ExtendedAttributeArgList$g | `引数~listを引数にとる@ | 現在は利用されない。 以前は `[Constructor(double x, double y)]^c のように利用されていた。 |
`ExtendedAttributeNamedArgList$g | `有名~引数~listを引数にとる@ | `[LegacyFactoryFunction=Image(DOMString src)]^c |
`ExtendedAttributeIdent$g | `識別子を引数にとる@ | `[PutForwards=name]^c |
`ExtendedAttributeIdentList$g | `識別子~listを引数にとる@ | `[Exposed=(Window,Worker)]^c |
`ExtendedAttributeWildcard$g | `~wildcardを引数にとる@ | `[Exposed=*]^c |
この仕様は、 ~JS言語束縛に適用-可能な,各種 `拡張d属性$を定義する。 それらについては `拡張d属性@~WEBIDLjs#js-extended-attributes§にて述べる。 各 拡張d属性の定義は、 上に挙げたどの形が許容されるか言明することになる。 ◎ This specification defines a number of extended attributes that are applicable to the JavaScript language binding, which are described in § 3.3 Extended attributes. Each extended attribute definition will state which of the above five forms are allowed.
3. ~JS言語束縛
【 この節の内容は、 `別~page@~WEBIDLjs$にて。 】
4. 共通な定義
この節では、 すべての`適合~実装$が~supportするモノトスル,いくつかの共通な定義を指定する。 ◎ This section specifies some common definitions that all conforming implementations must support.
4.1. `ArrayBufferView^T
typedef ( `Int8Array$T or `Int16Array$T or `Int32Array$T or `Uint8Array$T or `Uint16Array$T or `Uint32Array$T or `Uint8ClampedArray$T or `BigInt64Array$T or `BigUint64Array$T or `Float16Array$T or `Float32Array$T or `Float64Array$T or `DataView$T ) `ArrayBufferView$T;
`ArrayBufferView^T ~typedefは、[ `ArrayBuffer$T / `SharedArrayBuffer$T ] — ただし,後者は `AllowShared$x が利用されたときに限る — への~viewを供する~objを表現するために利用される。 ◎ The ArrayBufferView typedef is used to represent objects that provide a view on to an ArrayBuffer or SharedArrayBuffer (when [AllowShared] is used).
4.2. `BufferSource^T
typedef (`ArrayBufferView$T or `ArrayBuffer$T) `BufferSource$T;
`BufferSource^T ~typedefは、[ `ArrayBuffer$T あるいは,それへの~view ]を供する~objを表現するために利用される。 ◎ The BufferSource typedef is used to represent objects that are either themselves an ArrayBuffer or which provide a view on to an ArrayBuffer.
注記: `AllowShared$x は、 `BufferSource$T と伴には利用できない — `ArrayBuffer$T は、 それを~supportしないので。 代わりに `AllowSharedBufferSource$T を利用すること。 ◎ Note: [AllowShared] cannot be used with BufferSource as ArrayBuffer does not support it. Use AllowSharedBufferSource instead.
4.4. `DOMException^T
`DOMException$T 型は、 次の~IDL片により定義される`~ifc型$である: ◎ The DOMException type is an interface type defined by the following IDL fragment:
[Exposed=*, `Serializable$]
interface `DOMException$T {
/*
~JS言語束縛についての下の注記も見よ。
◎
but see below note about JavaScript binding
*/
`constructor@#dom-domexception-domexception$(optional `DOMString$T %message = "", optional `DOMString$T %name = "Error"),
readonly attribute `DOMString$T `name$M;
readonly attribute `DOMString$T `message$M;
readonly attribute `unsigned short$T `code$M;
const `unsigned short$T `INDEX_SIZE_ERR$Ec = 1;
const `unsigned short$T `DOMSTRING_SIZE_ERR@Ec = 2;
const `unsigned short$T `HIERARCHY_REQUEST_ERR$Ec = 3;
const `unsigned short$T `WRONG_DOCUMENT_ERR$Ec = 4;
const `unsigned short$T `INVALID_CHARACTER_ERR$Ec = 5;
const `unsigned short$T `NO_DATA_ALLOWED_ERR@Ec = 6;
const `unsigned short$T `NO_MODIFICATION_ALLOWED_ERR$Ec = 7;
const `unsigned short$T `NOT_FOUND_ERR$Ec = 8;
const `unsigned short$T `NOT_SUPPORTED_ERR$Ec = 9;
const `unsigned short$T `INUSE_ATTRIBUTE_ERR$Ec = 10;
const `unsigned short$T `INVALID_STATE_ERR$Ec = 11;
const `unsigned short$T `SYNTAX_ERR$Ec = 12;
const `unsigned short$T `INVALID_MODIFICATION_ERR$Ec = 13;
const `unsigned short$T `NAMESPACE_ERR$Ec = 14;
const `unsigned short$T `INVALID_ACCESS_ERR$Ec = 15;
const `unsigned short$T `VALIDATION_ERR@Ec = 16;
const `unsigned short$T `TYPE_MISMATCH_ERR$Ec = 17;
const `unsigned short$T `SECURITY_ERR$Ec = 18;
const `unsigned short$T `NETWORK_ERR$Ec = 19;
const `unsigned short$T `ABORT_ERR$Ec = 20;
const `unsigned short$T `URL_MISMATCH_ERR$Ec = 21;
const `unsigned short$T `QUOTA_EXCEEDED_ERR$Ec = 22;
const `unsigned short$T `TIMEOUT_ERR$Ec = 23;
const `unsigned short$T `INVALID_NODE_TYPE_ERR$Ec = 24;
const `unsigned short$T `DATA_CLONE_ERR$Ec = 25;
};
注記:
`DOMException
~custom言語束縛@~WEBIDLjs#js-DOMException-specialness§にて論じられるとおり、
~JS言語束縛は,【 `DOMException$T 型に対し】`~ifc型$に課される通常の要件を超える追加的な要件を課す。
◎
Note: as discussed in § 3.14.1 DOMException custom bindings, the JavaScript binding imposes additional requirements beyond the normal ones for interface types.
各 `DOMException$T ~objには、 `名前@eX, `~message@eX が結付けられる — どちらも`文字列$とする。 ◎ Each DOMException object has an associated name and message, both strings.
new DOMException(%message, %name)
構築子~手続きは:
◎
The new DOMException(message, name) constructor steps are:
- `this$V の`名前$eX ~SET %name ◎ Set this's name to name.
- `this$V の`~message$eX ~SET %message ◎ Set this's message to message.
`name@M 取得子~手続きは ⇒ ~RET `this$V の`名前$eX ◎ The name getter steps are to return this's name.
`message@M 取得子~手続きは ⇒ ~RET `this$V の`~message$eX ◎ The message getter steps are to return this's message.
`code@M 取得子~手続きは ⇒ ~RET `~DOMException用の名前~表t$内に[ `this$V の`名前$eX用の旧来の~code ]は[ 在るならば それ / 無いならば 0 ] ◎ The code getter steps are to return the legacy code indicated in the DOMException names table for this's name, or 0 if no such entry exists in the table.
`DOMException$T ~objは`直列化-可能$である: ◎ DOMException objects are serializable objects.
-
その`直列化~手続き$は、 所与の ( %値, %直列形 ) に対し: ◎ Their serialization steps, given value and serialized, are:
- %直列形.`Name^sl ~SET %値 の`名前$eX ◎ Set serialized.[[Name]] to value’s name.
- %直列形.`Message^sl ~SET %値 の`~message$eX ◎ Set serialized.[[Message]] to value’s message.
- ~UAは、 まだ仕様~化されていないが関心ng~data — 特に, `stack^jp ~propが挙げられる — が付随しているならば、 それを直列化した表現も %直列形 に添付するベキである ◎ User agents should attach a serialized representation of any interesting accompanying data which are not yet specified, notably the stack property, to serialized.
-
その`逆直列化~手続き$は、 所与の ( %直列形, %値, %宛先~realm ) に対し: ◎ Their deserialization steps, given value and serialized, are:
- %値 の`名前$eX ~SET %直列形.`Name^sl ◎ Set value’s name to serialized.[[Name]].
- %値 の`~message$eX ~SET %直列形.`Message^sl ◎ Set value’s message to serialized.[[Message]].
- 他にも %直列形 に添付された~dataがあるならば、 それも逆直列化して %値 に添付する ◎ If any other data is attached to serialized, then deserialize and attach it to value.
4.5. `Function^T
callback `Function$T = `any$T (`any$T... %arguments);
`Function^T `~callback関数$型は、 渡される引数や返り値の種類に対する制約が無い関数~値を表現するために利用される。 ◎ 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.
4.6. `VoidFunction^T
callback `VoidFunction$T = `undefined$T ();
`VoidFunction^T `~callback関数$型は、 引数をとらず, 値を返さない関数~値を表現するために利用される。 ◎ The VoidFunction callback function type is used for representing function values that take no arguments and do not return any value.
5. 拡張能
◎非規範的言語束縛の要件に対する拡張は、 この文書~内で定義される拡張d属性と競合しない`拡張d属性$を利用して指定できる。 [ 私的な~projectに特有な利用 ]のための拡張は、 他の仕様に現れる`~IDL片$に含められるべきではない。 他の仕様の用途に要求される拡張は、 この文書の将来~versionに取り込まれるためには, `Web IDL^cite の担当~group (この文書が書かれた時点では `W3C Web Platform ~WG@http://www.w3.org/WebPlatform/WG/$ 【現在は `W3C Web Applications ~WG@https://www.w3.org/groups/wg/webapps$】) と協調することが推奨される。 ◎ 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 ought 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.
この~IDL言語の他の側面は、 拡張しないことが強く奨励される。 ◎ Extensions to any other aspect of the IDL language are strongly discouraged.
6. 旧来の構成子
◎非規範的旧来の~Web~IDL構成子が存在するのは、 旧来の~Web~platform特能を指定できるようにするために限られる。 一般に,それらには、 文字列 `Legacy^l が接頭される。 [ 旧来の~Web~platform特能の挙動を指定する/ そのような特能との整合性を得る ]ことが要求されない限り、 旧来の~Web~IDL構成子は仕様~内に利用しないことが強く奨励される。 旧来の~Web~IDL構成子を利用したいと望む編集者には、 先に進む前に `Intent to use a legacy Web IDL construct$fI した上で論交することを,強く勧める。 ◎ Legacy Web IDL constructs exist only so that legacy Web platform features can be specified. They are generally prefixed with the "Legacy" string. It is strongly discouraged to use legacy Web IDL constructs in specifications unless required to specify the behavior of legacy Web platform features, or for consistency with such features. Editors who wish to use legacy Web IDL constructs are strongly advised to discuss this by filing an issue before proceeding.
旧来の構成子であること自体は、 この仕様から除去されつつあることは含意しない。 しかしながら,そのような構成子は、[ 様々な経験則から,その指定-対象である~Web~platform特能を[ まるごと除去できる/ 代わりに旧来のものでない~Web~IDL構成子に依拠するよう改変できる ]ことが指示される ]なら,将来にこの仕様から除去する良い候補になることを示唆する。 ◎ Marking a construct as legacy does not, in itself, imply that it is about to be removed from this specification. It does suggest however, that it is a good candidate for future removal from this specification, whenever various heuristics indicate that the Web platform features it helps specify can be removed altogether or can be modified to rely on non-legacy Web IDL constructs instead.
7. この仕様を参照するとき
◎非規範的他の仕様のうち, `~IDL片$を利用して~Web~platform~ifcを定義するものは、 この仕様を参照することになるものと期待されている。 それらの仕様には、 次の様な,[ この仕様に述べたとおり,~IDLを解釈することを指示する~~文 ]を含めることが示唆される: ◎ 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:
この仕様における各~IDL片は、 この仕様が規範とする参照文献にて定義される~IDL片とともに,[ “~Web~IDL” 仕様に述べられる, `適合~IDL片たちが成す集合$ に課される要件 ]に従って解釈するモノトスル。 [WEBIDL] ◎ 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]
加えて、 この仕様を参照する仕様における,~UA用の適合性クラスは、 この仕様の`適合~実装$クラスを参照することが示唆される: ◎ 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:
適合 FooML ~UAは、 “~Web~IDL” 仕様の記述に則り,この仕様に示されている各~IDL片に対しても `適合~実装$ になるモノトスル。 [WEBIDL] ◎ 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]
~privacyと~securityの考慮点
この仕様は、 ~JS値と~IDL値との間に変換~層を定義する。 この層の不正な実装は、 ~securityの課題を導き得る。 ◎ This specification defines a conversion layer between JavaScript and IDL values. An incorrect implementation of this layer can lead to security issues.
この仕様は、[ `any$T, `object$T ]~IDL型を通して,~JS値を直に利用する能も供する。 ~securityの課題を避けるため、 これらの値は,注意深く取扱われる必要がある。 特に,利用者~scriptは、 これらの値に対する ほぼ どの操作にも呼応して走り得る — その結果、 それらを利用している[ 仕様/実装 ]の期待を無効~化する。 ◎ This specification also provides the ability to use JavaScript values directly, through the any and object IDL types. These values need to be handled carefully to avoid security issues. In particular, user script can run in response to nearly any manipulation of these values, and invalidate the expectations of specifications or implementations using them.
この仕様は、 `SharedArrayBuffer$T ~objとヤリトリすることをアリにする — それは、 計時~攻撃を築くことにも利用できる。 これらの~objを利用する仕様は、 そのような攻撃を考慮する必要がある。 ◎ This specification makes it possible to interact with SharedArrayBuffer objects, which can be used to build timing attacks. Specifications that use these objects need to consider such attacks.
謝辞
◎非規範的編集者は、 この仕様に貢献された,次の方々に感謝する: ◎ The editors would like to thank the following people for contributing to this specification:\
`_acks1@~IDL文法
この節では、 開始~記号 `Definitions$g が`~IDL片$全体に合致する, LL(1) 文法を定義する。 ◎ This section defines an LL(1) grammar whose start symbol, Definitions, matches an entire IDL fragment.
文法~内の各~生成規則には、 その右側に 1 個~以上の記号たちが成す連列が示される:
- ε は、 何もなしを指示する。
- 等幅~fontで示される記号は、 ~literalによる終端記号である。
- 大文字から始まり, 斜体で示される記号は、 非~終端記号である。
- 小文字から始まり, 斜体で示される記号は、 次に示す正規表現に合致する終端記号である(Perl 5 `PERLRE$r の正規表現~構文を利用)。
- `integer^g
- ~SLASH
-?([1-9][0-9]*|0[Xx][0-9A-Fa-f]+|0[0-7]*)
~SLASH - `decimal^g
- ~SLASH
-?(([0-9]+\.[0-9]*|[0-9]*\.[0-9]+)([Ee][+-]?[0-9]+)?|[0-9]+[Ee][+-]?[0-9]+)
~SLASH - `identifier^g
- ~SLASH
[_-]?[A-Za-z][0-9A-Z_a-z-]*
~SLASH - `string^g
- ~SLASH
"[^"]*"
~SLASH - `whitespace^g
- ~SLASH
[\t\n\r ]+
~SLASH - `comment^g
- ~SLASH
\/\/.*|\/\*(.|\n)*?\*\/
~SLASH - `other^g
- ~SLASH
[^\t\n\r 0-9A-Za-z]
~SLASH
~token化は`~scalar値$たちが成す連列 `UNICODE$r に対し演算する。 ~token化の際には、 最長合致が利用されなければナラナイ。 例えば,入力~textが “`a1^c” であるなら、 それは 1 個の `identifier$g に~token化され, `identifier$g と `integer$g には分離されない。 最長合致が[ 上に挙げた名前を有する終端記号のうち いずれか ]と[ 文法~内の終端記号のうち いずれか ]どちらにも合致し得る場合、 後者の終端記号に~token化されなければナラナイ。 したがって、 入力~text “`long^c” は[ `identifier$g `long^l ではなく, 終端記号 `long^sym ]として~token化され, “`.^c” は[ `other$g ではなく, 終端記号 `.^sym ]として~token化される。 ◎ The tokenizer operates on a sequence of scalar values. 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 other terminal symbols from the grammar, it must be tokenized as the latter. Thus, the input text “long” is tokenized as the terminal symbol long rather than an identifier called "long", and “.” is tokenized as the terminal symbol . rather than an other.
~IDL構文においては、[ 文法~内で利用される[ 等幅~fontで示される終端記号 ], `identifier$g 終端記号に利用される値 ]いずれにおいても,文字大小は~~区別される。 したがって、 例えば 入力~text “`Const^c” は, 終端記号 `const^sym ではなく `identifier$g として~token化され、 `識別子$ `A^l を伴う`~ifc$は, `a^l を伴うそれとは別個になり、 また,`拡張d属性$ `legacyfactoryfunction^x が `LegacyFactoryFunction$x 拡張d属性に認識されることはない。 ◎ The IDL syntax is case sensitive, both for the monospaced 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 terminal symbol const, an interface with identifier "A" is distinct from one named "a", and an extended attribute [legacyfactoryfunction] will not be recognized as the [LegacyFactoryFunction] extended attribute.
`whitespace$g や `comment$g からなる任意~個数の終端記号が、 構文解析される入力~textにおける,他のどの終端記号の合間にも暗黙的に許容される。 それらの `whitespace$g や `comment$g は、 構文解析-時には無視される。 ◎ 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.
次の LL(1) 文法の開始~記号 `Definitions$g が`~IDL片$に合致する: ◎ The following LL(1) grammar, starting with Definitions, matches an IDL fragment:
【 見出しをクリックするとその文法~記号の~~参照元が示される(上の終端記号の表も同様)。 】
【!place holder for the over all grammar table】注記: 非~終端記号 `Other$g は、 `(^sym, `)^sym, `[^sym, `]^sym, `{^sym, `}^sym, `,^sym を除く,任意の 1 個の終端記号に合致する。 ◎ Note: The Other non-terminal matches any single terminal symbol except for (, ), [, ], {, } and ,.
非~終端記号 `ExtendedAttribute$g は,任意の空でない終端記号たちが成す連列に合致するが (丸括弧, 角括弧, 波括弧が対になっていて, かつ `,^sym ~tokenがそのような括弧対の間にのみ現れる限り)、 それらが成すアリな連列のうち一部に限り,この仕様で定義される`拡張d属性$に利用される — これらの拡張d属性に利用される構文については `拡張d属性@#idl-extended-attributes§を見よ。 ◎ 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 § 2.14 Extended attributes for the syntaxes that are used by these extended attributes.
表記規約
この文書では、 次の表記規約/~styleが利用される: ◎ The following typographic conventions are used in this document:
【 “†” が付与されたものは、 この訳による追加的な~style。 】
- 用語の定義: `用語例@#dfn-example-term@ ◎ Defining instances of terms: example term
- この文書で定義される用語への~link: `用語例@#dfn-example-term$ ◎ Links to terms defined in this document or elsewhere: example term
- 他の文書で定義される用語への~link: `用語例@https://example.com#dfn-example-term$ ◎ ↑
- 文法の終端記号(~literal): `sometoken^sym ◎ Grammar terminals: sometoken
- 文法の非~終端記号(先頭は大文字): `ExampleGrammarSymbol^g ◎ Grammar non-terminals: ExampleGrammarNonTerminal
- 文法~記号(正規表現による生成規則, 先頭は小文字): `identifier^g ◎ Grammar symbols: identifier
- ~IDL型: `unsigned long^T ◎ IDL types: unsigned long
-
~IDL~ifc~mb†:
`ExampleIDLMember^M,
- ~IDL値†: `ExampleIDLValue^V
- ~JS~class: `Map^jt ◎ JavaScript classes: Map
- ~JS言語~型: `Object^jt ◎ JavaScript language types: Object
- ~JS~obj~prop†: `property^jp
- ~JS値†: `undefined^jv 【!emu-val】
- ~JS内部[~prop/~method/~slot]†: `ExamplePropertyOrMethodOrSlot^sl
- ~JS抽象-演算†: ExampleAbstractOperation
- ~code片: `a = b + obj.f()^c ◎ Code snippets: a = b + obj.f()
- ~scalar値: `0030^U1 ◎ Scalar values: U+0030 (0)
- 拡張d属性: `ExampleExtendedAttribute^x ◎ Extended attributes: [ExampleExtendedAttribute]
- 注釈文や~algoにおける変数~名: %exampleVariableName ◎ Variable names in prose and algorithms: exampleVariableName.
- 文字列~literal†: `example string literal^l
- ~modelを定義するために利用される仮想の定数~値†: `定数~例^C
-
~IDL構文の非正式な例: ◎ IDL informal syntax examples:
[`extended_attributes^i] interface `identifier^i { /* `interface_members...^mk */ };
(周囲の注釈文の中で論じられている構文は, `<mark>^c 要素で`強調される^mk。) ◎ (Specific parts of the syntax discussed in surrounding prose are highlighted.)
-
~IDL文法~片: ◎ IDL grammar snippets:
- `ExampleGrammarNonTerminal^g
- `OtherNonTerminal^g `sometoken^sym `other$g `AnotherNonTerminal^g ε // nothing
-
規範的でない注記: ◎ Non-normative notes:
注記: これは注記。 ◎ Note: This is a note.
-
規範的でない例: ◎ Non-normative examples:
これは例。 ◎ This is an example.
-
規範的な警告: ◎ Normative warnings:
これは警告。 ◎ This is a warning.
-
~code~block: ◎ Code blocks:
/* これは~IDL~code~block。 ◎ This is an IDL code block. */ [Exposed=Window] interface Example { attribute long something; };
/* これは~JS~code~block。 ◎ This is a JavaScript code block. */ window.onload = function() { window.alert("loaded"); };
この文書の~algoでは、 次の規約が利用される: ◎ The following conventions are used in the algorithms in this document:
- ~JS`完了record$( `Completion Record^en )による包装を外す( `unwrap^en する)ための `"~NOABRUPT" や "~ABRUPT" を接頭する記法@~TC39#sec-returnifabrupt-shorthands$も含め, `ECMA-262$r による`~algo規約$を利用する。 ◎ Algorithms use the conventions of the JavaScript specification, including the ! and ? notation for unwrapping Completion Records.
- ~algoは、[ 値を返す/例外を投出する ]ことと,`完了record$を返すことを交換-可能に扱うこともある。 すなわち、[ ~RET/`~THROW$ を利用する~algo ]は[ `完了record$を返している ]ものと扱われることもあれば、 `完了record$を返すものは[ 値を返している/例外を投出している ]ものと扱われることもある。 同様に,例外を~catchする際に、[ 投出された例外を受け入れる挙動を定義すること ]と[[ `完了record$の `Type^sl ~field ~EQ `throw^i ]かどうか検査すること ]とは、 等価になる。 ◎ Algorithms sometimes treat returning/throwing values and returning Completion Records interchangeably. That is, an algorithm that uses return/throw terminology may be treated as returning a Completion Record, while one that returns a Completion Record may be treated as returning a value or throwing an exception. Similarly, to catch exceptions, defining the behavior to adopt when an exception was thrown and checking if the Completion Record's [[Type]] field is “throw” are equivalent.
- `完了record$は、 ~Web~IDL値などの~JS値でない値も包含できるよう,拡張された値である。 ◎ Completion Records are extended by allowing them to contain values that are not JavaScript values, such as Web IDL values.
適合性
明示的に規範的でないと~markされた節に加え, この仕様におけるすべての図式, 例, 注記は規範的ではない。 他のすべては規範的である。 ◎ Everything in this specification is normative except for diagrams, examples, notes and sections marked as being informative.
この仕様は、 `Infra Standard^cite `INFRA$r に依存する。 ◎ This specification depends on the Infra Standard. [INFRA]
この仕様への適合性の対象として、 次に挙げる類別が定義される — 以下に現れる “~~必須の判定基準” は、[ この仕様における[ “〜ナラナイ” / “モノトスル” / “要求される” ]~levelの判定基準 ]の総称である: ◎ The following conformance classes are defined by this specification:
- `適合~IDL片たちが成す集合@ ◎ conforming set of IDL fragments
- `~IDL片$たちが成す集合は、 全体として[ ~IDL片に適用される~~必須の判定基準 ]をすべて満たすならば, `適合~IDL片たちが成す集合$であると見なされる。 ◎ 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
- ~UAは、[ 自身が~supportする すべての言語束縛~用の実装に適用される~~必須の判定基準 ]をすべて満たすならば, `適合~IDL片たちが成す集合$に対する`適合~実装$であると見なされる。 ◎ 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.
- `適合~JS実装@ ◎ conforming JavaScript implementation
- ~UAは、[ ~JS言語束縛~用の実装に適用される~~必須の判定基準 ]をすべて満たすならば, `適合~IDL片たちが成す集合$に対する`適合~JS実装$であると見なされる。 ◎ A user agent is considered to be a conforming JavaScript 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 JavaScript language binding.