Language Bindings for DOM Specifications

3.3.1. Constants

A constant is a definition that matches the Const non-terminal, and is used to bind a constant value to a name. Constants can appear on interfaces and also at the module or outermost scope.

The ConstExpr part of a constant definition gives the value of the constant, which can be one of the two boolean literal terminals ("TRUE" and "FALSE"), an integer terminal or a float terminal.

The value of the boolean literal terminals are as follows:

• The value of the "TRUE" terminal is a value of type boolean: true.
• The value of the "FALSE" terminal is a value of type boolean: false.

The value of an integer terminal is determined as follows:

1. Let S be the string value of the integer terminal.
2. Let n be the length of S.
3. Initialize mag to 0.
4. Initialize sign to 1.
5. Initialize base to 10.
6. Initialize i to 0.
7. If the first character of S is not U+002D HYPHEN-MINUS ("-"), then go to step 10.
8. Set sign to −1.
9. Set i to 1.
10. If the ith zero-based character of S is not U+0030 DIGIT ZERO ("0"), then go to step 16.
11. Set base to 8.
12. Set i to i + 1.
13. If the ith zero-based character of S is not U+0058 LATIN CAPITAL LETTER X ("X") or U+0078 LATIN SMALL LETTER X ("x"), then go to step 16.
14. Set base to 16.
15. Set i to i + 1.
16. Let digit be the value obtained by looking up the ith zero-based character of S in the table below:

    Character	Value of digit
    U+0030 DIGIT ZERO ("0")	0
    U+0031 DIGIT ONE ("1")	1
    U+0032 DIGIT TWO ("2")	2
    U+0033 DIGIT THREE ("3")	3
    U+0034 DIGIT FOUR ("4")	4
    U+0035 DIGIT FIVE ("5")	5
    U+0036 DIGIT SIX ("6")	6
    U+0037 DIGIT SEVEN ("7")	7
    U+0038 DIGIT EIGHT ("8")	8
    U+0039 DIGIT NINE ("9")	9
    U+0041 LATIN CAPITAL LETTER A ("A")	10
    U+0042 LATIN CAPITAL LETTER B ("B")	11
    U+0043 LATIN CAPITAL LETTER C ("C")	12
    U+0044 LATIN CAPITAL LETTER D ("D")	13
    U+0045 LATIN CAPITAL LETTER E ("E")	14
    U+0046 LATIN CAPITAL LETTER F ("F")	15
    U+0061 LATIN SMALL LETTER A ("a")	10
    U+0062 LATIN SMALL LETTER B ("b")	11
    U+0063 LATIN SMALL LETTER C ("c")	12
    U+0064 LATIN SMALL LETTER D ("d")	13
    U+0065 LATIN SMALL LETTER E ("e")	14
    U+0066 LATIN SMALL LETTER F ("f")	15

17. Set mag to mag * base + digit.
18. Set i to i + 1.
19. If i < n, go to step 16.
20. The value of the integer terminal is sign * mag.

The type of an integer terminal is the same as the type of the constant it is being used as the value of. The value of the integer terminal must not lie outside the valid range of values for its type, as given in section 3.7 below.

The type of a float terminal is float, and its value is determined as follows:

1. Let S be the string value of the float terminal.
2. Let n be the length of S.
3. Initialize mant to 0.
4. Initialize sign to 1.
5. Initialize exp1 to 0.
6. Initialize exp2 to 0.
7. Initialize expSign to 1.
8. Iniitalize afterDot to false.
9. Initialize i to 0.
10. If the first character of S is not U+002D HYPHEN-MINUS ("-"), then go to step 13.
11. Set sign to −1.
12. Set i to 1.
13. If the ith zero-based character of S is U+0045 LATIN CAPITAL LETTER E ("E") or U+0045 LATIN SMALL LETTER E ("e"), then go to step 23.
14. If the ith zero-based character of S is not U+002E FULL STOP ("."), then go to step 17.
15. Set afterDot to true.
16. Go to step 20.
17. Let digit be the Unicode codepoint of the ith zero-based character of S minus 48.
18. Set mant to mant * 10 + digit.
19. If afterDot is true, set exp1 to exp1 − 1.
20. Set i to i + 1.
21. If i < n, go to step 13.
22. Go to step 33.
23. Set i to i + 1.
24. If the ith zero-based character of S is not U+002D HYPHEN-MINUS ("-"), then go to step 27.
25. Set expSign to −1.
26. Set i to i + 1.
27. If the ith zero-based character of S is not U+002B PLUS SIGN ("+"), then set i to i + 1.
28. Let digit be the Unicode codepoint of the ith zero-based character of S minus 48.
29. Set exp2 to exp2 * 10 + digit.
30. Set i to i + 1.
31. If i < n, go to step 33.
32. Go to step 28.
33. The value of the float terminal is the IEEE 754 floating point number closest to sign * mant * 10^{expSign * exp2 + exp1}. [IEEE-754]

A constant must be assigned a value of the same type that the constant is declared to be.

No extended attributes are applicable to constants.

3.3.2. Attributes

An attribute is an interface member that matches the Attribute non-terminal, and is used to declare that objects implementing the interface will have an attribute with the given identifier that can be assigned and retrieved.

The type of the attribute is given by the DeclarationType non-terminal. If the DeclarationType is a scoped name, then it must resolve, with respect to the enclosing module of the interface on which the attribute is defined, to an interface, typedef or boxed valuetype that has been declared previously.

The attribute is read only if the "readonly" terminal is used in the definition. 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.

The GetRaises and SetRaises clauses are used to declare the possible exceptions that can be thrown when retrieving the value of and assigning a value to the attribute, respectively. Each scoped name in the GetRaises and SetRaises clauses must resolve, with respect to the enclosing module of the interface on which the attribute is defined, to an exception that has been declared previously.

The following extended attributes are applicable to attributes: [NoNull], [PutForwards].

3.3.3. Operations

An operation is an interface member that matches the Operation non-terminal, and is used to declare that objects implementing the interface will have a method with the given identifier.

The return type of the operation is given by the ReturnType non-terminal. A return type of "void" indicates that the operation returns no value. If the DeclarationType is a scoped name, then it must resolve, with respect to the enclosing module of the interface on which the operation is defined, to an interface, typedef or boxed valuetype that has been declared previously.

The ArgumentList non-terminal gives the list of arguments for the operation. The identifier of an argument is given by the identifier terminal in the Argument, and the type of the argument is given by the DeclarationType. If the DeclarationType is a scoped name, then it must resolve, with respect to the enclosing module of the interface on which the operation is defined, to an interface, typedef or boxed valuetype that has been declared previously.

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.

The Raises clause is used to declare the possible exceptions that can be thrown when invoking the operation. Each scoped name in the Raises clause must resolve, with respect to the enclosing module of the interface on which the operation is defined, to an exception that has been declared previously.

The following extended attributes are applicable to operations: [IndexGetter], [IndexSetter], [NameGetter], [NameSetter], [NoNull].

The following extended attributes are applicable to operation arguments: [NoNull], [Variadic].

3.7.1. any

The any type is the union of all other possible types.

3.7.2. boolean

The boolean type has two values: true and false.

boolean constant values in IDL are represented with the "TRUE" and "FALSE" terminals.

3.7.3. octet

The octet type is an unsigned integer type that has values in the range [0, 255].

octet constant values in IDL are represented with integer terminals.

3.7.4. short

The short type is a signed integer type that has values in the range [−32768, 32767].

short constant values in IDL are represented with integer terminals.

3.7.5. unsigned short

The unsigned short type is an unsigned integer type that has values in the range [0, 65535].

unsigned short constant values in IDL are represented with integer terminals.

3.7.6. long

The long type is a signed integer type that has values in the range [−2147483648, 2147483647].

long constant values in IDL are represented with integer terminals.

3.7.7. unsigned long

The unsigned long type is an unsigned integer type that has values in the range [0, 4294967295].

unsigned long constant values in IDL are represented with integer terminals.

3.7.8. long long

The long long type is a signed integer type that has values in the range [−9223372036854775808, 9223372036854775807].

long long constant values in IDL are represented with integer terminals.

3.7.9. unsigned long long

The unsigned long long type is an unsigned integer type that has values in the range [0, 18446744073709551615].

unsigned long long constant values in IDL are represented with integer terminals.

3.7.10. float

The float type is a floating point numeric type that corresponds to the set of possible single-precision 32 bit IEEE 754 floating point numbers. [IEEE-754]

float constant values in IDL are represented with float terminals.

3.7.11. sequence<T>

The sequence<T> type is a parameterized type whose values are (possibly zero-length) sequences of values of type T. Sequences can have an arbitrary length that is immutable. However, sequence element values are mutable.

There is no way to represent a sequence constant value in IDL.

3.7.12. Object

The Object type corresponds to the set of all possible object references, plus the special value null, which indicates no object reference.

There is no way to represent an Object constant value in IDL.

3.7.13. Object implementing an interface

A scoped name that resolves to an interface is used to refer to a type that corresponds to the set of all possible references to objects that implement that interface, plus the special value null, which indicates no object reference.

There is no way to represent an Object constant value in IDL.

3.7.14. Boxed valuetype

A scoped name that resolves to a boxed valuetype is used to refer to a type that corresponds to the set of values for the type being boxed, plus the special value null, which indicates no value.

There is no way to represent a boxed valuetype constant value in IDL.

3.8.1. [Constructor]

If the [Constructor] extended attribute appears on an interface, it indicates that there must be a way to construct objects that implement this interface. How such objects can be constructed is specific to the language binding.

The [Constructor] extended attribute must take no argument.

interface NodeList {
  Node item(in unsigned long index);
  readonly attribute unsigned long length;
};

[Constructor]
interface Circle {
  attribute float r;
  attribute float cx;
  attribute float cy;
  readonly attribute float circumference;
};

var x = new Circle();    // x is now a reference to a host object that implements the Circle interface.
var y = new NodeList();  // This would throw a TypeError.

interface Circle {
  attribute float r;
  attribute float cx;
  attribute float cy;
  readonly attribute float circumference;

  [Constructor] Circle createCircle(in float r, in float cx, in float cy);
};

3.8.2. [ExceptionConsts]

If the [ExceptionConsts] extended attribute appears on a module, it indicates that any constants declared on that module are intended to exist on the language construct that corresponds to the exception given by the extended attribute’s argument (for languages that support constants on exceptions). Exactly how these constants are exposed is language binding specific.

The [ExceptionConsts] must take a single argument, an identifier, which must be the identifier of an exception defined in that module, on which the constants declared at the module scope should live.

[ExceptionConsts=FileIOException]
module fileio {

  exception FileIOException {
    unsigned short code;
  };

  const unsigned short FILE_NOT_FOUND = 1;
  const unsigned short READ_ERROR = 2;
  const unsigned short WRITE_ERROR = 3;
};

typeof FileIOException;          // evaluates to "object"
FileIOException.FILE_NOT_FOUND;  // evaluates to 1

3.8.3. [IndexGetter]

If the [IndexGetter] extended attribute appears on an operation with a single unsigned long argument, it indicates that an object that implements the interface can be indexed with an unsigned long, resulting in the same effect as calling the operation with the given index (for languages that support such object indexing). If an object implements interfaces such that it has more than one operation annotated with [IndexGetter], then which operation is invoked when an object is indexed with an unsigned long value is undefined.

The [IndexGetter] extended attribute must take no argument.

valuetype DOMString sequence<unsigned short>;

interface OrderedMap {
  readonly attribute unsigned long size;

  [IndexGetter] any getByIndex(in unsigned long index);
  [IndexSetter] void setByIndex(in unsigned long index, in any value);

  [NameGetter] any get(in DOMString name);
  [NameSetter] void set(in DOMString name, in any value);
};

var map = getOrderedMap();  // Assume map is a host object implementing the OrderedMap interface.
var x, y;

x = map[0];                 // Same as: x = map.getByIndex(0)
map[1] = false;             // Same as: map.setByIndex(1, false)

y = map.apple;              // Same as: y = map.get('apple')
map.banana = 123;           // Same as: map.set('banana', 123)

3.8.4. [IndexSetter]

If the [IndexSetter] extended attribute appears on an operation with two arguments, the first of which is unsigned long, it indicates that an object that implements the interface can be indexed with an unsigned long for assignment, resulting in the same effect as calling the operation with the given index and value to assign (for languages that support such object indexing). If an object implements interfaces such that it has more than one operation annotated with [IndexSetter], then which operation is invoked when an object is indexed with an unsigned long value for assignment is undefined.

The [IndexSetter] extended attribute must take no argument.

3.8.5. [NoInterfaceObject]

If the [NoInterfaceObject] extended attribute appears on an interface, it indicates that an interface object will not exist for the interface in the ECMAScript binding. Similarly, if it appears on an exception it indicates that an exception interface object will not exist for the exception in the ECMAScript binding.

The [NoInterfaceObject] must take no argument.

interface Storage {
  void addEntry(in unsigned long key, in any value);
};

[NoInterfaceObject]
interface Query {
  any lookupEntry(in unsigned long key);
};

typeof Storage;                        // evaluates to "object"

// Add some tracing alert() call to Storage.addEntry.
var fn = Storage.prototype.addEntry;
Storage.prototype.addEntry = function(key, value) {
  alert('Calling addEntry()');
  return fn.call(this, key, value);
};

typeof Query;                          // evaluates to "undefined"
var fn = Query.prototype.lookupEntry;  // exception, Query isn’t defined

3.8.6. [NameGetter]

If the [NameGetter] extended attribute appears on an operation with a single sequence<unsigned short> valuetype argument, it indicates that an object that implements the interface can be indexed with a string, resulting in the same effect as calling the operation with the given index name (for languages that support such object indexing). If an object has both a [NameGetter]- and [IndexGetter]-annotated operation, then which operation is invoked when an object is indexed is language binding specific.

The [NameGetter] extended attribute must take no argument.

3.8.7. [NameSetter]

If the [NameSetter] extended attribute appears on an operation with two arguments, the first of which is a sequence<unsigned short> boxed valuetype, it indicates that an object that implements the interface can be indexed with a string for assignment, resulting in the same effect as calling the operation with the given index and value to assign (for languages that support such object indexing). If an object implements interfaces such that it has more than one operation annotated with [NameSetter], then which operation is invoked when an object is indexed with a boxed sequence<unsigned short> value for assignment is undefined.

The [NameSetter] extended attribute must take no argument.

3.8.8. [NoNull]

If the [NoNull] extended attribute appears on an attribute, an operation or an operation argument, whose type is a boxed valuetype, it indicates that a null value is not expected and will never be returned. How implementations treat the assignment of a null value to an attribute with the [NoNull] extended attribute, or passing a null value as a [NoNull] operation argument, is specific to the language binding.

The [NoNull] extended attribute must take no argument.

valuetype DOMString sequence<unsigned short>;

interface Dog {
  [NoNull] attribute DOMString name;
  attribute DOMString shortName;

  boolean isMemberOfBreed([NoNull] in DOMString breedName);
};

var d = getDog();         // Assume d is a host object implementing the Dog interface.

d.name = null;            // This assigns the string "null" to the .name property.
d.isMemberOfBreed(null);  // This passes the string "null" to the isMemberOfBreed function.

typedef sequence<unsigned short> DOMString;
valuetype DOMStringOrNull DOMString;

3.8.9. [PutForwards]

If the [PutForwards] extended attribute appears on a read only attribute declaration whose type is an object implementing an interface, it indicates that assigning to the attribute will have specific behavior. Namely, the assignment is “forwarded” to the attribute (specified by the extended attribute argument) on the object that is currently the value of the attribute being assigned to.

It is language binding specific what behavior occurs when assigning to such an attribute when its value is null.

The [PutForwards] extended attribute must take a single argument, an identifier, which must be the identifier of an attribute that exists on the interface that is the type of this attribute, which is the attribute that assignments will be forward to.

valuetype DOMString sequence<unsigned short>;

interface Name {
  attribute DOMString full;
  attribute DOMString family;
  attribute DOMString given;
};

interface Person {
  [PutForwards=full] readonly attribute Name name;
  attribute unsigned short age;
};

var p = getPerson();           // Assume p is a host object implementing the Person interface.

p.name = 'John Citizen';       // This statement...
p.name.full = 'John Citizen';  // ...has the same behavior as this one.

3.8.10. [Stringifies]

If the [Stringifies] extended attribute appears on an interface, it indicates that, for language bindings that support object stringification, an object that implements the interface will stringify in a non-default manner.

The [Stringifies] extended attribute may take a single argument, an identifier, which identifies an attribute on the interface whose value will be used as the result of the stringification. If the argument is not supplied, the stringification behavior must be described in prose.

[Constructor, Stringifies=name]
interface Student {
  unsigned long id;
  DOMString name;
};

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

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

[Constructor, Stringifies]
interface Student {
  unsigned long id;
  DOMString familyName;
  [NoNull] DOMString givenName;
};

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

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

3.8.11. [Variadic]

If the [Variadic] extended attribute appears on the final argument of an operation, it indicates that the operation is variadic, and can be passed zero or more arguments after the regular arguments. Each of these extra arguments will have to be of the type specified by that final argument. How such arguments are passed is specific to the language binding.

The [Variadic] extended attribute must take no argument.

interface IntegerSet {
  readonly unsigned long cardinality;

  void union([Variadic] in long integers);
  void intersection([Variadic] in long integers);
};

var s = getIntegerSet();  // Assume s is a host object implementing the IntegerSet interface.

s.union();                // Passing no arguments corresponding to 'integers'.
s.union(1, 4, 7);         // Passing three arguments corresponding to 'integers'.

4.1.1. any

The IDL any type can correspond to any ECMAScript type.

Since there is no ECMAScript value that does correspond to an IDL value, no conversion is performed when passing an ECMAScript value to a host object expecting any, or when a host object returns a value of type any.

4.1.2. void

The only place that the void type may appear in IDL is as the return type of an operation. Functions on host objects that implement an operation whose IDL specifies a void return type must return the undefined value.

ECMAScript functions that implement an operation whose IDL specifies a void return type may return any value, which will be discarded.

4.1.3. boolean

IDL boolean values are represented by ECMAScript Boolean values.

Values passed to a host object expecting a boolean must first be converted to an ECMAScript Boolean value by the ToBoolean operator defined in section 9.2 of [ECMA-262].

boolean values returned from a host object must be ECMAScript Boolean values.

4.1.4. octet

IDL octet values are represented by integer ECMAScript Number values in the range [0, 255].

Values passed to a host object expecting an octet must first be converted to an ECMAScript Number value by the ToUint8 operator, which functions (analogously to the ToUint32 operator defined in section 9.6 of [ECMA-262]) as follows:

1. Call ToNumber on the input argument.
2. If Result(1) is NaN, +0, −0, +∞, or −∞, return +0.
3. Compute sign(Result(1)) * floor(abs(Result(1))).
4. Compute Result(3) modulo 2⁸.
5. Return Result(4).

octet values returned from a host object must be integer ECMAScript Number values in the range [0, 255].

4.1.5. short

IDL short values are represented by integer ECMAScript Number values in the range [−32768, 32767].

Values passed to a host object expecting a short must first be converted to an ECMAScript Number value by the ToInt16 operator, which functions (analogously to the ToInt32 operator defined in section 9.5 of [ECMA-262]) as follows:

1. Call ToNumber on the input argument.
2. If Result(1) is NaN, +0, −0, +∞, or −∞, return +0.
3. Compute sign(Result(1)) * floor(abs(Result(1))).
4. Compute Result(3) modulo 2¹⁶.
5. If Result(4) is greater than or equal to 2¹⁵, return Result(4) − 2¹⁶. Otherwise, return Result(4).

short values returned from a host object must be integer ECMAScript Number values in the range [−32768, 32767].

4.1.6. unsigned short

IDL unsigned short values are represented by integer ECMAScript Number values in the range [0, 65535].

Values passed to a host object expecting an unsigned short must first be converted to an ECMAScript Number value by the ToUint16 operator defined in section 9.7 of [ECMA-262].

unsigned short values returned from a host object must be integer ECMAScript Number values in the range [0, 65535].

4.1.7. long

IDL long values are represented by integer ECMAScript Number values in the range [−2147483648, 2147483647].

Values passed to a host object expecting an long must first be converted to an ECMAScript Number value by the ToInt32 operator defined in section 9.5 of [ECMA-262].

long values returned from a host object must be integer ECMAScript Number values in the range [−2147483648, 2147483647].

4.1.8. unsigned long

IDL unsigned long values are represented by integer ECMAScript Number values in the range [0, 4294967295].

Values pas