JavaScript, a.k.a. Web ECMAScript

To the extent possible under law, the editor has waived all copyright and related or neighboring rights to this work. In addition, as of 4 August 2015, the editor has made this specification available under the Open Web Foundation Agreement Version 1.0, which is available at http://www.openwebfoundation.org/legal/the-owf-1-0-agreements/owfa-1-0.

Table of Contents

1. 1 Goals
2. 2 Conformance
3. 3 Terminology
4. 4 Abstract operations
   1. 4.1 CheckObjectCoercible(value)
   2. 4.2 EscapeAttributeValue(value)
   3. 4.3 IsCallable(value)
   4. 4.4 ToString(value)
   5. 4.5 ToHTML(tagName, content, attributeName, attributeValue)
5. 5 Annex B
6. 6 Unicode database version
7. 7 Top-level var statements
8. 8 Date
   1. 8.1 Date.UTC(year, month, date, hours, minutes, seconds, ms)
9. 9 RegExp
   1. 9.1 Octal escapes in regular expression literals
   2. 9.2 RegExp.$1-$9
   3. 9.3 RegExp.lastMatch / RegExp["$&"]
10. 10 Function
    1. 10.1 Function.prototype.toString()
11. 11 Object
    1. 11.1 Object.prototype.__defineGetter__(propertyName, function)
    2. 11.2 Object.prototype.__defineSetter__(propertyName, function)
    3. 11.3 Object.prototype.__lookupGetter__(propertyName)
    4. 11.4 Object.prototype.__lookupSetter__(propertyName)
12. References
13. Acknowledgments

1 Goals

This specification aims to document the differences between the ECMAScript specification and the compatibility and interoperability requirements for ECMAScript implementations in web browsers. The ultimate goal of this document is to upstream its contents to the ECMAScript standard. [ECMASCRIPT]

2 Conformance

Everything in this specification is normative except for examples, notes, and sections marked as non-normative.

A JavaScript implementation must be a conforming implementation of ECMAScript with the extensions described in this document. [ECMASCRIPT]

A user agent must also be a conforming implementation of HTML, if applicable. [HTML]

Script authors must not depend on the extensions defined in this specification.

3 Terminology

The key words “must” and “should” in this document are to be interpreted as described in RFC 2119. [RFC2119]

Special symbols in this document are identified using their Unicode code points and names. [UNICODE]

When this specification uses the term ECMAScript character, it means a 16-bit unsigned value used to represent a single 16-bit unit of text. [ECMASCRIPT]

4 Abstract operations

To clarify the semantics of certain constructs used throughout this document, it is useful to define a set of abstract operations. These abstract operations are not a part of the language, and must not be exposed to Web authors; they are only defined here to aid the specification of the semantics of the language.

4.1 CheckObjectCoercible(value)

The abstract operation CheckObjectCoercible(value) throws an error if its argument is a value that cannot be converted to an object. It is defined in the ECMAScript specification.

4.2 EscapeAttributeValue(value)

The abstract operation EscapeAttributeValue(value) produces a string suitable for use in an HTML attribute value wrapped in double quotes. [HTML] This is done according to the following algorithm:

1. Let escaped be value with each U+0022 QUOTATION MARK character replaced with the string “"” (U+0026 U+0071 U+0075 U+006F U+0074 U+003B).
2. Return escaped.

For security reasons, Web authors should not rely on any such escaping, as older, non-JavaScript-compliant implementations might not perform this operation correctly.

4.3 IsCallable(value)

The abstract operation IsCallable(value) determines if its argument is a callable function object. It is defined in the ECMAScript specification.

4.4 ToString(value)

The abstract operation ToString(value) converts its argument to a value of type String. It is defined in the ECMAScript specification.

4.5 ToHTML(tagName, content, attributeName, attributeValue)

The abstract operation ToHTML(tagName, content, attributeName, attributeValue) produces an HTML string, according to the following algorithm:

1. If attributeName is undefined, return the concatenation of the strings “<” (U+003C), tagName, “>” (U+003E), content, “</” (U+003C U+002F), tagName, and “>” (U+003E).
2. Otherwise, return the concatenation of the strings “<” (U+003C), tagName, “ ” (U+0020), attributeName, “="” (U+003D U+0022), EscapeAttributeValue(attributeValue), “">” (U+0022 U+003E), content, “</” (U+003C U+002F), tagName, and “>” (U+003E).

5 Annex B

JavaScript implementations must fully implement Annex B of the ECMAScript specification.

6 Unicode database version

For optimal interoperability, JavaScript implementations should use the latest available Unicode database to determine which ECMAScript characters are allowed in Identifiers and IdentifierNames, and which ECMAScript characters are whitespace characters. [UNICODE]

7 Top-level var statements

The erratum in https://bugs.ecmascript.org/show_bug.cgi?id=78#c0 must be followed so that var statements at the top level of scripts can shadow any properties from the global object’s prototype chain.

8 Date

Tests are available: https://mathias.html5.org/tests/javascript/date/.

8.1 Date.UTC(year, month, date, hours, minutes, seconds, ms)

When called with fewer than two arguments, Date.UTC must return NaN.

9 RegExp

9.1 Octal escapes in regular expression literals

The octal escape sequence syntax for string literals as described in Annex B of the ECMAScript spec must be supported, and must also apply to regular expression literals, even in strict mode code.

/\123/.test('S'); // true

9.2 RegExp.$1-$9

After a regexp is executed the RegExp constructor object has properties $1...$9 which are assigned the values of the first 9 match groups from the previous regexp.

9.3 RegExp.lastMatch / RegExp["$&"]

10 Function

Tests are available: https://mathias.html5.org/tests/javascript/function/.

10.1 Function.prototype.toString()

11 Object

Tests are available: https://mathias.html5.org/tests/javascript/object/.

11.1 Object.prototype.__defineGetter__(propertyName, function)

Every Object instance must have a __defineGetter__ method which binds a property of that object to a function that is called each time the property is accessed.

1. If IsCallable(function) is false, throw a TypeError and return; else, continue following these steps.
2. Let obj be this.
3. Let prop be ToString(propertyName).
4. Set the internal [[Enumerable]] property of obj’s prop property to true.
5. Whenever a property with the name of prop is accessed on the obj object, call function with the this binding set to obj, and return the result.
6. Whenever the __lookupGetter__ method of the obj object is called with an argument arg for which prop is equal to ToString(arg), return a reference to function.
7. Return undefined.

var object = {},
    counter = 0;
object.__defineGetter__('foo', function() {
	return ++counter;
});
[object.foo, object.foo, object.foo]; // [1, 2, 3]

var myDate = new Date;
myDate.__defineGetter__('year', function() {
	return this.getFullYear();
});
myDate; // Sun Jul 01 2012 13:33:37 GMT+0200 (CEST)
myDate.year; // 2012

The length property of the __defineGetter__ method is 2.

11.2 Object.prototype.__defineSetter__(propertyName, function)

Every Object instance must have a __defineSetter__ method which binds a property of that object to a function that is called each time the property is set.

1. If IsCallable(function) is false, throw a TypeError and return; else, continue following these steps.
2. Let obj be this.
3. Let prop be ToString(propertyName).
4. Set the internal [[Enumerable]] property of obj’s prop property to true.
5. Set the prop property on the obj object to undefined.
6. Whenever a property with the name of prop is set to a value val on the obj object, instead of setting the prop property to val, call function with the this binding set to obj, passing val as its first argument.
7. Whenever the __lookupSetter__ method of the obj object is called with an argument arg for which prop is equal to ToString(arg), return a reference to function.
8. Return undefined.

var object = {};
object.__defineSetter__('degrees', function(degrees) {
	this.radians = degrees * Math.PI / 180;
});
object.degrees = 180;
object.degrees; // undefined
object.radians; // 3.141592653589793

var myDate = new Date;
myDate.__defineSetter__('year', function(y) {
	this.setFullYear(y);
});
myDate; // Sun Jul 01 2012 13:33:37 GMT+0200 (CEST)
myDate.year = 1988;
myDate; // Fri Jul 01 1988 13:33:37 GMT+0200 (CEST)

The length property of the __defineSetter__ method is 2.

11.3 Object.prototype.__lookupGetter__(propertyName)

Every Object instance must have a __lookupGetter__ method that implements the following algorithm:

1. Let prop be ToString(propertyName).
2. If a getter for the prop property has been defined on the this object through the use of __defineGetter__ or the get syntax in the object initializer, return the getter function; else, return undefined.

var object = { get foo() { return 1; } };
object.__lookupGetter__('foo'); // function foo() { return 1; }

The length property of the __lookupGetter__ method is 1.

11.4 Object.prototype.__lookupSetter__(propertyName)

Every Object instance must have a __lookupSetter__ method that implements the following algorithm:

1. Let prop be ToString(propertyName).
2. If a setter for the prop property has been defined on the this object through the use of __defineSetter__ or the set syntax in the object initializer, return the setter function; else, return undefined.

var object = { set foo(value) { this.bar = value * 2; } };
object.__lookupSetter__('foo'); // function foo(value) { this.bar = value * 2; }

The length property of the __lookupSetter__ method is 1.

References

Acknowledgments

Thanks to Anne van Kesteren, Aryeh Gregor, David Håsäther, Domenic Denicola, James Graham, John-David Dalton, Masatoshi Kimura, Ms2ger, Simon Pieters, Simon Sapin, Steven Levithan, Mark ‘Tarquin’ Wilton-Jones, and Tom Schuster for their useful comments.

Special thanks to James Graham for collecting and documenting most of these requirements on the WHATWG Wiki, and Juriy ‘kangax’ Zaytsev (Юрий Зайцев) for his ECMAScript Extensions Compatibility Table.