JavaScript, aka. Web ECMAScript

Table of Contents

1. 1 Goals
2. 2 Conformance
3. 3 Terminology
4. 4 Abstract operations
   1. 4.1 min(a, b)
   2. 4.2 max(a, b)
   3. 4.3 CheckObjectCoercible(value)
   4. 4.4 EscapeAttributeValue(value)
   5. 4.5 IsCallable(value)
   6. 4.6 ToInteger(value)
   7. 4.7 ToString(value)
   8. 4.8 ToHTML(tagName, content, attributeName, attributeValue)
5. 5 Annex B
6. 6 Unicode database version
7. 7 Syntax
   1. 7.1 Comment syntax
8. 8 Top-level var statements
9. 9 Array
   1. 9.1 Array.prototype.splice(start, deleteCount, item1, item2, …)
10. 10 String
    1. 10.1 String.prototype.anchor(name)
    2. 10.2 String.prototype.big()
    3. 10.3 String.prototype.blink()
    4. 10.4 String.prototype.bold()
    5. 10.5 String.prototype.fixed()
    6. 10.6 String.prototype.fontcolor(color)
    7. 10.7 String.prototype.fontsize(size)
    8. 10.8 String.prototype.italics()
    9. 10.9 String.prototype.link(href)
    10. 10.10 String.prototype.small()
    11. 10.11 String.prototype.strike()
    12. 10.12 String.prototype.sub()
    13. 10.13 String.prototype.substr(start, length)
    14. 10.14 String.prototype.sup()
11. 11 Date
    1. 11.1 Date.UTC(year, month, date, hours, minutes, seconds, ms)
12. 12 RegExp
    1. 12.1 Decimal escapes in character class ranges
    2. 12.2 Octal escapes in regular expression literals
    3. 12.3 RegExp.$1-$9
    4. 12.4 RegExp.lastMatch / RegExp["$&"]
    5. 12.5 RegExp.prototype.compile()
13. 13 Function
    1. 13.1 Function.prototype.arguments
    2. 13.2 Function.prototype.caller
    3. 13.3 Function.prototype.toString()
14. 14 Object
    1. 14.1 Object.prototype.__defineGetter__(propertyName, function)
    2. 14.2 Object.prototype.__defineSetter__(propertyName, function)
    3. 14.3 Object.prototype.__lookupGetter__(propertyName)
    4. 14.4 Object.prototype.__lookupSetter__(propertyName)
    5. 14.5 Object.prototype.__proto__
15. References
16. 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. [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]

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 min(a, b)

The abstract operation min(a, b) returns the smallest of its two arguments, as per the following algorithm:

1. If a is smaller than b, return a; else return b.

4.2 max(a, b)

The abstract operation max(a, b) returns the greatest of its two arguments, as per the following algorithm:

1. If a is greater than b, return a; else return b.

4.3 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.4 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.5 IsCallable(value)

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

4.6 ToInteger(value)

The abstract operation ToInteger(value) converts its argument to an integral numeric value (of type Number). It is defined in the ECMAScript specification.

4.7 ToString(value)

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

4.8 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. This includes:

• additional non-strict mode syntax and semantics for octal literals in numeric literals and octal escape sequences in string literals;
• the global escape(string) and unescape(string) methods;
• the String.prototype.substr(start, length) method;
• the Date.prototype.getYear(), Date.prototype.setYear(year), and Date.prototype.toGMTString() methods.

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 Syntax

7.1 Comment syntax

Tests are available: http://mathias.html5.org/tests/javascript/comment-syntax/.

<!-- must be treated as the start of a SingleLineComment — equivalent to //.

var x = true;
<!-- x = false; // note: no syntax error
x; // true

--> at the start of a line, optionally preceded by whitespace or single-line MultiLineComments, must be treated as a SingleLineComment — equivalent to //.

var x = true;
--> x = false; // note: no syntax error
x; // true

8 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.

9 Array

Tests are available: http://mathias.html5.org/tests/javascript/array/.

9.1 Array.prototype.splice(start, deleteCount, item1, item2, …)

This method is defined in the ECMAScript specification. However, for Web compatibility, JavaScript implementations must perform the following additional step before continuing with the algorithm:

1. If the start argument is provided and the deleteCount argument is omitted (i.e. when arguments.length == 1), set the value of deleteCount to Infinity.

According to the algorithm in the ECMAScript spec, omitting the deleteCount argument or setting its value to undefined would have the same effect as passing the value 0 (rather than Infinity), regardless of whether the start argument is provided or not.

var array = ['a', 'b', 'c', 'd'];
array.splice(2); // ['c', 'd']
array; // ['a', 'b']

array = ['a', 'b', 'c', 'd'];
array.splice(2, Infinity); // ['c', 'd']
array; // ['a', 'b']

array = ['a', 'b', 'c', 'd'];
array.splice(2, undefined); // []
array; // ['a', 'b', 'c', 'd']

10 String

Tests are available: http://mathias.html5.org/tests/javascript/string/.

Section 15.5.4 of the ECMAScript 5.1 specification defines the properties of the String.prototype object. For Web compatibility, user agents must extend this object with the following extra methods.

These methods are all generic, meaning the this argument need not be a String object.

10.1 String.prototype.anchor(name)

1. Call CheckObjectCoercible(this).
2. Let content be ToString(this).
3. Let attributeValue be ToString(name).
4. Return ToHTML("a", content, "name", attributeValue).

The length property of the anchor method is 1.

The use of this method is not recommended for Web authors; DOM APIs should be used instead. [DOM] [HTML] However, if this method is used nevertheless, the characters & and " in the value of the name argument should be escaped as “&” (U+0026 U+0061 U+006D U+0070 U+003B) and “"” (U+0026 U+0071 U+0075 U+006F U+0074 U+003B), respectively.

10.2 String.prototype.big()

1. Call CheckObjectCoercible(this).
2. Let content be ToString(this).
3. Return ToHTML("big", content).

The length property of the big method is 0.

10.3 String.prototype.blink()

1. Call CheckObjectCoercible(this).
2. Let content be ToString(this).
3. Return ToHTML("blink", content).

The length property of the blink method is 0.

10.4 String.prototype.bold()

1. Call CheckObjectCoercible(this).
2. Let content be ToString(this).
3. Return ToHTML("b", content).

The length property of the bold method is 0.

10.5 String.prototype.fixed()

1. Call CheckObjectCoercible(this).
2. Let content be ToString(this).
3. Return ToHTML("tt", content).

The length property of the fixed method is 0.

10.6 String.prototype.fontcolor(color)

1. Call CheckObjectCoercible(this).
2. Let content be ToString(this).
3. Let attributeValue be ToString(color).
4. Return ToHTML("font", content, "color", attributeValue).

The length property of the fontcolor method is 1.

The use of this method is not recommended for Web authors; DOM APIs should be used instead. [DOM] [HTML] However, if this method is used nevertheless, the characters & and " in the value of the color argument should be escaped as “&” (U+0026 U+0061 U+006D U+0070 U+003B) and “"” (U+0026 U+0071 U+0075 U+006F U+0074 U+003B), respectively.

10.7 String.prototype.fontsize(size)

1. Call CheckObjectCoercible(this).
2. Let content be ToString(this).
3. Let attributeValue be ToString(size).
4. Return ToHTML("font", content, "size", attributeValue).

The length property of the fontsize method is 1.

The use of this method is not recommended for Web authors; DOM APIs should be used instead. [DOM] [HTML] However, if this method is used nevertheless, the characters & and " in the value of the size argument should be escaped as “&” (U+0026 U+0061 U+006D U+0070 U+003B) and “"” (U+0026 U+0071 U+0075 U+006F U+0074 U+003B), respectively.

10.8 String.prototype.italics()

1. Call CheckObjectCoercible(this).
2. Let content be ToString(this).
3. Return ToHTML("i", content).

The length property of the italics method is 0.

10.9 String.prototype.link(href)

1. Call CheckObjectCoercible(this).
2. Let content be ToString(this).
3. Let attributeValue be ToString(href).
4. Return ToHTML("a", content, "href", attributeValue).

The length property of the link method is 1.

The use of this method is not recommended for Web authors; DOM APIs should be used instead. [DOM] [HTML] However, if this method is used nevertheless, the characters & and " in the value of the href argument should be escaped as “&” (U+0026 U+0061 U+006D U+0070 U+003B) and “"” (U+0026 U+0071 U+0075 U+006F U+0074 U+003B), respectively.

10.10 String.prototype.small()

1. Call CheckObjectCoercible(this).
2. Let content be ToString(this).
3. Return ToHTML("small", content).

The length property of the small method is 0.

10.11 String.prototype.strike()

1. Call CheckObjectCoercible(this).
2. Let content be ToString(this).
3. Return ToHTML("strike", content).

The length property of the strike method is 0.

10.12 String.prototype.sub()

1. Call CheckObjectCoercible(this).
2. Let content be ToString(this).
3. Return ToHTML("sub", content).

The length property of the sub method is 0.

10.13 String.prototype.substr(start, length)

10.14 String.prototype.sup()

1. Call CheckObjectCoercible(this).
2. Let content be ToString(this).
3. Return ToHTML("sup", content).

The length property of the sup method is 0.

11 Date

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

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

12 RegExp

12.1 Decimal escapes in character class ranges

Any DecimalEscapes in character class ranges must behave like \0 rather than throwing syntax errors.

For example, /[\1-Z]/ matches any character with a code point between U+0000 and U+005A.

12.2 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

12.3 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.

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

12.5 RegExp.prototype.compile()

The length property of the compile method is 1.

13 Function

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

13.1 Function.prototype.arguments

Each Function instance must have an arguments property that is equivalent to the standard arguments object within that function.

var a = function(x, y, z) {
	return [a.arguments, a.arguments === arguments];
};
a(1, 2, 3); // [{ '0': 1, '1': 2, '2': 3, 'length': 3 }], true]

The value of a function’s arguments property must be null if it’s accessed outside the function’s inner scope.

var a = function(x, y, z) {
	return a.arguments;
};
a(1, 2, 3); // { '0': 1, '1': 2, '2': 3, 'length': 3 }
a.arguments; // null

The standard arguments object is not created if the identifier “arguments” occurs as an Identifier in the function’s FormalParameterList or occurs as an Identifier of a FunctionDeclaration contained in the function code. However, even in these cases, the arguments property must be added to the function’s prototype.

var b = function(x, y, arguments) {
	return [b.arguments, b.arguments === arguments];
};
b(1, 2, 3); // [{ '0': 1, '1': 2, '2': 3, 'length': 3 }, false]

Strict mode functions must have a non-configurable accessor property with the name arguments that throws a TypeError exception on access.

var a = function(x, y, z) {
	'use strict';
	return a.arguments;
};
a(1, 2, 3); // throws a TypeError

13.2 Function.prototype.caller

Each Function instance must have a caller property that is a reference to the function that invoked the specified function.

var a = function() {
	return a.caller;
};
var b = function() {
	return a() === b;
};
b(); // true

The value of a function’s caller property must be null if it’s accessed outside the function’s inner scope, or if the function was invoked by top-level code.

var a = function() {
	return a.caller;
};
a.caller; // null
a(); // null

Strict mode functions must have a non-configurable accessor property with the name caller that throws a TypeError exception on access.

var fn = function(x, y, z) {
	'use strict';
	return fn.caller;
};
fn(); // throws a TypeError

13.3 Function.prototype.toString()

14 Object

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

14.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.

14.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.

14.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.

14.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.

14.5 Object.prototype.__proto__

All objects must have a mutable __proto__ property that is a reference to the prototype of the object. Note that ECMAScript defines that objects for which the [[Extensible]] internal property is false must not have their prototype mutated.

var string = 'foo';
string.__proto__ === String.prototype; // true

var object = {};
object.__proto__ === Object.prototype; // true
object.length; // undefined
object.__proto__ = Array.prototype;
object.length; // 0

In the case that setting an object’s __proto__ would cause a prototype chain to become cyclic, the setter must fail and throw an error.

var object = {};
object.__proto__ = object; // throws an Error

__proto__ will be fully specced in ECMAScript 6 (although the latest draft only defines it in Annex B). This section will be amended / removed when that happens.

References

Acknowledgments

Thanks to Anne van Kesteren, Aryeh Gregor, David Håsäther, James Graham, John-David Dalton, Ms2ger, Simon Pieters, 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.