Recent builds of the standalone SpiderMonkey shell include a reflection of the SpiderMonkey parser, made available as a JavaScript API. This makes it easier to write tools in JavaScript that manipulate JavaScript source programs, such as syntax highlighters, static analyses, translators, compilers, obfuscators, etc.

NOTE: Several projects are using this specification. Please do not make changes to it without consulting with the authors of Esprima, Escodegen, and Acorn.

It is also available since Firefox 7; it can be imported into the global object via:

Components.utils.import("resource://gre/modules/reflect.jsm")

or into a specified object via:

Components.utils.import("resource://gre/modules/reflect.jsm", obj)

Built-in objects

Whether in SpiderMonkey shell or Firefox (after importing), the global singleton object Reflect currently contains just the parse method.

Properties of the Reflect object

The Reflect object currently consists of a single method.

Reflect.parse(src[, options])

Coerces src to a string and parses the result as a JavaScript program. By default, the parsing returns a Program object (see below) representing the parsed abstract syntax tree (AST).

Additional options may be provided via the options object, which can include any of the following properties:

loc

Boolean

Default: true

When loc is true, the parser includes source location information in the returned AST nodes.

source

String

Default: null

A description of the input source; typically a filename, path, or URL. This string is not meaningful to the parsing process, but is produced as part of the source location information in the returned AST nodes.

line

Number

Default: 1

The initial line number to use for source location information.

builder

Builder

Default: null

A builder object, which can be used to produce AST nodes in custom data formats. The expected callback methods are described under Builder Objects.

If parsing fails due to a syntax error, an instance of SyntaxError is thrown. The syntax error object thrown by Reflect.parse() has the same message property as the syntax error that would be thrown by eval(src). The lineNumber and fileName properties of the syntax error object indicate the source location of the syntax error.

Node objects

By default, Reflect.parse() produces Node objects, which are plain JavaScript objects (i.e., their prototype derives from the standard Object prototype). All node types implement the following interface:

interface Node {
type: string;
loc: SourceLocation | null;
}

The type field is a string representing the AST variant type. Each subtype of Node is documented below with the specific string of its type field. You can use this field to determine which interface a node implements.

The loc field represents the source location information of the node. If the parser produced no information about the node's source location, the field is null; otherwise it is an object consisting of a start position (the position of the first character of the parsed source region) and an end position (the position of the first character after the parsed source region):

A literal property in an object expression can have either a string or number as its value. Ordinary property initializers have a kind value "init"; getters and setters have the kind values "get" and "set", respectively.

A member expression. If computed === true, the node corresponds to a computed e1[e2] expression and property is an Expression. If computed === false, the node corresponds to a static e1.x expression and property is an Identifier.

A generator expression. As with array comprehensions, the blocks array corresponds to the sequence of for and for each blocks, and the optional filter expression corresponds to the final if clause, if present.

Patterns

interface Pattern <: Node { }

JavaScript 1.7 introduced destructuring assignment and binding forms. All binding forms (such as function parameters, variable declarations, and catch block headers) accept array and object destructuring patterns in addition to plain identifiers. The left-hand sides of assignment expressions can be arbitrary expressions, but in the case where the expression is an object or array literal, it is interpreted by SpiderMonkey as a destructuring pattern.

Since the left-hand side of an assignment can in general be any expression, in an assignment context, a pattern can be any expression. In binding positions (such as function parameters, variable declarations, and catch headers), patterns can only be identifiers in the base case, not arbitrary expressions.

An E4X qualified identifier, i.e., a pseudo-identifier using the namespace separator ::. If the qualified identifier has a computed name (i.e., the id::[expr] form), then computed is true and the right property is an expression.

Builder objects

The optional builder parameter to Reflect.parse() makes it possible to construct user-specified data from the parser, rather than the default Node objects. Builder objects may contain any of the callback methods described in this section.

Each callback can produce any custom, user-defined datatype; these are referred to below as CustomExpression, CustomStatement, etc.

Note: Because this library uses null for optional nodes, it is recommended that user-defined datatypes not use null as a representation of an AST node.

If the loc option is enabled (see the Reflect.parse() options above), then each callback is provided with the source location information of the parsed node as an extra parameter.

All builder callbacks are optional. When a callback is missing, the default format is used, but the provided builder methods are still used recursively for sub-nodes.