JavaScript, a.k.a. Web ECMAScript

Living Standard — 8 August 2014

This Version:
http://javascript.spec.whatwg.org/
Participate:
File a bug (but check the list of open bugs first)
IRC: #whatwg on Freenode
Version History:
https://github.com/whatwg/javascript
Editor:
Mathias Bynens

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 Syntax
    1. 7.1 Comment syntax
  8. 8 Top-level var statements
  9. 9 String
    1. 9.1 String.prototype.anchor(name)
    2. 9.2 String.prototype.big()
    3. 9.3 String.prototype.blink()
    4. 9.4 String.prototype.bold()
    5. 9.5 String.prototype.fixed()
    6. 9.6 String.prototype.fontcolor(color)
    7. 9.7 String.prototype.fontsize(size)
    8. 9.8 String.prototype.italics()
    9. 9.9 String.prototype.link(href)
    10. 9.10 String.prototype.small()
    11. 9.11 String.prototype.strike()
    12. 9.12 String.prototype.sub()
    13. 9.13 String.prototype.substr(start, length)
    14. 9.14 String.prototype.sup()
  10. 10 Date
    1. 10.1 Date.UTC(year, month, date, hours, minutes, seconds, ms)
  11. 11 RegExp
    1. 11.1 Octal escapes in regular expression literals
    2. 11.2 RegExp.$1-$9
    3. 11.3 RegExp.lastMatch / RegExp["$&"]
  12. 12 Function
    1. 12.1 Function.prototype.arguments
    2. 12.2 Function.prototype.caller
    3. 12.3 Function.prototype.toString()
  13. 13 Object
    1. 13.1 Object.prototype.__defineGetter__(propertyName, function)
    2. 13.2 Object.prototype.__defineSetter__(propertyName, function)
    3. 13.3 Object.prototype.__lookupGetter__(propertyName)
    4. 13.4 Object.prototype.__lookupSetter__(propertyName)
  14. References
  15. 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 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 MultiLineComments, must be treated as a SingleLineComment — equivalent to //.

var x = true;
--> x = false; // note: no syntax error
x; // true
var x = 1;
/*
multiline comment!
x = 2;
*/ --> x = 3;
x; // 1

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

9.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 “&amp;” (U+0026 U+0061 U+006D U+0070 U+003B) and “&quot;” (U+0026 U+0071 U+0075 U+006F U+0074 U+003B), respectively.

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

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

The length property of the blink method is 0.

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

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

9.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 “&amp;” (U+0026 U+0061 U+006D U+0070 U+003B) and “&quot;” (U+0026 U+0071 U+0075 U+006F U+0074 U+003B), respectively.

9.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 “&amp;” (U+0026 U+0061 U+006D U+0070 U+003B) and “&quot;” (U+0026 U+0071 U+0075 U+006F U+0074 U+003B), respectively.

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

  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 “&amp;” (U+0026 U+0061 U+006D U+0070 U+003B) and “&quot;” (U+0026 U+0071 U+0075 U+006F U+0074 U+003B), respectively.

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

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

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

9.13 String.prototype.substr(start, length)

This method is defined in Annex B.2.3 of the ECMAScript specification. Although this section is non-normative, user agents must implement it for Web compatibility.

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

10 Date

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

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

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

11 RegExp

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

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

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

12 Function

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

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

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

12.3 Function.prototype.toString()

TODO

13 Object

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

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

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

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

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

[DOM]
DOM4, Anne van Kesteren, Aryeh Gregor and Ms2ger. W3C.
[ECMASCRIPT]
ECMAScript Language Specification. ECMA.
[HTML]
HTML, Ian Hickson. WHATWG.
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels, Scott Bradner. IETF.
[UNICODE]
Unicode Standard. Unicode Consortium.

Acknowledgments

Thanks to Anne van Kesteren, Aryeh Gregor, David Håsäther, 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.