웹 IDL

1. 소개

이 섹션은 참고용입니다.

이 표준은 웹 브라우저에 구현될 인터페이스를 기술하는 데 사용할 수 있는 인터페이스 정의 언어, 웹 IDL을 정의합니다. 웹 IDL은 웹 플랫폼의 일반적인 스크립트 객체의 동작을 보다 쉽게 명세할 수 있도록 하는 다양한 기능을 가진 IDL 변형입니다. 웹 IDL로 기술된 인터페이스가 자바스크립트 실행 환경 내의 구조와 어떻게 대응되는지도 이곳에서 자세히 설명합니다.

구체적으로, 웹 IDL은 웹 플랫폼 객체의 표면 API를 명세하는 구문과, 그 API가 자바스크립트 구조로 어떻게 나타나는지 상세히 기술하는 자바스크립트 바인딩을 제공합니다. 이로 인해 글로벌 속성 설치, 숫자 입력 처리, 반복 동작 노출과 같은 일반적인 작업들이 웹 플랫폼 명세서 전체에서 일관성을 유지할 수 있습니다. 이러한 명세서들은 웹 IDL로 인터페이스를 기술하고, 프로즈로 API 고유의 세부사항을 명세합니다.

"자바스크립트"라는 용어는 공식 용어 ECMAScript가 아닌 ECMA-262를 의미하며, 자바스크립트라는 명칭이 더 널리 알려져 있기 때문에 사용합니다.

2. 인터페이스 정의 언어

이 섹션에서는 웹 IDL이라는 언어를 설명합니다. 이는 웹 플랫폼의 API를 정의하는 인터페이스를 명세하는 데 사용할 수 있습니다. 웹 API를 정의하는 명세서는 하나 이상의 IDL 프래그먼트를 포함하여, 해당 명세서에서 정의된 API의 인터페이스(객체가 가질 수 있는 상태와 동작)를 기술합니다. IDL 프래그먼트는 Definitions 문법 기호에 일치하는 일련의 정의입니다. 구현체가 지원하는 IDL 프래그먼트 집합은 순서가 없습니다. 전체 문법과 표기법 설명은 IDL 문법을 참고하세요.

IDL 프래그먼트에 등장할 수 있는 다양한 정의의 종류는 다음과 같습니다: 인터페이스, 부분 인터페이스 정의, 인터페이스 믹스인, 부분 믹스인 정의, 콜백 함수, 콜백 인터페이스, 네임스페이스, 부분 네임스페이스 정의, 딕셔너리, 부분 딕셔너리 정의, 타입 정의(typedef) 및 includes 문입니다. 모든 종류는 아래 섹션에서 정의됩니다.

각 정의 (Definition에 일치) 앞에는 확장 속성 목록(ExtendedAttributeList에 일치)이 올 수 있으며, 이는 해당 정의가 언어 바인딩에서 어떻게 처리될지 제어합니다. 이 명세서에서 정의된 언어 바인딩에 독립적인 확장 속성은 § 2.14 확장 속성에서, 자바스크립트 언어 바인딩에 특화된 것은 § 3.3 확장 속성에서 설명합니다.

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

Definitions ::
    ExtendedAttributeList Definition Definitions
    ε

Definition ::
    CallbackOrInterfaceOrMixin
    Namespace
    Partial
    Dictionary
    Enum
    Typedef
    IncludesStatement

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

2.1. 이름

모든 인터페이스, 부분 인터페이스 정의, 네임스페이스, 부분 네임스페이스 정의, 딕셔너리, 부분 딕셔너리 정의, 열거형, 콜백 함수, 콜백 인터페이스 및 타입 정의(typedef) (이들을 통틀어 이름이 있는 정의이라 함) 그리고 모든 상수, 속성, 딕셔너리 멤버는 식별자를 가지며, 일부 연산도 마찬가지입니다. 식별자는 선언 내 어딘가에 등장하는 identifier 토큰에 의해 결정됩니다:

• 이름이 있는 정의의 경우, identifier 토큰이 interface, namespace, dictionary, enum 또는 callback 키워드 바로 뒤에 나오며, 이 토큰이 해당 정의의 식별자를 결정합니다.

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

• 속성, 타입 정의, 딕셔너리 멤버의 경우, 선언 마지막에 세미콜론 앞에 위치한 identifier 토큰이 식별자를 결정합니다.

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

• 상수의 경우, 등호 앞에 위치한 identifier 토큰이 식별자를 결정합니다.

  const type constant_identifier = 42;

• 연산의 경우, 반환 타입 뒤, 여는 괄호 앞에 위치한 identifier 토큰(즉, OptionalOperationName 문법 기호의 일부로 매칭되는 토큰)이 연산의 식별자를 결정합니다. 만약 해당 identifier 토큰이 없다면, 연산은 식별자를 가지지 않습니다.

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

참고: 연산은 getter, setter와 같은 특수 연산을 선언할 때 식별자가 없을 수 있습니다.

이러한 모든 구조에서, 식별자는 identifier 토큰 값에서 앞에 오는 U+005F (_)를 제거한 값입니다.

참고: 앞에 오는 U+005F (_)는 식별자가 예약어처럼 보이지 않게 하기 위해 사용되며, 예를 들어 "interface"라는 이름의 인터페이스를 정의할 수 있습니다. 식별자를 해제할 때는 앞의 U+005F (_)를 삭제합니다.

연산의 인자(argument)는 더 넓은 범위의 식별자 집합을 가질 수 있습니다. 연산 선언에서 인자의 식별자는 타입 뒤에 바로 명시되며, identifier 토큰 또는 ArgumentNameKeyword 심볼에 매칭되는 키워드 중 하나로 지정됩니다. 이런 키워드가 사용될 경우, 앞에 밑줄로 이스케이프할 필요가 없습니다.

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

ArgumentNameKeyword ::
    attribute
    callback
    const
    constructor
    deleter
    dictionary
    enum
    getter
    includes
    inherit
    interface
    iterable
    maplike
    mixin
    namespace
    partial
    readonly
    required
    setlike
    setter
    static
    stringifier
    typedef
    unrestricted

identifier 토큰이 사용된 경우, 연산 인자의 식별자는 해당 토큰 값에서 앞의 U+005F (_)를 제거한 값입니다. 만약 ArgumentNameKeyword 키워드 토큰이 사용된다면, 연산 인자의 식별자는 그 토큰 자체입니다.

위에 언급된 IDL 구조(연산 인자 제외)의 식별자는 "constructor", "toString"이거나 U+005F (_)로 시작해서는 안 됩니다. 이런 것들은 예약 식별자라 부릅니다.

"toJSON" 식별자는 예약 식별자는 아니지만, 정상 연산에서만 객체를 JSON 타입으로 변환하는 목적으로 사용해야 하며, § 2.5.3.1 toJSON에서 설명합니다.

참고: 특정 구조에 대한 식별자 명명 제한은 이후 섹션에서 추가될 수 있습니다.

주어진 구현체가 지원하는 IDL 프래그먼트 집합 내에서, 모든 인터페이스, 네임스페이스, 딕셔너리, 열거형, 콜백 함수, 콜백 인터페이스인터페이스, 타입 정의의 식별자는 다른 인터페이스, 네임스페이스, 딕셔너리, 열거형, 콜백 함수, 콜백 인터페이스, 타입 정의의 식별자와 같아서는 안 됩니다.

하나의 IDL 프래그먼트 내에서는, 정의에 대한 참조가 참조된 정의의 선언 뒤에 등장하지 않아도 됩니다. 또한 IDL 프래그먼트 간에도 참조할 수 있습니다.

[Exposed=Window]
interface B : A {
  undefined f(SequenceOfLongs x);
};

[Exposed=Window]
interface A {
};

typedef sequence<long> SequenceOfLongs;

// 타입 정의 식별자: "number"
typedef double number;

// 인터페이스 식별자: "System"
[Exposed=Window]
interface System {

  // 연산 식별자:          "createObject"
  // 연산 인자 식별자: "interface"
  object createObject(DOMString _interface);

  // 연산 인자 식별자: "interface"
  sequence<object> getObjects(DOMString interface);

  // 연산에는 식별자가 없음; getter 선언임.
  getter DOMString (DOMString keyName);
};

// 인터페이스 식별자: "TextField"
[Exposed=Window]
interface TextField {

  // 속성 식별자: "const"
  attribute boolean _const;

  // 속성 식별자: "value"
  attribute DOMString? _value;
};

2.2. 인터페이스

IDL 프래그먼트는 객체 지향 시스템을 기술하는 데 사용됩니다. 이러한 시스템에서 객체란 정체성을 가지고 있으며, 상태와 행동을 캡슐화한 엔티티입니다. 인터페이스는 (interface InterfaceRest에 일치) 해당 인터페이스를 구현하는 객체가 노출하는 상태와 행동을 선언하는 정의입니다.

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

인터페이스는 인터페이스 멤버 (InterfaceMembers에 일치)의 집합을 명세합니다. 인터페이스 선언 중괄호 사이에 등장하는 멤버들이 이에 해당합니다.

웹 IDL의 인터페이스는 해당 인터페이스를 구현하는 객체가 어떻게 동작하는지 기술합니다. 객체 지향 언어 바인딩에서는, 특정 IDL 인터페이스를 구현하는 객체가 객체의 상태를 검사하고 수정하며, 인터페이스가 기술하는 동작을 호출할 수 있도록 제공하는 것이 기대됩니다.

인터페이스는 다른 인터페이스를 상속하도록 정의할 수 있습니다. 만약 인터페이스 식별자 뒤에 U+003A (:)와 식별자가 오면, 해당 식별자가 상속받는 인터페이스를 나타냅니다. 어떤 객체가 다른 인터페이스를 상속한 인터페이스를 구현하면, 그 객체는 상속받은 인터페이스도 구현하게 됩니다. 즉, 객체는 상속된 인터페이스의 멤버도 가지게 됩니다.

interface identifier : identifier_of_inherited_interface {
  /* interface_members... */
};

멤버의 등장 순서는 자바스크립트 바인딩에서 프로퍼티 열거에 영향을 미칩니다.

인터페이스는 상속받은 인터페이스의 멤버와 같은 이름의 인터페이스 멤버를 명시할 수도 있습니다. 파생 인터페이스를 구현하는 객체는 파생 인터페이스의 멤버를 노출합니다. 오버라이드된 멤버를 객체에서 접근할 수 있는지는 언어 바인딩에 따라 다릅니다.

[Exposed=Window]
interface A {
  undefined f();
  undefined g();
};

[Exposed=Window]
interface B : A {
  undefined f();
  undefined g(DOMString x);
};

[Object.prototype: Object 프로토타입 객체]
     ↑
[A.prototype: A의 인터페이스 프로토타입 객체]
     ↑
[B.prototype: B의 인터페이스 프로토타입 객체]
     ↑
[instanceOfB]

주어진 인터페이스 A의 상속 인터페이스들은 A가 직접 또는 간접적으로 상속하는 모든 인터페이스의 집합입니다. A가 다른 인터페이스를 상속하지 않으면 집합은 비어 있습니다. 그렇지 않으면, 집합에는 A가 상속하는 인터페이스 B와 B의 상속 인터페이스들이 포함됩니다.

인터페이스의 상속 계층에 순환(cycle)이 있어서는 안 됩니다. 즉, 인터페이스 A가 자기 자신을 상속하거나, B에서 A를 상속하는 등 반복적으로 상속할 수 없습니다.

일반적인 인터페이스의 다중 상속은 지원하지 않으며, 객체도 임의의 인터페이스 집합을 구현할 수 없습니다. 객체는 하나의 주어진 인터페이스 A를 구현하도록 정의되며, 이는 A의 상속 인터페이스들도 구현함을 의미합니다. 추가로, includes 문을 사용하여 인터페이스 A를 구현하는 객체가 인터페이스 믹스인 멤버도 항상 포함하도록 정의할 수 있습니다. A가 include하는 인터페이스 믹스인의 멤버를 포함합니다.

각 인터페이스 멤버는 확장 속성 리스트(ExtendedAttributeList에 일치)가 앞에 올 수 있으며, 이는 해당 멤버가 언어 바인딩에서 어떻게 처리될지 제어합니다.

[extended_attributes]
interface identifier {

  [extended_attributes]
  const type constant_identifier = 42;

  [extended_attributes]
  attribute type identifier;

  [extended_attributes]
  return_type identifier(/* arguments... */);
};

인터페이스에 대한 IDL은 부분 인터페이스 정의(partial interface PartialInterfaceRest에 일치)를 사용하여 여러 부분으로 나눌 수 있습니다. 부분 인터페이스 정의의 식별자는 반드시 인터페이스 정의의 식별자와 같아야 합니다. 각 부분 인터페이스에 등장하는 모든 멤버는 실제 인터페이스의 멤버로 간주합니다.

interface SomeInterface {
  /* interface_members... */
};

partial interface SomeInterface {
  /* interface_members... */
};

참고: 부분 인터페이스 정의는 명세 편집 시, 하나의 인터페이스 정의를 여러 문서 또는 여러 섹션에 나눠서 기술하는 데 도움을 주기 위한 것입니다.

인터페이스 정의와 그 부분 인터페이스 정의의 등장 순서는 중요하지 않습니다.

참고: 부분 인터페이스 정의는 인터페이스가 다른 인터페이스를 상속하도록 지정할 수 없습니다. 상속은 원래의 인터페이스 정의에서 지정해야 합니다.

적용되는 언어 바인딩이 인터페이스가 해당 언어의 구조와 어떻게 대응되는지 결정합니다.

다음 확장 속성들이 인터페이스에 적용될 수 있습니다: [CrossOriginIsolated], [Exposed], [Global], [LegacyFactoryFunction], [LegacyNoInterfaceObject], [LegacyOverrideBuiltIns], [LegacyWindowAlias], [SecureContext].

다음 확장 속성들은 부분 인터페이스에 적용될 수 있습니다: [CrossOriginIsolated], [Exposed], [LegacyOverrideBuiltIns], [SecureContext].

인터페이스는 반드시 [Exposed] 확장 속성으로 주석 처리해야 합니다.

CallbackOrInterfaceOrMixin ::
    callback CallbackRestOrInterface
    interface InterfaceOrMixin

InterfaceOrMixin ::
    InterfaceRest
    MixinRest

InterfaceRest ::
    identifier Inheritance { InterfaceMembers } ;

Partial ::
    partial PartialDefinition

PartialDefinition ::
    interface PartialInterfaceOrPartialMixin
    PartialDictionary
    Namespace

PartialInterfaceOrPartialMixin ::
    PartialInterfaceRest
    MixinRest

PartialInterfaceRest ::
    identifier { PartialInterfaceMembers } ;

InterfaceMembers ::
    ExtendedAttributeList InterfaceMember InterfaceMembers
    ε

InterfaceMember ::
    PartialInterfaceMember
    Constructor

PartialInterfaceMembers ::
    ExtendedAttributeList PartialInterfaceMember PartialInterfaceMembers
    ε

PartialInterfaceMember ::
    Const
    Operation
    Stringifier
    StaticMember
    Iterable
    AsyncIterable
    ReadOnlyMember
    ReadWriteAttribute
    ReadWriteMaplike
    ReadWriteSetlike
    InheritAttribute

Inheritance ::
    : identifier
    ε

[Exposed=Window]
interface Animal {
  attribute DOMString name;
};

[Exposed=Window]
interface Human : Animal {
  attribute Dog? pet;
};

[Exposed=Window]
interface Dog : Animal {
  attribute Human? owner;
};

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

var node = getNode();                                // Node 인스턴스 얻기

var listener = {
  handleEvent: function(event) {
    // ...
  }
};
node.addEventListener("click", listener);            // 동작함

node.addEventListener("click", function() { ... });  // 이것도 동작함

var node = getNode();  // Node 인스턴스 얻기

var newNode = {
  nodeName: "span",
  parentNode: null,
  appendChild: function(newchild) {
    // ...
  },
  addEventListener: function(type, listener) {
    // ...
  }
};
node.appendChild(newNode);  // TypeError 예외 발생

2.3. 인터페이스 믹스인

인터페이스 믹스인은 (interface MixinRest에 일치) 하나 이상의 인터페이스에서 include하여 객체가 노출할 수 있는 상태와 행동을 선언합니다. 인터페이스에서 include한 인터페이스 믹스인을 구현하는 객체에 의해 노출됩니다.

interface mixin identifier {
  /* mixin_members... */
};

참고: 인터페이스 믹스인은 부분 인터페이스와 마찬가지로, 명세 편집의 편의를 위해 사용되어 일관된 기능 집합을 묶고, 여러 인터페이스(문서 간 포함 가능)에 포함할 수 있게 합니다. 언어 바인딩을 통해 직접 노출되도록 의도된 것이 아닙니다. § 2.3.1 믹스인 및 부분 사용에서 부분 인터페이스, 인터페이스 믹스인, 부분 인터페이스 믹스인 중 어느 것을 선택할지 설명합니다.

인터페이스 믹스인은 인터페이스 믹스인 멤버 (MixinMembers에 일치) 집합을 명세합니다. 즉, 상수, 일반 연산, 일반 속성, 문자열 변환자들이 해당 인터페이스 믹스인 선언의 중괄호 사이에 선언됩니다.

이러한 상수 , 일반 연산 , 일반 속성 , 문자열 변환자 는 객체가 구현할 수 있는 동작을 기술하며, 마치 이를 포함하는 인터페이스 에 직접 명세한 것처럼 동작합니다.

정적 속성, 정적 연산, 특수 연산, 이터러블, 비동기 이터러블, maplike, setlike 선언은 인터페이스 믹스인 선언에 포함될 수 없습니다.

인터페이스와 마찬가지로, 인터페이스 믹스인의 IDL도 부분 인터페이스 믹스인 정의(partial interface MixinRest에 일치)를 이용해 여러 부분으로 나눌 수 있습니다. 부분 인터페이스 믹스인 정의의 식별자는 해당 인터페이스 믹스인 정의의 식별자와 같아야 합니다. 각 부분 인터페이스 믹스인에 등장하는 모든 멤버는 실제 인터페이스 믹스인의 멤버로 간주되고, 인터페이스가 include하는 인터페이스 믹스인을 통해 해당 인터페이스의 멤버로도 간주됩니다.

interface mixin SomeMixin {
  /* mixin_members... */
};

partial interface mixin SomeMixin {
  /* mixin_members... */
};

멤버의 등장 순서는 자바스크립트 바인딩에서 프로퍼티 열거에 영향을 줍니다.

인터페이스나 딕셔너리와 달리, 인터페이스 믹스인은 타입을 생성하지 않습니다.

이 명세에서 정의된 확장 속성 중, [CrossOriginIsolated], [Exposed], [SecureContext] 만 인터페이스 믹스인에 적용됩니다.

includes 문은 (IncludesStatement에 일치) 모든 인터페이스 I (첫 번째 식별자로 식별됨)를 구현하는 객체가 멤버를 인터페이스 믹스인 M (두 번째 식별자로 식별됨)의 멤버를 추가로 포함해야 함을 선언하는 정의입니다. 인터페이스 I는 include 인터페이스 믹스인 M을 포함한다고 합니다.

interface_identifier includes mixin_identifier;

첫 번째 식별자는 인터페이스 I를 참조해야 하며, 두 번째 식별자는 인터페이스 믹스인 M을 참조해야 합니다.

M의 각 멤버는 인터페이스 I, J, K 등 include하는 모든 인터페이스의 멤버로 간주됩니다. 즉, M의 멤버 m에 대해 I는 멤버 m_I, J는 멤버 m_J, K는 멤버 m_K를 갖게 됩니다. 호스트 인터페이스란 m_I, m_J, m_K의 각각의 I, J, K를 말합니다.

참고: 자바스크립트에서는, 인터페이스 믹스인 멤버로 선언된 일반 연산이 내장 함수 객체 값의 데이터 속성으로 노출될 때, 연결된 인터페이스가 M을 포함하는 각 인터페이스 프로토타입 객체마다 별도 내장 함수 객체가 생성됩니다. 속성도 마찬가지로 접근자 속성의 getter와 setter가 각각 별도 내장 함수 객체가 됩니다.

includes 문의 등장 순서는 호스트 인터페이스에서 인터페이스 믹스인이 포함되는 순서에 영향을 줍니다.

멤버 순서는 명확히 규정되어 있지 않으며, 특히 인터페이스 믹스인이 별도 문서에 정의될 때 더욱 그렇습니다. issue #432에서 논의되고 있습니다.

이 명세에서 정의된 확장 속성 중 includes 문에 적용 가능한 것은 없습니다.

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

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

Entry includes Observable;

var e = getEntry();          // Entry 인스턴스 얻기
typeof e.addEventListener;   // "function"으로 평가됨

CallbackOrInterfaceOrMixin ::
    callback CallbackRestOrInterface
    interface InterfaceOrMixin

InterfaceOrMixin ::
    InterfaceRest
    MixinRest

Partial ::
    partial PartialDefinition

PartialDefinition ::
    interface PartialInterfaceOrPartialMixin
    PartialDictionary
    Namespace

MixinRest ::
    mixin identifier { MixinMembers } ;

MixinMembers ::
    ExtendedAttributeList MixinMember MixinMembers
    ε

MixinMember ::
    Const
    RegularOperation
    Stringifier
    OptionalReadOnly AttributeRest

IncludesStatement ::
    identifier includes identifier ;

2.3.1. 믹스인 및 부분 사용

이 섹션은 참고용입니다.

인터페이스 믹스인은 속성, 상수, 연산을 여러 인터페이스에 공유할 수 있게 해줍니다. 만약 하나의 인터페이스만 확장하려는 경우라면 부분 인터페이스 사용을 고려할 수 있습니다.

예를 들면, 다음과 같이 하지 말고:

interface mixin WindowSessionStorage {
  readonly attribute Storage sessionStorage;
};
Window includes WindowSessionStorage;

이렇게 하세요:

partial interface Window {
  readonly attribute Storage sessionStorage;
};

또한, 다른 명세에서 노출하는 인터페이스 믹스인을 확장하여 window와 worker 등 여러 컨텍스트에 속성, 상수, 연산을 노출하는 등 공통적인 활용 사례를 타겟할 수도 있습니다.

예를 들어, 흔하지만 장황한 방식 대신:

interface mixin GlobalCrypto {
  readonly attribute Crypto crypto;
};

Window includes GlobalCrypto;
WorkerGlobalScope includes GlobalCrypto;

WindowOrWorkerGlobalScope 인터페이스 믹스인을 부분 인터페이스 믹스인으로 확장할 수 있습니다:

partial interface mixin WindowOrWorkerGlobalScope {
  readonly attribute Crypto crypto;
};

2.4. 콜백 인터페이스

콜백 인터페이스는 정의로, callback interface identifier { CallbackInterfaceMembers } ;에 일치합니다. § 2.12 인터페이스를 구현하는 객체에서 설명한 대로, 어떤 객체든 구현할 수 있습니다.

참고: 콜백 인터페이스는 인터페이스가 아닙니다. 명칭과 문법은 표준의 이전 버전에서 유래된 것으로, 당시에는 개념적으로 더 많은 공통점이 있었습니다.

콜백 인터페이스는 콜백 인터페이스 멤버 (CallbackInterfaceMembers에 일치)의 집합을 명세합니다. 이들은 인터페이스 선언의 중괄호 사이에 등장하는 멤버입니다.

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

참고: 유사한 명칭의 콜백 함수 정의도 참고하세요.

콜백 인터페이스는 정확히 하나의 일반 연산을 정의해야 합니다.

콜백 인터페이스가 상수를 선언하는 경우 반드시 [Exposed] 확장 속성으로 주석 처리해야 합니다.

CallbackRestOrInterface ::
    CallbackRest
    interface identifier { CallbackInterfaceMembers } ;

CallbackInterfaceMembers ::
    ExtendedAttributeList CallbackInterfaceMember CallbackInterfaceMembers
    ε

CallbackInterfaceMember ::
    Const
    RegularOperation

2.5. 멤버

인터페이스, 인터페이스 믹스인, 네임스페이스는 중괄호 안에 등장하는 멤버(각각 InterfaceMembers, MixinMembers, NamespaceMembers에 일치)을 명세합니다. 멤버에는 상수, 속성, 연산, 기타 선언이 있습니다. 속성은 해당 인터페이스, 인터페이스 믹스인, 네임스페이스를 구현하는 객체가 노출하는 상태를 설명하며, 연산은 객체에서 호출할 수 있는 동작을 설명합니다. 상수는 시스템 내 객체 사용자에게 편의를 제공하기 위한 이름 있는 상수 값을 선언합니다.

여러 멤버에 대해 정의되는 생성자 단계, getter 단계, setter 단계, 메서드 단계는 해당 인터페이스 또는 인터페이스 믹스인 위에 정의된 멤버에서 this 값을 사용할 수 있습니다. 이는 멤버가 선언된 인터페이스 타입, 혹은 멤버가 선언된 인터페이스 믹스인을 include한 타입의 IDL 값입니다.

setter 단계에서는 지정된 값도 사용할 수 있는데, 이는 해당 속성이 선언된 타입의 IDL 값입니다.

인터페이스, 인터페이스 믹스인, 콜백 인터페이스, 네임스페이스는 각각 지원하는 멤버의 종류가 다르며, § 2.2 인터페이스, § 2.3 인터페이스 믹스인, § 2.4 콜백 인터페이스, § 2.6 네임스페이스에서 설명합니다. 아래 표는 이를 요약한 참고용 표입니다:

2.5.1. 상수

상수는 (Const에 일치) 이름에 상수값을 바인딩하는 선언입니다. 상수는 인터페이스와 콜백 인터페이스에 등장할 수 있습니다.

상수는 과거에 주로 열거형 스타일로 명명된 정수 코드를 정의하는 데 사용되었습니다. 웹 플랫폼은 문자열 사용으로 이 패턴에서 벗어나고 있습니다. 이 기능을 사용하려는 편집자는 진행하기 전에 이슈를 등록하여 논의할 것을 강력히 권고합니다.

const type constant_identifier = 42;

상수의 식별자는 동일한 인터페이스 멤버 또는 콜백 인터페이스 멤버의 식별자와 같아서는 안 됩니다(동일한 인터페이스나 콜백 인터페이스에 정의된). 또한 "length", "name", "prototype"이어서는 안 됩니다.

참고: 이 세 이름은 자바스크립트 바인딩에서 인터페이스 객체에 정의된 프로퍼티 이름입니다.

상수의 타입(ConstType에 일치)은 원시 타입이어야 하며, 그 외 타입은 허용되지 않습니다. 식별자가 사용되는 경우, 해당 식별자는 원시 타입인 타입 정의를 참조해야 합니다.

상수 선언의 ConstValue 부분은 상수의 값을 나타내며, 두 개의 불리언 리터럴 토큰(true, false), integer 토큰, decimal 토큰, 또는 세 가지 특수 부동소수점 상수값(-Infinity, Infinity, NaN) 중 하나일 수 있습니다.

참고: 이 값들은(문자열, 빈 시퀀스 포함) 딕셔너리 멤버의 기본값이나 옵션 인자 기본값으로도 사용할 수 있습니다. 단, 문자열, 빈 시퀀스 [], 기본 딕셔너리 {}는 상수의 값으로 사용할 수 없습니다.

불리언 리터럴 토큰 true와 false의 값은 IDL boolean 타입의 true와 false입니다.

integer 토큰의 타입은 사용되는 상수, 딕셔너리 멤버, 옵션 인자의 타입과 동일합니다. 해당 토큰의 값은 § 2.13 타입에서 주어진 타입의 유효 범위를 벗어나면 안 됩니다.

상수값이 Infinity, -Infinity, NaN로 지정된 경우, 상수, 딕셔너리 멤버, 옵션 인자의 타입에 따라 IEEE 754 단정밀도 또는 배정밀도 부동소수점 숫자가 됩니다:

타입 unrestricted float, 상수값 Infinity

값은 IEEE 754 단정밀도 양의 무한대입니다.

타입 unrestricted double, 상수값 Infinity

값은 IEEE 754 배정밀도 양의 무한대입니다.

타입 unrestricted float, 상수값 -Infinity

값은 IEEE 754 단정밀도 음의 무한대입니다.

타입 unrestricted double, 상수값 -Infinity

값은 IEEE 754 배정밀도 음의 무한대입니다.

타입 unrestricted float, 상수값 NaN

값은 비트 패턴 0x7fc00000의 IEEE 754 단정밀도 NaN입니다.

타입 unrestricted double, 상수값 NaN

값은 비트 패턴 0x7ff8000000000000의 IEEE 754 배정밀도 NaN입니다.

decimal 토큰의 타입은 사용되는 상수, 딕셔너리 멤버, 옵션 인자의 타입과 동일합니다. 해당 토큰의 값은 § 2.13 타입에서 주어진 타입의 유효 범위를 벗어나면 안 됩니다. 또한, Infinity, -Infinity, NaN은 float나 double 타입의 값으로 사용할 수 없습니다.

null 토큰의 값은 null 값이며, 널 허용 타입의 멤버입니다. null 토큰의 타입은 해당 상수, 딕셔너리 멤버, 옵션 인자의 타입과 동일합니다.

상수에 할당된 값의 타입 VT와 상수, 딕셔너리 멤버, 옵션 인자 자체의 타입 DT는 호환되어야 하며, DT와 VT가 동일하거나, DT가 널 허용 타입이고 내부 타입이 VT인 경우에 해당합니다.

상수는 해당 인터페이스 또는 콜백 인터페이스의 특정 인스턴스와 연결되지 않습니다. 인스턴스에서 상수가 노출되는지 여부는 언어 바인딩에 따라 다릅니다.

[Exposed=Window]
interface A {
  const short rambaldi = 47;
};

상수에 적용 가능한 확장 속성은 다음과 같습니다: [CrossOriginIsolated], [Exposed], [SecureContext].

Const ::
    const ConstType identifier = ConstValue ;

ConstValue ::
    BooleanLiteral
    FloatLiteral
    integer

BooleanLiteral ::
    true
    false

FloatLiteral ::
    decimal
    -Infinity
    Infinity
    NaN

ConstType ::
    PrimitiveType
    identifier

[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. 속성

속성은 인터페이스 멤버 또는 네임스페이스 멤버로, (inherit AttributeRest, static OptionalReadOnly AttributeRest, stringifier OptionalReadOnly AttributeRest, OptionalReadOnly AttributeRest, 또는 AttributeRest에 일치) 주어진 타입과 식별자를 가진 데이터 필드를 선언하며, 해당 값은 조회되거나(일부 경우) 변경될 수 있습니다. 속성에는 두 가지 종류가 있습니다:

1. 일반 속성은 해당 인터페이스를 구현하는 객체가 지정된 식별자의 데이터 필드 멤버를 갖도록 선언합니다.

   interface interface_identifier {
     attribute type identifier;
   };
   

2. 정적 속성은 인터페이스를 구현하는 특정 객체와 관련되지 않은 속성을 선언할 때 사용합니다.

   interface interface_identifier {
     static attribute type identifier;
   };
   

속성에 static 키워드가 없으면 일반 속성을 선언한 것이고, 있으면 정적 속성을 선언한 것입니다. 참고로 인터페이스 멤버 외에도, 읽기 전용 일반 속성은 네임스페이스 멤버가 될 수도 있습니다.

속성 attr의 getter 단계는 “attr getter 단계는 다음과 같다:”(목록) 또는 “attr getter 단계는 다음을 수행한다”(인라인 설명)와 같은 텍스트로 소개해야 합니다.

속성 attr의 setter 단계는 “attr setter 단계는 다음과 같다:”(목록) 또는 “attr setter 단계는 다음을 수행한다”(인라인 설명)와 같은 텍스트로 소개해야 합니다.

참고: getter 단계를 정의할 때는 this에 암묵적으로 접근할 수 있습니다. setter 단계를 정의할 때는 this와 지정된 값에 암묵적으로 접근할 수 있습니다.

속성의 식별자는 동일한 인터페이스에 정의된 다른 인터페이스 멤버의 식별자와 같아서는 안 됩니다. 정적 속성의 식별자는 "prototype"이면 안 됩니다.

속성의 타입은 attribute 키워드 뒤에 등장하는 타입(Type에 일치)으로 정해집니다. 만약 Type이 식별자거나 식별자 다음에 ?가 붙은 경우, 해당 식별자는 인터페이스, 열거형, 콜백 함수, 콜백 인터페이스, 타입 정의를 식별해야 합니다.

타입 정의를 해석한 후, 속성의 타입은 다음 타입의 널 허용 또는 비허용 버전이 되어서는 안 됩니다:

• 시퀀스 타입

• 비동기 시퀀스 타입

• 딕셔너리 타입

• 레코드 타입

• 유니온 타입에 널 허용 또는 비허용 시퀀스 타입, 딕셔너리, 레코드가 평탄화된 멤버 타입 중 하나로 포함된 경우

속성은 읽기 전용이며, readonly 키워드가 attribute 키워드 앞에 있으면 그렇게 됩니다. 읽기 전용 속성이 정의된 인터페이스를 구현하는 객체는 해당 속성에 값을 할당할 수 없습니다. 언어 바인딩마다 할당이 단순히 금지되는지, 무시되는지, 예외가 발생하는지 다를 수 있습니다.

interface interface_identifier {
  readonly attribute type identifier;
};

타입이 프라미스 타입인 속성은 반드시 읽기 전용이어야 하며, 또한 [LegacyLenientSetter], [PutForwards], [Replaceable], [SameObject] 확장 속성을 가질 수 없습니다.

읽기 전용이 아닌 일반 속성은 상위 인터페이스에서 getter를 상속받도록 선언할 수 있습니다. 이를 통해 상위 인터페이스의 읽기 전용 속성을 파생 인터페이스에서 쓰기 가능하게 만들 수 있습니다. 속성이 getter를 상속하려면 선언에 inherit이 포함되어야 합니다. getter를 상속받는 속성은 가장 가까운 상위 인터페이스에서 동일한 식별자를 가진 속성입니다. getter를 상속받는 속성과 상속하는 속성의 타입은 같아야 합니다.

참고: 문법상 inherit는 읽기 전용 속성이나 정적 속성에 사용할 수 없습니다.

[Exposed=Window]
interface Ancestor {
  readonly attribute TheType theIdentifier;
};

[Exposed=Window]
interface Derived : Ancestor {
  inherit attribute TheType theIdentifier;
};

stringifier 키워드가 일반 속성 선언에 사용되면, 해당 인터페이스를 구현하는 객체가 해당 속성 값으로 문자열 변환됨을 의미합니다. 자세한 내용은 § 2.5.5 문자열 변환자를 참조하세요.

interface interface_identifier {
  stringifier attribute DOMString identifier;
};

다음 확장 속성은 일반 및 정적 속성에 적용 가능합니다: [CrossOriginIsolated], [Exposed], [SameObject], [SecureContext].

다음 확장 속성은 일반 속성에만 적용됩니다: [LegacyLenientSetter], [LegacyLenientThis], [PutForwards], [Replaceable], [LegacyUnforgeable].

ReadOnlyMember ::
    readonly ReadOnlyMemberRest

ReadOnlyMemberRest ::
    AttributeRest
    MaplikeRest
    SetlikeRest

ReadWriteAttribute ::
    AttributeRest

InheritAttribute ::
    inherit AttributeRest

AttributeRest ::
    attribute TypeWithExtendedAttributes AttributeName ;

AttributeName ::
    AttributeNameKeyword
    identifier

AttributeNameKeyword ::
    required

OptionalReadOnly ::
    readonly
    ε

[Exposed=Window]
interface Animal {

  // 임의의 문자열 값으로 설정 가능한 단순 속성.
  readonly attribute DOMString name;

  // 값을 할당할 수 있는 속성.
  attribute unsigned short age;
};

[Exposed=Window]
interface Person : Animal {

  // Animal에서 getter 동작을 상속받으며, Person 설명에서 별도 명시 필요 없음.
  inherit attribute DOMString name;
};

2.5.3. 연산

연산은 인터페이스 멤버, 콜백 인터페이스 멤버, 네임스페이스 멤버 (static RegularOperation, stringifier, RegularOperation 또는 SpecialOperation에 일치) 해당 인터페이스를 구현하는 객체에서 호출할 수 있는 동작을 정의합니다. 연산에는 세 가지 종류가 있습니다:

1. 일반 연산은 해당 인터페이스를 구현하는 객체가 지정된 식별자의 메서드를 갖도록 선언합니다.

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

2. 특수 연산은 객체 인덱싱, 문자열 변환 등 특별한 동작을 구현하는 객체에 선언할 때 사용합니다.

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

3. 정적 연산은 인터페이스를 구현하는 특정 객체와 관련되지 않은 연산을 선언할 때 사용합니다.

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

연산에 식별자가 있고 static 키워드가 없으면 일반 연산을 선언한 것입니다. 연산에 선언에 특수 키워드(Special에 일치하는 키워드 또는 stringifier 키워드)가 있으면 특수 연산을 선언합니다. 하나의 연산이 일반 연산과 특수 연산을 동시에 선언할 수도 있습니다. 자세한 내용은 § 2.5.6 특수 연산을 참조하세요. 참고로, 일반 연산은 인터페이스 멤버 외에도, 콜백 인터페이스 멤버 및 네임스페이스 멤버가 될 수 있습니다.

연산에 식별자가 없으면 반드시 특수 키워드를 사용하여 특수 연산으로 선언해야 합니다.

일반 연산 또는 정적 연산의 식별자는 동일한 인터페이스, 콜백 인터페이스, 네임스페이스에 정의된 상수나 속성의 식별자와 같아서는 안 됩니다. 정적 연산의 식별자는 "prototype"이면 안 됩니다.

참고: 연산의 식별자는 동일 인터페이스의 다른 연산과 같을 수 있습니다. 이는 연산 오버로딩을 명세하는 방식입니다.

참고: 정적 연산의 식별자는 동일 인터페이스에 정의된 일반 연산의 식별자와 같을 수 있습니다.

연산의 반환 타입은 연산 선언에서 식별자 앞에 등장하는 타입(Type에 일치)으로 정해집니다. 반환 타입이 ?가 붙은 식별자인 경우, 해당 식별자는 인터페이스, 딕셔너리, 열거형, 콜백 함수, 콜백 인터페이스, 타입 정의를 식별해야 합니다.

연산의 인자(ArgumentList에 일치)는 선언의 괄호 사이에 명시됩니다. 각 인자는 타입(Type에 일치) 뒤에 식별자(ArgumentName에 일치)로 지정합니다.

참고: 표현력을 위해, 연산 인자의 식별자는 ArgumentNameKeyword 심볼에 일치하는 키워드 중 하나로 지정할 수 있으며, 이 경우 이스케이프할 필요가 없습니다.

연산 인자의 Type이 ?가 붙은 식별자인 경우, 해당 식별자는 인터페이스, 열거형, 콜백 함수, 콜백 인터페이스, 타입 정의를 식별해야 합니다. ?가 없는 식별자 타입인 경우, 해당 식별자는 위의 정의들 중 하나 또는 딕셔너리를 식별해야 합니다.

인자 타입을 타입 정의 해석 후, 널 허용 타입(nullable type)이면, 그 내부 타입은 딕셔너리 타입일 수 없습니다.

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

각 인자의 식별자는 동일 연산 선언 내의 다른 인자 식별자와 같아서는 안 됩니다.

각 인자는 확장 속성 리스트(ExtendedAttributeList에 일치)가 앞에 올 수 있으며, 이는 해당 인자 값이 언어 바인딩에서 어떻게 처리되는지 제어합니다.

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

[Exposed=Window]
interface Dimensions {
  attribute unsigned long width;
  attribute unsigned long height;
};

[Exposed=Window]
interface Button {

  // 인자를 받지 않고 불리언을 반환하는 연산.
  boolean isMouseOver();

  // 오버로딩된 연산들.
  undefined setDimensions(Dimensions size);
  undefined setDimensions(unsigned long width, unsigned long height);
};

연산 또는 생성자 연산은 마지막 인자가 ... 토큰으로 선언된 경우 가변 인자로 간주됩니다. 가변 인자 연산은 마지막 인자 이후 임의 개수의 인자를 받아 호출할 수 있음을 의미합니다. 추가 암시적 형식 인자들은 연산 선언의 마지막 명시적 인자와 동일한 타입입니다. 마지막 인자는 연산 호출 시 생략할 수도 있습니다. ... 토큰은 반드시 연산 인자 리스트의 마지막 인자에만 사용할 수 있습니다.

interface interface_identifier {
  return_type identifier(type... identifier);
  return_type identifier(type identifier, type... identifier);
};

확장 속성 중 인자 리스트를 받는 ([LegacyFactoryFunction]) 및 콜백 함수도 ... 토큰이 인자 리스트에 사용되면 가변 인자로 간주합니다.

[Exposed=Window]
interface IntegerSet {
  readonly attribute unsigned long cardinality;

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

var s = getIntegerSet();  // IntegerSet 인스턴스 얻기

s.union();                // 'ints'에 해당하는 인자를 안 넘김
s.union(1, 4, 7);         // 'ints'에 해당하는 인자를 세 개 넘김

인자에 optional 키워드가 있으면 옵션 인자로 간주합니다. 가변 인자(variadic) 연산의 마지막 인자도 옵션 인자로 간주됩니다. 인자를 옵션으로 선언하면 연산 호출 시 해당 인자를 생략할 수 있습니다. 연산이 가변 인자일 때 마지막 인자는 명시적으로 옵션 인자로 선언할 수 없습니다.

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

옵션 인자는 기본값도 가질 수 있습니다. 인자 식별자 뒤에 U+003D(=)와 값(DefaultValue에 일치)이 오면, 그 값이 옵션 인자의 기본값이 됩니다. 가변 인자 연산의 마지막(암시적 옵션) 인자에는 기본값을 지정할 수 없습니다. 기본값은 해당 인자가 생략되어 호출될 때 적용됩니다.

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

boolean 타입의 옵션 인자에 true를 기본값으로 사용하는 것은 권장하지 않습니다. 저자는 기본 변환(즉 undefined → false)을 예상할 수 있으므로 혼동을 줄 수 있습니다. [API-DESIGN-PRINCIPLES]

인자 타입이 딕셔너리 타입 또는 유니온 타입 중 평탄화된 멤버 타입의 하나로 딕셔너리 타입을 갖는 타입이며, 해당 딕셔너리 타입 및 조상에 필수 멤버가 없고, 인자가 마지막이거나 뒤따르는 인자들이 모두 옵션 인자라면, 해당 인자는 옵션으로 선언되고 기본값을 지정해야 합니다.

불리언 리터럴 토큰(true, false), null 토큰, integer 토큰, decimal 토큰, Infinity, -Infinity, NaN 중 하나가 옵션 인자 기본값으로 사용되면, 상수에 대해와 동일하게 해석합니다.

undefined 토큰이 옵션 인자 기본값으로 사용된 경우, 값은 IDL undefined입니다.

옵션 인자의 타입이 열거형이면, 지정된 기본값은 반드시 해당 열거형 값 중 하나여야 합니다.

옵션 인자 기본값으로 두 토큰 값 []를 사용할 수 있으며, 이는 빈 시퀀스 값을 나타냅니다. 타입은 해당 옵션 인자의 타입과 동일해야 하며, 반드시 시퀀스 타입, 널 허용 타입 중 내부 타입이 시퀀스 타입인 것, 유니온 타입, 널 허용 유니온 타입은 시퀀스 타입을 평탄화된 멤버 타입 중 하나로 가져야 합니다.

옵션 인자 기본값으로 두 토큰 값 {}도 사용할 수 있으며, 이는 기본 초기화된(ES null 또는 속성이 없는 객체와 같이) 딕셔너리 값을 의미합니다. 타입은 해당 옵션 인자의 타입과 동일해야 하며, 반드시 딕셔너리 타입이거나 유니온 타입 중 딕셔너리 타입을 평탄화된 멤버 타입 중 하나로 가져야 합니다.

[Exposed=Window]
interface ColorCreator {
  object createColor(double v1, double v2, double v3, optional double alpha);
};

[Exposed=Window]
interface ColorCreator {
  object createColor(double v1, double v2, double v3);
  object createColor(double v1, double v2, double v3, double alpha);
};

dictionary LookupOptions {
  boolean caseSensitive = false;
};

[Exposed=Window]
interface AddressBook {
  boolean hasAddressForName(USVString name, optional LookupOptions options = {});
};

연산에 적용 가능한 확장 속성은 다음과 같습니다: [CrossOriginIsolated], [Default], [Exposed], [LegacyUnforgeable], [NewObject], [SecureContext].

연산 operation의 메서드 단계는 “operation(arg1, arg2, ...) 메서드 단계는 다음과 같다:”(목록) 또는 “operation(arg1, arg2, ...) 메서드 단계는 다음을 수행한다”(인라인 설명)와 같은 텍스트로 소개해야 합니다.

참고: 메서드 단계를 정의할 때는 this에 암묵적으로 접근할 수 있습니다.

DefaultValue ::
    ConstValue
    string
    [ ]
    { }
    null
    undefined

Operation ::
    RegularOperation
    SpecialOperation

RegularOperation ::
    Type OperationRest

SpecialOperation ::
    Special RegularOperation

Special ::
    getter
    setter
    deleter

OperationRest ::
    OptionalOperationName ( ArgumentList ) ;

OptionalOperationName ::
    OperationName
    ε

OperationName ::
    OperationNameKeyword
    identifier

OperationNameKeyword ::
    includes

ArgumentList ::
    Argument Arguments
    ε

Arguments ::
    , Argument Arguments
    ε

Argument ::
    ExtendedAttributeList ArgumentRest

ArgumentRest ::
    optional TypeWithExtendedAttributes ArgumentName Default
    Type Ellipsis ArgumentName

ArgumentName ::
    ArgumentNameKeyword
    identifier

Ellipsis ::
    ...
    ε

ArgumentNameKeyword ::
    attribute
    callback
    const
    constructor
    deleter
    dictionary
    enum
    getter
    includes
    inherit
    interface
    iterable
    maplike
    mixin
    namespace
    partial
    readonly
    required
    setlike
    setter
    static
    stringifier
    typedef
    unrestricted

2.5.3.1. toJSON

toJSON 일반 연산을 선언함으로써, 인터페이스는 해당 인터페이스를 구현하는 객체를 JSON 타입으로 변환하는 방법을 명세합니다.

toJSON 일반 연산은 이러한 용도를 위해 예약되어 있습니다. 반드시 인자를 받지 않아야 하며, JSON 타입을 반환해야 합니다.

JSON 타입은 다음과 같습니다:

• 숫자 타입,

• boolean,

• 문자열 타입,

• 널 허용 타입 (내부 타입이 JSON 타입인 경우),

• 주석 타입 (내부 타입이 JSON 타입인 경우),

• 유니온 타입 (멤버 타입이 모두 JSON 타입인 경우),

• 타입 정의 (새 이름이 부여되는 타입이 JSON 타입인 경우),

• 시퀀스 타입 (파라미터 타입이 JSON 타입인 경우),

• 불변 배열 타입 (파라미터 타입이 JSON 타입인 경우),

• 딕셔너리 타입 (딕셔너리와 그 상속 딕셔너리 에 선언된 모든멤버 타입이 JSON 타입인 경우),

• 레코드 (모든 값이 JSON 타입인 경우),

• object,

• 인터페이스 타입 (자신이나 상속받은 인터페이스에 toJSON 연산이 선언된 경우),

toJSON 일반 연산 이 객체에서 어떻게 노출되는지, 그리고 JSON 타입이 JSON 문자열로 변환되는 방식은 언어 바인딩에 따라 다릅니다.

참고: 자바스크립트 바인딩에서는, toJSON 메서드를 노출하여 JSON 타입을 자바스크립트 값으로 반환하고, JSON.stringify() 함수로 JSON 문자열로 변환할 수 있도록 합니다. 또한, 자바스크립트 바인딩에서 toJSON 연산에 [Default] 확장 속성을 사용할 수 있으며, 이 경우 기본 toJSON 단계가 대신 노출됩니다.

[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 인스턴스 얻기
var txn = getTransaction();

// 아래와 같은 객체로 평가됨:
// {
//   from: "Bob",
//   to: "Alice",
//   amount: 50,
//   description: "books"
// }
txn.toJSON();

// 아래와 같은 문자열로 평가됨:
// '{"from":"Bob","to":"Alice","amount":50,"description":"books"}'
JSON.stringify(txn);

2.5.4. 생성자 연산

인터페이스에 생성자 연산 멤버(Constructor에 일치)가 있으면, 해당 인터페이스를 구현하는 객체를 생성자를 통해 만들 수 있다는 뜻입니다.

하나의 인터페이스에는 여러 개의 생성자 연산이 있을 수 있습니다. 인터페이스의 각각의 생성자 연산에 대해, 지정된 인자를 넘겨 인스턴스를 생성할 방법이 제공됩니다.

생성자 연산이 인터페이스 interface의 멤버일 때 생성자 단계는 “The new interface(arg1, arg2, ...) 생성자 단계는 다음과 같다:”(목록) 또는 “The new interface(arg1, arg2, ...) 생성자 단계는 다음을 수행한다”(인라인 설명)와 같은 텍스트로 소개해야 합니다.

생성자 단계는 아무 것도 하지 않거나, this에 전달된 값을 초기화하거나, 예외를 던질 수 있습니다.

생성자가 this를 초기화하지 않는 경우, “The new Example(init) 생성자 단계는 아무 것도 하지 않는다.”라고 쓸 수 있습니다.

§ 3.7.1 인터페이스 객체에서 생성자 연산이 어떻게 구현되는지 자세히 설명합니다.

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

var x = new Circle();      // 0개 인자 생성자로 Circle 인터페이스 구현 객체 생성
                           // 플랫폼 객체 참조 반환

var y = new Circle(1.25);  // 1개 인자 생성자로 Circle 객체 생성

var z = new NodeList();    // 생성자 선언이 없으므로 TypeError 발생

Constructor ::
    constructor ( ArgumentList ) ;

ArgumentList ::
    Argument Arguments
    ε

Arguments ::
    , Argument Arguments
    ε

Argument ::
    ExtendedAttributeList ArgumentRest

ArgumentRest ::
    optional TypeWithExtendedAttributes ArgumentName Default
    Type Ellipsis ArgumentName

ArgumentName ::
    ArgumentNameKeyword
    identifier

Ellipsis ::
    ...
    ε

ArgumentNameKeyword ::
    attribute
    callback
    const
    constructor
    deleter
    dictionary
    enum
    getter
    includes
    inherit
    interface
    iterable
    maplike
    mixin
    namespace
    partial
    readonly
    required
    setlike
    setter
    static
    stringifier
    typedef
    unrestricted

2.5.5. 문자열 변환자

인터페이스에 문자열 변환자가 있으면, 해당 인터페이스를 구현하는 객체가 기본값이 아닌 문자열 변환(conversion)을 갖는다는 의미입니다. 문자열 변환자는 stringifier 키워드로 지정할 수 있으며, 단독으로 사용될 경우 문자열 변환 연산을 만듭니다.

interface interface_identifier {
  stringifier;
};

인터페이스와 함께 설명되는 프로즈(prose)에서는 해당 인터페이스의 문자열 변환 동작을 정의해야 합니다.

stringifier 키워드는 속성에도 사용할 수 있습니다. 이 경우, 객체를 문자열로 변환할 때 사용할 값은 해당 속성의 값입니다. stringifier 키워드는 반드시 DOMString 또는 USVString 타입의 속성에만 사용할 수 있습니다. 또한 정적 속성에는 사용할 수 없습니다.

interface interface_identifier {
  stringifier attribute DOMString identifier;
};

특정 인터페이스에는 문자열 변환자가 최대 하나만 존재해야 합니다.

Stringifier ::
    stringifier StringifierRest

StringifierRest ::
    OptionalReadOnly AttributeRest
    ;

[Exposed=Window]
interface Student {
  constructor();
  attribute unsigned long id;
  stringifier attribute DOMString name;
};

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

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

[Exposed=Window]
interface Student {
  constructor();
  attribute unsigned long id;
  attribute DOMString? familyName;
  attribute DOMString givenName;

  stringifier;
};

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

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

2.5.6. 특수 연산

특수 연산은 해당 인터페이스를 구현하는 객체에 특정 종류의 특별한 동작을 선언하는 것입니다. 특수 연산은 연산 선언에 특수 키워드를 사용해 선언합니다.

특수 연산에는 세 가지 종류가 있습니다. 아래 표는 각 특수 연산의 종류별로 사용되는 특수 키워드와 그 목적을 나타냅니다:

모든 언어 바인딩이 네 가지 종류의 특수 객체 동작을 모두 지원하는 것은 아닙니다. 특수 연산이 식별자 없이 선언된 경우, 해당 종류의 특수 연산을 지원하지 않는 언어 바인딩에서는 해당 기능이 제공되지 않습니다.

[Exposed=Window]
interface Dictionary {
  readonly attribute unsigned long propertyCount;

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

특수 연산을 식별자를 사용해 정의하는 것은, 해당 특수 연산을 식별자 없이 별도의 선언으로 분리하는 것과 동등합니다. 이 방식은 인터페이스 연산의 메서드 단계를 단순화하기 위해 허용됩니다.

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

특정 특수 키워드는 연산에서 두 번 이상 등장해서는 안 됩니다.

Getter와 setter에는 두 가지 종류가 있습니다: DOMString을 프로퍼티 이름으로 받는 이름 있는 프로퍼티 getter와 이름 있는 프로퍼티 setter가 있고, unsigned long을 프로퍼티 인덱스로 받는 인덱스 프로퍼티 getter 및 인덱스 프로퍼티 setter가 있습니다. deleter는 한 종류만 있습니다: 이름 있는 프로퍼티 deleter. 자세한 내용은 § 2.5.6.1 인덱스 프로퍼티와 § 2.5.6.2 이름 프로퍼티를 참조하세요.

특정 인터페이스에는 이름 있는 프로퍼티 deleter가 최대 하나, getter와 setter의 각 종류도 최대 하나만 존재해야 합니다.

인터페이스에 특정 종류의 setter가 있으면 반드시 같은 종류의 getter도 있어야 합니다. 이름 있는 프로퍼티 deleter가 있으면, 반드시 이름 있는 프로퍼티 getter도 있어야 합니다.

연산으로 선언된 특수 연산은 가변 인자(variadic)가 아니어야 하며, 옵션 인자를 가질 수 없습니다.

객체가 두 개 이상의 인터페이스를 구현하며, 동일한 특수 연산을 정의한다면, 실제 어떤 특수 연산이 호출되는지는 정의되지 않습니다.

2.5.6.1. 인덱스 프로퍼티

인덱스 프로퍼티 getter를 정의한 인터페이스는 인덱스 프로퍼티를 지원한다고 한다. 확장해서, 플랫폼 객체가 인덱스 프로퍼티를 지원한다고 하려면 해당 객체가 인덱스 프로퍼티를 지원하는 인터페이스를 구현하면 된다.

인터페이스가 인덱스 프로퍼티를 지원하면, 인터페이스 정의에는 객체가 언제든지 어떤 인덱스로 인덱싱될 수 있는지 기술이 포함되어야 한다. 이 인덱스들을 지원되는 프로퍼티 인덱스라고 한다.

인덱스 프로퍼티를 지원하는 인터페이스는 "length"라는 정수형 속성을 정의해야 한다.

인덱스 프로퍼티 getter는 반드시 unsigned long 하나의 인자를 받아야 한다. 인덱스 프로퍼티 setter는 반드시 두 개의 인자를 받아야 하며, 첫 번째 인자는 unsigned long이어야 한다.

interface interface_identifier {
  getter type identifier(unsigned long identifier);
  setter type identifier(unsigned long identifier, type identifier);

  getter type (unsigned long identifier);
  setter type (unsigned long identifier, type identifier);
};

인덱스 프로퍼티 getter와 setter 정의에는 다음 요구 사항이 적용된다:

• 인덱스 프로퍼티 getter가 연산에 식별자를 써서 지정된 경우, 객체를 지원되는 프로퍼티 인덱스로 인덱싱하면 해당 인덱스를 유일 인자로 넘겨 연산을 호출한 결과값이 반환된다. 만약 인덱스 프로퍼티 getter 선언에 식별자가 없다면, 인터페이스 정의에 주어진 인덱스에 대해 인덱스 프로퍼티 값 결정 방법을 기술해야 한다.

• 인덱스 프로퍼티 setter가 연산에 식별자를 써서 지정된 경우, 객체를 지원되는 프로퍼티 인덱스와 값으로 프로퍼티 할당/생성을 위해 인덱싱하면, 인덱스를 첫 번째 인자, 값을 두 번째 인자로 넘겨 연산을 호출한 것과 동일하게 동작한다. 만약 인덱스 프로퍼티 setter 선언에 식별자가 없다면, 인터페이스 정의에 기존 인덱스 프로퍼티 값 설정(기존 인덱스 프로퍼티 값 설정)과 새 인덱스 프로퍼티 값 설정(새 인덱스 프로퍼티 값 설정) 방법을 기술해야 한다.

[Exposed=Window]
interface A {
  getter DOMString toWord(unsigned long index);
};

var a = getA();

a.toWord(0);  // "zero" 반환
a[0];         // 역시 "zero" 반환

a.toWord(5);  // "five" 반환
a[5];         // "5"라는 프로퍼티가 없으므로 undefined 반환

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

// map은 OrderedMap 인터페이스를 구현하는 레거시 플랫폼 객체라고 가정
var map = getOrderedMap();
var x, y;

x = map[0];       // map.length > 0이면 아래와 동등:
                  // x = map.getByIndex(0)
                  // 즉, map에 "0"이라는 프로퍼티가 있으므로
                  // 그렇지 않으면 x는 undefined

map[1] = false;   // 아래와 동등:
                  // map.setByIndex(1, false)

y = map.apple;    // apple이라는 이름 프로퍼티가 있으면 아래와 동등:
                  // y = map.get('apple')
                  // 없으면 y는 undefined

map.berry = 123;  // 아래와 동등:
                  // map.set('berry', 123)

delete map.cake;  // cake라는 이름 프로퍼티가 있으면 해당 프로퍼티 삭제 후 아래 동등:
                  // map.remove("cake")

2.5.6.2. 이름 프로퍼티

이름 프로퍼티 getter를 정의한 인터페이스는 이름 프로퍼티를 지원한다고 한다. 확장해서, 플랫폼 객체가 이름 프로퍼티를 지원한다고 하려면 해당 객체가 이름 프로퍼티를 지원하는 인터페이스를 구현하면 된다.

인터페이스가 이름 프로퍼티를 지원하면, 인터페이스 정의에는 객체를 언제든지 어떤 이름으로 인덱싱할 수 있는지(순서가 있는 이름 집합) 기술이 포함되어야 한다. 이 이름들을 지원되는 프로퍼티 이름이라고 한다.

이름 프로퍼티 getter와 deleter는 반드시 DOMString 하나의 인자를 받아야 한다. 이름 프로퍼티 setter는 반드시 두 개의 인자를 받아야 하며, 첫 번째 인자는 DOMString이어야 한다.

interface interface_identifier {
  getter type identifier(DOMString identifier);
  setter type identifier(DOMString identifier, type identifier);
  deleter type identifier(DOMString identifier);

  getter type (DOMString identifier);
  setter type (DOMString identifier, type identifier);
  deleter type (DOMString identifier);
};

이름 프로퍼티 getter, setter, deleter 정의에는 다음 요구 사항이 적용된다:

• 이름 프로퍼티 getter가 연산에 식별자를 써서 지정된 경우, 객체를 지원되는 프로퍼티 이름으로 인덱싱하면 해당 이름을 유일 인자로 넘겨 연산을 호출한 결과값이 반환된다. 만약 이름 프로퍼티 getter 선언에 식별자가 없다면, 인터페이스 정의에 주어진 이름에 대해 이름 프로퍼티 값 결정 방법을 기술해야 한다.

• 이름 프로퍼티 setter가 연산에 식별자를 써서 지정된 경우, 객체를 지원되는 프로퍼티 이름과 값으로 프로퍼티 할당/생성을 위해 인덱싱하면, 이름을 첫 번째 인자, 값을 두 번째 인자로 넘겨 연산을 호출한 것과 동일하게 동작한다. 만약 이름 프로퍼티 setter 선언에 식별자가 없다면, 인터페이스 정의에 기존 이름 프로퍼티 값 설정(기존 이름 프로퍼티 값 설정)과 새 이름 프로퍼티 값 설정(새 이름 프로퍼티 값 설정) 방법을 기술해야 한다.

• 이름 프로퍼티 deleter가 연산에 식별자를 써서 지정된 경우, 객체를 지원되는 프로퍼티 이름으로 삭제 인덱싱하면, 이름을 유일 인자로 넘겨 연산을 호출한 것과 동일하게 동작한다. 만약 이름 프로퍼티 deleter 선언에 식별자가 없다면, 인터페이스 정의에 주어진 이름에 대해 기존 이름 프로퍼티 삭제 방법을 기술해야 한다.

참고: 인덱스 프로퍼티와 마찬가지로, 이름 프로퍼티 getter, setter 또는 deleter 가 연산에 식별자를 써서 지정된 경우, 객체를 지원되는 프로퍼티 이름이 아닌 이름으로 인덱싱할 때 해당 연산을 해당 이름으로 호출하는 것과 반드시 같은 동작을 하는 것은 아니며, 실제 동작은 언어 바인딩마다 다릅니다.

2.5.7. 정적 속성 및 연산

정적 속성 및 정적 연산 은 해당 인터페이스의 특정 인스턴스가 아니라 인터페이스 자체에 연결되는 속성/연산입니다. 정적 속성과 연산은 선언에 static 키워드를 사용해 지정합니다.

정적 연산을 호출하거나 정적 속성을 참조하는 것이 인터페이스 인스턴스에서 가능한지는 언어 바인딩마다 다릅니다.

StaticMember ::
    static StaticMemberRest

StaticMemberRest ::
    OptionalReadOnly AttributeRest
    RegularOperation

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

var circles = getCircles();           // Circle 객체 배열

typeof Circle.triangulate;            // "function" 반환
typeof Circle.triangulationCount;     // "number" 반환
Circle.prototype.triangulate;         // undefined 반환
Circle.prototype.triangulationCount;  // 역시 undefined 반환
circles[0].triangulate;               // 이 역시 undefined
circles[0].triangulationCount;        // 이것도 undefined

// 정적 연산 호출
var triangulationPoint = Circle.triangulate(circles[0], circles[1], circles[2]);

// 수행한 삼각분할 개수 확인
window.alert(Circle.triangulationCount);

2.5.8. 오버로딩

인터페이스에 정의된 일반 연산 또는 정적 연산이 동일한 종류(일반 또는 정적)의 다른 연산과 동일한 식별자를 가지면, 해당 연산은 오버로딩된 연산이라 한다. 오버로딩된 연산의 식별자가 인터페이스를 구현하는 객체에서 호출될 때, 전달된 인자의 개수와 타입에 따라 실제로 어떤 오버로딩된 연산이 호출되는지가 결정된다. 생성자 연산도 오버로딩될 수 있다. 오버로딩된 연산과 생성자가 받을 수 있는 인자에는 몇 가지 제한이 있으며, 이를 설명하기 위해 유효 오버로드 집합이라는 개념을 사용한다.

오버로딩된 연산 집합은 다음 중 하나를 만족해야 한다:

• 연산 중 반환 타입이 프라미스 타입인 것이 없어야 한다;

• 모든 연산의 반환 타입이 프라미스 타입이어야 한다.

연산은 인터페이스, 부분 인터페이스, 인터페이스 믹스인, 부분 인터페이스 믹스인 정의를 넘나들어 오버로딩될 수 없다.

[Exposed=Window]
interface A {
  undefined f();
};

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

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

유효 오버로드 집합은 특정 연산, 생성자(생성자 연산 또는 [LegacyFactoryFunction]), 또는 콜백 함수에 대해 허용되는 호출을 나타낸다. 유효 오버로드 집합 계산 알고리즘은 다음 네 가지 IDL 구조에 대해 동작하며, 각 구조마다 필요한 입력이 있다:

일반 연산의 경우

정적 연산의 경우

• 연산이 정의된 인터페이스

• 연산의 식별자

• 전달할 인자의 개수

생성자의 경우

• 생성자 연산이 정의된 인터페이스

• 전달할 인자의 개수

레거시 팩토리 함수의 경우

• [LegacyFactoryFunction] 확장 속성이 정의된 인터페이스

• 레거시 팩토리 함수의 식별자

• 전달할 인자의 개수

유효 오버로드 집합은 인터페이스에 지정된 오버로딩 연산과 생성자에 모호함이 있는지 판별하는 데 사용된다.

아이템들은 유효 오버로드 집합의 튜플로, (호출 객체, 타입 리스트, 옵셔널리티 리스트) 형태를 가진다. 아래에 각 아이템 설명:

• 호출 객체는 유효 오버로드 집합이 일반 연산, 정적 연산 또는 생성자 연산일 때 연산이고, 유효 오버로드 집합이 레거시 팩토리 함수일 때는 확장 속성이다.

• 타입 리스트는 IDL 타입들의 리스트이다.

• 옵셔널리티 리스트는 "required", "optional", "variadic" 중 하나의 옵셔널리티 값을 인덱스별로 가지는 리스트이다. 해당 인자가 옵션 인자인지, 가변 인자인지를 표시한다.

각 튜플은 해당 타입의 인자값 리스트로 연산, 생성자, 콜백 함수를 호출할 수 있음을 의미한다. 옵션 인자 및 가변 인자 연산/생성자 덕분에, 동일한 연산이나 생성자로 식별되는 유효 오버로드 집합 아이템이 여러 개 있을 수 있다.

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

«
  (f1, « DOMString »,                           « required »),
  (f2, « Node, DOMString »,                     « required, required »),
  (f2, « Node, DOMString, double »,             « required, required, variadic »),
  (f2, « Node, DOMString, double, double »,     « required, required, variadic, variadic »),
  (f3, « »,                                     « »),
  (f4, « Event, DOMString »,                    « required, required »),
  (f4, « Event, DOMString, DOMString »,         « required, required, optional »),
  (f4, « Event, DOMString, DOMString, double », « required, required, optional, variadic »)
»

두 타입이 구별 가능하다는 것은 다음 알고리즘이 true를 반환하는 경우이다.

1. 한 타입이 널 허용 타입을 포함하고, 다른 타입이 널 허용 타입을 포함하거나, 유니온 타입이며 평탄화된 멤버 타입에 딕셔너리 타입이 포함되거나, 딕셔너리 타입이면, false를 반환한다.

   아래 쌍들은 구별 불가능하다:

   • double? 와 Dictionary1
   • (Interface1 or long)? 와 (Interface2 or DOMString)?
   • (Interface1 or long?) 와 (Interface2 or DOMString)?
   • (Interface1 or long?) 와 (Interface2 or DOMString?)
   • (Dictionary1 or long) 와 (Interface2 or DOMString)?
   • (Dictionary1 or long) 와 (Interface2 or DOMString?)

2. 두 타입 모두 유니온 타입 또는 널 허용 유니온 타입이면, 각 멤버 타입이 서로 구별 가능하면 true, 아니면 false를 반환한다.

3. 한 타입이 유니온 타입 또는 널 허용 유니온 타입이면, 유니온 타입의 각 멤버 타입이 비유니온 타입과 구별 가능하면 true, 아니면 false를 반환한다.

4. 각 타입의 내부 타입(주석 타입이면)과 내부 타입(그 결과가 널 허용 타입이면)을 취한 "가장 안쪽" 타입을 고려한다. 이 두 타입이 아래 표의 카테고리에 속하고, 해당 교차점에 ● 또는 지정된 조건(a, b, c, d)이 만족되면 true, 아니면 false를 반환한다.

   카테고리:

   interface-like

   • 인터페이스 타입

   • 버퍼 소스 타입

   dictionary-like

   • 딕셔너리 타입

   • 레코드 타입

   • 콜백 인터페이스 타입

   sequence-like

   • 시퀀스 타입

   • 불변 배열 타입

   	undefined	boolean	numeric types	bigint	string types	object	symbol	interface-like	callback function	dictionary-like	async sequence	sequence-like
   undefined		●	●	●	●	●	●	●	●		●	●
   boolean			●	●	●	●	●	●	●	●	●	●
   numeric types				(b)	●	●	●	●	●	●	●	●
   bigint					●	●	●	●	●	●	●	●
   string types						●	●	●	●	●	(d)	●
   object							●
   symbol								●	●	●	●	●
   interface-like								(a)	●	●	●	●
   callback function										(c)	●	●
   dictionary-like										●	●	●
   async sequence
   sequence-like

   1. 식별된 두 interface-like 타입이 서로 다르고, 어떤 플랫폼 객체도 두 타입을 모두 구현하지 않는다.

   2. 타입이 구별 가능하지만, 오버로딩에서 사용에 별도의 제한이 있다. 또한 이 타입의 유니온 사용에 관한 조언도 참고할 것.

   3. [LegacyTreatNonObjectAsNull] 확장 속성이 없는 콜백 함수는 dictionary-like 카테고리 타입과 구별 가능하다.

      예를 들어, ECMAScript 값을 콜백 함수와 딕셔너리-like 타입을 포함하는 유니온 타입으로 변환할 때, 값이 호출 가능이면 콜백 함수로, 아니면 딕셔너리-like 타입으로 변환된다.

   4. 타입은 구별 가능하지만, 문자열 타입 이 오버로드 집합이나 유니온에도 있으면 ECMAScript 값에서 변환할 때 문자열 객체 는 비동기 시퀀스 타입 으로 변환되지 않는다( %Symbol.iterator% 메서드가 있더라도).

   double 과 DOMString 은 숫자 타입과 문자열 타입 교차점에 ●이 있으므로 구별 가능하다.
   double 과 long은 모두 숫자 타입이므로, 숫자 타입과 숫자 타입의 교차점에 ●이나 문자가 없으므로 구별 불가능하다.
   다음과 같을 때:

   callback interface CBIface {
       undefined handle();
   };
   
   [Exposed=Window]
   interface Iface {
       attribute DOMString attr2;
   };
   
   dictionary Dict {
       DOMString field1;
   };
   

   CBIface는 Iface와는 구별 가능하다(딕셔너리-like와 인터페이스-like 교차점에 ●이 있음). 하지만 Dict와는 구별 불가능하다(딕셔너리-like 교차점에 ● 없음).

   프라미스 타입은 위 표에 없으므로, 어떤 다른 타입과도 구별 불가능하다.

주어진 효과적 오버로드 집합 에서 같은 타입 리스트 크기 를 갖는 항목 이 둘 이상이면, 그러한 항목들에 대해 어떤 인덱스 i 가 존재하여 모든 항목 쌍의 인덱스 i 에 있는 타입들이 구별 가능 해야 합니다. 이 조건을 만족하는 가장 작은 인덱스를, 해당 타입 리스트 크기를 갖는 효과적 오버로드 집합 의 항목들에 대한 구별 인자 인덱스 라고 합니다.

효과적 오버로드 집합 에는 같은 타입 리스트 크기 를 갖는 항목 이 둘 이상 있으면서, 그중 하나의 항목 은 구별 인자 인덱스 에 bigint 인자를 갖고 다른 하나는 구별 인자 인덱스 에 숫자 타입 인자를 갖는 경우가 있어서는 안 됩니다.

[Exposed=Window]
interface B {
  undefined f(DOMString x);
  undefined f(USVString x);
};

또한, 어떤 type list 크기의 구별 인자 인덱스보다 작은 인덱스 j에 대해, 모든 아이템의 type list에서 j번째 타입이 같아야 하며, 모든 아이템의 optionality list에서 j번째 optionality 값도 같아야 한다.

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

«
  (f1, « DOMString »,                       « required »),
  (f2, « long, double, Node, Node »,        « required, required, required, required »),
  (f3, « double, double, DOMString, Node », « required, required, required, required »)
»

2.5.8.1. 오버로딩 vs. 유니온 타입

이 섹션은 참고용입니다.

interface CanvasDrawPathExcerpt {
  undefined stroke();
  undefined stroke(Path2D path);
};

interface CanvasDrawPathExcerptOptional {
  undefined stroke(optional Path2D path);
};

2.5.9. 이터러블 선언

인터페이스는 이터러블로 선언될 수 있으며, 이는 인터페이스 본문에 이터러블 선언(Iterable에 일치)을 사용하여 지정한다.

interface interface_identifier {
  iterable<value_type>;
  iterable<key_type, value_type>;
};

인터페이스를 이터러블로 구현한 객체는 값을 시퀀스로 얻을 수 있도록 반복(iterate)할 수 있다.

참고: 자바스크립트 바인딩에서는 이터러블 인터페이스의 인터페이스 프로토타입 객체에 entries, forEach, keys, values, %Symbol.iterator% 프로퍼티가 있다.

타입 파라미터가 하나면 값 이터레이터이며, 해당 타입의 값을 제공한다. 타입 파라미터가 둘이면 쌍 이터레이터이며, 값 쌍을 제공한다.

값 쌍은 키 타입과 값 타입이 주어졌을 때 두 개의 구조체 아이템으로 이루어진다:

1. 아이템의 이름이 "key"이고, 값 쌍의 키라 하며, 값은 키 타입의 IDL 값이다;

2. 아이템의 이름이 "value"이고, 값 쌍의 값이라 하며, 값은 값 타입의 IDL 값이다.

값 이터레이터는 반드시 인덱스 프로퍼티를 지원하는 인터페이스에만 선언될 수 있다. 값 이터레이터의 value-type은 인덱스 프로퍼티 getter가 반환하는 타입과 같아야 한다. 값 이터레이터는 해당 객체의 인덱스 프로퍼티를 반복(iterate)하는 것으로 암묵적으로 정의된다.

쌍 이터레이터는 인덱스 프로퍼티를 지원하는 인터페이스에 선언될 수 없다.

페어 반복자가 있는 인터페이스에 대한 설명은 각 인터페이스 인스턴스마다 리스트를 값 쌍의 형태로 정의해야 하며, 이 리스트는 반복할 값 쌍입니다.

참고: 이는 array 이터레이터 객체 동작 방식이다. 인덱스 프로퍼티를 지원하는 인터페이스의 경우, entries, keys, values, %Symbol.iterator% 가 반환하는 이터레이터 객체는 실제 array 이터레이터 객체이다.

이터러블 선언이 있는 인터페이스에는 "entries", "forEach", "keys", "values"라는 이름의 속성, 상수, 일반 연산이 존재해서는 안 되며, 상속받은 인터페이스에도 이 이름의 속성, 상수, 일반 연산이 존재해서는 안 된다.

[Exposed=Window]
interface SessionManager {
  Session getSessionForUser(DOMString username);

  iterable<DOMString, Session>;
};

[Exposed=Window]
interface Session {
  readonly attribute DOMString username;
  // ...
};

// SessionManager 인스턴스를 얻는다.
// 예를 들어 "anna", "brian" 유저 세션이 있다고 가정.
var sm = getSessionManager();

typeof SessionManager.prototype.values;            // "function" 반환
var it = sm.values();                              // values()는 이터레이터 객체 반환
String(it);                                        // "[object SessionManager Iterator]" 반환
typeof it.next;                                    // "function" 반환

// 아래 루프는 "anna", "brian"을 로그한다.
for (;;) {
  let result = it.next();
  if (result.done) {
    break;
  }
  let session = result.value;
  console.log(session.username);
}

// 이것도 "anna", "brian"을 로그한다.
for (let username of sm.keys()) {
  console.log(username);
}

// 아래도 동일하다.
for (let [username, session] of sm) {
  console.log(username);
}

인터페이스에는 하나의 이터러블 선언만 존재해야 한다. 상속받은 인터페이스에도 이터러블 선언이 있으면 안 된다. 이터러블 선언이 있는 인터페이스와 그 상속 인터페이스에는 maplike 선언, setlike 선언, 비동기 이터러블 선언이 있어서는 안 된다.

이터러블 선언에 적용 가능한 확장 속성: [CrossOriginIsolated], [Exposed], [SecureContext].

Iterable ::
    iterable < TypeWithExtendedAttributes OptionalType > ;

OptionalType ::
    , TypeWithExtendedAttributes
    ε

2.5.10. 비동기 이터러블 선언

인터페이스는 비동기 반복 선언 (AsyncIterable과 일치) 을 인터페이스의 본문에 사용함으로써 비동기적으로 반복 가능하도록 선언할 수 있습니다.

interface interface_identifier {
  async_iterable<value_type>;
  async_iterable<value_type>(/* arguments... */);
  async_iterable<key_type, value_type>;
  async_iterable<key_type, value_type>(/* arguments... */);
};

비동기 이터러블로 선언된 인터페이스를 구현하는 객체는 값을 비동기로 반복(iterate)해서 얻을 수 있다.

타입 파라미터가 하나면 값 비동기 이터러블 선언이며, 해당 타입의 값을 비동기로 제공한다. 두 개면 쌍 비동기 이터러블 선언이며, 값 쌍을 비동기로 제공한다.

인자가 있다면, 비동기 이터러블 선언의 인자(ArgumentList에 일치)는 모두 옵션 인자여야 한다.

비동기 이터러블 선언이 있는 인터페이스의 프로즈에는 다음 반복 결과 얻기 알고리즘을 정의해야 한다. 이 알고리즘은 반복 중인 인터페이스 인스턴스와 비동기 이터레이터 객체를 받으며(상태 저장에 유용), Promise를 반환해야 한다. 이 Promise는 reject되거나, 반복 종료 신호를 나타내는 반복 종료 값을 resolve하거나, 아래 중 하나를 resolve한다:

값 비동기 이터러블 선언의 경우:

선언된 타입의 값

쌍 비동기 이터러블 선언의 경우:

선언된 두 타입의 값을 포함하는 튜플

또한 프로즈에서 비동기 이터레이터 반환 알고리즘을 정의할 수 있다. 이 알고리즘은 반복 중인 인터페이스 인스턴스, 비동기 이터레이터 객체, any 타입의 인자 하나를 받는다. 이는 이터레이터가 중단될 때 호출되며, Promise를 반환해야 하며, fulfill되면 값은 무시되고, reject되면 에러가 사용자에게 전달된다.

자바스크립트 바인딩에서는 이 알고리즘을 통해 async iterator의 return()이 호출될 때 동작을 커스터마이즈할 수 있다. 이는 break나 return으로 for-await-of 루프를 빠져나갈 때 가장 흔히 발생한다.

throw()에 대한 유사한 hook도 추가할 수 있다. 현재까지 필요가 없었지만, 그런 API가 필요하다면 이슈를 등록해 주세요.

또한 프로즈에서 비동기 이터레이터 초기화 단계도 정의할 수 있다. 이는 반복 중인 인터페이스 인스턴스, 새로 생성된 이터레이터 객체, 전달된 인자를 나타내는 IDL 값 리스트를 받는다.

비동기 이터러블 선언이 있는 인터페이스에는 "entries", "keys", "values"라는 이름의 속성, 상수, 일반 연산이 존재해서는 안 되며, 상속받은 인터페이스에도 이 이름의 속성, 상수, 일반 연산이 존재해서는 안 된다.

[Exposed=Window]
interface SessionManager {
  Session getSessionForUser(DOMString username);

  async_iterable<DOMString, Session>;
};

[Exposed=Window]
interface Session {
  readonly attribute DOMString username;
  // ...
};

// SessionManager 인스턴스를 얻는다.
// 예를 들어 "anna", "brian" 유저 세션이 있다고 가정.
var sm = getSessionManager();

typeof SessionManager.prototype.values;            // "function" 반환
var it = sm.values();                              // values()는 이터레이터 객체 반환
typeof it.next;                                    // "function" 반환

// 아래 루프는 "anna", "brian"을 로그한다.
for await (let username of sm.keys()) {
  console.log(username);
}

// 이것도 동일하다.
for await (let [username, session] of sm) {
  console.log(username);
}

인터페이스에는 하나의 비동기 이터러블 선언만 존재해야 한다. 비동기 이터러블 선언이 있는 인터페이스의 상속 인터페이스에도 비동기 이터러블 선언이 있으면 안 된다. 비동기 이터러블 선언이 있는 인터페이스와 그 상속 인터페이스에는 maplike 선언, setlike 선언, 이터러블 선언이 있어서는 안 된다.

비동기 이터러블 선언에 적용 가능한 확장 속성: [CrossOriginIsolated], [Exposed], [SecureContext].

이 확장 속성들은 현재는 적용되지 않으며, 추후 적용되면 예상대로 동작할 것이다.

AsyncIterable ::
    async_iterable < TypeWithExtendedAttributes OptionalType > OptionalArgumentList ;

OptionalArgumentList ::
    ( ArgumentList )
    ε

2.5.11. Maplike 선언

인터페이스는 maplike로 선언될 수 있으며, 이는 인터페이스 본문에 maplike 선언 (ReadWriteMaplike 또는 readonly MaplikeRest에 일치)을 사용해 지정한다.

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

maplike로 선언된 인터페이스를 구현하는 객체는, 처음에는 비어 있고, 키–값 쌍의 순서 있는 map을 나타내며, 이를 해당 객체의 map 엔트리라고 한다. 키와 값의 타입은 maplike 선언의 꺾쇠 괄호에 지정된다. 키는 반드시 고유해야 한다.

명세 작성자는 map 엔트리의 내용을 수정할 수 있으며, 이는 자바스크립트 코드에서 객체의 내용에 자동으로 반영된다.

maplike 인터페이스는 언어 바인딩에 적절한 map 엔트리 질의 API를 지원한다. readonly 키워드가 없으면, map 엔트리 수정 API도 지원한다.

참고: 자바스크립트 바인딩에서는 map 엔트리와 상호작용하는 API는 자바스크립트 Map 객체와 유사하다. readonly 키워드가 있을 때는 entries, forEach, get, has, keys, values, %Symbol.iterator% 메서드, 그리고 size getter를 포함한다. 읽기–쓰기 maplike일 경우, clear, delete, set 메서드도 포함한다.

maplike 인터페이스에는 "entries", "forEach", "get", "has", "keys", "size", "values" 이름의 속성, 상수, 일반 연산이 존재해서는 안 되며, 상속받은 인터페이스에도 이 이름의 속성, 상수, 일반 연산이 존재해서는 안 된다.

읽기–쓰기 maplike 인터페이스에는 "clear", "delete", "set" 이름의 속성 또는 상수가 존재해서는 안 되며, 상속받은 인터페이스에도 해당 이름의 속성이나 상수가 있어서는 안 된다.

참고: 읽기–쓰기 maplike 인터페이스는 일반 연산으로 "clear", "delete", "set" 이름을 가질 수 있으며, 이는 해당 메서드의 기본 구현을 덮어쓴다(§ 3.7.11 Maplike 선언 참조). 이런 연산이 정의되면, 각 메서드의 기본 구현에 명시된 입력/출력 기대치와 일치해야 한다.

인터페이스에는 하나의 maplike 선언만 존재해야 한다. maplike 인터페이스의 상속 인터페이스에도 maplike 선언이 있으면 안 된다. maplike 인터페이스와 상속 인터페이스에는 이터러블 선언, 비동기 이터러블 선언, setlike 선언, 인덱스 프로퍼티 getter가 있어서는 안 된다.

ReadOnlyMember ::
    readonly ReadOnlyMemberRest

ReadOnlyMemberRest ::
    AttributeRest
    MaplikeRest
    SetlikeRest

ReadWriteMaplike ::
    MaplikeRest

MaplikeRest ::
    maplike < TypeWithExtendedAttributes , TypeWithExtendedAttributes > ;

이 명세에서 정의된 확장 속성은 maplike 선언에 적용되지 않는다.

예시 추가 필요.

2.5.12. Setlike 선언

인터페이스는 setlike로 선언될 수 있으며, 이는 인터페이스 본문에 setlike 선언 (ReadWriteSetlike 또는 readonly SetlikeRest에 일치)을 사용해 지정한다.

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

setlike로 선언된 인터페이스를 구현하는 객체는, 처음에는 비어 있고, 값의 순서 있는 집합을 나타내며, 이를 해당 객체의 set 엔트리라고 한다. 값의 타입은 setlike 선언의 꺾쇠 괄호에 지정된다. 값은 반드시 고유해야 한다.

명세 작성자는 set 엔트리의 내용을 수정할 수 있으며, 이는 자바스크립트 코드에서 객체의 내용에 자동으로 반영된다.

setlike 인터페이스는 언어 바인딩에 적절한 set 엔트리 질의 API를 지원한다. readonly 키워드가 없으면, set 엔트리 수정 API도 지원한다.

참고: 자바스크립트 바인딩에서는 set 엔트리와 상호작용하는 API는 자바스크립트 Set 객체와 유사하다. readonly 키워드가 있을 때는 entries, forEach, has, keys, values, %Symbol.iterator% 메서드, 그리고 size getter를 포함한다. 읽기–쓰기 setlike일 경우, add, clear, delete 메서드도 포함한다.

setlike 인터페이스에는 "entries", "forEach", "has", "keys", "size", "values" 이름의 속성, 상수, 일반 연산이 존재해서는 안 되며, 상속받은 인터페이스에도 이 이름의 속성, 상수, 일반 연산이 존재해서는 안 된다.

읽기–쓰기 setlike 인터페이스에는 "add", "clear", "delete" 이름의 속성 또는 상수가 존재해서는 안 되며, 상속받은 인터페이스에도 해당 이름의 속성이나 상수가 있어서는 안 된다.

참고: 읽기–쓰기 setlike 인터페이스는 일반 연산으로 "add", "clear", "delete" 이름을 가질 수 있으며, 이는 해당 메서드의 기본 구현을 덮어쓴다(§ 3.7.12 Setlike 선언 참조). 이런 연산이 정의되면, 각 메서드의 기본 구현에 명시된 입력/출력 기대치와 일치해야 한다.

인터페이스에는 하나의 setlike 선언만 존재해야 한다. setlike 인터페이스의 상속 인터페이스에도 setlike 선언이 있으면 안 된다. setlike 인터페이스와 상속 인터페이스에는 이터러블 선언, 비동기 이터러블 선언, maplike 선언, 인덱스 프로퍼티 getter가 있어서는 안 된다.

ReadOnlyMember ::
    readonly ReadOnlyMemberRest

ReadOnlyMemberRest ::
    AttributeRest
    MaplikeRest
    SetlikeRest

ReadWriteSetlike ::
    SetlikeRest

SetlikeRest ::
    setlike < TypeWithExtendedAttributes > ;

이 명세에서 정의된 확장 속성은 setlike 선언에 적용되지 않는다.

예시 추가 필요.

2.6. 네임스페이스

네임스페이스란, 전역 싱글턴과 관련 동작을 선언하는 정의(Namespace에 일치)입니다.

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

네임스페이스는 네임스페이스 멤버들의 명세(NamespaceMembers에 일치)입니다. 네임스페이스 멤버란, 네임스페이스 선언의 중괄호 사이에 등장하는 일반 연산, 읽기 전용 일반 속성, 상수입니다. 이 연산과 속성들은 네임스페이스에 패키징되는 동작을 설명합니다.

인터페이스와 마찬가지로, 네임스페이스의 IDL도 부분 네임스페이스 정의(partial Namespace에 일치)를 사용해 여러 부분으로 나눌 수 있습니다. 부분 네임스페이스 정의의 식별자는 네임스페이스 정의의 식별자와 동일해야 합니다. 각 부분 네임스페이스 정의에 등장하는 모든 멤버는 네임스페이스 자체의 멤버로 간주됩니다.

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

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

참고: 부분 인터페이스 정의처럼, 부분 네임스페이스 정의는 명세 편집을 돕기 위한 것으로, 네임스페이스 정의를 문서의 여러 섹션 또는 여러 문서에 걸쳐 분리해 기술할 수 있게 해줍니다.

멤버가 등장하는 순서는 JavaScript 바인딩에서 프로퍼티 열거에 영향을 미칩니다.

인터페이스나 딕셔너리와 다르게, 네임스페이스는 타입을 생성하지 않습니다.

이 명세에서 정의된 확장 속성 중, [CrossOriginIsolated], [Exposed], [SecureContext]만 네임스페이스에 적용할 수 있습니다.

네임스페이스는 반드시 [Exposed] 확장 속성으로 어노테이트해야 합니다.

Partial ::
    partial PartialDefinition

PartialDefinition ::
    interface PartialInterfaceOrPartialMixin
    PartialDictionary
    Namespace

Namespace ::
    namespace identifier { NamespaceMembers } ;

NamespaceMembers ::
    ExtendedAttributeList NamespaceMember NamespaceMembers
    ε

NamespaceMember ::
    RegularOperation
    readonly AttributeRest
    Const

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

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

2.7. 딕셔너리

딕셔너리란, Dictionary에 일치하는 정의로, 고정된 순서의 순서 있는 map 데이터 타입을 정의하는 데 사용된다. 이 map의 엔트리들은 딕셔너리 멤버라 하며, 키는 문자열이고 값은 정의에서 지정한 특정 타입이다.

dictionary identifier {
  /* dictionary_members... */
};

딕셔너리 인스턴스는 언어별 표현(예: 해당하는 자바스크립트 객체)에 대한 참조를 유지하지 않는다. 예를 들어, 딕셔너리를 연산에서 반환하면, 현재 딕셔너리 값으로부터 새로운 자바스크립트 객체가 생성된다. 반대로 연산에서 딕셔너리를 인자로 받을 경우, 전달된 자바스크립트 값으로부터 딕셔너리로 한 번만 변환이 수행된다. 딕셔너리를 수정해도 해당 자바스크립트 객체에는 반영되지 않고, 그 반대도 마찬가지다.

딕셔너리는 속성이나 상수의 타입으로 사용될 수 없다.

딕셔너리는 다른 딕셔너리를 상속하도록 정의할 수 있다. 딕셔너리의 식별자 뒤에 콜론과 식별자가 오면, 해당 식별자는 상속받는 딕셔너리를 식별한다. 반드시 딕셔너리를 식별해야 한다.

딕셔너리의 상속 계층에 순환 구조가 있으면 안 된다. 즉, 딕셔너리 A가 자기 자신을 상속하거나, B를 상속하면서 B가 다시 A를 상속하는 방식은 금지된다.

dictionary Base {
  /* dictionary_members... */
};

dictionary Derived : Base {
  /* dictionary_members... */
};

딕셔너리 D의 상속된 딕셔너리들은 D가 직접 또는 간접적으로 상속받는 모든 딕셔너리 집합을 의미한다. D가 다른 딕셔너리를 상속하지 않으면 집합은 비어 있다. 그렇지 않으면, D가 상속한 딕셔너리 E와 E의 상속된 딕셔너리들이 모두 포함된다.

딕셔너리 멤버는 필수로 지정될 수 있다. 이 경우, 해당 멤버에 값을 제공하지 않으면 언어별 값에서 딕셔너리로 변환할 때 오류가 발생한다. 필수가 아닌 멤버는 옵션이다.

딕셔너리 멤버를 필수로 지정하는 것은, 언어별 딕셔너리 표현(예: 연산 인자로 자바스크립트 값을 전달할 때)에서만 효과가 있다. 이외의 경우, 즉 연산에서 딕셔너리를 반환 타입으로만 사용하는 경우 등에는 멤버를 옵션으로 남겨두는 것이 좋다.

타입 D의 딕셔너리 값에는, D와 D의 상속된 딕셔너리들에 정의된 모든 딕셔너리 멤버에 대한 엔트리가 있을 수 있다. 필수 또는 기본값이 지정된 멤버는 반드시 엔트리가 존재한다. 그 외 멤버의 엔트리는 존재할 수도 있고, 아닐 수도 있다.

자바스크립트 바인딩에서는, 딕셔너리 멤버에 해당하는 프로퍼티 값이 undefined면, 해당 프로퍼티가 생략된 것과 동일하게 처리된다. 즉, 필수라면 오류가 발생하고, 기본값이 있으면 그 값이 사용되며, 그 외에는 딕셔너리 값에 해당 엔트리가 존재하지 않는다.

연산 인자 기본값과 마찬가지로, boolean 타입 딕셔너리 멤버의 기본값으로 true를 사용하지 말 것을 강력히 권장한다. 이는 undefined의 기본 변환이 false가 되기를 기대하는 저자에게 혼란을 줄 수 있기 때문이다. [API-DESIGN-PRINCIPLES]

문자열 키를 가진 순서 있는 map은, 모든 엔트리가 딕셔너리 D의 딕셔너리 멤버에 대응하고, 타입이 맞고, 필수 또는 기본값 멤버에 대한 엔트리가 모두 존재하면 암묵적으로 D 타입의 딕셔너리 값으로 간주될 수 있다.

dictionary Descriptor {
  DOMString name;
  sequence<unsigned long> serviceIdentifiers;
};

각 딕셔너리 멤버(DictionaryMember에 일치)는 Type에 일치하는 타입 뒤에 식별자가 따라온다(타입 뒤에 identifier 토큰). 이 식별자가 키–값 쌍의 키 이름이다. Type이 식별자 뒤에 ?가 붙으면, 해당 식별자는 인터페이스, 열거형, 콜백 함수, 콜백 인터페이스, 타입 정의 중 하나를 식별해야 한다. ?가 없으면, 위 타입들 중 하나 또는 딕셔너리여야 한다.

딕셔너리 멤버의 타입이 typedef 해석 후 널 허용 타입이면, 내부 타입이 딕셔너리 타입이면 안 된다.

dictionary identifier {
  type identifier;
};

옵션 딕셔너리 멤버의 식별자 뒤에 U+003D(=)와 값(DefaultValue에 일치)이 오면, 해당 멤버의 기본값이 된다. 이 값은 코드나 명세에서 값을 지정하지 않을 경우 기본으로 사용된다.

dictionary identifier {
  type identifier = "value";
};

불리언 리터럴 토큰(true 또는 false), null 토큰, integer 토큰, decimal 토큰, 세 가지 특수 부동소수점 리터럴(Infinity, -Infinity, NaN), string 토큰, [] 또는 {} 토큰 시퀀스가 기본값으로 사용되면, 연산의 옵션 인자 기본값과 같은 방식으로 해석된다.

딕셔너리 멤버 타입이 열거형이면, 기본값은 반드시 열거형의 값 중 하나여야 한다.

딕셔너리 멤버 타입 앞에 required 키워드가 있으면, 해당 멤버는 필수 딕셔너리 멤버로 간주된다.

dictionary identifier {
  required type identifier;
};

딕셔너리 멤버의 타입에는 해당 딕셔너리가 포함되면 안 된다. 타입이 딕셔너리 D를 포함한다는 것은 다음 중 하나라도 참이면 성립한다:

• 타입이 D이다.

• 타입이 D를 상속하는 딕셔너리이다.

• 타입이 널 허용 타입이면서, 내부 타입이 D를 포함한다.

• 타입이 시퀀스 타입 또는 불변 배열이면서, 요소 타입이 D를 포함한다.

• 타입이 유니온 타입이며, 멤버 타입 중 하나가 D를 포함한다.

• 타입이 딕셔너리이고, 그 멤버 또는 상속 멤버의 타입 중 D를 포함하는 것이 있다.

• 타입이 record<K, V>이고, V가 D를 포함한다.

인터페이스와 마찬가지로, 딕셔너리의 IDL도 부분 딕셔너리 정의(partial Dictionary에 일치)를 사용해 여러 부분으로 나눌 수 있다. 부분 딕셔너리 정의의 식별자는 딕셔너리 정의의 식별자와 같아야 한다. 각 부분 딕셔너리 정의에 등장하는 모든 멤버는 딕셔너리 자체의 멤버로 간주된다.

dictionary SomeDictionary {
  /* dictionary_members... */
};

partial dictionary SomeDictionary {
  /* dictionary_members... */
};

참고: 부분 인터페이스 정의와 같이, 부분 딕셔너리 정의는 명세 편집을 돕기 위한 것으로, 딕셔너리 정의를 문서의 여러 섹션이나 여러 문서에 걸쳐 분리할 수 있게 해준다.

딕셔너리의 딕셔너리 멤버 순서는, 상속된 멤버가 비상속 멤버보다 앞에 오고, 한 딕셔너리 정의(부분 딕셔너리 포함) 내 멤버들은 식별자의 유니코드 코드포인트 기준으로 사전순 정렬된다.

사전 값의 항목은 항상 해당하는 사전 멤버의 순서대로 정렬되며, 이들이 설정된 순서와는 무관합니다.

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

[Exposed=Window]
interface Something {
  undefined f(A a);
};

var something = getSomething();  // 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);

따라서 항목이 동일한 키와 동일한 값을 갖는 두 사전 값은 해당 항목들이 설정된 순서와 관계없이 동일합니다. 해당 항목들이 설정된 순서와는 무관합니다.

사전 멤버의 식별자는 해당 사전 또는 해당 사전의 상속된 사전에 정의된 다른 사전 멤버의 식별자와 같아서는 안 됩니다.

사전에는 확장 속성이 적용되지 않습니다.

Partial ::
    partial PartialDefinition

PartialDefinition ::
    interface PartialInterfaceOrPartialMixin
    PartialDictionary
    Namespace

Dictionary ::
    dictionary identifier Inheritance { DictionaryMembers } ;

DictionaryMembers ::
    DictionaryMember DictionaryMembers
    ε

DictionaryMember ::
    ExtendedAttributeList DictionaryMemberRest

DictionaryMemberRest ::
    required TypeWithExtendedAttributes identifier ;
    Type identifier Default ;

PartialDictionary ::
    dictionary identifier { DictionaryMembers } ;

Default ::
    = DefaultValue
    ε

DefaultValue ::
    ConstValue
    string
    [ ]
    { }
    null
    undefined

Inheritance ::
    : identifier
    ε

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

// GraphicsContext 인스턴스 얻기
var ctx = getGraphicsContext();

// 사각형 그리기
ctx.drawRectangle(300, 200, { fillPattern: "red", position: new Point(10, 10) });

2.8. 예외

예외란 오류를 나타내는 객체 타입으로, 구현체에서 throw 하거나 값처럼 다룰 수 있다. Web IDL에는 명세에서 연산, 속성 등에 참조 또는 throw할 수 있는 여러 기본 예외가 정의되어 있다. 인터페이스에서 DOMException을 상속하여 커스텀 예외 타입도 정의할 수 있다.

단순 예외는 다음 타입 중 하나로 식별된다:

• EvalError

• RangeError

• ReferenceError

• TypeError

• URIError

이는 JavaScript의 모든 오류 객체에 해당하지만, 다음은 제외됩니다. AggregateError 및 SuppressedError는 다른 오류를 감싸는 용도로만 설계되었으며, SyntaxError는 JavaScript 파서에서 사용하도록 예약되어 있고, Error는 작성자가 사용하도록 예약되어 있습니다. 각 단순 예외의 의미는 해당 오류 객체의 의미와 JavaScript 명세에서 일치합니다.

두 번째 예외 종류는 DOMException으로, 발생한 오류에 대해 name으로 프로그래밍적으로 상세 정보를 제공한다. name 값은 아래 DOMException 이름 테이블에서 선정된다.

DOMException은 인터페이스 타입이므로 IDL에서 타입으로 사용할 수 있다. 예를 들어 연산의 DOMException 반환 타입으로 선언할 수 있지만, 예외는 반환이 아니라 throw하는 것이므로 이런 패턴은 바람직하지 않다.

세 번째 예외 종류는 DOMException을 상속한 인터페이스이다. 이들은 더 복잡하므로 § 2.8.2 DOMException 파생 인터페이스에서 따로 설명한다.

단순 예외는 타입 이름을 제공해 생성할 수 있다. DOMException은 name 뒤에 DOMException을 제공하여 생성한다. 예외는 throw할 수도 있는데, 이때도 생성할 때와 동일한 정보가 필요하다. 두 경우 모두 예외가 무엇을 의미하는지에 대한 추가 정보를 제공할 수 있으며, 예외 메시지 작성에 유용하다.

예외 생성 및 throw의 실제 동작은 언어 바인딩마다 다르다.

§ 3.14.3 예외 생성 및 throw에서 자바스크립트 바인딩에서 예외 생성 및 throw의 상세 동작을 볼 수 있다.

2.8.1. 기본 DOMException 오류 이름

아래 DOMException 이름 테이블은 기본 DOMException 인터페이스 인스턴스에 허용되는 모든 이름과, 각 이름의 의미 및 레거시 숫자 오류 코드 값을 설명합니다.

DOMException을 상속한 인터페이스(아래 § 2.8.2 DOMException 파생 인터페이스 참고)는 자체 이름을 가지며, 이 테이블에는 포함되지 않습니다.

DOMException을 생성하거나 throw할 때, 명세서는 반드시 이 이름 중 하나를 사용해야 합니다. 만약 명세자가 어떤 이름도 적합하지 않다고 생각되면, 이슈를 등록해 새로운 이름 추가를 논의해야 하며, 커뮤니티가 이런 작업을 조율할 수 있습니다. 새로운 케이스별 이름은, 웹 개발자가 단일 API에서 여러 오류 조건을 구분할 필요가 있을 때만 중요합니다.

DOMException 이름 중 "deprecated"로 표시된 것은 레거시를 위해 남아 있지만, 사용은 권장하지 않습니다.

참고: 여기 정의된 "SyntaxError" DOMException과 JavaScript의 SyntaxError를 혼동하지 마세요. "SyntaxError" DOMException은 웹 API에서 파싱 오류(예: 셀렉터 파싱 등)를 보고하는 데 사용되며, JavaScript SyntaxError는 JS 파서 용도로 예약되어 있습니다. 혼동을 피하기 위해, 항상 "SyntaxError" DOMException 표기를 사용하고, DOMException을 가리킬 때 단순히 SyntaxError라고만 쓰지 마세요. [DOM]

2.8.2. DOMException 파생 인터페이스

예외가 DOMException의 name으로 제공되는 정보 외에, 추가로 프로그래밍적으로 조회 가능한 정보를 담아야 할 때, 명세 작성자는 DOMException를 상속하는 인터페이스를 만들 수 있다. 이런 인터페이스는 개발자가 예측 가능한 형태로 다룰 수 있도록 다음 규칙을 따라야 한다:

• 인터페이스의 식별자는 반드시 Error로 끝나야 하며, DOMException 이름 테이블에 있는 이름이면 안 된다.

• 인터페이스에는, 인스턴스의 name을 인터페이스의 식별자로 설정하는 생성자 연산이 있어야 한다.

• 생성자 연산의 첫 번째 인자는 옵션 DOMString 타입의 message이며, 기본값은 빈 문자열이어야 하고, 인스턴스의 message를 message로 설정해야 한다.

• 생성자 연산의 두 번째 인자는 노출할 추가 정보를 담는 딕셔너리여야 한다.

• 생성자 딕셔너리의 멤버와 동일한 이름을 가진 읽기 전용 속성을 가지며, 생성자 연산에서 받은 값을 반환해야 한다.

• 직렬화 가능한 객체여야 하며, 직렬화 단계와 역직렬화 단계에서 추가 정보가 보존되어야 한다.

이 요구로 인해, 이런 인터페이스의 상속된 code 프로퍼티는 항상 0을 반환한다.

DOMException 파생 인터페이스를 생성하거나 throw하려면, 해당 인터페이스 식별자와 추가 정보가 필요하다.

2.8.3. 미리 정의된 DOMException 파생 인터페이스

이 표준에서는 현재 미리 정의된 DOMException 파생 인터페이스가 하나 있다:

[Exposed=*, Serializable]
interface QuotaExceededError : DOMException {
  constructor(optional DOMString message = "", optional QuotaExceededErrorOptions options = {});

  readonly attribute double? quota;
  readonly attribute double? requested;
};

dictionary QuotaExceededErrorOptions {
  double quota;
  double requested;
};

QuotaExceededError 예외는 할당량을 초과했을 때 throw할 수 있다. 두 개의 속성(quota, requested)을 가지고 있으며, 웹 개발자가 자신의 요청과 할당량 값을 비교할 수 있도록 추가 정보를 제공한다.

이전 버전의 표준에서는 "QuotaExceededError"가 기본 DOMException 오류 이름 중 하나였으나, 이런 정보를 제공할 수 있도록 풀 인터페이스로 승격되었다.

모든 QuotaExceededError 인스턴스는 requested와 quota라는 두 개의 숫자 또는 null 값을 가지며, 최초 값은 모두 null이다.

quota getter는 this의 quota를 반환한다.

requested getter는 this의 requested를 반환한다.

QuotaExceededError 인터페이스는 DOMException의 code getter를 상속받으며, 항상 22를 반환한다. 하지만 이 값에 의존하는 것은 권장되지 않는다(QuotaExceededError와 DOMException 모두에서). 대신 name getter를 사용하는 것이 더 낫다.

QuotaExceededError 객체는 직렬화 가능한 객체이다.

QuotaExceededError를 생성하거나 throw할 때, requested와 quota가 모두 null이 아니면서 requested가 quota보다 작으면 안 된다.

2.9. 열거형

열거형이란, Enum에 일치하는 정의로, 타입의 유효 값이 미리 정해진 문자열 집합인 것을 선언한다. 열거형은 DOMString 값이 속성에 할당되거나 연산에 인자로 전달될 때, 가능한 값을 제한하는 데 사용할 수 있다.

enum identifier { "enum", "values" /* , ... */ };

열거형 값은 쉼표로 구분된 string 리터럴 목록으로 지정한다. 열거형 값 목록에는 중복이 있으면 안 된다.

열거형 값은 모두 소문자로 하고, 여러 단어는 대시(-)로 구분하거나 아예 구분하지 않는 것이 강력히 권장된다. 특별한 이유가 없으면 다른 명명 규칙을 사용하지 말 것. 예를 들어, 객체 생성 의미의 값은 "createobject" 또는 "create-object"로 할 수 있다. 관련 API에서 일관성을 위해 단어 구분 방식도 신중히 결정할 것.

열거형 타입 속성에 유효하지 않은 문자열 값을 할당하거나, 연산 인자로 전달하는 경우의 동작은 언어 바인딩에 따라 다르다.

참고: 자바스크립트 바인딩에서는 속성에 잘못된 문자열 값을 할당하면 무시되지만, 다른 맥락(예: 연산 인자)에서는 예외가 throw된다.

이 명세에서 정의된 확장 속성은 열거형에 적용되지 않는다.

Enum ::
    enum identifier { EnumValueList } ;

EnumValueList ::
    string EnumValueListComma

EnumValueListComma ::
    , EnumValueListString
    ε

EnumValueListString ::
    string EnumValueListComma
    ε

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

[Exposed=Window]
interface Meal {
  attribute MealType type;
  attribute double size;     // g 단위

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

var meal = getMeal();                // Meal 인스턴스 얻기

meal.initialize("rice", 200);        // 정상적으로 호출됨

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

meal.type = "noodles";               // 정상 할당
meal.type = "dumplings";             // 무시됨
meal.type == "noodles";              // true 반환

2.10. 콜백 함수

"Custom DOM Elements" 명세에서는 플랫폼 객체 제공 함수에도 콜백 함수 타입을 사용하고 싶어합니다. 콜백 함수 대신 그냥 "함수"로 이름을 바꿔서 두 가지 용도 모두 명확히 할 수 있을까요?

콜백 함수란, callback CallbackRest에 일치하는 정의로, 함수 타입을 선언하는 데 사용됩니다.

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

참고: 유사 이름의 콜백 인터페이스도 참고하세요.

등호 왼쪽의 식별자가 콜백 함수 이름이며, 오른쪽의 반환 타입과 인자 목록(Type 및 ArgumentList)이 함수 시그니처를 정의합니다.

콜백 함수는 상수의 타입으로 사용될 수 없습니다.

콜백 함수에 적용 가능한 확장 속성: [LegacyTreatNonObjectAsNull].

CallbackOrInterfaceOrMixin ::
    callback CallbackRestOrInterface
    interface InterfaceOrMixin

CallbackRest ::
    identifier = Type ( ArgumentList ) ;

callback AsyncOperationCallback = undefined (DOMString status);

[Exposed=Window]
interface AsyncOperations {
  undefined performOperation(AsyncOperationCallback whenFinished);
};

var ops = getAsyncOperations();  // AsyncOperations 인스턴스 얻기

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

2.11. 타입 정의

타입 정의(typedef)란, Typedef에 일치하는 정의로, 타입에 새 이름을 선언하는 데 사용됩니다. 이 새 이름은 언어 바인딩에 노출되지 않으며, IDL 내에서 타입을 참조할 때만 약칭으로 쓰입니다.

typedef type identifier;

새 이름을 부여받는 타입은 typedef 키워드 뒤에 지정되며(TypeWithExtendedAttributes에 일치), 그 뒤의 identifier 토큰이 이름이 됩니다.

Type은 동일하거나 다른 typedef의 식별자가 되어서는 안 됩니다.

이 명세에서 정의된 확장 속성은 타입 정의에 적용되지 않습니다.

Typedef ::
    typedef TypeWithExtendedAttributes identifier ;

[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. 인터페이스를 구현하는 객체

하나의 IDL 프래그먼트 집합에 대한 구현에서는, 객체가 플랫폼 객체라고 할 수 있습니다.

플랫폼 객체란 인터페이스를 구현하는 객체입니다.

레거시 플랫폼 객체란 [Global] 확장 속성이 없는 인터페이스를 구현하고, 인덱스 프로퍼티 또는 이름 프로퍼티 또는 둘 다를 지원하는 플랫폼 객체입니다.

예를 들어 브라우저에서는, 브라우저가 구현한 DOM 객체들(Node, Document 등 인터페이스 구현)은 페이지 내 자바스크립트에서 웹 페이지 내용을 접근할 수 있게 해주는 플랫폼 객체입니다. 이런 객체들은 C++ 등으로 구현된 특수 객체일 수도 있고, 네이티브 자바스크립트 객체일 수도 있습니다. 어쨌든, 하나의 IDL 프래그먼트 집합에 대한 구현에서는, 모든 플랫폼 객체를 인식할 수 있어야 합니다. 이것은 내부적으로 객체가 플랫폼 객체임을 기록하거나, 객체가 특정 C++ 클래스에서 구현된 것을 감지하는 방식 등으로 이뤄질 수 있습니다. 어떤 방식으로 인식할지는 구현체마다 다릅니다.

시스템 내 다른 객체들은 플랫폼 객체로 취급되지 않습니다. 예를 들어, 브라우저에서 웹 페이지가 자바스크립트 라이브러리를 불러와 DOM Core를 구현한다고 해도, 이 라이브러리에서 Node 인터페이스를 구현해 만든 객체는 브라우저 구현체가 Node를 구현한 플랫폼 객체로 취급되지 않습니다.

반면 콜백 인터페이스는 어떤 자바스크립트 객체로도 구현할 수 있습니다. 이를 통해 웹 API가 저자(사용자) 정의 연산을 호출할 수 있습니다. 예를 들어, DOM Events 구현에서는 EventListener 인터페이스를 구현한 객체를 콜백 등록에 사용할 수 있습니다.

2.13. 타입

이 절에서는 Web IDL이 지원하는 타입, 각 타입에 대응하는 값의 집합 또는 Infra 타입, 그리고 해당 타입의 상수가 어떻게 표현되는지를 나열합니다.

다음 타입은 정수 타입으로 알려져 있습니다: byte, octet, short, unsigned short, long, unsigned long, long long 및 unsigned long long입니다.

다음 타입은 숫자 타입으로 알려져 있습니다: 정수 타입, float, unrestricted float, double 및 unrestricted double입니다.

기본 타입은 bigint, boolean 및 숫자 타입입니다.

문자열 타입은 DOMString, 모든 열거형 타입, ByteString 및 USVString입니다.

버퍼 타입은 ArrayBuffer 및 SharedArrayBuffer입니다.

형식화 배열 타입은 Int8Array, Int16Array, Int32Array, Uint8Array, Uint16Array, Uint32Array, Uint8ClampedArray, BigInt64Array, BigUint64Array, Float16Array, Float32Array, 및 Float64Array입니다.

버퍼 뷰 타입은 DataView 및 형식화 배열 타입입니다.

버퍼 소스 타입은 버퍼 타입 및 버퍼 뷰 타입입니다.

object 타입, 모든 인터페이스 타입 및 모든 콜백 인터페이스 타입은 객체 타입으로 알려져 있습니다.

연산을 호출하거나 속성에 값을 할당하기 위해 언어 바인딩별 타입에서 IDL 타입으로 변환할 때에는, 필요한 모든 변환이 연산 또는 속성 할당에 대해 지정된 기능이 수행되기 전에 완료됩니다. 변환을 수행할 수 없는 경우에는 연산이 실행되지 않거나 속성이 갱신되지 않습니다. 일부 언어 바인딩에서는 타입 변환으로 인해 예외가 발생할 수 있습니다. 이러한 경우 해당 예외는 연산을 호출하거나 속성에 값을 할당하려고 시도한 코드로 전파됩니다.

Type ::
    SingleType
    UnionType Null

TypeWithExtendedAttributes ::
    ExtendedAttributeList Type

SingleType ::
    DistinguishableType
    any
    PromiseType

UnionType ::
    ( UnionMemberType or UnionMemberType UnionMemberTypes )

UnionMemberType ::
    ExtendedAttributeList DistinguishableType
    UnionType Null

UnionMemberTypes ::
    or UnionMemberType UnionMemberTypes
    ε

DistinguishableType ::
    PrimitiveType Null
    StringType Null
    identifier Null
    sequence < TypeWithExtendedAttributes > Null
    async_sequence < TypeWithExtendedAttributes > Null
    object Null
    symbol Null
    BufferRelatedType Null
    FrozenArray < TypeWithExtendedAttributes > Null
    ObservableArray < TypeWithExtendedAttributes > Null
    RecordType Null
    undefined Null

ConstType ::
    PrimitiveType
    identifier

PrimitiveType ::
    UnsignedIntegerType
    UnrestrictedFloatType
    boolean
    byte
    octet
    bigint

UnrestrictedFloatType ::
    unrestricted FloatType
    FloatType

FloatType ::
    float
    double

UnsignedIntegerType ::
    unsigned IntegerType
    IntegerType

IntegerType ::
    short
    long OptionalLong

OptionalLong ::
    long
    ε

StringType ::
    ByteString
    DOMString
    USVString

PromiseType ::
    Promise < Type >

RecordType ::
    record < StringType , TypeWithExtendedAttributes >

Null ::
    ?
    ε

2.13.1. any

any 타입은 모든 다른 non-union 타입의 합집합입니다.

any 타입은 각 값이 특정 non-any 타입과 연결되어 있다는 점에서 discriminated union 타입과 유사합니다. 예를 들어, any 타입의 한 값은 unsigned long 150이고, 또 다른 값은 long 150입니다. 이 둘은 서로 다른 값입니다.

any 값의 특정 타입은 특정 타입이라고 합니다. (union 타입의 값도 특정 타입을 가집니다.)

2.13.2. undefined

undefined 타입은 고유한 값을 하나만 가집니다.

undefined 상수 값은 IDL에서 undefined 토큰으로 표현됩니다.

undefined 타입은 어떤 경우에도(연산, 콜백 함수, 생성자 연산 등) 인자 타입이나, 딕셔너리 멤버 타입(직접 또는 union 내)으로 사용해서는 안 됩니다. 대신 옵션 인자나, non-필수 딕셔너리 멤버를 사용하세요.

참고: 이 값은 이전에는 void로 표기되었으며, 사용 방식이 더 제한적이었습니다.

2.13.3. boolean

boolean 타입은 불리언과 대응됩니다.

boolean 상수 값은 IDL에서 true와 false 토큰으로 표현됩니다.